@hyperframes/studio 0.7.54 → 0.7.56

package/src/components/editor/snapEngine.test.ts

@@ -5,8 +5,8 @@ import {
   buildCompositionSnapTarget,
   buildGridSnapEdges,
   resolveSnapAdjustment,
-  resolveResizeSnapAdjustment,
   resolveEquidistanceGuides,
+  resolveGuideLineRect,
   SNAP_THRESHOLD_PX,
   type SnapTarget,
 } from "./snapEngine";
@@ -385,88 +385,22 @@ describe("resolveSnapAdjustment", () => {
 });
 
 // ---------------------------------------------------------------------------
-// resolveResizeSnapAdjustment
+// resolveGuideLineRect
 // ---------------------------------------------------------------------------
 
-describe("resolveResizeSnapAdjustment", () => {
-  test("only right edge snaps on X", () => {
-    // Moving rect at (100, 100) size 50x50, right=150.
-    // Target left at 200. Propose dx=47 => proposed right=197. Dist to 200=3.
-    const t = target("a", 200, 100, 100, 100);
-    const result = resolveResizeSnapAdjustment({
-      movingRect: rect(100, 100, 50, 50),
-      proposedDx: 47,
-      proposedDy: 0,
-      targets: [t],
-      threshold: SNAP_THRESHOLD_PX,
-      disabled: false,
-    });
-    expect(result.dx).toBe(50); // right edge snaps to 200
-  });
+describe("resolveGuideLineRect", () => {
+  const composition = rect(120, 80, 640, 360); // letterboxed inside the overlay
 
-  test("only bottom edge snaps on Y", () => {
-    // Moving rect at (100, 100) size 50x50, bottom=150.
-    // Target top at 200. Propose dy=47 => proposed bottom=197. Dist to 200=3.
-    const t = target("a", 100, 200, 100, 100);
-    const result = resolveResizeSnapAdjustment({
-      movingRect: rect(100, 100, 50, 50),
-      proposedDx: 0,
-      proposedDy: 47,
-      targets: [t],
-      threshold: SNAP_THRESHOLD_PX,
-      disabled: false,
-    });
-    expect(result.dy).toBe(50); // bottom edge snaps to 200
-  });
-
-  test("left edge does NOT snap during resize", () => {
-    // Target right at 150. Moving rect left=100. If drag were active,
-    // left would snap. But during resize, only right edge snaps.
-    // Moving rect at (100, 100) size 200x200, right=300.
-    // Target right=150. Proposed dx=-153 => proposed right=147. Dist to 150=3.
-    // This SHOULD snap right to 150 (dx = -150). But left stays at 100.
-    const t = target("a", 50, 100, 100, 100); // right=150
-    const result = resolveResizeSnapAdjustment({
-      movingRect: rect(100, 100, 200, 200),
-      proposedDx: -153,
-      proposedDy: 0,
-      targets: [t],
-      threshold: SNAP_THRESHOLD_PX,
-      disabled: false,
-    });
-    // Right edge: 300 + (-153) = 147 => snaps to 150, adjustment = +3, dx = -150
-    expect(result.dx).toBe(-150);
-  });
-
-  test("disabled=true returns passthrough for resize", () => {
-    const t = target("a", 200, 200, 100, 100);
-    const result = resolveResizeSnapAdjustment({
-      movingRect: rect(100, 100, 50, 50),
-      proposedDx: 47,
-      proposedDy: 47,
-      targets: [t],
-      threshold: SNAP_THRESHOLD_PX,
-      disabled: true,
-    });
-    expect(result.dx).toBe(47);
-    expect(result.dy).toBe(47);
-    expect(result.guides).toHaveLength(0);
+  test("vertical guide (axis x) spans the composition's height at the snap x", () => {
+    expect(resolveGuideLineRect({ axis: "x", position: 440, from: 0, to: 0 }, composition)).toEqual(
+      { left: 440, top: 80, width: 1, height: 360 },
+    );
   });
 
-  test("resize produces guide lines", () => {
-    const t = target("a", 200, 100, 100, 100);
-    const result = resolveResizeSnapAdjustment({
-      movingRect: rect(100, 100, 50, 50),
-      proposedDx: 47,
-      proposedDy: 0,
-      targets: [t],
-      threshold: SNAP_THRESHOLD_PX,
-      disabled: false,
-    });
-    expect(result.guides.length).toBeGreaterThanOrEqual(1);
-    const xGuide = result.guides.find((g) => g.axis === "x");
-    expect(xGuide).toBeDefined();
-    expect(xGuide!.position).toBe(200);
+  test("horizontal guide (axis y) spans the composition's width at the snap y", () => {
+    expect(resolveGuideLineRect({ axis: "y", position: 260, from: 0, to: 0 }, composition)).toEqual(
+      { left: 120, top: 260, width: 640, height: 1 },
+    );
   });
 });
 

package/src/components/editor/snapEngine.ts

@@ -410,62 +410,22 @@ export function resolveSnapAdjustment(input: {
 }
 
 // ---------------------------------------------------------------------------
-// resolveResizeSnapAdjustment — resize variant (only right/bottom snap)
+// resolveGuideLineRect — screen rect for rendering a snap guide line
 // ---------------------------------------------------------------------------
 
-// fallow-ignore-next-line complexity
-export function resolveResizeSnapAdjustment(input: {
-  movingRect: Rect;
-  proposedDx: number;
-  proposedDy: number;
-  targets: SnapTarget[];
-  gridEdges?: { x: SnapEdge[]; y: SnapEdge[] };
-  threshold: number;
-  disabled: boolean;
-}): SnapResult {
-  if (input.disabled || input.threshold <= 0) {
-    return DISABLED_RESULT(input.proposedDx, input.proposedDy);
+/**
+ * Full-length guide line spanning the composition: a vertical line (axis "x")
+ * runs the composition's height at the snapped x position; a horizontal line
+ * (axis "y") runs the composition's width. `composition` is the composition
+ * rect in overlay space — guide positions are already overlay-space, so the
+ * line must be offset by the composition's left/top (the canvas is usually
+ * letterboxed inside the overlay).
+ */
+export function resolveGuideLineRect(guide: SnapGuide, composition: Rect): Rect {
+  if (guide.axis === "x") {
+    return { left: guide.position, top: composition.top, width: 1, height: composition.height };
   }
-
-  const mr = input.movingRect;
-  const proposedRight = rectRight(mr) + input.proposedDx;
-  const proposedBottom = rectBottom(mr) + input.proposedDy;
-
-  const xCandidates = collectCandidates(
-    [proposedRight],
-    input.targets,
-    (t) => [t.left, t.centerX, t.right],
-    input.gridEdges?.x,
-    input.threshold,
-  );
-  const yCandidates = collectCandidates(
-    [proposedBottom],
-    input.targets,
-    (t) => [t.top, t.centerY, t.bottom],
-    input.gridEdges?.y,
-    input.threshold,
-  );
-
-  const bestX = pickBest(xCandidates);
-  const bestY = pickBest(yCandidates);
-  const adjustedDx = input.proposedDx + (bestX?.adjustment ?? 0);
-  const adjustedDy = input.proposedDy + (bestY?.adjustment ?? 0);
-
-  const adjustedRect: Rect = {
-    left: mr.left,
-    top: mr.top,
-    width: mr.width + adjustedDx,
-    height: mr.height + adjustedDy,
-  };
-
-  const targetMap = new Map(input.targets.map((t) => [t.id, t]));
-
-  return {
-    dx: adjustedDx,
-    dy: adjustedDy,
-    guides: buildGuidesFromMatches(bestX, bestY, adjustedRect, targetMap),
-    spacingGuides: [], // computed separately via resolveEquidistanceGuides
-  };
+  return { left: composition.left, top: guide.position, width: composition.width, height: 1 };
 }
 
 // ---------------------------------------------------------------------------

package/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();
+  });
+});

package/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 };
+}