hyperframes/packages/studio/AGENTS.md

Working on Studio

Read this before your first change in packages/studio. It is the handful of things that are not visible from the source, and that cost real time to rediscover.

The shape of the thing

Studio renders the user's composition in an iframe, and draws its own chrome — selection box, handles, dashed outlines, toolbars — in Studio's own document, positioned over the iframe. Nothing Studio draws lives inside the composition, because a render would capture it and the composition's styling would inherit into it.

Two consequences you will meet immediately:

• Reaching a preview element from a driver or a test means going through the iframe: iframe.contentDocument.getElementById(...). Studio's own panels may be inside shadow roots, so a plain document.querySelector finds neither.
• Every overlay box is a measurement of an element, not the element. When chrome disagrees with the pixels underneath it, the bug is almost always in the measurement, in components/editor/domEditOverlayGeometry.ts.

Where a canvas edit goes

Paths are under src/; bare file names are in src/components/editor/. Each line names the owner; read it there.

1. Gesture. DomEditSelectionChrome.tsx starts it, domEditOverlayStartGesture.ts arms it, useDomEditOverlayGestures.ts (onPointerUp) hands it off. Nudge, crop and inline text enter through useDomEditNudge.ts, DomEditCropHandles.tsx and useInlineTextEditing.tsx. hooks/useDomEditSession.ts wires the handlers.
2. GSAP or plain. The predicates gsapWritesPosition, gsapWritesRotation and gsapWritesBox live in hooks/gsapRuntimeKeyframes.ts. The router is hooks/useGsapAwareEditing.ts. Move and a plain rotation keep the route chosen at press. A GSAP rotation checks ownership again at commit, and resize decides at commit through hooks/gsapResizeIntercept.ts.
3. Writers. Plain edits go through hooks/elementOffsetStager.ts, hooks/useDomGeometryCommits.ts and hooks/plainRotation.ts, then hooks/useDomEditPositionPatchCommit.ts. GSAP edits: hooks/gsapRuntimeBridge.ts (the drag and rotate intercepts), hooks/gsapDragCommit.ts, hooks/gsapDragPositionCommit.ts (keyframe at the playhead) and hooks/gsapWholePropertyOffsetCommit.ts. Styles, text, attributes and groups: hooks/domStyleCommit.ts, hooks/useDomEditTextCommits.ts, hooks/useDomEditAttributeCommits.ts, hooks/useGroupCommits.ts.
4. Save. There are three paths. A single DOM edit goes through hooks/useDomEditPersist.ts. It first offers the edit to the SDK path (utils/sdkCutover.ts, wired in useDomEditSession.ts), which writes the file itself. Otherwise it posts studio-server's file-mutations/patch-element. Atomic DOM batches go through hooks/useDomEditCommits.ts to patch-element-batches. Script edits go through hooks/useGsapScriptCommits.ts, to gsap-mutations or to the SDK path. The routes are in packages/studio-server/src/routes/files.ts. The own-write token is in utils/studioFileVersion.ts, and hooks/useExternalFileChangeCoordinator.ts drops the echo.
5. Reload. Each save path decides its own reload. After a patch-element save, useDomEditPersist.ts reloads unless skipRefresh is set. For script edits, useGsapScriptCommits.ts (applyPreviewSync) picks one of three: an instant patch, utils/gsapSoftReload.ts, or a reload. A reload bumps refreshKey, and refreshPlayer in player/hooks/useTimelinePlayer.ts either swaps the scene or runs player/hooks/useShadowPreviewReload.ts, which waits while a gesture or a save is in flight.
6. Undo. hooks/usePersistentEditHistory.ts records the edit. hooks/useEditHistoryActions.ts steps through history. utils/gsapUndoRestore.ts repaints the preview.

Driving Studio for verification

A pixel-precise click inside the preview is not something an automated driver can reliably land, and some gestures cannot be synthesised at all: the canvas overlay takes pointer capture and recognises a double press itself, so page.mouse click pairs do not open a text edit no matter how they are timed.

Use the dev-only hook instead. In a dev build window.__studioTest exposes:

