@hyperframes/studio 0.7.57 → 0.7.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.57",
+  "version": "0.7.58",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.57",
-    "@hyperframes/parsers": "0.7.57",
-    "@hyperframes/sdk": "0.7.57",
-    "@hyperframes/player": "0.7.57",
-    "@hyperframes/studio-server": "0.7.57"
+    "@hyperframes/core": "0.7.58",
+    "@hyperframes/parsers": "0.7.58",
+    "@hyperframes/player": "0.7.58",
+    "@hyperframes/sdk": "0.7.58",
+    "@hyperframes/studio-server": "0.7.58"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.57"
+    "@hyperframes/producer": "0.7.58"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -189,10 +189,10 @@ export function StudioApp() {
       }>,
       coalesceKey?: string,
       operation: TimelineMoveOperation = "timing",
+      coalesceMs?: number,
     ) => {
-      await persistTimelineMoveEditsAtomically(edits, coalesceKey, operation, {
-        handleTimelineGroupMove: timelineEditing.handleTimelineGroupMove,
-      });
+      const deps = { handleTimelineGroupMove: timelineEditing.handleTimelineGroupMove };
+      await persistTimelineMoveEditsAtomically(edits, coalesceKey, operation, deps, coalesceMs);
     },
     [timelineEditing.handleTimelineGroupMove],
   );

package/src/components/StudioFeedbackBar.tsx

