@hyperframes/studio 0.7.56 → 0.7.57

package/src/player/components/TimelineRuler.tsx

@@ -1,6 +1,8 @@
 import { memo } from "react";
 import type { TimelineTheme } from "./timelineTheme";
 import { GUTTER, RULER_H, formatTimelineTickLabel } from "./timelineLayout";
+import { usePlayerStore } from "../store/playerStore";
+import { secondsToFrame } from "../lib/time";
 import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
 
 interface TimelineRulerProps {
@@ -26,6 +28,7 @@ export const TimelineRuler = memo(function TimelineRuler({
   theme,
   beatAnalysis,
 }: TimelineRulerProps) {
+  const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
   const beatTimes = beatAnalysis?.beatTimes ?? [];
   const beatStrengths = beatAnalysis?.beatStrengths ?? [];
 
@@ -38,27 +41,13 @@ export const TimelineRuler = memo(function TimelineRuler({
 
   return (
     <>
-      {/* Grid lines (major ticks + beat lines) — behind the tracks (background).
-          Opaque track rows hide them; only the beat dots show on tracks. */}
+      {/* Background SVG — beat lines only; major-tick gridlines removed so only
+          the ruler's own small ticks mark intervals (no full-height lines). */}
       <svg
         className="absolute pointer-events-none"
         style={{ left: GUTTER, width: trackContentWidth, zIndex: 0 }}
         height={totalH}
       >
-        {major.map((t) => {
-          const x = t * pps;
-          return (
-            <line
-              key={`g-${t}`}
-              x1={x}
-              y1={RULER_H}
-              x2={x}
-              y2={totalH}
-              stroke={theme.tickMinor}
-              strokeWidth="1"
-            />
-          );
-        })}
         {showBeats &&
           beatTimes.map((t, i) => {
             const x = t * pps;
@@ -79,41 +68,62 @@ export const TimelineRuler = memo(function TimelineRuler({
           })}
       </svg>
 
-      {/* Ruler. The bar fills the full panel width (canvas is min 100% wide);
-          calc(100% - GUTTER) equals trackContentWidth when zoomed in and extends
-          past the content when zoomed out. Ticks stay at composition coordinates. */}
+      {/* Ruler — sticky so the timestamps stay visible while the tracks scroll
+          vertically. Opaque background (plus the gutter corner block) so clips
+          scrolling underneath don't bleed through; z-index sits above the track
+          rows and drag overlays but below the playhead (z 100). */}
       <div
-        className="relative overflow-hidden"
-        style={{
-          height: RULER_H,
-          marginLeft: GUTTER,
-          width: `calc(100% - ${GUTTER}px)`,
-          background: theme.gutterBackground,
-          borderBottom: `1px solid ${theme.rulerBorder}`,
-        }}
+        className="sticky top-0 flex"
+        style={{ height: RULER_H, width: GUTTER + trackContentWidth, zIndex: 70 }}
       >
-        {minor.map((t) => (
-          <div key={`m-${t}`} className="absolute bottom-0" style={{ left: t * pps }}>
-            <div className="w-px h-2" style={{ background: theme.tickMinor }} />
-          </div>
-        ))}
+        <div
+          className="sticky left-0 z-[12] flex-shrink-0"
+          style={{
+            width: GUTTER,
+            // Ruler corner uses the panel surface — same as the ruler strip itself.
+            background: theme.shellBackground,
+            borderRight: `1px solid ${theme.gutterBorder}`,
+          }}
+        />
+        <div
+          className="relative overflow-hidden"
+          style={{
+            height: RULER_H,
+            width: trackContentWidth,
+            // Ruler background = panel surface (#0A0A0B) — no bottom border,
+            // no tick lines (CapCut-style clean ruler, labels only).
+            background: theme.shellBackground,
+          }}
+        >
+          {/* Each 1px tick line is shifted -0.5px so its CENTER sits exactly on
+              t * pps — matching the playhead line, which is also centered on
+              GUTTER + t * pps (see getTimelinePlayheadLeft). Without the shift
+              a tick spans [x, x+1) and its center is half a pixel right. */}
+          {minor.map((t) => (
+            <div key={`m-${t}`} className="absolute bottom-0" style={{ left: t * pps - 0.5 }}>
+              <div className="w-px h-2" style={{ background: theme.tickMinor }} />
+            </div>
+          ))}
 
-        {major.map((t) => (
-          <div key={`M-${t}`} className="absolute top-0" style={{ left: t * pps }}>
-            <span
-              className="absolute font-mono tabular-nums leading-none whitespace-nowrap"
-              style={{
-                color: theme.tickText,
-                left: 5,
-                top: 5,
-                fontSize: 10,
-              }}
-            >
-              {formatTimelineTickLabel(t, effectiveDuration, majorTickInterval)}
-            </span>
-            <div className="w-px" style={{ height: RULER_H, background: theme.tickMajor }} />
-          </div>
-        ))}
+          {major.map((t) => (
+            <div key={`M-${t}`} className="absolute top-0" style={{ left: t * pps - 0.5 }}>
+              <span
+                className="absolute font-mono tabular-nums leading-none whitespace-nowrap"
+                style={{
+                  color: theme.tickText,
+                  left: 5,
+                  top: 5,
+                  fontSize: 10,
+                }}
+              >
+                {timeDisplayMode === "frame"
+                  ? secondsToFrame(t)
+                  : formatTimelineTickLabel(t, effectiveDuration, majorTickInterval)}
+              </span>
+              <div className="w-px" style={{ height: RULER_H, background: theme.tickMajor }} />
+            </div>
+          ))}
+        </div>
       </div>
     </>
   );

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

@@ -219,6 +219,88 @@ describe("commitDraggedClipMove", () => {
     expect(map.b).toBeUndefined(); // the other clip is NOT rewritten
   });
 
+  it("persists a lane change in AUTHORED track space when the file is sparse", () => {
+    // Discovery normalized authored tracks {1, 2} to display lanes {0, 1}
+    // (authoredTrack records the file value). Moving 'a' onto b's lane must
+    // write b's AUTHORED track (2) — writing the display lane (1) would target
+    // a's own authored row and silently no-op in the file.
+    const elements = [
+      { ...el("a", 0, 0, 3), authoredTrack: 1 },
+      { ...el("b", 1, 10, 3), authoredTrack: 2 },
+    ];
+    const { updateElement, onMoveElements } = runClipMove(
+      drag(elements[0], { previewStart: 20, previewTrack: 1, desiredTrack: 1 }),
+      { elements, trackOrder: [0, 1] },
+    );
+    // Store stays in display-lane space, but authoredTrack is refreshed to the
+    // value just written to the file so a SECOND drag before any reload resolves
+    // authored tracks from current data, not the stale pre-edit value.
+    expect(updateElement).toHaveBeenCalledWith("a", { start: 20, track: 1, authoredTrack: 2 });
+    // ...while the persist is translated to the target lane's authored track.
+    const map = editMap(onMoveElements.mock.calls[0][0]);
+    expect(map.a).toEqual({ start: 20, track: 2 });
+  });
+
+  it("resolves the authored track from occupants of the dragged clip's OWN source file", () => {
+    // Expanded sub-comp children live on synthetic display lanes next to host
+    // clips. Their authoredTrack is in THEIR file's coordinate space, so a lane
+    // occupied by a clip from a DIFFERENT file must never lend its authored
+    // value. Here lane 1 holds both a host-file clip (authored 12) and a
+    // same-file sibling (authored 7): the sibling answers.
+    const child3 = { ...el("c3", 0, 0, 3), authoredTrack: 3, sourceFile: "scene.html" };
+    const child7 = { ...el("c7", 1, 10, 3), authoredTrack: 7, sourceFile: "scene.html" };
+    const hostClip = { ...el("h", 1, 20, 3), authoredTrack: 12, sourceFile: "index.html" };
+    const elements = [child3, child7, hostClip];
+    const { onMoveElements } = runClipMove(
+      drag(child3, { previewStart: 0, previewTrack: 1, desiredTrack: 1 }),
+      { elements, trackOrder: [0, 1] },
+    );
+    const map = editMap(onMoveElements.mock.calls[0][0]);
+    expect(map.c3).toEqual({ start: 0, track: 7 });
+  });
+
+  it("never persists the display-lane integer when the target lane has no same-file occupant", () => {
+    // Reviewer scenario: an expanded child of a SPARSE file (authored tracks 3
+    // and 7 → display lanes 4 and 5) dragged onto display lane 6, which holds
+    // only another file's clip. Persisting 6 (the display integer) or 12 (the
+    // foreign authored value) would corrupt the sparse file; the fallback
+    // offsets from the NEAREST same-file lane instead: authored 7 at lane 5,
+    // one lane further down → 8.
+    const child3 = { ...el("c3", 4, 0, 3), authoredTrack: 3, sourceFile: "scene.html" };
+    const child7 = { ...el("c7", 5, 10, 3), authoredTrack: 7, sourceFile: "scene.html" };
+    const foreign = { ...el("f", 6, 20, 3), authoredTrack: 12, sourceFile: "index.html" };
+    const elements = [child3, child7, foreign];
+    const { onMoveElements } = runClipMove(
+      drag(child3, { previewStart: 0, previewTrack: 6, desiredTrack: 6 }),
+      { elements, trackOrder: [4, 5, 6] },
+    );
+    const map = editMap(onMoveElements.mock.calls[0][0]);
+    expect(map.c3.track).not.toBe(6); // not the display-lane integer
+    expect(map.c3.track).not.toBe(12); // not the foreign file's authored value
+    expect(map.c3).toEqual({ start: 0, track: 8 });
+  });
+
+  it("dropping onto an overlap spill sub-lane persists the base lane's shared authored track", () => {
+    // Authored track 2 holds two time-overlapping clips, which packTrackLanes
+    // spills onto display sub-lanes 1 and 2 (both authoredTrack 2). Dropping
+    // 'a' onto the spill sub-lane (2) is a legitimate same-track join: the
+    // persisted value is the shared authored track (2), even though the clip
+    // may re-pack onto a different sub-lane on the next normalize.
+    const elements = normalizeToZones([
+      { ...el("a", 0, 30, 3), authoredTrack: 1 },
+      { ...el("b1", 2, 0, 5), authoredTrack: 2 },
+      { ...el("b2", 2, 3, 5), authoredTrack: 2 }, // overlaps b1 → spills
+    ]);
+    expect(elements.map((e) => e.track)).toEqual([0, 1, 2]); // spill happened
+    const spillLane = elements.find((e) => e.id === "b2")!.track;
+    const { onMoveElements } = runClipMove(
+      drag(elements[0], { previewStart: 30, previewTrack: spillLane, desiredTrack: spillLane }),
+      { elements, trackOrder: [0, 1, 2] },
+    );
+    const map = editMap(onMoveElements.mock.calls[0][0]);
+    expect(map.a).toEqual({ start: 30, track: 2 });
+  });
+
   it("multi-selection time-move shifts EVERY selected clip by the drag delta (atomic)", () => {
     const elements = [el("a", 0, 2, 3), el("b", 1, 10, 3), el("c", 2, 20, 3)];
     // Drag 'a' +5s on its own lane while {a, b} are marquee-selected.
@@ -283,8 +365,9 @@ describe("commitDraggedClipMove", () => {
     const map = editMap(onMoveElements.mock.calls[0][0]);
     // Lanes are contiguous and distinct (no two overlapping clips share a lane).
     expect(new Set([map.a.track, map.b.track, map.c.track])).toEqual(new Set([0, 1, 2]));
-    // The z-aware normalization may reverse the authored lane numbers, but the
-    // insert must still leave three distinct, contiguous visual lanes.
+    expect(map.a.track).toBe(0); // above the insert → unchanged
+    expect(map.c.track).toBe(1); // dragged clip lands on the new lane
+    expect(map.b.track).toBe(2); // at/below the insert → +1 shift
   });
 
   describe("lane ↔ stacking sync", () => {
@@ -440,9 +523,9 @@ describe("commitDraggedClipMove", () => {
         drag(elements[2], { previewStart: 30, previewTrack: 1, insertRow: 0 }),
         [0, 1],
       );
-      // Non-overlapping clips retain their authored/z-derived ordering; a lane
-      // gesture cannot invent a DOM stacking relationship where none overlaps.
-      expect(lane.dragged).toBe(2);
+      expect(lane.dragged).toBe(0); // aimed at the very top
+      expect(lane.top).toBe(1);
+      expect(lane.mid).toBe(2);
     });
 
     it("BETWEEN-insert of a non-overlapping clip lands it between its neighbours", async () => {
@@ -453,8 +536,8 @@ describe("commitDraggedClipMove", () => {
         [0, 1, 2],
       );
       expect(lane.a).toBe(0);
-      expect(lane.b).toBe(1);
-      expect(lane.x).toBe(2);
+      expect(lane.x).toBe(1); // between a and b, as aimed
+      expect(lane.b).toBe(2);
     });
 
     it("TOP-insert clears a NON-overlapping clip that currently tops the timeline", async () => {
@@ -466,7 +549,7 @@ describe("commitDraggedClipMove", () => {
         drag(elements[2], { previewStart: 10, previewTrack: 2, insertRow: 0 }),
         [0, 1, 2],
       );
-      expect(lane.X).toBe(1); // X reorders against overlapping M, not disjoint T
+      expect(lane.X).toBe(0); // aimed top, cleared the non-overlapping T
     });
 
     it("dragging X among overlapping neighbours preserves the RELATIVE order of the others (symptom 2)", async () => {

package/src/player/components/timelineClipDragCommit.ts

@@ -13,6 +13,13 @@ type StartTrack = Pick<TimelineElement, "start" | "track">;
 export interface TimelineMoveEdit {
   element: TimelineElement;
   updates: StartTrack;
+  /**
+   * File-space track override for the persist. The store's `updates.track` is a
+   * DISPLAY lane; when the source file's numbering is sparse (authored tracks
+   * 1,2,... or gaps), the file write must target the lane's AUTHORED track or it
+   * silently re-targets the wrong row. Omitted → persist `updates.track` as-is.
+   */
+  persistTrack?: number;
 }
 
 export interface DragCommitDeps {
@@ -114,21 +121,41 @@ function persistMoveEdits(
     key: keyOf(e.element),
     start: e.element.start,
     track: e.element.track,
+    authoredTrack: e.element.authoredTrack,
   }));
   const revision = beginTimelineOptimisticGesture(
     updateElement,
     edits.map((edit) => keyOf(edit.element)),
   );
-  for (const e of edits) updateElement(keyOf(e.element), e.updates);
+  // The file write below targets `persistTrack` (authored space) when supplied,
+  // or `updates.track` on a genuine lane write (track insert renumber). Mirror
+  // that written value into the store's `authoredTrack` so a SECOND drag before
+  // any reload resolves authored tracks from what the file now says, not stale
+  // pre-edit data. Pure time-moves leave authoredTrack untouched.
+  for (const e of edits) {
+    const writtenTrack =
+      e.persistTrack ?? (e.updates.track !== e.element.track ? e.updates.track : undefined);
+    updateElement(
+      keyOf(e.element),
+      writtenTrack == null ? e.updates : { ...e.updates, authoredTrack: writtenTrack },
+    );
+  }
+  // The store above gets DISPLAY lanes; the file below gets the authored-space
+  // track when one was resolved (see TimelineMoveEdit.persistTrack).
+  const persistEdits = edits.map((e) =>
+    e.persistTrack == null || e.persistTrack === e.updates.track
+      ? e
+      : { element: e.element, updates: { ...e.updates, track: e.persistTrack } },
+  );
   const persisted = onMoveElements
-    ? onMoveElements(edits, coalesceKey, operation)
-    : Promise.all(edits.map((e) => Promise.resolve(onMoveElement?.(e.element, e.updates))));
+    ? onMoveElements(persistEdits, coalesceKey, operation)
+    : Promise.all(persistEdits.map((e) => Promise.resolve(onMoveElement?.(e.element, e.updates))));
   return Promise.resolve(persisted).then(
     () => true,
     (error) => {
       for (const p of prev) {
         if (isLatestTimelineOptimisticGesture(updateElement, revision, p.key)) {
-          updateElement(p.key, { start: p.start, track: p.track });
+          updateElement(p.key, { start: p.start, track: p.track, authoredTrack: p.authoredTrack });
         }
       }
       console.error("[Timeline] Failed to persist clip edits", error);
@@ -143,6 +170,56 @@ function persistMoveEdits(
  * then compacts it to a distinct integer lane between its neighbours, and the
  * clips at/below the insert shift down by one — the sanctioned index-renumber.
  */
+/** Same-source-file predicate: authored track numbers only compare within ONE
+ *  file's coordinate space (an expanded sub-comp child's authoredTrack is in ITS
+ *  file, not the host timeline's). `undefined` means the active composition. */
+const sameSourceFile = (a: TimelineElement, b: TimelineElement): boolean =>
+  (a.sourceFile ?? null) === (b.sourceFile ?? null);
+
+/**
+ * Translate a DISPLAY lane into the AUTHORED (source-file) track to persist for
+ * `dragged`. Occupants are consulted ONLY from the dragged clip's own source
+ * file — an occupant from a different file (e.g. an expanded sub-comp child, or
+ * a host clip next to expanded rows) carries authored values in a different
+ * coordinate space, and borrowing them would write a foreign file's numbering.
+ *
+ * Lane semantics after normalizeToZones: each distinct authored track owns one
+ * base lane, and time-overlapping same-track clips spill onto adjacent display
+ * sub-lanes (packTrackLanes). A spill sub-lane IS a legal drop target (Timeline's
+ * trackOrder lists it): its occupants share the base lane's authored track by
+ * construction, so the same-file occupant lookup returns that authored track and
+ * the drop persists as a same-track join. The clip may then DISPLAY on a
+ * different sub-lane than it was dropped on — the spill re-packs
+ * deterministically by stable id, first-fit — but the persisted track is
+ * correct.
+ *
+ * Fallbacks when the lane has no same-file occupant (e.g. an expanded child
+ * dropped on a lane holding only other files' clips — the display-lane integer
+ * must NOT be persisted into a sparse file):
+ * 1. Offset from the NEAREST same-file lane: authored(nearest) + lane distance,
+ *    preserving "one lane up = one authored track up" in the clip's own file.
+ * 2. No same-file peers at all → the lane value itself (single-clip files:
+ *    display and authored spaces coincide for want of any other anchor).
+ * Edge-created lanes (min-1 / max+1 inserts) route through the insert path,
+ * never here.
+ */
+function authoredTrackForLane(
+  lane: number,
+  elements: TimelineElement[],
+  dragged: TimelineElement,
+): number {
+  const dragKey = keyOf(dragged);
+  const peers = elements.filter((e) => keyOf(e) !== dragKey && sameSourceFile(e, dragged));
+  const occupant = peers.find((e) => e.track === lane);
+  if (occupant) return occupant.authoredTrack ?? occupant.track;
+  let nearest: TimelineElement | null = null;
+  for (const p of peers) {
+    if (!nearest || Math.abs(p.track - lane) < Math.abs(nearest.track - lane)) nearest = p;
+  }
+  if (!nearest) return lane;
+  return (nearest.authoredTrack ?? nearest.track) + (lane - nearest.track);
+}
+
 function insertTrackValue(trackOrder: number[], insertRow: number): number {
   if (trackOrder.length === 0) return 0;
   if (insertRow <= 0) return trackOrder[0] - 0.5;
@@ -251,6 +328,7 @@ export function commitDraggedClipMove(drag: DraggedClipState, deps: DragCommitDe
   const dragEdit: TimelineMoveEdit = {
     element: drag.element,
     updates: { start: drag.previewStart, track: drag.previewTrack },
+    persistTrack: authoredTrackForLane(drag.previewTrack, elements, drag.element),
   };
   const coalesceKey = isVertical ? `clip-lane-move:${laneChangeGestureSeq++}` : undefined;
 
@@ -265,9 +343,13 @@ export function commitDraggedClipMove(drag: DraggedClipState, deps: DragCommitDe
   // The drop-intent set for the z-sync: the dragged clip at its new lane, others
   // as-is. Reasoning on this (not a re-normalize) keeps the sync seeing the user's
   // move; computeStackingPatches only compares lanes relatively.
-  const candidate = elements.map((e) =>
-    keyOf(e) === dragKey ? { ...e, start: drag.previewStart, track: drag.previewTrack } : e,
-  );
+  const candidate = elements.map((e) => {
+    if (keyOf(e) === dragKey) return { ...e, start: drag.previewStart, track: drag.previewTrack };
+    // Selection members shift in time with the drag — the z-sync must reason on
+    // their POST-move overlap sets, same as the insert branch's candidate.
+    if (multi?.keys.has(keyOf(e))) return { ...e, start: multi.movedStart(e) };
+    return e;
+  });
   const multiKeys = multi ? multi.keys : null;
   void persistMoveEdits(edits, deps, coalesceKey, "lane-reorder").then((moved) => {
     if (moved && isVertical) {
@@ -292,6 +374,7 @@ export function commitDraggedClipMove(drag: DraggedClipState, deps: DragCommitDe
  * The whole affected set is persisted atomically (single undo), and the deliberate
  * vertical move syncs the dragged clip's stacking afterwards.
  */
+// fallow-ignore-next-line complexity
 function commitTrackInsert(
   drag: DraggedClipState,
   deps: DragCommitDeps,
@@ -314,12 +397,25 @@ function commitTrackInsert(
   // shifts the at/below clips down by one — the sanctioned +1 index renumber.
   const normalized = normalizeToZones(candidate);
   const bySrc = new Map(elements.map((e) => [keyOf(e), e]));
+  // The renumber is only correct as a WHOLE-SET write: skipping an unwritable
+  // clip whose lane shifts leaves its track colliding with a renumbered
+  // neighbour, and the next normalize merges the two lanes. If any shifted clip
+  // can't be written, refuse the insert instead of persisting a broken layout.
+  for (const norm of normalized) {
+    const src = bySrc.get(keyOf(norm));
+    if (src && !canMoveElement(src) && norm.track !== src.track) {
+      console.warn(
+        `[Timeline] Track insert refused: locked clip ${keyOf(src)} would need renumbering`,
+      );
+      return;
+    }
+  }
   const edits: TimelineMoveEdit[] = [];
   for (const norm of normalized) {
     const src = bySrc.get(keyOf(norm));
     if (!src) continue;
-    // Capabilities gate: never write a locked/implicit clip, even one only swept
-    // along by the renumber (not just a marquee member).
+    // Capabilities gate (unchanged-lane clips only reach here now): never write
+    // a locked/implicit clip.
     if (!canMoveElement(src)) continue;
     const start =
       keyOf(norm) === dragKey || multi?.keys.has(keyOf(norm))
@@ -391,6 +487,7 @@ function syncStackingForEdit(
     zIndex: readZIndex(el),
     isAudio: classifyZone(el) === "audio",
     domIndex,
+    stackingContextId: el.stackingContextId ?? null,
   }));
 
   const editedKeys = [dragKey];

package/src/player/components/timelineLayout.ts

@@ -67,51 +67,105 @@ export const DRAG_EXTEND_MARGIN_PX = 160;
  * with 60s of ruler after it.
  */
 export const MIN_TIMELINE_EXTENT_S = 60;
+/**
+ * Fit-mode headroom (CapCut-style): "fit" maps `duration * 1.2` — not the bare
+ * duration — onto the viewport, so the composition ends at ~83% of the width
+ * and the trailing ~17% stays empty ruler + droppable lane surface (room to
+ * drag clips past the current end without first zooming out). Applied ONLY
+ * inside {@link getTimelineFitPps}, the single fit-pps source, so the ruler,
+ * lanes, playhead, marquee, and drag math all inherit it consistently. Manual
+ * zoom percentages stay defined relative to this fit basis (100% == fit).
+ */
+export const FIT_ZOOM_HEADROOM = 1.2;
 
 /* ── Tick generation ──────────────────────────────────────────────── */
-function getMajorTickInterval(duration: number, pixelsPerSecond?: number): number {
-  const zoomIntervals = [0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600];
+// fallow-ignore-next-line complexity
+function getMajorTickInterval(
+  duration: number,
+  pixelsPerSecond?: number,
+  frameRate?: number,
+): number {
+  // "Nice" NLE steps: 1-2-5 sub-second decades, then 1s/2s/5s/10s/15s/30s,
+  // minute multiples, and 15m/30m/1h so ultra-zoomed-out long comps still get
+  // readable (non-colliding) labels instead of the old 10m fallback everywhere.
+  const zoomIntervals = [
+    0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 15, 30, 60, 120, 300, 600, 900, 1800, 3600,
+  ];
+  let interval: number;
   if (Number.isFinite(pixelsPerSecond) && (pixelsPerSecond ?? 0) > 0) {
     const targetMajorPx = 88;
-    return (
-      zoomIntervals.find((interval) => interval * (pixelsPerSecond ?? 0) >= targetMajorPx) ?? 600
-    );
+    interval =
+      zoomIntervals.find((candidate) => candidate * (pixelsPerSecond ?? 0) >= targetMajorPx) ??
+      3600;
+  } else {
+    const durationIntervals = [0.25, 0.5, 1, 2, 5, 10, 15, 30, 60];
+    const target = duration / 6;
+    interval = durationIntervals.find((candidate) => candidate >= target) ?? 60;
   }
-  const durationIntervals = [0.25, 0.5, 1, 2, 5, 10, 15, 30, 60];
-  const target = duration / 6;
-  return durationIntervals.find((interval) => interval >= target) ?? 60;
+  // Frame display mode: labels are frame numbers, so a major step must be a
+  // WHOLE number of frames — sub-frame steps produce duplicate/uneven labels
+  // (e.g. 0.02s at 30fps is 0.6 frames → "0, 1, 1, 2, 2…"). Snap UP (ceil) so
+  // the label spacing never drops below the readability target.
+  if (Number.isFinite(frameRate) && (frameRate ?? 0) > 0) {
+    const fps = frameRate ?? 0;
+    return Math.max(1, Math.ceil(interval * fps - 1e-6)) / fps;
+  }
+  return interval;
 }
 
 // How many equal parts to split each major interval into for minor ticks. Prefer
 // quarters (4) so the midpoint stays a minor tick; fall back to halves (2) then
-// none (0) as ticks get too dense to read (< ~8px apart).
-function getMinorSubdivisions(majorInterval: number, pixelsPerSecond?: number): number {
+// none (0) as ticks get too dense to read (< ~8px apart). In frame display mode
+// the subdivision must also keep minor ticks on WHOLE frames (a minor tick at a
+// sub-frame time is not a seekable position), so only divisors of the major
+// step's frame count qualify — quarters, then fifths (15/30-frame majors),
+// thirds, halves.
+// fallow-ignore-next-line complexity
+function getMinorSubdivisions(
+  majorInterval: number,
+  pixelsPerSecond?: number,
+  frameRate?: number,
+): number {
   const pps = Number.isFinite(pixelsPerSecond) ? (pixelsPerSecond ?? 0) : 0;
   if (pps <= 0) return 4; // no zoom info (duration-fit mode): quarter ticks
-  if ((majorInterval / 4) * pps >= 8) return 4;
-  if ((majorInterval / 2) * pps >= 8) return 2;
+  const fps = Number.isFinite(frameRate) ? (frameRate ?? 0) : 0;
+  const majorFrames = fps > 0 ? Math.round(majorInterval * fps) : 0;
+  const candidates = fps > 0 ? [4, 5, 3, 2] : [4, 2];
+  for (const parts of candidates) {
+    if (fps > 0 && majorFrames % parts !== 0) continue;
+    if ((majorInterval / parts) * pps >= 8) return parts;
+  }
   return 0;
 }
 
+// Ticks are exact multiples of the interval (multiplied per index, never
+// accumulated with `+=`, so long rulers don't drift), then rounded to 1µs to
+// keep values/keys clean without disturbing frame-exact positions like 2/30s.
+function roundTickValue(t: number): number {
+  return Math.round(t * 1e6) / 1e6;
+}
+
 export function generateTicks(
   duration: number,
   pixelsPerSecond?: number,
+  frameRate?: number,
 ): { major: number[]; minor: number[] } {
-  if (duration <= 0 || !Number.isFinite(duration) || duration > 7200)
+  if (duration <= 0 || !Number.isFinite(duration) || duration > 14400)
     return { major: [], minor: [] };
-  const majorInterval = getMajorTickInterval(duration, pixelsPerSecond);
-  const subdivisions = getMinorSubdivisions(majorInterval, pixelsPerSecond);
+  const majorInterval = getMajorTickInterval(duration, pixelsPerSecond, frameRate);
+  const subdivisions = getMinorSubdivisions(majorInterval, pixelsPerSecond, frameRate);
   const minorInterval = subdivisions > 0 ? majorInterval / subdivisions : 0;
   const major: number[] = [];
   const minor: number[] = [];
   const maxTicks = 2000; // Safety cap to prevent runaway tick generation
-  for (let t = 0; t <= duration + 0.001 && major.length < maxTicks; t += majorInterval) {
-    const rounded = Math.round(t * 100) / 100;
-    major.push(rounded);
+  for (let i = 0; major.length < maxTicks; i++) {
+    const t = i * majorInterval;
+    if (t > duration + 0.001) break;
+    major.push(roundTickValue(t));
     // Emit the (subdivisions - 1) minor ticks between this major and the next.
     for (let k = 1; k < subdivisions && major.length + minor.length < maxTicks; k++) {
-      const m = Math.round((t + k * minorInterval) * 100) / 100;
-      if (m <= duration + 0.001) minor.push(m);
+      const m = t + k * minorInterval;
+      if (m <= duration + 0.001) minor.push(roundTickValue(m));
     }
   }
   return { major, minor };
@@ -144,15 +198,17 @@ export function formatTimelineTickLabel(time: number, duration: number, majorInt
 
 /* ── Width / duration derivation ──────────────────────────────────── */
 /**
- * Fit-mode pixels-per-second: fill the viewport with the composition, but
- * never map fewer than MIN_TIMELINE_EXTENT_S seconds onto it — a short comp
- * takes a fraction of the width and the remaining ruler runs to 1:00.
+ * Fit-mode pixels-per-second: fill the viewport with the composition plus
+ * FIT_ZOOM_HEADROOM trailing headroom (CapCut-style — the comp never slams
+ * into the right edge), and never map fewer than MIN_TIMELINE_EXTENT_S
+ * seconds onto it — a short comp takes a fraction of the width and the
+ * remaining ruler runs to 1:00.
  * Manual zoom multiplies this base, so the floor only anchors the default.
  */
 export function getTimelineFitPps(viewportWidth: number, effectiveDuration: number): number {
   const safeDuration =
     Number.isFinite(effectiveDuration) && effectiveDuration > 0 ? effectiveDuration : 0;
-  const span = Math.max(safeDuration, MIN_TIMELINE_EXTENT_S);
+  const span = Math.max(safeDuration * FIT_ZOOM_HEADROOM, MIN_TIMELINE_EXTENT_S);
   if (!Number.isFinite(viewportWidth) || viewportWidth <= GUTTER) return 100;
   return (viewportWidth - GUTTER - 2) / span;
 }
@@ -227,9 +283,26 @@ export function getTimelineScrollLeftForZoomAnchor(input: {
 }
 
 /* ── Playhead / canvas ────────────────────────────────────────────── */
+/**
+ * Width of the playhead wrapper element (== the diamond head chip's layout
+ * width, which the wrapper shrink-wraps to). The 1px vertical line inside
+ * PlayheadIndicator is centered at 50% of this wrapper, so the wrapper must be
+ * shifted LEFT by half this width for the line's center to land exactly on
+ * `GUTTER + time * pps` — see {@link getTimelinePlayheadLeft}.
+ */
+export const PLAYHEAD_HEAD_W = 9;
+
+/**
+ * The `left` for the playhead WRAPPER such that the vertical line's CENTER
+ * sits exactly on `GUTTER + time * pps` (the same x the ruler ticks center
+ * on) at every zoom level. Without the half-head offset the line sat
+ * `PLAYHEAD_HEAD_W / 2` px to the right of its ruler tick.
+ */
 export function getTimelinePlayheadLeft(time: number, pixelsPerSecond: number): number {
-  if (!Number.isFinite(time) || !Number.isFinite(pixelsPerSecond)) return GUTTER;
-  return GUTTER + Math.max(0, time) * Math.max(0, pixelsPerSecond);
+  if (!Number.isFinite(time) || !Number.isFinite(pixelsPerSecond)) {
+    return GUTTER - PLAYHEAD_HEAD_W / 2;
+  }
+  return GUTTER + Math.max(0, time) * Math.max(0, pixelsPerSecond) - PLAYHEAD_HEAD_W / 2;
 }
 
 export function getTimelineCanvasHeight(trackCount: number): number {