@hyperframes/studio 0.8.121 → 0.8.123

package/src/components/editor/motionPathGeometry.ts

@@ -78,7 +78,10 @@ export function nearestPointOnPath(
   return best;
 }
 
-export function buildMotionPathGeometry(read: ReadTween | null): MotionPathGeometry | null {
+export function buildMotionPathGeometry(
+  read: ReadTween | null,
+  base: { x: number; y: number } = { x: 0, y: 0 },
+): MotionPathGeometry | null {
   if (!read) return null;
   const isArc = Boolean(read.arcPath);
   const nodes: MotionPathNode[] = [];
@@ -87,8 +90,8 @@ export function buildMotionPathGeometry(read: ReadTween | null): MotionPathGeome
   // anchor. Arc waypoints always carry x/y (never filtered), so source index
   // and node order stay aligned.
   // Which axes does the tween animate at all? A single-axis tween (e.g.
-  // `to({ x: -260 })`) only carries x; its y stays at the base (0, the GSAP
-  // transform identity), so we default it and still draw a path. But if the tween
+  // `to({ x: -260 })`) only carries x; its y stays at `base`, GSAP's live y (a CSS
+  // translate it folded in, else 0), so we default it and still draw a path. But if the tween
   // DOES animate an axis and a given keyframe omits it, that value is interpolated
   // (not 0) and can't be placed here → skip that node (the prior behavior).
   const finite = (v: unknown): v is number => typeof v === "number" && isFinite(v);
@@ -100,8 +103,8 @@ export function buildMotionPathGeometry(read: ReadTween | null): MotionPathGeome
     if (tweenHasX && !finite(kf.properties.x)) return;
     if (tweenHasY && !finite(kf.properties.y)) return;
     nodes.push({
-      x: tweenHasX ? (kf.properties.x as number) : 0,
-      y: tweenHasY ? (kf.properties.y as number) : 0,
+      x: tweenHasX ? (kf.properties.x as number) : base.x,
+      y: tweenHasY ? (kf.properties.y as number) : base.y,
       ref: isArc ? { type: "waypoint", index: i } : { type: "keyframe", pct: kf.percentage },
     });
   });

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

@@ -0,0 +1,82 @@
+// @vitest-environment happy-dom
+import { expect, it } from "vitest";
+import { pressBelongsToLayer, pressSelectedLayer } from "./motionPathLayerNode";
+
+// Keyframe nodes at x 60 and 120 (y 30), drawn from home (500, 400); dots of radius 6.
+const atLayer = { x: 60, y: 30, ax: 560, ay: 430 };
+const other = { x: 120, y: 30, ax: 620, ay: 430 };
+const live = { x: 60, y: 30 };
+
+const box = document.createElement("div");
+box.setAttribute("data-dom-edit-selection-box", "true");
+const circle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+document.body.append(box, circle);
+
+/** A press on `circle` at (x, y), with `under` what the document hit-tests there. */
+function press(x: number, y: number, under: Element[]) {
+  document.elementsFromPoint = () => [circle, ...under];
+  return { currentTarget: circle, clientX: x, clientY: y } as unknown as React.PointerEvent;
+}
+
+it("the node GSAP renders the layer at is the layer, inside the box or out", () => {
+  expect(pressBelongsToLayer(press(562, 431, [box]), { x: 562, y: 431 }, atLayer, 6, live)).toBe(
+    true,
+  );
+  expect(pressBelongsToLayer(press(570, 440, []), { x: 570, y: 440 }, atLayer, 6, live)).toBe(true);
+});
+
+it("inside the layer's box another node's grab ring is the layer's; its dot stays the node's", () => {
+  expect(pressBelongsToLayer(press(610, 430, [box]), { x: 610, y: 430 }, other, 6, live)).toBe(
+    true,
+  );
+  expect(pressBelongsToLayer(press(617, 430, [box]), { x: 617, y: 430 }, other, 6, live)).toBe(
+    false,
+  );
+});
+
+it("outside the layer's box a node's whole grab ring is the node's", () => {
+  expect(pressBelongsToLayer(press(610, 430, []), { x: 610, y: 430 }, other, 6, live)).toBe(false);
+  expect(pressBelongsToLayer(press(610, 430, [box]), { x: 610, y: 430 }, other, 6, null)).toBe(
+    true,
+  );
+});
+
+it("hands a press to the selected layer's box with its pointer and position", () => {
+  const got: number[][] = [];
+  const listen = (e: Event) => {
+    const p = e as PointerEvent;
+    got.push([p.pointerId, p.clientX, p.clientY, p.button]);
+    e.preventDefault();
+  };
+  box.addEventListener("pointerdown", listen);
+  const nativeEvent = new PointerEvent("pointerdown", {
+    pointerId: 7,
+    clientX: 12,
+    clientY: 34,
+    button: 0,
+    bubbles: true,
+    cancelable: true,
+  });
+  const down = { currentTarget: circle, nativeEvent } as unknown as React.PointerEvent;
+  expect(pressSelectedLayer(down)).toBe(true);
+  expect(got).toEqual([[7, 12, 34, 0]]);
+  box.removeEventListener("pointerdown", listen);
+  box.remove();
+  expect(pressSelectedLayer(down)).toBe(false);
+  document.body.append(box);
+});
+
+it("keeps the press when the box does not start a gesture with it, or takes no pointer", () => {
+  let got = 0;
+  const listen = () => void got++;
+  box.addEventListener("pointerdown", listen);
+  const nativeEvent = new PointerEvent("pointerdown", { bubbles: true, cancelable: true });
+  const down = { currentTarget: circle, nativeEvent } as unknown as React.PointerEvent;
+  expect(pressSelectedLayer(down)).toBe(false);
+  expect(got).toBe(1);
+  box.style.pointerEvents = "none";
+  expect(pressSelectedLayer(down)).toBe(false);
+  expect(got).toBe(1);
+  box.style.pointerEvents = "";
+  box.removeEventListener("pointerdown", listen);
+});