await window.__studioTest.selectByDomId("headline"); // selects, reveals the inspector

That is the same selection a click produces. The general lesson: from a settled selection, keyboard paths are dependable where pointer paths are not. Prefer a key over a synthesised gesture whenever the feature offers one.

useStudioTestHooks also carries the timeline performance fixtures. The hook is gated on STUDIO_TEST_HOOKS_ENABLED (dev or development mode only), so window.__studioTest is absent in production builds — feature-detect it.

Tracing decisions

The interesting failures here are decisions, not crashes: a preview that reloads when it should not, a shift-click that selects the wrong element. Nothing throws, so a trace of the decision is the only way to avoid guessing.

Channels are off by default. Turn one on and reload:

localStorage.setItem("hf-drag-debug", "1"); // then grep the console for [hf-drag]

Live channels: reload, select, drag, resize, commit. Add one with makeStudioDebugLogger("<name>") in utils/studioDebug.ts.

Running the tests

Studio's tests are vitest, not bun test. Running bare bun test in this package collects the files with the wrong runner and reports failures that are not real:

bun run --cwd packages/studio test                       # all of them
bun run --cwd packages/studio test src/components/editor # one directory

happy-dom is not a browser. It does not reflect the individual transform properties (rotate, scale, translate) into computed style, and it has no DOMMatrix — the geometry tests carry their own stand-in. When a behaviour depends on real layout or real computed style, prove it in a browser and keep the unit test on the pure function underneath.

The edit accuracy bench

tests/e2e/edit-accuracy/ performs real gestures in the built CLI's Studio and checks the saved file, the reloaded preview, undo and a producer frame. It needs the built CLI (packages/cli/dist/cli.js, from bun run build) and chrome-headless-shell (npx hyperframes browser ensure):

bun run --cwd packages/studio test:edit-accuracy -- --grid pr --filter '^resize-' --jobs 1

• Case ids come from grid.mjs; --filter is a regex on them. --grid pr is the smaller slice, full is what CI runs.
• Each run writes its results, a table and a candidate baseline to tests/e2e/evidence/edit-accuracy/<run>/ (git-ignored; --out moves it); a failing case also gets its screens and saved files under cases/<id>/.
• A measurement waits until the box and the preview frames read the same on 3 animation frames in a row, with no Studio request in flight and every file write announced by the server. EDIT_ACCURACY_STILL_MS=500 swaps that for the older fixed window of 500 ms with no network signal, if the faster check ever proves flaky on CI.
• The run keeps one producer Chrome open for every render; each render still gets its own page and file server. Studio's server is started per case, because it serves one project folder and keeps that folder's undo history.
• CI runs the full grid in shards and ratchet.mjs gates the result against the base branch's baseline.json; its header states the rules. When cases newly pass, commit the baseline.json from the edit-accuracy-gate artifact.

Gates that will fail your PR

• 600 lines per file. CI checks only non-test files your PR changed. A file that grows past it has to be split in the same PR that grew it.
• bunx fallow audit --base origin/main --fail-on-issues — complexity per function, duplication, unused exports. Adding branches to an already-complex function trips it; extract rather than nest.
• oxlint and oxfmt, not eslint or prettier.
• Before and After captures. A PR that changes code under packages/studio or packages/player needs ## Before and ## After sections in its description, each with an image or video. The exemptions (a small change with no visible effect, Markdown, tests) are defined in scripts/check-pr-captures.mjs.

Traps worth knowing

• rotate is not transform. Studio's rotate handle writes the CSS rotate property, which is an individual transform property and does not appear in getComputedStyle(el).transform. Anything measuring an angle has to read both and compose them the way CSS does, individual properties first.
• A seek re-renders the whole timeline, not the tween you patched. Patching several elements one at a time and seeking after each repaints the ones still queued from their un-patched tweens. Batch, then render once.
• Studio's own writes must not reload the preview. Writes carry a token so the file-watcher event can be recognised as ours; a new write path that forgets it makes the preview flash on every edit.
• Preserving a selection set that does not contain the id empties it. Check preserveSet semantics before reusing it.