@hyperframes/studio 0.7.56 → 0.7.58

package/src/components/editor/LayersPanel.tsx

@@ -14,7 +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",
@@ -84,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,
@@ -99,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";
 
@@ -130,7 +147,7 @@ export const LayersPanel = memo(function LayersPanel() {
 
   useEffect(() => {
     collectLayers();
-  }, [collectLayers, refreshKey]);
+  }, [collectLayers, refreshKey, zEditVersion]);
 
   useEffect(() => {
     const iframe = previewIframeRef.current;
@@ -229,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.
@@ -263,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;
@@ -270,21 +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,
-      }));
-
-      handleDomZIndexReorderCommit(entries);
+      // 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;
@@ -427,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

@@ -1,9 +1,12 @@
 // @vitest-environment jsdom
 import { describe, expect, it } from "vitest";
 import {
+  isElementVisibleForZOrder,
   isZOrderActionEnabled,
   parseZIndex,
+  resolveCrossedNeighbor,
   resolveZOrderChange,
+  resolveZOrderReposition,
   type ZOrderAction,
   type ZOrderPatch,
 } from "./canvasContextMenuZOrder";
@@ -48,8 +51,12 @@ function makeFamily(
 }
 
 /** Resolve a z-order change and assert it produced patches (fails otherwise). */
