@hyperframes/studio 0.7.46 → 0.7.48

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

@@ -0,0 +1,200 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import type { StackingTimelineLayer } from "./timelineTrackOrder";
+import {
+  resolveTimelineLayerStackingMove,
+  resolveTimelineLayerZIndexChanges,
+} from "./timelineLayerDrag";
+
+function element(input: {
+  id: string;
+  zIndex: number;
+  tag?: string;
+  start?: number;
+  duration?: number;
+}): TimelineElement {
+  return {
+    id: input.id,
+    tag: input.tag ?? "div",
+    start: input.start ?? 0,
+    duration: input.duration ?? 1,
+    track: 0,
+    zIndex: input.zIndex,
+    hasExplicitZIndex: true,
+    stackingContextId: "root",
+    parentCompositionId: null,
+    compositionAncestors: ["root"],
+  };
+}
+
+function layer(
+  id: string,
+  zIndex: number,
+  elements: TimelineElement[] = [element({ id, zIndex })],
+): StackingTimelineLayer {
+  return {
+    id,
+    kind: "visual",
+    contextKey: "root",
+    zIndex,
+    placementTrack: 0,
+    elements,
+  };
+}
+
+describe("resolveTimelineLayerZIndexChanges", () => {
+  it("joins an existing lane by assigning the dragged clip that lane's z-index", () => {
+    const dragged = element({ id: "dragged", zIndex: 1, start: 2, duration: 1 });
+    const front = element({ id: "front", zIndex: 10, start: 0, duration: 1 });
+
+    expect(
+      resolveTimelineLayerZIndexChanges({
+        element: dragged,
+        layers: [layer("front", 10, [front]), layer("back", 1)],
+        placement: { type: "onto", layerId: "front" },
+      })?.zIndexChanges,
+    ).toEqual([{ key: "dragged", zIndex: 10 }]);
+  });
+
+  it("rejects an onto-lane join when the dragged clip would overlap that lane", () => {
+    const dragged = element({ id: "dragged", zIndex: 1, start: 0.5, duration: 1 });
+    const front = element({ id: "front", zIndex: 10, start: 0, duration: 1 });
+
+    expect(
+      resolveTimelineLayerZIndexChanges({
+        element: dragged,
+        layers: [layer("front", 10, [front]), layer("back", 1)],
+        placement: { type: "onto", layerId: "front" },
+      }),
+    ).toBeNull();
+  });
+
+  it("interpolates a new integer z-index strictly between neighboring layers", () => {
+    const dragged = element({ id: "dragged", zIndex: 1 });
+
+    expect(
+      resolveTimelineLayerZIndexChanges({
+        element: dragged,
+        layers: [layer("front", 10), layer("back", 4)],
+        placement: { type: "between", beforeLayerId: "front", afterLayerId: "back" },
+      })?.zIndexChanges,
+    ).toEqual([{ key: "dragged", zIndex: 7 }]);
+  });
+
+  it("renumbers the minimum sibling set when adjacent layers leave no integer gap", () => {
+    const dragged = element({ id: "dragged", zIndex: 0 });
+
+    expect(
+      resolveTimelineLayerZIndexChanges({
+        element: dragged,
+        layers: [layer("front", 2), layer("back", 1), layer("lower", 0)],
+        placement: { type: "between", beforeLayerId: "front", afterLayerId: "back" },
+      })?.zIndexChanges,
+    ).toEqual([
+      { key: "dragged", zIndex: 2 },
+      { key: "front", zIndex: 3 },
+    ]);
+  });
+
+  it("assigns new extreme z-index values above the top and below the bottom layer", () => {
+    const dragged = element({ id: "dragged", zIndex: 0 });
+    const layers = [layer("front", 10), layer("back", -2)];
+
+    expect(
+      resolveTimelineLayerZIndexChanges({
+        element: dragged,
+        layers,
+        placement: { type: "above", layerId: "front" },
+      })?.zIndexChanges,
+    ).toEqual([{ key: "dragged", zIndex: 11 }]);
+
+    expect(
+      resolveTimelineLayerZIndexChanges({
+        element: dragged,
+        layers,
+        placement: { type: "below", layerId: "back" },
+      })?.zIndexChanges,
+    ).toEqual([{ key: "dragged", zIndex: -3 }]);
+  });
+
+  it("does not resolve stacking z-index changes for audio clips", () => {
+    expect(
+      resolveTimelineLayerZIndexChanges({
+        element: element({ id: "music", zIndex: 0, tag: "audio" }),
+        layers: [layer("front", 10)],
+        placement: { type: "onto", layerId: "front" },
+      }),
+    ).toBeNull();
+  });
+});
+
+describe("resolveTimelineLayerStackingMove", () => {
+  it("places an upward onto-lane drop above the overlapping target lane", () => {
+    const front = element({ id: "front", zIndex: 10, start: 0, duration: 2 });
+    const dragged = element({ id: "dragged", zIndex: 1, start: 0.5, duration: 1 });
+    const layers = [layer("front", 10, [front]), layer("dragged", 1, [dragged])];
+
+    expect(
+      resolveTimelineLayerStackingMove({
+        element: dragged,
+        layers,
+        layerOrder: layers.map((item) => item.id),
+        trackDeltaRaw: -0.8,
+      }),
+    ).toEqual({
+      previewLayerId: "preview:dragged:above:front",
+      previewLayerIndex: 0,
+      stackingReorder: {
+        contextKey: "root",
+        placement: { type: "above", layerId: "front" },
+        zIndexChanges: [{ key: "dragged", zIndex: 11 }],
+      },
+    });
+  });
+
+  it("places a downward onto-lane drop below the overlapping target lane", () => {
+    const dragged = element({ id: "dragged", zIndex: 10, start: 0.5, duration: 1 });
+    const back = element({ id: "back", zIndex: 1, start: 0, duration: 2 });
+    const layers = [layer("dragged", 10, [dragged]), layer("back", 1, [back])];
+
+    expect(
+      resolveTimelineLayerStackingMove({
+        element: dragged,
+        layers,
+        layerOrder: layers.map((item) => item.id),
+        trackDeltaRaw: 0.8,
+      }),
+    ).toEqual({
+      previewLayerId: "preview:dragged:below:back",
+      previewLayerIndex: 2,
+      stackingReorder: {
+        contextKey: "root",
+        placement: { type: "below", layerId: "back" },
+        zIndexChanges: [{ key: "dragged", zIndex: 0 }],
+      },
+    });
+  });
+
+  it("keeps a non-overlapping onto-lane drop joined to the target lane", () => {
+    const front = element({ id: "front", zIndex: 10, start: 0, duration: 1 });
+    const dragged = element({ id: "dragged", zIndex: 1, start: 2, duration: 1 });
+    const layers = [layer("front", 10, [front]), layer("dragged", 1, [dragged])];
+
+    expect(
+      resolveTimelineLayerStackingMove({
+        element: dragged,
+        layers,
+        layerOrder: layers.map((item) => item.id),
+        trackDeltaRaw: -0.8,
+      }),
+    ).toEqual({
+      previewLayerId: "front",
+      previewLayerIndex: 0,
+      stackingReorder: {
+        contextKey: "root",
+        placement: { type: "onto", layerId: "front" },
+        zIndexChanges: [{ key: "dragged", zIndex: 10 }],
+      },
+    });
+  });
+});

