feat(studio): canvas context menu and z-order actions (unwired)

[ukimsanov]

What

CanvasContextMenu (right-click menu for canvas selections) and canvasContextMenuZOrder (tie-aware bring-forward/send-backward z-order patch computation) with its test suite. Shipped unwired.

Why

the z-order rules are the substance; mounting is one line in the later overlay swap.

How

new files, compiled against current main. Nothing mounts the menu yet, so .fallowrc.jsonc gains TEMP(studio-dnd) entries (entry registration + ignoreExports) — removed by the app-shell swap PR that wires everything.

Test plan

bunx vitest run canvasContextMenuZOrder.test.ts; tsc --noEmit; fallow audit clean.

---

Stack position 11/25 — studio NLE overhaul (CapCut-parity timeline + canvas). Graphite manages bases; merge from #2192 upward. Temporary TEMP(studio-dnd) fallow entries (unwired-component windows) are all removed by #2213 (app-shell swap), whose tree is byte-identical to the fully-verified integration branch.

[ukimsanov]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(studio): assets/blocks panel behaviors + preview helpers #2216
• feat(studio): timeline visual refresh #2215
• feat(studio): clip thumbnail modules #2214
• feat(studio): app shell swap — mount EditorShell, retire the legacy engine #2213
• feat(studio): timeline glue swap — Timeline/TimelineCanvas onto the NLE engine #2212
• feat(studio): canvas glue swap — overlay, gestures, selection to final form #2211
• feat(studio): sidebar asset card (unwired) #2210
• feat(studio): NLE shell assembly (unwired) #2209
• feat(studio): canvas chrome components (unwired) #2208
• feat(studio): timeline interaction hooks and lanes component (unwired) #2207
• feat(studio): clip drag engine — preview and commit (unwired) #2206
• feat(studio): glue API coexistence layer for the NLE swap #2205
• feat(studio): NLE shell components — context provider, panes, overlays (unwired) #2204
• feat(studio): arrow-key nudge step math (unwired) #2203
• feat(studio): canvas context menu and z-order actions (unwired) #2202 👈 (View in Graphite)
• test(studio): characterization suites for resize commit and razor history #2201
• feat(studio): asset click policy and canvas nudge gate #2200
• feat(studio): timeline lane-zone model #2199
• feat(studio): timeline z-stacking sync model #2198
• feat(studio): multi-clip drag preview math #2197
• feat(studio): timeline magnetic snapping #2196
• feat(studio): timeline collision and placement model #2195
• feat(studio-server): files route extensions #2194
• feat(studio): seek-restore contract for player reloads #2193
• feat(studio): timeline leaf helpers — audio inspector, zoom math, UI prefs #2192
• main

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

[miga-heygen]

Reviewed as part of the 25-PR NLE overhaul stack. Full stack review on #2205 (the keystone). No blockers on this PR. — Miga

[vanceingalls]

Verdict: LGTM (green) — pure math, unwired, correctly gated

A textbook z-order resolver: parse effective z, sort into render order (z asc, DOM asc), move the target one step or to an end, realize with the minimal patch (single between-value on the distinct-z fast path; renumber to 0..n-1 on the ties path). Every dispatch branch is a pure function of the inputs.

The pointed queries

• canvasContextMenuZOrder is a pure function. packages/studio/src/components/editor/canvasContextMenuZOrder.ts:228–:268 — resolveZOrderChange(target, action) performs no side effect: it reads the DOM (via getFamily/readEffectiveZIndex/getBoundingClientRect) and returns a patch list. Actual style mutation is the caller's responsibility. Every helper (:45, :52, :98, :156, :192) is a query, not a command. Test-friendly by design.
• Unwired at merge point. Verified against the tree at head SHA ad7cd1: DomEditOverlay.tsx at this ref does NOT import CanvasContextMenu, canvasContextMenuZOrder, or resolveZOrderChange (grep clean). The .fallowrc.jsonc at :53–:55 also honestly marks CanvasContextMenu.tsx as TEMP(studio-dnd): shipped unwired ahead of the NLE integration; the app-shell swap PR (studio-dnd/pr22) wires the consumers and removes this block. The unwired assertion holds. Batch-C reviewer will separately verify the assertion survives its post-batch state; my scope is the math itself.
• Render-order sort is deterministic. :156 — (a.zIndex - b.zIndex) || (a.domIndex - b.domIndex). Both keys stable functions of the input; no mutated-output tie-break (avoiding the same oscillation trap #2199 fixed). Test at :242–:258 pins the tie-break for a three-way z=0 case.
• DOM-order ties handled correctly. The comment at :13–:26 is precise about CSS paint reality (later-in-DOM paints on top at equal z) and the resolver at :78–:82 (paintsAbove) and :156 respects it. The tie-repro tests at :196–:240 cover all four actions × {earlier-in-DOM, later-in-DOM} — every ambiguous case has a deterministic outcome.
• Non-painting sibling hygiene. :85 excludes <audio>/<script>/<style>/<link>/<meta> from the family; test at :263–:307 pins the invariant using an audio sibling with a leaked z=2 that would otherwise pad the renumber. Nice defensive touch — the qa-clean audio artifact would otherwise skew results.
• Cross-realm HTMLElement check. :72–:76 uses node.ownerDocument?.defaultView to compare against the element's own realm's HTMLElement, with a nodeType === 1 fallback. Documented at :64–:71 as the fix for iframe-realm silent-empty-family bug. Good.
• z clamped ≥ 0. :174 (Math.max(0, above.zIndex - 1)) and the renumber path :215–:218 (i starts at 0) both keep the invariant. renumber emits patches only for elements whose z actually changes at :242–:258 confirms.

Nits (non-blocking)

• readEffectiveZIndex at :52 is exported but never consumed at this SHA — correctly exempted via .fallowrc.jsonc ignoreExports at :90–:99 with a TEMP marker. Would be removed by studio-dnd/pr22. Fine.

R1 by Via

[miguel-heygen]

Current required CI is not clean: preview-regression is failing at head 138ede6. Please rerun/fix and re-request review once green.

[miguel-heygen]

Re-reviewed current head and verified the addressed feedback and required behavior. Approval is for this exact head; Graphite mergeability may still be pending.

Superseded by current-head re-review; findings verified addressed.