@hyperframes/studio 0.7.86 → 0.7.87

package/src/player/components/timelineLayout.ts

@@ -1,5 +1,5 @@
-import { formatTime } from "../lib/time";
 import type { ZoomMode } from "../store/playerStore";
+import type { TimelineTimeRange } from "../lib/timelineClipIndex";
 
 /* ── Layout constants ──────────────────────────────────────────────── */
 export const GUTTER = 32;
@@ -10,6 +10,47 @@ export const RULER_H = 24;
 export const CLIP_Y = 3;
 export const CLIP_HANDLE_W = 18;
 
+export interface TimelineBeatEntry {
+  readonly index: number;
+  readonly time: number;
+  readonly strength: number | undefined;
+}
+
+function findFirstTimeAtOrAfter(times: readonly number[], target: number): number {
+  let low = 0;
+  let high = times.length;
+  while (low < high) {
+    const mid = Math.floor((low + high) / 2);
+    if ((times[mid] ?? Number.POSITIVE_INFINITY) < target) low = mid + 1;
+    else high = mid;
+  }
+  return low;
+}
+
+/** Slice sorted beat data without allocating entries outside the render window. */
+export function getTimelineBeatEntries(
+  beatTimes: readonly number[] | undefined,
+  beatStrengths: readonly number[] | undefined,
+  range: TimelineTimeRange | undefined,
+  pinnedIndexes: ReadonlySet<number> = new Set(),
+): readonly TimelineBeatEntry[] {
+  if (!beatTimes?.length) return [];
+  const start = range?.start ?? Number.NEGATIVE_INFINITY;
+  const end = range?.end ?? Number.POSITIVE_INFINITY;
+  const selected = new Set<number>();
+  for (let index = findFirstTimeAtOrAfter(beatTimes, start); index < beatTimes.length; index++) {
+    const time = beatTimes[index];
+    if (time === undefined || time >= end) break;
+    selected.add(index);
+  }
+  for (const index of pinnedIndexes) {
+    if (index >= 0 && index < beatTimes.length) selected.add(index);
+  }
+  return [...selected]
+    .sort((left, right) => left - right)
+    .map((index) => ({ index, time: beatTimes[index]!, strength: beatStrengths?.[index] }));
+}
+
 export function getTimelineLaneTop(laneIndex: number): number {
   return TRACK_H + Math.max(0, Math.trunc(laneIndex)) * LANE_H;
 }
@@ -74,55 +115,134 @@ function validRowHeight(height: number | undefined): number {
   return height;
 }
 
