@hyperframes/studio 0.7.57 → 0.7.59

package/src/player/components/useTimelinePlayhead.ts

@@ -4,6 +4,7 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { getPinchTimelineZoomPercent } from "./timelineZoom";
 import {
   GUTTER,
+  TRACKS_LEFT_PAD,
   getTimelinePlayheadLeft,
   getTimelineScrollLeftForZoomTransition,
   getTimelineScrollLeftForZoomAnchor,
@@ -73,7 +74,7 @@ export function useTimelinePlayhead({
     const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
       pointerX: scroll.clientWidth / 2,
       currentScrollLeft: scroll.scrollLeft,
-      gutter: GUTTER,
+      gutter: GUTTER + TRACKS_LEFT_PAD,
       currentPixelsPerSecond: prevPps,
       nextPixelsPerSecond: pps,
       duration: durationRef.current,
@@ -129,7 +130,7 @@ export function useTimelinePlayhead({
       const el = scrollRef.current;
       if (!el || effectiveDuration <= 0) return;
       const rect = el.getBoundingClientRect();
-      const x = clientX - rect.left + el.scrollLeft - GUTTER;
+      const x = clientX - rect.left + el.scrollLeft - GUTTER - TRACKS_LEFT_PAD;
       if (x < 0) return;
       const time = Math.max(0, Math.min(effectiveDuration, x / pps));
       liveTime.notify(time);
@@ -185,7 +186,7 @@ export function useTimelinePlayhead({
       const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
         pointerX: e.clientX - rect.left,
         currentScrollLeft: scroll.scrollLeft,
-        gutter: GUTTER,
+        gutter: GUTTER + TRACKS_LEFT_PAD,
         currentPixelsPerSecond: ppsRef.current,
         nextPixelsPerSecond: nextPps,
         duration: durationRef.current,

package/src/player/components/useTimelineRangeSelection.ts

@@ -7,7 +7,7 @@ import {
 } from "./timelineEditing";
 import type { TimelineElement } from "../store/playerStore";
 import { liveTime, usePlayerStore } from "../store/playerStore";
-import { GUTTER } from "./timelineLayout";
+import { GUTTER, TRACKS_LEFT_PAD } from "./timelineLayout";
 import {
   computeMarqueeSelection,
   getMarqueeRect,
@@ -228,7 +228,8 @@ export function useTimelineRangeSelection({
       setShowPopover(false);
       const rect = scrollRef.current?.getBoundingClientRect();
       if (rect) {
-        const x = e.clientX - rect.left + (scrollRef.current?.scrollLeft ?? 0) - GUTTER;
+        const x =
+          e.clientX - rect.left + (scrollRef.current?.scrollLeft ?? 0) - GUTTER - TRACKS_LEFT_PAD;
         const time = Math.max(0, x / pps);
         rangeAnchorTime.current = time;
         setRangeSelection({ start: time, end: time, anchorX: e.clientX, anchorY: e.clientY });
@@ -285,7 +286,7 @@ export function useTimelineRangeSelection({
       const el = scrollRef.current;
       if (el) {
         const rect = el.getBoundingClientRect();
-        const x = clientX - rect.left + el.scrollLeft - GUTTER;
+        const x = clientX - rect.left + el.scrollLeft - GUTTER - TRACKS_LEFT_PAD;
         if (x >= 0) {
           const dur = el.scrollWidth / pps;
           liveTime.notify(Math.max(0, Math.min(dur, x / pps)));
@@ -309,7 +310,8 @@ export function useTimelineRangeSelection({
       if (isRangeSelecting.current) {
         const rect = scrollRef.current?.getBoundingClientRect();
         if (rect) {
-          const x = e.clientX - rect.left + (scrollRef.current?.scrollLeft ?? 0) - GUTTER;
+          const x =
+            e.clientX - rect.left + (scrollRef.current?.scrollLeft ?? 0) - GUTTER - TRACKS_LEFT_PAD;
           setRangeSelection((prev) =>
             prev
               ? { ...prev, end: Math.max(0, x / pps), anchorX: e.clientX, anchorY: e.clientY }

package/src/player/components/useTimelineScrollViewport.ts

@@ -0,0 +1,73 @@
+import { useCallback, useEffect, useRef, useState, type RefObject } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
+import { shouldShowTimelineShortcutHint } from "./timelineLayout";
+
+/**
+ * The timeline scroll container's viewport plumbing — extracted verbatim from
+ * Timeline.tsx (600-line studio cap): the ResizeObserver-backed viewport width,
+ * the rAF-throttled shortcut-hint visibility sync, and the callback ref that
+ * wires both to the scroll element. `resyncShortcutHintOn` re-checks the hint
+ * whenever any of its values change (timeline readiness / element count /
+ * canvas height), matching the original effect.
+ */
+export function useTimelineScrollViewport(
+  scrollRef: RefObject<HTMLDivElement | null>,
+  resyncShortcutHintOn: ReadonlyArray<unknown>,
+): {
+  viewportWidth: number;
+  showShortcutHint: boolean;
+  setScrollRef: (el: HTMLDivElement | null) => void;
+} {
+  const [viewportWidth, setViewportWidth] = useState(0);
+  const [showShortcutHint, setShowShortcutHint] = useState(true);
+  const roRef = useRef<ResizeObserver | null>(null);
+  const shortcutHintRafRef = useRef(0);
+
+  const syncShortcutHintVisibility = useCallback(() => {
+    const scroll = scrollRef.current;
+    setShowShortcutHint(
+      scroll ? shouldShowTimelineShortcutHint(scroll.scrollHeight, scroll.clientHeight) : true,
+    );
+  }, [scrollRef]);
+
+  const scheduleShortcutHintVisibilitySync = useCallback(() => {
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
+    shortcutHintRafRef.current = requestAnimationFrame(() => {
+      shortcutHintRafRef.current = 0;
+      syncShortcutHintVisibility();
+    });
+  }, [syncShortcutHintVisibility]);
+
+  const setScrollRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      if (roRef.current) {
+        roRef.current.disconnect();
+        roRef.current = null;
+      }
+      scrollRef.current = el;
+      if (!el) return;
+
+      const syncScrollViewport = () => {
+        setViewportWidth(el.clientWidth);
+        scheduleShortcutHintVisibilitySync();
+      };
+
+      syncScrollViewport();
+      roRef.current = new ResizeObserver(syncScrollViewport);
+      roRef.current.observe(el);
+    },
+    [scrollRef, scheduleShortcutHintVisibilitySync],
+  );
+
+  useMountEffect(() => () => {
+    roRef.current?.disconnect();
+    if (shortcutHintRafRef.current) cancelAnimationFrame(shortcutHintRafRef.current);
+  });
+
+  useEffect(() => {
+    syncShortcutHintVisibility();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [syncShortcutHintVisibility, ...resyncShortcutHintOn]);
+
+  return { viewportWidth, showShortcutHint, setScrollRef };
+}

package/src/player/components/useTimelineStackingSync.test.tsx

@@ -40,7 +40,6 @@ describe("useTimelineStackingSync", () => {
       start: 0,
       duration: 2,
       track: 0,
-      sourceFile: "nested.html",
     };
     let apply: ((patches: Array<{ key: string; zIndex: number }>, key?: string) => unknown) | null =
       null;

package/src/player/components/useTimelineStackingSync.ts

@@ -37,7 +37,7 @@ export function useTimelineStackingSync({ expandedElementsRef }: UseTimelineStac
           id: el.domId ?? el.id,
           selector: el.selector,
           selectorIndex: el.selectorIndex,
-          sourceFile: el.sourceFile,
+          sourceFile: el.sourceFile ?? zSyncActiveCompPath ?? "index.html",
         },
         zSyncActiveCompPath,
       );
@@ -61,7 +61,7 @@ export function useTimelineStackingSync({ expandedElementsRef }: UseTimelineStac
 
   const applyStackingPatches = useCallback(
     (patches: StackingPatch[], coalesceKey?: string) => {
-      if (!handleDomZIndexReorderCommit) return;
+      if (!handleDomZIndexReorderCommit) return Promise.resolve();
       const entries = patches.flatMap((p) => {
         const el = expandedElementsRef.current.find((e) => (e.key ?? e.id) === p.key);
         const node = el && resolveIframeElement(el);
@@ -82,7 +82,9 @@ export function useTimelineStackingSync({ expandedElementsRef }: UseTimelineStac
       });
       // Forward the drag-commit's shared coalesce key so the z-reorder history
       // entry merges with the lane change's move entry into one undo step.
-      if (entries.length) handleDomZIndexReorderCommit(entries, coalesceKey);
+      return entries.length
+        ? handleDomZIndexReorderCommit(entries, coalesceKey).then(() => undefined)
+        : Promise.resolve();
     },
     [handleDomZIndexReorderCommit, resolveIframeElement, zSyncActiveCompPath, expandedElementsRef],
   );

package/src/player/components/useTimelineTrackDerivations.ts

@@ -0,0 +1,38 @@
+import { useMemo } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import { getTrackStyle, type TrackVisualStyle } from "./timelineIcons";
+
+/**
+ * Per-render track derivations Timeline.tsx feeds the canvas/lanes: the lane →
+ * clip grouping (`tracks`, ascending), per-lane visual styles, the ascending
+ * `trackOrder`, and the z-override badge set. Extracted from Timeline.tsx as a
+ * cohesive unit (600-line studio cap); each memo keys on the expanded display
+ * element set exactly as before.
+ */
+export function useTimelineTrackDerivations(expandedElements: TimelineElement[]): {
+  tracks: [number, TimelineElement[]][];
+  trackStyles: Map<number, TrackVisualStyle>;
+  trackOrder: number[];
+} {
+  const tracks = useMemo(() => {
+    const map = new Map<number, TimelineElement[]>();
+    for (const el of expandedElements) {
+      const list = map.get(el.track) ?? [];
+      list.push(el);
+      map.set(el.track, list);
+    }
+    return Array.from(map.entries()).sort(([a], [b]) => a - b);
+  }, [expandedElements]);
+
+  const trackStyles = useMemo(() => {
+    const map = new Map<number, TrackVisualStyle>();
+    for (const [trackNum, els] of tracks) {
+      map.set(trackNum, getTrackStyle(els[0]?.tag ?? ""));
+    }
+    return map;
+  }, [tracks]);
+
+  const trackOrder = useMemo(() => tracks.map(([trackNum]) => trackNum), [tracks]);
+
+  return { tracks, trackStyles, trackOrder };
+}

package/src/player/components/useTrackGapMenu.ts

@@ -0,0 +1,155 @@
+import { useCallback, useMemo, useState, type MutableRefObject } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { DragCommitDeps } from "./timelineClipDragCommit";
+import {
+  laneGapFloor,
+  resolveAllGapIntervals,
+  resolveAllTrackGaps,
+  resolveCloseGapShifts,
+  resolveTrackGapAt,
+  type TrackGapInterval,
+} from "./timelineGaps";
+import {
+  canShiftTrackGapClips,
+  commitCloseAllTrackGaps,
+  commitCloseTrackGap,
+} from "./timelineGapCommit";
+
+/** Right-click anchor on EMPTY lane space: pointer position + clicked lane/time. */
+interface TrackGapMenuAnchor {
+  x: number;
+  y: number;
+  track: number;
+  time: number;
+}
+
+/** Gap strips to paint on one lane while a menu row is hovered. */
+export interface TrackGapHighlight {
+  track: number;
+  intervals: TrackGapInterval[];
+}
+
+/**
+ * Track-gap context menu (right-click on empty lane space) — state, the
+ * derived menu model, and the two commit actions. Extracted from Timeline.tsx
+ * as a cohesive unit (600-line studio cap); behavior identical.
+ *
+ * Only the ANCHOR (and the hovered row) is state; the menu model (gap under
+ * the pointer, compaction, movability) derives from live `tracks` so an open
+ * menu reflects concurrent edits. `gapHighlight` — the strips TimelineCanvas
+ * paints while "Close gap" / "Close all gaps" is hovered — derives the same
+ * way. Commits are ONE atomic batch each via the existing move-persist
+ * pipeline (see timelineGapCommit.ts).
+ */
+export function useTrackGapMenu({
+  tracks,
+  expandedElementsRef,
+  trackOrderRef,
+  onMoveElement,
+  onMoveElements,
+}: {
+  tracks: [number, TimelineElement[]][];
+  expandedElementsRef: MutableRefObject<TimelineElement[]>;
+  trackOrderRef: MutableRefObject<number[]>;
+  onMoveElement: DragCommitDeps["onMoveElement"];
+  onMoveElements: DragCommitDeps["onMoveElements"];
+}) {
+  const updateElement = usePlayerStore((s) => s.updateElement);
+  const [gapContextMenu, setGapContextMenu] = useState<TrackGapMenuAnchor | null>(null);
+  const [hoveredGapAction, setHoveredGapAction] = useState<"close-gap" | "close-all" | null>(null);
+
+  const gapMenuLaneElements = useMemo(
+    () => (gapContextMenu ? (tracks.find(([t]) => t === gapContextMenu.track)?.[1] ?? []) : null),
+    [gapContextMenu, tracks],
+  );
+  const gapMenuModel = useMemo(() => {
+    if (!gapContextMenu || !gapMenuLaneElements) return null;
+    const floor = laneGapFloor(gapMenuLaneElements);
+    const gap = resolveTrackGapAt(gapMenuLaneElements, gapContextMenu.time, undefined, floor);
+    const allShifts = resolveAllTrackGaps(gapMenuLaneElements, undefined, floor);
+    return {
+      x: gapContextMenu.x,
+      y: gapContextMenu.y,
+      gapWidth: gap ? gap.gapEnd - gap.gapStart : null,
+      canCloseGap:
+        gap != null &&
+        canShiftTrackGapClips(gapMenuLaneElements, resolveCloseGapShifts(gapMenuLaneElements, gap)),
+      hasAnyGaps: allShifts.length > 0,
+      canCloseAllGaps:
+        allShifts.length > 0 && canShiftTrackGapClips(gapMenuLaneElements, allShifts),
+    };
+  }, [gapContextMenu, gapMenuLaneElements]);
+
+  // The strips to paint while a menu row is hovered: the one gap under the
+  // pointer for "Close gap", every current gap (leading included) for
+  // "Close all gaps". Null when nothing is hovered / nothing would close.
+  const gapHighlight = useMemo<TrackGapHighlight | null>(() => {
+    if (!gapContextMenu || !gapMenuLaneElements || !hoveredGapAction) return null;
+    const floor = laneGapFloor(gapMenuLaneElements);
+    if (hoveredGapAction === "close-gap") {
+      const gap = resolveTrackGapAt(gapMenuLaneElements, gapContextMenu.time, undefined, floor);
+      if (!gap) return null;
+      return {
+        track: gapContextMenu.track,
+        intervals: [{ start: gap.gapStart, end: gap.gapEnd }],
+      };
+    }
+    const intervals = resolveAllGapIntervals(gapMenuLaneElements, undefined, floor);
+    return intervals.length > 0 ? { track: gapContextMenu.track, intervals } : null;
+  }, [gapContextMenu, gapMenuLaneElements, hoveredGapAction]);
+
+  const closeTrackGap = useCallback(() => {
+    if (!gapContextMenu || !gapMenuLaneElements) return;
+    commitCloseTrackGap(gapMenuLaneElements, gapContextMenu.time, {
+      elements: expandedElementsRef.current,
+      trackOrder: trackOrderRef.current,
+      updateElement,
+      onMoveElement,
+      onMoveElements,
+    });
+  }, [
+    gapContextMenu,
+    gapMenuLaneElements,
+    expandedElementsRef,
+    trackOrderRef,
+    updateElement,
+    onMoveElement,
+    onMoveElements,
+  ]);
+  const closeAllTrackGaps = useCallback(() => {
+    if (!gapMenuLaneElements) return;
+    commitCloseAllTrackGaps(gapMenuLaneElements, {
+      elements: expandedElementsRef.current,
+      trackOrder: trackOrderRef.current,
+      updateElement,
+      onMoveElement,
+      onMoveElements,
+    });
+  }, [
+    gapMenuLaneElements,
+    expandedElementsRef,
+    trackOrderRef,
+    updateElement,
+    onMoveElement,
+    onMoveElements,
+  ]);
+
+  const openGapMenu = useCallback((anchor: TrackGapMenuAnchor) => {
+    setHoveredGapAction(null);
+    setGapContextMenu(anchor);
+  }, []);
+  const dismissGapMenu = useCallback(() => {
+    setHoveredGapAction(null);
+    setGapContextMenu(null);
+  }, []);
+
+  return {
+    gapMenuModel,
+    gapHighlight,
+    setHoveredGapAction,
+    openGapMenu,
+    dismissGapMenu,
+    closeTrackGap,
+    closeAllTrackGaps,
+  };
+}

package/src/player/hooks/useExpandedTimelineElements.test.ts

@@ -152,10 +152,34 @@ describe("buildExpandedElements", () => {
       ["pill-3", "group-1"],
     ]);
     const domClipChildren = [
-      { id: "group-1", parentId: "scene-host", hostId: "scene-host", label: "Group 1" },
-      { id: "pill-1", parentId: "group-1", hostId: "scene-host", label: "pill-1" },
-      { id: "pill-2", parentId: "group-1", hostId: "scene-host", label: "pill-2" },
-      { id: "pill-3", parentId: "group-1", hostId: "scene-host", label: "pill-3" },
+      {
+        id: "group-1",
+        parentId: "scene-host",
+        hostId: "scene-host",
+        label: "Group 1",
+        stackingContextId: "css:0",
+      },
+      {
+        id: "pill-1",
+        parentId: "group-1",
+        hostId: "scene-host",
+        label: "pill-1",
+        stackingContextId: "css:0.0",
+      },
+      {
+        id: "pill-2",
+        parentId: "group-1",
+        hostId: "scene-host",
+        label: "pill-2",
+        stackingContextId: "css:0.1",
+      },
+      {
+        id: "pill-3",
+        parentId: "group-1",
+        hostId: "scene-host",
+        label: "pill-3",
+        stackingContextId: "css:0.1",
+      },
     ];
 
     // Expanding pill-3's siblings: topLevel scene-host, immediate parent group-1.
@@ -173,6 +197,7 @@ describe("buildExpandedElements", () => {
     expect(pills[0]!.start).toBe(5);
     expect(pills[0]!.duration).toBe(6);
     expect(pills[0]!.sourceFile).toBe("scene.html");
+    expect(pills.map((pill) => pill.stackingContextId)).toEqual(["css:0.0", "css:0.1", "css:0.1"]);
     // The host row is replaced by its children.
     expect(out.some((e) => e.domId === "scene-host")).toBe(false);
   });
@@ -273,3 +298,41 @@ describe("resolveTimelineExpansionRawId", () => {
     ).toBe("caption");
   });
 });
+
+describe("buildExpandedElements — collision-free synthetic rows (cross-file lane safety)", () => {
+  it("expanded children NEVER share a display track with an unrelated top-level clip", () => {
+    // The Deepwork regression: host on track 0 with two children used to put
+    // child #2 on integer track 1 — the same lane as index.html#foreign. Lane
+    // grouping merges purely by track number, so a gap-close on that "one"
+    // lane batch-persisted a foreign file's clip.
+    const elements = [
+      el({ id: "host", start: 0, duration: 20, track: 0, compositionSrc: "scene.html" }),
+      el({ id: "foreign", start: 20, duration: 5, track: 1 }),
+    ];
+    const manifest = [
+      clip({ id: "host", start: 0, duration: 20, compositionSrc: "scene.html" }),
+      clip({ id: "c1", start: 0, duration: 5 }),
+      clip({ id: "c2", start: 10, duration: 5 }),
+    ];
+    const parentMap = new Map([
+      ["c1", "host"],
+      ["c2", "host"],
+    ]);
+
+    const out = buildExpandedElements(elements, manifest, parentMap, "host", "host");
+    const foreign = out.find((e) => e.id === "foreign")!;
+    const children = out.filter((e) => e.domId === "c1" || e.domId === "c2");
+    expect(children).toHaveLength(2);
+    for (const child of children) {
+      // No lane sharing with the foreign clip…
+      expect(child.track).not.toBe(foreign.track);
+      // …and structurally impossible to collide with ANY normalized (integer)
+      // lane: synthetic rows are strict fractions under the host's lane.
+      expect(Number.isInteger(child.track)).toBe(false);
+      expect(child.track).toBeGreaterThan(0);
+      expect(child.track).toBeLessThan(1);
+    }
+    // Distinct ordered rows per child.
+    expect(children[0].track).not.toBe(children[1].track);
+  });
+});

package/src/player/hooks/useExpandedTimelineElements.ts

@@ -168,7 +168,17 @@ function buildChildElements(
       // file's coordinate space) and the runtime-computed `stackingContextId`
       // must survive verbatim — lane persists and z-sync read them, they are
       // never reconstructed from display lanes.
-      track: display.track + result.length,
+      //
+      // COLLISION-FREE synthetic rows: the old `display.track + index` scheme
+      // could equal a REAL clip's integer lane (host on track 0 with two
+      // children puts child #2 on track 1 — where an unrelated top-level clip
+      // may live). Lane grouping merges purely by track number, so that
+      // collision fused clips from DIFFERENT source files into one display
+      // lane, and lane-scoped actions (gap close) then batch-persisted foreign
+      // clips. Fractions strictly between the host's lane and the next integer
+      // can never equal a normalized (integer) lane, while still rendering the
+      // children as their own ordered rows directly under the host.
+      track: display.track + (result.length + 1) / (siblings.length + 2),
       authoredTrack: base.authoredTrack,
       stackingContextId: base.stackingContextId,
       expandedParentStart: editBasis.start,
@@ -205,6 +215,7 @@ function domSiblingClips(
         parentCompositionId: host.id ?? null,
         compositionSrc: host.compositionSrc ?? null,
         assetUrl: null,
+        stackingContextId: c.stackingContextId,
       }),
     );
 }

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -11,6 +11,7 @@
 import { useCallback } from "react";
 import { liveTime, usePlayerStore } from "../store/playerStore";
 import type { TimelineElement, DomClipChild } from "../store/playerStore";
+import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import type { PlaybackAdapter, ClipManifestClip, IframeWindow } from "../lib/playbackTypes";
 import {
   parseTimelineFromDOM,
@@ -199,6 +200,7 @@ export function useTimelineSyncCallbacks({
                   parentId,
                   hostId,
                   label: isGroup ? child.getAttribute("data-hf-group") || child.id : child.id,
+                  stackingContextId: resolveCssStackingContextId(child),
                 });
                 parentMap.set(child.id, parentId);
                 if (isGroup) collect(child, child.id);

package/src/player/lib/layerOrdering.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 
 import { describe, expect, it } from "vitest";
-import { computeReorderZValues, getElementZIndex, resolveContextOrder } from "./layerOrdering";
+import { getElementZIndex, resolveContextOrder } from "./layerOrdering";
 
 function makeElement(zIndex?: string): HTMLElement {
   const element = document.createElement("div");
@@ -31,20 +31,6 @@ describe("getElementZIndex", () => {
   });
 });
 
-describe("computeReorderZValues", () => {
-  it("preserves distinct existing z-index values and remaps them onto the new order", () => {
-    expect(computeReorderZValues([1, 8, 3], 0, 2)).toEqual([8, 3, 1]);
-  });
-
-  it("renumbers an all-tied group to descending contiguous z-index values", () => {
-    expect(computeReorderZValues([0, 0, 0], 2, 0)).toEqual([3, 2, 1]);
-  });
-
-  it("renumbers the whole group when any existing z-index values are tied", () => {
-    expect(computeReorderZValues([5, 5, 1], 2, 0)).toEqual([3, 2, 1]);
-  });
-});
-
 describe("resolveContextOrder", () => {
   it("sorts a flat sibling group by z-index descending then original order", () => {
     const ordered = resolveContextOrder([

package/src/player/lib/layerOrdering.ts

@@ -1,3 +1,5 @@
+import { readLayerRevealPriorZ } from "./timelineElementHelpers";
+
 export interface StackingContextDescriptor {
   parentCompositionId: string | null;
   compositionAncestors: readonly string[];
@@ -11,6 +13,9 @@ export interface ContextOrderItem extends StackingContextDescriptor {
 // fallow-ignore-next-line complexity
 export function getElementZIndex(element: HTMLElement): number {
   try {
+    // An active Layers-panel reveal lift reports the element's TRUE z.
+    const prior = readLayerRevealPriorZ(element);
+    if (prior != null) return prior;
     const inline = element.style?.zIndex;
     if (inline && inline !== "auto") {
       const parsed = parseInt(inline, 10);
@@ -27,34 +32,6 @@ export function getElementZIndex(element: HTMLElement): number {
   }
 }
 
-// fallow-ignore-next-line complexity
-export function hasExplicitZIndex(element: HTMLElement): boolean {
-  try {
-    const inline = element.style?.zIndex;
-    if (inline) return inline !== "auto";
-    const win = element.ownerDocument?.defaultView;
-    if (!win) return false;
-    const value = win.getComputedStyle(element).zIndex;
-    return value !== "auto" && value !== "";
-  } catch {
-    return false;
-  }
-}
-
-export function computeReorderZValues(
-  existingValues: readonly number[],
-  fromIndex: number,
-  toIndex: number,
-): number[] {
-  const reordered = [...existingValues];
-  const [moved] = reordered.splice(fromIndex, 1);
-  reordered.splice(toIndex, 0, moved);
-
-  const sorted = [...existingValues].sort((a, b) => b - a);
-  const hasDupes = sorted.some((v, i) => i > 0 && v === sorted[i - 1]);
-  return hasDupes ? reordered.map((_, i) => reordered.length - i) : sorted;
-}
-
 export function resolveStackingContextKey(item: StackingContextDescriptor): string {
   return item.stackingContextId ?? item.parentCompositionId ?? item.compositionAncestors[0] ?? "";
 }

package/src/player/lib/timelineDOM.test.ts

@@ -110,7 +110,79 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
   });
 });
 
+describe("createTimelineElementFromManifestClip — source-scoped selector identity", () => {
+  it("ignores an index.html duplicate when indexing a scene.html selector", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root" data-composition-file="index.html">
+        <div class="sub"></div>
+        <div data-composition-id="scene" data-composition-file="scene.html">
+          <div class="sub"></div>
+          <div class="sub" data-target></div>
+        </div>
+      </div>
+    `);
+    const target = doc.querySelector("[data-target]");
+    if (!target) throw new Error("missing target");
+
+    const element = createTimelineElementFromManifestClip({
+      clip: {
+        id: null,
+        label: "Sub",
+        kind: "element",
+        tagName: "div",
+        start: 0,
+        duration: 5,
+        track: 0,
+        compositionId: null,
+        parentCompositionId: null,
+        compositionSrc: null,
+        assetUrl: null,
+      },
+      fallbackIndex: 0,
+      doc,
+      hostEl: target,
+    });
+
+    expect(element.sourceFile).toBe("scene.html");
+    expect(element.selectorIndex).toBe(1);
+    expect(element.key).toBe("scene.html:.sub:1");
+  });
+});
+
 describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
+  it("uses the runtime root paint scope for implicit siblings of manifest clips", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div id="timed" data-start="0" data-duration="5"></div>
+        <div id="implicit"></div>
+      </div>
+    `);
+    const timedHost = doc.getElementById("timed");
+    const timed = createTimelineElementFromManifestClip({
+      clip: {
+        id: "timed",
+        label: "Timed",
+        start: 0,
+        duration: 5,
+        track: 0,
+        stackingContextId: "css:root",
+        kind: "element",
+        tagName: "div",
+        compositionId: null,
+        parentCompositionId: null,
+        compositionSrc: null,
+        assetUrl: null,
+      },
+      fallbackIndex: 0,
+      doc,
+      hostEl: timedHost,
+    });
+    const implicit = createImplicitTimelineLayersFromDOM(doc, 5, [timed])[0];
+
+    expect(implicit?.stackingContextId).toBe("css:root");
+    expect(implicit?.stackingContextId).toBe(timed.stackingContextId);
+  });
+
   it("harvests hfId from an implicit layer child that has data-hf-id", () => {
     const doc = makeDoc(`
       <div data-composition-id="root">