@hyperframes/studio 0.8.81 → 0.8.83

package/src/components/TimelineHistoryButtons.tsx

@@ -1,4 +1,4 @@
-import { useStudioShellContext } from "../contexts/StudioContext";
+import { useStudioShellContextOptional } from "../contexts/StudioContext";
 import { RotateCcw, RotateCw } from "../icons/SystemIcons";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { historyTooltipLabel } from "../utils/studioHelpers";
@@ -7,13 +7,14 @@ import { Tooltip } from "./ui";
 
 interface HistoryButtonProps {
   action: "undo" | "redo";
-  enabled: boolean;
+  can: boolean;
   label: string | undefined;
-  onClick: () => Promise<void> | void;
+  onClick: (() => Promise<void> | void) | undefined;
 }
 
-function HistoryButton({ action, enabled, label, onClick }: HistoryButtonProps) {
+function HistoryButton({ action, can, label, onClick }: HistoryButtonProps) {
   const Icon = action === "undo" ? RotateCcw : RotateCw;
+  const enabled = Boolean(onClick) && can;
   return (
     <Tooltip label={historyTooltipLabel(action, label)}>
       <button
@@ -23,7 +24,7 @@ function HistoryButton({ action, enabled, label, onClick }: HistoryButtonProps)
         className={enabled ? flatIdle : flatDisabled}
         onClick={() => {
           trackStudioEvent("toolbar_action", { action });
-          void onClick();
+          void onClick?.();
         }}
       >
         <Icon size={16} />
@@ -32,22 +33,33 @@ function HistoryButton({ action, enabled, label, onClick }: HistoryButtonProps)
   );
 }
 
-/** Undo and Redo, on the one edit-history path the shell already owns. */
-export function TimelineHistoryButtons() {
-  const { editHistory, handleUndo, handleRedo } = useStudioShellContext();
+export interface TimelineHistoryButtonsProps {
+  canUndo?: boolean;
+  canRedo?: boolean;
+  undoLabel?: string;
+  redoLabel?: string;
+  onUndo?: () => Promise<void> | void;
+  onRedo?: () => Promise<void> | void;
+}
+
+/** Undo and Redo: a host's props win, else the shell's edit history. */
+export function TimelineHistoryButtons(props: TimelineHistoryButtonsProps) {
+  const shell = useStudioShellContextOptional();
+  const onUndo = props.onUndo ?? shell?.handleUndo;
+  const onRedo = props.onRedo ?? shell?.handleRedo;
   return (
     <>
       <HistoryButton
         action="undo"
-        enabled={editHistory.canUndo}
-        label={editHistory.undoLabel}
-        onClick={handleUndo}
+        can={props.canUndo ?? shell?.editHistory.canUndo ?? false}
+        label={props.undoLabel ?? shell?.editHistory.undoLabel}
+        onClick={onUndo}
       />
       <HistoryButton
         action="redo"
-        enabled={editHistory.canRedo}
-        label={editHistory.redoLabel}
-        onClick={handleRedo}
+        can={props.canRedo ?? shell?.editHistory.canRedo ?? false}
+        label={props.redoLabel ?? shell?.editHistory.redoLabel}
+        onClick={onRedo}
       />
     </>
   );

package/src/components/TimelineToolbar.test.tsx

@@ -12,7 +12,7 @@ import { AudioMeterStrip } from "./nle/AudioMeterStrip";
 import { TimelineToolbar } from "./TimelineToolbar";
 
 vi.mock("../contexts/StudioContext", () => ({
-  useStudioShellContext: () => ({
+  useStudioShellContextOptional: () => ({
     previewIframeRef: { current: null },
     editHistory: { canUndo: false, canRedo: false },
     handleUndo: vi.fn(),
@@ -214,3 +214,11 @@ describe("TimelineToolbar audio meters", () => {
     }
   });
 });
+
+describe("TimelineToolbar add beat", () => {
+  it("shows Add beat by default, as Studio does", () => {
+    const { host, root } = renderToolbar();
+    expect(host.querySelector('button[aria-label="Add beat at playhead"]')).not.toBeNull();
+    act(() => root.unmount());
+  });
+});

package/src/components/TimelineToolbar.tsx

@@ -19,7 +19,7 @@ import { Tooltip } from "./ui";
 import { AudioMetersIcon } from "./icons/AudioMetersIcon";
 import { RippleEditIcon } from "./icons/RippleEditIcon";
 import { flatActive, flatBtn, flatDisabled, flatIdle } from "./timelineToolbarStyles";
-import { TimelineHistoryButtons } from "./TimelineHistoryButtons";
+import { TimelineHistoryButtons, type TimelineHistoryButtonsProps } from "./TimelineHistoryButtons";
 import { Scissors } from "../icons/SystemIcons";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "./editor/domEditingTypes";
@@ -33,9 +33,11 @@ interface DomEditSessionSlice extends EnableKeyframesSession {
   selectedGsapAnimations: GsapAnimation[];
 }
 
-interface TimelineToolbarProps {
+export interface TimelineToolbarProps {
   domEditSession?: DomEditSessionSlice;
   onSplitElement?: (element: TimelineElement, splitTime: number) => void;
+  history?: TimelineHistoryButtonsProps;
+  showAddBeat?: boolean;
 }
 
 interface KeyframeToggleState {
@@ -127,7 +129,12 @@ function useKeyframeToggle(session?: DomEditSessionSlice) {
 }
 
 // fallow-ignore-next-line complexity
-export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineToolbarProps) {
+export function TimelineToolbar({
+  domEditSession,
+  onSplitElement,
+  history,
+  showAddBeat = true,
+}: TimelineToolbarProps) {
   const activeTool = usePlayerStore((s) => s.activeTool);
   const setActiveTool = usePlayerStore((s) => s.setActiveTool);
   const timelineSnapEnabled = usePlayerStore((s) => s.timelineSnapEnabled);
@@ -195,7 +202,7 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
     <div className="border-b border-neutral-800/60">
       <div className="flex items-center justify-between px-2 py-0.5">
         <div className="flex items-center gap-0.5">
-          <TimelineHistoryButtons />
+          <TimelineHistoryButtons {...history} />
           <Tooltip label="Selection tool (V)">
             <button
               type="button"
@@ -416,7 +423,8 @@ export function TimelineToolbar({ domEditSession, onSplitElement }: TimelineTool
               );
             })()}
           {(() => {
-            // Always rendered (CapCut-style): before beat analysis loads (or when
+            if (!showAddBeat) return null;
+            // Rendered whenever shown (CapCut-style): before beat analysis loads (or when
             // the project has no analyzed music) the button fades to a disabled
             // state instead of unmounting, so the toolbar layout never shifts.
             const canAdd = beatAnalysisReady && canAddBeatAt(currentTime);

package/src/components/editor/BlockParamsPanel.tsx

@@ -3,6 +3,7 @@ import type { BlockParam } from "@hyperframes/core/registry";
 import { useFileManagerContextOptional } from "../../contexts/FileManagerContext";
 import { useStudioPlaybackContext } from "../../contexts/StudioContext";
 import { trackBlockParamCommit } from "../../telemetry/events";
+import { serializeStudioFileMutation } from "../../utils/studioFileMutationCoordinator";
 
 interface BlockParamsPanelProps {
   blockName: string;
@@ -77,7 +78,11 @@ export const BlockParamsPanel = memo(function BlockParamsPanel({
           trackBlockParamCommit({ tone: "error", blockName, key });
           return;
         }
-        await fileManager.writeProjectFile(compositionPath, content.replace(matcher, nextValue));
+        await fileManager.writeProjectFile(
+          compositionPath,
+          content.replace(matcher, nextValue),
+          content,
+        );
         appliedRef.current[key] = nextValue;
         setCommitState({ tone: "saved" });
         trackBlockParamCommit({ tone: "saved", blockName, key });
@@ -90,16 +95,15 @@ export const BlockParamsPanel = memo(function BlockParamsPanel({
     [fileManager, compositionPath, setRefreshKey, blockName],
   );
 
-  // Commits are serialized: two params committing concurrently would each
-  // read-modify-write the same file and the second write would drop the first.
-  const commitChainRef = useRef<Promise<void>>(Promise.resolve());
+  // Commits join the file's queue: two read-modify-writes of one file must not interleave.
   const commitParam = useCallback(
-    (key: string, nextValue: string) => {
-      const run = commitChainRef.current.then(() => commitParamNow(key, nextValue));
-      commitChainRef.current = run.catch(() => undefined);
-      return run;
-    },
-    [commitParamNow],
+    (key: string, nextValue: string) =>
+      fileManager
+        ? serializeStudioFileMutation(fileManager.writeProjectFile, compositionPath, () =>
+            commitParamNow(key, nextValue),
+          )
+        : Promise.resolve(),
+    [commitParamNow, compositionPath, fileManager],
   );
 
   const handleChange = useCallback(

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 "../nle/PreviewOverlays";
+import { resolveZIndexEntries } from "./ConnectedDomEditOverlay";
 import { useElementLifecycleOps } from "../../hooks/useElementLifecycleOps";
 import { makeLifecycleOpsParams } from "../../hooks/elementLifecycleOpsTestUtils";
 import type { DomEditPatchBatch } from "../../hooks/domEditCommitTypes";
@@ -138,7 +138,7 @@ describe("CanvasContextMenu — handler gating", () => {
   });
 });
 
-// ── Menu z-action → commit path (wired the way PreviewOverlays wires the app) ──
+// ── Menu z-action → commit path (wired the way ConnectedDomEditOverlay wires the app) ──
 
 function pressMenuItem(label: string) {
   const button = zOrderButtons().find((b) => b.textContent === label);
@@ -200,7 +200,7 @@ describe("CanvasContextMenu — z-action commit path", () => {
     const captured: CapturedBatchCall[] = [];
     const { commit, cleanup } = renderCommitHook(captured);
 
-    // Wire onApplyZIndex the way the app does (PreviewOverlays → the commit
+    // Wire onApplyZIndex the way the app does (ConnectedDomEditOverlay → the commit
     // hook), asserting the menu has NOT touched the DOM when it fires — the
     // hook must capture true pre-change styles for its rollback.
     const stylesAtApply: Array<{ zIndex: string; position: string }> = [];

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. PreviewOverlays.tsx builds the per-patch PatchTargets (the selected
+ * path. ConnectedDomEditOverlay.tsx 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.

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

@@ -0,0 +1,163 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { getPreviewState, iframeRef } from "../nle/PreviewOverlaysTestMocks";
+import { PreviewOverlays } from "../nle/PreviewOverlays";
+import { ConnectedDomEditOverlay } from "./ConnectedDomEditOverlay";
+
+// Overlay prop -> session handler, as PreviewOverlays wired DomEditOverlay itself.
+const WIRING = {
+  onCanvasMouseDown: "handlePreviewCanvasMouseDown",
+  onCanvasPointerMove: "handlePreviewCanvasPointerMove",
+  onCanvasPointerLeave: "handlePreviewCanvasPointerLeave",
+  onSelectionChange: "applyDomSelection",
+  onBlockedMove: "handleBlockedDomMove",
+  onManualDragStart: "handleDomManualDragStart",
+  onPathOffsetCommit: "handleDomPathOffsetCommit",
+  onGroupPathOffsetCommit: "handleDomGroupPathOffsetCommit",
+  onBoxSizeCommit: "handleDomBoxSizeCommit",
+  onRotationCommit: "handleDomRotationCommit",
+  onStyleCommit: "handleDomStyleCommit",
+  onDeleteSelection: "handleDomEditElementDelete",
+  onMarqueeSelect: "applyMarqueeSelection",
+} as const;
+
+const ctx = vi.hoisted(() => ({
+  overlayProps: null as Record<string, unknown> | null,
+  actions: {} as Record<string, unknown>,
+  selection: {
+    domEditHoverSelection: { label: "hover" },
+    domEditSelection: { label: "selected" },
+    domEditGroupSelections: [{ label: "member" }],
+  },
+}));
+
+vi.mock("../../contexts/DomEditContext", () => ({
+  useDomEditSelectionContext: () => ctx.selection,
+  useDomEditActionsContext: () => ctx.actions,
+}));
+vi.mock("./DomEditOverlay", () => ({
+  DomEditOverlay: (props: Record<string, unknown>) => {
+    ctx.overlayProps = props;
+    return null;
+  },
+}));
+vi.mock("./TopologyLens", () => ({ TopologyLens: () => null }));
+vi.mock("./MotionPathOverlay", () => ({ MotionPathOverlay: () => null }));
+vi.mock("./SnapToolbar", () => ({ SnapToolbar: () => null }));
+vi.mock("./GridOverlay", () => ({ GridOverlay: () => null }));
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root;
+
+function mount(node: React.ReactNode): Record<string, unknown> {
+  ctx.actions = {
+    previewIframeRef: iframeRef,
+    handleDomZIndexReorderCommit: vi.fn(() => Promise.resolve(undefined)),
+  };
+  for (const name of Object.values(WIRING)) ctx.actions[name] = vi.fn();
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() => root.render(node));
+  return ctx.overlayProps!;
+}
+
+afterEach(() => {
+  act(() => root.unmount());
+  ctx.overlayProps = null;
+  getPreviewState().isPlaying = false;
+  document.body.replaceChildren();
+});
+
+describe("ConnectedDomEditOverlay", () => {
+  it("is what PreviewOverlays renders, with every handler from the session", () => {
+    const props = mount(
+      <PreviewOverlays
+        shouldShowMotionPath={false}
+        shouldShowSelectedDomBounds={true}
+        recordingState={"idle" as never}
+        onToggleRecording={vi.fn()}
+      />,
+    );
+    // The overlay never read these, so the connected wrapper does not pass them.
+    expect(props).not.toHaveProperty("recordingState");
+    expect(props).not.toHaveProperty("onToggleRecording");
+    for (const [prop, handler] of Object.entries(WIRING)) {
+      expect(props[prop], prop).toBe(ctx.actions[handler]);
+    }
+    expect(props).toMatchObject({
+      iframeRef,
+      activeCompositionPath: "index.html",
+      hoverSelection: ctx.selection.domEditHoverSelection,
+      selection: ctx.selection.domEditSelection,
+      groupSelections: ctx.selection.domEditGroupSelections,
+      allowCanvasMovement: true,
+      canvasInput: undefined,
+      onTextEditingChange: undefined,
+    });
+  });
+
+  it("shows no hover box while playback runs", () => {
+    getPreviewState().isPlaying = true;
+    const props = mount(
+      <PreviewOverlays shouldShowMotionPath={false} shouldShowSelectedDomBounds={true} />,
+    );
+    expect(props.hoverSelection).toBeNull();
+    expect(props.selection).toBe(ctx.selection.domEditSelection);
+  });
+
+  it("hides the selection and stops movement while a gesture records", () => {
+    const props = mount(
+      <PreviewOverlays
+        shouldShowMotionPath={false}
+        shouldShowSelectedDomBounds={false}
+        isGestureRecording={true}
+      />,
+    );
+    expect(props).toMatchObject({
+      selection: null,
+      groupSelections: [],
+      allowCanvasMovement: false,
+    });
+  });
+
+  it("persists a z-order change through the session's reorder commit", () => {
+    const props = mount(
+      <PreviewOverlays shouldShowMotionPath={false} shouldShowSelectedDomBounds={true} />,
+    );
+    const element = document.createElement("div");
+    element.id = "card";
+    const sel = { element, id: "card", selector: "#card", sourceFile: "index.html" };
+    const apply = props.onApplyZIndex as (...args: unknown[]) => void;
+    act(() => apply(sel, [{ element, zIndex: 4 }], "bring-forward", null));
+    expect(ctx.actions.handleDomZIndexReorderCommit).toHaveBeenCalledWith(
+      [expect.objectContaining({ element, zIndex: 4, id: "card", sourceFile: "index.html" })],
+      expect.stringContaining("z-reorder:bring-forward"),
+      "bring-forward",
+    );
+  });
+
+  it("passes a host's canvas input, text-editing listener and hover gate to the overlay", () => {
+    const onTextEditingChange = vi.fn();
+    const props = mount(
+      <ConnectedDomEditOverlay
+        activeCompositionPath={null}
+        showHoverSelection={false}
+        shouldShowSelectedDomBounds={true}
+        canvasInput="host"
+        onTextEditingChange={onTextEditingChange}
+      />,
+    );
+    expect(props).toMatchObject({
+      canvasInput: "host",
+      onTextEditingChange,
+      hoverSelection: null,
+      selection: ctx.selection.domEditSelection,
+      iframeRef,
+    });
+  });
+});

package/src/components/editor/ConnectedDomEditOverlay.tsx

@@ -0,0 +1,206 @@
+import type { ComponentProps } from "react";
+import { DomEditOverlay } from "./DomEditOverlay";
+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";
+
+type HostInputProps = Pick<
+  ComponentProps<typeof DomEditOverlay>,
+  "canvasInput" | "onSelectionBoxClick"
+>;
+
+export interface ConnectedDomEditOverlayProps extends HostInputProps {
+  activeCompositionPath: string | null;
+  showHoverSelection: boolean;
+  shouldShowSelectedDomBounds: boolean;
+  isGestureRecording?: boolean;
+  /** True when an in-place text edit opens its caret, false when it ends or unmounts. */
+  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({
+  activeCompositionPath,
+  showHoverSelection,
+  shouldShowSelectedDomBounds,
+  isGestureRecording,
+  canvasInput,
+  onTextEditingChange,
+  onSelectionBoxClick,
+}: ConnectedDomEditOverlayProps) {
+  const { domEditHoverSelection, domEditSelection, domEditGroupSelections } =
+    useDomEditSelectionContext();
+  const {
+    previewIframeRef,
+    handlePreviewCanvasMouseDown,
+    handlePreviewCanvasPointerMove,
+    handlePreviewCanvasPointerLeave,
+    applyDomSelection,
+    handleBlockedDomMove,
+    handleDomManualDragStart,
+    handleDomPathOffsetCommit,
+    handleDomGroupPathOffsetCommit,
+    handleDomBoxSizeCommit,
+    handleDomRotationCommit,
+    handleDomStyleCommit,
+    applyMarqueeSelection,
+    handleDomEditElementDelete,
+    handleDomZIndexReorderCommit,
+  } = useDomEditActionsContext();
+  const mirrorZOrderToTimeline = useCanvasZOrderTimelineMirror();
+
+  return (
+    <DomEditOverlay
+      iframeRef={previewIframeRef}
+      activeCompositionPath={activeCompositionPath}
+      hoverSelection={showHoverSelection ? domEditHoverSelection : null}
+      selection={shouldShowSelectedDomBounds ? domEditSelection : null}
+      groupSelections={shouldShowSelectedDomBounds ? domEditGroupSelections : []}
+      allowCanvasMovement={!isGestureRecording}
+      canvasInput={canvasInput}
+      onTextEditingChange={onTextEditingChange}
+      onSelectionBoxClick={onSelectionBoxClick}
+      onCanvasMouseDown={handlePreviewCanvasMouseDown}
+      onCanvasPointerMove={handlePreviewCanvasPointerMove}
+      onCanvasPointerLeave={handlePreviewCanvasPointerLeave}
+      onSelectionChange={applyDomSelection}
+      onBlockedMove={handleBlockedDomMove}
+      onManualDragStart={handleDomManualDragStart}
+      onPathOffsetCommit={handleDomPathOffsetCommit}
+      onGroupPathOffsetCommit={handleDomGroupPathOffsetCommit}
+      onBoxSizeCommit={handleDomBoxSizeCommit}
+      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);
+      }}
+      onMarqueeSelect={applyMarqueeSelection}
+    />
+  );
+}