-/**
- * Memoized by the rowHeights array identity: a marquee/drag pointer tick calls
- * getTimelineRowTop once per clip, and each call would otherwise rebuild the
- * whole cumulative array (O(clips x rows) allocations per tick). rowHeights is
- * itself memoized upstream (useTimelineTrackLayout), so the identity is stable
- * for the life of a gesture. Callers must treat the result as read-only.
- */
-const rowOffsetsCache = new WeakMap<readonly number[], number[]>();
+export interface TimelineRowGeometry {
+  readonly rowKeys: readonly number[];
+  readonly rowHeights: readonly number[];
+  /** Cumulative row boundaries, including the final bottom boundary. */
+  readonly rowOffsets: readonly number[];
+  readonly rowsHeight: number;
+  readonly canvasHeight: number;
+  getRowIndex(rowKey: number): number;
+  getRowHeight(row: number): number;
+  getRowTop(row: number): number;
+  getRowFromY(contentY: number): number;
+  getRowPositionFromY(contentY: number): {
+    rowFloat: number;
+    row: number;
+    fraction: number;
+    rowHeight: number;
+  };
+}
+
+const rowGeometryCache = new WeakMap<readonly number[], TimelineRowGeometry>();
+const EMPTY_ROW_HEIGHTS: readonly number[] = Object.freeze([]);
+
+/** Build the immutable row snapshot shared by rendering and hit testing. */
+export function createTimelineRowGeometry(
+  rowKeys: readonly number[],
+  rowHeights: readonly number[],
+): TimelineRowGeometry {
+  const heights = Object.freeze(rowHeights.map(validRowHeight));
+  const keys = Object.freeze(
+    heights.map((_, row) => {
+      const key = rowKeys[row];
+      return key !== undefined && Number.isFinite(key) ? key : row;
+    }),
+  );
+  const offsets = [0];
+  for (const height of heights) offsets.push((offsets.at(-1) ?? 0) + height);
+  Object.freeze(offsets);
+  const rowIndexByKey = new Map(keys.map((key, row) => [key, row]));
+
+  const getRowHeight = (row: number) => validRowHeight(heights[row]);
+  const getRowOffset = (row: number) => {
+    if (heights.length === 0) return row * TRACK_H;
+    if (row <= 0) return row * getRowHeight(0);
+    if (row >= heights.length) {
+      return (offsets[heights.length] ?? 0) + (row - heights.length) * TRACK_H;
+    }
+    const wholeRow = Math.floor(row);
+    return (offsets[wholeRow] ?? 0) + (row - wholeRow) * getRowHeight(wholeRow);
+  };
+  const getRowFromY = (contentY: number) => {
+    const y = contentY - RULER_H - TRACKS_TOP_PAD;
+    if (heights.length === 0) return y / TRACK_H;
+    if (y < 0) return y / getRowHeight(0);
+    const rowsHeight = offsets[heights.length] ?? 0;
+    if (y >= rowsHeight) return heights.length + (y - rowsHeight) / TRACK_H;
+
+    // First boundary strictly greater than y. Unlike the old linear scan this
+    // stays logarithmic for large timelines and uses the precomputed offsets.
+    let low = 1;
+    let high = heights.length;
+    while (low < high) {
+      const mid = Math.floor((low + high) / 2);
+      if ((offsets[mid] ?? 0) > y) high = mid;
+      else low = mid + 1;
+    }
+    const row = low - 1;
+    return row + (y - (offsets[row] ?? 0)) / getRowHeight(row);
+  };
+  const geometry: TimelineRowGeometry = {
+    rowKeys: keys,
+    rowHeights: heights,
+    rowOffsets: offsets,
+    rowsHeight: offsets.at(-1) ?? 0,
+    canvasHeight: RULER_H + TRACKS_TOP_PAD + (offsets.at(-1) ?? 0) + TRACKS_BOTTOM_PAD,
+    getRowIndex: (rowKey) => rowIndexByKey.get(rowKey) ?? -1,
+    getRowHeight,
+    getRowTop: (row) => RULER_H + TRACKS_TOP_PAD + getRowOffset(row),
+    getRowFromY,
+    getRowPositionFromY: (contentY) => {
+      const rowFloat = getRowFromY(contentY);
+      const row = Math.floor(rowFloat);
+      return { rowFloat, row, fraction: rowFloat - row, rowHeight: getRowHeight(row) };
+    },
+  };
+  const frozenGeometry = Object.freeze(geometry);
+  rowGeometryCache.set(heights, frozenGeometry);
+  return frozenGeometry;
+}
+
+/** Compatibility accessor; repeated calls for one height-array reuse one snapshot. */
+export function getTimelineRowGeometry(rowHeights: readonly number[]): TimelineRowGeometry {
+  const cached = rowGeometryCache.get(rowHeights);
+  if (cached) return cached;
+  const geometry = createTimelineRowGeometry(
+    rowHeights.map((_, row) => row),
+    rowHeights,
+  );
+  rowGeometryCache.set(rowHeights, geometry);
+  return geometry;
+}
 
 /** Cumulative top offsets, including the final bottom boundary. */
 export function getTimelineRowOffsets(rowHeights: readonly number[]): number[] {
-  const cached = rowOffsetsCache.get(rowHeights);
-  if (cached) return cached;
-  const offsets = [0];
-  for (const height of rowHeights) {
-    offsets.push((offsets[offsets.length - 1] ?? 0) + validRowHeight(height));
-  }
-  rowOffsetsCache.set(rowHeights, offsets);
-  return offsets;
+  return [...getTimelineRowGeometry(rowHeights).rowOffsets];
 }
 
