@hyperframes/studio 0.8.101 → 0.8.102

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.101",
+  "version": "0.8.102",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.8.101",
-    "@hyperframes/sdk": "0.8.101",
-    "@hyperframes/shader-transitions": "0.8.101",
-    "@hyperframes/studio-server": "0.8.101",
-    "@hyperframes/player": "0.8.101",
-    "@hyperframes/core": "0.8.101"
+    "@hyperframes/core": "0.8.102",
+    "@hyperframes/player": "0.8.102",
+    "@hyperframes/sdk": "0.8.102",
+    "@hyperframes/parsers": "0.8.102",
+    "@hyperframes/studio-server": "0.8.102",
+    "@hyperframes/shader-transitions": "0.8.102"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.101"
+    "@hyperframes/producer": "0.8.102"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/editor/CanvasContextMenu.test.tsx

@@ -3,7 +3,7 @@ import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { installReactActEnvironment, makeSelection } from "../../hooks/domSelectionTestHarness";
-import { resolveZIndexEntries } from "./ConnectedDomEditOverlay";
+import { resolveZIndexEntries } from "./useDomEditZOrder";
 import { useElementLifecycleOps } from "../../hooks/useElementLifecycleOps";
 import { makeLifecycleOpsParams } from "../../hooks/elementLifecycleOpsTestUtils";
 import type { DomEditPatchBatch } from "../../hooks/domEditCommitTypes";
@@ -193,6 +193,27 @@ function renderCommitHook(captured: CapturedBatchCall[]) {
   return { commit: commit!, cleanup: () => act(() => hookRoot.unmount()) };
 }
 
