@hyperframes/studio 0.8.121 → 0.8.122

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(
       {

package/src/player/components/timelineClipDragPreview.ts

@@ -5,7 +5,7 @@ import {
   resolveTimelineMinDuration,
 } from "./timelineGroupEditing";
 import type { TimelineElement } from "../store/playerStore";
-import { clampToHostStart } from "../store/timelineElement";
+import { clampToHostStart, savedClipEdges } from "../store/timelineElement";
 import {
   CLIP_Y,
   TRACK_H,
@@ -34,7 +34,6 @@ import { heldAudioShiftRange, heldPartnerVideoBounds } from "./audioClipLink";
 type BuildSnapTargets = (
   excludeElementKey: string | null,
   includeBeats: boolean,
-  includePlayhead?: boolean,
 ) => TimelineSnapTarget[];
 
 export interface DragPreviewContext {
@@ -56,6 +55,8 @@ export interface DragPreviewContext {
    * on demand from `elements`, so the result is identical either way.
    */
   audioTracks?: ReadonlySet<number>;
+  /** Seconds between the ruler's lines; 0 or absent when snapping is off. */
+  gridStep?: number;
 }
 
 export function createKeyboardClipDrag(
@@ -248,6 +249,7 @@ export function computeDragPreview(
     // Relaxed clamp: allow the snapped start past the content, up to the
     // rendered extent (see dragMaxStart) — the composition grows on commit.
     dragMaxStart + drag.element.duration,
+    ctx.gridStep,
   );
   // A group moves rigidly: the grabbed clip stops where any mover would cross its host's start.
   const group = resolveGroupDrag(drag, ctx);
@@ -266,6 +268,11 @@ export function computeDragPreview(
     return { ...drag, started: true };
   }
   const { track: previewTrack, insertRow } = placement;
+  const target =
+    placement.start === snap.start && snap.snapTime !== null && snap.snapType !== null
+      ? { time: snap.snapTime, type: snap.snapType }
+      : null;
+  const guide = guideIfSaved(drag.element, { start: snap.start }, target, pps);
   return {
     ...drag,
     started: true,
@@ -277,11 +284,24 @@ export function computeDragPreview(
     // tell a deliberate vertical lane change from a horizontal drag.
     desiredTrack: nextMove.track,
     insertRow,
-    snapTime: placement.start === snap.start ? snap.snapTime : null,
-    snapType: placement.start === snap.start ? snap.snapType : null,
+    snapTime: guide?.time ?? null,
+    snapType: guide?.type ?? null,
   };
 }
 
+/** A snap's guide, kept only when the clip's edge as its file will save it is within a pixel of it. */
+export function guideIfSaved(
+  element: TimelineElement,
+  clip: { start: number; duration?: number },
+  target: TimelineSnapTarget | null,
+  pps: number,
+): TimelineSnapTarget | null {
+  if (!target) return null;
+  const saved = savedClipEdges(element, clip.start, clip.duration);
+  const off = Math.min(Math.abs(saved.start - target.time), Math.abs(saved.end - target.time));
+  return off * pps < 1 ? target : null;
+}
+
 /** One frame: the last visible frame of a clip sits just before its end time. */
 const TRIM_END_FRAME_LEAD_S = 1 / STUDIO_PREVIEW_FPS;
 
@@ -296,6 +316,8 @@ export interface ResizePreviewContext {
   buildSnapTargets: BuildSnapTargets;
   elements?: readonly TimelineElement[];
   gestureKeys?: ReadonlySet<string>;
+  /** Seconds between the ruler's lines; 0 or absent when snapping is off. */
+  gridStep?: number;
 }
 
 export interface ResizePreviewResult {
@@ -362,21 +384,19 @@ export function computeResizePreview(
     effectiveClientX,
   );
 
-  // Snap to beats and clip edges, never the playhead (the dragged edge drives
-  // its own preview seek, so that would be circular). Stay inside the same
-  // limits resolveTimelineResize enforces. The music track defines the
-  // beats, so it must not snap to them, but still snaps to clip edges.
+  // Snap within the same limits resolveTimelineResize enforces. The music
+  // track defines the beats, so it must not snap to them.
   const trimTargets = buildSnapTargets(
     resize.element.key ?? resize.element.id,
     !isMusicTrack(resize.element),
-    false,
   );
+  const gridStep = ctx.gridStep ?? 0;
   let snap: TimelineSnapTarget | null = null;
-  if (trimTargets.length > 0) {
+  if (trimTargets.length > 0 || gridStep > 0) {
     const snapSecs = TIMELINE_SNAP_PX / Math.max(pps, 1);
     if (resize.edge === "end") {
       const edgeTime = nextResize.start + nextResize.duration;
-      const { time: snapped, target } = snapTimelineTime(edgeTime, trimTargets, snapSecs);
+      const { time: snapped, target } = snapTimelineTime(edgeTime, trimTargets, snapSecs, gridStep);
       // Stay within [start+minDuration, maxEnd] so the snap can't create a
       // degenerate clip or run past the source/composition limit.
       const snappedDuration = Math.round((snapped - nextResize.start) * 1000) / 1000;
@@ -387,16 +407,21 @@ export function computeResizePreview(
       ) {
         // An edge already on the target still owns the guide; only move it when off.
         if (snapped !== edgeTime) nextResize = { ...nextResize, duration: snappedDuration };
-        snap = target;
+        snap = guideIfSaved(resize.element, nextResize, target, pps);
       }
     } else {
-      const { time: snapped, target } = snapTimelineTime(nextResize.start, trimTargets, snapSecs);
+      const { time: snapped, target } = snapTimelineTime(
+        nextResize.start,
+        trimTargets,
+        snapSecs,
+        gridStep,
+      );
       const clip = { ...nextResize, playbackRate: resize.element.playbackRate };
       const delta = snapped - nextResize.start;
       const bounds = clipStartTrimDeltaBounds(clip, minStart, resolveTimelineMinDuration());
       if (target && delta >= bounds.minDelta - 1e-6 && delta <= bounds.maxDelta + 1e-6) {
         if (snapped !== nextResize.start) nextResize = applyClipStartTrimDelta(clip, delta);
-        snap = target;
+        snap = guideIfSaved(resize.element, nextResize, target, pps);
       }
     }
   }

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

@@ -18,7 +18,11 @@ import {
   resolveTimelineAssetDrop,
   getTimelineBeatEntries,
 } from "./timelineLayout";
-import { generateTicks, getTimelineMajorTickInterval } from "./timelineRulerGeometry";
+import {
+  generateTicks,
+  getTimelineGridStep,
+  getTimelineMajorTickInterval,
+} from "./timelineRulerGeometry";
 import { resolveInsertRow } from "./timelineCollision";
 import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
 
@@ -42,6 +46,25 @@ describe("horizontal timeline window", () => {
     expect(ticks.major.length + ticks.minor.length).toBeLessThan(100);
   });
 
+  it("spaces the snap grid exactly like the ruler's drawn lines at each zoom", () => {
+    for (const [pps, fps] of [
+      [100, undefined],
+      [12, undefined],
+      [900, undefined],
+      [100, 30],
+      [3, 30],
+    ] as const) {
+      const { major, minor } = generateTicks(60, pps, fps);
+      const lines = [...major, ...minor].sort((a, b) => a - b);
+      expect(getTimelineGridStep(60, pps, fps)).toBeCloseTo(lines[1]! - lines[0]!, 6);
+    }
+  });
+
+  it("has no snap grid where the ruler draws no lines", () => {
+    expect(generateTicks(20_000, 100)).toEqual({ major: [], minor: [] });
+    expect(getTimelineGridStep(20_000, 100)).toBe(0);
+  });
+
   it("slices beat records with original strength indexes and unions a pinned beat", () => {
     expect(
       getTimelineBeatEntries(

package/src/player/components/timelineRulerGeometry.ts

@@ -1,4 +1,5 @@
-import { formatTime } from "../lib/time";
+import { formatTime, STUDIO_PREVIEW_FPS } from "../lib/time";
+import type { TimelineTimeDisplayMode } from "../../utils/studioUiPreferences";
 import type { TimelineTimeRange } from "../lib/timelineClipIndex";
 
 // fallow-ignore-next-line complexity
@@ -87,6 +88,27 @@ function appendMinorTicks(
   }
 }
 
+function tickSpacing(duration: number, pixelsPerSecond?: number, frameRate?: number) {
+  const majorInterval = getTimelineMajorTickInterval(duration, pixelsPerSecond, frameRate);
+  const subdivisions = getMinorSubdivisions(majorInterval, pixelsPerSecond, frameRate);
+  return { majorInterval, subdivisions };
+}
+
+export function rulerFrameRate(mode: TimelineTimeDisplayMode): number | undefined {
+  return mode === "frame" ? STUDIO_PREVIEW_FPS : undefined;
+}
+
+/** Seconds between neighbouring ruler lines (minor ticks when drawn, else major): the snap grid. */
+export function getTimelineGridStep(
+  duration: number,
+  pixelsPerSecond?: number,
+  frameRate?: number,
+): number {
+  if (!isSupportedTickDuration(duration)) return 0;
+  const { majorInterval, subdivisions } = tickSpacing(duration, pixelsPerSecond, frameRate);
+  return subdivisions > 0 ? majorInterval / subdivisions : majorInterval;
+}
+
 export function generateTicks(
   duration: number,
   pixelsPerSecond?: number,
@@ -94,8 +116,7 @@ export function generateTicks(
   range?: TimelineTimeRange,
 ): { major: number[]; minor: number[] } {
   if (!isSupportedTickDuration(duration)) return { major: [], minor: [] };
-  const majorInterval = getTimelineMajorTickInterval(duration, pixelsPerSecond, frameRate);
-  const subdivisions = getMinorSubdivisions(majorInterval, pixelsPerSecond, frameRate);
+  const { majorInterval, subdivisions } = tickSpacing(duration, pixelsPerSecond, frameRate);
   const minorInterval = subdivisions > 0 ? majorInterval / subdivisions : 0;
   const major: number[] = [];
   const minor: number[] = [];

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

@@ -27,18 +27,6 @@ describe("collectTimelineSnapTargets", () => {
     expect(targets).toContainEqual({ time: 0.5, type: "beat" });
   });
 
-  it("omits the playhead when includePlayhead is false, for a trim", () => {
-    const targets = collectTimelineSnapTargets({
-      elements,
-      playheadTime: 7.25,
-      beatTimes: [0.5],
-      includePlayhead: false,
-    });
-    expect(targets.some((t) => t.type === "playhead")).toBe(false);
-    expect(targets).toContainEqual({ time: 2, type: "clip-edge" });
-    expect(targets).toContainEqual({ time: 0.5, type: "beat" });
-  });
-
   it("excludes the dragged element's own edges", () => {
     const targets = collectTimelineSnapTargets({
       elements,
@@ -90,6 +78,35 @@ describe("snapTimelineTime", () => {
   it("returns input unchanged when nothing is within threshold", () => {
     expect(snapTimelineTime(6, targets, 0.1)).toEqual({ time: 6, target: null });
   });
+
+  it("snaps to the nearest ruler line when no target is in range", () => {
+    expect(snapTimelineTime(6.27, targets, 0.08, 0.25)).toEqual({
+      time: 6.25,
+      target: { time: 6.25, type: "grid" },
+    });
+    expect(snapTimelineTime(6.37, targets, 0.08, 0.25)).toEqual({ time: 6.37, target: null });
+  });
+
+  it("prefers a target in range over a nearer ruler line", () => {
+    expect(snapTimelineTime(5.24, targets, 0.08, 0.25).target).toEqual({
+      time: 5.3,
+      type: "playhead",
+    });
+  });
+
+  it("snaps a line at its saved centisecond, and not at all when that is a pixel or more off", () => {
+    // 187.5 px/s: 4.625s saves as 4.63s, under a pixel away, so the guide sits where the clip lands.
+    expect(snapTimelineTime(4.627, [], 8 / 187.5, 0.125).target).toEqual({
+      time: 4.63,
+      type: "grid",
+    });
+    // 1440 px/s: 1.025s would save 7px off its line, so the line does not snap.
+    expect(snapTimelineTime(1.026, [], 8 / 1440, 0.025)).toEqual({ time: 1.026, target: null });
+  });
+
+  it("lands on whole frames for a frame-spaced grid", () => {
+    expect(snapTimelineTime(1.01, [], 0.08, 1 / 30).time).toBe(1);
+  });
 });
 
 describe("snapMoveToTargets", () => {
@@ -120,6 +137,20 @@ describe("snapMoveToTargets", () => {
     expect(snapMoveToTargets(5.5, 2, targets, 1000, 60).snapTime).toBeNull();
   });
 
+  it("snaps a clip edge to the ruler grid when no target is near", () => {
+    expect(snapMoveToTargets(1.02, 2, [], 100, 60, 0.25)).toEqual({
+      start: 1,
+      snapTime: 1,
+      snapType: "grid",
+    });
+  });
+
+  it("prefers the edge on a real target over the other edge nearer a ruler line", () => {
+    // start 2.99 is 1px from the 3s line; the end 4.94 is 6px from the playhead at 5
+    const r = snapMoveToTargets(2.99, 1.95, targets, 100, 60, 0.25);
+    expect(r).toEqual({ start: 3.05, snapTime: 5, snapType: "playhead" });
+  });
+
   it("TIMELINE_SNAP_PX matches the historical beat-snap threshold", () => {
     expect(TIMELINE_SNAP_PX).toBe(8);
   });