test(core): add T10 PreviewAdapter contract stubs (spec for R7)

[vanceingalls]

Summary

• Adds packages/core/src/studio-api/helpers/previewAdapter.test.ts with 14 it.todo stubs defining the full createPreviewAdapter interface (spec for R7)
• Follows the T4 pattern (test(studio): add T4 op-contract stubs for editor dispatch boundary #1243): land the interface spec as stubs so the surface is agreed on before implementation begins
• Covers four describe groups: elementAtPoint (root exclusion, data-hf-id ancestor walk, opacity-at-playhead filter), applyDraft/revertDraft (draft marker lifecycle), commitPreview (patch derivation — move and resize), getElementTimings (data-start/data-end reader)
• createPreviewAdapter does not exist yet; R7 implements it and converts these stubs to real assertions

Test plan

• bun run --cwd packages/core test -- previewAdapter.test.ts — 14 todos, 0 failures

[vanceingalls]

• test(core,studio): add T3+T7 hfId targeting stubs (spec for R1) #1267
• test(core): add T6a GSAP parser golden baselines (Recast/Babel snapshot) #1263
• test(core): add T10 PreviewAdapter contract stubs (spec for R7) #1262 👈 (View in Graphite)
• refactor(core): extract maxEndTime+serialize to parsers/test-utils.ts (TU) #1261
• test(studio): add T5c review-fix gaps in manualEditsDomPatches characterization #1259
• test(studio): add T5b rotation+motion build-patches characterization #1258
• test(studio): add T5a pathOffset+boxSize build-patches characterization #1257
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miguel-heygen]

14 it.todo stubs for createPreviewAdapter (R7). The four describe groups map cleanly to distinct surface areas:

• elementAtPoint — root exclusion, ancestor walk, opacity filter
• applyDraft/revertDraft — marker lifecycle, --hf-studio-* CSS props
• commitPreview — null when no gesture, move+resize patches, marker cleanup
• getElementTimings — data-start/data-end reads, ignores elements without data-hf-id

The stubs are specific enough to constrain the implementation without over-specifying internals. The opacity-at-playhead stub (elementAtPoint: filters elements with opacity-at-playhead = 0) and the [data-hf-root] exclusion are the two cases most likely to be forgotten in R7 — good that they're explicitly named here.

No issues.

[james-russo-rames-d-jusso]

Round-1 review of T10 (PreviewAdapter contract stubs, spec for R7). +51/-0, single file, 14 it.todo stubs across 4 describe groups. Same shape as T4 from the prior batch — stubs land first to lock the surface; R7 converts to real assertions.

What's right

The describe groupings match the natural R7 surface. elementAtPoint, applyDraft/revertDraft, commitPreview, getElementTimings — these are the four orthogonal capabilities a preview-interaction adapter has to expose, and grouping by capability (not by source line) makes the spec readable as a contract rather than a test plan.

Upfront documentation of the geometry-stub gap. Lines 8-12:

Hit-testing (elementAtPoint) in both linkedom and jsdom returns null for all geometry calls — the real tests must inject a position-resolver stub or mock elementFromPoint. The contract tested is filtering logic (root exclusion, data-hf-id ancestor walk, opacity-at-playhead), not geometry.

This is exactly the kind of comment that saves R7's author from spending an hour discovering this on their own. linkedom/jsdom both implement elementFromPoint as a no-op stub, and the tests will need a manual hit-mask. Calling it out before R7 starts is high-leverage.

Stub semantics are concrete. Each it.todo description names a specific behavior rather than a generic capability — "returns the nearest ancestor with data-hf-id", "skips elements whose computed opacity is 0 at the given playhead time". The "given playhead time" parameterization tells R7's author the API needs to accept time as a parameter, which is a real design constraint that's easy to miss otherwise.

Concerns

[concern — applyDraft accepts both move (dx/dy) and resize (w/h) payloads should be two tests] Line 26:

it.todo("applyDraft accepts both move (dx/dy) and resize (w/h) payloads");

When R7 converts this to a real assertion, having both shapes in one test means a failing move assertion masks the resize assertion (and vice versa). The commitPreview group already splits this:

it.todo("derives a moveElement patch from draft markers on commit");
it.todo("derives a resize patch from draft markers on commit");

Either split this applyDraft test the same way, or keep it as one and add a comment that the test body asserts both branches independently. Otherwise R7's author has to make that call mid-implementation.

[concern — missing edge cases worth mentioning before R7 commits to the surface] The current 14 stubs cover the happy path well. Edges that R7 will run into:

• Concurrent gestures. If applyDraft is called twice in succession before a revertDraft/commitPreview, does the second call overwrite the first's marker, accumulate (dx, dy), or no-op? The current stubs don't pin this down — R7 implementor will pick a behavior and it'll be silently load-bearing for the Studio gesture layer.
• Gesture interruption mid-flight. Distinct from revertDraft (which is "user cancelled the gesture cleanly") — what if the user starts a drag, then triggers a different action (Esc, scroll-jank, browser tab switch)? Same revertDraft path, or a different cleanup?
• Playhead motion during a draft. elementAtPoint filters by opacity-at-playhead. If the user holds a drag while scrubbing, does the draft remain valid against the new playhead, or does it re-anchor / get reverted?
• Stage-root exclusion edge. returns null for the stage root (data-hf-root) — but what if there are nested data-hf-root elements (sub-compositions)? Outer root only, inner-roots count as ancestors, or both excluded?

None are blockers for the stub PR — they're R7-implementation questions. But worth at least one more it.todo per category so the spec captures "yes, R7 has to answer this." A describe("R7 implementation questions — to resolve before converting stubs", () => { it.todo(...) }) block would carry them visibly into the next PR.

Nits

• getElementTimings has two stubs: read times, ignore elements without data-hf-id. Worth one more for the "what if data-start/data-end is missing on an element with data-hf-id?" path — null, NaN, throw? Tiny gap.
• The describe-block reads top-to-bottom in roughly the order R7 will need to implement (elementAtPoint first because everything else depends on element lookup, then drafts, then commit, then timings). Good narrative order — keep it.

Plan-doc alignment

T10 = spec for R7 (PreviewAdapter — interaction-layer extraction in Studio → Core). The four describe groups are the four R7 must-haves. ✓ Scope matches.

Verdict

Reasonable spec stub. The applyDraft split and the four edge-case categories are worth adding before R7 starts so the author doesn't have to backtrack the spec mid-implementation. Leaving as a comment.

— Review by Rames D Jusso

The base branch was changed.