@hyperframes/studio 0.7.55 → 0.7.57

package/src/player/components/timelineOptimisticRevision.ts

@@ -0,0 +1,42 @@
+import type { TimelineElement } from "../store/playerStore";
+
+type UpdateElement = (key: string, updates: Partial<TimelineElement>) => void;
+const revisionsByUpdater = new WeakMap<UpdateElement, Map<string, number>>();
+
+export function beginTimelineOptimisticGesture(
+  updateElement: UpdateElement,
+  keys: readonly string[],
+): Map<string, number> {
+  let revisions = revisionsByUpdater.get(updateElement);
+  if (!revisions) {
+    revisions = new Map();
+    revisionsByUpdater.set(updateElement, revisions);
+  }
+  const gesture = new Map<string, number>();
+  for (const key of keys) {
+    const revision = (revisions.get(key) ?? 0) + 1;
+    revisions.set(key, revision);
+    gesture.set(key, revision);
+  }
+  return gesture;
+}
+
+export function isLatestTimelineOptimisticGesture(
+  updateElement: UpdateElement,
+  gesture: ReadonlyMap<string, number>,
+  key: string,
+): boolean {
+  return revisionsByUpdater.get(updateElement)?.get(key) === gesture.get(key);
+}
+
+export function rollbackLatestTimelineOptimisticGesture(
+  updateElement: UpdateElement,
+  gesture: ReadonlyMap<string, number>,
+  rollbacks: ReadonlyArray<{ key: string; updates: Partial<TimelineElement> }>,
+): void {
+  for (const rollback of rollbacks) {
+    if (isLatestTimelineOptimisticGesture(updateElement, gesture, rollback.key)) {
+      updateElement(rollback.key, rollback.updates);
+    }
+  }
+}

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

@@ -19,6 +19,66 @@ function patchMap(elements: StackingElement[], edited: string[]): Record<string,
   return out;
 }
 
