@hyperframes/studio 0.7.56 → 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/components/sidebar/AssetCard.test.tsx

@@ -0,0 +1,106 @@
+// @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 { usePlayerStore, type TimelineElement } from "../../player/store/playerStore";
+import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
+import { AssetCard } from "./AssetCard";
+import { AudioRow } from "./AudioRow";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | null = null;
+
+afterEach(() => {
+  if (root) {
+    act(() => root?.unmount());
+    root = null;
+  }
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+  useAssetPreviewStore.getState().clearPreviewAsset();
+  vi.restoreAllMocks();
+});
+
+function mount(node: React.ReactElement): HTMLElement {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  act(() => {
+    root?.render(node);
+  });
+  return host;
+}
+
+function clip(input: Partial<TimelineElement> & { id: string; src: string }): TimelineElement {
+  return { tag: "div", start: 0, duration: 5, track: 0, ...input };
+}
+
+/** Simulate a drag-free click: pointerdown + pointerup at the same point. */
+function clickCard(host: HTMLElement): void {
+  const card = host.querySelector('[draggable="true"]');
+  if (!card) throw new Error("Expected a draggable card root");
+  const PointerCtor = (window as { PointerEvent?: typeof MouseEvent }).PointerEvent ?? MouseEvent;
+  act(() => {
+    card.dispatchEvent(new PointerCtor("pointerdown", { bubbles: true, clientX: 5, clientY: 5 }));
+    card.dispatchEvent(new PointerCtor("pointerup", { bubbles: true, clientX: 5, clientY: 5 }));
+  });
+}
+
+describe("AssetCard click behavior", () => {
+  const cardProps = {
+    projectId: "p1",
+    onCopy: vi.fn(),
+    isCopied: false,
+  };
+
+  it("clears an open preview overlay when clicking an already-added asset (reveal branch)", () => {
+    usePlayerStore.getState().setElements([clip({ id: "img1", src: "assets/logo.png" })]);
+    // Preview overlay is open on ANOTHER asset — the reveal must dismiss it,
+    // or it stays stuck over the canvas while the timeline reveals the clip.
+    useAssetPreviewStore.getState().setPreviewAsset("assets/other.png", "p1");
+
+    const host = mount(<AssetCard {...cardProps} asset="assets/logo.png" used />);
+    clickCard(host);
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBeNull();
+    expect(usePlayerStore.getState().selectedElementId).toBe("img1");
+  });
+
+  it("opens the preview overlay for a not-yet-added asset", () => {
+    const host = mount(<AssetCard {...cardProps} asset="assets/logo.png" used={false} />);
+    clickCard(host);
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBe("assets/logo.png");
+    expect(useAssetPreviewStore.getState().previewProjectId).toBe("p1");
+  });
+});
+
+describe("AudioRow click behavior", () => {
+  const rowProps = {
+    projectId: "p1",
+    onCopy: vi.fn(),
+    isCopied: false,
+  };
+
+  it("clears an open preview overlay when clicking an already-added audio asset (reveal branch)", () => {
+    usePlayerStore
+      .getState()
+      .setElements([clip({ id: "bgm1", tag: "audio", src: "assets/bgm.mp3" })]);
+    useAssetPreviewStore.getState().setPreviewAsset("assets/other.mp3", "p1");
+
+    const host = mount(<AudioRow {...rowProps} asset="assets/bgm.mp3" used />);
+    clickCard(host);
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBeNull();
+    expect(usePlayerStore.getState().selectedElementId).toBe("bgm1");
+  });
+
+  it("opens the preview overlay for a not-yet-added audio asset", () => {
+    const host = mount(<AudioRow {...rowProps} asset="assets/bgm.mp3" used={false} />);
+    clickCard(host);
+
+    expect(useAssetPreviewStore.getState().previewAsset).toBe("assets/bgm.mp3");
+  });
+});

package/src/components/sidebar/AssetCard.tsx

