@hyperframes/studio 0.7.54 → 0.7.56

package/src/hooks/useDomSelectionSelectionGuards.test.ts

@@ -0,0 +1,276 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { installReactActEnvironment, makeSelection } from "./domSelectionTestHarness";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { SelectElementOptions, TimelineElement } from "../player";
+import { usePlayerStore } from "../player";
+
+installReactActEnvironment();
+
+// ── Module mocks ──
+// Control the async selection-resolution ordering so the race guard can be
+// exercised deterministically, and neutralise the DOM re-apply side effect.
+vi.mock("../components/editor/manualEdits", () => ({
+  reapplyPositionEditsAfterSeek: () => undefined,
+}));
+
+const deferreds = new Map<string, { promise: Promise<DomEditSelection>; resolve: () => void }>();
+
+function deferredFor(el: HTMLElement): Promise<DomEditSelection> {
+  const id = el.id;
+  let resolveFn: () => void = () => undefined;
+  const promise = new Promise<DomEditSelection>((resolve) => {
+    resolveFn = () => resolve(makeSelection(id.toUpperCase(), el));
+  });
+  deferreds.set(id, { promise, resolve: resolveFn });
+  return promise;
+}
+
+vi.mock("../components/editor/domEditing", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../components/editor/domEditing")>();
+  return {
+    ...actual,
+    findElementForTimelineElement: (doc: Document, element: { id?: string }) =>
+      element.id ? doc.getElementById(element.id) : null,
+    resolveDomEditSelection: (startEl: HTMLElement | null) =>
+      startEl ? deferredFor(startEl) : Promise.resolve(null),
+  };
+});
+
+// Imported after the mocks so the hook picks up the mocked modules.
+const { useDomSelection } = await import("./useDomSelection");
+
+interface HarnessProps {
+  rightPanelTab: "design" | "variables";
+  setRightPanelTab: (tab: "design" | "variables") => void;
+  iframe: HTMLIFrameElement | null;
+  timelineElements: TimelineElement[];
+  setSelectedTimelineElementId?: (id: string | null, options?: SelectElementOptions) => void;
+}
+
+function renderHarness(props: HarnessProps) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  let currentHook: ReturnType<typeof useDomSelection> | null = null;
+
+  function Harness() {
+    currentHook = useDomSelection({
+      projectId: "project-1",
+      activeCompPath: "index.html",
+      isMasterView: false,
+      compIdToSrc: new Map(),
+      captionEditMode: false,
+      previewIframeRef: { current: props.iframe },
+      timelineElements: props.timelineElements,
+      setSelectedTimelineElementId: props.setSelectedTimelineElementId ?? vi.fn(),
+      setRightCollapsed: vi.fn(),
+      setRightPanelTab: props.setRightPanelTab,
+      previewIframe: props.iframe,
+      refreshKey: 0,
+      rightPanelTab: props.rightPanelTab,
+    });
+    return null;
+  }
+
+  act(() => root.render(React.createElement(Harness)));
+
+  return {
+    current: () => {
+      if (!currentHook) throw new Error("Expected hook result");
+      return currentHook;
+    },
+    cleanup: () => {
+      act(() => root.unmount());
+      host.remove();
+    },
+  };
+}
+
+describe("useDomSelection — Variables tab preservation", () => {
+  it("does not yank the user off the Variables tab when selecting on canvas", () => {
+    const setRightPanelTab = vi.fn();
+    const el = document.createElement("div");
+    el.id = "headline";
+    const harness = renderHarness({
+      rightPanelTab: "variables",
+      setRightPanelTab,
+      iframe: null,
+      timelineElements: [],
+    });
+
+    act(() => harness.current().applyDomSelection(makeSelection("Headline", el)));
+
+    expect(setRightPanelTab).not.toHaveBeenCalled();
+    harness.cleanup();
+  });
+
+  it("switches to the Design tab when not on Variables (control)", () => {
+    const setRightPanelTab = vi.fn();
+    const el = document.createElement("div");
+    el.id = "headline";
+    const harness = renderHarness({
+      rightPanelTab: "design",
+      setRightPanelTab,
+      iframe: null,
+      timelineElements: [],
+    });
+
+    act(() => harness.current().applyDomSelection(makeSelection("Headline", el)));
+
+    expect(setRightPanelTab).toHaveBeenCalledWith("design");
+    harness.cleanup();
+  });
+});
+
+describe("useDomSelection — timeline-select race guard", () => {
+  beforeEach(() => deferreds.clear());
+  afterEach(() => deferreds.clear());
+
+  it("a stale async resolution never clobbers a newer selection", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const doc = iframe.contentDocument!;
+    const elA = doc.createElement("div");
+    elA.id = "a";
+    const elB = doc.createElement("div");
+    elB.id = "b";
+    doc.body.append(elA, elB);
+
+    const elementA: TimelineElement = { id: "a", tag: "div", start: 0, duration: 1, track: 0 };
+    const elementB: TimelineElement = { id: "b", tag: "div", start: 0, duration: 1, track: 0 };
+
+    const harness = renderHarness({
+      rightPanelTab: "design",
+      setRightPanelTab: vi.fn(),
+      iframe,
+      timelineElements: [elementA, elementB],
+    });
+
+    // Fire A then B; both suspend on their (pending) resolveDomEditSelection.
+    let pA: Promise<void> = Promise.resolve();
+    let pB: Promise<void> = Promise.resolve();
+    act(() => {
+      pA = harness.current().handleTimelineElementSelect(elementA);
+      pB = harness.current().handleTimelineElementSelect(elementB);
+    });
+
+    // Resolve the NEWER select (B) first, then the older one (A) last.
+    await act(async () => {
+      deferreds.get("b")?.resolve();
+      await pB;
+    });
+    await act(async () => {
+      deferreds.get("a")?.resolve();
+      await pA;
+    });
+
+    // The stale A resolution must be dropped: B wins.
+    expect(harness.current().domEditSelection?.id).toBe("b");
+    harness.cleanup();
+    iframe.remove();
+  });
+});
+
+describe("useDomSelection — marquee multi-select survives the late async primary", () => {
+  beforeEach(() => {
+    deferreds.clear();
+    const store = usePlayerStore.getState();
+    store.setSelectedElementId(null);
+    store.clearSelectedElementIds();
+  });
+  afterEach(() => {
+    deferreds.clear();
+    const store = usePlayerStore.getState();
+    store.setSelectedElementId(null);
+    store.clearSelectedElementIds();
+  });
+
+  function timelineEl(id: string): TimelineElement {
+    return { id, domId: id, tag: "div", start: 0, duration: 1, track: 0 };
+  }
+
+  // Reproduces the reported regression: a marquee over N clips leaves N members in
+  // selectedElementIds, then the inspector-open notify (finishMarquee →
+  // handleTimelineElementSelect → applyDomSelection) resolves LATE and writes the
+  // primary again. Before the fix that late write collapsed the set to one clip.
+  it("keeps all N members when a late primary-set targets a set member", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const doc = iframe.contentDocument!;
+    for (const id of ["a", "b", "c"]) {
+      const el = doc.createElement("div");
+      el.id = id;
+      doc.body.append(el);
+    }
+
+    const store = usePlayerStore.getState();
+    // Marquee end state: primary written first, then the full set (real ordering).
+    store.setSelectedElementId("a");
+    store.setSelectedElementIds(new Set(["a", "b", "c"]));
+
+    const harness = renderHarness({
+      rightPanelTab: "design",
+      setRightPanelTab: vi.fn(),
+      iframe,
+      timelineElements: [timelineEl("a"), timelineEl("b"), timelineEl("c")],
+      // Wire the real store write so applyDomSelection's collapse decision is exercised.
+      setSelectedTimelineElementId: usePlayerStore.getState().setSelectedElementId,
+    });
+
+    let pending: Promise<void> = Promise.resolve();
+    act(() => {
+      pending = harness.current().handleTimelineElementSelect(timelineEl("a"));
+    });
+    await act(async () => {
+      deferreds.get("a")?.resolve();
+      await pending;
+    });
+
+    expect(usePlayerStore.getState().selectedElementIds.size).toBe(3);
+    expect(usePlayerStore.getState().selectedElementId).toBe("a");
+    harness.cleanup();
+    iframe.remove();
+  });
+
+  it("collapses the set when a late primary-set targets a non-member (fresh click)", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const doc = iframe.contentDocument!;
+    for (const id of ["a", "b", "d"]) {
+      const el = doc.createElement("div");
+      el.id = id;
+      doc.body.append(el);
+    }
+
+    const store = usePlayerStore.getState();
+    // Stale set left over from a previous gesture.
+    store.setSelectedElementId("a");
+    store.setSelectedElementIds(new Set(["a", "b"]));
+
+    const harness = renderHarness({
+      rightPanelTab: "design",
+      setRightPanelTab: vi.fn(),
+      iframe,
+      timelineElements: [timelineEl("a"), timelineEl("b"), timelineEl("d")],
+      setSelectedTimelineElementId: usePlayerStore.getState().setSelectedElementId,
+    });
+
+    let pending: Promise<void> = Promise.resolve();
+    act(() => {
+      pending = harness.current().handleTimelineElementSelect(timelineEl("d"));
+    });
+    await act(async () => {
+      deferreds.get("d")?.resolve();
+      await pending;
+    });
+
+    expect(usePlayerStore.getState().selectedElementIds.size).toBe(0);
+    expect(usePlayerStore.getState().selectedElementId).toBe("d");
+    harness.cleanup();
+    iframe.remove();
+  });
+});

