@hyperframes/studio 0.7.56 → 0.7.58

package/src/player/components/timelineLayout.ts

@@ -31,6 +31,17 @@ export const INSERT_BOUNDARY_BAND = CLIP_Y / TRACK_H;
  */
 export const TRACKS_TOP_PAD = 50;
 export const TRACKS_BOTTOM_PAD = Math.round(TRACK_H * 1.5);
+/**
+ * Breathing room LEFT of t=0 (CapCut-style), inside the scroll content — the
+ * horizontal sibling of TRACKS_TOP_PAD: empty lane surface between the sticky
+ * gutter and where the ruler's 00:00 / the clips actually start, scrolling
+ * WITH the content. Time↔pixel mapping: content x = GUTTER + TRACKS_LEFT_PAD
+ * + t·pps, and every pointer→time inverse subtracts it symmetrically. The
+ * lanes and the ruler realize it as a plain flow spacer between the sticky
+ * gutter cell and the time-mapped content div, so all content-relative math
+ * (clip left = t·pps, beat lines, lane-menu time) is untouched.
+ */
+export const TRACKS_LEFT_PAD = 48;
 
 /**
  * The y (content-space) of the top edge of track ROW index `row` (0 = first
@@ -67,51 +78,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;
+  }
+  // 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;
   }
-  const durationIntervals = [0.25, 0.5, 1, 2, 5, 10, 15, 30, 60];
-  const target = duration / 6;
-  return durationIntervals.find((interval) => interval >= target) ?? 60;
+  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,17 +209,19 @@ 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);
-  if (!Number.isFinite(viewportWidth) || viewportWidth <= GUTTER) return 100;
-  return (viewportWidth - GUTTER - 2) / span;
+  const span = Math.max(safeDuration * FIT_ZOOM_HEADROOM, MIN_TIMELINE_EXTENT_S);
+  if (!Number.isFinite(viewportWidth) || viewportWidth <= GUTTER + TRACKS_LEFT_PAD) return 100;
+  return (viewportWidth - GUTTER - TRACKS_LEFT_PAD - 2) / span;
 }
 
 /**
@@ -174,7 +241,7 @@ export function getTimelineDisplayContentWidth(input: {
   const safePps = Number.isFinite(input.pps) ? Math.max(input.pps, 0) : 0;
   return Math.max(
     input.trackContentWidth,
-    input.viewportWidth - GUTTER - 2,
+    input.viewportWidth - GUTTER - TRACKS_LEFT_PAD - 2,
     input.dragGhostEndPx ?? 0,
     input.resizeGhostEndPx ?? 0,
     MIN_TIMELINE_EXTENT_S * safePps,
@@ -227,9 +294,31 @@ 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 + TRACKS_LEFT_PAD - PLAYHEAD_HEAD_W / 2;
+  }
+  return (
+    GUTTER +
+    TRACKS_LEFT_PAD +
+    Math.max(0, time) * Math.max(0, pixelsPerSecond) -
+    PLAYHEAD_HEAD_W / 2
+  );
 }
 
 export function getTimelineCanvasHeight(trackCount: number): number {
@@ -300,7 +389,7 @@ export function resolveTimelineAssetDrop(
   clientX: number,
   clientY: number,
 ): { start: number; track: number } {
-  const x = clientX - input.rectLeft + input.scrollLeft - GUTTER;
+  const x = clientX - input.rectLeft + input.scrollLeft - GUTTER - TRACKS_LEFT_PAD;
   const contentY = clientY - input.rectTop + input.scrollTop;
   const start = Math.max(
     0,

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

@@ -7,7 +7,17 @@ import {
   getTimelineClipRect,
   computeMarqueeSelection,
 } from "./timelineMarquee";
-import { GUTTER, TRACK_H, RULER_H, CLIP_Y, getTimelineRowTop } from "./timelineLayout";
+import {
+  GUTTER,
+  TRACK_H,
+  RULER_H,
+  CLIP_Y,
+  TRACKS_LEFT_PAD,
+  getTimelineRowTop,
+} from "./timelineLayout";
+
+// Canvas-space time origin: right edge of the sticky gutter + the left pad.
+const ORIGIN = GUTTER + TRACKS_LEFT_PAD;
 
 describe("isTimelineRulerPress", () => {
   const rectTop = 500; // scroll container's viewport top
@@ -86,7 +96,7 @@ describe("getTimelineClipRect", () => {
   it("maps start/duration to x via pps and the track row to y via the shared row→y helper", () => {
     const rect = getTimelineClipRect({ start: 2, duration: 3, track: 2 }, trackOrder, 100);
     expect(rect).toEqual({
-      left: GUTTER + 200,
+      left: ORIGIN + 200,
       top: getTimelineRowTop(1) + CLIP_Y,
       width: 300,
       height: TRACK_H - CLIP_Y * 2,
@@ -96,7 +106,7 @@ describe("getTimelineClipRect", () => {
   it("places the first visible track below the ruler + top breathing pad", () => {
     const rect = getTimelineClipRect({ start: 0, duration: 1, track: 0 }, trackOrder, 50);
     expect(rect?.top).toBe(getTimelineRowTop(0) + CLIP_Y);
-    expect(rect?.left).toBe(GUTTER);
+    expect(rect?.left).toBe(ORIGIN);
   });
 
   it("uses the row index in trackOrder, not the raw track number", () => {
@@ -129,26 +139,26 @@ describe("computeMarqueeSelection", () => {
   const row1Top = getTimelineRowTop(1) + CLIP_Y;
 
   it("selects only the clips the marquee rect intersects", () => {
-    const marquee = { left: GUTTER, top: row0Top, width: 50, height: 10 };
+    const marquee = { left: ORIGIN, top: row0Top, width: 50, height: 10 };
     const { ids, primaryId } = computeMarqueeSelection({ clips, trackOrder, pps, marquee });
     expect(ids).toEqual(new Set(["a"]));
     expect(primaryId).toBe("a");
   });
 
   it("selects across tracks when the rect spans multiple rows", () => {
-    const marquee = { left: GUTTER, top: row0Top, width: 60, height: row1Top - row0Top + 5 };
+    const marquee = { left: ORIGIN, top: row0Top, width: 60, height: row1Top - row0Top + 5 };
     const { ids } = computeMarqueeSelection({ clips, trackOrder, pps, marquee });
     expect(ids).toEqual(new Set(["a", "c"]));
   });
 
   it("excludes clips outside the rect horizontally", () => {
-    const marquee = { left: GUTTER + 140, top: row0Top, width: 50, height: 10 };
+    const marquee = { left: ORIGIN + 140, top: row0Top, width: 50, height: 10 };
     const { ids } = computeMarqueeSelection({ clips, trackOrder, pps, marquee });
     expect(ids).toEqual(new Set());
   });
 
   it("returns null primaryId and keeps the base when nothing is hit (additive)", () => {
-    const marquee = { left: GUTTER + 140, top: row0Top, width: 50, height: 10 };
+    const marquee = { left: ORIGIN + 140, top: row0Top, width: 50, height: 10 };
     const { ids, primaryId } = computeMarqueeSelection({
       clips,
       trackOrder,
@@ -161,7 +171,7 @@ describe("computeMarqueeSelection", () => {
   });
 
   it("unions additive base selection with new hits; primary comes from the marquee", () => {
-    const marquee = { left: GUTTER, top: row1Top, width: 100, height: 10 };
+    const marquee = { left: ORIGIN, top: row1Top, width: 100, height: 10 };
     const { ids, primaryId } = computeMarqueeSelection({
       clips,
       trackOrder,
@@ -174,8 +184,8 @@ describe("computeMarqueeSelection", () => {
   });
 
   it("shrinking the rect live drops clips it no longer covers", () => {
-    const wide = { left: GUTTER, top: row0Top, width: 320, height: 10 };
-    const narrow = { left: GUTTER, top: row0Top, width: 80, height: 10 };
+    const wide = { left: ORIGIN, top: row0Top, width: 320, height: 10 };
+    const narrow = { left: ORIGIN, top: row0Top, width: 80, height: 10 };
     expect(computeMarqueeSelection({ clips, trackOrder, pps, marquee: wide }).ids).toEqual(
       new Set(["a", "b"]),
     );

package/src/player/components/timelineMarquee.ts

@@ -1,4 +1,11 @@
-import { GUTTER, TRACK_H, RULER_H, CLIP_Y, getTimelineRowTop } from "./timelineLayout";
+import {
+  GUTTER,
+  TRACK_H,
+  RULER_H,
+  CLIP_Y,
+  TRACKS_LEFT_PAD,
+  getTimelineRowTop,
+} from "./timelineLayout";
 import { rectsOverlap, type Rect } from "../../utils/marqueeGeometry";
 
 /** Pointer must travel at least this far (either axis) before a pointerdown on
@@ -73,7 +80,7 @@ export function getTimelineClipRect(
   const row = trackOrder.indexOf(clip.track);
   if (row < 0 || !Number.isFinite(pps) || pps <= 0) return null;
   return {
-    left: GUTTER + clip.start * pps,
+    left: GUTTER + TRACKS_LEFT_PAD + clip.start * pps,
     top: getTimelineRowTop(row) + CLIP_Y,
     width: Math.max(clip.duration * pps, MIN_CLIP_W),
     height: TRACK_H - CLIP_Y * 2,

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

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+import {
+  computeRevealScroll,
+  REVEAL_SCROLL_PADDING_PX,
+  type RevealScrollInput,
+} from "./timelineRevealScroll";
+
+/** A 1000×400 viewport with a 32px sticky gutter and 24px sticky ruler. */
+function makeInput(overrides: Partial<RevealScrollInput> = {}): RevealScrollInput {
+  return {
+    scrollLeft: 0,
+    scrollTop: 0,
+    viewportWidth: 1000,
+    viewportHeight: 400,
+    clipLeft: 100,
+    clipRight: 200,
+    clipTop: 100,
+    clipBottom: 148,
+    stickyLeft: 32,
+    stickyTop: 24,
+    allowHorizontal: true,
+    ...overrides,
+  };
+}
+
+describe("computeRevealScroll", () => {
+  it("returns null on both axes when the clip is fully visible", () => {
+    expect(computeRevealScroll(makeInput())).toEqual({ left: null, top: null });
+  });
+
+  it("scrolls right minimally when the clip end is past the right edge", () => {
+    const result = computeRevealScroll(makeInput({ clipLeft: 1500, clipRight: 1600 }));
+    // Clip end lands padding px inside the right edge.
+    expect(result.left).toBe(1600 - 1000 + REVEAL_SCROLL_PADDING_PX);
+    expect(result.top).toBeNull();
+  });
+
+  it("scrolls left when the clip start is hidden (including under the sticky gutter)", () => {
+    const result = computeRevealScroll(
+      makeInput({ scrollLeft: 500, clipLeft: 510, clipRight: 610 }),
+    );
+    // clipLeft 510 sits under the 32px sticky gutter (window starts at 500+32+pad).
+    expect(result.left).toBe(510 - 32 - REVEAL_SCROLL_PADDING_PX);
+  });
+
+  it("aligns the start edge when the clip is wider than the viewport", () => {
+    const result = computeRevealScroll(makeInput({ clipLeft: 2000, clipRight: 4000 }));
+    expect(result.left).toBe(2000 - 32 - REVEAL_SCROLL_PADDING_PX);
+  });
+
+  it("never returns a negative scroll target", () => {
+    const result = computeRevealScroll(
+      makeInput({
+        scrollLeft: 300,
+        clipLeft: 10,
+        clipRight: 60,
+        scrollTop: 200,
+        clipTop: 4,
+        clipBottom: 20,
+      }),
+    );
+    expect(result.left).toBe(0);
+    expect(result.top).toBe(0);
+  });
+
+  it("suppresses horizontal scroll when allowHorizontal is false (fit zoom)", () => {
+    const result = computeRevealScroll(
+      makeInput({
+        allowHorizontal: false,
+        clipLeft: 1500,
+        clipRight: 1600,
+        clipTop: 700,
+        clipBottom: 748,
+      }),
+    );
+    expect(result.left).toBeNull();
+    // Vertical reveal still happens.
+    expect(result.top).toBe(748 - 400 + REVEAL_SCROLL_PADDING_PX);
+  });
+
+  it("scrolls up when the clip lane is hidden under the sticky ruler", () => {
+    const result = computeRevealScroll(
+      makeInput({ scrollTop: 200, clipTop: 210, clipBottom: 258 }),
+    );
+    // clipTop 210 sits under the 24px sticky ruler (window starts at 200+24+pad).
+    expect(result.top).toBe(210 - 24 - REVEAL_SCROLL_PADDING_PX);
+  });
+
+  it("scrolls down minimally when the clip lane is below the viewport", () => {
+    const result = computeRevealScroll(makeInput({ clipTop: 500, clipBottom: 548 }));
+    expect(result.top).toBe(548 - 400 + REVEAL_SCROLL_PADDING_PX);
+    expect(result.left).toBeNull();
+  });
+
+  it("never scrolls on an axis whose visible window is degenerate", () => {
+    // Horizontal window collapses: 40px viewport minus the 32px gutter and
+    // 2x12px padding is negative; vertical is intact and still reveals.
+    const result = computeRevealScroll(
+      makeInput({
+        viewportWidth: 40,
+        clipLeft: 1500,
+        clipRight: 1600,
+        clipTop: 500,
+        clipBottom: 548,
+      }),
+    );
+    expect(result.left).toBeNull();
+    expect(result.top).toBe(548 - 400 + REVEAL_SCROLL_PADDING_PX);
+
+    // Exactly-zero window (viewport == sticky + 2x padding) is degenerate too.
+    const zero = computeRevealScroll(
+      makeInput({
+        viewportWidth: 32 + 2 * REVEAL_SCROLL_PADDING_PX,
+        clipLeft: 1500,
+        clipRight: 1600,
+      }),
+    );
+    expect(zero.left).toBeNull();
+
+    // Both axes degenerate: no scroll at all.
+    const both = computeRevealScroll(
+      makeInput({
+        viewportWidth: 10,
+        viewportHeight: 10,
+        clipLeft: 1500,
+        clipRight: 1600,
+        clipTop: 500,
+        clipBottom: 548,
+      }),
+    );
+    expect(both).toEqual({ left: null, top: null });
+  });
+});