package/src/player/components/timelineLayerDrag.ts

@@ -0,0 +1,383 @@
+import { resolveStackingContextKey } from "../lib/layerOrdering";
+import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
+import {
+  timelineElementsOverlap,
+  type StackingTimelineLayer,
+  type TimelineLayerId,
+} from "./timelineTrackOrder";
+import {
+  toStackingOrderItem,
+  type TimelineLayerDropPlacement,
+  type TimelineStackingElement,
+  type TimelineStackingReorderIntent,
+  type TimelineStackingZIndexChange,
+} from "./timelineStacking";
+
+const ONTO_ROW_THRESHOLD = 0.35;
+
+export interface TimelineLayerStackingMoveResolution {
+  previewLayerId: TimelineLayerId;
+  previewLayerIndex: number;
+  stackingReorder: TimelineStackingReorderIntent | null;
+}
+
+function isAudioElement(element: TimelineStackingElement): boolean {
+  return element.tag?.toLowerCase() === "audio";
+}
+
+function layerContainsElement(layer: StackingTimelineLayer, key: string): boolean {
+  return layer.elements.some((element) => getTimelineElementIdentity(element) === key);
+}
+
+function layerConflictsWithElement(
+  layer: StackingTimelineLayer,
+  element: TimelineStackingElement,
+  draggedKey: string,
+): boolean {
+  return layer.elements.some(
+    (candidate) =>
+      getTimelineElementIdentity(candidate) !== draggedKey &&
+      timelineElementsOverlap(candidate, element),
+  );
+}
+
+function addElementChange(
+  changes: TimelineStackingZIndexChange[],
+  element: TimelineStackingElement,
+  zIndex: number,
+): void {
+  if ((element.zIndex ?? 0) === zIndex) return;
+  changes.push({
+    key: getTimelineElementIdentity(element),
+    zIndex,
+    domId: element.domId,
+    selector: element.selector,
+    selectorIndex: element.selectorIndex,
+    sourceFile: element.sourceFile,
+  });
+}
+
+function addLayerChanges(
+  changes: TimelineStackingZIndexChange[],
+  layer: StackingTimelineLayer,
+  zIndex: number,
+  excludedKey: string,
+): number {
+  let count = 0;
+  for (const element of layer.elements) {
+    const key = getTimelineElementIdentity(element);
+    if (key === excludedKey) continue;
+    const before = changes.length;
+    addElementChange(changes, element, zIndex);
+    if (changes.length > before) count += 1;
+  }
+  return count;
+}
+
+function getContextLayers(
+  layers: readonly StackingTimelineLayer[],
+  contextKey: string,
+): StackingTimelineLayer[] {
+  return layers.filter((layer) => layer.kind === "visual" && layer.contextKey === contextKey);
+}
+
+function findLayer(
+  layers: readonly StackingTimelineLayer[],
+  id: string,
+): StackingTimelineLayer | null {
+  return layers.find((layer) => layer.id === id) ?? null;
+}
+
+function resolvePlacementZIndexChanges(input: {
+  element: TimelineStackingElement;
+  targetZIndex: number;
+}): TimelineStackingZIndexChange[] {
+  const changes: TimelineStackingZIndexChange[] = [];
+  addElementChange(changes, input.element, input.targetZIndex);
+  return changes;
+}
+
+function buildPushUpCandidate(input: {
+  element: TimelineStackingElement;
+  layers: readonly StackingTimelineLayer[];
+  beforeIndex: number;
+  bottomZIndex: number;
+}): { changes: TimelineStackingZIndexChange[]; siblingChanges: number } {
+  const draggedKey = getTimelineElementIdentity(input.element);
+  const draggedZIndex = input.bottomZIndex + 1;
+  const changes = resolvePlacementZIndexChanges({
+    element: input.element,
+    targetZIndex: draggedZIndex,
+  });
+  let siblingChanges = 0;
+  let requiredZIndex = draggedZIndex + 1;
+  for (let index = input.beforeIndex; index >= 0; index -= 1) {
+    const layer = input.layers[index];
+    if (!layer) continue;
+    const nextZIndex = layer.zIndex >= requiredZIndex ? layer.zIndex : requiredZIndex;
+    siblingChanges += addLayerChanges(changes, layer, nextZIndex, draggedKey);
+    requiredZIndex = nextZIndex + 1;
+  }
+  return { changes, siblingChanges };
+}
+
+function buildPushDownCandidate(input: {
+  element: TimelineStackingElement;
+  layers: readonly StackingTimelineLayer[];
+  afterIndex: number;
+  topZIndex: number;
+}): { changes: TimelineStackingZIndexChange[]; siblingChanges: number } {
+  const draggedKey = getTimelineElementIdentity(input.element);
+  const draggedZIndex = input.topZIndex - 1;
+  const changes = resolvePlacementZIndexChanges({
+    element: input.element,
+    targetZIndex: draggedZIndex,
+  });
+  let siblingChanges = 0;
+  let requiredZIndex = draggedZIndex - 1;
+  for (let index = input.afterIndex; index < input.layers.length; index += 1) {
+    const layer = input.layers[index];
+    if (!layer) continue;
+    const nextZIndex = layer.zIndex <= requiredZIndex ? layer.zIndex : requiredZIndex;
+    siblingChanges += addLayerChanges(changes, layer, nextZIndex, draggedKey);
+    requiredZIndex = nextZIndex - 1;
+  }
+  return { changes, siblingChanges };
+}
+
+function resolveBetweenChanges(input: {
+  element: TimelineStackingElement;
+  layers: readonly StackingTimelineLayer[];
+  beforeLayer: StackingTimelineLayer;
+  afterLayer: StackingTimelineLayer;
+}): TimelineStackingZIndexChange[] {
+  const topZIndex = input.beforeLayer.zIndex;
+  const bottomZIndex = input.afterLayer.zIndex;
+  if (topZIndex - bottomZIndex > 1) {
+    return resolvePlacementZIndexChanges({
+      element: input.element,
+      targetZIndex: Math.floor((topZIndex + bottomZIndex) / 2),
+    });
+  }
+
+  const beforeIndex = input.layers.findIndex((layer) => layer.id === input.beforeLayer.id);
+  const afterIndex = input.layers.findIndex((layer) => layer.id === input.afterLayer.id);
+  const pushUp = buildPushUpCandidate({
+    element: input.element,
+    layers: input.layers,
+    beforeIndex,
+    bottomZIndex,
+  });
+  const pushDown = buildPushDownCandidate({
+    element: input.element,
+    layers: input.layers,
+    afterIndex,
+    topZIndex,
+  });
+  return pushUp.siblingChanges <= pushDown.siblingChanges ? pushUp.changes : pushDown.changes;
+}
+
+function resolveOntoChanges(input: {
+  element: TimelineStackingElement;
+  layers: readonly StackingTimelineLayer[];
+  layerId: string;
+}): TimelineStackingZIndexChange[] | null {
+  const target = findLayer(input.layers, input.layerId);
+  if (!target) return null;
+  if (layerConflictsWithElement(target, input.element, getTimelineElementIdentity(input.element))) {
+    return null;
+  }
+  return resolvePlacementZIndexChanges({
+    element: input.element,
+    targetZIndex: target.zIndex,
+  });
+}
+
+function resolveEdgeChanges(input: {
+  element: TimelineStackingElement;
+  layers: readonly StackingTimelineLayer[];
+  layerId: string;
+  offset: number;
+}): TimelineStackingZIndexChange[] | null {
+  const target = findLayer(input.layers, input.layerId);
+  if (!target) return null;
+  return resolvePlacementZIndexChanges({
+    element: input.element,
+    targetZIndex: target.zIndex + input.offset,
+  });
+}
+
+function resolvePlacementChanges(input: {
+  element: TimelineStackingElement;
+  layers: readonly StackingTimelineLayer[];
+  placement: TimelineLayerDropPlacement;
+}): TimelineStackingZIndexChange[] | null {
+  switch (input.placement.type) {
+    case "onto":
+      return resolveOntoChanges({
+        element: input.element,
+        layers: input.layers,
+        layerId: input.placement.layerId,
+      });
+    case "above":
+      return resolveEdgeChanges({
+        element: input.element,
+        layers: input.layers,
+        layerId: input.placement.layerId,
+        offset: 1,
+      });
+    case "below":
+      return resolveEdgeChanges({
+        element: input.element,
+        layers: input.layers,
+        layerId: input.placement.layerId,
+        offset: -1,
+      });
+    case "between": {
+      const beforeLayer = findLayer(input.layers, input.placement.beforeLayerId);
+      const afterLayer = findLayer(input.layers, input.placement.afterLayerId);
+      return beforeLayer && afterLayer
+        ? resolveBetweenChanges({
+            element: input.element,
+            layers: input.layers,
+            beforeLayer,
+            afterLayer,
+          })
+        : null;
+    }
+  }
+}
+
+export function resolveTimelineLayerZIndexChanges(input: {
+  element: TimelineStackingElement;
+  layers: readonly StackingTimelineLayer[];
+  placement: TimelineLayerDropPlacement;
+}): TimelineStackingReorderIntent | null {
+  if (isAudioElement(input.element)) return null;
+  const contextKey = resolveStackingContextKey(toStackingOrderItem(input.element));
+  const layers = getContextLayers(input.layers, contextKey);
+  const changes = resolvePlacementChanges({
+    element: input.element,
+    layers,
+    placement: input.placement,
+  });
+
+  return changes && changes.length > 0
+    ? { contextKey, placement: input.placement, zIndexChanges: changes }
+    : null;
+}
+
+// fallow-ignore-next-line complexity
+function resolveDragPlacement(
+  layers: readonly StackingTimelineLayer[],
+  targetPosition: number,
+): TimelineLayerDropPlacement | null {
+  const first = layers[0];
+  const last = layers[layers.length - 1];
+  if (!first || !last) return null;
+  if (targetPosition < -ONTO_ROW_THRESHOLD) return { type: "above", layerId: first.id };
+  if (targetPosition > layers.length - 1 + ONTO_ROW_THRESHOLD) {
+    return { type: "below", layerId: last.id };
+  }
+
+  const nearestIndex = Math.round(targetPosition);
+  const nearest = layers[nearestIndex];
+  if (nearest && Math.abs(targetPosition - nearestIndex) <= ONTO_ROW_THRESHOLD) {
+    return { type: "onto", layerId: nearest.id };
+  }
+
+  const insertionIndex = Math.max(0, Math.min(layers.length, Math.ceil(targetPosition)));
+  if (insertionIndex <= 0) return { type: "above", layerId: first.id };
+  if (insertionIndex >= layers.length) return { type: "below", layerId: last.id };
+  const before = layers[insertionIndex - 1];
+  const after = layers[insertionIndex];
+  return before && after
+    ? { type: "between", beforeLayerId: before.id, afterLayerId: after.id }
+    : null;
+}
+
+function resolveLaneAwareDragPlacement(input: {
+  layers: readonly StackingTimelineLayer[];
+  element: TimelineStackingElement;
+  draggedKey: string;
+  placement: TimelineLayerDropPlacement;
+  targetPosition: number;
+  currentIndex: number;
+}): TimelineLayerDropPlacement | null {
+  if (input.placement.type !== "onto") return input.placement;
+  const target = findLayer(input.layers, input.placement.layerId);
+  if (!target) return null;
+  if (!layerConflictsWithElement(target, input.element, input.draggedKey)) return input.placement;
+  if (input.targetPosition < input.currentIndex) {
+    return { type: "above", layerId: target.id };
+  }
+  if (input.targetPosition > input.currentIndex) {
+    return { type: "below", layerId: target.id };
+  }
+  return input.placement;
+}
+
+function getPreviewLayerId(
+  draggedKey: string,
+  placement: TimelineLayerDropPlacement,
+): TimelineLayerId {
+  if (placement.type === "onto") return placement.layerId;
+  if (placement.type === "between") {
+    return `preview:${draggedKey}:between:${placement.beforeLayerId}:${placement.afterLayerId}`;
+  }
+  return `preview:${draggedKey}:${placement.type}:${placement.layerId}`;
+}
+
+function getPreviewLayerIndex(
+  layerOrder: readonly TimelineLayerId[],
+  placement: TimelineLayerDropPlacement,
+): number {
+  if (placement.type === "onto") return Math.max(0, layerOrder.indexOf(placement.layerId));
+  if (placement.type === "between") {
+    return Math.max(0, layerOrder.indexOf(placement.afterLayerId));
+  }
+  const targetIndex = Math.max(0, layerOrder.indexOf(placement.layerId));
+  return placement.type === "above" ? targetIndex : targetIndex + 1;
+}
+
+export function resolveTimelineLayerStackingMove(input: {
+  element: TimelineStackingElement;
+  layers: readonly StackingTimelineLayer[];
+  layerOrder: readonly TimelineLayerId[];
+  trackDeltaRaw: number;
+}): TimelineLayerStackingMoveResolution | null {
+  if (isAudioElement(input.element)) return null;
+  const contextKey = resolveStackingContextKey(toStackingOrderItem(input.element));
+  const layerById = new Map(input.layers.map((layer) => [layer.id, layer]));
+  const contextLayers = input.layerOrder
+    .map((id) => layerById.get(id) ?? null)
+    .filter(
+      (layer): layer is StackingTimelineLayer =>
+        layer != null && layer.kind === "visual" && layer.contextKey === contextKey,
+    );
+  const draggedKey = getTimelineElementIdentity(input.element);
+  const currentIndex = contextLayers.findIndex((layer) => layerContainsElement(layer, draggedKey));
+  if (currentIndex < 0) return null;
+
+  const targetPosition = currentIndex + input.trackDeltaRaw;
+  const rawPlacement = resolveDragPlacement(contextLayers, targetPosition);
+  if (!rawPlacement) return null;
+  const placement = resolveLaneAwareDragPlacement({
+    layers: contextLayers,
+    element: input.element,
+    draggedKey,
+    placement: rawPlacement,
+    targetPosition,
+    currentIndex,
+  });
+  if (!placement) return null;
+  return {
+    previewLayerId: getPreviewLayerId(draggedKey, placement),
+    previewLayerIndex: getPreviewLayerIndex(input.layerOrder, placement),
+    stackingReorder: resolveTimelineLayerZIndexChanges({
+      element: input.element,
+      layers: contextLayers,
+      placement,
+    }),
+  };
+}

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

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { computeTimelineBasisDuration, computeTimelineEffectiveDuration } from "./timelineLayout";
+
+describe("computeTimelineBasisDuration", () => {
+  it("uses the root duration when it exceeds every clip end", () => {
+    expect(computeTimelineBasisDuration(12, [4, 6, 9])).toBe(12);
+  });
+
+  it("grows to the furthest committed clip end past the root duration", () => {
+    expect(computeTimelineBasisDuration(12, [4, 18, 9])).toBe(18);
+  });
+
+  it("falls back to the root duration with no clips / non-finite ends", () => {
+    expect(computeTimelineBasisDuration(10, [])).toBe(10);
+    expect(computeTimelineBasisDuration(Number.NaN, [])).toBe(0);
+  });
+});
+
+describe("computeTimelineEffectiveDuration", () => {
+  it("returns the basis when there is no active preview", () => {
+    expect(computeTimelineEffectiveDuration(12, [null, null])).toBe(12);
+  });
+
+  it("extends to a drag/resize preview end beyond the basis", () => {
+    expect(computeTimelineEffectiveDuration(12, [20, null])).toBe(20);
+    expect(computeTimelineEffectiveDuration(12, [null, 16])).toBe(16);
+  });
+
+  it("never shrinks below the basis for a preview inside the current length", () => {
+    // The invariant behind the jump fix: the basis (which drives zoom) is
+    // independent of the preview, and a smaller preview end can't reduce it.
+    expect(computeTimelineEffectiveDuration(12, [8])).toBe(12);
+  });
+});

