@hyperframes/studio 0.7.45 → 0.7.47

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

@@ -0,0 +1,231 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
+import { GUTTER, RULER_H, TRACK_H } from "./timelineLayout";
+import type { StackingTimelineLayer } from "./timelineTrackOrder";
+import { useTimelineMarqueeSelection } from "./useTimelineMarqueeSelection";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function element(id: string, start: number, duration: number, track: number): TimelineElement {
+  return { id, tag: "div", start, duration, track };
+}
+
+function layer(id: string, elements: TimelineElement[]): StackingTimelineLayer {
+  return {
+    id,
+    kind: "visual",
+    contextKey: "",
+    zIndex: 0,
+    placementTrack: elements[0]?.track ?? 0,
+    elements,
+  };
+}
+
+function pointerEvent(type: string, init: MouseEventInit & { pointerId?: number }) {
+  const event = new MouseEvent(type, { bubbles: true, cancelable: true, ...init });
+  Object.defineProperty(event, "pointerId", { value: init.pointerId ?? 1 });
+  return event;
+}
+
+function dispatchPointer(
+  target: HTMLElement,
+  type: "pointerdown" | "pointermove" | "pointerup",
+  point: { x: number; y: number },
+) {
+  target.dispatchEvent(pointerEvent(type, { button: 0, clientX: point.x, clientY: point.y }));
+}
+
+function dragMarquee(
+  harness: ReturnType<typeof renderMarqueeHarness>,
+  start: { x: number; y: number },
+  end: { x: number; y: number },
+  downTarget: HTMLElement = harness.scroll,
+) {
+  dispatchPointer(downTarget, "pointerdown", start);
+  dispatchPointer(harness.scroll, "pointermove", end);
+  dispatchPointer(harness.scroll, "pointerup", end);
+}
+
+function renderMarqueeHarness(layers: StackingTimelineLayer[]) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const layerOrder = layers.map((item) => item.id);
+  const setShowPopover = () => {};
+  const setRangeSelection = () => {};
+  const seekedX: number[] = [];
+
+  function Harness() {
+    const scrollRef = React.useRef<HTMLDivElement | null>(null);
+    const hook = useTimelineMarqueeSelection({
+      scrollRef,
+      ppsRef: { current: 100 },
+      trackOrderRef: { current: layerOrder },
+      timelineLayersRef: { current: layers },
+      setShowPopover,
+      setRangeSelectionRef: { current: setRangeSelection },
+      seekFromX: (clientX: number) => seekedX.push(clientX),
+    });
+    return (
+      <div
+        ref={scrollRef}
+        data-scroll="true"
+        onPointerDown={(event) => {
+          hook.handlePointerDown(event);
+        }}
+        onPointerMove={(event) => {
+          hook.handlePointerMove(event);
+        }}
+        onPointerUp={(event) => {
+          hook.handlePointerUp(event);
+        }}
+      >
+        <button data-clip="true">clip</button>
+        {hook.marqueeRect && <span data-marquee="true" />}
+      </div>
+    );
+  }
+
+  const root = createRoot(host);
+  act(() => {
+    root.render(<Harness />);
+  });
+  const scroll = host.querySelector<HTMLElement>("[data-scroll]");
+  if (!scroll) throw new Error("Expected scroll host");
+  Object.defineProperty(scroll, "clientWidth", { configurable: true, value: 160 });
+  Object.defineProperty(scroll, "clientHeight", { configurable: true, value: 160 });
+  Object.defineProperty(scroll, "scrollWidth", { configurable: true, value: 600 });
+  Object.defineProperty(scroll, "scrollHeight", { configurable: true, value: 260 });
+  scroll.getBoundingClientRect = () =>
+    ({
+      left: 0,
+      top: 0,
+      right: 160,
+      bottom: 160,
+      width: 160,
+      height: 160,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    }) as DOMRect;
+
+  return {
+    host,
+    scroll,
+    root,
+    seekedX,
+    clip: host.querySelector<HTMLElement>("[data-clip]")!,
+    unmount() {
+      act(() => root.unmount());
+    },
+  };
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+});
+
+describe("useTimelineMarqueeSelection", () => {
+  it("selects clips intersecting an empty-lane drag rectangle", () => {
+    const layers = [
+      layer("lane-0", [element("first", 0.5, 0.5, 0)]),
+      layer("lane-1", [element("second", 2, 0.5, 1)]),
+      layer("lane-2", [element("third", 0.5, 0.5, 2)]),
+    ];
+    const harness = renderMarqueeHarness(layers);
+    const start = { x: GUTTER + 10, y: RULER_H + 4 };
+    const end = { x: GUTTER + 260, y: RULER_H + TRACK_H * 2 - 2 };
+
+    act(() => {
+      dispatchPointer(harness.scroll, "pointerdown", start);
+      dispatchPointer(harness.scroll, "pointermove", end);
+    });
+    expect(harness.host.querySelector("[data-marquee]")).not.toBeNull();
+
+    act(() => {
+      dispatchPointer(harness.scroll, "pointerup", end);
+    });
+
+    expect([...usePlayerStore.getState().selectedElementIds]).toEqual(["first", "second"]);
+    harness.unmount();
+  });
+
+  it("treats a sub-threshold empty-lane drag as a clear click that also seeks", () => {
+    usePlayerStore.getState().setSelection(["selected"]);
+    const harness = renderMarqueeHarness([layer("lane-0", [element("selected", 0, 1, 0)])]);
+
+    act(() => {
+      dragMarquee(harness, { x: GUTTER + 20, y: RULER_H + 4 }, { x: GUTTER + 21, y: RULER_H + 5 });
+    });
+
+    expect(usePlayerStore.getState().selectedElementIds.size).toBe(0);
+    expect(harness.host.querySelector("[data-marquee]")).toBeNull();
+    // A sub-threshold press still scrubs the playhead to the click, like a plain lane click.
+    expect(harness.seekedX).toEqual([GUTTER + 20]);
+    harness.unmount();
+  });
+
+  it("does not start from clips or the ruler", () => {
+    usePlayerStore.getState().setSelection(["kept"]);
+    const harness = renderMarqueeHarness([layer("lane-0", [element("kept", 0, 1, 0)])]);
+
+    act(() => {
+      dragMarquee(
+        harness,
+        { x: GUTTER + 20, y: RULER_H + 4 },
+        { x: GUTTER + 80, y: RULER_H + 40 },
+        harness.clip,
+      );
+      dragMarquee(harness, { x: GUTTER + 20, y: RULER_H - 2 }, { x: GUTTER + 80, y: RULER_H + 40 });
+    });
+
+    expect([...usePlayerStore.getState().selectedElementIds]).toEqual(["kept"]);
+    expect(harness.host.querySelector("[data-marquee]")).toBeNull();
+    harness.unmount();
+  });
+
+  it("clears selection when the released marquee hits no clips", () => {
+    usePlayerStore.getState().setSelection(["selected"]);
+    const harness = renderMarqueeHarness([layer("lane-0", [element("selected", 4, 1, 0)])]);
+
+    act(() => {
+      dragMarquee(harness, { x: GUTTER + 10, y: RULER_H + 4 }, { x: GUTTER + 80, y: RULER_H + 40 });
+    });
+
+    expect(usePlayerStore.getState().selectedElementIds.size).toBe(0);
+    harness.unmount();
+  });
+
+  it("uses autoscroll position when resolving the released marquee", () => {
+    const originalRaf = window.requestAnimationFrame;
+    const originalCancel = window.cancelAnimationFrame;
+    const callbacks: FrameRequestCallback[] = [];
+    window.requestAnimationFrame = ((callback: FrameRequestCallback) => {
+      callbacks.push(callback);
+      return callbacks.length;
+    }) as typeof window.requestAnimationFrame;
+    window.cancelAnimationFrame = (() => {}) as typeof window.cancelAnimationFrame;
+    const harness = renderMarqueeHarness([layer("lane-0", [element("reachable", 1.28, 0.2, 0)])]);
+
+    try {
+      act(() => {
+        dispatchPointer(harness.scroll, "pointerdown", { x: GUTTER + 10, y: RULER_H + 4 });
+        dispatchPointer(harness.scroll, "pointermove", { x: 155, y: RULER_H + 40 });
+        callbacks.shift()?.(0);
+        dispatchPointer(harness.scroll, "pointerup", { x: 155, y: RULER_H + 40 });
+      });
+
+      expect(harness.scroll.scrollLeft).toBeGreaterThan(0);
+      expect([...usePlayerStore.getState().selectedElementIds]).toEqual(["reachable"]);
+      harness.unmount();
+    } finally {
+      window.requestAnimationFrame = originalRaf;
+      window.cancelAnimationFrame = originalCancel;
+    }
+  });
+});