package/src/player/components/timelineRevealScroll.ts

@@ -0,0 +1,91 @@
+/**
+ * Pure scroll-target math for revealing a timeline clip inside the timeline's
+ * scroll container (the overflow div in Timeline.tsx).
+ *
+ * Coordinates are content-space: a clip edge measured from the scroll
+ * container's content origin (rect delta + current scroll offset). The visible
+ * window on each axis is reduced by the sticky chrome that occludes it — the
+ * track gutter on the left (GUTTER) and the ruler on top (RULER_H) — so a clip
+ * "hidden" under the sticky gutter still counts as off-screen.
+ *
+ * Scrolls minimally: an axis already fully visible returns null for that axis;
+ * otherwise the nearest edge is brought just inside the window (plus padding).
+ * A clip larger than the window aligns its start edge. Pure — unit-tested.
+ */
+
+export interface RevealScrollInput {
+  scrollLeft: number;
+  scrollTop: number;
+  /** Scroll container clientWidth / clientHeight. */
+  viewportWidth: number;
+  viewportHeight: number;
+  /** Clip bounds in content-space (relative to the scroll content origin). */
+  clipLeft: number;
+  clipRight: number;
+  clipTop: number;
+  clipBottom: number;
+  /** Width of the sticky left gutter occluding the viewport's left edge. */
+  stickyLeft: number;
+  /** Height of the sticky ruler occluding the viewport's top edge. */
+  stickyTop: number;
+  /** False in "fit" zoom mode, where horizontal scrolling is disabled. */
+  allowHorizontal: boolean;
+}
+
+export interface RevealScrollTarget {
+  /** Target scrollLeft, or null when the horizontal axis needs no scroll. */
+  left: number | null;
+  /** Target scrollTop, or null when the vertical axis needs no scroll. */
+  top: number | null;
+}
+
+/** Breathing room between the revealed clip edge and the window edge. */
+export const REVEAL_SCROLL_PADDING_PX = 12;
+
+/**
+ * Minimal scroll on one axis to bring [start, end] inside the visible window
+ * [scroll + stickyStart, scroll + viewport], with padding. Returns null when
+ * the range is already fully visible.
+ */
+function revealAxis(
+  scroll: number,
+  viewport: number,
+  stickyStart: number,
+  start: number,
+  end: number,
+): number | null {
+  const windowStart = scroll + stickyStart + REVEAL_SCROLL_PADDING_PX;
+  const windowEnd = scroll + viewport - REVEAL_SCROLL_PADDING_PX;
+  const windowSize = windowEnd - windowStart;
+  // Degenerate viewport (container smaller than the sticky chrome + padding):
+  // there is no visible window to reveal into, so never scroll on this axis.
+  if (windowSize <= 0) return null;
+  if (start >= windowStart && end <= windowEnd) return null;
+  // Oversized range (or start hidden): align the start edge to the window start.
+  if (end - start > windowSize || start < windowStart) {
+    return Math.max(0, start - stickyStart - REVEAL_SCROLL_PADDING_PX);
+  }
+  // Only the end is clipped: pull it just inside the window's far edge.
+  return Math.max(0, end - viewport + REVEAL_SCROLL_PADDING_PX);
+}
+
+export function computeRevealScroll(input: RevealScrollInput): RevealScrollTarget {
+  return {
+    left: input.allowHorizontal
+      ? revealAxis(
+          input.scrollLeft,
+          input.viewportWidth,
+          input.stickyLeft,
+          input.clipLeft,
+          input.clipRight,
+        )
+      : null,
+    top: revealAxis(
+      input.scrollTop,
+      input.viewportHeight,
+      input.stickyTop,
+      input.clipTop,
+      input.clipBottom,
+    ),
+  };
+}

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

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { computeStackingPatches, laneIsAbove, type StackingElement } from "./timelineStackingSync";
+import {
+  computeStackingPatches,
+  laneIsAbove,
+  samePaintScope,
+  type StackingElement,
+} from "./timelineStackingSync";
 
 function el(
   key: string,
@@ -19,6 +24,102 @@ function patchMap(elements: StackingElement[], edited: string[]): Record<string,
   return out;
 }
 
