From 3fdfc5404627efc436281c353ae5d4000f97c44d Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Sat, 11 Jul 2026 13:55:16 -0700
Subject: [PATCH 1/3] =?UTF-8?q?feat(studio):=20clip=20drag=20engine=20?=
 =?UTF-8?q?=E2=80=94=20preview=20and=20commit=20(unwired)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

What: the NLE clip-drag engine core: timelineClipDragPreview (zone-aware
preview placement; keeps the legacy resolveDragPreviewPlacement export until
the timeline swap), timelineClipDragCommit (drop → move/insert commit,
stacking-synced) and timelineElementsMove (batched ripple/insert move with
GSAP position shifting), with test suites.

Why: the drag-drop brain, reviewable as functions before any component
mounts it.

How: new files plus one authored intermediate (preview file = final content
+ legacy export the old engine still imports); consumes the collision/
snapping/zones/stacking modules and the coexistence layer.

Test plan: bunx vitest run on both test suites; tsc --noEmit; fallow audit
clean.
---
 .fallowrc.jsonc | 17 -----------------
 1 file changed, 17 deletions(-)

diff --git a/.fallowrc.jsonc b/.fallowrc.jsonc
index c6eb57fc1c..e96e35e470 100644
--- a/.fallowrc.jsonc
+++ b/.fallowrc.jsonc
@@ -55,13 +55,6 @@
     "packages/studio/src/hooks/gsapRuntimePreview.ts",
     // 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.
-    "packages/studio/src/player/components/TimelineLanes.tsx",
-    "packages/studio/src/player/components/useTimelineStackingSync.ts",
-    "packages/studio/src/player/components/useTimelineGeometry.ts",
-    "packages/studio/src/player/components/useTimelineEditPinning.ts",
-    "packages/studio/src/hooks/useTimelineEditingDrops.ts",
-    // 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.
     "packages/studio/src/components/nle/NLEContext.tsx",
     "packages/studio/src/components/nle/PreviewPane.tsx",
     "packages/studio/src/components/nle/AssetPreviewOverlay.tsx",