@@ -180,9 +180,9 @@ export const StudioFeedbackBar = memo(function StudioFeedbackBar() {
         </>
       ) : (
         <>
-          <span className="text-neutral-500 flex-shrink-0">How's the Studio experience?</span>
+          <span className="text-neutral-500 flex-shrink-0">Recommend HyperFrames?</span>
           <div className="flex items-center gap-0.5">
-            {[1, 2, 3, 4, 5].map((n) => (
+            {Array.from({ length: 11 }, (_, n) => n).map((n) => (
               <button
                 key={n}
                 onClick={() => handleRating(n)}

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

@@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { installReactActEnvironment, makeSelection } from "../../hooks/domSelectionTestHarness";
 import { resolveZIndexEntries } from "../nle/PreviewOverlays";
 import { useElementLifecycleOps } from "../../hooks/useElementLifecycleOps";
+import { makeLifecycleOpsParams } from "../../hooks/elementLifecycleOpsTestUtils";
 import type { DomEditPatchBatch } from "../../hooks/domEditCommitTypes";
 import { CanvasContextMenu } from "./CanvasContextMenu";
 import type { ZOrderAction, ZOrderPatch } from "./canvasContextMenuZOrder";
@@ -102,9 +103,26 @@ describe("CanvasContextMenu — handler gating", () => {
 
     renderMenu({ selection: makeSelection("Target", el), onApplyZIndex: vi.fn() });
 
-    expect(zOrderButtons()).toHaveLength(4);
+    const buttons = zOrderButtons();
+    expect(buttons).toHaveLength(4);
     expect(hasDeleteItem()).toBe(false);
     expect(document.body.querySelector(".border-t")).toBeNull();
+
+    // Labels stay the exact industry-standard names (the icons add no text)...
+    expect(buttons.map((b) => b.textContent)).toEqual([
+      "Bring to front",
+      "Bring forward",
+      "Send backward",
+      "Send to back",
+    ]);
+    // ...and each item leads with a stroke icon that inherits the item's text
+    // color (currentColor), so the disabled muted tone applies to it too.
+    for (const button of buttons) {
+      const svg = button.firstElementChild;
+      expect(svg?.tagName.toLowerCase()).toBe("svg");
+      expect(svg?.getAttribute("stroke")).toBe("currentColor");
+      expect(svg?.getAttribute("aria-hidden")).toBe("true");
+    }
   });
 
   it("shows only Delete (no z-order items, no divider) when onApplyZIndex is absent", () => {
@@ -158,19 +176,14 @@ function renderCommitHook(captured: CapturedBatchCall[]) {
   type Commit = ReturnType<typeof useElementLifecycleOps>["handleDomZIndexReorderCommit"];
   let commit: Commit | undefined;
   function Harness() {
-    ({ handleDomZIndexReorderCommit: commit } = useElementLifecycleOps({
-      activeCompPath: "index.html",
-      showToast: vi.fn(),
-      writeProjectFile: vi.fn(async () => {}),
-      domEditSaveTimestampRef: { current: 0 },
-      editHistory: { recordEdit: vi.fn(async () => {}) },
-      projectIdRef: { current: null },
-      reloadPreview: vi.fn(),
-      clearDomSelection: vi.fn(),
-      commitDomEditPatchBatches: async (batches, options) => {
-        captured.push({ batches, options });
-      },
-    }));
+    ({ handleDomZIndexReorderCommit: commit } = useElementLifecycleOps(
+      makeLifecycleOpsParams({
+        commitDomEditPatchBatches: async (batches, options) => {
+          captured.push({ batches, options });
+          return { durable: true, allMatched: true, changed: true };
+        },
+      }),
+    ));
     return null;
   }
   const hookHost = document.createElement("div");

package/src/components/editor/CanvasContextMenu.tsx

@@ -50,8 +50,17 @@ interface CanvasContextMenuProps {
    * affected siblings). The menu does NOT touch the live DOM — wire to
    * handleDomZIndexReorderCommit, which applies the live styles itself
    * (see module-level wiring comment).
+   *
+   * `crossed` is the sibling a forward/backward step moved past, resolved from
+   * the SAME pre-mutation render order as the patches (null for front/back or
+   * when there is no neighbor). The host uses it to mirror the z action into a
+   * timeline lane move (resolveZMirrorLaneMove's crossedKey).
    */
-  onApplyZIndex?: (patches: ZOrderPatch[], action: ZOrderAction) => void;
+  onApplyZIndex?: (
+    patches: ZOrderPatch[],
+    action: ZOrderAction,
+    crossed: HTMLElement | null,
+  ) => void;
   /**
    * Called after a successful bring-forward / send-backward with the sibling
    * the target stepped over (resolved from the SAME pre-mutation state as the
@@ -70,10 +79,61 @@ interface CanvasContextMenuProps {
 
 type ZAction = "bring-forward" | "send-backward" | "bring-to-front" | "send-to-back";
 
+// Stacked-layer + arrow glyphs, one per z action (16px, stroke, currentColor —
+// matches the studio's inline-SVG conventions: fill="none", 1.2 stroke, round
+// caps/joins). Single actions show ONE layer diamond with the arrow stepping
+// one way; front/back show a TWO-diamond stack with the arrow piercing through
+// and beyond it. `paths` are the d attributes, drawn in order.
+const Z_ACTION_ICONS: Record<ZAction, string[]> = {
+  "bring-forward": [
+    "M3 11 L8 8.5 L13 11 L8 13.5 Z", // layer diamond (bottom)
+    "M8 8.5 L8 2", // arrow shaft up
+    "M5.5 4.5 L8 2 L10.5 4.5", // arrow head
+  ],
+  "send-backward": [
+    "M3 5 L8 2.5 L13 5 L8 7.5 Z", // layer diamond (top)
+    "M8 7.5 L8 14", // arrow shaft down
+    "M5.5 11.5 L8 14 L10.5 11.5", // arrow head
+  ],
+  "bring-to-front": [
+    "M3 9.5 L8 7 L13 9.5 L8 12 Z", // upper layer of the stack
+    "M3 12.5 L8 10 L13 12.5 L8 15 Z", // lower layer of the stack
+    "M8 12.5 L8 2", // arrow piercing up through/above the stack
+    "M5.5 4.5 L8 2 L10.5 4.5", // arrow head
+  ],
+  "send-to-back": [
+    "M3 4 L8 1.5 L13 4 L8 6.5 Z", // upper layer of the stack
+    "M3 7 L8 4.5 L13 7 L8 9.5 Z", // lower layer of the stack
+    "M8 3.5 L8 14", // arrow piercing down through/below the stack
+    "M5.5 11.5 L8 14 L10.5 11.5", // arrow head
+  ],
+};
+
+function ZActionIcon({ action }: { action: ZAction }) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="mr-2 shrink-0"
+      aria-hidden="true"
+    >
+      {Z_ACTION_ICONS[action].map((d) => (
+        <path key={d} d={d} />
+      ))}
+    </svg>
+  );
+}
+
 const Z_ACTIONS: Array<{ action: ZAction; label: string }> = [
+  { action: "bring-to-front", label: "Bring to front" },
   { action: "bring-forward", label: "Bring forward" },
   { action: "send-backward", label: "Send backward" },
-  { action: "bring-to-front", label: "Bring to front" },
   { action: "send-to-back", label: "Send to back" },
 ];
 
@@ -113,14 +173,16 @@ export const CanvasContextMenu = memo(function CanvasContextMenu({
     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.
-    const crossed = onZOrderCrossed ? resolveCrossedNeighbor(el, action) : null;
+    // 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);
     // 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
     // the PRE-change styles itself, both to capture true rollback values and
     // to detect a static position that needs persisting.
-    onApplyZIndex(patches, action);
+    onApplyZIndex(patches, action, crossed);
     if (crossed && onZOrderCrossed) onZOrderCrossed(crossed, action);
     onClose();
   }
@@ -185,7 +247,10 @@ export const CanvasContextMenu = memo(function CanvasContextMenu({
                 if (enabled) handleZAction(action);
               }}
             >
-              {label}
+              {/* Icon inherits the item's text color via currentColor, so the
+                  disabled muted tone applies to both icon and label. */}
+              <ZActionIcon action={action} />
+              <span>{label}</span>
             </button>
           );
         })}

package/src/components/editor/DomEditOverlay.tsx

@@ -103,6 +103,9 @@ interface DomEditOverlayProps {
     selection: DomEditSelection,
     patches: ZOrderPatch[],
     action: ZOrderAction,
+    /** Sibling a forward/backward step moved past (pre-mutation render order);
+     *  null for front/back. Feeds the timeline z-mirror's crossedKey. */
+    crossed: HTMLElement | null,
   ) => void;
 }
 
@@ -529,8 +532,8 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           }
           onApplyZIndex={
             onApplyZIndex
-              ? (patches, action) => {
-                  onApplyZIndex(contextMenu.sel, patches, action);
+              ? (patches, action, crossed) => {
+                  onApplyZIndex(contextMenu.sel, patches, action, crossed);
                 }
               : undefined
           }

package/src/components/editor/LayersPanel.tsx

@@ -14,8 +14,14 @@ import {
 } from "../../utils/studioHelpers";
 import { Layers } from "../../icons/SystemIcons";
 import { useLayerDrag, isLayerDraggable, type LayerReorderEvent } from "./useLayerDrag";
-import { computeReorderZValues, getElementZIndex } from "../../player/lib/layerOrdering";
+import { getVisibleLayers, sortLayersByZIndex } from "./layersPanelSort";
 import { deriveTimelineStoreKey } from "../../player/lib/timelineElementHelpers";
+import { resolveZOrderReposition } from "./canvasContextMenuZOrder";
+import { buildStableSelector } from "./domEditingDom";
+import { zReorderCoalesceKey } from "../../hooks/useElementLifecycleOps";
+import { useLayerReorderTimelineMirror } from "../nle/useCanvasZOrderTimelineMirror";
+import { runZLaneGesture } from "../nle/zLaneGesture";
+import { useLayerRevealOverride } from "./useLayerRevealOverride";
 
 const TAG_ICONS: Record<string, string> = {
   video: "Vi",
@@ -85,8 +91,13 @@ interface CollapsedState {
 // fallow-ignore-next-line complexity
 export const LayersPanel = memo(function LayersPanel() {
   const { previewIframeRef, activeCompPath, showToast } = useStudioShellContext();
-  const { refreshKey, compositionLoading, timelineElements } = useStudioPlaybackContext();
+  const { refreshKey, compositionLoading, timelineElements, isPlaying } =
+    useStudioPlaybackContext();
   const currentTime = usePlayerStore((s) => s.currentTime);
+  // Flashless z commits (canvas menu, timeline lane-drag z-sync) mutate iframe
+  // z-indexes with no reload and no refreshKey bump — while paused, nothing
+  // else re-collects, so the panel's z-sorted order would go stale.
+  const zEditVersion = usePlayerStore((s) => s.zEditVersion);
   const {
     domEditSelection,
     activeGroupElement,
@@ -100,6 +111,11 @@ export const LayersPanel = memo(function LayersPanel() {
   const [collapsed, setCollapsed] = useState<CollapsedState>({});
   const prevDocVersionRef = useRef(0);
   const scrollContainerRef = useRef<HTMLDivElement>(null);
+  const mirrorLayerReorderToTimeline = useLayerReorderTimelineMirror();
+  const { scheduleReveal } = useLayerRevealOverride({
+    isPlaying,
+    selectedElement: domEditSelection?.element ?? null,
+  });
 
   const isMasterView = !activeCompPath || activeCompPath === "index.html";
 
@@ -131,7 +147,7 @@ export const LayersPanel = memo(function LayersPanel() {
 
   useEffect(() => {
     collectLayers();
-  }, [collectLayers, refreshKey]);
+  }, [collectLayers, refreshKey, zEditVersion]);
 
   useEffect(() => {
     const iframe = previewIframeRef.current;
@@ -230,8 +246,13 @@ export const LayersPanel = memo(function LayersPanel() {
       if (!selection) return;
       applyDomSelection(selection);
       await seekToLayer(layer);
+      // Force-reveal AFTER the seek's runtime visibility sync has had a beat:
+      // a clip made active by the seek shows naturally and needs no override,
+      // so the reveal only touches nodes that REMAIN hidden (animation-parked
+      // opacity, non-clip display/visibility hides, hidden ancestors).
+      scheduleReveal(selection.element, 150);
     },
-    [resolveSelection, applyDomSelection, seekToLayer],
+    [resolveSelection, applyDomSelection, seekToLayer, scheduleReveal],
   );
 
   // Double-click a group row → drill into it; any other row → select it.
@@ -264,6 +285,7 @@ export const LayersPanel = memo(function LayersPanel() {
     setCollapsed((prev) => ({ ...prev, [key]: !prev[key] }));
   }, []);
 
+  // fallow-ignore-next-line complexity
   const handleReorder = useCallback(
     (event: LayerReorderEvent) => {
       const { siblingLayers, fromIndex, toIndex } = event;
@@ -271,29 +293,88 @@ export const LayersPanel = memo(function LayersPanel() {
       const [moved] = reordered.splice(fromIndex, 1);
       reordered.splice(toIndex, 0, moved);
 
-      const existingValues = siblingLayers.map((l) => getElementZIndex(l.element));
-      const zValues = computeReorderZValues(existingValues, fromIndex, toIndex);
-
-      const entries = reordered.map((layer, i) => ({
-        element: layer.element,
-        zIndex: zValues[i],
-        id: layer.id,
-        selector: layer.selector,
-        selectorIndex: layer.selectorIndex,
-        sourceFile: layer.sourceFile,
-        key: deriveTimelineStoreKey({
-          domId: layer.id,
-          selector: layer.selector,
-          selectorIndex: layer.selectorIndex,
-          sourceFile: layer.sourceFile,
-        }),
-      }));
-
-      // "layer-drag" keeps consecutive drops of the same sibling set coalescing
-      // into one undo step, without merging with a context-menu z action.
-      handleDomZIndexReorderCommit(entries, undefined, "layer-drag");
+      // Panel order is top-first (sortLayersByZIndex: z desc, later-DOM-first),
+      // so the desired RENDER order (bottom→top) is the reverse. The minimal
+      // resolver (shared with the canvas z-menu) then writes one between-z
+      // value when a strict gap exists, band-safe renumber otherwise — instead
+      // of the old computeReorderZValues stamp of every sibling.
+      const desiredBottomToTop = [...reordered].reverse();
+      const patches = resolveZOrderReposition(
+        moved.element,
+        desiredBottomToTop.map((l) => l.element),
+      );
+      if (!patches || patches.length === 0) return; // paint order unchanged
+
+      const layerByElement = new Map(siblingLayers.map((l) => [l.element, l]));
+      const entries: Array<{
+        element: HTMLElement;
+        zIndex: number;
+        id?: string;
+        selector?: string;
+        selectorIndex?: number;
+        sourceFile: string;
+        key?: string;
+      }> = [];
+      for (const patch of patches) {
+        // The renumber fallback can patch a painting sibling the panel didn't
+        // list (non-collected family member): derive its identity from the DOM
+        // node, exactly like the canvas menu's siblingZIndexEntry. Un-targetable
+        // nodes get a live-only style write (reverts on reload).
+        const layer = layerByElement.get(patch.element);
+        const id = layer?.id ?? (patch.element.id || undefined);
+        const selector = layer?.selector ?? buildStableSelector(patch.element);
+        if (!id && !selector) {
+          patch.element.style.zIndex = String(patch.zIndex);
+          continue;
+        }
+        const sourceFile = layer?.sourceFile ?? moved.sourceFile;
+        entries.push({
+          element: patch.element,
+          zIndex: patch.zIndex,
+          id,
+          selector,
+          selectorIndex: layer?.selectorIndex,
+          sourceFile,
+          key: deriveTimelineStoreKey({
+            domId: id,
+            selector,
+            selectorIndex: layer?.selectorIndex,
+            sourceFile,
+          }),
+        });
+      }
+      if (entries.length === 0) return;
+
+      // ONE undo entry for the whole gesture: the z persist and the timeline
+      // lane mirror below share this per-gesture-unique key (same contract as
+      // the canvas menu's wiring in PreviewOverlays).
+      const coalesceKey = zReorderCoalesceKey(entries, "layer-drag");
+      const desiredOrderKeys = desiredBottomToTop.map(
+        (l) =>
+          deriveTimelineStoreKey({
+            domId: l.id,
+            selector: l.selector,
+            selectorIndex: l.selectorIndex,
+            sourceFile: l.sourceFile,
+          }) ?? null,
+      );
+      const movedKey = deriveTimelineStoreKey({
+        domId: moved.id,
+        selector: moved.selector,
+        selectorIndex: moved.selectorIndex,
+        sourceFile: moved.sourceFile,
+      });
+      // One serialized z→lane transaction (shared queue with the canvas
+      // z-order menu): the mirror runs only after a DURABLE z persist, and
+      // rapid successive gestures cannot interleave phases — see
+      // runZLaneGesture.
+      runZLaneGesture({
+        commitZ: () => handleDomZIndexReorderCommit(entries, coalesceKey, "layer-drag"),
+        mirror: () =>
+          mirrorLayerReorderToTimeline({ selectionKey: movedKey, desiredOrderKeys, coalesceKey }),
+      }).catch(() => undefined);
     },
-    [handleDomZIndexReorderCommit],
+    [handleDomZIndexReorderCommit, mirrorLayerReorderToTimeline],
   );
 
   const selectedKey = domEditSelection ? getDomEditLayerKey(domEditSelection) : null;
@@ -436,76 +517,6 @@ export const LayersPanel = memo(function LayersPanel() {
   );
 });
 
-// ── Pure helpers ──────────────────────────────────────────────────────
-
-// fallow-ignore-next-line complexity
-export function sortLayersByZIndex(layers: DomEditLayerItem[]): DomEditLayerItem[] {
-  if (layers.length <= 1) return layers;
-
-  const minDepth = layers[0].depth;
-  for (let i = 1; i < layers.length; i++) {
-    if (layers[i].depth < minDepth) return layers;
-  }
-
-  const chunks: Array<{ root: DomEditLayerItem; children: DomEditLayerItem[]; domIndex: number }> =
-    [];
-
-  for (let i = 0; i < layers.length; i++) {
-    if (layers[i].depth === minDepth) {
-      const children: DomEditLayerItem[] = [];
-      let j = i + 1;
-      while (j < layers.length && layers[j].depth > minDepth) {
-        children.push(layers[j]);
-        j++;
-      }
-      chunks.push({ root: layers[i], children, domIndex: chunks.length });
-    }
-  }
-
-  if (chunks.length <= 1) {
-    if (chunks.length === 1 && chunks[0].children.length > 0) {
-      const sorted = sortLayersByZIndex(chunks[0].children);
-      return [chunks[0].root, ...sorted];
-    }
-    return layers;
-  }
-
-  chunks.sort((a, b) => {
-    const zA = getElementZIndex(a.root.element);
-    const zB = getElementZIndex(b.root.element);
-    if (zA !== zB) return zB - zA;
-    return b.domIndex - a.domIndex;
-  });
-
-  const result: DomEditLayerItem[] = [];
-  for (const chunk of chunks) {
-    result.push(chunk.root);
-    if (chunk.children.length > 0) {
-      result.push(...sortLayersByZIndex(chunk.children));
-    }
-  }
-  return result;
-}
-
-function getVisibleLayers(
-  layers: DomEditLayerItem[],
-  collapsed: CollapsedState,
-): DomEditLayerItem[] {
-  if (Object.keys(collapsed).length === 0) return layers;
-
-  const result: DomEditLayerItem[] = [];
-  let skipDepth = -1;
-
-  for (const layer of layers) {
-    if (skipDepth >= 0 && layer.depth > skipDepth) continue;
-    skipDepth = -1;
-
-    result.push(layer);
-
-    if (collapsed[layer.key] && layer.childCount > 0) {
-      skipDepth = layer.depth;
-    }
-  }
-
-  return result;
-}
+// The sort helper lives in layersPanelSort.ts (600-line studio cap);
+// re-exported so existing imports from "./LayersPanel" still resolve.
+export { sortLayersByZIndex } from "./layersPanelSort";

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

@@ -6,6 +6,7 @@ import {
   parseZIndex,
   resolveCrossedNeighbor,
   resolveZOrderChange,
+  resolveZOrderReposition,
   type ZOrderAction,
   type ZOrderPatch,
 } from "./canvasContextMenuZOrder";
@@ -617,3 +618,59 @@ describe("isZOrderActionEnabled", () => {
     }
   });
 });
+
+describe("resolveZOrderReposition (Layers-panel arbitrary drop)", () => {
+  it("multi-position jump with distinct z resolves to ONE between-z write", () => {
+    // Render order bottom→top today: target(1), a(3), b(5). Drop target between
+    // a and b → single write: z strictly between 3 and 5.
+    const { target, byId } = makeFamily("1", [
+      ["a", "3"],
+      ["b", "5"],
+    ]);
+    const patches = resolveZOrderReposition(target, [byId.a, target, byId.b]);
+    expect(patches).toEqual([{ element: target, zIndex: 4 }]);
+  });
+
+  it("jump to the very top writes one z above the previous top", () => {
+    const { target, byId } = makeFamily("1", [
+      ["a", "3"],
+      ["b", "5"],
+    ]);
+    const patches = resolveZOrderReposition(target, [byId.a, byId.b, target]);
+    expect(patches).toEqual([{ element: target, zIndex: 6 }]);
+  });
+
+  it("no-op drop (unchanged order) returns null", () => {
+    const { target, byId } = makeFamily("1", [
+      ["a", "3"],
+      ["b", "5"],
+    ]);
+    expect(resolveZOrderReposition(target, [target, byId.a, byId.b])).toBeNull();
+  });
+
+  it("tied z values renumber the scoped set minimally (band-safe)", () => {
+    const { target, byId } = makeFamily("2", [
+      ["a", "2"],
+      ["b", "2"],
+    ]);
+    // All tied at 2; DOM order target,a,b → render bottom→top target,a,b.
+    // Move target to the top: scoped renumber within the band.
+    const patches = resolveZOrderReposition(target, [byId.a, byId.b, target]);
+    expect(patches).not.toBeNull();
+    const z = new Map(patches!.map((p) => [(p.element as HTMLElement).id, p.zIndex]));
+    const zOf = (id: string) => z.get(id) ?? 2;
+    expect(zOf("a")).toBeLessThan(zOf("b"));
+    expect(zOf("b")).toBeLessThan(zOf("target"));
+  });
+
+  it("rejects elements that are not painting siblings of the target", () => {
+    const { target, byId } = makeFamily("1", [["a", "3"]]);
+    const stranger = makeEl("stranger", "2");
+    expect(resolveZOrderReposition(target, [stranger, target, byId.a])).toBeNull();
+  });
+
+  it("returns null for sets too small to reorder", () => {
+    const { target } = makeFamily("1", []);
+    expect(resolveZOrderReposition(target, [target])).toBeNull();
+  });
+});

package/src/components/editor/canvasContextMenuZOrder.ts

@@ -42,6 +42,7 @@
  */
 
 import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
+import { readLayerRevealPriorZ } from "../../player/lib/timelineElementHelpers";
 
 export type ZOrderAction = "bring-forward" | "send-backward" | "bring-to-front" | "send-to-back";
 
@@ -107,8 +108,11 @@ export function parseZIndex(value: string | null | undefined): number {
   return Number.isFinite(n) ? n : 0;
 }
 
-/** Read the effective z-index for an element (inline style preferred). */
+/** Read the effective z-index for an element (inline style preferred).
+ *  Reveal-lift transparent: an active Layers-panel lift reports the TRUE z. */
 export function readEffectiveZIndex(el: HTMLElement): number {
+  const prior = readLayerRevealPriorZ(el);
+  if (prior != null) return prior;
   const inline = el.style.zIndex;
   if (inline && inline !== "auto") return parseZIndex(inline);
   try {
@@ -439,6 +443,41 @@ export function resolveZOrderChange(
   return realizeOrder(order, desired, target, entries);
 }
 
+/**
+ * Realize an ARBITRARY repositioning of `target` within a scoped sibling set —
+ * the Layers-panel drag, which can jump several siblings in one drop, unlike
+ * the menu's four fixed actions. `desiredOrderBottomToTop` is the scoped set
+ * (target included at its new slot) in the intended render order. Reuses the
+ * menu's minimal-write realization (realizeOrder): one between-z write when a
+ * strict gap exists, band-safe scoped renumber otherwise — replacing the old
+ * LayersPanel computeReorderZValues path that stamped EVERY sibling.
+ *
+ * Null when nothing changes, the set is too small, or an element in the
+ * desired order is not actually a painting sibling of `target`.
+ */
+export function resolveZOrderReposition(
+  target: HTMLElement,
+  desiredOrderBottomToTop: readonly HTMLElement[],
+): ZOrderPatch[] | null {
+  const { entries } = getFamily(target);
+  if (entries.length < 2) return null;
+  const byElement = new Map(entries.map((entry) => [entry.element, entry]));
+  const desired: RenderEntry[] = [];
+  for (const el of desiredOrderBottomToTop) {
+    const entry = byElement.get(el);
+    if (!entry) return null;
+    desired.push(entry);
+  }
+  if (desired.length < 2 || !desired.some((entry) => entry.element === target)) return null;
+  const currentOrder = toRenderOrder(desired);
+  // A drop back into the same slot is a no-op. The menu actions guard this via
+  // their position checks before realizeOrder; an arbitrary reposition must
+  // compare the orders itself — realizeOrder would otherwise "normalize" an
+  // end-of-set target to a fresh z value it doesn't need.
+  if (currentOrder.every((entry, i) => entry.element === desired[i].element)) return null;
+  return realizeOrder(currentOrder, desired, target, entries);
+}
+
 /**
  * The sibling a forward/backward step crosses: the visible overlapping
  * neighbor directly above (bring-forward) or below (send-backward) the target