@hyperframes/studio 0.7.56 → 0.7.58

package/src/hooks/useClipboard.ts

@@ -8,6 +8,7 @@ import { insertTimelineAssetIntoSource } from "../utils/timelineAssetDrop";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import type { EditHistoryKind } from "../utils/editHistory";
 import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
+import { findElementForSelection } from "../components/editor/domEditingElement";
 import { readFileContent } from "./timelineEditingHelpers";
 
 interface RecordEditInput {
@@ -34,6 +35,7 @@ interface UseClipboardOptions {
 function getElementOuterHtml(
   iframeRef: React.MutableRefObject<HTMLIFrameElement | null>,
   selection: DomEditSelection,
+  activeCompositionPath: string | null,
 ): string | null {
   let doc: Document | null = null;
   try {
@@ -43,15 +45,7 @@ function getElementOuterHtml(
   }
   if (!doc) return null;
 
-  let el: Element | null = null;
-  if (selection.id) {
-    el = doc.getElementById(selection.id);
-  }
-  if (!el && selection.selector) {
-    const matches = doc.querySelectorAll(selection.selector);
-    el = matches[selection.selectorIndex ?? 0] ?? null;
-  }
-  return el && "outerHTML" in el ? (el as Element).outerHTML : null;
+  return findElementForSelection(doc, selection, activeCompositionPath)?.outerHTML ?? null;
 }
 
 export function useClipboard({
@@ -71,6 +65,9 @@ export function useClipboard({
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
 
+  // The copy-mode branches predate this change; this diff only replaces its
+  // duplicated DOM lookup with the canonical composition-aware resolver.
+  // fallow-ignore-next-line complexity
   const handleCopy = useCallback((): boolean => {
     const { selectedElementId, elements } = usePlayerStore.getState();
 
@@ -84,13 +81,18 @@ export function useClipboard({
       try {
         const doc = previewIframeRef.current?.contentDocument;
         if (doc) {
-          let el: Element | null = null;
-          if (element.domId) el = doc.getElementById(element.domId);
-          if (!el && element.selector) {
-            const matches = doc.querySelectorAll(element.selector);
-            el = matches[element.selectorIndex ?? 0] ?? null;
-          }
-          if (el && "outerHTML" in el) html = (el as Element).outerHTML;
+          html =
+            findElementForSelection(
+              doc,
+              {
+                hfId: element.hfId,
+                id: element.domId,
+                selector: element.selector,
+                selectorIndex: element.selectorIndex,
+                sourceFile: targetPath,
+              },
+              activeCompPath,
+            )?.outerHTML ?? null;
         }
       } catch {
         // cross-origin frame
@@ -110,7 +112,7 @@ export function useClipboard({
     // DOM element copy
     const domSelection = domEditSelectionRef.current;
     if (domSelection) {
-      const html = getElementOuterHtml(previewIframeRef, domSelection);
+      const html = getElementOuterHtml(previewIframeRef, domSelection, activeCompPath);
       if (!html) {
         showToast("Unable to copy this element.", "info");
         return false;

package/src/hooks/useCompositionDimensions.ts

@@ -1,6 +1,33 @@
 import { useState } from "react";
 import { useMountEffect } from "./useMountEffect";
 import type { CompositionDimensions } from "../components/renders/RenderQueue";
+import { acceptStudioRuntimeMessage } from "../player/lib/runtimeProtocol";
+
+function readCompositionSizeMessage(data: unknown): CompositionDimensions | null {
+  if (!isStageSizeMessage(data)) return null;
+  const message = data;
+  if (!acceptStudioRuntimeMessage(message)) return null;
+  return readPositiveDimensions(message.width, message.height);
+}
+
+function isStageSizeMessage(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object") return false;
+  if (value === null) return false;
+  const message = value as Record<string, unknown>;
+  return message.source === "hf-preview" && message.type === "stage-size";
+}
+
+function readPositiveNumber(value: unknown): number | null {
+  if (typeof value !== "number") return null;
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+function readPositiveDimensions(width: unknown, height: unknown): CompositionDimensions | null {
+  const parsedWidth = readPositiveNumber(width);
+  const parsedHeight = readPositiveNumber(height);
+  if (parsedWidth === null || parsedHeight === null) return null;
+  return { width: parsedWidth, height: parsedHeight };
+}
 
 export function useCompositionDimensions() {
   const [compositionDimensions, setCompositionDimensions] = useState<CompositionDimensions | null>(
@@ -9,12 +36,12 @@ export function useCompositionDimensions() {
 
   useMountEffect(() => {
     const handleMessage = (e: MessageEvent) => {
-      const data = e.data;
-      if (data?.source !== "hf-preview" || data?.type !== "stage-size") return;
-      const { width, height } = data as { width: number; height: number };
-      if (!(width > 0) || !(height > 0)) return;
+      const dimensions = readCompositionSizeMessage(e.data);
+      if (!dimensions) return;
       setCompositionDimensions((prev) =>
-        prev && prev.width === width && prev.height === height ? prev : { width, height },
+        prev && prev.width === dimensions.width && prev.height === dimensions.height
+          ? prev
+          : dimensions,
       );
     };
     window.addEventListener("message", handleMessage);

package/src/hooks/useDomEditCommits.test.tsx

@@ -265,7 +265,7 @@ describe("useDomEditCommits z-index reorder persistence", () => {
     document.body.replaceChildren();
   });
 
-  it("persists an N-element reorder with one batch POST, one undo entry, and one reload", async () => {
+  it("persists an N-element reorder with one batch POST, one undo entry, and NO iframe reload", async () => {
     const original =
       '<div id="a" style="z-index: 1"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 3"></div>';
     const after =
@@ -276,18 +276,20 @@ describe("useDomEditCommits z-index reorder persistence", () => {
         _init?: Parameters<typeof fetch>[1],
       ): Promise<Response> => {
         const url = requestUrl(input);
-        if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: original });
-        if (url.includes("/file-mutations/patch-elements-batch/")) {
+        if (url.endsWith("/file-mutations/patch-element-batches")) {
           return jsonResponse({
-            ok: true,
-            changed: true,
-            matched: [true, true, true],
-            content: after,
+            durable: true,
+            files: [
+              {
+                sourceFile: "index.html",
+                changed: true,
+                matched: [true, true, true],
+                before: original,
+                after,
+              },
+            ],
           });
         }
-        if (url.includes("/file-mutations/patch-element/")) {
-          return jsonResponse({ ok: true, changed: true, matched: true, content: after });
-        }
         throw new Error(`Unexpected fetch: ${url}`);
       },
     );
@@ -317,39 +319,262 @@ describe("useDomEditCommits z-index reorder persistence", () => {
       });
 
       const batchPosts = fetchMock.mock.calls.filter(([input]) =>
-        requestUrl(input).includes("/file-mutations/patch-elements-batch/"),
+        requestUrl(input).endsWith("/file-mutations/patch-element-batches"),
       );
       const singlePosts = fetchMock.mock.calls.filter(([input]) =>
-        requestUrl(input).includes("/file-mutations/patch-element/"),
+        requestUrl(input).includes("/file-mutations/patch-elements-batch/"),
       );
       expect(batchPosts).toHaveLength(1);
       expect(singlePosts).toHaveLength(0);
       expect(JSON.parse(String(batchPosts[0]?.[1]?.body))).toEqual({
-        patches: expect.arrayContaining([
-          expect.objectContaining({ target: expect.objectContaining({ id: "a" }) }),
-          expect.objectContaining({ target: expect.objectContaining({ id: "b" }) }),
-          expect.objectContaining({ target: expect.objectContaining({ id: "c" }) }),
-        ]),
+        batches: [
+          {
+            sourceFile: "index.html",
+            patches: expect.arrayContaining([
+              expect.objectContaining({ target: expect.objectContaining({ id: "a" }) }),
+              expect.objectContaining({ target: expect.objectContaining({ id: "b" }) }),
+              expect.objectContaining({ target: expect.objectContaining({ id: "c" }) }),
+            ]),
+          },
+        ],
       });
       expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
       expect(rendered.recordEdit).toHaveBeenCalledWith({
         label: "Reorder layers",
         kind: "manual",
         coalesceKey: "z-reorder:test",
+        // Unbounded per-gesture fold window (keys are unique per gesture):
+        // the z entry and its mirror/lane counterpart fold across the server
+        // round-trip that separates them.
+        coalesceMs: Number.POSITIVE_INFINITY,
         files: { "index.html": { before: original, after } },
       });
+      // FIX: a z-only reorder must NOT remount the preview iframe ("the blink").
+      // The live DOM + store already hold the final state and the server matched
+      // every style-only patch, so the reload is provably redundant.
+      expect(rendered.reloadPreview).not.toHaveBeenCalled();
+    } finally {
+      rendered.cleanup();
+    }
+  });
+
+  it("falls back to reloading when the server response omits matched[]", async () => {
+    // Without a matched[] confirmation the persist can't be proven in sync with
+    // the live DOM — the skip-reload path must not engage.
+    const original = '<div id="a" style="z-index: 1"></div>';
+    const after = '<div id="a" style="z-index: 2"></div>';
+    const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
+      const url = requestUrl(input);
+      if (url.endsWith("/file-mutations/patch-element-batches")) {
+        return jsonResponse({
+          durable: true,
+          files: [{ sourceFile: "index.html", changed: true, before: original, after }],
+        });
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const { iframe, element } = createPreviewElement();
+    element.id = "a";
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      await act(async () => {
+        await rendered.hook.handleDomZIndexReorderCommit([
+          { element, zIndex: 2, id: "a", sourceFile: "index.html" },
+        ]);
+      });
+
+      expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
+      expect(rendered.reloadPreview).toHaveBeenCalledTimes(1);
+    } finally {
+      rendered.cleanup();
+    }
+  });
+
+  it("warns and reports telemetry for unmatched batch patches without throwing", async () => {
+    // The server reports per-patch matched[]: #b was not found in the source,
+    // so it atomically refuses the whole multi-file gesture. The reload
+    // reconverges the preview with disk while the lifecycle owner rolls back
+    // both optimistic writes.
+    const original = '<div id="a" style="z-index: 1"></div>';
+    const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
+      const url = requestUrl(input);
+      if (url.endsWith("/file-mutations/patch-element-batches")) {
+        return jsonResponse({
+          durable: false,
+          files: [
+            {
+              sourceFile: "index.html",
+              changed: false,
+              matched: [true, false],
+              before: original,
+              after: original,
+            },
+          ],
+        });
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { iframe, element } = createPreviewElement(
+      '<div data-hf-id="hf-card"></div><div id="b"></div>',
+    );
+    element.id = "a";
+    const second = iframe.contentDocument!.getElementById("b")!;
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      await act(async () => {
+        await rendered.hook.handleDomZIndexReorderCommit([
+          { element, zIndex: 2, id: "a", sourceFile: "index.html" },
+          { element: second, zIndex: 1, id: "b", sourceFile: "index.html" },
+        ]);
+      });
+
+      // No throw: incomplete durability rolls back both optimistic writes.
+      expect(element.style.zIndex).toBe("");
+      expect(second.style.zIndex).toBe("");
+      expect(rendered.recordEdit).not.toHaveBeenCalled();
+      expect(rendered.reloadPreview).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("could not match 1 patch target(s) in index.html"),
+        "b",
+      );
+      expect(trackStudioEvent).toHaveBeenCalledWith(
+        "save_failure",
+        expect.objectContaining({
+          mutation_type: "z-reorder-unmatched",
+          file_path: "index.html",
+          error_message: expect.stringContaining("b"),
+        }),
+      );
+    } finally {
+      warnSpy.mockRestore();
+      rendered.cleanup();
+    }
+  });
+
+  it("uses one atomic request and rolls back every file when one target is unmatched", async () => {
+    const indexOriginal = '<div id="a" style="z-index: 4"></div>';
+    const sceneOriginal = '<div id="b" style="z-index: 5"></div>';
+    const fetchMock = vi.fn(
+      async (
+        input: Parameters<typeof fetch>[0],
+        init?: Parameters<typeof fetch>[1],
+      ): Promise<Response> => {
+        const url = requestUrl(input);
+        if (url.endsWith("/file-mutations/patch-element-batches")) {
+          expect(JSON.parse(String(init?.body))).toEqual({
+            batches: [
+              expect.objectContaining({ sourceFile: "index.html" }),
+              expect.objectContaining({ sourceFile: "scene.html" }),
+            ],
+          });
+          return jsonResponse({
+            durable: false,
+            files: [
+              {
+                sourceFile: "index.html",
+                changed: false,
+                matched: [true],
+                before: indexOriginal,
+                after: indexOriginal,
+              },
+              {
+                sourceFile: "scene.html",
+                changed: false,
+                matched: [false],
+                before: sceneOriginal,
+                after: sceneOriginal,
+              },
+            ],
+          });
+        }
+        throw new Error(`Unexpected fetch: ${url}`);
+      },
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { iframe, element } = createPreviewElement(
+      '<div data-hf-id="hf-card" style="z-index: 4"></div><div id="b" style="z-index: 5"></div>',
+    );
+    element.id = "a";
+    const second = iframe.contentDocument!.getElementById("b")!;
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      let result:
+        | Awaited<ReturnType<typeof rendered.hook.handleDomZIndexReorderCommit>>
+        | undefined;
+      await act(async () => {
+        result = await rendered.hook.handleDomZIndexReorderCommit([
+          { element, zIndex: 8, id: "a", sourceFile: "index.html" },
+          { element: second, zIndex: 9, id: "b", sourceFile: "scene.html" },
+        ]);
+      });
+
+      expect(result).toEqual({ durable: false, allMatched: false, changed: false });
+      expect(element.style.zIndex).toBe("4");
+      expect(second.style.zIndex).toBe("5");
+      expect(rendered.recordEdit).not.toHaveBeenCalled();
+      expect(rendered.reloadPreview).toHaveBeenCalledTimes(1);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    } finally {
+      warnSpy.mockRestore();
+      rendered.cleanup();
+    }
+  });
+
+  it("reloads and reports non-durable when an unmatched batch changes no bytes", async () => {
+    const original = '<div id="a" style="z-index: 1"></div>';
+    const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
+      const url = requestUrl(input);
+      if (url.endsWith("/file-mutations/patch-element-batches")) {
+        return jsonResponse({
+          durable: false,
+          files: [
+            {
+              sourceFile: "index.html",
+              changed: false,
+              matched: [false],
+              before: original,
+              after: original,
+            },
+          ],
+        });
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const { iframe, element } = createPreviewElement();
+    element.id = "a";
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      let result:
+        | Awaited<ReturnType<typeof rendered.hook.handleDomZIndexReorderCommit>>
+        | undefined;
+      await act(async () => {
+        result = await rendered.hook.handleDomZIndexReorderCommit([
+          { element, zIndex: 2, id: "missing", sourceFile: "index.html" },
+        ]);
+      });
+
+      expect(result).toEqual({ durable: false, allMatched: false, changed: false });
+      expect(element.style.zIndex).toBe("");
+      expect(rendered.recordEdit).not.toHaveBeenCalled();
       expect(rendered.reloadPreview).toHaveBeenCalledTimes(1);
     } finally {
       rendered.cleanup();
     }
   });
 
-  it("rolls back live state after a failed batch POST without a disk write-back", async () => {
-    const original = '<div id="a" style="z-index: 7"></div><div id="b"></div>';
+  it("rolls back and reloads after a rejected batch POST", async () => {
     const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
       const url = requestUrl(input);
-      if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: original });
-      if (url.includes("/file-mutations/patch-elements-batch/")) {
+      if (url.endsWith("/file-mutations/patch-element-batches")) {
         return jsonResponse({ error: "batch rejected" }, 500);
       }
       throw new Error(`Unexpected fetch: ${url}`);
@@ -394,10 +619,154 @@ describe("useDomEditCommits z-index reorder persistence", () => {
       ]);
       expect(writeProjectFile).not.toHaveBeenCalled();
       expect(rendered.recordEdit).not.toHaveBeenCalled();
-      expect(rendered.reloadPreview).not.toHaveBeenCalled();
+      expect(rendered.reloadPreview).toHaveBeenCalledTimes(1);
+      expect(
+        fetchMock.mock.calls.filter(([input]) =>
+          requestUrl(input).endsWith("/file-mutations/patch-element-batches"),
+        ),
+      ).toHaveLength(1);
+    } finally {
+      rendered.cleanup();
+    }
+  });
+
+  it("reloads after the server commits but the aggregate response is lost", async () => {
+    const original = '<div data-hf-id="hf-card" id="a" style="z-index: 7"></div>';
+    const after = '<div data-hf-id="hf-card" id="a" style="z-index: 2"></div>';
+    let diskContent = original;
+    const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
+      const url = requestUrl(input);
+      if (url.endsWith("/file-mutations/patch-element-batches")) {
+        diskContent = after;
+        throw new TypeError("connection reset after commit");
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const { iframe, element } = createPreviewElement(original);
+    usePlayerStore.getState().setElements([
+      {
+        id: "a",
+        tag: "div",
+        start: 0,
+        duration: 1,
+        track: 0,
+        zIndex: 7,
+        hasExplicitZIndex: true,
+      },
+    ]);
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      let rejection: unknown;
+      await act(async () => {
+        try {
+          await rendered.hook.handleDomZIndexReorderCommit([
+            { element, zIndex: 2, id: "a", sourceFile: "index.html", key: "a" },
+          ]);
+        } catch (error) {
+          rejection = error;
+        }
+      });
+
+      expect(rejection).toBeInstanceOf(Error);
+      expect((rejection as Error).message).toContain("connection reset after commit");
+      expect(diskContent).toBe(after);
+      expect(element.style.zIndex).toBe("7");
+      expect(usePlayerStore.getState().elements[0]).toMatchObject({
+        zIndex: 7,
+        hasExplicitZIndex: true,
+      });
+      expect(rendered.recordEdit).not.toHaveBeenCalled();
+      expect(rendered.reloadPreview).toHaveBeenCalledTimes(1);
+      expect(
+        fetchMock.mock.calls.filter(([input]) =>
+          requestUrl(input).endsWith("/file-mutations/patch-element-batches"),
+        ),
+      ).toHaveLength(1);
+    } finally {
+      rendered.cleanup();
+    }
+  });
+
+  it.each([
+    [
+      "changed=false with different snapshots",
+      {
+        durable: true,
+        files: [
+          {
+            sourceFile: "index.html",
+            changed: false,
+            matched: [true],
+            before: '<div id="a" style="z-index: 1"></div>',
+            after: '<div id="a" style="z-index: 2"></div>',
+          },
+        ],
+      },
+    ],
+    [
+      "changed=true with identical snapshots",
+      {
+        durable: true,
+        files: [
+          {
+            sourceFile: "index.html",
+            changed: true,
+            matched: [true],
+            before: '<div id="a" style="z-index: 1"></div>',
+            after: '<div id="a" style="z-index: 1"></div>',
+          },
+        ],
+      },
+    ],
+    [
+      "durable=false with a changed file",
+      {
+        durable: false,
+        files: [
+          {
+            sourceFile: "index.html",
+            changed: true,
+            matched: [true],
+            before: '<div id="a" style="z-index: 1"></div>',
+            after: '<div id="a" style="z-index: 2"></div>',
+          },
+        ],
+      },
+    ],
+  ])("rejects and reloads for malformed 200 response: %s", async (_label, responseBody) => {
+    const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]): Promise<Response> => {
+      const url = requestUrl(input);
+      if (url.endsWith("/file-mutations/patch-element-batches")) {
+        return jsonResponse(responseBody);
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const { iframe, element } = createPreviewElement();
+    element.id = "a";
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      let rejection: unknown;
+      await act(async () => {
+        try {
+          await rendered.hook.handleDomZIndexReorderCommit([
+            { element, zIndex: 2, id: "a", sourceFile: "index.html", key: "a" },
+          ]);
+        } catch (error) {
+          rejection = error;
+        }
+      });
+
+      expect(rejection).toBeInstanceOf(Error);
+      expect((rejection as Error).message).toBe("Invalid atomic element patch response");
+      expect(rendered.recordEdit).not.toHaveBeenCalled();
+      expect(rendered.reloadPreview).toHaveBeenCalledTimes(1);
       expect(
         fetchMock.mock.calls.filter(([input]) =>
-          requestUrl(input).includes("/file-mutations/patch-elements-batch/"),
+          requestUrl(input).endsWith("/file-mutations/patch-element-batches"),
         ),
       ).toHaveLength(1);
     } finally {