feat(studio): three-way z sync — layers drags mirror timeline lanes, panel tracks live z edits

Completes the layers/canvas/timeline sync triangle: the Layers panel was the
one surface whose reorders never reached the timeline, and the one that went
stale when the other two wrote z flashlessly.

- Layers drag -> minimal z + equal-jump lane mirror. handleReorder now uses
  the canvas menu's realization core via resolveZOrderReposition (one
  between-z write when a strict gap exists, band-safe scoped renumber
  otherwise) instead of computeReorderZValues' all-sibling stamp — that
  helper is deleted, completing the #2347 unification follow-up. The drop
  then mirrors into a timeline lane move through the same machinery as the
  canvas menu (new resolveRepositionLaneMove: the clip lands on a free lane
  strictly between its NEW paint neighbors' lanes — nearest clip siblings in
  the desired render order, decorations skipped — else a track insert at
  that boundary; audio zone never crossed). Both writes share one
  per-gesture zReorderCoalesceKey with an unbounded fold window, so a drag
  is exactly ONE undo entry; useCanvasZOrderTimelineMirror's plumbing is
  factored into useMirrorLaneMoveCommit and reused by the new
  useLayerReorderTimelineMirror. A same-slot drop is a hard no-op (new
  order-equality guard in resolveZOrderReposition).
- Panel staleness fix: flashless z commits (skipReload) reload nothing and
  bump no refreshKey, so the panel's z-sorted order went stale while paused.
  handleDomZIndexReorderCommit now bumps a store zEditVersion on apply AND
  rollback; the panel re-collects on it. Verified live: the panel re-sorts
  the instant a drag commits and again on undo.
- Layer click reveal (useLayerRevealOverride): clicking a layer that stays
  hidden at the current frame (animation-parked opacity, non-clip
  display/visibility hides, hidden ancestors) temporarily forces the chain
  visible with live inline styles — exact priors restored on deselect, on
  another reveal, on play, and on unmount; never persisted (file diff == 0
  verified live). Clips keep the existing seek-into-window behavior; the
  override applies on a short defer so a seek-revealed clip needs none.
- layerOrdering's unused hasExplicitZIndex probe (zero callers) removed.

Live-verified on a bed copy: a 2-position layers drag wrote exactly one
element (z 6->23 + data-track-index 15->2), the timeline lane moved without
a reload, and a single Cmd+Z restored the file byte-identically.

Author: ukimsanov

packages/studio/src/components/editor/LayersPanel.tsx

@@ -14,8 +14,13 @@ import {
 } from "../../utils/studioHelpers";
 import { Layers } from "../../icons/SystemIcons";
 import { useLayerDrag, isLayerDraggable, type LayerReorderEvent } from "./useLayerDrag";
-import { computeReorderZValues, getElementZIndex } from "../../player/lib/layerOrdering";
+import { getElementZIndex } from "../../player/lib/layerOrdering";
 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 { useLayerRevealOverride } from "./useLayerRevealOverride";
 
 const TAG_ICONS: Record<string, string> = {
   video: "Vi",
@@ -85,8 +90,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 +110,15 @@ export const LayersPanel = memo(function LayersPanel() {
   const [collapsed, setCollapsed] = useState<CollapsedState>({});
   const prevDocVersionRef = useRef(0);
   const scrollContainerRef = useRef<HTMLDivElement>(null);
+  const mirrorLayerReorderToTimeline = useLayerReorderTimelineMirror();
+  const { reveal, restoreReveal, revealedBase } = useLayerRevealOverride({ isPlaying });
+
+  // Drop the temporary reveal when the selection leaves the revealed layer
+  // (deselect, or a selection made anywhere else in the studio).
+  useEffect(() => {
+    const base = revealedBase();
+    if (base && domEditSelection?.element !== base) restoreReveal();
+  }, [domEditSelection, revealedBase, restoreReveal]);
 
   const isMasterView = !activeCompPath || activeCompPath === "index.html";
 
@@ -131,7 +150,7 @@ export const LayersPanel = memo(function LayersPanel() {
 
   useEffect(() => {
     collectLayers();
-  }, [collectLayers, refreshKey]);
+  }, [collectLayers, refreshKey, zEditVersion]);
 
   useEffect(() => {
     const iframe = previewIframeRef.current;
@@ -224,15 +243,25 @@ export const LayersPanel = memo(function LayersPanel() {
     [currentTime, resolveSelection, timelineElements],
   );
 
+  const revealTimerRef = useRef(0);
   const handleSelectLayer = useCallback(
     async (layer: DomEditLayerItem) => {
       const selection = await resolveSelection(layer);
       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).
+      window.clearTimeout(revealTimerRef.current);
+      revealTimerRef.current = window.setTimeout(() => {
+        if (selection.element.isConnected) reveal(selection.element);
+      }, 150);
     },
-    [resolveSelection, applyDomSelection, seekToLayer],
+    [resolveSelection, applyDomSelection, seekToLayer, reveal],
   );
+  useEffect(() => () => window.clearTimeout(revealTimerRef.current), []);
 
   // Double-click a group row → drill into it; any other row → select it.
   const handleLayerDoubleClick = useCallback(
@@ -264,36 +293,86 @@ 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;
       const reordered = [...siblingLayers];
       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 = [];
+      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,
+      });
+      // Mirror AFTER the z persist resolves — the two writes patch the same
+      // source file, so they are serialized (see useCanvasZOrderTimelineMirror).
+      handleDomZIndexReorderCommit(entries, coalesceKey, "layer-drag")
+        .then(() =>
+          mirrorLayerReorderToTimeline({ selectionKey: movedKey, desiredOrderKeys, coalesceKey }),
+        )
+        .catch(() => undefined);
     },
-    [handleDomZIndexReorderCommit],
+    [handleDomZIndexReorderCommit, mirrorLayerReorderToTimeline],
   );
 
   const selectedKey = domEditSelection ? getDomEditLayerKey(domEditSelection) : null;

packages/studio/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();
+  });
+});

packages/studio/src/components/editor/canvasContextMenuZOrder.ts

@@ -439,6 +439,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