package/src/player/components/useTimelineMarqueeSelection.ts

@@ -0,0 +1,276 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type PointerEvent as ReactPointerEvent,
+  type RefObject,
+} from "react";
+import { usePlayerStore } from "../store/playerStore";
+import {
+  resolveTimelineAutoScroll,
+  selectTimelineElementsInMarquee,
+  type TimelineMarqueeSelectionRect,
+} from "./timelineEditing";
+import { GUTTER, RULER_H, TRACK_H } from "./timelineLayout";
+import { TIMELINE_LAYER_GROUP_HEADER_H } from "./TimelineLayerGroupHeader";
+import type { StackingTimelineLayer, TimelineLayerId } from "./timelineTrackOrder";
+
+const MARQUEE_THRESHOLD_PX = 4;
+
+export interface TimelineMarqueeOverlayRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+interface ActiveMarqueeGesture {
+  pointerId: number;
+  anchorClientX: number;
+  anchorClientY: number;
+  anchorX: number;
+  anchorY: number;
+  lastClientX: number;
+  lastClientY: number;
+  started: boolean;
+}
+
+interface UseTimelineMarqueeSelectionInput {
+  scrollRef: RefObject<HTMLDivElement | null>;
+  ppsRef: RefObject<number>;
+  trackOrderRef: RefObject<TimelineLayerId[]>;
+  timelineLayersRef: RefObject<StackingTimelineLayer[]>;
+  disabled?: boolean;
+  setShowPopover: (show: boolean) => void;
+  setRangeSelectionRef: RefObject<((sel: null) => void) | null>;
+  /** Canonical playhead seek, used to keep empty-lane clicks scrubbing the playhead. */
+  seekFromX: (clientX: number) => void;
+}
+
+function getCanvasPoint(scroll: HTMLDivElement, clientX: number, clientY: number) {
+  const rect = scroll.getBoundingClientRect();
+  return {
+    x: clientX - rect.left + scroll.scrollLeft,
+    y: clientY - rect.top + scroll.scrollTop,
+  };
+}
+
+function getMarqueeStartPoint(
+  event: ReactPointerEvent<HTMLDivElement>,
+  scroll: HTMLDivElement | null,
+  disabled: boolean,
+) {
+  if (disabled || event.button !== 0 || event.shiftKey || !scroll) return null;
+  const target = event.target as HTMLElement;
+  if (target.closest("[data-clip]")) return null;
+  const point = getCanvasPoint(scroll, event.clientX, event.clientY);
+  if (point.x < GUTTER || point.y < RULER_H) return null;
+  return point;
+}
+
+function capturePointerIfAvailable(event: ReactPointerEvent<HTMLDivElement>) {
+  const currentTarget = event.currentTarget as HTMLElement;
+  if (typeof currentTarget.setPointerCapture === "function") {
+    currentTarget.setPointerCapture(event.pointerId);
+  }
+}
+
+function buildSelectionRect(
+  active: ActiveMarqueeGesture,
+  scroll: HTMLDivElement,
+  pps: number,
+): { overlay: TimelineMarqueeOverlayRect; selection: TimelineMarqueeSelectionRect } {
+  const current = getCanvasPoint(scroll, active.lastClientX, active.lastClientY);
+  const left = Math.min(active.anchorX, current.x);
+  const right = Math.max(active.anchorX, current.x);
+  const top = Math.min(active.anchorY, current.y);
+  const bottom = Math.max(active.anchorY, current.y);
+  const overlayLeft = Math.max(GUTTER, left);
+  const overlayTop = Math.max(RULER_H, top);
+  const overlayRight = Math.max(overlayLeft, right);
+  const overlayBottom = Math.max(overlayTop, bottom);
+
+  // Hit-test must use the SAME pixels-per-second the overlay is drawn at, or the
+  // selected time span diverges from the visible box at low zoom (pps < 1). Guard
+  // only against a non-finite/zero pps (would yield NaN/Infinity), never floor it.
+  const safePps = Number.isFinite(pps) && pps > 0 ? pps : 0;
+  const timeFromX = (x: number) => (safePps > 0 ? Math.max(0, (x - GUTTER) / safePps) : 0);
+
+  return {
+    overlay: {
+      left: overlayLeft,
+      top: overlayTop,
+      width: overlayRight - overlayLeft,
+      height: overlayBottom - overlayTop,
+    },
+    selection: {
+      startTime: timeFromX(left),
+      endTime: timeFromX(right),
+      top,
+      bottom,
+    },
+  };
+}
+
+export function useTimelineMarqueeSelection({
+  scrollRef,
+  ppsRef,
+  trackOrderRef,
+  timelineLayersRef,
+  disabled = false,
+  setShowPopover,
+  setRangeSelectionRef,
+  seekFromX,
+}: UseTimelineMarqueeSelectionInput) {
+  const activeRef = useRef<ActiveMarqueeGesture | null>(null);
+  const pointerRef = useRef<{ clientX: number; clientY: number } | null>(null);
+  const scrollRafRef = useRef(0);
+  const [marqueeRect, setMarqueeRect] = useState<TimelineMarqueeOverlayRect | null>(null);
+
+  const stopAutoScroll = useCallback(() => {
+    pointerRef.current = null;
+    if (scrollRafRef.current) {
+      cancelAnimationFrame(scrollRafRef.current);
+      scrollRafRef.current = 0;
+    }
+  }, []);
+
+  const updateMarqueeRect = useCallback(() => {
+    const active = activeRef.current;
+    const scroll = scrollRef.current;
+    if (!active || !scroll) return null;
+    const rects = buildSelectionRect(active, scroll, ppsRef.current);
+    setMarqueeRect(rects.overlay);
+    return rects;
+  }, [ppsRef, scrollRef]);
+
+  const stepAutoScroll = useCallback(() => {
+    scrollRafRef.current = 0;
+    const pointer = pointerRef.current;
+    const scroll = scrollRef.current;
+    if (!pointer || !scroll || !activeRef.current) return;
+
+    const delta = resolveTimelineAutoScroll(
+      scroll.getBoundingClientRect(),
+      pointer.clientX,
+      pointer.clientY,
+    );
+    if (delta.x === 0 && delta.y === 0) return;
+
+    const maxScrollLeft = Math.max(0, scroll.scrollWidth - scroll.clientWidth);
+    const maxScrollTop = Math.max(0, scroll.scrollHeight - scroll.clientHeight);
+    const nextScrollLeft = Math.max(0, Math.min(maxScrollLeft, scroll.scrollLeft + delta.x));
+    const nextScrollTop = Math.max(0, Math.min(maxScrollTop, scroll.scrollTop + delta.y));
+    if (nextScrollLeft === scroll.scrollLeft && nextScrollTop === scroll.scrollTop) return;
+
+    scroll.scrollLeft = nextScrollLeft;
+    scroll.scrollTop = nextScrollTop;
+    updateMarqueeRect();
+    scrollRafRef.current = requestAnimationFrame(stepAutoScroll);
+  }, [scrollRef, updateMarqueeRect]);
+
+  const syncAutoScroll = useCallback(
+    (clientX: number, clientY: number) => {
+      pointerRef.current = { clientX, clientY };
+      const scroll = scrollRef.current;
+      if (!scroll) return;
+      const delta = resolveTimelineAutoScroll(scroll.getBoundingClientRect(), clientX, clientY);
+      if (delta.x === 0 && delta.y === 0) {
+        if (scrollRafRef.current) {
+          cancelAnimationFrame(scrollRafRef.current);
+          scrollRafRef.current = 0;
+        }
+        return;
+      }
+      if (!scrollRafRef.current) {
+        scrollRafRef.current = requestAnimationFrame(stepAutoScroll);
+      }
+    },
+    [scrollRef, stepAutoScroll],
+  );
+
+  const handlePointerDown = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      const point = getMarqueeStartPoint(event, scrollRef.current, disabled);
+      if (!point) return false;
+      capturePointerIfAvailable(event);
+      activeRef.current = {
+        pointerId: event.pointerId,
+        anchorClientX: event.clientX,
+        anchorClientY: event.clientY,
+        anchorX: point.x,
+        anchorY: point.y,
+        lastClientX: event.clientX,
+        lastClientY: event.clientY,
+        started: false,
+      };
+      setShowPopover(false);
+      setRangeSelectionRef.current?.(null);
+      return true;
+    },
+    [disabled, scrollRef, setRangeSelectionRef, setShowPopover],
+  );
+
+  const handlePointerMove = useCallback(
+    (event: ReactPointerEvent<HTMLDivElement>) => {
+      const active = activeRef.current;
+      if (!active || active.pointerId !== event.pointerId) return false;
+      active.lastClientX = event.clientX;
+      active.lastClientY = event.clientY;
+      const distance = Math.hypot(
+        event.clientX - active.anchorClientX,
+        event.clientY - active.anchorClientY,
+      );
+      if (!active.started && distance < MARQUEE_THRESHOLD_PX) return true;
+      active.started = true;
+      updateMarqueeRect();
+      syncAutoScroll(event.clientX, event.clientY);
+      return true;
+    },
+    [syncAutoScroll, updateMarqueeRect],
+  );
+
+  const handlePointerUp = useCallback(
+    (event?: ReactPointerEvent<HTMLDivElement>) => {
+      const active = activeRef.current;
+      if (!active || (event && active.pointerId !== event.pointerId)) return false;
+      activeRef.current = null;
+      stopAutoScroll();
+      setMarqueeRect(null);
+
+      if (!active.started) {
+        // A press that never crossed the marquee threshold is a plain empty-lane
+        // click: clear the selection AND scrub the playhead, matching the seek that
+        // the range/playhead handler would have run had the marquee not claimed it.
+        usePlayerStore.getState().clearSelection();
+        seekFromX(active.anchorClientX);
+        return true;
+      }
+
+      const scroll = scrollRef.current;
+      if (!scroll) return true;
+      const rects = buildSelectionRect(active, scroll, ppsRef.current);
+      const selectedIds = selectTimelineElementsInMarquee({
+        rect: rects.selection,
+        layers: timelineLayersRef.current,
+        layerOrder: trackOrderRef.current,
+        rulerHeight: RULER_H,
+        trackHeight: TRACK_H,
+        groupHeaderHeight: TIMELINE_LAYER_GROUP_HEADER_H,
+      });
+      usePlayerStore.getState().setSelection(selectedIds);
+      return true;
+    },
+    [ppsRef, scrollRef, seekFromX, stopAutoScroll, timelineLayersRef, trackOrderRef],
+  );
+
+  useEffect(() => stopAutoScroll, [stopAutoScroll]);
+
+  return {
+    marqueeRect,
+    handlePointerDown,
+    handlePointerMove,
+    handlePointerUp,
+  };
+}