+describe("stacking-context partitioning", () => {
+  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);

package/src/player/components/timelineStackingSync.ts

@@ -43,6 +43,13 @@ export interface StackingElement {
   zIndex: number;
   /** Audio clips have no visual stacking and are excluded from the computation. */
   isAudio: boolean;
+  /**
+   * CSS stacking context the clip's node lives in (TimelineElement.stackingContextId).
+   * Leaf z-indexes are only comparable WITHIN one context — across contexts the
+   * ancestors' z decides paint order — so the sync partitions by this key and
+   * never patches across contexts. Null/undefined ⇒ the root context.
+   */
+  stackingContextId?: string | null;
   /**
    * Discovery / DOM document position (optional). Two clips with EQUAL z paint by
    * DOM order — the one LATER in the DOM paints ON TOP. When supplied, "is A above
@@ -62,6 +69,14 @@ export interface StackingPatch {
 
 const EPS = 1e-6;
 
+/**
+ * Canonical stacking-context key: null/undefined both mean the root context.
+ * The ONLY place the normalization lives — context partitioning, membership
+ * checks, and pairwise equality must all go through it.
+ */
+const contextKey = (el: { stackingContextId?: string | null }): string | null =>
+  el.stackingContextId ?? null;
+
 /**
  * Two clips overlap in time when their half-open [start, end) intervals intersect.
  *
@@ -284,7 +299,14 @@ export function computeStackingPatches(
   // z=0 would enter the boundary math as a phantom neighbour at the z-floor. An
   // unresolved clip is neither a neighbour nor resolvable as an edit, so it is
   // excluded outright (item 13).
-  const resolved = elements.filter((e) => Number.isFinite(e.zIndex));
+  const allResolved = elements.filter((e) => Number.isFinite(e.zIndex));
+
+  // Leaf z is only meaningful within ONE stacking context: across contexts the
+  // ancestor contexts' z decides paint order, so comparing (or patching) leaf
+  // values across contexts is nonsense. Restrict the computation to the edited
+  // clips' own context(s); cross-context lane relations are out of scope.
+  const editedContexts = new Set(allResolved.filter((e) => editedSet.has(e.key)).map(contextKey));
+  const resolved = allResolved.filter((e) => editedContexts.has(contextKey(e)));
 
   // Mutable z snapshot so edits + cascaded bumps see each other's applied z.
   const byKey = new Map<string, MutZ>(resolved.map((e) => [e.key, { ...e }]));
@@ -304,8 +326,11 @@ export function computeStackingPatches(
   // The full live set, so the transitive cascade can reach clips that overlap a
   // LIFTED neighbour without overlapping the edited clip itself (#2198).
   const all = [...byKey.values()];
+  const sameContext = (a: MutZ, b: MutZ) => contextKey(a) === contextKey(b);
   const overlappersOf = (clip: MutZ): MutZ[] =>
-    all.filter((o) => o.key !== clip.key && !o.isAudio && overlapsInTime(clip, o));
+    all.filter(
+      (o) => o.key !== clip.key && !o.isAudio && sameContext(clip, o) && overlapsInTime(clip, o),
+    );
 
   for (const clip of edited) {
     resolveEditedZ(clip, overlappersOf(clip), overlappersOf, patchZ);

package/src/player/components/timelineTheme.ts

@@ -43,10 +43,15 @@ const TRACK_STYLE: TimelineTrackStyle = {
 };
 
 export const defaultTimelineTheme: TimelineTheme = {
+  // Near-black card surfaces: the panels sit dark while the shell canvas
+  // between them is a step LIGHTER (#18181B), so the gaps read as visible
+  // seams around dark cards (CapCut-style).
   shellBackground: "#0A0A0B",
   shellBorder: "rgba(255,255,255,0.05)",
   rulerBorder: "rgba(255,255,255,0.16)",
-  rowBackground: "#0B0C0F",
+  // All track lanes use a single uniform color — one step lighter than the panel
+  // surface (#0A0A0B) so lanes are visibly distinct from the ruler/shell.
+  rowBackground: "#101014",
   rowBorder: "rgba(255,255,255,0.06)",
   gutterBackground: "#0E0F12",
   gutterBorder: "rgba(255,255,255,0.10)",

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

@@ -0,0 +1,168 @@
+import { describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import type { ClipManifestClip } from "../lib/playbackTypes";
+import { createTimelineElementFromManifestClip } from "../lib/timelineDOM";
+import { buildExpandedElements } from "../hooks/useExpandedTimelineElements";
+import { normalizeToZones } from "./timelineZones";
+import { commitDraggedClipMove, type TimelineMoveEdit } from "./timelineClipDragCommit";
+import type { DraggedClipState } from "./useTimelineClipDrag";
+
+/**
+ * Pipeline test across the REAL manifest→element boundary: no hand-injected
+ * `authoredTrack` / `stackingContextId`. A runtime-manifest-shaped payload with
+ * SPARSE authored tracks flows through createTimelineElementFromManifestClip →
+ * (normalizeToZones | buildChildElements) → commitDraggedClipMove, and the
+ * persisted data-track-index must be the AUTHORED target, never the display lane.
+ */
+
+const manifestClip = (over: Partial<ClipManifestClip>): ClipManifestClip => ({
+  id: "x",
+  label: "x",
+  start: 0,
+  duration: 2,
+  track: 0,
+  stackingContextId: "root",
+  kind: "element",
+  tagName: "div",
+  compositionId: null,
+  parentCompositionId: null,
+  compositionSrc: null,
+  assetUrl: null,
+  ...over,
+});
+
+function fromManifest(clips: ClipManifestClip[]): TimelineElement[] {
+  return clips.map((clip, index) =>
+    createTimelineElementFromManifestClip({ clip, fallbackIndex: index }),
+  );
+}
+
+function drag(
+  element: TimelineElement,
+  opts: { previewStart: number; previewTrack: number },
+): DraggedClipState {
+  return {
+    element,
+    originClientX: 0,
+    originClientY: 0,
+    originScrollLeft: 0,
+    originScrollTop: 0,
+    pointerClientX: 0,
+    pointerClientY: 0,
+    pointerOffsetX: 0,
+    pointerOffsetY: 0,
+    previewStart: opts.previewStart,
+    previewTrack: opts.previewTrack,
+    desiredTrack: opts.previewTrack,
+    insertRow: null,
+    snapTime: null,
+    snapType: null,
+    started: true,
+  };
+}
+
+/** Commit a lane-change drag and return the single persisted edit batch. */
+function commitLaneChange(
+  element: TimelineElement,
+  previewTrack: number,
+  elements: TimelineElement[],
+  trackOrder: number[],
+): TimelineMoveEdit[] {
+  const onMoveElements = vi.fn();
+  commitDraggedClipMove(drag(element, { previewStart: element.start, previewTrack }), {
+    elements,
+    trackOrder,
+    updateElement: vi.fn(),
+    onMoveElements,
+  });
+  expect(onMoveElements).toHaveBeenCalledTimes(1);
+  return onMoveElements.mock.calls[0][0] as TimelineMoveEdit[];
+}
+
+describe("track persist pipeline (manifest → factory → lanes → drag commit)", () => {
+  // Sparse authored tracks 3 and 7 (mixed kinds), plus audio on 5, exactly as a
+  // runtime manifest would ship them (clip.track is the verbatim data-track-index).
+  const sparseManifest = [
+    manifestClip({ id: "v", kind: "video", tagName: "video", track: 3, start: 0 }),
+    manifestClip({ id: "g", kind: "element", tagName: "div", track: 7, start: 10 }),
+    manifestClip({ id: "m", kind: "audio", tagName: "audio", track: 5, start: 0 }),
+  ];
+
+  it("factory records the authored track and stacking context from the manifest clip", () => {
+    const [v, g, m] = fromManifest(sparseManifest);
+    expect([v.authoredTrack, g.authoredTrack, m.authoredTrack]).toEqual([3, 7, 5]);
+    expect(v.stackingContextId).toBe("root");
+  });
+
+  it("a lane change on a sparse file persists the AUTHORED target track, not the display lane", () => {
+    // normalizeToZones packs visual tracks {3, 7} onto display lanes {0, 1} and
+    // the audio track 5 onto lane 2, preserving the factory-set authoredTrack.
+    const elements = normalizeToZones(fromManifest(sparseManifest));
+    const byId = new Map(elements.map((e) => [e.id, e]));
+    expect(byId.get("v")).toMatchObject({ track: 0, authoredTrack: 3 });
+    expect(byId.get("g")).toMatchObject({ track: 1, authoredTrack: 7 });
+    expect(byId.get("m")).toMatchObject({ track: 2, authoredTrack: 5 });
+
+    // Drag the video (lane 0) onto the div's lane (display 1, authored 7).
+    const down = commitLaneChange(byId.get("v")!, 1, elements, [0, 1, 2]);
+    expect(down).toHaveLength(1);
+    expect(down[0].updates.track).toBe(7); // authored, NOT display lane 1
+    expect(down[0].updates.track).not.toBe(1);
+
+    // And the reverse: the div (lane 1) onto the video's lane (display 0, authored 3).
+    const up = commitLaneChange(byId.get("g")!, 0, elements, [0, 1, 2]);
+    expect(up[0].updates.track).toBe(3); // authored, NOT display lane 0
+  });
+
+  it("an expanded sub-comp child's lane change persists the sibling's authored track from ITS file", () => {
+    // Host timeline: the sub-comp host plus a root clip, discovered through the
+    // factory and lane-normalized like the store does.
+    const hostManifest = [
+      manifestClip({
+        id: "scene",
+        kind: "composition",
+        tagName: "div",
+        track: 0,
+        start: 0,
+        duration: 10,
+        compositionId: "scene",
+        compositionSrc: "scene.html",
+      }),
+      manifestClip({ id: "root-clip", kind: "video", tagName: "video", track: 1, start: 0 }),
+    ];
+    // scene.html has SPARSE authored tracks 3 and 7.
+    const childClips = [
+      manifestClip({ id: "c3", track: 3, start: 1, duration: 2, parentCompositionId: "scene" }),
+      manifestClip({ id: "c7", track: 7, start: 4, duration: 2, parentCompositionId: "scene" }),
+    ];
+    const storeElements = normalizeToZones(fromManifest(hostManifest));
+    const parentMap = new Map([
+      ["c3", "scene"],
+      ["c7", "scene"],
+    ]);
+    const expanded = buildExpandedElements(
+      storeElements,
+      [...hostManifest, ...childClips],
+      parentMap,
+      "scene",
+      "scene",
+    );
+
+    // The children replaced the host row: synthetic display lanes, but the
+    // authored track (in scene.html's coordinate space) survived the expansion.
+    const c3 = expanded.find((e) => e.domId === "c3")!;
+    const c7 = expanded.find((e) => e.domId === "c7")!;
+    expect(c3).toMatchObject({ authoredTrack: 3, sourceFile: "scene.html" });
+    expect(c7).toMatchObject({ authoredTrack: 7, sourceFile: "scene.html" });
+    expect(c3.stackingContextId).toBe("root");
+    expect(c3.track).not.toBe(3); // display row is synthetic
+
+    // Drag c3 onto c7's display lane: the persist target is c3's OWN file, so
+    // the written track must be c7's authored 7 — not the display-lane integer.
+    const trackOrder = [...new Set(expanded.map((e) => e.track))].sort((a, b) => a - b);
+    const edits = commitLaneChange(c3, c7.track, expanded, trackOrder);
+    expect(edits).toHaveLength(1);
+    expect(edits[0].updates.track).toBe(7);
+    expect(edits[0].updates.track).not.toBe(c7.track);
+  });
+});