-export function getTimelineRowHeight(row: number, rowHeights: readonly number[] = []): number {
+export function getTimelineRowHeight(
+  row: number,
+  rowHeights: readonly number[] = EMPTY_ROW_HEIGHTS,
+): number {
   return validRowHeight(rowHeights[row]);
 }
 
 function getTimelineRowOffset(row: number, rowHeights: readonly number[]): number {
-  if (rowHeights.length === 0) return row * TRACK_H;
-  const offsets = getTimelineRowOffsets(rowHeights);
-  if (row <= 0) return row * getTimelineRowHeight(0, rowHeights);
-  if (row >= rowHeights.length) {
-    // Deliberately TRACK_H, not the last row's height: rows past the end do not
-    // exist yet, and a row created by dropping there starts unexpanded. The
-    // pre-first-row branch above uses row 0's concrete height instead because
-    // that row DOES exist — the pointer is in the top pad above a real lane.
-    return (offsets[rowHeights.length] ?? 0) + (row - rowHeights.length) * TRACK_H;
-  }
-  const wholeRow = Math.floor(row);
-  const fraction = row - wholeRow;
-  return (offsets[wholeRow] ?? 0) + fraction * getTimelineRowHeight(wholeRow, rowHeights);
+  return getTimelineRowGeometry(rowHeights).getRowTop(row) - RULER_H - TRACKS_TOP_PAD;
 }
 
 /**
  * The y (content-space) of the top edge of track ROW index `row` (0 = first
- * displayed lane). The single source of truth for row→y — the ruler height plus
+ * displayed lane). The single source of truth for row->y: the ruler height plus
  * the top breathing pad plus whole track lanes above it. Every clip/ghost/
- * placeholder/insertion top and every pointer-y→row inversion goes through this
+ * placeholder/insertion top and every pointer-y->row inversion goes through this
  * (or its inverse in {@link getTimelineRowFromY}) so the pad can never drift.
  */
-export function getTimelineRowTop(row: number, rowHeights: readonly number[] = []): number {
+export function getTimelineRowTop(
+  row: number,
+  rowHeights: readonly number[] = EMPTY_ROW_HEIGHTS,
+): number {
   return RULER_H + TRACKS_TOP_PAD + getTimelineRowOffset(row, rowHeights);
 }
 
@@ -131,34 +251,18 @@ export function getTimelineRowTop(row: number, rowHeights: readonly number[] = [
  * space y (used for insert-row / drop-lane decisions). Locates the concrete row
  * from cumulative offsets, then returns its local fractional position.
  */
-export function getTimelineRowFromY(contentY: number, rowHeights: readonly number[] = []): number {
-  const y = contentY - RULER_H - TRACKS_TOP_PAD;
-  if (rowHeights.length === 0) return y / TRACK_H;
-  if (y < 0) return y / getTimelineRowHeight(0, rowHeights);
-
-  const offsets = getTimelineRowOffsets(rowHeights);
-  for (let row = 0; row < rowHeights.length; row += 1) {
-    const bottom = offsets[row + 1] ?? 0;
-    if (y < bottom) {
-      const top = offsets[row] ?? 0;
-      return row + (y - top) / getTimelineRowHeight(row, rowHeights);
-    }
-  }
-  return rowHeights.length + (y - (offsets[rowHeights.length] ?? 0)) / TRACK_H;
+export function getTimelineRowFromY(
+  contentY: number,
+  rowHeights: readonly number[] = EMPTY_ROW_HEIGHTS,
+): number {
+  return getTimelineRowGeometry(rowHeights).getRowFromY(contentY);
 }
 
 export function getTimelineRowPositionFromY(
   contentY: number,
-  rowHeights: readonly number[] = [],
+  rowHeights: readonly number[] = EMPTY_ROW_HEIGHTS,
 ): { rowFloat: number; row: number; fraction: number; rowHeight: number } {
-  const rowFloat = getTimelineRowFromY(contentY, rowHeights);
-  const row = Math.floor(rowFloat);
-  return {
-    rowFloat,
-    row,
-    fraction: rowFloat - row,
-    rowHeight: getTimelineRowHeight(row, rowHeights),
-  };
+  return getTimelineRowGeometry(rowHeights).getRowPositionFromY(contentY);
 }
 
 /** Fractional insert band for the concrete row under a pointer. */
@@ -193,123 +297,6 @@ export const MIN_TIMELINE_EXTENT_S = 60;
 export const FIT_ZOOM_HEADROOM = 1.2;
 
 /* ── Tick generation ──────────────────────────────────────────────── */
-// 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;
-    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;
-  }
-  // 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). 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
-  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 > 14400)
-    return { major: [], minor: [] };
-  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 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 = t + k * minorInterval;
-      if (m <= duration + 0.001) minor.push(roundTickValue(m));
-    }
-  }
-  return { major, minor };
-}
-
-export function formatTimelineTickLabel(time: number, duration: number, majorInterval: number) {
-  if (!Number.isFinite(time)) return "00:00";
-  const safeTime = Math.max(0, time);
-  if (majorInterval < 0.1) {
-    const totalHundredths = Math.round(safeTime * 100);
-    const wholeSeconds = Math.floor(totalHundredths / 100);
-    const hundredth = totalHundredths % 100;
-    return `${formatTime(wholeSeconds)}.${hundredth.toString().padStart(2, "0")}`;
-  }
-  if (majorInterval < 1) {
-    const totalTenths = Math.round(safeTime * 10);
-    const wholeSeconds = Math.floor(totalTenths / 10);
-    const tenth = totalTenths % 10;
-    return `${formatTime(wholeSeconds)}.${tenth}`;
-  }
-  if (duration >= 3600 || safeTime >= 3600) {
-    const totalSeconds = Math.floor(safeTime);
-    const hours = Math.floor(totalSeconds / 3600);
-    const minutes = Math.floor((totalSeconds % 3600) / 60);
-    const seconds = totalSeconds % 60;
-    return `${hours}:${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}`;
-  }
-  return formatTime(safeTime);
-}
-
 /* ── Width / duration derivation ──────────────────────────────────── */
 /**
  * Fit-mode pixels-per-second: fill the viewport with the composition plus
@@ -473,13 +460,52 @@ export function getTimelineScrubTime(input: {
   });
   return Math.max(0, Math.min(duration, x / pixelsPerSecond));
 }
+const PLAYBACK_FOLLOW_POSITION = 0.75;
+
+/**
+ * Keep a playing timeline calm until the playhead crosses the right-side
+ * comfort line, then advance the viewport just enough to hold it there. A
+ * loop/reverse jump that leaves the playhead behind the sticky labels restores
+ * the matching earlier viewport instead.
+ */
+export function getTimelinePlaybackFollowScrollLeft(input: {
+  playheadX: number;
+  currentScrollLeft: number;
+  viewportWidth: number;
+  contentOrigin: number;
+  maxScrollLeft: number;
+}): number {
+  const current = Number.isFinite(input.currentScrollLeft)
+    ? Math.max(0, input.currentScrollLeft)
+    : 0;
+  const max = Number.isFinite(input.maxScrollLeft) ? Math.max(0, input.maxScrollLeft) : 0;
+  const visibleTimelineWidth = input.viewportWidth - input.contentOrigin;
+  if (
+    !Number.isFinite(input.playheadX) ||
+    !Number.isFinite(input.contentOrigin) ||
+    !Number.isFinite(visibleTimelineWidth) ||
+    visibleTimelineWidth <= 0 ||
+    max <= 0
+  ) {
+    return Math.min(max, current);
+  }
+
+  const visibleStart = current + input.contentOrigin;
+  const followLine = visibleStart + visibleTimelineWidth * PLAYBACK_FOLLOW_POSITION;
+  let next = current;
+  if (input.playheadX > followLine) {
+    next = input.playheadX - input.contentOrigin - visibleTimelineWidth * PLAYBACK_FOLLOW_POSITION;
+  } else if (input.playheadX < visibleStart) {
+    next = input.playheadX - input.contentOrigin;
+  }
+  return Math.max(0, Math.min(max, next));
+}
 
 export function getTimelineCanvasHeight(rowHeights: readonly number[]): number {
   // RULER_H + top pad + lanes + bottom pad. The old TIMELINE_SCROLL_BUFFER is
   // subsumed by TRACKS_BOTTOM_PAD (which is larger), so the drag-into-void space
   // below the last lane is real scrollable surface, not a hidden buffer.
-  const rowsHeight = getTimelineRowOffsets(rowHeights).at(-1) ?? 0;
-  return RULER_H + TRACKS_TOP_PAD + rowsHeight + TRACKS_BOTTOM_PAD;
+  return getTimelineRowGeometry(rowHeights).canvasHeight;
 }
 
 /* ── UI helpers ───────────────────────────────────────────────────── */

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