package/src/player/hooks/useExpandedTimelineElements.ts

@@ -192,9 +192,12 @@ function domSiblingClips(
         start: host.start,
         duration: host.duration,
         track: host.track,
+        zIndex: 0,
+        stackingContextId: host.stackingContextId ?? host.domId ?? host.id ?? null,
         kind: "element",
         tagName: null,
         compositionId: null,
+        compositionAncestors: host.compositionAncestors ?? [],
         parentCompositionId: host.id ?? null,
         compositionSrc: host.compositionSrc ?? null,
         assetUrl: null,

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

@@ -243,7 +243,10 @@ describe("buildStandaloneRootTimelineElement", () => {
         iframeSrc: "http://127.0.0.1:4173/api/projects/demo/preview/comp/scenes/hero.html?_t=123",
         selector: '[data-composition-id="hero"]',
       }),
-    ).toEqual({
+      // toMatchObject (not toEqual): asserts the selector/source metadata this
+      // test is about, without re-pinning the full element shape (stacking
+      // metadata like hasExplicitZIndex is covered in timelineDOM.test.ts).
+    ).toMatchObject({
       id: "hero",
       label: "hero",
       key: 'scenes/hero.html:[data-composition-id="hero"]:0',

package/src/player/hooks/useTimelinePlayer.ts

@@ -44,6 +44,7 @@ import {
 import { scrubMusicAtSeek, stopScrubPreviewAudio } from "../lib/playbackScrub";
 import { applyCachedSourceDurations, probeMissingSourceDurations } from "../lib/mediaProbe";
 import { shouldResumeForwardPlaybackAfterSeek, shouldStopAfterSeek } from "../lib/playbackSeek";
+import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
 
 /**
  * Whether the derived elements differ from the current ones in any field that
@@ -127,6 +128,8 @@ export function useTimelinePlayer() {
     [setElements, setTimelineReady, setDuration],
   );
 
+  // Pre-existing dispatcher complexity — surfaced by this PR's line shifts, not new logic.
+  // fallow-ignore-next-line complexity
   const getAdapter = useCallback((): PlaybackAdapter | null => {
     try {
       const iframe = iframeRef.current;
@@ -209,6 +212,7 @@ export function useTimelinePlayer() {
   }, []);
 
   const startRAFLoop = useCallback(() => {
+    // fallow-ignore-next-line complexity
     const tick = () => {
       const adapter = getAdapter();
       if (adapter) {
@@ -475,6 +479,7 @@ export function useTimelinePlayer() {
     const src = iframe.src;
     const url = new URL(src, window.location.origin);
     url.searchParams.set("_t", String(Date.now()));
+    applyPreviewVariablesToUrl(url);
     iframe.src = url.toString();
   }, [saveSeekPosition]);
   const getAdapterRef = useRef(getAdapter);
@@ -484,6 +489,8 @@ export function useTimelinePlayer() {
     const handleWindowKeyDown = (e: KeyboardEvent) => playbackKeyDownRef.current(e);
     const handleWindowKeyUp = (e: KeyboardEvent) => playbackKeyUpRef.current(e);
 
+    // Pre-existing message-router complexity — surfaced by line shifts, not new logic.
+    // fallow-ignore-next-line complexity
     const handleMessage = (e: MessageEvent) => {
       const data = e.data;
       const ourIframe = iframeRef.current;

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

@@ -0,0 +1,77 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+import { computeReorderZValues, getElementZIndex, resolveContextOrder } from "./layerOrdering";
+
+function makeElement(zIndex?: string): HTMLElement {
+  const element = document.createElement("div");
+  if (zIndex != null) element.style.zIndex = zIndex;
+  document.body.appendChild(element);
+  return element;
+}
+
+describe("getElementZIndex", () => {
+  it("returns inline z-index when present", () => {
+    expect(getElementZIndex(makeElement("7"))).toBe(7);
+  });
+
+  it("falls back to computed style when inline z-index is not usable", () => {
+    const element = makeElement();
+    element.className = "computed-z";
+    const style = document.createElement("style");
+    style.textContent = ".computed-z { position: relative; z-index: 12; }";
+    document.head.appendChild(style);
+
+    expect(getElementZIndex(element)).toBe(12);
+  });
+
+  it("returns zero for auto or missing z-index", () => {
+    expect(getElementZIndex(makeElement())).toBe(0);
+    expect(getElementZIndex(makeElement("auto"))).toBe(0);
+  });
+});
+
+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([
+      { id: "a", zIndex: 2, parentCompositionId: null, compositionAncestors: ["root"] },
+      { id: "b", zIndex: 5, parentCompositionId: null, compositionAncestors: ["root"] },
+      { id: "c", zIndex: 5, parentCompositionId: null, compositionAncestors: ["root"] },
+    ]);
+
+    expect(ordered.map((item) => item.id)).toEqual(["b", "c", "a"]);
+  });
+
+  it("keeps distinct stacking contexts from interleaving", () => {
+    const ordered = resolveContextOrder([
+      { id: "root-low", zIndex: 1, parentCompositionId: null, compositionAncestors: ["root"] },
+      {
+        id: "nested-high",
+        zIndex: 100,
+        parentCompositionId: "scene",
+        compositionAncestors: ["root", "scene"],
+      },
+      { id: "root-top", zIndex: 2, parentCompositionId: null, compositionAncestors: ["root"] },
+    ]);
+
+    expect(ordered.map((item) => item.id)).toEqual(["root-top", "root-low", "nested-high"]);
+  });
+
+  it("returns an empty list for empty input", () => {
+    expect(resolveContextOrder([])).toEqual([]);
+  });
+});