@hyperframes/studio 0.7.56 → 0.7.57

package/src/hooks/useTimelineGroupEditing.ts

@@ -6,17 +6,20 @@ import {
   buildTimelineMoveTimingPatch,
   buildTimelineResizeTimingPatch,
   extendRootDurationIfNeeded,
-  finishTimelineTimingFallback,
-  foldGsapMutationIntoHistory,
   formatTimelineAttributeNumber,
   patchIframeDomTiming,
   persistTimelineBatchEdit,
-  readFileContent,
-  scaleGsapPositions,
-  shiftGsapPositions,
   type PersistTimelineBatchChange,
   type RecordEditInput,
 } from "./timelineEditingHelpers";
+import {
+  captureDurationRollback,
+  finishGroupTimingGsapFallback,
+  readFileContent,
+  scaleGsapPositions,
+  shiftGsapPositions,
+  syncPreviewContentDuration,
+} from "./timelineTimingSync";
 
 export interface TimelineGroupMoveChange {
   element: TimelineElement;
@@ -75,6 +78,15 @@ function resizeCoalesceKey(changes: readonly TimelineGroupResizeChange[]): strin
   return `timeline-group-resize:${changes.map((change) => change.element.hfId ?? change.element.id).join(",")}`;
 }
 
+function toSdkTimingChanges<T extends { element: TimelineElement }>(
+  changes: readonly T[],
+  timingUpdate: (change: T) => { start: number; duration?: number },
+): Array<{ hfId: string; timingUpdate: { start: number; duration?: number } } | null> {
+  return changes.map((change) =>
+    change.element.hfId ? { hfId: change.element.hfId, timingUpdate: timingUpdate(change) } : null,
+  );
+}
+
 function resizeHasPlaybackStartAdjustment(change: TimelineGroupResizeChange): boolean {
   return (
     change.playbackStart != null ||
@@ -149,6 +161,55 @@ export function useTimelineGroupEditing({
     ],
   );
 
+  // Shared SDK fast path for group move/resize: eligible when nothing needs the
+  // server (no root-duration growth, one shared file, every change SDK-addressable
+  // and `eligible` per the caller's own gate). Returns whether the SDK handled it;
+  // false → caller falls through to the server batch persist.
+  const trySdkBatchPersist = useCallback(
+    async (input: {
+      changes: readonly { element: TimelineElement }[];
+      sdkChanges: Array<{
+        hfId: string;
+        timingUpdate: { start: number; duration?: number };
+      } | null>;
+      eligible: boolean;
+      needsExtension: boolean;
+      label: string;
+      coalesceKey: string;
+    }): Promise<boolean> => {
+      const sharedPath = allChangesSharePath(input.changes, activeCompPath);
+      const canUseSdk =
+        !input.needsExtension &&
+        sharedPath !== null &&
+        input.eligible &&
+        input.sdkChanges.every((change) => change !== null);
+      if (!canUseSdk) return false;
+      return sdkTimingBatchPersist(
+        input.sdkChanges.filter((change): change is NonNullable<typeof change> => change !== null),
+        sharedPath,
+        sdkSession,
+        {
+          editHistory: { recordEdit },
+          writeProjectFile,
+          reloadPreview,
+          domEditSaveTimestampRef,
+          compositionPath: activeCompPath,
+          readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
+        },
+        { label: input.label, coalesceKey: input.coalesceKey },
+      );
+    },
+    [
+      activeCompPath,
+      domEditSaveTimestampRef,
+      projectIdRef,
+      recordEdit,
+      reloadPreview,
+      sdkSession,
+      writeProjectFile,
+    ],
+  );
+
   const handleTimelineGroupMove = useCallback(
     (changes: TimelineGroupMoveChange[], options?: TimelineGroupCommitOptions) => {
       if (changes.length === 0) return Promise.resolve();
@@ -163,38 +224,27 @@ export function useTimelineGroupEditing({
       }
 
       const maxEnd = Math.max(...changes.map((change) => change.start + change.element.duration));
+      // Snapshot the duration BEFORE the optimistic updates below so a failed
+      // persist can roll the readout + live root back (see captureDurationRollback).
+      const rollbackDuration = captureDurationRollback(previewIframeRef.current);
+      // needsExtension gates the SDK path (setTiming can't grow the root duration),
+      // so read the store BEFORE the readout sync below optimistically updates it.
       const needsExtension = extendRootDurationIfNeeded(maxEnd);
+      // Optimistic duration readout: content-driven (grow AND shrink), read from
+      // the just-patched live DOM. See syncPreviewContentDuration.
+      syncPreviewContentDuration(previewIframeRef.current);
       const coalesceKey = options?.coalesceKey ?? moveCoalesceKey(changes);
       return enqueueGroupOperation("Move timeline clips", async (projectId) => {
         await options?.beforeTiming;
-        const sharedPath = allChangesSharePath(changes, activeCompPath);
-        const sdkChanges = changes.map((change) =>
-          change.element.hfId
-            ? { hfId: change.element.hfId, timingUpdate: { start: change.start } }
-            : null,
-        );
-        const canUseSdk =
-          !needsExtension &&
-          sharedPath !== null &&
-          changes.every((change) => change.track == null) &&
-          sdkChanges.every((change) => change !== null);
-        if (canUseSdk) {
-          const handled = await sdkTimingBatchPersist(
-            sdkChanges.filter((change): change is NonNullable<typeof change> => change !== null),
-            sharedPath,
-            sdkSession,
-            {
-              editHistory: { recordEdit },
-              writeProjectFile,
-              reloadPreview,
-              domEditSaveTimestampRef,
-              compositionPath: activeCompPath,
-              readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
-            },
-            { label: "Move timeline clips", coalesceKey },
-          );
-          if (handled) return;
-        }
+        const handledBySdk = await trySdkBatchPersist({
+          changes,
+          sdkChanges: toSdkTimingChanges(changes, (change) => ({ start: change.start })),
+          eligible: changes.every((change) => change.track == null),
+          needsExtension,
+          label: "Move timeline clips",
+          coalesceKey,
+        });
+        if (handledBySdk) return;
 
         await persistServerBatch(
           projectId,
@@ -212,50 +262,39 @@ export function useTimelineGroupEditing({
           })),
           coalesceKey,
         );
-        await finishTimelineTimingFallback({
+        await finishGroupTimingGsapFallback({
+          projectId,
           iframe: previewIframeRef.current,
-          needsExtension,
-          rootDurationSeconds: maxEnd,
           reloadPreview,
-          gsapMutation: () =>
-            foldGsapMutationIntoHistory({
-              projectId,
-              paths: changes.map((change) => targetPathFor(change.element, activeCompPath)),
-              label: "Move timeline clips",
-              coalesceKey,
-              recordEdit,
-              gsapMutation: async () => {
-                let mutated = false;
-                for (const change of changes) {
-                  const delta = change.start - change.element.start;
-                  const domId = change.element.domId;
-                  if (delta === 0 || !domId) continue;
-                  const status = await shiftGsapPositions(
-                    projectId,
-                    targetPathFor(change.element, activeCompPath),
-                    domId,
-                    delta,
-                  );
-                  mutated = mutated || status.mutated;
-                }
-                return { mutated };
-              },
-            }),
-          onGsapError: (err) => console.error("[Timeline] Failed to shift GSAP positions", err),
+          label: "Move timeline clips",
+          errorLabel: "Failed to shift GSAP positions",
+          coalesceKey,
+          recordEdit,
+          activeCompPath,
+          changes,
+          resolveChangePath: (element) => targetPathFor(element, activeCompPath),
+          mutateChange: (change, changePath) => {
+            const delta = change.start - change.element.start;
+            const domId = change.element.domId;
+            if (delta === 0 || !domId) return null;
+            return shiftGsapPositions(projectId, changePath, domId, delta);
+          },
         });
+      }).catch((error) => {
+        // Failed persist: revert the optimistic duration readout + live root
+        // alongside the gesture owner's store rollback.
+        rollbackDuration();
+        throw error;
       });
     },
     [
       activeCompPath,
-      domEditSaveTimestampRef,
       enqueueGroupOperation,
       persistServerBatch,
       previewIframeRef,
-      projectIdRef,
       recordEdit,
       reloadPreview,
-      sdkSession,
-      writeProjectFile,
+      trySdkBatchPersist,
     ],
   );
 
@@ -278,41 +317,30 @@ export function useTimelineGroupEditing({
       }
 
       const maxEnd = Math.max(...changes.map((change) => change.start + change.duration));
+      // Snapshot the duration BEFORE the optimistic updates below so a failed
+      // persist can roll the readout + live root back (see captureDurationRollback).
+      const rollbackDuration = captureDurationRollback(previewIframeRef.current);
+      // needsExtension gates the SDK path (setTiming can't grow the root duration),
+      // so read the store BEFORE the readout sync below optimistically updates it.
       const needsExtension = extendRootDurationIfNeeded(maxEnd);
+      // Optimistic duration readout: content-driven (grow AND shrink), read from
+      // the just-patched live DOM. See syncPreviewContentDuration.
+      syncPreviewContentDuration(previewIframeRef.current);
       const coalesceKey = options?.coalesceKey ?? resizeCoalesceKey(changes);
       return enqueueGroupOperation("Resize timeline clips", async (projectId) => {
         await options?.beforeTiming;
-        const sharedPath = allChangesSharePath(changes, activeCompPath);
-        const sdkChanges = changes.map((change) =>
-          change.element.hfId
-            ? {
-                hfId: change.element.hfId,
-                timingUpdate: { start: change.start, duration: change.duration },
-              }
-            : null,
-        );
-        const canUseSdk =
-          !needsExtension &&
-          sharedPath !== null &&
-          changes.every((change) => !resizeHasPlaybackStartAdjustment(change)) &&
-          sdkChanges.every((change) => change !== null);
-        if (canUseSdk) {
-          const handled = await sdkTimingBatchPersist(
-            sdkChanges.filter((change): change is NonNullable<typeof change> => change !== null),
-            sharedPath,
-            sdkSession,
-            {
-              editHistory: { recordEdit },
-              writeProjectFile,
-              reloadPreview,
-              domEditSaveTimestampRef,
-              compositionPath: activeCompPath,
-              readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
-            },
-            { label: "Resize timeline clips", coalesceKey },
-          );
-          if (handled) return;
-        }
+        const handledBySdk = await trySdkBatchPersist({
+          changes,
+          sdkChanges: toSdkTimingChanges(changes, (change) => ({
+            start: change.start,
+            duration: change.duration,
+          })),
+          eligible: changes.every((change) => !resizeHasPlaybackStartAdjustment(change)),
+          needsExtension,
+          label: "Resize timeline clips",
+          coalesceKey,
+        });
+        if (handledBySdk) return;
 
         await persistServerBatch(
           projectId,
@@ -328,55 +356,48 @@ export function useTimelineGroupEditing({
           })),
           coalesceKey,
         );
-        await finishTimelineTimingFallback({
+        await finishGroupTimingGsapFallback({
+          projectId,
           iframe: previewIframeRef.current,
-          needsExtension,
-          rootDurationSeconds: maxEnd,
           reloadPreview,
-          gsapMutation: () =>
-            foldGsapMutationIntoHistory({
+          label: "Resize timeline clips",
+          errorLabel: "Failed to scale GSAP positions",
+          coalesceKey,
+          recordEdit,
+          activeCompPath,
+          changes,
+          resolveChangePath: (element) => targetPathFor(element, activeCompPath),
+          mutateChange: (change, changePath) => {
+            const domId = change.element.domId;
+            const timingChanged =
+              change.start !== change.element.start || change.duration !== change.element.duration;
+            if (!timingChanged || !domId) return null;
+            return scaleGsapPositions(
               projectId,
-              paths: changes.map((change) => targetPathFor(change.element, activeCompPath)),
-              label: "Resize timeline clips",
-              coalesceKey,
-              recordEdit,
-              gsapMutation: async () => {
-                let mutated = false;
-                for (const change of changes) {
-                  const domId = change.element.domId;
-                  const timingChanged =
-                    change.start !== change.element.start ||
-                    change.duration !== change.element.duration;
-                  if (!timingChanged || !domId) continue;
-                  const status = await scaleGsapPositions(
-                    projectId,
-                    targetPathFor(change.element, activeCompPath),
-                    domId,
-                    change.element.start,
-                    change.element.duration,
-                    change.start,
-                    change.duration,
-                  );
-                  mutated = mutated || status.mutated;
-                }
-                return { mutated };
-              },
-            }),
-          onGsapError: (err) => console.error("[Timeline] Failed to scale GSAP positions", err),
+              changePath,
+              domId,
+              change.element.start,
+              change.element.duration,
+              change.start,
+              change.duration,
+            );
+          },
         });
+      }).catch((error) => {
+        // Failed persist: revert the optimistic duration readout + live root
+        // alongside the gesture owner's store rollback.
+        rollbackDuration();
+        throw error;
       });
     },
     [
       activeCompPath,
-      domEditSaveTimestampRef,
       enqueueGroupOperation,
       persistServerBatch,
       previewIframeRef,
-      projectIdRef,
       recordEdit,
       reloadPreview,
-      sdkSession,
-      writeProjectFile,
+      trySdkBatchPersist,
     ],
   );
 

package/src/player/components/PlayerControls.tsx

@@ -9,10 +9,8 @@ import { Tooltip } from "../../components/ui";
 import { ShortcutsPanel } from "./ShortcutsPanel";
 import { SpeedMenu } from "./SpeedMenu";
 import { useSeekBarDrag, resolveSeekPercent } from "./useSeekBarDrag";
-import { useState } from "react";
 
 export { resolveSeekPercent };
-type TimeDisplayMode = "time" | "frame";
 
 /* ── Icon sub-components ─────────────────────────────────────────── */
 
@@ -369,7 +367,8 @@ export const PlayerControls = memo(function PlayerControls({
   const outPoint = usePlayerStore((s) => s.outPoint);
   const setInPoint = usePlayerStore.getState().setInPoint;
   const setOutPoint = usePlayerStore.getState().setOutPoint;
-  const [timeDisplayMode, setTimeDisplayMode] = useState<TimeDisplayMode>("time");
+  const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
+  const setTimeDisplayMode = usePlayerStore.getState().setTimeDisplayMode;
 
   const progressFillRef = useRef<HTMLDivElement>(null);
   const progressThumbRef = useRef<HTMLDivElement>(null);
@@ -428,10 +427,11 @@ export const PlayerControls = memo(function PlayerControls({
 
   return (
     <div
+      // No own background/border: the transport blends into the preview
+      // panel's surface — buttons carry their own chrome.
       className="px-4 py-2 flex flex-wrap items-center gap-x-2 gap-y-1"
       aria-disabled={disabled || undefined}
       style={{
-        borderTop: "1px solid rgba(255,255,255,0.04)",
         paddingBottom: "calc(0.5rem + env(safe-area-inset-bottom))",
       }}
     >
@@ -456,7 +456,7 @@ export const PlayerControls = memo(function PlayerControls({
       >
         <button
           type="button"
-          onClick={() => setTimeDisplayMode((m) => (m === "time" ? "frame" : "time"))}
+          onClick={() => setTimeDisplayMode(timeDisplayMode === "time" ? "frame" : "time")}
           disabled={disabled}
           className="font-mono text-[11px] tabular-nums flex-shrink-0 w-[118px] text-left transition-colors disabled:pointer-events-none hover:opacity-80"
           style={{ color: "#A1A1AA", cursor: "pointer" }}

package/src/player/components/PlayheadIndicator.tsx

@@ -9,6 +9,8 @@
  * no matter how far the tracks are scrolled. The head is OUTLINE-only at rest and
  * FILLED while the playhead is actively held/scrubbed (`scrubbing`).
  */
+import { PLAYHEAD_HEAD_W } from "./timelineLayout";
+
 interface PlayheadIndicatorProps {
   /** CSS color, defaults to the HF accent variable */
   color?: string;
@@ -31,8 +33,11 @@ export function PlayheadIndicator({
 }: PlayheadIndicatorProps) {
   // Head chip dimensions — used to compute the centering offset and the
   // point where the vertical line starts (so it begins at the head's bottom
-  // edge rather than running through the hollow diamond center).
-  const HEAD_W = 9;
+  // edge rather than running through the hollow diamond center). The width is
+  // the shared PLAYHEAD_HEAD_W constant: getTimelinePlayheadLeft shifts the
+  // wrapper by -PLAYHEAD_HEAD_W/2 so the 1px line (centered at 50% of the
+  // wrapper) lands exactly on GUTTER + time * pps — the ruler ticks' center x.
+  const HEAD_W = PLAYHEAD_HEAD_W;
   const HEAD_H = 9;
   // marginTop(1) + HEAD_H = where the line should start.
   const HEAD_TOTAL_H = 1 + HEAD_H;

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

@@ -19,8 +19,10 @@ import {
   shouldAutoScrollTimeline,
 } from "./Timeline";
 import {
+  FIT_ZOOM_HEADROOM,
   GUTTER,
   MIN_TIMELINE_EXTENT_S,
+  PLAYHEAD_HEAD_W,
   RULER_H,
   TRACK_H,
   getTimelineDisplayContentWidth,
@@ -327,6 +329,60 @@ describe("generateTicks", () => {
     const { major } = generateTicks(180, 80);
     expect(major[1] - major[0]).toBe(2);
   });
+
+  it("picks 'nice' NLE steps across zoom levels (no 7s-style intervals)", () => {
+    // step = first nice interval whose px spacing >= 88 at that pps.
+    const cases: Array<[number, number]> = [
+      [2, 60], // 60s * 2pps = 120px
+      [10, 10], // 10s * 10pps = 100px
+      [20, 5], // 5s * 20pps = 100px
+      [50, 2], // 2s * 50pps = 100px
+      [100, 1], // 1s * 100pps = 100px
+    ];
+    for (const [pps, expected] of cases) {
+      const { major } = generateTicks(600, pps);
+      expect(major[1] - major[0]).toBe(expected);
+    }
+  });
+
+  it("uses minute/hour steps when zoomed far out instead of colliding 10m labels", () => {
+    // 0.05 pps → 600s step would be 30px apart (labels collide); 1800s = 90px.
+    const { major } = generateTicks(7200, 0.05);
+    expect(major[1] - major[0]).toBe(1800);
+    expect(major).toContain(3600);
+  });
+
+  it("does not drift on long rulers (ticks are exact multiples of the step)", () => {
+    const { major } = generateTicks(600, 100); // 1s step, 601 ticks
+    expect(major[599]).toBe(599);
+  });
+
+  describe("frame display mode (frameRate provided)", () => {
+    it("snaps sub-frame steps up to one whole frame (no duplicate frame labels)", () => {
+      // 4400 pps would pick a 0.02s step = 0.6 frames at 30fps → snapped to 1 frame.
+      const { major } = generateTicks(2, 4400, 30);
+      const frames = major.map((t) => Math.round(t * 30));
+      // Frame labels are consecutive integers — no duplicates, no gaps.
+      frames.forEach((f, i) => expect(f).toBe(i));
+    });
+
+    it("keeps major AND minor ticks on whole frames", () => {
+      // 200 pps → 0.5s step (15 frames); quarters (3.75f) are rejected in
+      // frame mode in favour of fifths (3f).
+      const { major, minor } = generateTicks(20, 200, 30);
+      expect(major[1]).toBeCloseTo(0.5);
+      expect(minor).toContain(0.1); // 3 frames
+      for (const t of [...major, ...minor]) {
+        const frames = t * 30;
+        expect(Math.abs(frames - Math.round(frames))).toBeLessThan(1e-3);
+      }
+    });
+
+    it("leaves whole-second steps unchanged", () => {
+      const { major } = generateTicks(60, 100, 30);
+      expect(major[1] - major[0]).toBe(1);
+    });
+  });
 });
 
 describe("formatTime", () => {
@@ -397,19 +453,33 @@ describe("shouldAutoScrollTimeline", () => {
   });
 });
 
-describe("getTimelineFitPps (min 60s extent)", () => {
+describe("getTimelineFitPps (min 60s extent + fit headroom)", () => {
   const viewport = 632; // usable width = 632 - GUTTER - 2 = 598
 
   it("computes fit pps against the 60s floor for short compositions", () => {
     // A 10s comp maps 60s onto the viewport → the comp takes ~1/6 of the width.
+    // (10 * 1.2 = 12s of headroom-padded content is still under the 60s floor.)
     const pps = getTimelineFitPps(viewport, 10);
     expect(pps).toBeCloseTo((viewport - GUTTER - 2) / MIN_TIMELINE_EXTENT_S);
     expect(10 * pps).toBeCloseTo((viewport - GUTTER - 2) / 6);
   });
 
-  it("keeps filling the viewport with the composition when it is 60s or longer", () => {
-    expect(getTimelineFitPps(viewport, 60)).toBeCloseTo((viewport - GUTTER - 2) / 60);
-    expect(getTimelineFitPps(viewport, 120)).toBeCloseTo((viewport - GUTTER - 2) / 120);
+  it("fits duration * FIT_ZOOM_HEADROOM (not the bare duration) for long compositions", () => {
+    expect(getTimelineFitPps(viewport, 60)).toBeCloseTo(
+      (viewport - GUTTER - 2) / (60 * FIT_ZOOM_HEADROOM),
+    );
+    expect(getTimelineFitPps(viewport, 120)).toBeCloseTo(
+      (viewport - GUTTER - 2) / (120 * FIT_ZOOM_HEADROOM),
+    );
+  });
+
+  it("leaves CapCut-style trailing headroom: the comp ends at 1/1.2 of the usable width", () => {
+    const usable = viewport - GUTTER - 2;
+    const pps = getTimelineFitPps(viewport, 120);
+    // Composition content occupies usable/1.2 px; the remaining ~17% is empty
+    // droppable ruler/lane surface past the end.
+    expect(120 * pps).toBeCloseTo(usable / FIT_ZOOM_HEADROOM);
+    expect(120 * pps).toBeLessThan(usable);
   });
 
   it("falls back to 100 pps before the viewport is measured", () => {
@@ -529,13 +599,20 @@ describe("getTimelineScrollLeftForZoomAnchor", () => {
 });
 
 describe("getTimelinePlayheadLeft", () => {
-  it("converts time to a pixel offset from the gutter", () => {
-    expect(getTimelinePlayheadLeft(4, 20)).toBe(112);
+  it("offsets the wrapper by half the head width so the line CENTER = GUTTER + t*pps", () => {
+    // Wrapper left + PLAYHEAD_HEAD_W/2 (where the 1px line is centered) must
+    // equal GUTTER + t*pps at any zoom.
+    expect(getTimelinePlayheadLeft(4, 20) + PLAYHEAD_HEAD_W / 2).toBe(GUTTER + 4 * 20);
+    expect(getTimelinePlayheadLeft(10, 7.5) + PLAYHEAD_HEAD_W / 2).toBe(GUTTER + 75);
+  });
+
+  it("centers the line exactly on the gutter (the 00:00 tick) at t = 0", () => {
+    expect(getTimelinePlayheadLeft(0, 20) + PLAYHEAD_HEAD_W / 2).toBe(GUTTER);
   });
 
   it("guards invalid input", () => {
-    expect(getTimelinePlayheadLeft(Number.NaN, 20)).toBe(32);
-    expect(getTimelinePlayheadLeft(4, Number.NaN)).toBe(32);
+    expect(getTimelinePlayheadLeft(Number.NaN, 20)).toBe(GUTTER - PLAYHEAD_HEAD_W / 2);
+    expect(getTimelinePlayheadLeft(4, Number.NaN)).toBe(GUTTER - PLAYHEAD_HEAD_W / 2);
   });
 });
 

package/src/player/components/Timeline.tsx

@@ -26,6 +26,7 @@ import {
   getTimelineCanvasHeight,
   shouldShowTimelineShortcutHint,
 } from "./timelineLayout";
+import { STUDIO_PREVIEW_FPS } from "../lib/time";
 import { useResolvedTimelineEditCallbacks } from "./useResolvedTimelineEditCallbacks";
 import type { TimelineProps } from "./TimelineTypes";
 
@@ -95,6 +96,7 @@ export const Timeline = memo(function Timeline({
     [beatAnalysis, musicElement, beatEdits],
   );
   const duration = usePlayerStore((s) => s.duration);
+  const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
   const timelineReady = usePlayerStore((s) => s.timelineReady);
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
   const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
@@ -156,11 +158,8 @@ export const Timeline = memo(function Timeline({
     containerRef.current = el;
   }, []);
 
-  // Last horizontal scroll offset, tracked so it can be RESTORED across the
-  // post-edit iframe reload: an edit re-derives elements (and may shrink the
-  // content width), which the browser clamps into a scroll jump. Paired with the
-  // pinned zoom (which keeps pps constant so the pixel offset stays meaningful),
-  // restoring this keeps the user parked at the same spot after any edit.
+  // Last horizontal scroll offset, RESTORED across the post-edit iframe reload (which clamps into
+  // a scroll jump); with the pinned zoom this keeps the user parked at the same spot after edits.
   const lastScrollLeftRef = useRef(0);
   const setScrollRef = useCallback(
     (el: HTMLDivElement | null) => {
@@ -395,9 +394,11 @@ export const Timeline = memo(function Timeline({
     }
   });
 
+  // Frame display mode labels ruler ticks as frame numbers — pass the fps so ticks snap to frames.
+  const tickFps = timeDisplayMode === "frame" ? STUDIO_PREVIEW_FPS : undefined;
   const { major, minor } = useMemo(
-    () => generateTicks(displayDuration, pps),
-    [displayDuration, pps],
+    () => generateTicks(displayDuration, pps, tickFps),
+    [displayDuration, pps, tickFps],
   );
   const majorTickInterval = major.length >= 2 ? major[1] - major[0] : effectiveDuration;
 
@@ -526,8 +527,7 @@ export const Timeline = memo(function Timeline({
             const elKey = el.key ?? el.id;
             setSelectedElementId(elKey);
             onSelectElement?.(el);
-            // Visually select the clicked diamond (matches shift-click / motion-path
-            // selection); cleared above so this single-selects it.
+            // Select the clicked diamond (matches shift-click); cleared above so this single-selects.
             toggleSelectedKeyframe(`${elKey}:${pct}`);
             const absTime = el.start + (pct / 100) * el.duration;
             onSeek?.(absTime);

package/src/player/components/TimelineCanvas.tsx

@@ -10,6 +10,8 @@ import {
   CLIP_Y,
   TRACKS_TOP_PAD,
   TRACKS_BOTTOM_PAD,
+  PLAYHEAD_HEAD_W,
+  getTimelinePlayheadLeft,
   getTimelineRowTop,
 } from "./timelineLayout";
 import { usePlayerStore } from "../store/playerStore";
@@ -20,6 +22,7 @@ import type { Rect } from "../../utils/marqueeGeometry";
 import { TimelineClip } from "./TimelineClip";
 import { TimelineLanes, type TimelineLaneBaseProps } from "./TimelineLanes";
 import { renderClipChildren } from "./timelineClipChildren";
+import { useTimelineRevealClip } from "./useTimelineRevealClip";
 
 interface TimelineCanvasProps extends TimelineLaneBaseProps {
   major: number[];
@@ -41,6 +44,8 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
   const { onResizeElement, onMoveElement, onToggleTrackHidden, onRazorSplit, onRazorSplitAll } =
     useTimelineEditContextOptional();
   const beatDragging = usePlayerStore((s) => s.beatDragging);
+  // Scroll a clip into view when the sidebar (asset card) requests a reveal.
+  useTimelineRevealClip(scrollRef);
   const draggedElement = draggedClip?.element ?? null;
   const activeDraggedElement =
     draggedClip?.started === true && draggedElement
@@ -259,12 +264,16 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
       )}
 
       {/* Playhead — hidden while dragging a beat so its guideline doesn't
-          track the scrub and clutter the beat being moved. */}
+          track the scrub and clutter the beat being moved. Explicit width +
+          the half-head offset baked into getTimelinePlayheadLeft keep the
+          inner 1px line's CENTER exactly on GUTTER + t * pps (the ruler
+          ticks' center), instead of relying on shrink-wrap sizing. */}
       <div
         ref={props.playheadRef}
         className="absolute top-0 bottom-0 pointer-events-none"
         style={{
-          left: `${GUTTER}px`,
+          left: `${getTimelinePlayheadLeft(0, 0)}px`,
+          width: PLAYHEAD_HEAD_W,
           zIndex: 100,
           display: beatDragging ? "none" : undefined,
         }}