feat(studio): revamps Studio + improves code quality (#2291)

* feat(studio): glue API coexistence layer for the NLE swap What: extends 21 glue files so the OLD timeline/canvas engine and the NEW NLE components type-check side by side: playerStore (multi-select setters, zoom pin, snap toggle, non-reactive scale scratch), drag-state types gain optional NLE fields, timelineLayout/timelineAssetDrop/timelineEditingHelpers/ timelineEditing/timelineElementHelpers/studioHelpers/assetHelpers gain the NLE exports, DomEditOverlay + gestures + AssetContextMenu + Timeline props gain optional callbacks/params, contexts gain *Optional hooks, and TimelineEditCallbacks.onMoveElements becomes a bivariant method accepting both engines' change shapes. patchDocumentRootDuration's test rides along. Why: this is the keystone that dissolves the old "welded glue" problem — every symbol the NLE components need is ADDED next to what the old engine still uses, so the engine components and the swaps can land as separate reviewable PRs. How: 15 authored intermediate files (main content + additive symbols; no behavior changes — new fields optional, new callbacks unused until wired) plus 6 files whose final content is already purely additive. New exports without consumers yet carry TEMP(studio-dnd) ignoreExports entries, removed by the app-shell swap. Test plan: tsc --noEmit in studio + studio-server (verifies BOTH engines compile); bunx vitest run (full suite green incl. the 6 new patchDocumentRootDuration tests); fallow audit clean. * feat(studio): timeline interaction hooks and lanes component (unwired) What: the timeline-side wiring layer, unwired: TimelineLanes (the lane renderer driving drag/resize/marquee), timelineMarquee (+tests), useTimelineStackingSync, useTimelineGeometry, useTimelineEditPinning, useTimelineEditingDrops. Why: everything between the pure drag math and <Timeline> itself; the timeline-glue swap PR then only rewires Timeline/TimelineCanvas onto these. How: new files, tsc-clean against the coexistence layer. Unwired components carry TEMP(studio-dnd) entry registrations, removed at the app-shell swap. Test plan: bunx vitest run timelineMarquee.test.ts; tsc --noEmit; fallow audit clean. * feat(studio): NLE shell assembly (unwired) What: EditorShell (the full editor layout replacing NLELayout + StudioPreviewArea), TimelinePane (timeline host with sub-comp rebasing) and useTimelineEditCallbacks (the callback bag bridging store edits to the timeline), all unwired. Why: the shell that App swaps to in the final step; reviewing it standalone keeps that swap PR small. How: new files against the coexistence layer; TEMP(studio-dnd) entries until App mounts EditorShell in the app-shell swap. Test plan: tsc --noEmit; bunx vitest run (suite unchanged); fallow audit clean. * feat(studio): timeline glue swap — Timeline/TimelineCanvas onto the NLE engine What: flips the timeline glue to its final form (23 files): Timeline and TimelineCanvas rebuilt on TimelineLanes/TimelineOverlays, useTimelineClipDrag drives preview/commit through the new drag engine, range selection goes multi-select, playback loop moves to useTimelinePlayerLoop. Deletes the 9 old-engine files this orphans (group drag, marquee selection, snap targets, layer gutter, selection overlays + their suites) — each is compile- or gate-forced by this swap, verified by probe. Why: second swap step; timeline-only, canvas and App untouched. How: modified files to final content + forced deletions. playerStore/timelineEditing/timelineCallbacks stay at their coexistence form until the app swap (the old App still runs on them). Test plan: tsc --noEmit; bunx vitest run (full suite); fallow audit clean. * feat(studio): clip thumbnail modules What: ImageThumbnail (+tests) and thumbnailUtils (+tests) — frame decode with SVG/AVIF format fallbacks and rounded-corner clipping — plus VideoThumbnail updates. Why: the decode layer for timeline clip thumbnails, ahead of the visual refresh that renders them. How: new modules + one modified file; purely presentational. Test plan: bunx vitest run on both test files; tsc --noEmit; fallow audit clean. * feat(studio): assets/blocks panel behaviors + preview helpers What: blocks tab install flow, right-panel and global drag-overlay polish, music beat analysis and clip-content rendering hooks, and the preview-helper utilities backing asset preview. Why: completes the studio NLE stack on top of the visual refresh. How: modified files only (kept as one PR: splitting further would produce sub-150-LOC fragments of interdependent panel glue). Test plan: bunx vitest run studioPreviewHelpers/studioUrlState suites; tsc --noEmit; fallow audit clean. * fix(studio): restore timeline playback loop * fix(studio): restore missing GSAP helpers module * refactor(studio): split timeline GSAP helpers * style(studio): keep timeline helper under size limit * fix(studio): restore timeline overlays module * fix(studio): remove stale GSAP import * fix(studio): restore canonical timeline dependencies * style(studio): format restored timeline helpers * style(studio): satisfy helper line limit * fix(studio): repair rebuilt timeline integration * feat(studio): complete rebuilt NLE cutover * fix(studio): guard project and timeline race boundaries * fix(studio): preserve graded resize and crop geometry * fix(studio): log resize/rotate commit failures, move anchor accumulator to resize-local * fix(studio): treat duration-0 tweens as static holds and settle resize position before persist Instant holds (to()/fromTo() with duration 0) were classified as animated tweens by every commit route, so resizing or rotating them converted the hold into a corrupt duration-0 keyframes tween (new value at 0%, old at 100%) that GSAP drops; panel edits appended a losing set. A shared isInstantHold() now routes them through the static replace-in-place path, and percentage math guards zero-duration windows. Separately, anchored-corner resizes painted 3-5 frames at the new size but old position while the offset persist round-tripped the server. The commit path now applies the corrected GSAP position synchronously before awaiting the offset persist, mirroring the scale route's settle. * feat(studio): gesture-transaction seam with commit observability Introduce runGestureTransaction — one owner for a gesture commit's settle -> persist -> record lifecycle. It settles the live DOM synchronously before any async persist, folds every mutation into one undo entry via a per-transaction coalesceKey, restores pre-gesture state exactly once on failure, and asserts (dev console) + reports (PostHog: commit_transaction / commit_invariant_violation / commit_transaction_failed) that a persist never changes pixels. The box-size resize path is migrated onto it; the ad hoc per-route coalesceKey/reload handling is removed. Extract the resize draft-rect math into resizeDraft.ts to keep the gesture-handler file under the size cap. Also: keep url_hash telemetry to the route slug only (drop the query string, which carried the user's selected element id/selector), and gate the [hf-resize] diagnostics behind localStorage hf-resize-debug so they ship as opt-in tracing rather than console noise. * fix(studio): transaction owns the undo label The coalesced history entry took the last sub-mutation's label, so a resize surfaced as "Move layer" (the offset persist) in undo/redo. The seam now stamps tx.label on every wrapped mutation, so the folded entry reads as the gesture. * fix(studio): atomic static size/position commits (no data loss) Static resize/position holds updated an existing set via delete+add — two undo entries, and a delete that succeeded before a failed add lost the hold on disk. Use one in-place update-properties mutation when a set exists (one undo entry, no partial-failure window). The keyframed-hold heal that can't be expressed as a property update now adds before it deletes, so any single failure leaves a recoverable duplicate, never a lost hold. Transaction-owned commits are tracked via a WeakSet so the heal path never double-wraps an already-wrapped gesture. * fix(core): restore timed-clip visibility after a forced timeline rebind __hfForceTimelineRebind force-rendered the re-registered timeline but never re-ran the per-[data-start] visibility pass, so after undo or soft reload every clip rendered regardless of its time window until a full page reload. Extract the visibility loop into syncTimedElementVisibility and call it from both syncMediaForCurrentState (unchanged) and the rebind. * fix(studio): atomic z-order/keyframe/split commits, one undo entry each Three edit-commit paths hardened onto the one-transaction invariant: - Z-order reorder (useElementLifecycleOps): N per-element writes now fold into one undo entry (coalesceMs Infinity) and, on a failed persist, restore already-written files to disk so no partial reorder survives. - Enable-keyframes (useEnableKeyframes/useGsapKeyframeOps): the intermediate convert phase no longer full-reloads the preview (skipReload), killing the black-flash remount; convert + edit share one coalesce key = one undo entry. - Razor split-all (useRazorSplit): snapshot before the batch and restore on any failure, so a mid-batch error never leaves un-revertable partial splits. Shared file-history helpers (RecordEditInput, DomEditCommitBaseParams, readProjectFileContent, restoreFilesToOriginal) dedupe the rollback/commit logic across these paths. Commit options thread as one partial object rather than field-by-field. Test setup extracted into colocated helpers. * fix(studio): fold multi-step edits into one undo entry; guard text revert - Gesture recording (useGestureCommit): the per-property-group commits now share one coalesce key and only the last reloads, so a recording is one undo entry and one preview reload instead of up to four. - Delete selected keyframes (deleteSelectedKeyframes, split out of timelineEditingHelpers): N removals fold into one coalesced undo entry with a single reload. - Text-field commit (useDomEditTextCommits): commitDomTextFields now uses the same version-guarded revert as handleDomTextCommit, so a stale failed commit can no longer stomp a newer successful one. * feat(studio): batch a gesture's mutations into one atomic server write A transaction that emits N mutations previously did N sequential POSTs, each rewriting the file and soft-reloading — the root of the multi-phase persist window. Add a gsap-mutations-batch endpoint that validates every mutation up front, applies them in one in-memory rewrite chain, and writes the file once (all-or-nothing: an invalid entry rejects the whole batch, no partial write). The seam buffers a transaction's commits and, when more than one targets the same file, dispatches a single batch — one write, one history entry, one reload. The batch capability rides on the existing commit-function reference; no option fields are threaded through callers. * fix(studio): soften off-canvas indicator outline to 30% opacity The dashed off-canvas selection outline at 60% was noisy with many protruding elements on screen; drop the resting opacity to 30% (hover still restores full opacity so it stays discoverable). * fix(studio): drop off-canvas indicator outline to 10% opacity Follow-up to the 30% softening — 10% resting opacity reads much calmer with many protruding elements; hover still restores full opacity. * fix(studio): gate [hf-commit] console traces to dev only The start/settled/persisted/restore lifecycle traces logged on every gesture commit in all environments — console noise for end users. Route them through a dev-only traceCommit helper (matching the pixel-violation error's existing DEV gate). The commit_* PostHog events stay always on; they are the production observability, the console lines are a dev aid. * fix(studio): count actual reloads, not softReload requests, in commit telemetry A resize's size and offset persists both request softReload; the seam counted each request, so a batched gesture reported reload_count 2 even though the batch is one write and one reload. Compute the count from what dispatchBufferedCommits actually did — one for a batch, the request count for the sequential fallback. * fix(studio): rotate hover + off-canvas overlays with the element; flicker-free crop - Hover overlay applied the element's rotation only to the selection chrome, not the hover box; it now rotates about center like the selection, via a shared orientedGroupAwareOverlayRect router (one owner for rotation-aware overlay geometry across hover/selection/off-canvas). - Off-canvas indicator was axis-aligned; it now rotates with the element and inverse-rotates the canvas-exclusion clip into the element's local frame, so the protruding-sliver clip stays correct for rotated elements. - Crop commit re-lifted the element only in the commit's .then(), so one frame painted the cropped state (the flicker). Re-lift synchronously right after onStyleCommit (which applies the clip before its first await), so the cropped state never paints; the persisted file value is unchanged. * fix(studio): address code-review findings across the commit-hardening campaign Correctness (would ship green, bite under latency): - Enable-keyframes phase 2 now carries coalesceMs: Infinity, so the convert folds into one undo entry instead of splitting past the 300ms default. - The SDK keyframe persist path forwards coalesceMs (CutoverOptions gains the field); multi-keyframe delete and convert coalesce correctly when SDK-routed. - Razor split-all's rollback is guarded so a failing restore can't swallow the error toast that tells the user the split failed. Simplification (single source of truth / no dead flexibility): - Decompose resolveResizeDraftRect (drops a fallow-ignore suppression). - Delegate the third readProjectFileContent copy to the shared helper. - Inline setPatchFromUpdateProperties (its only caller passes one mutation). - One toSdkPersistOptions translates gesture overrides to SDK options. - Bundle the reorder-rollback deps into one object (was 7-9 positional args). - Dedupe the 'last group reloads' ternary; type gesture options as CommitMutationOptions; drop a Map+array wrapper around a single write. * feat(studio): atomic z-order reorder via batch patch-element endpoint Z-order reorder issued N per-element inline-style patches (one server write each), so a mid-chain failure could leave a partial reorder on disk. Add a patch-elements-batch endpoint that validates every patch, folds them over the file in one in-memory rewrite, and writes once (all-or-nothing; unsafe input rejects with no write). The reorder now sends one batch per source file and records one undo entry. Because a failed atomic write persists nothing, the interim disk-write-back rollback (restoreReorderedFile / restoreFulfilledReorderFiles / ReorderRollbackDeps) is deleted — failure rolls back only live DOM/store state. Closes the last disk-atomicity gap. * fix(studio): razor-split undo no longer silently no-ops The split clone was written to disk without a data-hf-id, so the split endpoint recorded that unstamped HTML as the undo entry's afterHash. The next reloadPreview() ran the preview route's ensureHfIds write-back, which minted a fresh id and persisted DIFFERENT bytes — so at undo time the disk hash no longer matched afterHash and editHistory's content-mismatch guard silently refused the undo (no write, no network, no error). Stamp the split output via ensureHfIds in splitElementInHtml before it is written/returned, so the preview write-back is a no-op and the recorded afterHash always equals the final on-disk bytes. Fixes at the source rather than relaxing the mismatch guard. Corrects the stale comment that credited forceReloadSdkSession. * feat(studio): closed-hand grab cursor on the rotate handle The rotate handle used the default arrow cursor; show a grabbing (closed-hand) cursor on hover to signal it's grabbed and dragged to rotate. * fix(studio): dropping a dragged element over another no longer selects it A moved drag's release fired the box click, which re-selected whatever now sat under the pointer via the hover cache — so dropping an element over a higher-z one selected the drop target instead of keeping the dragged element selected. The drag-move branch now suppresses the next box click, mirroring the resize branch. * fix(studio): group drag is one undo entry, not one per element Dragging a multi-selected group committed each member's position write as its own undo entry, so reverting took N Cmd+Z presses. Force a shared coalesceKey (infinite window) across every member's commit so they fold into a single undo entry, like the other multi-step commit paths. * fix(studio): undo of a split no longer leaves a ghost clip in the timeline The file and the composition iframe revert correctly on undo, but the timeline panel kept a ghost node for the split clone. The element-merge that repopulates the timeline preserves elements the fresh scan dropped — intended for enriched sub-composition children a bare DOM re-scan misses, but it also preserved a genuinely-removed TOP-LEVEL element (the split clone after undo), leaving a phantom clip. Restrict the preserve to elements with a compositionSrc (the enriched sub-comp children); a top-level element missing from the fresh scan was truly removed. --------- Co-authored-by: ukimsanov <ular.kimsanov@heygen.com>
2026-09-10 22:20:14 +00:00 · 2026-07-13 02:55:36 -04:00
parent 9940503102
commit df29fa7a5e
228 changed files with 18774 additions and 7332 deletions
@@ -1,5 +1,4 @@
-import { memo, useEffect, useMemo, useRef, useState, type RefObject } from "react";
-import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";
+import { memo, useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";
 import { type DomEditSelection } from "./domEditing";
 import type { PreviewMouseDownOptions } from "../../hooks/usePreviewInteraction";
 import { useMarqueeGestures } from "./marqueeCommit";
@@ -16,17 +15,20 @@ import {
 import { useDomEditOverlayRects } from "./useDomEditOverlayRects";
 import { OffCanvasIndicators, type OffCanvasRect } from "./OffCanvasIndicators";
 import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
+import { useDomEditNudge } from "./useDomEditNudge";
 import { SnapGuideOverlay, type SnapGuidesState } from "./SnapGuideOverlay";
 import { GridOverlay } from "./GridOverlay";
 import type { GestureRecordingState } from "./GestureRecordControl";
-import { DomEditCropHandles } from "./DomEditCropHandles";
-import { DomEditRotateHandle } from "./DomEditRotateHandle";
+import { DomEditGroupChrome, DomEditSelectionChrome } from "./DomEditSelectionChrome";
 import { hugRectForElement } from "./domEditOverlayCrop";
 import { useCropOverlay } from "../../hooks/useCropOverlay";
 import { readDomEditSelectionShapeStyles, resolveBoxChromeClass } from "./domEditOverlayShape";
 import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { startOffCanvasIndicatorRefresh } from "./offCanvasIndicatorRefresh";
+import { CanvasContextMenu } from "./CanvasContextMenu";
+import type { ZOrderPatch } from "./canvasContextMenuZOrder";
+import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";

 // Re-exports for external consumers — preserving existing import paths.
 export {
@@ -37,7 +39,6 @@ export {
 export {
  focusDomEditOverlayElement,
  hasDomEditRotationChanged,
-  resolveDomEditResizeGesture,
  resolveDomEditRotationGesture,
 } from "./domEditOverlayGestures";
 export type { DomEditGroupPathOffsetCommit } from "./domEditOverlayGestures";
@@ -73,6 +74,8 @@ interface DomEditOverlayProps {
  onBoxSizeCommit: (
    selection: DomEditSelection,
    next: { width: number; height: number },
+    offset?: { x: number; y: number },
+    restore?: () => void,
  ) => Promise<void> | void;
  onRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void> | void;
  onStyleCommit?: (property: string, value: string) => Promise<void> | void;
@@ -81,6 +84,19 @@ interface DomEditOverlayProps {
  recordingState?: GestureRecordingState;
  onToggleRecording?: () => void;
  onMarqueeSelect?: (selections: DomEditSelection[], additive: boolean) => void;
+  /**
+   * Delete the selected canvas element.
+   * Wire to handleDomEditElementDelete from useDomEditActionsContext —
+   * same handler the Delete/Backspace hotkey uses.
+   */
+  onDeleteSelection?: (selection: DomEditSelection) => void;
+  /**
+   * Called with the resolved z-order patch list after an optimistic DOM update.
+   * The patch list is tie-aware and may include sibling elements (see
+   * canvasContextMenuZOrder). Wire to handleDomZIndexReorderCommit from
+   * useDomEditActionsContext. See CanvasContextMenu.tsx module comment.
+   */
+  onApplyZIndex?: (selection: DomEditSelection, patches: ZOrderPatch[]) => void;
 }

 // fallow-ignore-next-line complexity
@@ -105,6 +121,8 @@ export const DomEditOverlay = memo(function DomEditOverlay({
  onRotationCommit,
  onStyleCommit,
  onMarqueeSelect,
+  onDeleteSelection,
+  onApplyZIndex,
 }: DomEditOverlayProps) {
  const overlayRef = useRef<HTMLDivElement | null>(null);
  const boxRef = useRef<HTMLDivElement | null>(null);
@@ -121,8 +139,31 @@ export const DomEditOverlay = memo(function DomEditOverlay({
  const snapGuidesRef = useRef<SnapGuidesState | null>(null);
  const rafPausedRef = useRef(false);

+  // Context menu state: position of the right-click that opened it.
+  // contextMenuSelection is the element the menu targets — captured at right-click
+  // time so the menu can open even before the React selection state settles.
+  const [contextMenu, setContextMenu] = useState<{
+    x: number;
+    y: number;
+    sel: DomEditSelection;
+  } | null>(null);
+
  const selectionRef = useRef(selection);
  selectionRef.current = selection;
+
+  // Close the context menu whenever the selection moves off the element the menu
+  // targets (a click that reselects elsewhere, a deselect, or a preview reload
+  // that rebuilds the selection). Without this the menu can linger — orphaned —
+  // over a stale target after the underlying element is gone. A right-click that
+  // OPENS the menu also selects its target, so the common open path keeps the
+  // menu (same element) rather than immediately dismissing it.
+  useEffect(() => {
+    if (!contextMenu) return;
+    if (!selection || selection.element !== contextMenu.sel.element) {
+      setContextMenu(null);
+    }
+  }, [selection, contextMenu]);
+
  const activeCompositionPathRef = useRef(activeCompositionPath);
  activeCompositionPathRef.current = activeCompositionPath;
  const groupSelectionsRef = useRef(groupSelections);
@@ -241,6 +282,23 @@ export const DomEditOverlay = memo(function DomEditOverlay({
    snapGuidesRef,
  });

+  // Arrow-key nudge (1px, Shift = 10px) — commits through the same
+  // path-offset callbacks as a drag, one undo entry per key burst.
+  const { flushNudge } = useDomEditNudge({
+    selection,
+    groupSelections,
+    allowCanvasMovement,
+    selectionRef,
+    overlayRectRef,
+    groupOverlayItemsRef,
+    gestureRef,
+    groupGestureRef,
+    blockedMoveRef,
+    onManualDragStartRef,
+    onPathOffsetCommitRef,
+    onGroupPathOffsetCommitRef,
+  });
+
  const marquee = useMarqueeGestures({
    iframeRef,
    overlayRef,
@@ -370,6 +428,38 @@ export const DomEditOverlay = memo(function DomEditOverlay({
    e.stopPropagation();
  };

+  // Right-click: select element first (if not already selected), then open menu.
+  const handleContextMenu = useCallback(
+    async (event: React.MouseEvent<HTMLDivElement>) => {
+      event.preventDefault();
+
+      // If no element is selected yet, resolve it from the pointer position first.
+      const currentSel = selectionRef.current;
+      let activeSel: DomEditSelection | null = currentSel;
+      if (!currentSel) {
+        const pointerEvent = event as unknown as React.PointerEvent<HTMLDivElement>;
+        const resolved = await onCanvasPointerMoveRef.current(pointerEvent);
+        if (!resolved) return; // Nothing under the cursor — skip menu.
+        onSelectionChangeRef.current(resolved, { revealPanel: true });
+        // Use `resolved` directly: React state (and therefore selectionRef) won't
+        // update synchronously after onSelectionChange — we'd be reading stale null.
+        activeSel = resolved;
+      } else {
+        // Check if the user right-clicked on an unselected element (hover target).
+        const hover = hoverSelectionRef.current;
+        if (hover && hover.element !== currentSel.element) {
+          onSelectionChangeRef.current(hover, { revealPanel: true });
+          activeSel = hover;
+        }
+      }
+
+      if (!activeSel) return;
+      setContextMenu({ x: event.clientX, y: event.clientY, sel: activeSel });
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
  return (
    <div
      ref={overlayRef}
@@ -378,142 +468,59 @@ export const DomEditOverlay = memo(function DomEditOverlay({
      aria-label="Composition canvas"
      // Cursor follows marquee rect *state* (re-renders), not the mutable ref.
      style={marquee.marqueeRect ? { cursor: "crosshair" } : undefined}
-      onPointerDownCapture={(event) =>
-        focusDomEditOverlayElement(event.currentTarget as FocusableDomEditOverlay)
-      }
+      onPointerDownCapture={(event) => {
+        // A pointer gesture supersedes a pending nudge burst — commit it first
+        // so the gesture's member snapshot starts from the nudged position.
+        flushNudge();
+        focusDomEditOverlayElement(event.currentTarget as FocusableDomEditOverlay);
+      }}
      onPointerDown={handleOverlayPointerDown}
      onMouseDown={handleOverlayMouseDown}
      onPointerMove={marquee.onPointerMove}
      onPointerLeave={() => onCanvasPointerLeaveRef.current()}
      onPointerUp={marquee.onPointerUp}
      onPointerCancel={marquee.onPointerCancel}
+      onContextMenu={handleContextMenu}
    >
      {hoverSelection && hoverRect && compRect.width > 0 && (
        <div
          aria-hidden="true"
          data-dom-edit-hover-box="true"
          className="pointer-events-none absolute rounded-md border border-studio-accent/80 shadow-[0_0_0_1px_rgba(60,230,172,0.25)]"
-          style={hugRectForElement(hoverRect, hoverSelection.element)}
+          style={{
+            ...hugRectForElement(hoverRect, hoverSelection.element),
+            transform: hoverRect.angle ? `rotate(${hoverRect.angle}deg)` : undefined,
+          }}
        />
      )}
      {hasGroupSelection && groupOverlayItems.length > 1 && groupBounds && compRect.width > 0 && (
-        <>
-          {groupOverlayItems.map((item) => (
-            <div
-              key={item.key}
-              aria-hidden="true"
-              className="pointer-events-none absolute rounded-xl border border-studio-accent/70"
-              style={{
-                left: item.rect.left,
-                top: item.rect.top,
-                width: item.rect.width,
-                height: item.rect.height,
-              }}
-            />
-          ))}
-          <div
-            data-dom-edit-selection-box="true"
-            className="pointer-events-auto absolute rounded-xl border border-studio-accent shadow-[0_0_0_1px_rgba(60,230,172,0.3)]"
-            style={{
-              left: groupBounds.left,
-              top: groupBounds.top,
-              width: groupBounds.width,
-              height: groupBounds.height,
-              cursor: allowCanvasMovement && groupCanMove ? "move" : "default",
-            }}
-            onPointerDown={(e) => {
-              if (!allowCanvasMovement || !groupCanMove || e.shiftKey) return;
-              gestures.startGroupDrag(e);
-            }}
-            onMouseDown={suppressBoxMouseDown}
-            onClick={handleBoxClick}
-          />
-        </>
+        <DomEditGroupChrome
+          groupOverlayItems={groupOverlayItems}
+          groupBounds={groupBounds}
+          allowCanvasMovement={allowCanvasMovement}
+          groupCanMove={groupCanMove}
+          gestures={gestures}
+          onBoxMouseDown={suppressBoxMouseDown}
+          onBoxClick={handleBoxClick}
+        />
      )}
      {!hasGroupSelection && selection && overlayRect && compRect.width > 0 && (
-        <>
-          {allowCanvasMovement && selection.capabilities.canApplyManualRotation && (
-            <DomEditRotateHandle
-              overlayRect={overlayRect}
-              cropOutlineInsetPx={cropOutlineInsetPx}
-              onStartRotate={(e) => {
-                e.stopPropagation();
-                gestures.startGesture("rotate", e);
-              }}
-            />
-          )}
-          <div
-            key={selectionKey}
-            ref={boxRef}
-            data-dom-edit-selection-box="true"
-            className={`pointer-events-auto absolute rounded-md ${boxChromeClass}`}
-            style={{
-              left: overlayRect.left,
-              top: overlayRect.top,
-              width: overlayRect.width,
-              height: overlayRect.height,
-              clipPath: boxClipPath,
-              cursor:
-                allowCanvasMovement && selection.capabilities.canApplyManualOffset
-                  ? "move"
-                  : "default",
-            }}
-            onPointerDown={(e) => {
-              if (!allowCanvasMovement || e.shiftKey) return;
-              if (selection.capabilities.canApplyManualOffset) {
-                gestures.startGesture("drag", e);
-                return;
-              }
-              e.preventDefault();
-              e.stopPropagation();
-              e.currentTarget.setPointerCapture(e.pointerId);
-              blockedMoveRef.current = {
-                pointerId: e.pointerId,
-                startX: e.clientX,
-                startY: e.clientY,
-                notified: false,
-              };
-            }}
-            onMouseDown={suppressBoxMouseDown}
-            onClick={handleBoxClick}
-          >
-            {cropOutlineInsetPx && (
-              <div
-                className="pointer-events-none absolute rounded-md border border-studio-accent/80 shadow-[0_0_0_1px_rgba(60,230,172,0.25)]"
-                style={{
-                  left: cropOutlineInsetPx.left,
-                  top: cropOutlineInsetPx.top,
-                  right: cropOutlineInsetPx.right,
-                  bottom: cropOutlineInsetPx.bottom,
-                }}
-              />
-            )}
-            {allowCanvasMovement && selection.capabilities.canApplyManualSize && (
-              <div
-                className="absolute -right-1.5 -bottom-1.5 w-3 h-3 rounded-sm bg-studio-accent border border-studio-accent/60"
-                style={{
-                  cursor: "se-resize",
-                  touchAction: "none",
-                  ...(cropOutlineInsetPx && {
-                    right: cropOutlineInsetPx.right - 6,
-                    bottom: cropOutlineInsetPx.bottom - 6,
-                  }),
-                }}
-                onPointerDown={(e) => {
-                  e.stopPropagation();
-                  gestures.startGesture("resize", e);
-                }}
-              />
-            )}
-          </div>
-          {selection.capabilities.canCrop && groupSelections.length <= 1 && (
-            <DomEditCropHandles
-              selection={selection}
-              overlayRect={overlayRect}
-              onStyleCommit={onStyleCommitRef.current}
-            />
-          )}
-        </>
+        <DomEditSelectionChrome
+          selection={selection}
+          overlayRect={overlayRect}
+          allowCanvasMovement={allowCanvasMovement}
+          cropOutlineInsetPx={cropOutlineInsetPx ?? undefined}
+          boxRef={boxRef}
+          boxChromeClass={boxChromeClass}
+          boxClipPath={boxClipPath}
+          selectionKey={selectionKey}
+          groupSelectionCount={groupSelections.length}
+          blockedMoveRef={blockedMoveRef}
+          gestures={gestures}
+          onStyleCommit={onStyleCommitRef.current}
+          onBoxMouseDown={suppressBoxMouseDown}
+          onBoxClick={handleBoxClick}
+        />
      )}
      {childRects.length > 0 &&
        compRect.width > 0 &&
@@ -539,6 +546,29 @@ export const DomEditOverlay = memo(function DomEditOverlay({
        onSelectionChangeRef={onSelectionChangeRef}
      />
      <MarqueeOverlay candidateRects={marquee.candidateRects} marqueeRect={marquee.marqueeRect} />
+      {contextMenu && (
+        <CanvasContextMenu
+          x={contextMenu.x}
+          y={contextMenu.y}
+          selection={contextMenu.sel}
+          onClose={() => setContextMenu(null)}
+          onDelete={
+            onDeleteSelection
+              ? (sel) => {
+                  setContextMenu(null);
+                  onDeleteSelection(sel);
+                }
+              : undefined
+          }
+          onApplyZIndex={
+            onApplyZIndex
+              ? (patches) => {
+                  onApplyZIndex(contextMenu.sel, patches);
+                }
+              : undefined
+          }
+        />
+      )}
      <GridOverlay
        visible={gridVisible}
        spacing={gridSpacing}
@@ -551,8 +581,10 @@ export const DomEditOverlay = memo(function DomEditOverlay({
      />
      <SnapGuideOverlay
        snapGuidesRef={snapGuidesRef}
-        overlayWidth={compRect.width}
-        overlayHeight={compRect.height}
+        compositionLeft={compRect.left}
+        compositionTop={compRect.top}
+        compositionWidth={compRect.width}
+        compositionHeight={compRect.height}
      />
    </div>
  );