+describe("stacking-context partitioning", () => {
+  it("uses source file and normalized stacking context as the canonical paint scope", () => {
+    expect(samePaintScope({}, { stackingContextId: null })).toBe(true);
+    expect(samePaintScope({}, { sourceFile: "index.html" })).toBe(false);
+    expect(
+      samePaintScope(
+        { sourceFile: "scene.html", stackingContextId: "card" },
+        { sourceFile: "scene.html", stackingContextId: "modal" },
+      ),
+    ).toBe(false);
+  });
+
+  it("never compares or patches across source files in the root context", () => {
+    const root: StackingElement = {
+      key: "root",
+      track: 0,
+      start: 0,
+      duration: 5,
+      zIndex: 1,
+      isAudio: false,
+      sourceFile: "index.html",
+      stackingContextId: null,
+    };
+    const scene: StackingElement = {
+      key: "scene",
+      track: 1,
+      start: 0,
+      duration: 5,
+      zIndex: 10,
+      isAudio: false,
+      sourceFile: "scenes/scene.html",
+      stackingContextId: null,
+    };
+
+    expect(patchMap([root, scene], ["root"])).toEqual({});
+  });
+
+  it("never compares or patches across stacking contexts", () => {
+    // X lives in sub-comp context "scene-1" with a high leaf z; Y is a root clip
+    // with a lower leaf z, overlapping in time. Their leaf z values are NOT
+    // comparable (the ancestors' z decides paint order), so moving X's lane above
+    // Y must not reason on Y or patch either based on the 10-vs-5 comparison.
+    const x: StackingElement = {
+      key: "x",
+      track: 0,
+      start: 0,
+      duration: 5,
+      zIndex: 10,
+      isAudio: false,
+      stackingContextId: "scene-1",
+    };
+    const y: StackingElement = {
+      key: "y",
+      track: 1,
+      start: 0,
+      duration: 5,
+      zIndex: 5,
+      isAudio: false,
+      stackingContextId: null,
+    };
+    // X edited: only same-context neighbours participate — none here, so X keeps
+    // its z (nothing to fix WITHIN its context) and Y is never touched.
+    expect(patchMap([x, y], ["x"])).toEqual({});
+  });
+
+  it("still resolves within the edited clip's own context", () => {
+    const a: StackingElement = {
+      key: "a",
+      track: 1,
+      start: 0,
+      duration: 5,
+      zIndex: 1,
+      isAudio: false,
+      stackingContextId: "scene-1",
+    };
+    const b: StackingElement = {
+      key: "b",
+      track: 0,
+      start: 0,
+      duration: 5,
+      zIndex: 5,
+      isAudio: false,
+      stackingContextId: "scene-1",
+    };
+    // 'a' moved BELOW b's lane... a (track 1) is under b (track 0): a's z (1)
+    // is already below b's (5) — consistent, no patch. Move a ABOVE (track -1
+    // relative ordering) is covered by existing suites; here we just prove the
+    // same-context pair still participates (no patch ≠ no participation: verify
+    // by flipping z so a MUST be lifted).
+    const aWrong = { ...a, track: 0, zIndex: 1 };
+    const bLow = { ...b, track: 1, zIndex: 5 };
+    const patches = patchMap([aWrong, bLow], ["a"]);
+    expect(patches.a).toBeGreaterThan(5);
+  });
+});
+
 describe("laneIsAbove", () => {
   it("lower track renders above (top of timeline wins)", () => {
     expect(laneIsAbove({ track: 0 }, { track: 1 })).toBe(true);