feat(studio): off-screen element indicators + unclipped overlay

[miguel-heygen]

Summary

• Add useOffScreenIndicators hook: RAF-driven detection of GSAP elements positioned outside composition bounds
• Render dotted indicators at composition edges showing direction to off-screen elements
• Click indicator to select the element, drag indicator to move and select
• Split NLE layout: inner overflow-hidden clips iframe, outer container leaves overlay unclipped for handle interaction beyond composition bounds
• Add onSelectElementById prop to DomEditOverlay for programmatic selection
• Intentional flag flip: STUDIO_GSAP_DRAG_INTERCEPT_ENABLED set to true — this stack implements and tests the drag intercept system that was gated behind false in fix(studio): disable preview gsap-element dragging behaviour by default #1341

Review feedback addressed (from R2)

• fix(studio): property panel group-aware keyframe routing #1358 blocker (onMoveKeyframe percentage-space): all three conversions (find, remove, add) now use tween-relative percentages
• fix(studio): per-property-group intercept routing + drag/resize fixes #1356 blocker (URL-hash projectId): replaced window.location.hash regex with fetchAnimations callback threaded through GsapDragCommitCallbacks
• fix(studio): per-property-group intercept routing + drag/resize fixes #1356 activeKeyframePct: clear moved to after mutation succeeds (preserves target on throw)
• feat(studio): off-screen element indicators + unclipped overlay #1360 getElementById vs data-hf-id: indicators now skip elements without a real id attribute — no silent click failures
• delete-all-for-selector: new atomic server mutation replacing sequential per-animation deletes
• Context menus portaled to document.body with smart overflow positioning
• Auto-keyframe toggle removed (always on); CSS drag blocked on GSAP-animated elements

Test plan

• Build passes
• Typecheck clean
• GSAP-animated elements positioned outside bounds show dotted indicators
• Clicking an indicator selects the element
• Dragging an indicator commits a position move
• Iframe content doesn't bleed outside preview area at any zoom level
• Delete All Keyframes removes all animations atomically in one click
• Context menus appear at cursor position
• Drag on GSAP element creates/updates keyframes correctly

Stack: 7/7 — depends on #1359

[miguel-heygen]

• feat(studio): off-screen element indicators + unclipped overlay #1360 👈 (View in Graphite)
• fix(studio): gesture recording replaces existing position keyframes #1359
• fix(studio): property panel group-aware keyframe routing #1358
• fix(studio): keyframe cache propertyGroup tagging + timeline UI #1357
• fix(studio): per-property-group intercept routing + drag/resize fixes #1356
• fix(core): split-into-property-groups and replace-with-keyframes mutations #1355
• fix(core): per-property-group keyframe foundations #1354
• main

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

[james-russo-rames-d-jusso]

Verdict: 🚨 BLOCKER — off-screen indicator click handler can't find the elements it surfaces.

Blocker — broken selection for unidentified elements

• useOffScreenIndicators.ts:181 sets elementId = el.id || base where base falls back to data-hf-id || tagName.
• StudioPreviewArea.tsx:285 click handler resolves via iframe.contentDocument.getElementById(id) — but getElementById only matches the id attribute, NOT data-hf-id.
• Elements without an HTML id (most authored HF elements, per htmlParser.ts:204 which preserves data-hf-id as canonical) will show indicators that silently fail on click.

Fix: either select by [data-hf-id="..."] in the click handler (querySelector instead of getElementById), or restrict indicators to elements with a real id.

Other concerns

• Docstring says "edge-clamped" but code doesn't clamp — useOffScreenIndicators.ts:1-4 claims "edge-clamped indicator positions" but the hook pushes raw elLeft/elTop/elW/elH — no clamp to comp edges. The "indicators at edges" UX described in the PR body relies entirely on the NLELayout overflow-hidden move letting the off-screen rect render in the unclipped region. A very-far-off element won't render an edge indicator at all — it'll render somewhere far outside the outer container or be clipped by it. Either add the clamp, or update the docstring + PR body to match what's actually built.
• RAF loop runs forever — useOffScreenIndicators.ts:113-167 walks every GSAP target, calls getBoundingClientRect() per element, every frame, regardless of whether anything is animating or any element is actually off-screen. With many elements + studio panel re-renders, this is layout thrash on the 16ms budget. Suggest gating on selection change + transform-commit events, or throttling to e.g. 10Hz, or short-circuiting when compRect.width hasn't changed AND targets array hash hasn't changed.
• Pointer-handler leak risk — DomEditOverlay.tsx:560-572 attaches pointermove/pointerup via el.addEventListener but no pointercancel listener. Touch-cancel / contextmenu / scroll-while-dragging will leak listeners + leave setPointerCapture un-released + leave el.style.transform mutated. Add a pointercancel cleanup path mirroring onUp.
• Outside-comp click guard changes deselection behavior — DomEditOverlay.tsx:263-278 early-returns on clicks outside comp bounds. Comment says "would clear the selection" — but the previous "click empty space to deselect" behavior is now broken in the unclipped overlay region. Worth a UX check: if you select an element then click in the new unclipped margin, does selection persist forever? May be intentional, but it's a behavior change beyond the documented fix.