@@ -0,0 +1,23 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.resetModules();
+});
+
+describe("timeline row virtualization flag", () => {
+  it("enables virtualization by default", async () => {
+    const { STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED } =
+      await import("./timelineRowVirtualizationFlag");
+
+    expect(STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED).toBe(true);
+  });
+
+  it("keeps an explicit rollback path", async () => {
+    vi.stubEnv("VITE_STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED", "0");
+    const { STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED } =
+      await import("./timelineRowVirtualizationFlag");
+
+    expect(STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED).toBe(false);
+  });
+});

package/src/player/components/timelineRowVirtualizationFlag.ts

@@ -0,0 +1,10 @@
+/**
+ * Row virtualization is the product default. Setting the environment flag to
+ * "0" keeps one explicit rollback path for comparisons and emergencies.
+ *
+ * It lives in its own module so the scroll-viewport hook can read it without
+ * importing the virtualization hook that already imports the viewport snapshot
+ * type back, which would close an import cycle.
+ */
+export const STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED =
+  import.meta.env.VITE_STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED !== "0";

package/src/player/components/timelineRulerGeometry.ts

@@ -0,0 +1,142 @@
+import { formatTime } from "../lib/time";
+import type { TimelineTimeRange } from "../lib/timelineClipIndex";
+
+// fallow-ignore-next-line complexity
+export function getTimelineMajorTickInterval(
+  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;
+    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;
+  }
+  // Frame display mode: labels are frame numbers, so a major step must be a
+  // WHOLE number of frames. Snap UP so label spacing stays readable.
+  if (Number.isFinite(frameRate) && (frameRate ?? 0) > 0) {
+    const fps = frameRate ?? 0;
+    return Math.max(1, Math.ceil(interval * fps - 1e-6)) / fps;
+  }
+  return interval;
+}
+
+// Prefer quarter subdivisions so the midpoint remains visible; fall back to
+// smaller whole-frame-compatible sets as ticks become too dense to read.
+// 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;
+  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;
+}
+
+// Multiply from the index rather than accumulating, then round to 1µs so long
+// rulers do not drift and frame-exact positions keep clean values and keys.
+function roundTickValue(time: number): number {
+  return Math.round(time * 1e6) / 1e6;
+}
+
+function isSupportedTickDuration(duration: number): boolean {
+  return duration > 0 && Number.isFinite(duration) && duration <= 14400;
+}
+
+function getTickRange(duration: number, range?: TimelineTimeRange): TimelineTimeRange {
+  return {
+    start: Math.max(0, range?.start ?? 0),
+    end: Math.min(duration, range?.end ?? duration),
+  };
+}
+
+function appendMinorTicks(
+  minor: number[],
+  majorTime: number,
+  minorInterval: number,
+  subdivisions: number,
+  range: TimelineTimeRange,
+  maxTicks: number,
+  majorCount: number,
+): void {
+  for (let part = 1; part < subdivisions && majorCount + minor.length < maxTicks; part++) {
+    const time = majorTime + part * minorInterval;
+    if (time >= range.start - 0.001 && time <= range.end + 0.001) {
+      minor.push(roundTickValue(time));
+    }
+  }
+}
+
+export function generateTicks(
+  duration: number,
+  pixelsPerSecond?: number,
+  frameRate?: number,
+  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 minorInterval = subdivisions > 0 ? majorInterval / subdivisions : 0;
+  const major: number[] = [];
+  const minor: number[] = [];
+  // Safety cap prevents malformed inputs from creating an unbounded ruler.
+  const maxTicks = 2000;
+  const tickRange = getTickRange(duration, range);
+  const firstMajorIndex = Math.max(0, Math.floor(tickRange.start / majorInterval));
+  for (let index = firstMajorIndex; major.length < maxTicks; index++) {
+    const time = index * majorInterval;
+    if (time > tickRange.end + 0.001) break;
+    if (time >= tickRange.start - 0.001) major.push(roundTickValue(time));
+    appendMinorTicks(minor, time, minorInterval, subdivisions, tickRange, maxTicks, major.length);
+  }
+  return { major, minor };
+}
+
+export function formatTimelineTickLabel(
+  time: number,
+  duration: number,
+  majorInterval: number,
+): string {
+  if (!Number.isFinite(time)) return "00:00";
+  const safeTime = Math.max(0, time);
+  if (majorInterval < 0.1) {
+    const totalHundredths = Math.round(safeTime * 100);
+    const wholeSeconds = Math.floor(totalHundredths / 100);
+    const hundredth = totalHundredths % 100;
+    return `${formatTime(wholeSeconds)}.${hundredth.toString().padStart(2, "0")}`;
+  }
+  if (majorInterval < 1) {
+    const totalTenths = Math.round(safeTime * 10);
+    const wholeSeconds = Math.floor(totalTenths / 10);
+    const tenth = totalTenths % 10;
+    return `${formatTime(wholeSeconds)}.${tenth}`;
+  }
+  if (duration >= 3600 || safeTime >= 3600) {
+    const totalSeconds = Math.floor(safeTime);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    return `${hours}:${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}`;
+  }
+  return formatTime(safeTime);
+}

