@hyperframes/studio 0.7.57 → 0.7.58

package/src/components/nle/zLaneGesture.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it, vi } from "vitest";
+import { runLaneZGesture, runZLaneGesture } from "./zLaneGesture";
+
+const durable = { durable: true, allMatched: true, changed: true };
+
+function deferred<T>() {
+  let resolve!: (v: T) => void;
+  let reject!: (e: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+describe("runZLaneGesture", () => {
+  it("runs the mirror after a durable z commit and resolves its result", async () => {
+    const order: string[] = [];
+    const result = await runZLaneGesture({
+      commitZ: async () => {
+        order.push("z");
+        return durable;
+      },
+      mirror: async () => {
+        order.push("mirror");
+        return true;
+      },
+    });
+    expect(result).toBe(true);
+    expect(order).toEqual(["z", "mirror"]);
+  });
+
+  it("skips the mirror when the z commit reports unmatched targets", async () => {
+    const mirror = vi.fn(async () => true);
+    const result = await runZLaneGesture({
+      commitZ: async () => ({ durable: false, allMatched: false, changed: true }),
+      mirror,
+    });
+    expect(result).toBe(false);
+    expect(mirror).not.toHaveBeenCalled();
+  });
+
+  it("still mirrors on a void resolution (empty-entries commit path)", async () => {
+    const mirror = vi.fn(async () => true);
+    await runZLaneGesture({ commitZ: async () => undefined, mirror });
+    expect(mirror).toHaveBeenCalledTimes(1);
+  });
+
+  it("serializes gestures: B's z phase waits for A's mirror phase", async () => {
+    const order: string[] = [];
+    const aMirrorGate = deferred<void>();
+
+    const a = runZLaneGesture({
+      commitZ: async () => {
+        order.push("A:z");
+        return durable;
+      },
+      mirror: async () => {
+        await aMirrorGate.promise;
+        order.push("A:mirror");
+        return true;
+      },
+    });
+    const b = runZLaneGesture({
+      commitZ: async () => {
+        order.push("B:z");
+        return durable;
+      },
+      mirror: async () => {
+        order.push("B:mirror");
+        return true;
+      },
+    });
+
+    // Give B every chance to start early — it must not.
+    await new Promise((r) => setTimeout(r, 10));
+    expect(order).toEqual(["A:z"]);
+
+    aMirrorGate.resolve();
+    await Promise.all([a, b]);
+    expect(order).toEqual(["A:z", "A:mirror", "B:z", "B:mirror"]);
+  });
+
+  it("holds a lane→z gesture until an overlapping z→lane gesture fully settles", async () => {
+    const order: string[] = [];
+    const mirrorGate = deferred<void>();
+    const zFirst = runZLaneGesture({
+      commitZ: async () => {
+        order.push("z-first:z");
+        return durable;
+      },
+      mirror: async () => {
+        order.push("z-first:lane-start");
+        await mirrorGate.promise;
+        order.push("z-first:lane-end");
+        return true;
+      },
+    });
+    const laneFirst = runLaneZGesture({
+      commitLane: async () => {
+        order.push("lane-first:lane");
+        return true;
+      },
+      commitZ: async () => {
+        order.push("lane-first:z");
+      },
+    });
+
+    await Promise.resolve();
+    expect(order).toEqual(["z-first:z", "z-first:lane-start"]);
+    mirrorGate.resolve();
+    await Promise.all([zFirst, laneFirst]);
+    expect(order).toEqual([
+      "z-first:z",
+      "z-first:lane-start",
+      "z-first:lane-end",
+      "lane-first:lane",
+      "lane-first:z",
+    ]);
+  });
+
+  it("holds a z→lane gesture until an overlapping lane→z gesture fully settles", async () => {
+    const order: string[] = [];
+    const zGate = deferred<void>();
+    const laneFirst = runLaneZGesture({
+      commitLane: async () => {
+        order.push("lane-first:lane");
+        return true;
+      },
+      commitZ: async () => {
+        order.push("lane-first:z-start");
+        await zGate.promise;
+        order.push("lane-first:z-end");
+      },
+    });
+    const zFirst = runZLaneGesture({
+      commitZ: async () => {
+        order.push("z-first:z");
+        return durable;
+      },
+      mirror: async () => {
+        order.push("z-first:lane");
+        return true;
+      },
+    });
+
+    await Promise.resolve();
+    expect(order).toEqual(["lane-first:lane", "lane-first:z-start"]);
+    zGate.resolve();
+    await Promise.all([laneFirst, zFirst]);
+    expect(order).toEqual([
+      "lane-first:lane",
+      "lane-first:z-start",
+      "lane-first:z-end",
+      "z-first:z",
+      "z-first:lane",
+    ]);
+  });
+
+  it("a failed gesture rejects its caller but never wedges the queue", async () => {
+    const boom = new Error("z failed");
+    const failed = runZLaneGesture({
+      commitZ: async () => {
+        throw boom;
+      },
+      mirror: async () => true,
+    });
+    await expect(failed).rejects.toBe(boom);
+
+    const next = await runZLaneGesture({
+      commitZ: async () => durable,
+      mirror: async () => true,
+    });
+    expect(next).toBe(true);
+  });
+});

package/src/components/nle/zLaneGesture.ts

@@ -0,0 +1,77 @@
+import type { DomEditPatchBatchesResult } from "../../hooks/domEditCommitTypes";
+
+/**
+ * Run one COMPLETE z→lane gesture — the z-index persist followed by its
+ * timeline lane mirror — as a single serialized transaction.
+ *
+ * Why a queue: the two phases persist through DIFFERENT pipelines (the z patch
+ * rides the DOM-edit save queue, the lane move rides the timeline/SDK move
+ * path). Each gesture orders its own phases by awaiting the z persist, but
+ * without cross-gesture serialization a second rapid gesture can land between
+ * the first gesture's phases and the interleaved file writes can clobber each
+ * other. Canvas z→lane and timeline lane→z gestures both chain through this
+ * single module-level tail, so gesture B cannot start until gesture A settled.
+ *
+ * Why the durability gate: a resolved z commit is not necessarily durable —
+ * when the server cannot match a patch target, commitDomEditPatchBatches
+ * resolves with `durable: false` (after scheduling a reload to
+ * reconverge). Mirroring a lane move onto a z state that disk never held
+ * would desync track order from what actually paints, so the mirror phase is
+ * skipped and the gesture resolves `false`.
+ *
+ * Failures never wedge the queue: a rejected gesture propagates to ITS caller
+ * while the tail continues for the next gesture.
+ */
+let gestureTail: Promise<void> | null = null;
+
+/** The single ordering owner for every gesture that crosses z/lane persistence. */
+export function serializeZLaneGesture<Result>(run: () => Promise<Result>): Promise<Result> {
+  const previous = gestureTail;
+  // Preserve synchronous optimistic updates for the first gesture. A queued
+  // gesture starts only after the preceding gesture fully settled.
+  let gesture: Promise<Result>;
+  if (previous) {
+    gesture = previous.then(run, run);
+  } else {
+    try {
+      gesture = Promise.resolve(run());
+    } catch (error) {
+      gesture = Promise.reject(error);
+    }
+  }
+  const tail = gesture.then(
+    () => undefined,
+    () => undefined,
+  );
+  gestureTail = tail;
+  void tail.then(() => {
+    if (gestureTail === tail) gestureTail = null;
+  });
+  return gesture;
+}
+
+export function runZLaneGesture(input: {
+  /** Phase 1: persist the z patch (handleDomZIndexReorderCommit). */
+  commitZ: () => Promise<DomEditPatchBatchesResult | undefined | void>;
+  /** Phase 2: mirror into a timeline lane move; only runs on a durable phase 1. */
+  mirror: () => Promise<boolean>;
+}): Promise<boolean> {
+  const run = async (): Promise<boolean> => {
+    const result = await input.commitZ();
+    if (result && !result.durable) return false;
+    return input.mirror();
+  };
+  return serializeZLaneGesture(run);
+}
+
+/** Run one lane→z gesture under the same owner as canvas z→lane gestures. */
+export function runLaneZGesture(input: {
+  commitLane: () => Promise<boolean>;
+  commitZ: () => Promise<void>;
+}): Promise<boolean> {
+  return serializeZLaneGesture(async () => {
+    if (!(await input.commitLane())) return false;
+    await input.commitZ();
+    return true;
+  });
+}

package/src/hooks/domEditCommitTypes.ts

@@ -11,6 +11,8 @@ export type CommitDomEditPatchBatches = (
   options: {
     label: string;
     coalesceKey: string;
+    /** Per-entry undo coalesce window override (ms) — see EditHistoryEntry.coalesceMs. */
+    coalesceMs?: number;
     /**
      * Request skipping the preview iframe reload after a successful persist.
      * Only honored when the persist is provably in sync with the live DOM:
@@ -20,7 +22,21 @@ export type CommitDomEditPatchBatches = (
      */
     skipReload?: boolean;
   },
-) => Promise<void>;
+) => Promise<DomEditPatchBatchesResult>;
+
+/**
+ * Durability report for a patch-batches commit. `durable === false` means the
+ * server could not locate at least one patch target on disk — the preview was
+ * reloaded to reconverge, and dependent follow-up writes (the z→lane timeline
+ * mirror) must be skipped. `allMatched` retains the underlying match detail.
+ * `changed === false` means no source file was written: every patch was a
+ * byte-identical no-op, or the atomic gesture was refused before any write.
+ */
+export interface DomEditPatchBatchesResult {
+  durable: boolean;
+  allMatched: boolean;
+  changed: boolean;
+}
 
 export type PersistDomEditOperations = (
   selection: DomEditSelection,

package/src/hooks/elementLifecycleOpsTestUtils.ts

@@ -0,0 +1,25 @@
+import { vi } from "vitest";
+import type { useElementLifecycleOps } from "./useElementLifecycleOps";
+
+type LifecycleOpsParams = Parameters<typeof useElementLifecycleOps>[0];
+
+/**
+ * Baseline `useElementLifecycleOps` params for tests: inert stubs for every
+ * dependency, overridden per test (typically just `commitDomEditPatchBatches`).
+ * Shared by the z-reorder commit tests and the timeline-mirror harness.
+ */
+export function makeLifecycleOpsParams(
+  overrides: Partial<LifecycleOpsParams> & Pick<LifecycleOpsParams, "commitDomEditPatchBatches">,
+): LifecycleOpsParams {
+  return {
+    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(),
+    ...overrides,
+  };
+}

package/src/hooks/fetchStubTestUtils.ts

@@ -0,0 +1,16 @@
+// Shared helpers for test-side `fetch` stubs (timelineTimingSync.test.ts,
+// useTimelineEditing.test.tsx): a JSON Response factory and a Request → URL
+// normalizer. Test-only module — imported exclusively from *.test.* files.
+
+export function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+export function requestUrl(input: Parameters<typeof fetch>[0]): string {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.toString();
+  return input.url;
+}

package/src/hooks/timelineEditingHelpers.test.ts

@@ -5,6 +5,7 @@ import {
   buildTimelineMoveTimingPatch,
   deleteSelectedKeyframes,
   extendRootDurationIfNeeded,
+  patchIframeDomTiming,
   persistTimelineBatchEdit,
   type PersistTimelineBatchChange,
 } from "./timelineEditingHelpers";
@@ -42,7 +43,11 @@ describe("applyTimelineStackingReorder", () => {
   it("commits via the change's own locator even when the element is not in timelineElements", () => {
     // Sub-comp children live in the preview iframe but NOT in the top-level
     // timelineElements list — the intent must be self-contained.
-    const iframe = makeIframeWith(`<div id="chip" style="z-index: 1"></div>`);
+    const iframe = makeIframeWith(`
+      <div data-composition-id="scene" data-composition-file="scenes/scene.html">
+        <div id="chip" style="z-index: 1"></div>
+      </div>
+    `);
     const commit = vi.fn<(entries: unknown[]) => void>();
 
     applyTimelineStackingReorder({
@@ -96,6 +101,92 @@ describe("applyTimelineStackingReorder", () => {
 
     expect(commit).not.toHaveBeenCalled();
   });
+
+  it("resolves selectorIndex within the change's source file", () => {
+    const iframe = makeIframeWith(`
+      <div data-composition-id="root">
+        <div class="chip">root</div>
+        <div data-composition-id="scene" data-composition-file="scenes/scene.html">
+          <div class="chip">scene zero</div>
+          <div class="chip" style="z-index: 1">scene one</div>
+        </div>
+      </div>
+    `);
+    const sceneOne = iframe.contentDocument?.querySelectorAll(".chip")[2];
+    const commit = vi.fn<(entries: unknown[]) => void>();
+
+    applyTimelineStackingReorder({
+      element: el({ id: "scene-one", tag: "div" }),
+      stackingReorder: {
+        contextKey: "scene",
+        placement: { type: "above", layerId: "layer:scene:x" },
+        zIndexChanges: [
+          {
+            key: "scenes/scene.html#.chip:1",
+            zIndex: 5,
+            selector: ".chip",
+            selectorIndex: 1,
+            sourceFile: "scenes/scene.html",
+          },
+        ],
+      },
+      timelineElements: [],
+      iframe,
+      activeCompPath: "index.html",
+      commit,
+    });
+
+    const entries = commit.mock.calls[0]![0] as Array<{ element: Element }>;
+    expect(entries[0]!.element).toBe(sceneOne);
+  });
+});
+
+describe("patchIframeDomTiming", () => {
+  it("resolves selectorIndex within the element's source file", () => {
+    const iframe = makeIframeWith(`
+      <div data-composition-id="root">
+        <div class="clip" data-start="1">root</div>
+        <div data-composition-id="scene" data-composition-file="scenes/scene.html">
+          <div class="clip" data-start="2">scene zero</div>
+          <div class="clip" data-start="3">scene one</div>
+        </div>
+      </div>
+    `);
+    const clips = iframe.contentDocument?.querySelectorAll<HTMLElement>(".clip");
+    const target = el({
+      id: "scene-one",
+      tag: "div",
+      selector: ".clip",
+      selectorIndex: 1,
+      sourceFile: "scenes/scene.html",
+    });
+
+    patchIframeDomTiming(iframe, target, [["data-start", "9"]], "index.html");
+
+    expect([...clips!].map((clip) => clip.dataset.start)).toEqual(["1", "2", "9"]);
+  });
+
+  it("resolves duplicate domId within the element's source file", () => {
+    const iframe = makeIframeWith(`
+      <div data-composition-id="root">
+        <div id="card" data-start="1">root</div>
+        <div data-composition-id="scene" data-composition-file="scenes/scene.html">
+          <div id="card" data-start="2">scene</div>
+        </div>
+      </div>
+    `);
+    const cards = iframe.contentDocument?.querySelectorAll<HTMLElement>("#card");
+    const target = el({
+      id: "scene-card",
+      tag: "div",
+      domId: "card",
+      sourceFile: "scenes/scene.html",
+    });
+
+    patchIframeDomTiming(iframe, target, [["data-start", "9"]], "index.html");
+
+    expect([...cards!].map((card) => card.dataset.start)).toEqual(["1", "9"]);
+  });
 });
 
 describe("extendRootDurationIfNeeded", () => {

package/src/hooks/timelineEditingHelpers.ts

@@ -13,6 +13,7 @@ import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/stud
 import type { TimelineZIndexReorderCommit } from "./useTimelineEditingTypes";
 import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
 import { readFileContent } from "./timelineTimingSync";
+import { findElementForSelection } from "../components/editor/domEditingElement";
 export { deleteSelectedKeyframes } from "./deleteSelectedKeyframes";
 export { readFileContent };
 function isHTMLElement(element: Element | null): element is HTMLElement {
@@ -53,12 +54,6 @@ export function applyTimelineStackingReorder(input: {
     input.timelineElements.map((el) => [getTimelineElementIdentity(el), el]),
   );
   const doc = input.iframe?.contentDocument ?? null;
-  const findLive = (domId?: string, selector?: string, selectorIndex?: number): Element | null => {
-    if (!doc) return null;
-    if (domId) return doc.getElementById(domId);
-    if (selector) return doc.querySelectorAll(selector)[selectorIndex ?? 0] ?? null;
-    return null;
-  };
   const commitEntries: Array<{
     element: HTMLElement;
     zIndex: number;
@@ -73,7 +68,15 @@ export function applyTimelineStackingReorder(input: {
     const domId = change.domId ?? sibling?.domId;
     const selector = change.selector ?? sibling?.selector;
     const selectorIndex = change.selectorIndex ?? sibling?.selectorIndex;
-    const element = findLive(domId, selector, selectorIndex);
+    const sourceFile =
+      change.sourceFile ?? sibling?.sourceFile ?? input.activeCompPath ?? "index.html";
+    const element = doc
+      ? findElementForSelection(
+          doc,
+          { id: domId, selector, selectorIndex, sourceFile },
+          input.activeCompPath,
+        )
+      : null;
     if (!isHTMLElement(element)) return Promise.resolve();
     if (getElementZIndex(element) === change.zIndex) continue;
     commitEntries.push({
@@ -82,12 +85,15 @@ export function applyTimelineStackingReorder(input: {
       id: domId ?? sibling?.id ?? change.key,
       selector,
       selectorIndex,
-      sourceFile: change.sourceFile ?? sibling?.sourceFile ?? input.activeCompPath ?? "index.html",
+      sourceFile,
       key: change.key,
     });
   }
   if (commitEntries.length === 0) return Promise.resolve();
-  return input.commit?.(commitEntries, input.coalesceKey) ?? Promise.resolve();
+  // The durability report is for gesture-level callers (z→lane mirror); this
+  // lane-drag z-sync path has no dependent follow-up write — swallow it.
+  // Promise.resolve-wrapped: a commit implementation may return void.
+  return Promise.resolve(input.commit?.(commitEntries, input.coalesceKey)).then(() => undefined);
 }
 export function extendRootDurationIfNeeded(newEnd: number): boolean {
   const store = usePlayerStore.getState();
@@ -126,15 +132,22 @@ export type PatchTarget = NonNullable<ReturnType<typeof buildPatchTarget>>;
 export function findTimelineElementInIframe(
   iframe: HTMLIFrameElement | null,
   element: TimelineElement,
+  activeCompositionPath: string | null = null,
 ): Element | null {
   try {
     const doc = iframe?.contentDocument;
     if (!doc) return null;
-    return element.domId
-      ? doc.getElementById(element.domId)
-      : element.selector
-        ? (doc.querySelectorAll(element.selector)[element.selectorIndex ?? 0] ?? null)
-        : null;
+    return findElementForSelection(
+      doc,
+      {
+        hfId: element.hfId,
+        id: element.domId,
+        selector: element.selector,
+        selectorIndex: element.selectorIndex,
+        sourceFile: element.sourceFile || activeCompositionPath || "index.html",
+      },
+      activeCompositionPath,
+    );
   } catch {
     return null;
   }
@@ -143,9 +156,10 @@ export function patchIframeDomTiming(
   iframe: HTMLIFrameElement | null,
   element: TimelineElement,
   attrs: Array<[string, string]>,
+  activeCompositionPath: string | null = null,
 ): void {
   try {
-    const el = findTimelineElementInIframe(iframe, element);
+    const el = findTimelineElementInIframe(iframe, element, activeCompositionPath);
     if (!el) return;
     for (const [name, value] of attrs) el.setAttribute(name, value);
   } catch {
@@ -299,6 +313,8 @@ export interface PersistTimelineBatchEditInput {
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   pendingTimelineEditPathRef: React.MutableRefObject<Set<string>>;
   coalesceKey?: string;
+  /** Per-entry undo coalesce window override (ms) — see EditHistoryEntry.coalesceMs. */
+  coalesceMs?: number;
 }
 
 export async function persistTimelineBatchEdit(
@@ -347,6 +363,7 @@ export async function persistTimelineBatchEdit(
     label: input.label,
     kind: "timeline",
     coalesceKey: input.coalesceKey,
+    coalesceMs: input.coalesceMs,
     files,
     readFile: async (path) => originals.get(path) ?? readFileContent(input.projectId, path),
     writeFile: input.writeProjectFile,

package/src/hooks/timelineMoveAdapter.ts

@@ -23,6 +23,7 @@ export function persistTimelineMoveEditsAtomically(
   coalesceKey: string | undefined,
   operation: TimelineMoveOperation,
   deps: AtomicMoveDeps,
+  coalesceMs?: number,
 ): Promise<void> {
   return deps.handleTimelineGroupMove(
     edits.map(({ element, updates }) => ({
@@ -34,6 +35,6 @@ export function persistTimelineMoveEditsAtomically(
       // ("timing") omit it so they stay eligible for the SDK fast path.
       track: operation === "timing" ? undefined : updates.track,
     })),
-    { coalesceKey },
+    { coalesceKey, coalesceMs },
   );
 }