@hyperframes/studio 0.7.56 → 0.7.58

package/src/player/components/timelineStackingSync.ts

@@ -43,6 +43,15 @@ export interface StackingElement {
   zIndex: number;
   /** Audio clips have no visual stacking and are excluded from the computation. */
   isAudio: boolean;
+  /** Source document. Leaf z-indexes are comparable only inside this file. */
+  sourceFile?: string;
+  /**
+   * 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 +71,22 @@ export interface StackingPatch {
 
 const EPS = 1e-6;
 
+/**
+ * Canonical paint-scope key: leaf z-indexes are comparable only within the same
+ * source document and CSS stacking context. The ONLY place this normalization
+ * lives — partitioning, membership checks, and pairwise equality all use it.
+ */
+const paintScopeKey = (el: { sourceFile?: string; stackingContextId?: string | null }): string =>
+  JSON.stringify([el.sourceFile ?? null, el.stackingContextId ?? null]);
+
+/** Canonical paint-scope equality for stacking sync and its inverse mirror. */
+export function samePaintScope(
+  a: { sourceFile?: string; stackingContextId?: string | null },
+  b: { sourceFile?: string; stackingContextId?: string | null },
+): boolean {
+  return paintScopeKey(a) === paintScopeKey(b);
+}
+
 /**
  * Two clips overlap in time when their half-open [start, end) intervals intersect.
  *
@@ -71,7 +96,10 @@ const EPS = 1e-6;
  * epsilon guards against float fuzz (e.g. 5.0000001 vs 5) spuriously overlapping two
  * abutting clips and shuffling lanes. The two are intended to differ, not align.
  */
-function overlapsInTime(a: StackingElement, b: StackingElement): boolean {
+function overlapsInTime(
+  a: Pick<StackingElement, "start" | "duration">,
+  b: Pick<StackingElement, "start" | "duration">,
+): boolean {
   return a.start < b.start + b.duration - EPS && b.start < a.start + a.duration - EPS;
 }
 
@@ -99,9 +127,13 @@ interface MutZ extends StackingElement {
  * Does `a` currently paint ON TOP of `b`? Higher z wins; equal z breaks by DOM
  * order (later in DOM paints on top). When either domIndex is absent, equal z is
  * treated as "not strictly above" (ambiguous) — callers should supply domIndex to
- * disambiguate (see StackingElement.domIndex). Operates on resolved (`MutZ`) clips.
+ * disambiguate (see StackingElement.domIndex). Exported (like laneIsAbove) as the
+ * ONE paint-order predicate so every consumer agrees on what "paints above" means.
  */
-function paintsAbove(a: MutZ, b: MutZ): boolean {
+function paintsAbove(
+  a: Pick<StackingElement, "zIndex" | "domIndex">,
+  b: Pick<StackingElement, "zIndex" | "domIndex">,
+): boolean {
   if (a.zIndex !== b.zIndex) return a.zIndex > b.zIndex;
   if (a.domIndex != null && b.domIndex != null) return a.domIndex > b.domIndex;
   return false;
@@ -284,7 +316,13 @@ 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 source document and stacking context:
+  // across either boundary the ancestor composition/context decides paint order.
+  // Restrict the computation to the edited clips' own paint scope(s).
+  const editedScopes = new Set(allResolved.filter((e) => editedSet.has(e.key)).map(paintScopeKey));
+  const resolved = allResolved.filter((e) => editedScopes.has(paintScopeKey(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 }]));
@@ -305,7 +343,9 @@ export function computeStackingPatches(
   // LIFTED neighbour without overlapping the edited clip itself (#2198).
   const all = [...byKey.values()];
   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 && samePaintScope(clip, o) && overlapsInTime(clip, o),
+    );
 
   for (const clip of edited) {
     resolveEditedZ(clip, overlappersOf(clip), overlappersOf, patchZ);

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);
+  });
+});