@@ -133,8 +133,10 @@ export function AssetCard({
   const pointerDownRef = useRef<{ x: number; y: number } | null>(null);
 
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
+  const requestClipReveal = usePlayerStore((s) => s.requestClipReveal);
   const elements = usePlayerStore((s) => s.elements);
   const setPreviewAsset = useAssetPreviewStore((s) => s.setPreviewAsset);
+  const clearPreviewAsset = useAssetPreviewStore((s) => s.clearPreviewAsset);
 
   const handlePointerDown = useCallback((e: React.PointerEvent) => {
     pointerDownRef.current = { x: e.clientX, y: e.clientY };
@@ -150,14 +152,29 @@ export function AssetCard({
       if (used) {
         const clip = findClipForAsset(elements, asset);
         if (clip) {
-          setSelectedElementId(clip.key ?? clip.id);
+          // Dismiss any open preview overlay (from another asset) — the reveal
+          // must not leave a stale preview card floating over the canvas.
+          clearPreviewAsset();
+          const clipKey = clip.key ?? clip.id;
+          setSelectedElementId(clipKey);
+          // Scroll the timeline so the selected clip is actually visible.
+          requestClipReveal(clipKey);
           return;
         }
       }
       // Not added (or no matching clip found) → preview overlay
       setPreviewAsset(asset, projectId);
     },
-    [used, elements, asset, projectId, setSelectedElementId, setPreviewAsset],
+    [
+      used,
+      elements,
+      asset,
+      projectId,
+      setSelectedElementId,
+      requestClipReveal,
+      setPreviewAsset,
+      clearPreviewAsset,
+    ],
   );
 
   return (

package/src/components/sidebar/AudioRow.tsx

@@ -43,8 +43,10 @@ export function AudioRow({
   // CapCut-style click behavior: drag-threshold gate.
   const pointerDownRef = useRef<{ x: number; y: number } | null>(null);
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
+  const requestClipReveal = usePlayerStore((s) => s.requestClipReveal);
   const elements = usePlayerStore((s) => s.elements);
   const setPreviewAsset = useAssetPreviewStore((s) => s.setPreviewAsset);
+  const clearPreviewAsset = useAssetPreviewStore((s) => s.clearPreviewAsset);
 
   const handlePointerDown = useCallback((e: React.PointerEvent) => {
     pointerDownRef.current = { x: e.clientX, y: e.clientY };
@@ -59,14 +61,29 @@ export function AudioRow({
       if (used) {
         const clip = findClipForAsset(elements, asset);
         if (clip) {
-          setSelectedElementId(clip.key ?? clip.id);
+          // Dismiss any open preview overlay (from another asset) — the reveal
+          // must not leave a stale preview card floating over the canvas.
+          clearPreviewAsset();
+          const clipKey = clip.key ?? clip.id;
+          setSelectedElementId(clipKey);
+          // Scroll the timeline so the selected clip is actually visible.
+          requestClipReveal(clipKey);
           return;
         }
       }
       // Not added → preview overlay (audio player)
       setPreviewAsset(asset, projectId);
     },
-    [used, elements, asset, projectId, setSelectedElementId, setPreviewAsset],
+    [
+      used,
+      elements,
+      asset,
+      projectId,
+      setSelectedElementId,
+      requestClipReveal,
+      setPreviewAsset,
+      clearPreviewAsset,
+    ],
   );
 
   useEffect(() => {

package/src/hooks/domEditCommitTypes.ts

@@ -8,8 +8,35 @@ export interface DomEditPatchBatch {
 
 export type CommitDomEditPatchBatches = (
   batches: DomEditPatchBatch[],
-  options: { label: string; coalesceKey: string },
-) => Promise<void>;
+  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:
+     * every patch operation is inline-style-only AND the server matched every
+     * patch target. Any unmatched target (or a non-style op) falls back to the
+     * reload so the preview reconverges with disk. Default: always reload.
+     */
+    skipReload?: boolean;
+  },
+) => 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;
+}