package/src/player/components/timelineViewModel.ts

@@ -0,0 +1,44 @@
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
+import type { ResizingClipState } from "./timelineClipDragTypes";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { animationContributesLane } from "./TimelinePropertyLanes";
+
+export function hasKeyframedTimelineClips(
+  animationsByElement: ReadonlyMap<string, readonly GsapAnimation[]>,
+): boolean {
+  return Array.from(animationsByElement.values()).some((animations) =>
+    animations.some(animationContributesLane),
+  );
+}
+
+export function getEffectiveTimelineDuration(
+  duration: number,
+  elements: readonly TimelineElement[],
+): number {
+  const safeDuration = Number.isFinite(duration) ? duration : 0;
+  if (elements.length === 0) return safeDuration;
+  const result = Math.max(
+    safeDuration,
+    ...elements.map((element) => element.start + element.duration),
+  );
+  return Number.isFinite(result) ? result : safeDuration;
+}
+
+export function getTimelinePreviewElement(
+  element: TimelineElement,
+  resizingClip: ResizingClipState | null,
+): TimelineElement {
+  if (
+    resizingClip &&
+    getTimelineElementIdentity(resizingClip.element) === getTimelineElementIdentity(element)
+  ) {
+    return {
+      ...element,
+      start: resizingClip.previewStart,
+      duration: resizingClip.previewDuration,
+      playbackStart: resizingClip.previewPlaybackStart,
+    };
+  }
+  return element;
+}