package/src/hooks/useElementLifecycleOps.test.tsx

@@ -0,0 +1,258 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../player";
+import type { DomEditPatchBatch } from "./domEditCommitTypes";
+import { useElementLifecycleOps } from "./useElementLifecycleOps";
+import { mountReactHarness } from "./domSelectionTestHarness";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.getState().setElements([]);
+  vi.unstubAllGlobals();
+});
+
+interface BatchOptions {
+  label: string;
+  coalesceKey: string;
+}
+
+interface CapturedBatchCall {
+  batches: DomEditPatchBatch[];
+  options: BatchOptions;
+}
+
+type ReorderCommit = (
+  entries: Array<{
+    element: HTMLElement;
+    zIndex: number;
+    id?: string;
+    selector?: string;
+    selectorIndex?: number;
+    sourceFile: string;
+    key?: string;
+  }>,
+  coalesceKeyOverride?: string,
+) => Promise<void>;
+
+function renderReorderHook(
+  capturedCalls: CapturedBatchCall[],
+  onReady: (commit: ReorderCommit) => void,
+) {
+  function Harness() {
+    const { handleDomZIndexReorderCommit } = 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) => {
+        capturedCalls.push({ batches, options });
+      },
+    });
+    onReady(handleDomZIndexReorderCommit);
+    return null;
+  }
+  return mountReactHarness(<Harness />);
+}
+
+/** Append the element, mount the reorder hook, and run one commit through act. */
+async function runReorderCommit(el: HTMLElement, entries: Parameters<ReorderCommit>[0]) {
+  document.body.appendChild(el);
+
+  const captured: CapturedBatchCall[] = [];
+  let commit: ReorderCommit | undefined;
+  const root = renderReorderHook(captured, (fn) => (commit = fn));
+
+  await act(async () => {
+    commit!(entries);
+  });
+
+  return { captured, root };
+}
+
+describe("useElementLifecycleOps — z-index reorder payload", () => {
+  // Regression: an id-less canvas element (e.g. a caption `.sub` div, which
+  // carries only data-hf-id + class) once had its absent id coerced to `null`
+  // (`entry.id ?? null`). The DOM-patch guard rejects a null `body.target.id`,
+  // so "move to back" toasted "unsafe values" and nothing persisted. The target
+  // id must be `undefined` (dropped on the wire), letting hfId / selector match.
+  it("never sends a null target id for an id-less element", async () => {
+    const el = document.createElement("div");
+    el.className = "sub clip";
+    el.setAttribute("data-hf-id", "hf-card");
+
+    const { captured, root } = await runReorderCommit(el, [
+      {
+        element: el,
+        zIndex: 0,
+        // id intentionally absent — the id-less element case.
+        selector: ".sub.clip",
+        selectorIndex: 3,
+        sourceFile: "index.html",
+      },
+    ]);
+
+    const target = captured[0]?.batches[0]?.patches[0]?.target;
+    expect(captured).toHaveLength(1);
+    expect(target?.id).toBeUndefined();
+    expect(target?.id).not.toBeNull();
+    // The element stays addressable via hfId (and selector) instead.
+    expect(target?.hfId).toBe("hf-card");
+
+    act(() => root.unmount());
+  });
+
+  it("preserves a real id when the element has one", async () => {
+    const el = document.createElement("video");
+    el.id = "v-hero";
+    el.setAttribute("data-hf-id", "hf-ezl2");
+
+    const { captured, root } = await runReorderCommit(el, [
+      { element: el, zIndex: 2, id: "v-hero", selector: "#v-hero", sourceFile: "index.html" },
+    ]);
+
+    expect(captured).toHaveLength(1);
+    expect(captured[0]?.batches[0]?.patches[0]?.target.id).toBe("v-hero");
+
+    act(() => root.unmount());
+  });
+
+  it("threads the lane gesture key into z-index persistence", async () => {
+    const el = document.createElement("div");
+    el.id = "clip-a";
+    document.body.appendChild(el);
+    const captured: CapturedBatchCall[] = [];
+    let commit: ReorderCommit | undefined;
+    const root = renderReorderHook(captured, (fn) => (commit = fn));
+
+    await act(async () => {
+      await commit!(
+        [{ element: el, zIndex: 4, id: "clip-a", sourceFile: "index.html" }],
+        "clip-lane-move:7",
+      );
+    });
+
+    expect(captured).toHaveLength(1);
+    expect(captured[0]?.options.coalesceKey).toBe("clip-lane-move:7");
+    act(() => root.unmount());
+  });
+
+  it("creates one batch per source file in a multi-file reorder", async () => {
+    const elements = ["clip-a", "clip-b", "clip-c"].map((id) => {
+      const element = document.createElement("div");
+      element.id = id;
+      document.body.appendChild(element);
+      return element;
+    });
+    const captured: CapturedBatchCall[] = [];
+    let commit: ReorderCommit | undefined;
+    const root = renderReorderHook(captured, (fn) => (commit = fn));
+
+    await act(async () => {
+      await commit!(
+        elements.map((element, index) => ({
+          element,
+          zIndex: index + 1,
+          id: element.id,
+          sourceFile: index < 2 ? "index.html" : "compositions/scene.html",
+        })),
+      );
+    });
+
+    expect(captured).toHaveLength(1);
+    expect(
+      captured[0]?.batches.map(({ sourceFile, patches }) => [sourceFile, patches.length]),
+    ).toEqual([
+      ["index.html", 2],
+      ["compositions/scene.html", 1],
+    ]);
+    act(() => root.unmount());
+  });
+
+  it("rolls back only live and store state after an atomic reorder failure", async () => {
+    const writeProjectFile = vi.fn(async () => {});
+    const recordEdit = vi.fn(async () => {});
+    const forceReloadSdkSession = vi.fn();
+    const originalError = new Error("second patch failed");
+    const elements = ["clip-a", "clip-b", "clip-c"].map((id, index) => {
+      const element = document.createElement("div");
+      element.id = id;
+      element.style.zIndex = String(index + 10);
+      document.body.appendChild(element);
+      return element;
+    });
+    usePlayerStore.getState().setElements(
+      elements.map((element, index) => ({
+        id: element.id,
+        tag: "div",
+        start: 0,
+        duration: 1,
+        track: index,
+        zIndex: index + 10,
+        hasExplicitZIndex: false,
+      })),
+    );
+
+    let commit: ReorderCommit | undefined;
+    function Harness() {
+      const { handleDomZIndexReorderCommit } = useElementLifecycleOps({
+        activeCompPath: "index.html",
+        showToast: vi.fn(),
+        writeProjectFile,
+        domEditSaveTimestampRef: { current: 0 },
+        editHistory: { recordEdit },
+        projectIdRef: { current: "demo" },
+        reloadPreview: vi.fn(),
+        clearDomSelection: vi.fn(),
+        forceReloadSdkSession,
+        commitDomEditPatchBatches: vi.fn(async () => {
+          throw originalError;
+        }),
+      });
+      commit = handleDomZIndexReorderCommit;
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+
+    let rejection: unknown;
+    await act(async () => {
+      try {
+        await commit!(
+          elements.map((element, index) => ({
+            element,
+            zIndex: 3 - index,
+            id: element.id,
+            sourceFile: "index.html",
+            key: element.id,
+          })),
+          "clip-lane-move:failure",
+        );
+      } catch (error) {
+        rejection = error;
+      }
+    });
+
+    expect(rejection).toBe(originalError);
+    expect(elements.map((element) => element.style.zIndex)).toEqual(["10", "11", "12"]);
+    expect(
+      usePlayerStore
+        .getState()
+        .elements.map(({ zIndex, hasExplicitZIndex }) => ({ zIndex, hasExplicitZIndex })),
+    ).toEqual([
+      { zIndex: 10, hasExplicitZIndex: false },
+      { zIndex: 11, hasExplicitZIndex: false },
+      { zIndex: 12, hasExplicitZIndex: false },
+    ]);
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    expect(recordEdit).not.toHaveBeenCalled();
+    expect(forceReloadSdkSession).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+});