+describe("resolveZIndexEntries", () => {
+  it("keys a same-class sibling by its index among them, not as the first of its class", () => {
+    const parent = document.body.appendChild(document.createElement("div"));
+    const [first, second, selected] = ["card", "card", "picked"].map((name) => {
+      const child = parent.appendChild(document.createElement("div"));
+      child.className = name;
+      return child;
+    });
+    const { entries } = resolveZIndexEntries(
+      makeSelection("Picked", selected!),
+      [first!, second!].map((element, zIndex) => ({ element, zIndex })),
+      null,
+    );
+    expect(entries.map((entry) => [entry.selector, entry.selectorIndex])).toEqual([
+      [".card", 0],
+      [".card", 1],
+    ]);
+    parent.remove();
+  });
+});
+
 describe("CanvasContextMenu — z-action commit path", () => {
   it("never mutates live styles itself and persists the position patch for a static element", async () => {
     const { target } = makeStaticFamily();
@@ -208,7 +229,7 @@ describe("CanvasContextMenu — z-action commit path", () => {
       selection,
       onApplyZIndex: (patches, action) => {
         stylesAtApply.push({ zIndex: target.style.zIndex, position: target.style.position });
-        const { entries } = resolveZIndexEntries(selection, patches);
+        const { entries } = resolveZIndexEntries(selection, patches, null);
         void commit(entries, undefined, action);
       },
     });

package/src/components/editor/CanvasContextMenu.tsx

@@ -16,7 +16,7 @@
  * flow, and captures the TRUE prior styles for its failure rollback.
  *
  * The prop MUST be wired at the call site to route through the full persist
- * path. ConnectedDomEditOverlay.tsx builds the per-patch PatchTargets (the selected
+ * path. useDomEditZOrder.ts builds the per-patch PatchTargets (the selected
  * element carries its full selection identity; sibling elements are iframe DOM
  * nodes, so their id / selector are derived from the node and they share the
  * selection's sourceFile) and forwards them to handleDomZIndexReorderCommit.
@@ -29,8 +29,7 @@ import type { DomEditSelection } from "./domEditing";
 import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
 import {
   isZOrderActionEnabled,
-  resolveCrossedNeighbor,
-  resolveZOrderChange,
+  resolveZOrderStep,
   type ZOrderAction,
   type ZOrderPatch,
 } from "./canvasContextMenuZOrder";
@@ -170,13 +169,11 @@ export const CanvasContextMenu = memo(function CanvasContextMenu({
 
   function handleZAction(action: ZAction) {
     if (!onApplyZIndex) return;
-    const patches = resolveZOrderChange(el, action);
-    if (patches === null) return;
-    // Resolve the crossed neighbor BEFORE the commit path mutates live styles —
-    // both resolvers must read the same pre-change render order. Always resolved
-    // (not only for the flash): onApplyZIndex forwards it so the host can mirror
-    // the z step into a timeline lane move.
-    const crossed = resolveCrossedNeighbor(el, action);
+    // Resolved BEFORE the commit path mutates live styles. `crossed` is always
+    // resolved (not only for the flash): the host mirrors it into a lane move.
+    const step = resolveZOrderStep(el, action);
+    if (step === null) return;
+    const { patches, crossed } = step;
     // Do NOT pre-apply styles here: handleDomZIndexReorderCommit writes the
     // live z-index (and injects position:relative for static elements) in the
     // same synchronous flow, so feedback is still instant — and it must read

package/src/components/editor/ConnectedDomEditOverlay.tsx

@@ -4,12 +4,7 @@ import {
   useDomEditActionsContext,
   useDomEditSelectionContext,
 } from "../../contexts/DomEditContext";
-import { readHfId, type DomEditSelection } from "./domEditing";
-import { buildStableSelector } from "./domEditingDom";
-import { deriveTimelineStoreKey } from "../../player/lib/timelineElementHelpers";
-import { zReorderCoalesceKey } from "../../hooks/useElementLifecycleOps";
-import { useCanvasZOrderTimelineMirror } from "../nle/useCanvasZOrderTimelineMirror";
-import { runZLaneGesture } from "../nle/zLaneGesture";
+import { useDomEditZOrder } from "./useDomEditZOrder";
 
 type HostInputProps = Pick<
   ComponentProps<typeof DomEditOverlay>,
@@ -25,94 +20,6 @@ export interface ConnectedDomEditOverlayProps extends HostInputProps {
   onTextEditingChange?: (editing: boolean) => void;
 }
 
-type ZIndexReorderEntry = {
-  element: HTMLElement;
-  zIndex: number;
-  id?: string;
-  selector?: string;
-  selectorIndex?: number;
-  sourceFile: string;
-  /** Timeline store key — lets the commit update the store zIndex synchronously. */
-  key?: string;
-};
-
-/** Can this element be robustly re-targeted for a persisted z change? */
-function canTargetZIndexElement(
-  element: HTMLElement,
-  id: string | undefined,
-  selector: string | undefined,
-): boolean {
-  return Boolean(id || selector || readHfId(element));
-}
-
-/** The selected element carries its full selection identity. */
-function selectedZIndexEntry(sel: DomEditSelection, zIndex: number): ZIndexReorderEntry {
-  return {
-    element: sel.element,
-    zIndex,
-    id: sel.id ?? undefined,
-    selector: sel.selector,
-    selectorIndex: sel.selectorIndex,
-    sourceFile: sel.sourceFile,
-    key: deriveTimelineStoreKey({
-      domId: sel.id ?? undefined,
-      selector: sel.selector,
-      selectorIndex: sel.selectorIndex,
-      sourceFile: sel.sourceFile,
-    }),
-  };
-}
-
-/** A raw iframe sibling in the selection's file; null with no id or selector (z stays live). */
-function siblingZIndexEntry(
-  element: HTMLElement,
-  zIndex: number,
-  sourceFile: string,
-): ZIndexReorderEntry | null {
-  const id = element.id || undefined;
-  const selector = buildStableSelector(element);
-  if (!canTargetZIndexElement(element, id, selector)) return null;
-  return {
-    element,
-    zIndex,
-    id,
-    selector,
-    selectorIndex: undefined,
-    sourceFile,
-    key: deriveTimelineStoreKey({ domId: id, selector, sourceFile }),
-  };
-}
-
-/** Short human-readable label for a dropped sibling, for the console warning below. */
-function describeZIndexElement(element: HTMLElement): string {
-  if (element.id) return `#${element.id}`;
-  const firstClass = element.classList.item(0);
-  return firstClass
-    ? `${element.tagName.toLowerCase()}.${firstClass}`
-    : element.tagName.toLowerCase();
-}
-
-// Resolve z-index patches into commit entries; a sibling with no stable
-// id/selector can't be written to source, so it is returned as `dropped` for
-// the revert-on-reload warning. Exported so tests can drive the menu → commit path.
-export function resolveZIndexEntries(
-  sel: DomEditSelection,
-  patches: ReadonlyArray<{ element: HTMLElement; zIndex: number }>,
-): { entries: ZIndexReorderEntry[]; dropped: Array<{ element: HTMLElement; zIndex: number }> } {
-  const entries: ZIndexReorderEntry[] = [];
-  const dropped: Array<{ element: HTMLElement; zIndex: number }> = [];
-  for (const patch of patches) {
-    if (patch.element === sel.element) {
-      entries.push(selectedZIndexEntry(sel, patch.zIndex));
-      continue;
-    }
-    const entry = siblingZIndexEntry(patch.element, patch.zIndex, sel.sourceFile);
-    if (entry) entries.push(entry);
-    else dropped.push(patch);
-  }
-  return { entries, dropped };
-}
-
 // Studio's DomEditOverlay wired to the session in DomEditProvider, so a host
 // outside EditorShell mounts the same canvas editing without its own callbacks.
 export function ConnectedDomEditOverlay({
@@ -142,9 +49,8 @@ export function ConnectedDomEditOverlay({
     handleDomStyleCommit,
     applyMarqueeSelection,
     handleDomEditElementDelete,
-    handleDomZIndexReorderCommit,
   } = useDomEditActionsContext();
-  const mirrorZOrderToTimeline = useCanvasZOrderTimelineMirror();
+  const zOrder = useDomEditZOrder();
 
   return (
     <DomEditOverlay
@@ -170,38 +76,7 @@ export function ConnectedDomEditOverlay({
       onRotationCommit={handleDomRotationCommit}
       onStyleCommit={handleDomStyleCommit}
       onDeleteSelection={handleDomEditElementDelete}
-      onApplyZIndex={(sel, patches, action, crossed) => {
-        const { entries, dropped } = resolveZIndexEntries(sel, patches);
-        if (dropped.length > 0) {
-          // These siblings can't be written to source. Apply their live z
-          // anyway so the resolved stacking order renders coherently — it
-          // just reverts to the prior order on the next reload.
-          for (const patch of dropped) patch.element.style.zIndex = String(patch.zIndex);
-          console.warn(
-            "[studio] z-index reorder: dropping sibling(s) with no stable id/selector " +
-              "(will revert on reload):",
-            dropped.map((patch) => describeZIndexElement(patch.element)).join(", "),
-          );
-        }
-        if (entries.length === 0) return;
-        // One coalesce key for the z persist AND the lane mirror folds both into one undo entry;
-        // passed explicitly so the mirror shares it by construction, not by formula duplication.
-        const coalesceKey = zReorderCoalesceKey(entries, action);
-        // One serialized z→lane transaction: the mirror runs only AFTER a durable z commit and
-        // no second gesture interleaves (see runZLaneGesture). A failed z commit has already
-        // toasted and rolled back, so the catch only keeps its rejection from going unhandled.
-        runZLaneGesture({
-          commitZ: () => handleDomZIndexReorderCommit(entries, coalesceKey, action),
-          mirror: () =>
-            mirrorZOrderToTimeline({
-              selectionKey: entries.find((e) => e.element === sel.element)?.key,
-              action,
-              crossed,
-              sourceFile: sel.sourceFile,
-              coalesceKey,
-            }),
-        }).catch(() => undefined);
-      }}
+      onApplyZIndex={zOrder.commit}
       onMarqueeSelect={applyMarqueeSelection}
     />
   );

package/src/components/editor/canvasContextMenuZOrder.ts

@@ -511,3 +511,16 @@ export function isZOrderActionEnabled(
 ): boolean {
   return resolveZOrderChange(target, action, options) !== null;
 }
+
+/**
+ * One z-order step: the patches plus the sibling it crosses, both read from the
+ * same pre-change render order. Null when the action is a no-op.
+ */
+export function resolveZOrderStep(
+  target: HTMLElement,
+  action: ZOrderAction,
+): { patches: ZOrderPatch[]; crossed: HTMLElement | null } | null {
+  const patches = resolveZOrderChange(target, action);
+  if (patches === null) return null;
+  return { patches, crossed: resolveCrossedNeighbor(target, action) };
+}

package/src/components/editor/gsapAnimatesProperty.ts

@@ -1,32 +1,3 @@
-// GSAP's CSSPlugin takes ownership of the element's entire transform stack
-// when it tweens ANY of these — it bakes the CSS `translate` longhand into
-// style.transform at init and writes `translate: none` every tick. Position
-// reapply/strip logic must therefore stand down for all of them, not just x/y.
-const GSAP_TRANSFORM_PROPS = [
-  "x",
-  "y",
-  "xPercent",
-  "yPercent",
-  "scale",
-  "scaleX",
-  "scaleY",
-  "rotation",
-  "rotate",
-  "rotationX",
-  "rotationY",
-  "skewX",
-  "skewY",
-  "transform",
-];
-
-/**
- * True when GSAP animates any transform-affecting property on the element,
- * meaning GSAP owns `style.transform` and has neutralized CSS `translate`.
- */
-export function gsapAnimatesTransform(el: HTMLElement): boolean {
-  return gsapAnimatesProperty(el, ...GSAP_TRANSFORM_PROPS);
-}
-
 /**
  * Checks whether GSAP actively animates one or more CSS/GSAP properties on
  * the given element by inspecting all registered `__timelines`.

package/src/components/editor/gsapLivePreview.test.ts

@@ -1,10 +1,15 @@
 // @vitest-environment happy-dom
-import { expect, it, vi } from "vitest";
+import { afterEach, expect, it, vi } from "vitest";
 import { createGsapLivePreview } from "./gsapLivePreview";
 import type { DomEditSelection } from "./domEditingTypes";
 import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
 import { readGsapRuntimeValuesForPanel } from "./propertyPanelHelpers";
 
+afterEach(() => {
+  delete (window as { gsap?: unknown }).gsap;
+  delete (window as { __timelines?: unknown }).__timelines;
+});
+
 it("previews on the selected element, not an earlier same-id copy in a sub-composition", () => {
   document.body.innerHTML =
     '<div data-composition-id="strip"><div id="card" data-hf-id="hf-inner"></div></div>' +
@@ -61,3 +66,43 @@ it("the panel reads GSAP values off the node the live preview moves", () => {
   });
   expect(getProperty.mock.calls[0]?.[0]).toBe(root);
 });
+
+it.each([
+  ["fades it", { opacity: 0 }, ["opacity"]],
+  ["fades it about its corner", { opacity: 0, transformOrigin: "0 0" }, ["opacity"]],
+  [
+    "moves it",
+    { x: 100 },
+    [
+      "x",
+      "y",
+      "rotation",
+      "rotationX",
+      "rotationY",
+      "rotationZ",
+      "z",
+      "scale",
+      "transformPerspective",
+      "opacity",
+    ],
+  ],
+])(
+  "the panel reads GSAP's transform only off an element GSAP positions: a tween that %s",
+  (_, vars, read) => {
+    document.body.innerHTML = '<div id="card"></div>';
+    const card = document.querySelector<HTMLElement>("#card");
+    const tween = { targets: () => [card], vars, duration: () => 1 };
+    const getProperty = vi.fn(() => 1);
+    const contentWindow = Object.assign(window, {
+      gsap: { getProperty },
+      __timelines: { main: { getChildren: () => [tween] } },
+    });
+    const selection = { id: "card", sourceFile: "index.html", element: card } as DomEditSelection;
+    const animations = [{ properties: vars }] as unknown as GsapAnimation[];
+    readGsapRuntimeValuesForPanel("anim", animations, selection, {
+      current: { contentWindow, contentDocument: document } as unknown as HTMLIFrameElement,
+    });
+    const props = getProperty.mock.calls.map((call) => (call as unknown[])[1]);
+    expect(props).toEqual(read);
+  },
+);

package/src/components/editor/propertyPanelHelpers.ts

@@ -9,6 +9,7 @@ import {
   playbackStartAttributeForElement,
   readPlaybackStartAttributes,
 } from "../../player/lib/timelineElementHelpers";
+import { GSAP_TRANSFORM_KEYS, gsapWritesPosition } from "../../hooks/gsapRuntimeKeyframes";
 
 export type {
   BackgroundRemovalProgress,
@@ -496,8 +497,10 @@ export function readGsapRuntimeValuesForPanel(
     const el = findPreviewNode(iframe.contentDocument, element);
     if (!el) return null;
     const propKeys = collectPanelPropKeys(gsapAnimations);
+    const readsTransform = gsapWritesPosition(el);
     const result: Record<string, number> = {};
     for (const prop of propKeys) {
+      if (!readsTransform && GSAP_TRANSFORM_KEYS.has(prop)) continue;
       const v = Number(gsap.getProperty(el, prop));
       if (Number.isFinite(v)) result[prop] = roundToCenti(v);
     }

package/src/components/editor/useDomEditZOrder.ts

@@ -0,0 +1,185 @@
+import { useCallback, useMemo } from "react";
+import { useDomEditActionsContext } from "../../contexts/DomEditContext";
+import { readHfId, type DomEditSelection } from "./domEditing";
+import { buildStableSelector, getSelectorIndex } from "./domEditingDom";
+import { usePreviewReadOnly } from "./previewReadOnlyContext";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { deriveTimelineStoreKey } from "../../player/lib/timelineElementHelpers";
+import { zReorderCoalesceKey } from "../../hooks/useElementLifecycleOps";
+import { useCanvasZOrderTimelineMirror } from "../nle/useCanvasZOrderTimelineMirror";
+import { runZLaneGesture } from "../nle/zLaneGesture";
+import {
+  isZOrderActionEnabled,
+  resolveZOrderStep,
+  type ZOrderAction,
+  type ZOrderPatch,
+} from "./canvasContextMenuZOrder";
+
+type ZIndexReorderEntry = {
+  element: HTMLElement;
+  zIndex: number;
+  id?: string;
+  selector?: string;
+  selectorIndex?: number;
+  sourceFile: string;
+  /** Timeline store key — lets the commit update the store zIndex synchronously. */
+  key?: string;
+};
+
+/** Can this element be robustly re-targeted for a persisted z change? */
+function canTargetZIndexElement(
+  element: HTMLElement,
+  id: string | undefined,
+  selector: string | undefined,
+): boolean {
+  return Boolean(id || selector || readHfId(element));
+}
+
+/** The selected element carries its full selection identity. */
+function selectedZIndexEntry(sel: DomEditSelection, zIndex: number): ZIndexReorderEntry {
+  return {
+    element: sel.element,
+    zIndex,
+    id: sel.id ?? undefined,
+    selector: sel.selector,
+    selectorIndex: sel.selectorIndex,
+    sourceFile: sel.sourceFile,
+    key: deriveTimelineStoreKey({
+      domId: sel.id ?? undefined,
+      selector: sel.selector,
+      selectorIndex: sel.selectorIndex,
+      sourceFile: sel.sourceFile,
+    }),
+  };
+}
+
+/** A raw iframe sibling in the selection's file; null with no id or selector (z stays live). Its selector index
+ * picks it among same-class siblings, the way the lane mirror keys `crossed`. */
+function siblingZIndexEntry(
+  element: HTMLElement,
+  zIndex: number,
+  sourceFile: string,
+  activeCompPath: string | null,
+): ZIndexReorderEntry | null {
+  const id = element.id || undefined;
+  const selector = buildStableSelector(element);
+  if (!canTargetZIndexElement(element, id, selector)) return null;
+  const selectorIndex = id
+    ? undefined
+    : getSelectorIndex(element.ownerDocument, element, selector, sourceFile, activeCompPath);
+  return {
+    element,
+    zIndex,
+    id,
+    selector,
+    selectorIndex,
+    sourceFile,
+    key: deriveTimelineStoreKey({ domId: id, selector, selectorIndex, sourceFile }),
+  };
+}
+
+/** Short human-readable label for a dropped sibling, for the console warning below. */
+function describeZIndexElement(element: HTMLElement): string {
+  if (element.id) return `#${element.id}`;
+  const firstClass = element.classList.item(0);
+  return firstClass
+    ? `${element.tagName.toLowerCase()}.${firstClass}`
+    : element.tagName.toLowerCase();
+}
+
+// Patches as commit entries; a sibling with no id or selector is `dropped` and reverts on reload.
+export function resolveZIndexEntries(
+  sel: DomEditSelection,
+  patches: ReadonlyArray<{ element: HTMLElement; zIndex: number }>,
+  activeCompPath: string | null,
+): { entries: ZIndexReorderEntry[]; dropped: Array<{ element: HTMLElement; zIndex: number }> } {
+  const entries: ZIndexReorderEntry[] = [];
+  const dropped: Array<{ element: HTMLElement; zIndex: number }> = [];
+  for (const patch of patches) {
+    if (patch.element === sel.element) {
+      entries.push(selectedZIndexEntry(sel, patch.zIndex));
+      continue;
+    }
+    const entry = siblingZIndexEntry(patch.element, patch.zIndex, sel.sourceFile, activeCompPath);
+    if (entry) entries.push(entry);
+    else dropped.push(patch);
+  }
+  return { entries, dropped };
+}
+
+export interface DomEditZOrder {
+  /** False in a read-only preview, for an element no longer in the live preview, or at that end of its stacking set. */
+  enabled: (sel: DomEditSelection, action: ZOrderAction) => boolean;
+  /** Resolve and commit one step; false when nothing is sent to be saved. */
+  apply: (sel: DomEditSelection, action: ZOrderAction) => boolean;
+  /** Commit patches already resolved (the canvas menu resolves its own); false when none could be sent to be saved. */
+  commit: (
+    sel: DomEditSelection,
+    patches: ReadonlyArray<ZOrderPatch>,
+    action: ZOrderAction,
+    crossed: HTMLElement | null,
+  ) => boolean;
+}
+
+/** A selection from before a preview reload holds an element of a document no window shows, with stale z values. */
+const isLive = (element: HTMLElement) =>
+  element.isConnected && element.ownerDocument.defaultView !== null;
+
+// The canvas menu's z-order (write, undo, lane mirror) for any caller in DomEditProvider.
+export function useDomEditZOrder(): DomEditZOrder {
+  const { handleDomZIndexReorderCommit } = useDomEditActionsContext();
+  const mirrorZOrderToTimeline = useCanvasZOrderTimelineMirror();
+  const readOnly = usePreviewReadOnly();
+  const activeCompPath = useStudioShellContextOptional()?.activeCompPath ?? null;
+
+  const enabled = useCallback<DomEditZOrder["enabled"]>(
+    (sel, action) => !readOnly && isLive(sel.element) && isZOrderActionEnabled(sel.element, action),
+    [readOnly],
+  );
+
+  const commit = useCallback<DomEditZOrder["commit"]>(
+    (sel, patches, action, crossed) => {
+      if (readOnly) return false;
+      const { entries, dropped } = resolveZIndexEntries(sel, patches, activeCompPath);
+      if (dropped.length > 0) {
+        // Not writable to source: their live z still applies, so the order renders, until a reload.
+        for (const patch of dropped) patch.element.style.zIndex = String(patch.zIndex);
+        console.warn(
+          "[studio] z-index reorder: dropping sibling(s) with no stable id/selector " +
+            "(will revert on reload):",
+          dropped.map((patch) => describeZIndexElement(patch.element)).join(", "),
+        );
+      }
+      if (entries.length === 0) return false;
+      // One coalesce key for the z write and the lane mirror: one undo entry.
+      const coalesceKey = zReorderCoalesceKey(entries, action);
+      // One serialized z→lane transaction: the mirror runs only AFTER a durable z commit and
+      // no second gesture interleaves (see runZLaneGesture). A failed z commit has already
+      // toasted and rolled back, so the catch only keeps its rejection from going unhandled.
+      runZLaneGesture({
+        commitZ: () => handleDomZIndexReorderCommit(entries, coalesceKey, action),
+        mirror: () =>
+          mirrorZOrderToTimeline({
+            selectionKey: entries.find((e) => e.element === sel.element)?.key,
+            action,
+            crossed,
+            sourceFile: sel.sourceFile,
+            coalesceKey,
+          }),
+      }).catch(() => undefined);
+      return true;
+    },
+    [activeCompPath, handleDomZIndexReorderCommit, mirrorZOrderToTimeline, readOnly],
+  );
+
+  const apply = useCallback<DomEditZOrder["apply"]>(
+    (sel, action) => {
+      if (!isLive(sel.element)) return false;
+      const step = resolveZOrderStep(sel.element, action);
+      return step !== null && commit(sel, step.patches, action, step.crossed);
+    },
+    [commit],
+  );
+
+  return useMemo(() => ({ enabled, apply, commit }), [enabled, apply, commit]);
+}

package/src/components/nle/PreviewOverlaysTestMocks.ts

@@ -8,6 +8,10 @@ export const iframeRef = { current: null as HTMLIFrameElement | null };
 
 vi.mock("../../contexts/StudioContext", () => ({
   useStudioShellContext: () => ({ activeCompPath: "index.html", previewIframeRef: iframeRef }),
+  useStudioShellContextOptional: () => ({
+    activeCompPath: "index.html",
+    previewIframeRef: iframeRef,
+  }),
   useStudioPlaybackContext: () => ({
     captionEditMode: previewState.captionEditMode,
     compositionLoading: false,