package/src/player/components/timelineLayout.ts

@@ -9,6 +9,37 @@ export const CLIP_Y = 3;
 export const CLIP_HANDLE_W = 18;
 const TIMELINE_SCROLL_BUFFER = 20;
 
+/* ── Timeline duration ─────────────────────────────────────────────── */
+
+// Committed timeline length: root duration or the furthest committed clip end,
+// with NO live drag/resize preview. This drives the zoom (fit-to-width pps) so
+// the pixels-per-second mapping stays fixed while you drag — otherwise a clip
+// dragged past the end grows the duration, shrinks pps, and jumps under the
+// pointer (a positive-feedback loop). The zoom re-fits once on drop.
+export function computeTimelineBasisDuration(
+  rootDuration: number,
+  clipEnds: readonly number[],
+): number {
+  const safeDur = Number.isFinite(rootDuration) ? rootDuration : 0;
+  if (clipEnds.length === 0) return safeDur;
+  const maxEnd = Math.max(safeDur, ...clipEnds);
+  return Number.isFinite(maxEnd) ? maxEnd : safeDur;
+}
+
+// Displayed length: the basis plus any active drag/resize preview end, so the
+// ruler and track width grow to follow a clip dragged past the current end
+// (with the zoom held fixed, the extra length becomes scrollable content).
+export function computeTimelineEffectiveDuration(
+  basisDuration: number,
+  previewEnds: readonly (number | null)[],
+): number {
+  let maxEnd = basisDuration;
+  for (const end of previewEnds) {
+    if (end != null && Number.isFinite(end)) maxEnd = Math.max(maxEnd, end);
+  }
+  return maxEnd;
+}
+
 /* ── 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];
@@ -56,6 +87,22 @@ export function generateTicks(
   return { major, minor };
 }
 
+/**
+ * Ticks spanning the full visible ruler width, not just the composition, so a
+ * zoomed-out ruler stays filled with labels instead of ending mid-panel. The
+ * major/minor interval is driven by pixelsPerSecond (pixel spacing), so widening
+ * the range keeps spacing identical — it only adds ticks past the content end.
+ */
+export function generateVisibleTicks(
+  effectiveDuration: number,
+  pixelsPerSecond: number,
+  viewportWidth: number,
+  gutter: number,
+): { major: number[]; minor: number[] } {
+  const visible = viewportWidth > gutter ? (viewportWidth - gutter) / pixelsPerSecond : 0;
+  return generateTicks(Math.max(effectiveDuration, visible), pixelsPerSecond);
+}
+
 export function formatTimelineTickLabel(time: number, duration: number, majorInterval: number) {
   if (!Number.isFinite(time)) return "0:00";
   const safeTime = Math.max(0, time);