Determinism

collectGsapTargetElements:36-58 reads iframe.contentWindow.__timelines — wrapped in try/catch for cross-origin, good. No render-time fetch(). HF determinism rule not violated.

Test coverage

No tests added — 196 LOC of coordinate math + RAF loop + DOM mutation with zero coverage. The coordinate-math path (elLeft = iframeRect.left - overlayRect.left + elRect.left * rootScaleX) is exactly the kind of thing that breaks silently on zoom/pan changes.

Cross-stack

Introduces new onSelectElementById prop on DomEditOverlay; depends on buildDomSelectionFromTarget from useDomSelection.ts:206 (already in stack). NLELayout overflow restructure is isolated to this PR.

— Review by Rames D Jusso

[james-russo-rames-d-jusso]

R3 verification — blocker. R2 click-resolution blocker unchanged, plus a stack-internal drive-by flag flip.

🚨 StudioPreviewArea.tsx:289 / useOffScreenIndicators.ts:464 — getElementById vs data-hf-id mismatch unchanged. The click handler is still iframe?.contentDocument?.getElementById(id); elementId = el.id || base still falls back to data-hf-id/tagName. Authored HF elements with no id attribute will still render an indicator (keyed off data-hf-id) and silently fail to select on click. Fix: swap click handler to querySelector('[data-hf-id="..."], #...') with a discriminator, OR guard elementId so we only emit indicators for elements with a real id.

🚨 manualEditingAvailability.ts:93 — stack-internal drive-by flag flip. STUDIO_GSAP_DRAG_INTERCEPT_ENABLED default flips from false → true in this PR — and #1356 (one below in the stack) correctly ships false. Not in the PR body, not in scope of "off-screen element indicators." Either an accidental ride-along (the same accidental flip I caught on monolithic #1344 R2) or an intentional flip that needs body/commit-message coverage. Same flag, same shape, same stack. Please confirm intent.

❌ RAF loop still per-frame at useOffScreenIndicators.ts:387-480. requestAnimationFrame(update) runs unconditionally every frame, calling getBoundingClientRect on every GSAP target. No throttling, no early-out on no-iframe-change. Layout thrash risk on big compositions.

❌ No pointercancel listener at DomEditOverlay.tsx:225-260. onPointerDown adds pointermove/pointerup, no pointercancel. OS-cancelled gestures (touch interrupt, alt-tab mid-drag) leak listeners + leave el.style.transform stuck.

❌ Zero tests. 196 LOC of coordinate math (declared-vs-iframe scaling, overlay vs comp-rect transforms) shipped untested.

❌ PR body vs implementation. Body says "dotted indicators at composition edges"; what ships is border: 1.5px dashed; opacity: 0.5 at ind.left/ind.top — the element's actual off-screen position, clipped by the unclipped overlay. A translucent dashed ghost at real position, not an edge indicator. Update body or implementation.

Review by Rames D Jusso

[vanceingalls]

Verification pass — R3 items checked against current HEAD (7e8f788).

1. getElementById vs data-hf-id — StudioPreviewArea.tsx:290

FIXED. useOffScreenIndicators.ts now has a guard at line 172:

// Only elements with a real id attribute can be selected via getElementById
if (!el.id) continue;

All surfaced indicators have elementId = el.id (a real DOM id). The getElementById(id) call in StudioPreviewArea.tsx:290 correctly resolves them. Comment explains the contract.

2. STUDIO_GSAP_DRAG_INTERCEPT_ENABLED false→true flip — manualEditingAvailability.ts:93

INTENTIONAL and explained. PR body states: "Intentional flag flip: STUDIO_GSAP_DRAG_INTERCEPT_ENABLED set to true — this stack implements and tests the drag intercept system that was gated behind false in #1341." The explanation is in the PR body. Sufficient.

Both R3 items addressed. Stamp-ready (with the same non-blocking R3 concerns Rames noted: RAF throttling, pointercancel, zero tests).

— Vai (verification pass)

[vanceingalls]

LGTM — Via reviewed, stamp applied.

— Vai

The base branch was changed.