@@ -446,12 +439,6 @@
     // require intrusive middleware changes beyond this PR's scope.
     "minLines": 6,
     "ignore": [
-      // TEMP(studio-dnd): coexistence-window clone (extraction vs still-live original);
-      // studio-dnd pr22 removes this with the final config.
-      "packages/studio/src/hooks/useTimelineEditing.ts",
-      // TEMP(studio-dnd): coexistence-window clone (extraction vs still-live original);
-      // studio-dnd pr22 removes this with the final config.
-      "packages/studio/src/hooks/useTimelineEditingDrops.ts",
       // TEMP(studio-dnd): coexistence-window clone (extraction vs still-live original);
       // studio-dnd pr22 removes this with the final config.
       "packages/studio/src/utils/timelineAssetDrop.ts",
@@ -631,10 +618,6 @@
     // complexity pre-dates the computed-timeline work. Exempted at file level
     // rather than refactored as scope creep.
     "ignore": [
-      // TEMP(studio-dnd): coexistence-window complexity flare (inherited/CRAP-no-coverage);
-      // removed by studio-dnd/pr22 when the final config lands.
-      "packages/studio/src/player/components/useTimelineGeometry.ts",
-      "packages/studio/src/player/components/useTimelineStackingSync.ts",
       // TEMP(studio-dnd): coexistence-window complexity flare (inherited/CRAP-no-coverage);
       // removed by studio-dnd/pr22 when the final config lands.
       "packages/studio/src/components/editor/domEditOverlayGeometry.ts",

From 84b040ce8a5b6c0b08ee31bdcd59e58669f50e07 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Sat, 11 Jul 2026 13:55:17 -0700
Subject: [PATCH 2/3] 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.
---
 .fallowrc.jsonc | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/.fallowrc.jsonc b/.fallowrc.jsonc
index e96e35e470..c6eb57fc1c 100644
--- a/.fallowrc.jsonc
+++ b/.fallowrc.jsonc
@@ -55,6 +55,13 @@
     "packages/studio/src/hooks/gsapRuntimePreview.ts",
     // 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.
+    "packages/studio/src/player/components/TimelineLanes.tsx",
+    "packages/studio/src/player/components/useTimelineStackingSync.ts",
+    "packages/studio/src/player/components/useTimelineGeometry.ts",
+    "packages/studio/src/player/components/useTimelineEditPinning.ts",
+    "packages/studio/src/hooks/useTimelineEditingDrops.ts",
+    // 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.
     "packages/studio/src/components/nle/NLEContext.tsx",
     "packages/studio/src/components/nle/PreviewPane.tsx",
     "packages/studio/src/components/nle/AssetPreviewOverlay.tsx",
@@ -439,6 +446,12 @@
     // require intrusive middleware changes beyond this PR's scope.
     "minLines": 6,
     "ignore": [
+      // TEMP(studio-dnd): coexistence-window clone (extraction vs still-live original);
+      // studio-dnd pr22 removes this with the final config.
+      "packages/studio/src/hooks/useTimelineEditing.ts",
+      // TEMP(studio-dnd): coexistence-window clone (extraction vs still-live original);
+      // studio-dnd pr22 removes this with the final config.
+      "packages/studio/src/hooks/useTimelineEditingDrops.ts",
       // TEMP(studio-dnd): coexistence-window clone (extraction vs still-live original);
       // studio-dnd pr22 removes this with the final config.
       "packages/studio/src/utils/timelineAssetDrop.ts",
@@ -618,6 +631,10 @@
     // complexity pre-dates the computed-timeline work. Exempted at file level
     // rather than refactored as scope creep.
     "ignore": [
+      // TEMP(studio-dnd): coexistence-window complexity flare (inherited/CRAP-no-coverage);
+      // removed by studio-dnd/pr22 when the final config lands.
+      "packages/studio/src/player/components/useTimelineGeometry.ts",
+      "packages/studio/src/player/components/useTimelineStackingSync.ts",
       // TEMP(studio-dnd): coexistence-window complexity flare (inherited/CRAP-no-coverage);
       // removed by studio-dnd/pr22 when the final config lands.
       "packages/studio/src/components/editor/domEditOverlayGeometry.ts",

From 412c2ebd807cc0bc744f72839a97d8f88413dbca Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Sat, 11 Jul 2026 13:55:18 -0700
Subject: [PATCH 3/3] feat(studio): canvas chrome components (unwired)

What: the canvas-side NLE chrome, unwired: DomEditSelectionChrome (rotated
selection chrome + corner handles), domEditResizeLocal (+tests, local-space
resize math), useDomEditNudge (arrow-key nudge hook), PreviewOverlays (the
canvas overlay stack for the NLE shell).

Why: the visible canvas editing layer, reviewable before the overlay swap
rewires DomEditOverlay onto it.

How: new files compiled against the coexistence layer; TEMP(studio-dnd)
entry registrations for the unwired components, removed at the app-shell
swap.

Test plan: bunx vitest run domEditResizeLocal.test.ts; tsc --noEmit; fallow
audit clean.
---
 .fallowrc.jsonc                               |  15 ++
 .../editor/DomEditSelectionChrome.tsx         | 251 +++++++++++++++++
 .../editor/domEditResizeLocal.test.ts         | 131 +++++++++
 .../components/editor/domEditResizeLocal.ts   | 113 ++++++++
 .../editor/useDomEditNudge.test.tsx           | 228 ++++++++++++++++
 .../src/components/editor/useDomEditNudge.ts  | 254 ++++++++++++++++++
 .../src/components/nle/PreviewOverlays.tsx    | 240 +++++++++++++++++
 7 files changed, 1232 insertions(+)
 create mode 100644 packages/studio/src/components/editor/DomEditSelectionChrome.tsx
 create mode 100644 packages/studio/src/components/editor/domEditResizeLocal.test.ts
 create mode 100644 packages/studio/src/components/editor/domEditResizeLocal.ts
 create mode 100644 packages/studio/src/components/editor/useDomEditNudge.test.tsx
 create mode 100644 packages/studio/src/components/editor/useDomEditNudge.ts
 create mode 100644 packages/studio/src/components/nle/PreviewOverlays.tsx

diff --git a/.fallowrc.jsonc b/.fallowrc.jsonc
index c6eb57fc1c..6a66d50816 100644
--- a/.fallowrc.jsonc
+++ b/.fallowrc.jsonc
@@ -55,6 +55,11 @@
     "packages/studio/src/hooks/gsapRuntimePreview.ts",
     // 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.
+    "packages/studio/src/components/editor/DomEditSelectionChrome.tsx",
+    "packages/studio/src/components/editor/useDomEditNudge.ts",
+    "packages/studio/src/components/nle/PreviewOverlays.tsx",
+    // 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.
     "packages/studio/src/player/components/TimelineLanes.tsx",
     "packages/studio/src/player/components/useTimelineStackingSync.ts",
     "packages/studio/src/player/components/useTimelineGeometry.ts",
@@ -446,6 +451,12 @@
     // require intrusive middleware changes beyond this PR's scope.
     "minLines": 6,
     "ignore": [
+      // TEMP(studio-dnd): coexistence-window clone (extraction vs still-live original);
+      // studio-dnd pr22 removes this with the final config.
+      "packages/studio/src/components/editor/DomEditOverlay.tsx",
+      // TEMP(studio-dnd): coexistence-window clone (extraction vs still-live original);
+      // studio-dnd pr22 removes this with the final config.
+      "packages/studio/src/components/editor/DomEditSelectionChrome.tsx",
       // TEMP(studio-dnd): coexistence-window clone (extraction vs still-live original);
       // studio-dnd pr22 removes this with the final config.
       "packages/studio/src/hooks/useTimelineEditing.ts",
@@ -631,6 +642,10 @@
     // complexity pre-dates the computed-timeline work. Exempted at file level
     // rather than refactored as scope creep.
     "ignore": [
+      // TEMP(studio-dnd): coexistence-window complexity flare (inherited/CRAP-no-coverage);
+      // removed by studio-dnd/pr22 when the final config lands.
+      "packages/studio/src/components/editor/DomEditSelectionChrome.tsx",
+      "packages/studio/src/components/editor/useDomEditNudge.ts",
       // TEMP(studio-dnd): coexistence-window complexity flare (inherited/CRAP-no-coverage);
       // removed by studio-dnd/pr22 when the final config lands.
       "packages/studio/src/player/components/useTimelineGeometry.ts",
diff --git a/packages/studio/src/components/editor/DomEditSelectionChrome.tsx b/packages/studio/src/components/editor/DomEditSelectionChrome.tsx
new file mode 100644
index 0000000000..6ecdacf137
--- /dev/null
+++ b/packages/studio/src/components/editor/DomEditSelectionChrome.tsx
@@ -0,0 +1,251 @@
+import type { RefObject } from "react";
+import { type DomEditSelection } from "./domEditing";
+import type { GroupOverlayItem, OverlayRect } from "./domEditOverlayGeometry";
+import type { BlockedMoveState, ResizeHandle } from "./domEditOverlayGestures";
+import type { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
+import { DomEditCropHandles } from "./DomEditCropHandles";
+import { DomEditRotateHandle } from "./DomEditRotateHandle";
+import { resolveRotatedResizeCursor } from "./domEditResizeLocal";
+
+// Corner resize handles, Canva-style: one per corner, diagonal cursors.
+// Corners scale about the element center; the translate keeps the center
+// planted, so they need the manual-offset capability in addition to manual-size.
+const RESIZE_HANDLE_DEFS: Array<{
+  handle: ResizeHandle;
+  cursor: string;
+  x: "left" | "right";
+  y: "top" | "bottom";
+}> = [
+  { handle: "nw", cursor: "nwse-resize", x: "left", y: "top" },
+  { handle: "ne", cursor: "nesw-resize", x: "right", y: "top" },
+  { handle: "sw", cursor: "nesw-resize", x: "left", y: "bottom" },
+  { handle: "se", cursor: "nwse-resize", x: "right", y: "bottom" },
+];
+
+// Visible dot is 9px; the pointer target is a 16px invisible square centered
+// on the corner so click targets don't shrink with the smaller dot.
+const RESIZE_HANDLE_HIT_PX = 16;
+
+type CropInset = { top: number; right: number; bottom: number; left: number };
+const NO_CROP_INSET: CropInset = { top: 0, right: 0, bottom: 0, left: 0 };
+
+function resizeHandleStyle(
+  def: (typeof RESIZE_HANDLE_DEFS)[number],
+  overlayRect: { left: number; top: number; width: number; height: number },
+  cropInset?: CropInset,
+): React.CSSProperties {
+  const half = RESIZE_HANDLE_HIT_PX / 2;
+  const inset = cropInset ?? NO_CROP_INSET;
+  const style: React.CSSProperties = { cursor: def.cursor, touchAction: "none" };
+  // Position relative to the overlay container (not the selection box).
+  // This ensures the dots render as siblings of the box border div — strictly
+  // above it — rather than as children where the parent border can visually
+  // overlap the dot circle at the corner.
+  style.left =
+    def.x === "left"
+      ? overlayRect.left + inset.left - half
+      : overlayRect.left + overlayRect.width - inset.right - half;
+  style.top =
+    def.y === "top"
+      ? overlayRect.top + inset.top - half
+      : overlayRect.top + overlayRect.height - inset.bottom - half;
+  return style;
+}
+
+type GestureHandlers = ReturnType<typeof createDomEditOverlayGestureHandlers>;
+
+interface DomEditGroupChromeProps {
+  groupOverlayItems: GroupOverlayItem[];
+  groupBounds: OverlayRect;
+  allowCanvasMovement: boolean;
+  groupCanMove: boolean;
+  gestures: GestureHandlers;
+  onBoxMouseDown: (e: React.MouseEvent) => void;
+  onBoxClick: (event: React.MouseEvent<HTMLDivElement>) => void;
+}
+
+// Multi-selection chrome: per-member outlines plus a single draggable bounding
+// box spanning the union of the members.
+export function DomEditGroupChrome({
+  groupOverlayItems,
+  groupBounds,
+  allowCanvasMovement,
+  groupCanMove,
+  gestures,
+  onBoxMouseDown,
+  onBoxClick,
+}: DomEditGroupChromeProps) {
+  return (
+    <>
+      {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={onBoxMouseDown}
+        onClick={onBoxClick}
+      />
+    </>
+  );
+}
+
+interface DomEditSelectionChromeProps {
+  selection: DomEditSelection;
+  overlayRect: OverlayRect;
+  allowCanvasMovement: boolean;
+  cropOutlineInsetPx?: { top: number; right: number; bottom: number; left: number };
+  boxRef: RefObject<HTMLDivElement | null>;
+  boxChromeClass: string;
+  boxClipPath: string | undefined;
+  selectionKey: string;
+  groupSelectionCount: number;
+  blockedMoveRef: RefObject<BlockedMoveState | null>;
+  gestures: GestureHandlers;
+  onStyleCommit?: (property: string, value: string) => Promise<void> | void;
+  onBoxMouseDown: (e: React.MouseEvent) => void;
+  onBoxClick: (event: React.MouseEvent<HTMLDivElement>) => void;
+}
+
+// Oriented selection chrome: a rotation wrapper spanning the overlay, rotated by
+// the element's live angle about the selection box CENTER. Its children (border
+// box, corner dots, rotate handle, crop pills) keep their existing
+// overlay-absolute positions — rotating the whole plane about the box center
+// lands them on the element's real transformed corners for free. At angle 0 the
+// transform is a no-op, so the chrome is pixel-identical.
+export function DomEditSelectionChrome({
+  selection,
+  overlayRect,
+  allowCanvasMovement,
+  cropOutlineInsetPx,
+  boxRef,
+  boxChromeClass,
+  boxClipPath,
+  selectionKey,
+  groupSelectionCount,
+  blockedMoveRef,
+  gestures,
+  onStyleCommit,
+  onBoxMouseDown,
+  onBoxClick,
+}: DomEditSelectionChromeProps) {
+  return (
+    <div
+      className="pointer-events-none absolute inset-0"
+      style={{
+        transformOrigin: `${overlayRect.left + overlayRect.width / 2}px ${overlayRect.top + overlayRect.height / 2}px`,
+        transform: overlayRect.angle ? `rotate(${overlayRect.angle}deg)` : undefined,
+      }}
+    >
+      {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={onBoxMouseDown}
+        onClick={onBoxClick}
+      >
+        {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,
+            }}
+          />
+        )}
+      </div>
+      {/* Resize-handle dots rendered as siblings of the selection box, not
+          children, so they paint strictly above the box border. Each handle
+          is positioned relative to the overlay container using the
+          overlayRect origin, matching the old child-relative offsets. */}
+      {allowCanvasMovement &&
+        selection.capabilities.canApplyManualSize &&
+        RESIZE_HANDLE_DEFS.map((def) =>
+          def.handle !== "se" && !selection.capabilities.canApplyManualOffset ? null : (
+            <div
+              key={def.handle}
+              className="pointer-events-auto absolute flex h-4 w-4 items-center justify-center"
+              style={{
+                ...resizeHandleStyle(def, overlayRect, cropOutlineInsetPx ?? undefined),
+                // Cursor rotates with the object: bucket the corner's base
+                // diagonal + element rotation into the 8 CSS resize cursors.
+                cursor: resolveRotatedResizeCursor(def.handle, overlayRect.angle ?? 0),
+              }}
+              onPointerDown={(e) => {
+                e.stopPropagation();
+                gestures.startGesture("resize", e, { resizeHandle: def.handle });
+              }}
+            >
+              <div className="pointer-events-none h-[12px] w-[12px] rounded-full border-[1.5px] border-studio-accent bg-white shadow-[0_0_3px_rgba(0,0,0,0.45)]" />
+            </div>
+          ),
+        )}
+      {selection.capabilities.canCrop && groupSelectionCount <= 1 && (
+        <DomEditCropHandles
+          selection={selection}
+          overlayRect={overlayRect}
+          onStyleCommit={onStyleCommit}
+        />
+      )}
+    </div>
+  );
+}
diff --git a/packages/studio/src/components/editor/domEditResizeLocal.test.ts b/packages/studio/src/components/editor/domEditResizeLocal.test.ts
new file mode 100644
index 0000000000..8842b61f17
--- /dev/null
+++ b/packages/studio/src/components/editor/domEditResizeLocal.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveCenterResizeScale,
+  resolveCenterResizeSize,
+  resolveRotatedResizeCursor,
+} from "./domEditResizeLocal";
+
+const DEG = Math.PI / 180;
+
+describe("resolveCenterResizeScale — radial distance from the center", () => {
+  it("scale is the ratio of pointer-to-center distances", () => {
+    // start 100px from center, now 150px from center → 1.5x.
+    expect(
+      resolveCenterResizeScale({
+        centerStart: { x: 100, y: 100 },
+        pointerStart: { x: 200, y: 100 },
+        pointer: { x: 250, y: 100 },
+      }),
+    ).toBeCloseTo(1.5, 9);
+  });
+
+  it("shrinks as the pointer moves toward the center", () => {
+    expect(
+      resolveCenterResizeScale({
+        centerStart: { x: 0, y: 0 },
+        pointerStart: { x: 0, y: 200 },
+        pointer: { x: 0, y: 50 },
+      }),
+    ).toBeCloseTo(0.25, 9);
+  });
+
+  it("bails to 1 when the gesture starts at (or ~at) the center (degenerate)", () => {
+    expect(
+      resolveCenterResizeScale({
+        centerStart: { x: 100, y: 100 },
+        pointerStart: { x: 101, y: 100 },
+        pointer: { x: 400, y: 400 },
+      }),
+    ).toBe(1);
+  });
+});
+
+describe("resolveCenterResizeSize — rotation is a non-event (radial distance)", () => {
+  // The pure function takes no rotation argument: rotating the WHOLE gesture
+  // (center, pointer-down, pointer-now) about the center by any angle preserves
+  // every radial distance, so the returned size is identical at 0/37/90deg.
+  const base = { baseWidth: 240, baseHeight: 120 };
+  const centerStart = { x: 320, y: 180 };
+  // A pointer-down 100px right of center, dragged to 160px right of center (1.6x).
+  const p0 = { x: 100, y: 0 };
+  const p1 = { x: 160, y: 0 };
+  const rot = (v: { x: number; y: number }, t: number) => ({
+    x: centerStart.x + (Math.cos(t) * v.x - Math.sin(t) * v.y),
+    y: centerStart.y + (Math.sin(t) * v.x + Math.cos(t) * v.y),
+  });
+
+  for (const deg of [0, 37, 90]) {
+    it(`@${deg}deg: proportional 1.6x scale, same result as unrotated`, () => {
+      const t = deg * DEG;
+      const out = resolveCenterResizeSize({
+        ...base,
+        centerStart,
+        pointerStart: rot(p0, t),
+        pointer: rot(p1, t),
+      });
+      expect(out.width).toBeCloseTo(240 * 1.6, 6);
+      expect(out.height).toBeCloseTo(120 * 1.6, 6);
+      expect(out.width / out.height).toBeCloseTo(2, 9);
+    });
+  }
+
+  it("shrink toward center keeps the aspect ratio", () => {
+    const out = resolveCenterResizeSize({
+      baseWidth: 300,
+      baseHeight: 180,
+      centerStart: { x: 0, y: 0 },
+      pointerStart: { x: 0, y: 200 },
+      pointer: { x: 0, y: 120 },
+    });
+    expect(out.width).toBeCloseTo(300 * 0.6, 6);
+    expect(out.height).toBeCloseTo(180 * 0.6, 6);
+    expect(out.width / out.height).toBeCloseTo(300 / 180, 9);
+  });
+
+  it("clamps at the local minimum, never mirroring through zero (drag past center)", () => {
+    // Pointer dragged to the exact center → raw scale 0; the smaller edge is
+    // clamped to MIN_RESIZE_LOCAL_PX and the aspect ratio holds at the clamp.
+    const out = resolveCenterResizeSize({
+      baseWidth: 200,
+      baseHeight: 100,
+      centerStart: { x: 100, y: 100 },
+      pointerStart: { x: 200, y: 100 },
+      pointer: { x: 100, y: 100 },
+    });
+    expect(out.width).toBeGreaterThan(0);
+    expect(out.height).toBeGreaterThan(0);
+    expect(Math.min(out.width, out.height)).toBeCloseTo(1, 9);
+    expect(out.width / out.height).toBeCloseTo(2, 9);
+  });
+
+  it("degenerate start-at-center returns the base size unchanged (scale 1)", () => {
+    const out = resolveCenterResizeSize({
+      baseWidth: 200,
+      baseHeight: 100,
+      centerStart: { x: 100, y: 100 },
+      pointerStart: { x: 100, y: 100 },
+      pointer: { x: 400, y: 400 },
+    });
+    expect(out).toEqual({ width: 200, height: 100 });
+  });
+});
+
+describe("resolveRotatedResizeCursor", () => {
+  it("returns the static diagonal cursors at rotation 0", () => {
+    expect(resolveRotatedResizeCursor("nw", 0)).toBe("nwse-resize");
+    expect(resolveRotatedResizeCursor("se", 0)).toBe("nwse-resize");
+    expect(resolveRotatedResizeCursor("ne", 0)).toBe("nesw-resize");
+    expect(resolveRotatedResizeCursor("sw", 0)).toBe("nesw-resize");
+  });
+
+  it("rotates the cursor with the element (90deg swaps the diagonals)", () => {
+    // NW base 315° + 90° = 45° → nesw-resize
+    expect(resolveRotatedResizeCursor("nw", 90)).toBe("nesw-resize");
+    // NW base 315° + 45° = 360°→0° → ns-resize
+    expect(resolveRotatedResizeCursor("nw", 45)).toBe("ns-resize");
+  });
+
+  it("wraps negative rotations", () => {
+    expect(resolveRotatedResizeCursor("se", -90)).toBe("nesw-resize");
+  });
+});
diff --git a/packages/studio/src/components/editor/domEditResizeLocal.ts b/packages/studio/src/components/editor/domEditResizeLocal.ts
new file mode 100644
index 0000000000..3aa1b209a2
--- /dev/null
+++ b/packages/studio/src/components/editor/domEditResizeLocal.ts
@@ -0,0 +1,113 @@
+/**
+ * Center-anchored corner-resize math (the CapCut model): the element scales
+ * proportionally about its CENTER, the center stays planted, and all four corners
+ * behave identically.
+ *
+ * The scale factor is the RADIAL distance from the element's center: how far the
+ * pointer is from the center now, divided by how far it was at gesture start. This
+ * is inherently proportional, continuous everywhere, and rotation-invariant — a
+ * distance is a distance regardless of the element's angle, so there is no per-axis
+ * projection and no dominant-axis branch to jump across. Which corner was grabbed
+ * is irrelevant to the size (it only picks the resize cursor).
+ *
+ * All math here is pure and unit-tested; the live wiring (measuring the element's
+ * rendered center, feeding the center-pin translate through the manual-offset
+ * channel) lives in useDomEditOverlayGestures.ts.
+ */
+import type { ResizeHandle } from "./domEditOverlayGestures";
+
+/** Minimum element edge in LOCAL px — mirrors the old MIN_RESIZE_EDGE_PX clamp
+ *  (no flip-through-zero: clamp, never mirror). */
+const MIN_RESIZE_LOCAL_PX = 1;
+
+/**
+ * Below this pointer-to-center distance (overlay px) the gesture started at (or
+ * effectively at) the center, so the ratio is degenerate (division by ~0). Bail to
+ * scale 1 rather than blow up.
+ */
+const DEGENERATE_START_DIST_PX = 3;
+
+/**
+ * The proportional scale factor for a center-anchored resize: the ratio of the
+ * pointer's radial distance from the element center now to its distance at gesture
+ * start. Rotation-invariant (a radial distance ignores the element's angle) and
+ * continuous. Never negative — dragging through the center just shrinks toward the
+ * clamp; the caller clamps the resulting size, this returns the raw ratio (guarded
+ * against a degenerate start-at-center gesture, which returns 1).
+ */
+export function resolveCenterResizeScale(input: {
+  pointer: { x: number; y: number };
+  pointerStart: { x: number; y: number };
+  centerStart: { x: number; y: number };
+}): number {
+  const startDist = Math.hypot(
+    input.pointerStart.x - input.centerStart.x,
+    input.pointerStart.y - input.centerStart.y,
+  );
+  if (!Number.isFinite(startDist) || startDist < DEGENERATE_START_DIST_PX) return 1;
+  const nowDist = Math.hypot(
+    input.pointer.x - input.centerStart.x,
+    input.pointer.y - input.centerStart.y,
+  );
+  return nowDist / startDist;
+}
+
+/**
+ * The element's new LOCAL size for a center-anchored corner resize: base size
+ * scaled by `resolveCenterResizeScale`, clamped so the smaller edge never drops
+ * below MIN_RESIZE_LOCAL_PX (clamp small, never mirror through zero). The scale is
+ * a dimensionless ratio, so the base local size and the screen-space pointer
+ * distances live in different frames without any display-scale conversion — the
+ * ratio cancels the scale.
+ */
+export function resolveCenterResizeSize(input: {
+  baseWidth: number;
+  baseHeight: number;
+  pointer: { x: number; y: number };
+  pointerStart: { x: number; y: number };
+  centerStart: { x: number; y: number };
+}): { width: number; height: number } {
+  const baseWidth = Math.max(input.baseWidth, MIN_RESIZE_LOCAL_PX);
+  const baseHeight = Math.max(input.baseHeight, MIN_RESIZE_LOCAL_PX);
+  const rawScale = resolveCenterResizeScale({
+    pointer: input.pointer,
+    pointerStart: input.pointerStart,
+    centerStart: input.centerStart,
+  });
+  const minScale = MIN_RESIZE_LOCAL_PX / Math.min(baseWidth, baseHeight);
+  const scale = Math.max(minScale, rawScale);
+  return { width: baseWidth * scale, height: baseHeight * scale };
+}
+
+/**
+ * The eight CSS resize cursors, rotated with the object. A corner's base pointing
+ * direction (the diagonal it lives on) plus the element rotation, bucketed into
+ * 45° slots. So a 90°-rotated NW corner reads as a NE-diagonal cursor, etc.
+ */
+const CURSORS_8 = [
+  "ns-resize", // 0°   (up)
+  "nesw-resize", // 45°
+  "ew-resize", // 90°  (right)
+  "nwse-resize", // 135°
+  "ns-resize", // 180° (down)
+  "nesw-resize", // 225°
+  "ew-resize", // 270° (left)
+  "nwse-resize", // 315°
+] as const;
+
+/** Base outward diagonal angle of each corner, in degrees, screen convention
+ *  (0° = up, clockwise). NW points up-left = 315°, NE up-right = 45°, etc. */
+const CORNER_BASE_ANGLE_DEG: Record<ResizeHandle, number> = {
+  nw: 315,
+  ne: 45,
+  se: 135,
+  sw: 225,
+};
+
+/** Resize cursor for a corner handle on an element rotated by `rotationDeg`. */
+export function resolveRotatedResizeCursor(handle: ResizeHandle, rotationDeg: number): string {
+  const angle = CORNER_BASE_ANGLE_DEG[handle] + rotationDeg;
+  const normalized = ((angle % 360) + 360) % 360;
+  const bucket = Math.round(normalized / 45) % 8;
+  return CURSORS_8[bucket]!;
+}
diff --git a/packages/studio/src/components/editor/useDomEditNudge.test.tsx b/packages/studio/src/components/editor/useDomEditNudge.test.tsx
new file mode 100644
index 0000000000..9d7265f7a3
--- /dev/null
+++ b/packages/studio/src/components/editor/useDomEditNudge.test.tsx
@@ -0,0 +1,228 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { installReactActEnvironment, makeSelection } from "../../hooks/domSelectionTestHarness";
+import { useDomEditNudge, type UseDomEditNudgeParams } from "./useDomEditNudge";
+import { CANVAS_NUDGE_COMMIT_DEBOUNCE_MS, CANVAS_NUDGE_STEP_PX } from "./domEditNudge";
+import { __resetForTests } from "../../utils/canvasNudgeGate";
+import type { DomEditSelection } from "./domEditing";
+import type { OverlayRect } from "./domEditOverlayGeometry";
+
+installReactActEnvironment();
+
+function makeRef<T>(current: T): { current: T } {
+  return { current };
+}
+
+const REST_RECT: OverlayRect = {
+  left: 0,
+  top: 0,
+  width: 100,
+  height: 50,
+  editScaleX: 1,
+  editScaleY: 1,
+};
+
+// Stable across renders on purpose: the test targets the `selection` identity
+// key specifically, so `groupSelections` must not itself be a source of churn.
+const EMPTY_GROUP_SELECTIONS: DomEditSelection[] = [];
+
+function Harness({
+  selection,
+  onPathOffsetCommit,
+}: {
+  selection: DomEditSelection | null;
+  onPathOffsetCommit: UseDomEditNudgeParams["onPathOffsetCommitRef"]["current"];
+}) {
+  useDomEditNudge({
+    selection,
+    groupSelections: EMPTY_GROUP_SELECTIONS,
+    allowCanvasMovement: true,
+    selectionRef: makeRef(selection),
+    overlayRectRef: makeRef(REST_RECT),
+    groupOverlayItemsRef: makeRef([]),
+    gestureRef: makeRef(null),
+    groupGestureRef: makeRef(null),
+    blockedMoveRef: makeRef(null),
+    onManualDragStartRef: makeRef(() => {}),
+    onPathOffsetCommitRef: makeRef(onPathOffsetCommit),
+    onGroupPathOffsetCommitRef: makeRef(async () => {}),
+  });
+  return null;
+}
+
+function dispatchArrowRight(): void {
+  window.dispatchEvent(
+    new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true, cancelable: true }),
+  );
+}
+
+describe("useDomEditNudge — selection cleanup keyed on stable identity", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    __resetForTests();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("keeps a nudge burst alive when the parent hands down a new selection object for the same element", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    const element = document.createElement("div");
+    element.id = "dot-a";
+    document.body.append(element);
+
+    const commit = vi.fn();
+    const firstSelection = makeSelection("Dot", element);
+
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: firstSelection, onPathOffsetCommit: commit }),
+      );
+    });
+
+    act(() => {
+      dispatchArrowRight();
+    });
+    expect(commit).not.toHaveBeenCalled();
+
+    // Re-render with a BRAND NEW selection object describing the SAME element
+    // (same id) — exactly what an un-memoized parent does on every render.
+    // Before the fix, the cleanup effect was keyed on this object's identity
+    // and would flush the burst right here, one arrow-press early.
+    const secondSelection = makeSelection("Dot", element);
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: secondSelection, onPathOffsetCommit: commit }),
+      );
+    });
+    expect(commit).not.toHaveBeenCalled();
+
+    act(() => {
+      dispatchArrowRight();
+    });
+    expect(commit).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(CANVAS_NUDGE_COMMIT_DEBOUNCE_MS + 10);
+    });
+
+    // One combined commit for both presses, not two separate (premature) ones.
+    expect(commit).toHaveBeenCalledTimes(1);
+    const [, next] = commit.mock.calls[0] as [DomEditSelection, { x: number; y: number }];
+    expect(next.x).toBeCloseTo(2 * CANVAS_NUDGE_STEP_PX);
+    expect(next.y).toBeCloseTo(0);
+
+    act(() => root.unmount());
+    host.remove();
+    element.remove();
+  });
+
+  it("still flushes the burst when the selection actually changes to a different element", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    const elementA = document.createElement("div");
+    elementA.id = "dot-a";
+    document.body.append(elementA);
+    const elementB = document.createElement("div");
+    elementB.id = "dot-b";
+    document.body.append(elementB);
+
+    const commit = vi.fn();
+    const selectionA = makeSelection("Dot A", elementA);
+    const selectionB = makeSelection("Dot B", elementB);
+
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: selectionA, onPathOffsetCommit: commit }),
+      );
+    });
+
+    act(() => {
+      dispatchArrowRight();
+    });
+    expect(commit).not.toHaveBeenCalled();
+
+    // A genuine selection change (different id) must still flush immediately —
+    // only same-identity re-renders should be ignored.
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: selectionB, onPathOffsetCommit: commit }),
+      );
+    });
+    expect(commit).toHaveBeenCalledTimes(1);
+    const [committedSelection, next] = commit.mock.calls[0] as [
+      DomEditSelection,
+      { x: number; y: number },
+    ];
+    expect(committedSelection.element).toBe(elementA);
+    expect(next.x).toBeCloseTo(CANVAS_NUDGE_STEP_PX);
+
+    act(() => root.unmount());
+    host.remove();
+    elementA.remove();
+    elementB.remove();
+  });
+
+  it("flushes the burst when switching between two id-less siblings that share a selector", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    // Two id-less siblings with the SAME selector — distinguished only by
+    // selectorIndex. Under the old `id ?? selector ?? label` key they shared
+    // one identity, so selecting B mid-burst didn't flush A and the next arrow
+    // kept moving A. The key now folds in selectorIndex, so they're distinct.
+    const elementA = document.createElement("div");
+    document.body.append(elementA);
+    const elementB = document.createElement("div");
+    document.body.append(elementB);
+
+    const commit = vi.fn();
+    const base = (label: string, element: HTMLElement) => ({
+      ...makeSelection(label, element),
+      id: undefined,
+      selector: "div.row",
+    });
+    const selectionA: DomEditSelection = { ...base("Row", elementA), selectorIndex: 0 };
+    const selectionB: DomEditSelection = { ...base("Row", elementB), selectorIndex: 1 };
+
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: selectionA, onPathOffsetCommit: commit }),
+      );
+    });
+
+    act(() => {
+      dispatchArrowRight();
+    });
+    expect(commit).not.toHaveBeenCalled();
+
+    act(() => {
+      root.render(
+        React.createElement(Harness, { selection: selectionB, onPathOffsetCommit: commit }),
+      );
+    });
+
+    // The sibling switch must flush A's pending burst exactly once, for A.
+    expect(commit).toHaveBeenCalledTimes(1);
+    const [committedSelection, next] = commit.mock.calls[0] as [
+      DomEditSelection,
+      { x: number; y: number },
+    ];
+    expect(committedSelection.element).toBe(elementA);
+    expect(next.x).toBeCloseTo(CANVAS_NUDGE_STEP_PX);
+
+    act(() => root.unmount());
+    host.remove();
+    elementA.remove();
+    elementB.remove();
+  });
+});
diff --git a/packages/studio/src/components/editor/useDomEditNudge.ts b/packages/studio/src/components/editor/useDomEditNudge.ts
new file mode 100644
index 0000000000..dc7e5993fc
--- /dev/null
+++ b/packages/studio/src/components/editor/useDomEditNudge.ts
@@ -0,0 +1,254 @@
+/**
+ * Canvas arrow-key nudge for DomEditOverlay: arrows move the selected
+ * element(s) 1 composition px, Shift = 10. Each keypress previews through the
+ * same GSAP/CSS channel as a drag draft, and the burst commits ONCE through
+ * the same onPathOffsetCommit / onGroupPathOffsetCommit path a drag drop uses
+ * — so a nudge burst is exactly a tiny drag: one source patch, one undo entry.
+ */
+import { useCallback, useEffect, useRef, type RefObject } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
+import { isEditableTarget } from "../../utils/timelineDiscovery";
+import { acquireCanvasNudgeKeys } from "../../utils/canvasNudgeGate";
+import type { DomEditSelection } from "./domEditing";
+import {
+  type GroupOverlayItem,
+  type OverlayRect,
+  filterNestedDomEditGroupItems,
+} from "./domEditOverlayGeometry";
+import type {
+  BlockedMoveState,
+  DomEditGroupPathOffsetCommit,
+  GestureState,
+  GroupGestureState,
+} from "./domEditOverlayGestures";
+import {
+  applyManualOffsetNudgeCommit,
+  applyManualOffsetNudgeDraft,
+  createManualOffsetDragMember,
+  endManualOffsetDragMembers,
+  restoreManualOffsetDragMembers,
+  type ManualOffsetDragMember,
+} from "./manualOffsetDrag";
+import { isStudioManualEditGestureCurrent, restoreStudioPathOffset } from "./manualEdits";
+import {
+  CANVAS_NUDGE_COMMIT_DEBOUNCE_MS,
+  canCanvasNudgeTargets,
+  resolveCanvasNudgeDelta,
+} from "./domEditNudge";
+
+interface NudgeSession {
+  members: ManualOffsetDragMember[];
+  isGroup: boolean;
+  /** Accumulated delta of the burst, in composition px. */
+  accum: { x: number; y: number };
+  timer: ReturnType<typeof setTimeout> | null;
+}
+
+export interface UseDomEditNudgeParams {
+  selection: DomEditSelection | null;
+  groupSelections: DomEditSelection[];
+  allowCanvasMovement: boolean;
+  selectionRef: RefObject<DomEditSelection | null>;
+  overlayRectRef: RefObject<OverlayRect | null>;
+  groupOverlayItemsRef: RefObject<GroupOverlayItem[]>;
+  gestureRef: RefObject<GestureState | null>;
+  groupGestureRef: RefObject<GroupGestureState | null>;
+  blockedMoveRef: RefObject<BlockedMoveState | null>;
+  onManualDragStartRef: RefObject<(() => void) | undefined>;
+  onPathOffsetCommitRef: RefObject<
+    (
+      s: DomEditSelection,
+      n: { x: number; y: number },
+      m?: { altKey?: boolean },
+    ) => Promise<void> | void
+  >;
+  onGroupPathOffsetCommitRef: RefObject<
+    (updates: DomEditGroupPathOffsetCommit[]) => Promise<void> | void
+  >;
+}
+
+type NudgeTarget = {
+  key: string;
+  selection: DomEditSelection;
+  element: HTMLElement;
+  rect: OverlayRect;
+};
+
+/**
+ * A selection's stable identity, not its object reference. A parent that
+ * doesn't memoize the selection it passes down hands us a new object every
+ * render for the SAME element — keying an effect on the object itself would
+ * then re-fire on every render instead of on an actual selection change.
+ *
+ * All discriminators are folded in (id / hfId / selector / selectorIndex /
+ * label), not just the first present one: two id-less siblings can share a
+ * selector, so `id ?? selector ?? label` collapsed them to the same key —
+ * selecting sibling B mid-burst then didn't flush A's pending nudge, so the
+ * next arrow kept moving A. selectorIndex is the discriminator that separates
+ * them. The parts are only ever compared for equality (never parsed back),
+ * so they're joined on a NUL delimiter — a byte no discriminator can contain,
+ * so distinct selections stay distinct even when a value (e.g. a label) holds
+ * a space. It's written as the escape "\u0000", not a literal 0x00 byte, so
+ * this source file stays text (a raw NUL makes git treat it as binary).
+ */
+function selectionIdentityKey(selection: DomEditSelection | null): string {
+  if (!selection) return "";
+  return [
+    selection.id ?? "",
+    selection.hfId ?? "",
+    selection.selector ?? "",
+    selection.selectorIndex ?? "",
+    selection.label,
+  ].join("\u0000");
+}
+
+function groupSelectionsIdentityKey(selections: DomEditSelection[]): string {
+  return selections.map(selectionIdentityKey).join(" ");
+}
+
+/** Drag members for a multi-selection nudge (same snapshot a group drag uses). */
+function resolveGroupNudgeTargets(groupItems: GroupOverlayItem[]): NudgeTarget[] | null {
+  if (!canCanvasNudgeTargets(groupItems.map((item) => item.selection))) return null;
+  return filterNestedDomEditGroupItems(groupItems);
+}
+
+/** Drag member for a single-selection nudge, or null when it can't be moved. */
+function resolveSingleNudgeTarget(
+  sel: DomEditSelection | null,
+  rect: OverlayRect | null,
+): NudgeTarget[] | null {
+  if (!sel || !rect || !sel.capabilities.canApplyManualOffset || !sel.element.isConnected) {
+    return null;
+  }
+  return [{ key: sel.id ?? sel.selector ?? sel.label, selection: sel, element: sel.element, rect }];
+}
+
+/**
+ * True when a keydown must not start/extend a nudge: canvas movement disabled,
+ * a pointer gesture already owns the element, or the user is typing in a field.
+ */
+function shouldIgnoreNudgeKey(p: UseDomEditNudgeParams, event: KeyboardEvent): boolean {
+  if (!p.allowCanvasMovement || event.defaultPrevented) return true;
+  if (p.gestureRef.current || p.groupGestureRef.current || p.blockedMoveRef.current) return true;
+  return isEditableTarget(event.target);
+}
+
+export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: () => void } {
+  const sessionRef = useRef<NudgeSession | null>(null);
+  const paramsRef = useRef(params);
+  paramsRef.current = params;
+
+  // Commit the pending burst: one source write per burst = one undo entry.
+  // Mirrors the drag's onPointerUp — same commit callbacks, same failure
+  // restore, same member teardown.
+  const commitSession = () => {
+    const session = sessionRef.current;
+    if (!session) return;
+    sessionRef.current = null;
+    if (session.timer) clearTimeout(session.timer);
+    const updates: DomEditGroupPathOffsetCommit[] = session.members.map((member) => ({
+      selection: member.selection,
+      next: applyManualOffsetNudgeCommit(member, session.accum),
+    }));
+    const p = paramsRef.current;
+    const commit = session.isGroup
+      ? p.onGroupPathOffsetCommitRef.current(updates)
+      : p.onPathOffsetCommitRef.current(updates[0].selection, updates[0].next);
+    void Promise.resolve(commit)
+      .catch(() => {
+        for (const member of session.members) {
+          if (isStudioManualEditGestureCurrent(member.element, member.gestureToken)) {
+            restoreStudioPathOffset(member.element, member.initialPathOffset);
+          }
+        }
+      })
+      .finally(() => endManualOffsetDragMembers(session.members));
+  };
+  const commitSessionRef = useRef(commitSession);
+  commitSessionRef.current = commitSession;
+
+  // Build drag members for the current target set — the same member snapshot a
+  // pointer drag starts from (startGesture / startGroupDrag), so the nudge
+  // commit converts offsets → GSAP x/y with identical math.
+  const beginSession = (): NudgeSession | null => {
+    const p = paramsRef.current;
+    const groupItems = p.groupOverlayItemsRef.current;
+    const isGroup = groupItems.length > 1;
+    const targets = isGroup
+      ? resolveGroupNudgeTargets(groupItems)
+      : resolveSingleNudgeTarget(p.selectionRef.current, p.overlayRectRef.current);
+    if (!targets) return null;
+    const members: ManualOffsetDragMember[] = [];
+    for (const target of targets) {
+      const result = createManualOffsetDragMember(target);
+      if (!result.ok) {
+        restoreManualOffsetDragMembers(members);
+        return null;
+      }
+      members.push(result.member);
+    }
+    if (members.length === 0) return null;
+    // Same side effect a drag start has (pauses preview playback).
+    p.onManualDragStartRef.current?.();
+    return { members, isGroup, accum: { x: 0, y: 0 }, timer: null };
+  };
+
+  const handleKeyDown = (event: KeyboardEvent) => {
+    const p = paramsRef.current;
+    if (shouldIgnoreNudgeKey(p, event)) return;
+    const delta = resolveCanvasNudgeDelta(event);
+    if (!delta) return;
+    const session = sessionRef.current ?? beginSession();
+    if (!session) return;
+    sessionRef.current = session;
+    event.preventDefault();
+    session.accum = { x: session.accum.x + delta.dx, y: session.accum.y + delta.dy };
+    for (const member of session.members) applyManualOffsetNudgeDraft(member, session.accum);
+    if (session.timer) clearTimeout(session.timer);
+    session.timer = setTimeout(() => commitSessionRef.current(), CANVAS_NUDGE_COMMIT_DEBOUNCE_MS);
+  };
+  const handleKeyDownRef = useRef(handleKeyDown);
+  handleKeyDownRef.current = handleKeyDown;
+
+  useMountEffect(() => {
+    const listener = (event: KeyboardEvent) => handleKeyDownRef.current(event);
+    // Capture, like the other app-level key handlers, so a focused panel
+    // can't swallow the nudge before it reaches us.
+    window.addEventListener("keydown", listener, true);
+    return () => {
+      window.removeEventListener("keydown", listener, true);
+      commitSessionRef.current();
+    };
+  });
+
+  // Selection change ends the burst: commit to the OLD target before the
+  // arrows start moving the new one. Keyed on the selection's stable identity
+  // (id/selector/label), NOT the object reference — a parent that re-creates
+  // the selection object on every render (without memoizing it) must not
+  // flush a burst that's still in progress for the same element.
+  const selectionKey = selectionIdentityKey(params.selection);
+  const groupSelectionsKey = groupSelectionsIdentityKey(params.groupSelections);
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => () => commitSessionRef.current(), [selectionKey, groupSelectionsKey]);
+
+  // Claim the arrow keys from the playback frame-step while the selection is
+  // nudgeable (see canvasNudgeGate — listener order is mount-dependent, so
+  // preventDefault alone can't arbitrate).
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    const targets =
+      params.groupSelections.length > 1
+        ? params.groupSelections
+        : params.selection
+          ? [params.selection]
+          : [];
+    if (!params.allowCanvasMovement || !canCanvasNudgeTargets(targets)) return;
+    return acquireCanvasNudgeKeys();
+  }, [params.selection, params.groupSelections, params.allowCanvasMovement]);
+
+  // A pointer gesture supersedes a pending burst — DomEditOverlay flushes on
+  // pointerdown-capture so the drag's member snapshot starts from the nudged,
+  // committed position.
+  const flushNudge = useCallback(() => commitSessionRef.current(), []);
+  return { flushNudge };
+}
diff --git a/packages/studio/src/components/nle/PreviewOverlays.tsx b/packages/studio/src/components/nle/PreviewOverlays.tsx
new file mode 100644
index 0000000000..36b67748a3
--- /dev/null
+++ b/packages/studio/src/components/nle/PreviewOverlays.tsx
@@ -0,0 +1,240 @@
+import { useState } from "react";
+import { CaptionOverlay } from "../../captions/components/CaptionOverlay";
+import { DomEditOverlay } from "../editor/DomEditOverlay";
+import { MotionPathOverlay } from "../editor/MotionPathOverlay";
+import { SnapToolbar } from "../editor/SnapToolbar";
+import { useCompositionDimensions } from "../../hooks/useCompositionDimensions";
+import {
+  STUDIO_INSPECTOR_PANELS_ENABLED,
+  STUDIO_KEYFRAMES_ENABLED,
+  STUDIO_PREVIEW_MANUAL_EDITING_ENABLED,
+  STUDIO_PREVIEW_SELECTION_ENABLED,
+} from "../editor/manualEditingAvailability";
+import { useStudioPlaybackContext, useStudioShellContext } from "../../contexts/StudioContext";
+import {
+  useDomEditActionsContext,
+  useDomEditSelectionContext,
+} from "../../contexts/DomEditContext";
+import { readStudioUiPreferences } from "../../utils/studioUiPreferences";
+import { readHfId, type DomEditSelection } from "../editor/domEditing";
+import { buildStableSelector } from "../editor/domEditingDom";
+import type { BlockPreviewInfo } from "../sidebar/BlocksTab";
+import type { GestureRecordingState } from "../editor/GestureRecordControl";
+import type { ReactNode } from "react";
+
+export interface PreviewOverlaysProps {
+  shouldShowSelectedDomBounds: boolean;
+  blockPreview?: BlockPreviewInfo | null;
+  isGestureRecording?: boolean;
+  recordingState?: GestureRecordingState;
+  onToggleRecording?: () => void;
+  gestureOverlay?: ReactNode;
+}
+
+type ZIndexReorderEntry = {
+  element: HTMLElement;
+  zIndex: number;
+  id?: string;
+  selector?: string;
+  selectorIndex?: number;
+  sourceFile: string;
+};
+
+/** Can this element be robustly re-targeted for a persisted z change? */
+function canTargetZIndexElement(
+  element: HTMLElement,
+  id: string | undefined,
+  selector: string | undefined,
+): boolean {
+  return Boolean(id || selector || readHfId(element));
+}
+
+/** The selected element carries its full selection identity. */
+function selectedZIndexEntry(sel: DomEditSelection, zIndex: number): ZIndexReorderEntry {
+  return {
+    element: sel.element,
+    zIndex,
+    id: sel.id ?? undefined,
+    selector: sel.selector,
+    selectorIndex: sel.selectorIndex,
+    sourceFile: sel.sourceFile,
+  };
+}
+
+/**
+ * Sibling elements are raw iframe DOM nodes with no selection object: derive a
+ * PatchTarget from the node itself (siblings live in the same document, so they
+ * share the selection's sourceFile). Null when it cannot be robustly targeted
+ * (no id and no selector) — its z stays live-only.
+ */
+function siblingZIndexEntry(
+  element: HTMLElement,
+  zIndex: number,
+  sourceFile: string,
+): ZIndexReorderEntry | null {
+  const id = element.id || undefined;
+  const selector = buildStableSelector(element);
+  if (!canTargetZIndexElement(element, id, selector)) return null;
+  return { element, zIndex, id, selector, selectorIndex: undefined, sourceFile };
+}
+
+/** Short human-readable label for a dropped sibling, for the console warning below. */
+function describeZIndexElement(element: HTMLElement): string {
+  if (element.id) return `#${element.id}`;
+  const firstClass = element.classList.item(0);
+  return firstClass
+    ? `${element.tagName.toLowerCase()}.${firstClass}`
+    : element.tagName.toLowerCase();
+}
+
+// Resolve z-index patches into commit entries; a sibling with no stable
+// id/selector can't be written to source, so it is collected as a label for the
+// revert-on-reload warning instead.
+function resolveZIndexEntries(
+  sel: DomEditSelection,
+  patches: ReadonlyArray<{ element: HTMLElement; zIndex: number }>,
+): { entries: ZIndexReorderEntry[]; droppedLabels: string[] } {
+  const entries: ZIndexReorderEntry[] = [];
+  const droppedLabels: string[] = [];
+  for (const patch of patches) {
+    if (patch.element === sel.element) {
+      entries.push(selectedZIndexEntry(sel, patch.zIndex));
+      continue;
+    }
+    const entry = siblingZIndexEntry(patch.element, patch.zIndex, sel.sourceFile);
+    if (entry) entries.push(entry);
+    else droppedLabels.push(describeZIndexElement(patch.element));
+  }
+  return { entries, droppedLabels };
+}
+
+// fallow-ignore-next-line complexity
+export function PreviewOverlays({
+  shouldShowSelectedDomBounds,
+  blockPreview,
+  isGestureRecording,
+  recordingState,
+  onToggleRecording,
+  gestureOverlay,
+}: PreviewOverlaysProps) {
+  const { activeCompPath, previewIframeRef } = useStudioShellContext();
+  const { captionEditMode, compositionLoading, isPlaying } = useStudioPlaybackContext();
+  const compositionDimensions = useCompositionDimensions();
+
+  const { domEditHoverSelection, domEditSelection, domEditGroupSelections } =
+    useDomEditSelectionContext();
+  const {
+    handlePreviewCanvasMouseDown,
+    handlePreviewCanvasPointerMove,
+    handlePreviewCanvasPointerLeave,
+    applyDomSelection,
+    handleBlockedDomMove,
+    handleDomManualDragStart,
+    handleDomPathOffsetCommit,
+    handleDomGroupPathOffsetCommit,
+    handleDomBoxSizeCommit,
+    handleDomRotationCommit,
+    handleDomStyleCommit,
+    applyMarqueeSelection,
+    handleDomEditElementDelete,
+    handleDomZIndexReorderCommit,
+  } = useDomEditActionsContext();
+
+  // fallow-ignore-next-line complexity
+  const [snapPrefs, setSnapPrefs] = useState(() => {
+    const p = readStudioUiPreferences();
+    return {
+      snapEnabled: p.snapEnabled ?? true,
+      gridVisible: p.gridVisible ?? false,
+      gridSpacing: p.gridSpacing ?? 50,
+      snapToGrid: p.snapToGrid ?? false,
+    };
+  });
+
+  if (blockPreview) {
+    return (
+      <div className="absolute inset-0 z-30 bg-black pointer-events-none">
+        {blockPreview.videoUrl ? (
+          <video
+            src={blockPreview.videoUrl}
+            autoPlay
+            muted
+            loop
+            playsInline
+            className="w-full h-full object-contain"
+          />
+        ) : blockPreview.posterUrl ? (
+          <img
+            src={blockPreview.posterUrl}
+            alt={blockPreview.title}
+            className="w-full h-full object-contain"
+          />
+        ) : null}
+      </div>
+    );
+  }
+
+  if (captionEditMode) {
+    return <CaptionOverlay iframeRef={previewIframeRef} />;
+  }
+
+  if (!STUDIO_INSPECTOR_PANELS_ENABLED) return null;
+
+  return (
+    <>
+      <DomEditOverlay
+        iframeRef={previewIframeRef}
+        activeCompositionPath={activeCompPath}
+        hoverSelection={
+          STUDIO_PREVIEW_SELECTION_ENABLED && !captionEditMode && !compositionLoading && !isPlaying
+            ? domEditHoverSelection
+            : null
+        }
+        selection={shouldShowSelectedDomBounds ? domEditSelection : null}
+        groupSelections={shouldShowSelectedDomBounds ? domEditGroupSelections : []}
+        allowCanvasMovement={STUDIO_PREVIEW_MANUAL_EDITING_ENABLED && !isGestureRecording}
+        onCanvasMouseDown={handlePreviewCanvasMouseDown}
+        onCanvasPointerMove={handlePreviewCanvasPointerMove}
+        onCanvasPointerLeave={handlePreviewCanvasPointerLeave}
+        onSelectionChange={applyDomSelection}
+        onBlockedMove={handleBlockedDomMove}
+        onManualDragStart={handleDomManualDragStart}
+        onPathOffsetCommit={handleDomPathOffsetCommit}
+        onGroupPathOffsetCommit={handleDomGroupPathOffsetCommit}
+        onBoxSizeCommit={handleDomBoxSizeCommit}
+        onRotationCommit={handleDomRotationCommit}
+        onStyleCommit={handleDomStyleCommit}
+        onDeleteSelection={handleDomEditElementDelete}
+        onApplyZIndex={(sel, patches) => {
+          const { entries, droppedLabels } = resolveZIndexEntries(sel, patches);
+          if (droppedLabels.length > 0) {
+            // The optimistic z-index has already been applied live at this point —
+            // these siblings just won't be written to source, so they'll revert to
+            // their prior stacking order on the next reload with no other signal.
+            console.warn(
+              "[studio] z-index reorder: dropping sibling(s) with no stable id/selector " +
+                "(will revert on reload):",
+              droppedLabels.join(", "),
+            );
+          }
+          if (entries.length > 0) handleDomZIndexReorderCommit(entries);
+        }}
+        gridVisible={snapPrefs.gridVisible}
+        gridSpacing={snapPrefs.gridSpacing}
+        recordingState={recordingState}
+        onToggleRecording={onToggleRecording}
+        onMarqueeSelect={applyMarqueeSelection}
+      />
+      <SnapToolbar onSnapChange={setSnapPrefs} />
+      {STUDIO_KEYFRAMES_ENABLED && (
+        <MotionPathOverlay
+          iframeRef={previewIframeRef}
+          selection={shouldShowSelectedDomBounds ? domEditSelection : null}
+          compositionSize={compositionDimensions}
+          isPlaying={isPlaying}
+        />
+      )}
+      {gestureOverlay}
+    </>
+  );
+}