@hyperframes/studio 0.7.55 → 0.7.56

package/src/hooks/useBlockHandlers.ts

@@ -2,7 +2,7 @@
  * Block drop/add handlers for the Studio.
  * Extracted from App.tsx to keep file sizes under the 600-line limit.
  */
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
 import { addBlockToProject } from "../utils/blockInstaller";
@@ -83,17 +83,41 @@ export function useBlockHandlers({
     ],
   );
 
+  // Block installs hit the server and end in a full preview reload; without a
+  // guard, repeat drops while one is in flight stack duplicate installs.
+  const installingBlockRef = useRef(false);
+  const runBlockInstall = useCallback(
+    async <T>(blockName: string, install: () => Promise<T>): Promise<T | null> => {
+      if (installingBlockRef.current) {
+        blockCtx.showToast("A block is already installing — one moment…", "info");
+        return null;
+      }
+      installingBlockRef.current = true;
+      blockCtx.showToast(`Adding ${blockName}…`, "info");
+      try {
+        return await install();
+      } finally {
+        installingBlockRef.current = false;
+      }
+    },
+    [blockCtx],
+  );
+
   const handleAddBlock = useCallback(
     (blockName: string) => {
       if (!projectId) return;
+      // fallow-ignore-next-line complexity
       void (async () => {
-        const result = await addBlockToProject({
-          projectId,
-          blockName,
-          ...blockCtx,
-          previewIframe: previewIframeRef.current,
-          currentTime: usePlayerStore.getState().currentTime,
-        });
+        const result = await runBlockInstall(blockName, () =>
+          addBlockToProject({
+            projectId,
+            blockName,
+            ...blockCtx,
+            previewIframe: previewIframeRef.current,
+            currentTime: usePlayerStore.getState().currentTime,
+          }),
+        );
+        if (result === null) return;
         const params = result?.block.type === "hyperframes:block" ? result.block.params : undefined;
         if (params?.length) {
           setActiveBlockParams({
@@ -107,37 +131,41 @@ export function useBlockHandlers({
         }
       })();
     },
-    [projectId, blockCtx, previewIframeRef, setRightCollapsed, setRightPanelTab],
+    [projectId, blockCtx, previewIframeRef, runBlockInstall, setRightCollapsed, setRightPanelTab],
   );
 
   const handleTimelineBlockDrop = useCallback(
     (blockName: string, placement: { start: number; track: number }) => {
       if (!projectId) return;
-      void addBlockToProject({
-        projectId,
-        blockName,
-        placement,
-        ...blockCtx,
-        previewIframe: previewIframeRef.current,
-        currentTime: usePlayerStore.getState().currentTime,
-      });
+      void runBlockInstall(blockName, () =>
+        addBlockToProject({
+          projectId,
+          blockName,
+          placement,
+          ...blockCtx,
+          previewIframe: previewIframeRef.current,
+          currentTime: usePlayerStore.getState().currentTime,
+        }),
+      );
     },
-    [projectId, blockCtx, previewIframeRef],
+    [projectId, blockCtx, previewIframeRef, runBlockInstall],
   );
 
   const handlePreviewBlockDrop = useCallback(
     (blockName: string, position: { left: number; top: number }) => {
       if (!projectId) return;
-      void addBlockToProject({
-        projectId,
-        blockName,
-        visualPosition: position,
-        ...blockCtx,
-        previewIframe: previewIframeRef.current,
-        currentTime: usePlayerStore.getState().currentTime,
-      });
+      void runBlockInstall(blockName, () =>
+        addBlockToProject({
+          projectId,
+          blockName,
+          visualPosition: position,
+          ...blockCtx,
+          previewIframe: previewIframeRef.current,
+          currentTime: usePlayerStore.getState().currentTime,
+        }),
+      );
     },
-    [projectId, blockCtx, previewIframeRef],
+    [projectId, blockCtx, previewIframeRef, runBlockInstall],
   );
 
   return {

package/src/hooks/useContextMenuDismiss.ts

@@ -1,26 +1,50 @@
 import { useCallback, useEffect, useRef, type RefObject } from "react";
 
 /**
- * Shared dismiss logic for context menus: closes on outside click or Escape.
- * Returns a ref to attach to the menu container element.
+ * Shared dismiss logic for context menus: closes on ANY pointerdown outside the
+ * menu (mouse, pen, or touch), or Escape.
+ *
+ * Two failure modes this guards against, both seen in the canvas editor:
+ *
+ * 1. The menu lives inside DomEditOverlay, whose own pointer handlers call
+ *    `event.stopPropagation()` on several branches (marquee start, shift-select).
+ *    A bubble-phase `mousedown`/`pointerdown` listener on `document` never fires
+ *    for those events — the overlay eats them first — so the menu stayed open.
+ *    Listening in the CAPTURE phase runs this dismiss BEFORE any bubble-phase
+ *    stopPropagation, so an outside press always closes the menu.
+ *
+ * 2. `mousedown` alone misses pointer/touch-only gestures. `pointerdown` is the
+ *    superset (fires for mouse, pen, and touch) and is exactly the event the
+ *    overlay itself acts on, so hooking it here dismisses on the same press that
+ *    starts a canvas gesture — no second click required.
  */
 export function useContextMenuDismiss(onClose: () => void): RefObject<HTMLDivElement | null> {
   const menuRef = useRef<HTMLDivElement>(null);
 
   const dismiss = useCallback(
-    (e: MouseEvent | KeyboardEvent) => {
-      if (e instanceof KeyboardEvent && e.key !== "Escape") return;
-      if (e instanceof MouseEvent && menuRef.current?.contains(e.target as Node)) return;
+    (e: PointerEvent | MouseEvent | KeyboardEvent) => {
+      if (e instanceof KeyboardEvent) {
+        if (e.key === "Escape") onClose();
+        return;
+      }
+      // Any press inside the menu is a menu interaction — leave it open (the
+      // item's own handler will close it after acting).
+      if (menuRef.current?.contains(e.target as Node)) return;
       onClose();
     },
     [onClose],
   );
 
   useEffect(() => {
-    document.addEventListener("mousedown", dismiss);
+    // Capture phase so overlay/iframe-side handlers that stopPropagation on the
+    // bubble phase can't swallow the dismiss. `pointerdown` covers mouse + touch
+    // + pen; keep `mousedown` too for any synthetic-mouse path that skips it.
+    document.addEventListener("pointerdown", dismiss, true);
+    document.addEventListener("mousedown", dismiss, true);
     document.addEventListener("keydown", dismiss);
     return () => {
-      document.removeEventListener("mousedown", dismiss);
+      document.removeEventListener("pointerdown", dismiss, true);
+      document.removeEventListener("mousedown", dismiss, true);
       document.removeEventListener("keydown", dismiss);
     };
   }, [dismiss]);

package/src/hooks/useDomEditCommits.test.tsx

@@ -6,6 +6,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { MutableRefObject } from "react";
 import type { DomEditSelection, DomEditTextField } from "../components/editor/domEditing";
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
+import { usePlayerStore } from "../player";
 import { StudioSaveHttpError } from "../utils/studioSaveDiagnostics";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { useDomEditCommits } from "./useDomEditCommits";
@@ -27,6 +28,7 @@ interface RenderedDomEditCommits {
   hook: ReturnType<typeof useDomEditCommits>;
   showToast: ReturnType<typeof makeShowToast>;
   recordEdit: ReturnType<typeof vi.fn<() => Promise<void>>>;
+  reloadPreview: ReturnType<typeof vi.fn>;
   cleanup: () => void;
 }
 
@@ -209,6 +211,7 @@ function renderDomEditCommits(
   const previewIframeRef: MutableRefObject<HTMLIFrameElement | null> = { current: iframe };
   const projectIdRef: MutableRefObject<string | null> = { current: "p1" };
   const domEditSaveTimestampRef: MutableRefObject<number> = { current: 0 };
+  const reloadPreview = vi.fn();
 
   function Probe() {
     captured.current = useDomEditCommits({
@@ -223,7 +226,7 @@ function renderDomEditCommits(
       importedFontAssetsRef: { current: options.importedFontAssets ?? [] },
       projectId: "p1",
       projectIdRef,
-      reloadPreview: vi.fn(),
+      reloadPreview,
       domEditSelection: selection,
       applyDomSelection: vi.fn(),
       clearDomSelection: vi.fn(),
@@ -244,6 +247,7 @@ function renderDomEditCommits(
     hook: captured.current,
     showToast,
     recordEdit,
+    reloadPreview,
     cleanup: () => {
       act(() => {
         root.unmount();
@@ -253,6 +257,155 @@ function renderDomEditCommits(
   } satisfies RenderedDomEditCommits;
 }
 
+describe("useDomEditCommits z-index reorder persistence", () => {
+  beforeEach(() => {
+    ensureCssEscape();
+    vi.clearAllMocks();
+    vi.unstubAllGlobals();
+    document.body.replaceChildren();
+  });
+
+  it("persists an N-element reorder with one batch POST, one undo entry, and one 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 =
+      '<div id="a" style="z-index: 3"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 1"></div>';
+    const fetchMock = vi.fn(
+      async (
+        input: Parameters<typeof fetch>[0],
+        _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/")) {
+          return jsonResponse({
+            ok: true,
+            changed: true,
+            matched: [true, true, true],
+            content: after,
+          });
+        }
+        if (url.includes("/file-mutations/patch-element/")) {
+          return jsonResponse({ ok: true, changed: true, matched: true, content: after });
+        }
+        throw new Error(`Unexpected fetch: ${url}`);
+      },
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    const { iframe, element } = createPreviewElement(
+      '<div data-hf-id="hf-card"></div><div id="b"></div><div id="c"></div>',
+    );
+    element.id = "a";
+    const elements = [
+      element,
+      iframe.contentDocument!.getElementById("b")!,
+      iframe.contentDocument!.getElementById("c")!,
+    ];
+    const rendered = renderDomEditCommits(createSelection(element), iframe);
+
+    try {
+      await act(async () => {
+        await rendered.hook.handleDomZIndexReorderCommit(
+          elements.map((item, index) => ({
+            element: item,
+            zIndex: 3 - index,
+            id: item.id,
+            sourceFile: "index.html",
+          })),
+          "z-reorder:test",
+        );
+      });
+
+      const batchPosts = fetchMock.mock.calls.filter(([input]) =>
+        requestUrl(input).includes("/file-mutations/patch-elements-batch/"),
+      );
+      const singlePosts = fetchMock.mock.calls.filter(([input]) =>
+        requestUrl(input).includes("/file-mutations/patch-element/"),
+      );
+      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" }) }),
+        ]),
+      });
+      expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
+      expect(rendered.recordEdit).toHaveBeenCalledWith({
+        label: "Reorder layers",
+        kind: "manual",
+        coalesceKey: "z-reorder:test",
+        files: { "index.html": { before: original, after } },
+      });
+      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>';
+    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/")) {
+        return jsonResponse({ error: "batch rejected" }, 500);
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const writeProjectFile = vi.fn(async () => {});
+    const { iframe, element } = createPreviewElement(
+      '<div data-hf-id="hf-card" style="z-index: 7"></div><div id="b"></div>',
+    );
+    element.id = "a";
+    const second = iframe.contentDocument!.getElementById("b")!;
+    usePlayerStore.getState().setElements([
+      { id: "a", tag: "div", start: 0, duration: 1, track: 0, zIndex: 7, hasExplicitZIndex: true },
+      { id: "b", tag: "div", start: 0, duration: 1, track: 1, zIndex: 0, hasExplicitZIndex: false },
+    ]);
+    const rendered = renderDomEditCommits(createSelection(element), iframe, { writeProjectFile });
+
+    try {
+      let rejection: unknown;
+      await act(async () => {
+        try {
+          await rendered.hook.handleDomZIndexReorderCommit([
+            { element, zIndex: 2, id: "a", sourceFile: "index.html", key: "a" },
+            { element: second, zIndex: 1, id: "b", sourceFile: "index.html", key: "b" },
+          ]);
+        } catch (error) {
+          rejection = error;
+        }
+      });
+
+      expect(rejection).toBeInstanceOf(Error);
+      expect((rejection as Error).message).toContain("batch rejected");
+      expect(element.style.zIndex).toBe("7");
+      expect(second.style.zIndex).toBe("");
+      expect(
+        usePlayerStore
+          .getState()
+          .elements.map(({ zIndex, hasExplicitZIndex }) => ({ zIndex, hasExplicitZIndex })),
+      ).toEqual([
+        { zIndex: 7, hasExplicitZIndex: true },
+        { zIndex: 0, hasExplicitZIndex: false },
+      ]);
+      expect(writeProjectFile).not.toHaveBeenCalled();
+      expect(rendered.recordEdit).not.toHaveBeenCalled();
+      expect(rendered.reloadPreview).not.toHaveBeenCalled();
+      expect(
+        fetchMock.mock.calls.filter(([input]) =>
+          requestUrl(input).includes("/file-mutations/patch-elements-batch/"),
+        ),
+      ).toHaveLength(1);
+    } finally {
+      rendered.cleanup();
+    }
+  });
+});
+
 async function commitStyleAgainst(response: Parameters<typeof stubPatchFetch>[0]) {
   stubPatchFetch(response);
   const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});

package/src/hooks/useDomEditCommits.ts

@@ -4,11 +4,19 @@ import { FONT_EXT } from "../utils/mediaTypes";
 
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { primaryFontFamilyValue } from "../utils/studioFontHelpers";
-import { createStudioSaveHttpError } from "../utils/studioSaveDiagnostics";
+import {
+  createStudioSaveHttpError,
+  StudioSaveHttpError,
+  trackStudioSaveFailure,
+} from "../utils/studioSaveDiagnostics";
 import { buildDomEditPatchTarget, type DomEditSelection } from "../components/editor/domEditing";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
-import type { PersistDomEditOperations } from "./domEditCommitTypes";
+import type {
+  CommitDomEditPatchBatches,
+  DomEditPatchBatch,
+  PersistDomEditOperations,
+} from "./domEditCommitTypes";
 import type { PatchOperation } from "../utils/sourcePatcher";
 import {
   DomEditPersistUnsafeValueError,
@@ -20,6 +28,7 @@ import { useDomEditTextCommits } from "./useDomEditTextCommits";
 import { useDomGeometryCommits } from "./useDomGeometryCommits";
 import { useElementLifecycleOps } from "./useElementLifecycleOps";
 import { formatFieldsSuffix } from "./gsapScriptCommitHelpers";
+import { readProjectFileContent } from "../utils/studioFileHistory";
 
 // ── Helpers ──
 
@@ -48,9 +57,36 @@ interface RecordEditInput {
   label: string;
   kind: EditHistoryKind;
   coalesceKey?: string;
+  coalesceMs?: number;
   files: Record<string, { before: string; after: string }>;
 }
 
+async function patchElementBatch(projectId: string, batch: DomEditPatchBatch) {
+  const before = await readProjectFileContent(projectId, batch.sourceFile);
+  const response = await fetch(
+    `/api/projects/${encodeURIComponent(projectId)}/file-mutations/patch-elements-batch/${encodeURIComponent(batch.sourceFile)}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ patches: batch.patches }),
+    },
+  );
+  if (!response.ok) {
+    const rejection = await readErrorResponseBody(response);
+    throw new StudioSaveHttpError(formatPatchRejectionMessage(rejection), response.status);
+  }
+  const result = (await response.json()) as {
+    changed?: boolean;
+    content?: string;
+  };
+  return {
+    sourceFile: batch.sourceFile,
+    changed: result.changed === true,
+    before,
+    after: typeof result.content === "string" ? result.content : before,
+  };
+}
+
 export interface UseDomEditCommitsParams {
   activeCompPath: string | null;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
@@ -271,6 +307,7 @@ export function useDomEditCommits({
         label: options?.label ?? "Edit layer",
         kind: "manual",
         coalesceKey: options?.coalesceKey,
+        coalesceMs: options?.coalesceMs,
         files: { [targetPath]: { before: originalContent, after: finalContent } },
       });
       forceReloadSdkSession?.();
@@ -292,6 +329,66 @@ export function useDomEditCommits({
     ],
   );
 
+  const commitDomEditPatchBatches: CommitDomEditPatchBatches = useCallback(
+    (batches, options) =>
+      queueDomEditSave(async () => {
+        const pid = projectIdRef.current;
+        if (!pid) throw new Error("No active project");
+        const unsafeFields = batches.flatMap((batch) =>
+          batch.patches.flatMap((patch) => findUnsafeDomPatchValues(patch)),
+        );
+        if (unsafeFields.length > 0) {
+          showToast("Couldn't save edit because it contains invalid layout values", "error");
+          throw new DomEditPersistUnsafeValueError(
+            `DOM patch contains unsafe values: ${formatUnsafeFieldList(unsafeFields)}`,
+            { alreadyToasted: true },
+          );
+        }
+
+        domEditSaveTimestampRef.current = Date.now();
+        const results = await Promise.all(batches.map((batch) => patchElementBatch(pid, batch)));
+        const files = Object.fromEntries(
+          results
+            .filter((result) => result.changed)
+            .map((result) => [result.sourceFile, { before: result.before, after: result.after }]),
+        );
+        if (Object.keys(files).length === 0) return;
+        await editHistory.recordEdit({
+          label: options.label,
+          kind: "manual",
+          coalesceKey: options.coalesceKey,
+          files,
+        });
+        forceReloadSdkSession?.();
+        reloadPreview();
+      }).catch((error) => {
+        const alreadyToasted =
+          (error instanceof StudioSaveHttpError ||
+            error instanceof DomEditPersistUnsafeValueError) &&
+          error.alreadyToasted;
+        if (!alreadyToasted) {
+          showToast(error instanceof Error ? error.message : "Failed to reorder layers", "error");
+        }
+        trackStudioSaveFailure({
+          source: "dom_edit",
+          error,
+          filePath: batches.map((batch) => batch.sourceFile).join(","),
+          mutationType: "z-reorder",
+          label: options.label,
+        });
+        throw error;
+      }),
+    [
+      domEditSaveTimestampRef,
+      editHistory,
+      forceReloadSdkSession,
+      projectIdRef,
+      queueDomEditSave,
+      reloadPreview,
+      showToast,
+    ],
+  );
+
   // ── Text & style commits (delegated to useDomEditTextCommits) ──
 
   const {
@@ -352,7 +449,7 @@ export function useDomEditCommits({
     onTrySdkDelete,
     onReorderShadow,
     forceReloadSdkSession,
-    commitPositionPatchToHtml,
+    commitDomEditPatchBatches,
   });
 
   return {

package/src/hooks/useDomEditPositionPatchCommit.ts

@@ -15,6 +15,7 @@ interface UseDomEditPositionPatchCommitParams {
 interface PositionPatchOptions {
   label: string;
   coalesceKey: string;
+  coalesceMs?: number;
   skipRefresh?: boolean;
 }
 
@@ -30,6 +31,7 @@ export function useDomEditPositionPatchCommit({
         await persistDomEditOperations(selection, patches, {
           label: options.label,
           coalesceKey: options.coalesceKey,
+          coalesceMs: options.coalesceMs,
           skipRefresh: options.skipRefresh ?? true,
         });
       }).catch((error) => {

package/src/hooks/useDomEditSession.ts

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
 import { trackStudioEvent } from "../utils/studioTelemetry";
-import type { TimelineElement } from "../player";
+import type { SelectElementOptions, TimelineElement } from "../player";
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
 import type { RightPanelTab } from "../utils/studioHelpers";
@@ -38,7 +38,7 @@ export interface UseDomEditSessionParams {
   compositionLoading: boolean;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
   timelineElements: TimelineElement[];
-  setSelectedTimelineElementId: (id: string | null) => void;
+  setSelectedTimelineElementId: (id: string | null, options?: SelectElementOptions) => void;
   setRightCollapsed: (collapsed: boolean) => void;
   setRightPanelTab: (tab: RightPanelTab) => void;
   showToast: (message: string, tone?: "error" | "info") => void;