package/src/components/editor/motionPathLayerNode.ts

@@ -0,0 +1,28 @@
+type Point = { x: number; y: number };
+type DrawnNode = Point & { ax: number; ay: number };
+
+const LAYER_BOX = '[data-dom-edit-selection-box="true"]';
+
+/** How far a node's dot reaches; a selected node draws it larger. */
+export const dotRadius = (r: number, selected: boolean) => (selected ? r * 1.5 : r);
+
+/** A press on the layer's own node, or in its box but off a node's dot, belongs to the layer. */
+export function pressBelongsToLayer(
+  e: React.PointerEvent,
+  point: Point,
+  pressed: DrawnNode,
+  dotR: number,
+  live: Point | null,
+): boolean {
+  if (live && Math.abs(pressed.x - live.x) < 0.5 && Math.abs(pressed.y - live.y) < 0.5) return true;
+  const hits = e.currentTarget.ownerDocument.elementsFromPoint(e.clientX, e.clientY);
+  const inBox = hits.some((el) => el.closest(LAYER_BOX));
+  return inBox && Math.hypot(point.x - pressed.ax, point.y - pressed.ay) > dotR;
+}
+
+/** Hands a press to the selected layer's box; true when the box started a gesture with it. */
+export function pressSelectedLayer(e: React.PointerEvent): boolean {
+  const box = e.currentTarget.ownerDocument.querySelector(LAYER_BOX);
+  if (!box || getComputedStyle(box).pointerEvents === "none") return false;
+  return !box.dispatchEvent(new PointerEvent("pointerdown", e.nativeEvent));
+}

package/src/components/editor/useDomEditNudge.test.tsx

