@hyperframes/studio 0.8.101 → 0.8.103

package/src/components/editor/plainTranslate.ts

@@ -6,29 +6,65 @@ import type { PatchOperation } from "../../utils/sourcePatcher";
 
 type Point = { x: number; y: number };
 
-const TERM = /^(-?\d*\.?\d+(?:e[-+]?\d+)?)(px|%)$/i;
+const TOKEN = /\s*(?:(\d*\.?\d+(?:e[-+]?\d+)?)(px|%)?|([a-z]+)\(|([-+*/(),]))/giy;
+const FUNCTIONS: Record<string, (args: number[]) => number> = {
+  "(": ([a = Number.NaN]) => a,
+  "calc(": ([a = Number.NaN]) => a,
+  "min(": (args) => Math.min(...args),
+  "max(": (args) => Math.max(...args),
+  "clamp(": ([lo = Number.NaN, v = Number.NaN, hi = Number.NaN]) => Math.max(lo, Math.min(v, hi)),
+};
 
-const SIGN: Record<string, number> = { "+": 1, "-": -1 };
-
-function termPx(term: string | undefined, side: number): number | null {
-  const match = TERM.exec(term ?? "");
-  return match ? Number(match[1]) * (match[2] === "%" ? side / 100 : 1) : null;
+/** Lengths become px against `side`; functions keep their "(" so they can't pass for an operator. */
+function tokenize(value: string, side: number): (number | string)[] {
+  const tokens: (number | string)[] = [];
+  const end = value.trimEnd().length;
+  TOKEN.lastIndex = 0;
+  for (let m = TOKEN.exec(value); m; m = TOKEN.lastIndex < end ? TOKEN.exec(value) : null) {
+    if (m[1]) tokens.push(Number(m[1]) * (m[2] === "%" ? side / 100 : 1));
+    else tokens.push(m[3] ? `${m[3].toLowerCase()}(` : (m[4] ?? ""));
+  }
+  return TOKEN.lastIndex < end ? [] : tokens;
 }
 
-/** px, %, or Chrome's computed `calc(P% + Lpx)`, against the border-box side; null for min()/max()/clamp(). */
-function resolveLength(value: string, side: number): number | null {
-  const parts = (/^calc\((.*)\)$/.exec(value)?.[1] ?? value).split(" ");
-  if (parts.length % 2 === 0) return null;
-  let total = termPx(parts[0], side);
-  for (let i = 1; i < parts.length && total !== null; i += 2) {
-    const term = termPx(parts[i + 1], side);
-    const sign = SIGN[parts[i] ?? ""];
-    total = term === null || !sign ? null : total + sign * term;
+/** Chrome's computed length (px, %, calc/min/max/clamp, + - * /) in px against `side`; NaN otherwise. */
+function evaluateLength(value: string, side: number): number {
+  const tokens = tokenize(value, side);
+  let i = 0;
+  const next = () => tokens[i++];
+  const take = (...ops: string[]) => ops.includes(tokens[i] as string) && next();
+  function sum(): number {
+    let total = product();
+    for (let op = take("+", "-"); op; op = take("+", "-"))
+      total += (op === "+" ? 1 : -1) * product();
+    return total;
+  }
+  function product(): number {
+    let total = unary();
+    for (let op = take("*", "/"); op; op = take("*", "/"))
+      total = op === "*" ? total * unary() : total / unary();
+    return total;
+  }
+  function unary(): number {
+    return take("-") ? -unary() : atom();
+  }
+  function atom(): number {
+    const token = next();
+    if (typeof token === "number") return token;
+    const fn = FUNCTIONS[token ?? ""];
+    if (!fn) return Number.NaN;
+    const args = [sum()];
+    while (take(",")) args.push(sum());
+    return take(")") ? fn(args) : Number.NaN;
   }
-  return total;
+  const total = tokens.length ? sum() : Number.NaN;
+  return i === tokens.length ? total : Number.NaN;
 }
 
-function borderBox(
+const CONTENT_BOXES = new Set(["content-box", "fill-box"]);
+
+/** The side % resolves against: the box `transform-box` names (fill-box is the content box on HTML). */
+function referenceBox(
   cs: CSSStyleDeclaration,
   size: "width" | "height",
   a: string,
@@ -37,35 +73,29 @@ function borderBox(
   const n = (prop: string) => Number.parseFloat(cs.getPropertyValue(prop)) || 0;
   const pad =
     n(`padding-${a}`) + n(`padding-${b}`) + n(`border-${a}-width`) + n(`border-${b}-width`);
-  return n(size) + (cs.boxSizing === "border-box" ? 0 : pad);
-}
-
-// Chrome resolves min()/max()/clamp() inside a transform function to a matrix; an unrendered box has none.
-function resolveInTransform(el: HTMLElement, x: string, y: string): Point {
-  const style = el.style;
-  const saved = [style.getPropertyValue("transform"), style.getPropertyPriority("transform")];
-  style.setProperty("transform", `translate(${x}, ${y})`, "important");
-  try {
-    const resolved = el.ownerDocument.defaultView?.getComputedStyle(el).transform ?? "";
-    const matrix = new DOMMatrixReadOnly(resolved.startsWith("matrix") ? resolved : undefined);
-    return { x: matrix.m41, y: matrix.m42 };
-  } finally {
-    style.setProperty("transform", saved[0] ?? "", saved[1] ?? "");
-  }
+  const content = n(size) - (cs.boxSizing === "border-box" ? pad : 0);
+  return CONTENT_BOXES.has(cs.getPropertyValue("transform-box")) ? content : content + pad;
 }
 
 /** The element's CSS `translate` in px, as it renders now. */
 // ponytail: a 3-value translate loses its z on the next move; keep z when a fixture needs it.
 export function readTranslatePx(el: HTMLElement): Point {
   const cs = el.ownerDocument.defaultView?.getComputedStyle(el);
-  const value = el.style.getPropertyValue("translate") || cs?.translate || "none";
+  // Computed first: Chrome resolves em, vw and var() there and leaves only % to work out.
+  const value = cs?.translate || el.style.getPropertyValue("translate") || "none";
   if (value === "none") return { x: 0, y: 0 };
   const [x = "0px", y = "0px"] = splitTopLevelWhitespace(value);
-  const px = cs && resolveLength(x, borderBox(cs, "width", "left", "right"));
-  const py = cs && resolveLength(y, borderBox(cs, "height", "top", "bottom"));
-  return px != null && py != null ? { x: px, y: py } : resolveInTransform(el, x, y);
+  const side = (size: "width" | "height", a: string, b: string) =>
+    cs ? referenceBox(cs, size, a, b) : 0;
+  return {
+    x: evaluateLength(x, side("width", "left", "right")),
+    y: evaluateLength(y, side("height", "top", "bottom")),
+  };
 }
 
+export const UNREADABLE_TRANSLATE =
+  "Studio can't read this layer's translate. Move it in the Code tab.";
+
 /** Plain px only: GSAP's CSSPlugin splits `translate` on spaces and drops a calc(). */
 function formatTranslatePx(p: Point): string {
   return `${roundTo3(p.x)}px ${roundTo3(p.y)}px`;

package/src/components/editor/previewReadOnly.overlay.test.tsx

@@ -9,6 +9,7 @@ import { __resetForTests } from "../../utils/canvasNudgeGate";
 import { PreviewReadOnlyProvider } from "./previewReadOnlyContext";
 import "./domEditOverlayTestMocks";
 import { DomEditOverlay } from "./DomEditOverlay";
+import { UNREADABLE_TRANSLATE } from "./plainTranslate";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -475,3 +476,32 @@ describe("DomEditOverlay onTextEditingChange", () => {
     expect(spies.onTextEditingChange.mock.calls).toEqual([[true], [false]]);
   });
 });
+
+describe("DomEditOverlay on a layer whose translate Studio can't read", () => {
+  it("refuses a drag and an arrow nudge out loud, and commits nothing", () => {
+    const { spies, overlay, selection } = fixture();
+    selection.element.style.setProperty("translate", "abs(10% - 50px) 0px");
+    fire(overlay.querySelector(BOX)!, "pointerdown");
+    const presses = [false, true, true].map(
+      (repeat) =>
+        new KeyboardEvent("keydown", {
+          key: "ArrowRight",
+          bubbles: true,
+          cancelable: true,
+          repeat,
+        }),
+    );
+    act(() => {
+      for (const press of presses) window.dispatchEvent(press);
+      vi.advanceTimersByTime(CANVAS_NUDGE_COMMIT_DEBOUNCE_MS + 10);
+    });
+    // One toast for the drag and one for the whole held arrow, whose every press is swallowed.
+    expect(spies.onBlockedMove.mock.calls).toEqual([
+      [selection, UNREADABLE_TRANSLATE],
+      [selection, UNREADABLE_TRANSLATE],
+    ]);
+    expect(presses.map((press) => press.defaultPrevented)).toEqual([true, true, true]);
+    expect(spies.onPathOffsetCommit).not.toHaveBeenCalled();
+    expect(selection.element.style.getPropertyValue("translate")).toBe("abs(10% - 50px) 0px");
+  });
+});

package/src/components/editor/previewReadOnlyContext.tsx

@@ -49,10 +49,12 @@ interface ManualEditCapabilities {
  */
 export function useManualEditDisabledFlags(
   capabilities: ManualEditCapabilities | null | undefined,
+  offset = { x: 0, y: 0 },
 ) {
   const { readOnly } = useContext(PreviewReadOnlyContext);
+  const unreadable = !Number.isFinite(offset.x) || !Number.isFinite(offset.y);
   return {
-    manualOffsetEditingDisabled: !capabilities?.canApplyManualOffset || readOnly,
+    manualOffsetEditingDisabled: !capabilities?.canApplyManualOffset || readOnly || unreadable,
     manualSizeEditingDisabled: !capabilities?.canApplyManualSize || readOnly,
     manualRotationEditingDisabled: !capabilities?.canApplyManualRotation || readOnly,
   };

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/propertyPanelTransformCommit.test.ts

@@ -1,9 +1,13 @@
 // @vitest-environment happy-dom
 
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
 import { describe, expect, it, vi } from "vitest";
+import { useManualEditDisabledFlags } from "./previewReadOnlyContext";
 import type { DomEditSelection } from "./domEditingTypes";
 import { GsapEditBlockedError } from "../../hooks/gsapEditOutcome";
 import { createTransformCommitHandlers } from "./propertyPanelTransformCommit";
+import { readMoveOffset, UNREADABLE_TRANSLATE } from "./plainTranslate";
 
 describe("createTransformCommitHandlers", () => {
   it.each([
@@ -55,3 +59,50 @@ describe("createTransformCommitHandlers", () => {
     expect(onSetManualRotation).not.toHaveBeenCalled();
   });
 });
+
+describe("the panel's position fields on a translate Studio can't read", () => {
+  it("are disabled", () => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+    const box = document.createElement("div");
+    box.style.setProperty("translate", "abs(10% - 50px) 30px");
+    const seen: boolean[] = [];
+    function Probe({ element }: { element: HTMLElement }) {
+      seen.push(
+        useManualEditDisabledFlags({ canApplyManualOffset: true } as never, readMoveOffset(element))
+          .manualOffsetEditingDisabled,
+      );
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe, { element: box })));
+    box.style.setProperty("translate", "40px 30px");
+    act(() => root.render(React.createElement(Probe, { element: box })));
+    act(() => root.unmount());
+    expect(seen).toEqual([true, false]);
+  });
+
+  it("commit nothing and say why", async () => {
+    const onSetManualOffset = vi.fn();
+    const showToast = vi.fn();
+    const box = document.createElement("div");
+    box.style.setProperty("translate", "abs(10% - 50px) 30px");
+    const element = { id: "box", selector: "#box", element: box } as unknown as DomEditSelection;
+    const handlers = createTransformCommitHandlers({
+      element,
+      styles: {},
+      hasGsapAnimation: false,
+      gsapAnimId: null,
+      gsapKeyframes: null,
+      currentPct: 0,
+      onCommitAnimatedProperty: undefined,
+      onAddKeyframe: undefined,
+      onSetManualOffset,
+      onSetManualSize: vi.fn(),
+      onSetManualRotation: vi.fn(),
+      showToast,
+    });
+    await handlers.commitManualOffset("y", "20px");
+    expect(onSetManualOffset).not.toHaveBeenCalled();
+    expect(showToast).toHaveBeenCalledWith(UNREADABLE_TRANSLATE);
+  });
+});

package/src/components/editor/propertyPanelTransformCommit.ts

@@ -1,6 +1,6 @@
 import type { DomEditSelection } from "./domEditingTypes";
 import { readStudioBoxSize } from "./manualEdits";
-import { readMoveOffset } from "./plainTranslate";
+import { readMoveOffset, UNREADABLE_TRANSLATE } from "./plainTranslate";
 import { parsePxMetricValue, type PropertyPanelProps } from "./propertyPanelHelpers";
 
 interface TransformCommitDeps {
@@ -75,6 +75,8 @@ export function createTransformCommitHandlers({
     )
       return;
     const current = readMoveOffset(element.element);
+    if (!Number.isFinite(current.x) || !Number.isFinite(current.y))
+      return void showToast?.(UNREADABLE_TRANSLATE);
     await Promise.resolve(
       onSetManualOffset(element, {
         x: axis === "x" ? parsed : current.x,

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

@@ -71,7 +71,9 @@ function HookHost({
   element,
   previewIframeRef,
   onApplyScope,
+  projectId = "proj",
 }: {
+  projectId?: string;
   onState: (state: ReturnType<typeof useColorGradingController>) => void;
   onSetAttributeLive: (attr: string, value: string | null) => void;
   element: DomEditSelection;
@@ -79,7 +81,7 @@ function HookHost({
   onApplyScope?: ApplyScope;
 }) {
   const state = useColorGradingController({
-    projectId: "proj",
+    projectId,
     element,
     previewIframeRef,
     onSetAttributeLive,
@@ -94,6 +96,7 @@ function renderHook(
   initialElement: DomEditSelection = makeElement(),
   previewIframeRef?: React.RefObject<HTMLIFrameElement | null>,
   onApplyScope?: ApplyScope,
+  projectId?: string,
 ) {
   const host = document.createElement("div");
   document.body.append(host);
@@ -108,6 +111,7 @@ function renderHook(
           element,
           previewIframeRef,
           onApplyScope,
+          projectId,
         }),
       );
     });
@@ -763,6 +767,37 @@ describe("useColorGradingController", () => {
     act(() => second.root.unmount());
     vi.unstubAllGlobals();
   });
+
+  it("keeps media metadata apart for 'p:a' + 'b.mp4' and 'p' + 'a:b.mp4'", async () => {
+    const video = (src: string) => {
+      const el = document.createElement("video");
+      el.setAttribute("src", src);
+      return el;
+    };
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ metadata: { kind: "video", color: { dynamicRange: "hdr" } } }),
+    } as unknown as Response);
+    vi.stubGlobal("fetch", fetchMock);
+    for (const [projectId, src] of [
+      ["p:a", "b.mp4"],
+      ["p", "a:b.mp4"],
+    ]) {
+      const { root } = renderHook(
+        vi.fn(),
+        makeElement({ element: video(src) }),
+        undefined,
+        undefined,
+        projectId,
+      );
+      await act(async () => {
+        await Promise.resolve();
+      });
+      act(() => root.unmount());
+    }
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    vi.unstubAllGlobals();
+  });
 });
 
 describe("useColorGradingController after the preview iframe is replaced", () => {

package/src/components/editor/useColorGradingController.ts

@@ -284,13 +284,13 @@ export function useColorGradingController({
   useEffect(() => {
     setMediaMetadata(null);
     if (!selectedAssetPath) return;
-    const cacheKey = `${projectId}:${selectedAssetPath}`;
+    const cacheKey = mediaMetadataUrl(projectId, selectedAssetPath);
     if (MEDIA_METADATA_CACHE.has(cacheKey)) {
       setMediaMetadata(MEDIA_METADATA_CACHE.get(cacheKey) ?? null);
       return;
     }
     const controller = new AbortController();
-    fetch(mediaMetadataUrl(projectId, selectedAssetPath), { signal: controller.signal })
+    fetch(cacheKey, { signal: controller.signal })
       .then(async (response) => {
         if (!response.ok) return { ok: false as const };
         const data: MediaMetadataResponse | null = await response.json();

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

@@ -46,6 +46,7 @@ function Harness({
     groupGestureRef: makeRef(null),
     blockedMoveRef: makeRef(null),
     onManualDragStartRef: makeRef(() => {}),
+    onBlockedMoveRef: makeRef(() => {}),
     onPathOffsetCommitRef: makeRef(onPathOffsetCommit),
     onGroupPathOffsetCommitRef: makeRef(async () => {}),
   });

package/src/components/editor/useDomEditNudge.ts

@@ -55,6 +55,7 @@ export interface UseDomEditNudgeParams {
   groupGestureRef: RefObject<GroupGestureState | null>;
   blockedMoveRef: RefObject<BlockedMoveState | null>;
   onManualDragStartRef: RefObject<(() => void) | undefined>;
+  onBlockedMoveRef: RefObject<(selection: DomEditSelection, reason?: string) => void>;
   onPathOffsetCommitRef: RefObject<
     (
       s: DomEditSelection,
@@ -179,7 +180,7 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
   // Build drag members for the current target set — the same member snapshot a
   // pointer drag starts from (startGesture / startGroupDrag), so the nudge
   // commit converts offsets → GSAP x/y with identical math.
-  const beginSession = (): NudgeSession | null => {
+  const beginSession = (event: KeyboardEvent): NudgeSession | "refused" | null => {
     const p = paramsRef.current;
     const groupItems = p.groupOverlayItemsRef.current;
     const isGroup = groupItems.length > 1;
@@ -192,7 +193,8 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
       const result = createManualOffsetDragMember({ ...target, gesture: "nudge" });
       if (!result.ok) {
         restoreManualOffsetDragMembers(members);
-        return null;
+        if (!event.repeat) p.onBlockedMoveRef.current(result.selection, result.reason);
+        return "refused";
       }
       members.push(result.member);
     }
@@ -207,7 +209,8 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
     if (shouldIgnoreNudgeKey(p, event)) return;
     const delta = resolveCanvasNudgeDelta(event);
     if (!delta) return;
-    const session = sessionRef.current ?? beginSession();
+    const session = sessionRef.current ?? beginSession(event);
+    if (session === "refused") return void event.preventDefault();
     if (!session) return;
     sessionRef.current = session;
     event.preventDefault();

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,