-function resolveZOrderPatches(target: HTMLElement, action: ZOrderAction): ZOrderPatch[] {
-  const patches = resolveZOrderChange(target, action);
+function resolveZOrderPatches(
+  target: HTMLElement,
+  action: ZOrderAction,
+  options?: { isVisible?: (el: HTMLElement) => boolean },
+): ZOrderPatch[] {
+  const patches = resolveZOrderChange(target, action, options);
   expect(patches).not.toBeNull();
   if (!patches) throw new Error("expected z-order patches");
   return patches;
@@ -375,6 +382,27 @@ describe("resolveZOrderChange – excludes non-painting siblings", () => {
     expect(order.indexOf("target")).toBeLessThan(order.indexOf("a"));
   });
 
+  it("ignores <template>/<noscript> siblings in the family", () => {
+    // A renumber fallback once wrote z-index/position into <template> source
+    // markup because templates entered the sibling family. They never paint —
+    // exclude them like audio/script/style.
+    const parent = document.createElement("div");
+    const a = makeEl("a", "0");
+    const template = document.createElement("template");
+    template.style.zIndex = "2";
+    const noscript = document.createElement("noscript");
+    const target = makeEl("target", "0");
+    parent.append(a, template, noscript, target);
+
+    const patches = resolveZOrderPatches(target, "send-to-back");
+    for (const p of patches) {
+      expect(p.element).not.toBe(template);
+      expect(p.element).not.toBe(noscript);
+    }
+    const order = renderOrderIds(parent, { a, target }, patches);
+    expect(order.indexOf("target")).toBeLessThan(order.indexOf("a"));
+  });
+
   it("a lone painting element beside only non-painting siblings has no family → null", () => {
     const parent = document.createElement("div");
     const target = makeEl("target", "1");
@@ -392,6 +420,163 @@ describe("resolveZOrderChange – excludes non-painting siblings", () => {
   });
 });
 
+// ── visibility scoping (forward/backward step over VISIBLE siblings only) ──────
+//
+// The visibility probe is injectable (ZOrderResolveOptions.isVisible) exactly
+// like rect reading is stubbable — these tests drive the scoping logic with a
+// stub, without a real style engine.
+
+describe("resolveZOrderChange – visibility scoping (injectable stub)", () => {
+  /** Probe that hides exactly the given elements. */
+  function hiding(...hidden: HTMLElement[]) {
+    return { isVisible: (el: HTMLElement) => !hidden.includes(el) };
+  }
+
+  it("bring-forward steps over the next VISIBLE sibling, ignoring an invisible z-neighbor", () => {
+    // Render order: target(1), hidden(2), vis(3). The nearest z-neighbor above
+    // is invisible at the current frame — forward must land the target above
+    // `vis` (the next VISIBLE overlapping sibling), leaving `hidden` untouched.
+    const { target, byId } = makeFamily("1", [
+      ["hidden", "2"],
+      ["vis", "3"],
+    ]);
+    const patches = resolveZOrderPatches(target, "bring-forward", hiding(byId.hidden!));
+    expect(patches).toHaveLength(1);
+    expect(patchFor(patches, byId, "target")?.zIndex).toBe(4);
+    expect(patchFor(patches, byId, "hidden")).toBeUndefined();
+  });
+
+  it("send-backward steps below the next VISIBLE sibling, ignoring an invisible z-neighbor", () => {
+    // Render order: vis(1), hidden(2), target(3). Backward must drop the target
+    // below `vis`, not merely below the invisible `hidden`.
+    const { target, byId } = makeFamily("3", [
+      ["vis", "1"],
+      ["hidden", "2"],
+    ]);
+    const patches = resolveZOrderPatches(target, "send-backward", hiding(byId.hidden!));
+    expect(patches).toHaveLength(1);
+    expect(patchFor(patches, byId, "target")?.zIndex).toBe(0);
+    expect(patchFor(patches, byId, "hidden")).toBeUndefined();
+  });
+
+  it("forward/backward are no-ops when every overlapping sibling is invisible", () => {
+    const { target, byId } = makeFamily("1", [["hidden", "2"]]);
+    const opts = hiding(byId.hidden!);
+    expect(resolveZOrderChange(target, "bring-forward", opts)).toBeNull();
+    expect(resolveZOrderChange(target, "send-backward", opts)).toBeNull();
+  });
+
+  it("bring-to-front / send-to-back keep the FULL painting family (invisible siblings included)", () => {
+    // Unchanged semantics: front/back operate across all siblings, so an
+    // invisible sibling still counts and the actions stay meaningful.
+    const { target, byId } = makeFamily("1", [["hidden", "2"]]);
+    const opts = hiding(byId.hidden!);
+    const patches = resolveZOrderPatches(target, "bring-to-front", opts);
+    expect(patchFor(patches, byId, "target")?.zIndex).toBe(3);
+    expect(resolveZOrderChange(target, "send-to-back", opts)).toBeNull(); // already bottom
+  });
+
+  it("the target itself is retained even when the probe reports it invisible", () => {
+    const { target, byId } = makeFamily("1", [["vis", "2"]]);
+    const patches = resolveZOrderPatches(target, "bring-forward", hiding(target));
+    expect(patchFor(patches, byId, "target")?.zIndex).toBe(3);
+  });
+
+  it("isZOrderActionEnabled matches the resolver under the same visibility scope", () => {
+    const { target, byId } = makeFamily("1", [["hidden", "2"]]);
+    const opts = hiding(byId.hidden!);
+    // Forward/backward: scoped set collapses to the target alone → disabled.
+    expect(isZOrderActionEnabled(target, "bring-forward", opts)).toBe(false);
+    expect(isZOrderActionEnabled(target, "send-backward", opts)).toBe(false);
+    // Front/back: full family → enabled exactly where the resolver acts.
+    expect(isZOrderActionEnabled(target, "bring-to-front", opts)).toBe(true);
+    expect(isZOrderActionEnabled(target, "send-to-back", opts)).toBe(false);
+  });
+});
+
+// ── default visibility probe (element-level computed style) ───────────────────
+
+describe("isElementVisibleForZOrder – default probe", () => {
+  function attachedEl(style: Partial<CSSStyleDeclaration> = {}): HTMLElement {
+    const el = document.createElement("div");
+    Object.assign(el.style, style);
+    document.body.appendChild(el);
+    return el;
+  }
+
+  it("treats display:none / visibility:hidden / opacity≈0 as invisible", () => {
+    expect(isElementVisibleForZOrder(attachedEl({ display: "none" }))).toBe(false);
+    expect(isElementVisibleForZOrder(attachedEl({ visibility: "hidden" }))).toBe(false);
+    expect(isElementVisibleForZOrder(attachedEl({ opacity: "0" }))).toBe(false);
+    expect(isElementVisibleForZOrder(attachedEl({ opacity: "0.005" }))).toBe(false);
+  });
+
+  it("treats normal, translucent, and unstyled elements as visible", () => {
+    expect(isElementVisibleForZOrder(attachedEl())).toBe(true);
+    expect(isElementVisibleForZOrder(attachedEl({ opacity: "0.5" }))).toBe(true);
+    expect(isElementVisibleForZOrder(attachedEl({ visibility: "visible" }))).toBe(true);
+  });
+
+  it("exempts a hidden color-grading source (its canvas paints in its place)", () => {
+    const el = attachedEl({ opacity: "0" });
+    el.setAttribute("data-hf-color-grading-source-hidden", "");
+    expect(isElementVisibleForZOrder(el)).toBe(true);
+  });
+
+  it("is the default probe: the runtime's inline visibility:hidden on a time-inactive clip is skipped", () => {
+    // End-to-end through resolveZOrderChange with NO injected probe: the
+    // runtime hides inactive clips with inline `visibility:hidden` (see core
+    // runtime syncTimedElementVisibility) — computed style picks that up.
+    const parent = document.createElement("div");
+    const target = makeEl("target", "1");
+    const hidden = makeEl("hidden", "2");
+    hidden.style.visibility = "hidden";
+    const vis = makeEl("vis", "3");
+    parent.append(target, hidden, vis);
+    document.body.appendChild(parent);
+    const patches = resolveZOrderPatches(target, "bring-forward");
+    expect(patchFor(patches, { target, hidden, vis }, "target")?.zIndex).toBe(4);
+    expect(patchFor(patches, { target, hidden, vis }, "hidden")).toBeUndefined();
+  });
+});
+
+// ── resolveCrossedNeighbor (the "show your work" flash target) ────────────────
+
+describe("resolveCrossedNeighbor", () => {
+  it("returns the visible sibling directly above for bring-forward", () => {
+    const { target, byId } = makeFamily("1", [
+      ["hidden", "2"],
+      ["vis", "3"],
+    ]);
+    const opts = { isVisible: (el: HTMLElement) => el !== byId.hidden };
+    expect(resolveCrossedNeighbor(target, "bring-forward", opts)).toBe(byId.vis);
+  });
+
+  it("returns the visible sibling directly below for send-backward", () => {
+    const { target, byId } = makeFamily("3", [
+      ["vis", "1"],
+      ["hidden", "2"],
+    ]);
+    const opts = { isVisible: (el: HTMLElement) => el !== byId.hidden };
+    expect(resolveCrossedNeighbor(target, "send-backward", opts)).toBe(byId.vis);
+  });
+
+  it("returns null for front/back actions and for no-op steps", () => {
+    const { target } = makeFamily("1", [["a", "2"]]);
+    expect(resolveCrossedNeighbor(target, "bring-to-front")).toBeNull();
+    expect(resolveCrossedNeighbor(target, "send-to-back")).toBeNull();
+    expect(resolveCrossedNeighbor(target, "send-backward")).toBeNull(); // already bottom
+    const { target: top } = makeFamily("5", [["a", "2"]]);
+    expect(resolveCrossedNeighbor(top, "bring-forward")).toBeNull(); // already top
+  });
+
+  it("returns null when there are no siblings", () => {
+    const solo = makeEl("solo", "1");
+    document.createElement("div").appendChild(solo);
+    expect(resolveCrossedNeighbor(solo, "bring-forward")).toBeNull();
+  });
+});
+
 // ── isZOrderActionEnabled ─────────────────────────────────────────────────────
 
 describe("isZOrderActionEnabled", () => {
@@ -433,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();
+  });
+});