@@ -34,9 +34,11 @@ let flushNudge = () => {};
 function Harness({
   selection,
   onPathOffsetCommit,
+  onManualDragStart = () => {},
 }: {
   selection: DomEditSelection | null;
   onPathOffsetCommit: UseDomEditNudgeParams["onPathOffsetCommitRef"]["current"];
+  onManualDragStart?: () => void;
 }) {
   flushNudge = useDomEditNudge({
     selection,
@@ -48,7 +50,7 @@ function Harness({
     gestureRef: makeRef(null),
     groupGestureRef: makeRef(null),
     blockedMoveRef: makeRef(null),
-    onManualDragStartRef: makeRef(() => {}),
+    onManualDragStartRef: makeRef(onManualDragStart),
     onBlockedMoveRef: makeRef(() => {}),
     onPathOffsetCommitRef: makeRef(onPathOffsetCommit),
     onGroupPathOffsetCommitRef: makeRef(async () => {}),
@@ -340,6 +342,56 @@ describe("useDomEditNudge carries the route its press chose", () => {
   });
 });
 
+describe("useDomEditNudge pauses playback before it snapshots the timelines", () => {
+  let reactRoot: ReturnType<typeof createRoot> | null = null;
+  const pause = vi.fn();
+  const mount = (selection: DomEditSelection | null) => {
+    reactRoot = createRoot(document.createElement("div"));
+    act(() => {
+      reactRoot!.render(
+        React.createElement(Harness, {
+          selection,
+          onPathOffsetCommit: vi.fn(),
+          onManualDragStart: pause,
+        }),
+      );
+    });
+  };
+  beforeEach(() => {
+    vi.useFakeTimers();
+    __resetForTests();
+    pause.mockReset();
+  });
+  afterEach(() => {
+    act(() => reactRoot?.unmount());
+    reactRoot = null;
+    document.body.innerHTML = "";
+    vi.useRealTimers();
+    delete (window as { __timelines?: unknown }).__timelines;
+  });
+
+  it("does not resume a timeline the playback pause stopped", () => {
+    let playing = true;
+    const root = { pause: () => void (playing = false), paused: () => !playing };
+    (window as { __timelines?: unknown }).__timelines = { root };
+    pause.mockImplementation(root.pause);
+    const element = document.body.appendChild(document.createElement("div"));
+    mount(makeSelection("Dot", element));
+
+    act(() => dispatchArrowRight());
+
+    expect(element.hasAttribute("data-hf-drag-paused-timelines")).toBe(false);
+  });
+
+  it("leaves playback alone when no layer can move", () => {
+    mount(null);
+
+    act(() => dispatchArrowRight());
+
+    expect(pause).not.toHaveBeenCalled();
+  });
+});
+
 describe("useDomEditNudge — undo right after a burst", () => {
   it("undo's drain commits a burst still inside its debounce and waits for its save", async () => {
     __resetForTests();

package/src/components/editor/useDomEditNudge.ts

@@ -212,6 +212,8 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
       ? resolveGroupNudgeTargets(groupItems)
       : resolveSingleNudgeTarget(p.selectionRef.current, p.overlayRectRef.current);
     if (!targets) return null;
+    // Same side effect a drag start has (pauses preview playback).
+    p.onManualDragStartRef.current?.();
     const members: ManualOffsetDragMember[] = [];
     for (const target of targets) {
       const result = createManualOffsetDragMember({ ...target, gesture: "nudge" });
@@ -223,8 +225,6 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
       members.push(result.member);
     }
     if (members.length === 0) return null;
-    // Same side effect a drag start has (pauses preview playback).
-    p.onManualDragStartRef.current?.();
     const edit = beginStudioPendingEdit(manualOffsetMoveRevert(members));
     return { members, isGroup, accum: { x: 0, y: 0 }, timer: null, edit };
   };

package/src/components/editor/useMotionPathData.test.tsx

@@ -8,6 +8,12 @@ import { usePlayerStore } from "../../player/store/playerStore";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
+const runtime = vi.hoisted(() => ({ read: null as unknown, gsapPosition: null as unknown }));
+vi.mock("../../hooks/gsapRuntimeKeyframes", () => ({ readRuntimeKeyframes: () => runtime.read }));
+vi.mock("../../hooks/gsapPositionDetection", () => ({
+  readGsapPositionFromIframe: () => runtime.gsapPosition,
+}));
+
 const originalRaf = window.requestAnimationFrame;
 let frames: Array<() => void> = [];
 const runFrames = (count: number) => {
@@ -36,6 +42,30 @@ afterEach(() => {
   vi.useRealTimers();
   usePlayerStore.setState({ previewBooted: false, motionPathArmed: false });
   document.body.innerHTML = "";
+  runtime.read = runtime.gsapPosition = null;
+});
+
+it("draws an axis the tween leaves alone where GSAP renders it, so the playhead node sits on the layer", () => {
+  runtime.read = {
+    keyframes: [
+      { percentage: 66.667, properties: { x: 60 } },
+      { percentage: 100, properties: { x: 120 } },
+    ],
+  };
+  runtime.gsapPosition = { x: 60, y: 30 };
+  let points: string | undefined;
+  function Probe() {
+    const ref = useRef(document.createElement("iframe"));
+    points = useMotionPathData(ref, "#box").geometry?.points;
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  try {
+    act(() => root.render(<Probe />));
+    expect(points).toBe("60,30 120,30");
+  } finally {
+    act(() => root.unmount());
+  }
 });
 
 it("reads no layout per frame until there is a path or a create ring to draw", () => {

package/src/components/editor/useMotionPathData.ts

@@ -1,5 +1,6 @@
 import { useEffect, useRef, useState, type RefObject } from "react";
 import { readRuntimeKeyframes } from "../../hooks/gsapRuntimeKeyframes";
+import { readGsapPositionFromIframe } from "../../hooks/gsapPositionDetection";
 import { isElementVisibleForOverlay } from "./domEditOverlayGeometry";
 import { buildMotionPathGeometry, type MotionPathGeometry } from "./motionPathGeometry";
 import { subscribeOverlayFrame } from "./overlayFrameLoop";
@@ -169,7 +170,8 @@ export function useMotionPathData(
     const recompute = () => {
       // Position-only: never let a co-located size/scale tween shadow the path.
       const read = readRuntimeKeyframes(iframeRef.current, selector, undefined, ["x", "y"]);
-      const next = buildMotionPathGeometry(read);
+      const base = read ? readGsapPositionFromIframe(iframeRef.current, selector) : null;
+      const next = buildMotionPathGeometry(read, base ?? undefined);
       setGeometry((prev) =>
         prev?.points === next?.points && prev?.kind === next?.kind ? prev : next,
       );

package/src/hooks/gsapValueAtPlayhead.test.ts

@@ -527,9 +527,52 @@ describe("planValueAtPlayhead", () => {
     ]);
   });
 
-  it("refuses keyframes eased as a whole, whose segment curves it cannot keep", () => {
-    const anim = { ...kf([{ percentage: 100, properties: { x: 20 } }]), ease: "power2.out" };
-    expect(plan({ anim, values: { x: 5 } })).toEqual({ ok: false, reason: "eased-keyframes" });
+  describe("keyframes eased as a whole", () => {
+    const eased = {
+      ...kf([
+        { percentage: 0, properties: { x: 0 } },
+        { percentage: 100, properties: { x: 20 } },
+      ]),
+      ease: "power2.out",
+    };
+
+    it("changes the keyframe under the playhead and writes the ease back", () => {
+      const result = plan({ anim: eased, at: { time: 4 }, values: { x: 5 } });
+      expect(result.ok && result.mutation.keyframes.map((k) => k.properties.x)).toEqual([0, 5]);
+      expect(result.ok && result.mutation.ease).toBe("power2.out");
+    });
+
+    it("writes the keyframes' own ease as the tween's, as GSAP prefers it", () => {
+      const anim = { ...eased, keyframes: { ...eased.keyframes!, ease: "expo.in" } };
+      const result = plan({ anim, at: { time: 0 }, values: { x: 5 } });
+      expect(result.ok && result.mutation.ease).toBe("expo.in");
+    });
+
+    it("refuses an inner keyframe, which the ease shows at another time", () => {
+      const anim = {
+        ...kf([
+          { percentage: 0, properties: { x: 0 } },
+          { percentage: 50, properties: { x: 100 } },
+          { percentage: 100, properties: { x: 300 } },
+        ]),
+        ease: "power2.out",
+      };
+      expect(plan({ anim, at: { time: 2 }, values: { x: 5 } })).toEqual({
+        ok: false,
+        reason: "eased-keyframes",
+      });
+    });
+
+    it("refuses to add a keyframe, whose time the ease would move", () => {
+      expect(plan({ anim: eased, at: { time: 2 }, values: { x: 5 } })).toEqual({
+        ok: false,
+        reason: "eased-keyframes",
+      });
+      expect(plan({ anim: eased, at: { time: 6 }, values: { x: 5 } })).toEqual({
+        ok: false,
+        reason: "eased-keyframes",
+      });
+    });
   });
 });
 

package/src/hooks/gsapValueAtPlayhead.ts

@@ -55,6 +55,7 @@ export type PlayheadEditPlan =
         position: number;
         duration: number;
         keyframes: Keyframe[];
+        ease?: string;
         easeEach?: string;
       };
       /** A keyframe was added, not only changed: keyframe usage counts it as an add. */
@@ -70,6 +71,7 @@ const isLinear = (ease: string | undefined) => !ease || ease === "none" || ease
 
 interface Normalized {
   keyframes: Keyframe[];
+  runEase?: string;
   easeEach?: string;
 }
 
@@ -82,10 +84,10 @@ function normalize(edit: PlayheadEdit): Normalized | { reason: PlayheadEditRefus
   const { anim } = edit;
   const data = anim.keyframes;
   if (data) {
-    if (!isLinear(anim.ease) || !isLinear(data.ease)) return { reason: "eased-keyframes" };
     if (data.format === "simple-array") return { reason: "simple-array-keyframes" };
     const arrayStep = data.format === "object-array";
     return {
+      runEase: data.ease ?? anim.ease,
       keyframes: data.keyframes.map((kf) => ({
         ...kf,
         properties: { ...kf.properties },
@@ -126,8 +128,11 @@ function valueAt(keyframes: Keyframe[], prop: string, side: "first" | "last") {
   return kf ? { percentage: kf.percentage, value: kf.properties[prop]! } : null;
 }
 
+const keyframeAt = (keyframes: Keyframe[], percentage: number) =>
+  keyframes.find((kf) => Math.abs(kf.percentage - percentage) <= KEYFRAME_PCT_MATCH);
+
 function upsert(keyframes: Keyframe[], percentage: number, properties: Props, ease?: string) {
-  const hit = keyframes.find((kf) => Math.abs(kf.percentage - percentage) <= KEYFRAME_PCT_MATCH);
+  const hit = keyframeAt(keyframes, percentage);
   if (hit) {
     Object.assign(hit.properties, properties);
     return hit;
@@ -195,14 +200,18 @@ export function planValueAtPlayhead(edit: PlayheadEdit): PlayheadEditPlan {
     "percentage" in edit.at
       ? edit.at.percentage
       : roundPct(((edit.at.time - start) / duration) * 100);
+  const eased = !isLinear(norm.runEase);
   if (pct >= -KEYFRAME_PCT_MATCH && pct <= 100 + KEYFRAME_PCT_MATCH) {
     const at = Math.min(100, Math.max(0, pct));
+    const hit = keyframeAt(keyframes, at);
+    if (eased && hit?.percentage !== 0 && hit?.percentage !== 100) return refuse("eased-keyframes");
     const next = [...keyframes]
       .sort((a, b) => a.percentage - b.percentage)
       .find((kf) => kf.percentage > at + KEYFRAME_PCT_MATCH);
     // The new keyframe splits next's segment, so it takes next's ease.
     upsert(keyframes, at, { ...values }, next?.ease);
   } else {
+    if (eased) return refuse("eased-keyframes");
     const time = (edit.at as { time: number }).time;
     const before = time < start;
     const held = heldEnds(norm, before ? "start" : "end", edit.implicitEndValue, backfilled);
@@ -232,6 +241,7 @@ export function planValueAtPlayhead(edit: PlayheadEdit): PlayheadEditPlan {
       position: roundTo3(position),
       duration: roundTo3(span),
       keyframes,
+      ...(norm.runEase ? { ease: norm.runEase } : {}),
       ...(norm.easeEach ? { easeEach: norm.easeEach } : {}),
     },
     added: keyframes.length > authored,

package/src/hooks/linkShortcuts.test.ts

@@ -61,6 +61,22 @@ describe("dispatchLinkShortcut", () => {
     expect(handleTimelineElementDeleteOnly).toHaveBeenCalledWith(video);
   });
 
+  it("leaves ⌥⌫ to a text field the user is typing in", () => {
+    const video = clip("talk", "video", { muted: true, link: "lk-1" });
+    select([video, clip("talk-audio", "audio", { link: "lk-1" })], "talk");
+    const input = document.createElement("input");
+    document.body.append(input);
+    const event = key({ altKey: true, key: "Backspace", bubbles: true });
+    const handleTimelineElementDeleteOnly = vi.fn();
+    input.addEventListener("keydown", (e) =>
+      dispatchLinkShortcut(e, { handleLinkEdit: vi.fn(), handleTimelineElementDeleteOnly }),
+    );
+    input.dispatchEvent(event);
+    input.remove();
+    expect(handleTimelineElementDeleteOnly).not.toHaveBeenCalled();
+    expect(event.preventDefault).not.toHaveBeenCalled();
+  });
+
   it("leaves the key alone when no link item applies", () => {
     select([clip("title", "div")], "title");
     const event = key({ metaKey: true, key: "l" });

package/src/hooks/linkShortcuts.ts

@@ -1,6 +1,7 @@
 import { usePlayerStore } from "../player";
 import type { TimelineEditCallbacks } from "../player/components/timelineCallbacks";
 import { resolveLinkMenuItems } from "../player/components/clipMenuLinkItems";
+import { isTypingTarget } from "../utils/typingTarget";
 
 export interface LinkShortcutCallbacks {
   handleLinkEdit?: TimelineEditCallbacks["onLinkEdit"];
@@ -22,6 +23,7 @@ function shortcutOf(event: KeyboardEvent): string | null {
 
 /** ⌘L unlink/link, ⌥⇧D detach audio, ⌥⌫ delete one linked clip — the clip menu's shortcuts. */
 export function dispatchLinkShortcut(event: KeyboardEvent, cb: LinkShortcutCallbacks): boolean {
+  if (isTypingTarget(event.target)) return false;
   const shortcut = shortcutOf(event);
   if (!shortcut) return false;
   const { elements, selectedElementId, selectedElementIds } = usePlayerStore.getState();

package/src/hooks/useAppHotkeys.ts

@@ -2,7 +2,6 @@ import { useCallback, useEffect, useRef } from "react";
 import { usePlayerStore } from "../player";
 import type { TimelineElement } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
-import { isTypingTarget } from "../utils/typingTarget";
 import { dispatchLinkShortcut, type LinkShortcutCallbacks } from "./linkShortcuts";
 import { useCaptionStore } from "../captions/store";
 import {
@@ -226,7 +225,7 @@ export function useAppHotkeys({
   const handleAppKeyDown = useCallback((event: KeyboardEvent) => {
     const cb = cbRef.current;
     const key = event.key.toLowerCase();
-    if (!isTypingTarget(event.target) && dispatchLinkShortcut(event, cb)) return;
+    if (dispatchLinkShortcut(event, cb)) return;
     if (event.metaKey || event.ctrlKey) {
       dispatchModifierKey(event, key, cb);
       return;

package/src/index.ts

@@ -7,6 +7,8 @@ export type { EditorShellProps } from "./components/EditorShell";
 export { NLEPreview } from "./components/nle/NLEPreview";
 export { DEFAULT_SHORTCUT_SECTIONS } from "./player/components/studioShortcuts";
 export { ShortcutsButton } from "./player/components/ShortcutsPanel";
+export { dispatchLinkShortcut } from "./hooks/linkShortcuts";
+export type { LinkShortcutCallbacks } from "./hooks/linkShortcuts";
 export type { ShortcutsButtonProps } from "./player/components/ShortcutsPanel";
 export type { ShortcutHint, ShortcutSection } from "./player/components/studioShortcuts";
 export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";

package/src/player/components/TimelineClipFades.tsx

@@ -48,6 +48,7 @@ const SNAP_LABEL: Record<TimelineSnapType, string> = {
   playhead: "playhead",
   "clip-edge": "clip edge",
   beat: "beat",
+  grid: "grid line",
 };
 
 export type ClipFadeShape = AudioFades & { duration: number };

package/src/player/components/timelineClipDragPreview.test.ts

@@ -3,6 +3,7 @@ import type { TimelineElement } from "../store/playerStore";
 import {
   computeDragPreview,
   computeResizePreview,
+  guideIfSaved,
   getTimelineDragOverlayPosition,
   type DragPreviewContext,
 } from "./timelineClipDragPreview";
@@ -293,6 +294,52 @@ describe("computeDragPreview — a clip landing on an empty main track keeps its
   });
 });
 
+describe("guideIfSaved — a guide only where the clip saves", () => {
+  const grid = { time: 3.25, type: "grid" as const };
+
+  it("drops the guide when start and duration round apart from the target", () => {
+    // 1440 px/s: 1.125s + 2.125s saves as 1.13s + 2.13s, 14px past the 3.25s guide.
+    const el = clip("a", 0, 1.125, 2, 0, "div");
+    expect(guideIfSaved(el, { start: 1.125, duration: 2.125 }, grid, 1440)).toBeNull();
+  });
+
+  it("drops the guide when a nested clip's local start rounds off it", () => {
+    const el = { ...clip("a", 0, 2, 1, 0, "div"), parentCompositionStart: 1 / 30 };
+    const target = { time: 2.1, type: "playhead" as const };
+    expect(guideIfSaved(el, { start: 2.1, duration: 1 }, target, 1440)).toBeNull();
+  });
+
+  it("keeps the guide when the saved edge is on it", () => {
+    const el = clip("a", 0, 1, 2, 0, "div");
+    expect(guideIfSaved(el, { start: 1, duration: 2.25 }, grid, 1440)).toBe(grid);
+  });
+
+  it("judges a move by the duration it keeps, not a rounded one", () => {
+    // A 31/30 s clip moved so its end meets 3.25s saves its start at 2.22s and ends 4.8px past.
+    const el = clip("a", 0, 1, 31 / 30, 0, "div");
+    const edge = { time: 3.25, type: "clip-edge" as const };
+    expect(guideIfSaved(el, { start: 2.217 }, edge, 1440)).toBeNull();
+  });
+
+  it("draws no guide for a move whose saved start misses the target", () => {
+    const nested = { ...moodboard, parentCompositionStart: 1 / 30 };
+    const { drag } = horizontalDrag(nested, 0.5, 0);
+    const context = {
+      ...ctx(),
+      pps: 1440,
+      buildSnapTargets: () => [{ time: 21, type: "playhead" as const }],
+    };
+    const next = computeDragPreview(
+      drag,
+      drag.originClientX + 2 * 1440,
+      drag.originClientY,
+      context,
+    );
+    expect(next.previewStart).toBe(21);
+    expect(next.snapTime).toBeNull();
+  });
+});
+
 describe("computeResizePreview — composition source continuity", () => {
   it("seeds a legacy composition offset and advances it at playback rate", () => {
     const element = {
@@ -320,6 +367,27 @@ describe("computeResizePreview — composition source continuity", () => {
     });
   });
 
+  it("draws no guide when the trimmed start cannot save onto the target", () => {
+    // 1440 px/s: a playhead on frame 31 (1.033s) saves a start of 1.03s, 4px off the guide.
+    const result = computeResizePreview(
+      {
+        element: clip("a", 0, 1, 2, 0, "div"),
+        edge: "start",
+        originClientX: 0,
+        previewStart: 1,
+        previewDuration: 2,
+        started: true,
+      },
+      48,
+      {
+        scroll: fakeScroll(),
+        pps: 1440,
+        buildSnapTargets: () => [{ time: 1.033, type: "playhead" }],
+      },
+    );
+    expect(result).toMatchObject({ previewStart: 1.03, snapTime: null, snapType: null });
+  });
+
   it("does not let a tail snap shrink a clip below the drag's minimum duration", () => {
     const result = computeResizePreview(
       {