@hyperframes/studio 0.8.23 → 0.8.25

package/src/hooks/useDomEditCommits.test.tsx

@@ -8,7 +8,9 @@ import type { DomEditSelection, DomEditTextField } from "../components/editor/do
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
 import { usePlayerStore } from "../player";
 import { StudioSaveHttpError } from "../utils/studioSaveDiagnostics";
+import { createDomEditSaveQueue } from "../utils/domEditSaveQueue";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import type { CutoverResult } from "../utils/sdkCutover";
 import { useDomEditCommits } from "./useDomEditCommits";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
@@ -22,6 +24,8 @@ interface PatchResponseBody {
   changed?: boolean;
   matched?: boolean;
   content?: string;
+  path?: string;
+  version?: string;
 }
 
 interface RenderedDomEditCommits {
@@ -35,6 +39,9 @@ interface RenderedDomEditCommits {
 interface RenderDomEditCommitsOptions {
   importedFontAssets?: ImportedFontAsset[];
   writeProjectFile?: (path: string, content: string, expectedContent?: string) => Promise<void>;
+  onTrySdkPersist?: () => Promise<CutoverResult>;
+  queueDomEditSave?: <T>(save: () => Promise<T>) => Promise<T>;
+  projectIdRef?: MutableRefObject<string | null>;
 }
 
 type FetchHandler = (
@@ -201,7 +208,7 @@ function renderDomEditCommits(
   const showToast = makeShowToast();
   const recordEdit = vi.fn(async () => {});
   const previewIframeRef: MutableRefObject<HTMLIFrameElement | null> = { current: iframe };
-  const projectIdRef: MutableRefObject<string | null> = { current: "p1" };
+  const projectIdRef: MutableRefObject<string | null> = options.projectIdRef ?? { current: "p1" };
   const domEditSaveTimestampRef: MutableRefObject<number> = { current: 0 };
   const reloadPreview = vi.fn();
 
@@ -210,7 +217,7 @@ function renderDomEditCommits(
       activeCompPath: "index.html",
       previewIframeRef,
       showToast,
-      queueDomEditSave: async (save) => save(),
+      queueDomEditSave: options.queueDomEditSave ?? (async (save) => save()),
       writeProjectFile: options.writeProjectFile ?? (async () => {}),
       domEditSaveTimestampRef,
       editHistory: { recordEdit },
@@ -224,6 +231,7 @@ function renderDomEditCommits(
       clearDomSelection: vi.fn(),
       refreshDomEditSelectionFromPreview: vi.fn(),
       buildDomSelectionFromTarget: vi.fn(async () => null),
+      onTrySdkPersist: options.onTrySdkPersist,
     });
     return null;
   }
@@ -772,11 +780,13 @@ async function commitStyleAgainst(response: Parameters<typeof stubPatchFetch>[0]
   const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
   const { iframe, element } = createPreviewElement();
   const rendered = renderDomEditCommits(createSelection(element), iframe);
+  let outcome: Awaited<ReturnType<typeof rendered.hook.handleDomStyleCommit>> | undefined;
   await act(async () => {
-    await rendered.hook.handleDomStyleCommit("color", "blue");
+    outcome = await rendered.hook.handleDomStyleCommit("color", "blue");
   });
   return {
     element,
+    outcome,
     rendered,
     warnSpy,
     cleanup: () => {
@@ -944,10 +954,12 @@ describe("useDomEditCommits style persist handling", () => {
   });
 
   it("warns without a toast when the server matched the element but reported no change", async () => {
-    const { rendered, warnSpy, cleanup } = await commitStyleAgainst({
+    const { rendered, outcome, warnSpy, cleanup } = await commitStyleAgainst({
       ok: true,
       changed: false,
       matched: true,
+      path: "index.html",
+      version: '"sha256:current"',
     });
 
     try {
@@ -956,6 +968,14 @@ describe("useDomEditCommits style persist handling", () => {
         "[Studio] DOM edit persist no-op",
         expect.objectContaining({ operations: "inline-style:color" }),
       );
+      expect(outcome).toEqual({
+        ok: true,
+        persistence: {
+          sourceFile: "index.html",
+          version: '"sha256:current"',
+          changed: false,
+        },
+      });
     } finally {
       cleanup();
     }
@@ -976,22 +996,203 @@ describe("useDomEditCommits style persist handling", () => {
   });
 
   it("keeps the optimistic style and records history when the patch succeeds", async () => {
-    const { element, rendered, cleanup } = await commitStyleAgainst({
+    const { element, rendered, outcome, cleanup } = await commitStyleAgainst({
       ok: true,
       changed: true,
       matched: true,
       content: '<div data-hf-id="hf-card" style="color: blue">Card</div>',
+      path: "index.html",
+      version: '"sha256:after"',
     });
 
     try {
       expect(rendered.showToast).not.toHaveBeenCalled();
       expect(element.style.getPropertyValue("color")).toBe("blue");
       expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
+      expect(outcome).toEqual({
+        ok: true,
+        persistence: {
+          sourceFile: "index.html",
+          version: '"sha256:after"',
+          changed: true,
+        },
+      });
     } finally {
       cleanup();
     }
   });
 
+  it("serializes the full read, write, and history transaction across overlapping commits", async () => {
+    const firstPatch = createDeferred<Response>();
+    let readCount = 0;
+    let patchCount = 0;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: Parameters<typeof fetch>[0]) => {
+        const url = requestUrl(input);
+        if (url.includes("/api/projects/p1/files/")) {
+          readCount += 1;
+          return jsonResponse({
+            content:
+              readCount === 1
+                ? '<div data-hf-id="hf-card" style="color: red">Card</div>'
+                : '<div data-hf-id="hf-card" style="color: blue">Card</div>',
+          });
+        }
+        if (url.includes("/api/projects/p1/file-mutations/patch-element/")) {
+          patchCount += 1;
+          if (patchCount === 1) return firstPatch.promise;
+          return jsonResponse({
+            ok: true,
+            changed: true,
+            matched: true,
+            content: '<div data-hf-id="hf-card" style="color: green">Card</div>',
+            path: "index.html",
+            version: '"sha256:green"',
+          });
+        }
+        throw new Error(`Unexpected fetch: ${url}`);
+      }),
+    );
+    const queue = createDomEditSaveQueue();
+    const { iframe, element } = createPreviewElement();
+    const rendered = renderDomEditCommits(createSelection(element), iframe, {
+      queueDomEditSave: queue.enqueue,
+    });
+
+    try {
+      const first = rendered.hook.handleDomStyleCommit("color", "blue");
+      await flushAsyncWork();
+      const second = rendered.hook.handleDomStyleCommit("color", "green");
+      await flushAsyncWork();
+
+      expect(readCount).toBe(1);
+      expect(patchCount).toBe(1);
+
+      firstPatch.resolve(
+        jsonResponse({
+          ok: true,
+          changed: true,
+          matched: true,
+          content: '<div data-hf-id="hf-card" style="color: blue">Card</div>',
+          path: "index.html",
+          version: '"sha256:blue"',
+        }),
+      );
+      await first;
+      await second;
+
+      expect(readCount).toBe(2);
+      expect(patchCount).toBe(2);
+      expect(rendered.recordEdit).toHaveBeenNthCalledWith(
+        1,
+        expect.objectContaining({
+          files: {
+            "index.html": expect.objectContaining({
+              before: expect.stringContaining("color: red"),
+              after: expect.stringContaining("color: blue"),
+            }),
+          },
+        }),
+      );
+      expect(rendered.recordEdit).toHaveBeenNthCalledWith(
+        2,
+        expect.objectContaining({
+          files: {
+            "index.html": expect.objectContaining({
+              before: expect.stringContaining("color: blue"),
+              after: expect.stringContaining("color: green"),
+            }),
+          },
+        }),
+      );
+    } finally {
+      queue.destroy();
+      rendered.cleanup();
+    }
+  });
+
+  it("refuses queued persistence after the active project changes", async () => {
+    const firstPatch = createDeferred<Response>();
+    const projectIdRef: MutableRefObject<string | null> = { current: "p1" };
+    const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0]) => {
+      const url = requestUrl(input);
+      if (url.includes("/api/projects/p1/files/")) {
+        return jsonResponse({
+          content: '<div data-hf-id="hf-card" style="color: red">Card</div>',
+        });
+      }
+      if (url.includes("/api/projects/p1/file-mutations/patch-element/")) {
+        return firstPatch.promise;
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const queue = createDomEditSaveQueue();
+    const { iframe, element } = createPreviewElement();
+    const rendered = renderDomEditCommits(createSelection(element), iframe, {
+      queueDomEditSave: queue.enqueue,
+      projectIdRef,
+    });
+
+    try {
+      const first = rendered.hook.handleDomStyleCommit("color", "blue");
+      await flushAsyncWork();
+      const second = rendered.hook.handleDomStyleCommit("color", "green");
+      projectIdRef.current = "p2";
+      firstPatch.resolve(
+        jsonResponse({
+          ok: true,
+          changed: true,
+          matched: true,
+          content: '<div data-hf-id="hf-card" style="color: blue">Card</div>',
+          path: "index.html",
+          version: '"sha256:blue"',
+        }),
+      );
+
+      await first;
+      await expect(second).resolves.toMatchObject({
+        ok: false,
+        reason: "persist-failed",
+      });
+      expect(fetchMock.mock.calls.some(([input]) => requestUrl(input).includes("/p2/"))).toBe(
+        false,
+      );
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    } finally {
+      queue.destroy();
+      rendered.cleanup();
+    }
+  });
+
+  it("preserves the SDK cutover version as the style commit's durable evidence", async () => {
+    const fetchMock = stubPatchFetch({ ok: true, changed: true, matched: true });
+    const { iframe, element } = createPreviewElement();
+    const rendered = renderDomEditCommits(createSelection(element), iframe, {
+      onTrySdkPersist: async () => ({ status: "committed", version: "sdk-version-2" }),
+    });
+
+    try {
+      let outcome: Awaited<ReturnType<typeof rendered.hook.handleDomStyleCommit>> | undefined;
+      await act(async () => {
+        outcome = await rendered.hook.handleDomStyleCommit("color", "blue");
+      });
+
+      expect(outcome).toEqual({
+        ok: true,
+        persistence: { sourceFile: "index.html", version: "sdk-version-2", changed: true },
+      });
+      expect(
+        fetchMock.mock.calls.some(([input]) =>
+          requestUrl(input).includes("/file-mutations/patch-element/"),
+        ),
+      ).toBe(false);
+    } finally {
+      rendered.cleanup();
+    }
+  });
+
   it("keeps a newer style value when an older overlapping commit later fails", async () => {
     const firstPatch = createDeferred<Response>();
     const secondPatch = createDeferred<Response>();
@@ -1466,9 +1667,7 @@ describe("useDomEditCommits attribute persist handling", () => {
       // optimistic apply) and succeeds before the older one rejects. Without the
       // per-key version guard, the stale rejection would revert to the older
       // commit's own previousValue (null) and stomp the newer commit's value.
-      const firstCommit = act(async () => {
-        await rendered.hook.handleDomHtmlAttributeCommit("muted", "first-value");
-      });
+      const firstCommit = rendered.hook.handleDomHtmlAttributeCommit("muted", "first-value");
       await act(async () => {
         await rendered.hook.handleDomHtmlAttributeCommit("muted", "second-value");
       });

package/src/hooks/useDomEditCommits.ts

@@ -32,7 +32,7 @@ import {
   patchElementBatches,
   readErrorResponseBody,
 } from "./useDomEditCommitsHelpers";
-import { cutoverCommittedOrThrow, type CutoverResult } from "../utils/sdkCutover";
+import type { CutoverResult } from "../utils/sdkCutover";
 import { studioWriteHeaders } from "../utils/studioFileVersion";
 interface RecordEditInput {
   label: string;
@@ -139,11 +139,18 @@ export function useDomEditCommits({
   const reportedUnresolvableRef = useRef(new Set<string>());
 
   // fallow-ignore-next-line complexity
-  const persistDomEditOperations: PersistDomEditOperations = useCallback(
+  const performPersistDomEditOperations = useCallback(
     // fallow-ignore-next-line complexity
-    async (selection, operations, options) => {
-      const pid = projectIdRef.current;
-      if (!pid) throw new Error("No active project");
+    async (
+      selection: DomEditSelection,
+      operations: PatchOperation[],
+      options: Parameters<PersistDomEditOperations>[2],
+      expectedProjectId: string,
+    ) => {
+      if (projectIdRef.current !== expectedProjectId) {
+        throw new Error("Active project changed before the edit could be saved");
+      }
+      const pid = expectedProjectId;
       if (options?.shouldSave && !options.shouldSave()) return;
 
       const targetPath = selection.sourceFile || activeCompPath || "index.html";
@@ -160,6 +167,10 @@ export function useDomEditCommits({
         throw new Error(`Missing file contents for ${targetPath}`);
       }
 
+      if (projectIdRef.current !== expectedProjectId) {
+        throw new Error("Active project changed before the edit could be saved");
+      }
+
       if (options?.shouldSave && !options.shouldSave()) return;
 
       // Validate layout values BEFORE any persist path runs. The SDK cutover
@@ -186,10 +197,11 @@ export function useDomEditCommits({
           coalesceKey: options?.coalesceKey,
           skipRefresh: options?.skipRefresh,
         });
-        if (cutoverCommittedOrThrow(cutover)) {
+        if (cutover.status === "failed") throw cutover.error;
+        if (cutover.status === "committed") {
           // SDK handled it — its in-memory doc is already current, so do NOT
           // forceReload (that would echo-reload the session we just wrote).
-          return;
+          return { sourceFile: targetPath, version: cutover.version, changed: true };
         }
       }
 
@@ -218,6 +230,8 @@ export function useDomEditCommits({
         changed?: boolean;
         matched?: boolean;
         content?: string;
+        path?: string;
+        version?: string;
       };
 
       if (!patchData.changed) {
@@ -235,7 +249,9 @@ export function useDomEditCommits({
           throw new DomEditPersistUnresolvableError(targetPath);
         }
         warnDomEditPersistNoOp(selection, operations);
-        return;
+        return typeof patchData.path === "string" && typeof patchData.version === "string"
+          ? { sourceFile: patchData.path, version: patchData.version, changed: false }
+          : undefined;
       }
 
       const patchedContent =
@@ -273,6 +289,11 @@ export function useDomEditCommits({
       if (!options?.skipRefresh) {
         reloadPreview();
       }
+      return finalContent === patchedContent &&
+        typeof patchData.path === "string" &&
+        typeof patchData.version === "string"
+        ? { sourceFile: patchData.path, version: patchData.version, changed: true }
+        : undefined;
     },
     [
       activeCompPath,
@@ -287,15 +308,30 @@ export function useDomEditCommits({
     ],
   );
 
+  const persistDomEditOperations: PersistDomEditOperations = useCallback(
+    (selection, operations, options) => {
+      const expectedProjectId = projectIdRef.current;
+      if (!expectedProjectId) return Promise.reject(new Error("No active project"));
+      return queueDomEditSave(() =>
+        performPersistDomEditOperations(selection, operations, options, expectedProjectId),
+      );
+    },
+    [performPersistDomEditOperations, projectIdRef, queueDomEditSave],
+  );
+
   const commitDomEditPatchBatches: CommitDomEditPatchBatches = useCallback(
-    (batches, options) =>
-      queueDomEditSave(
+    (batches, options) => {
+      const expectedProjectId = projectIdRef.current;
+      if (!expectedProjectId) return Promise.reject(new Error("No active project"));
+      return queueDomEditSave(
         // One queued transaction owns validation, persistence, history, reload,
         // and its durable result; splitting those phases risks partial commits.
         // fallow-ignore-next-line complexity
         async () => {
-          const pid = projectIdRef.current;
-          if (!pid) throw new Error("No active project");
+          if (projectIdRef.current !== expectedProjectId) {
+            throw new Error("Active project changed before the edit could be saved");
+          }
+          const pid = expectedProjectId;
           const unsafeFields = batches.flatMap((batch) =>
             batch.patches.flatMap((patch) => findUnsafeDomPatchValues(patch)),
           );
@@ -357,7 +393,8 @@ export function useDomEditCommits({
           label: options.label,
         });
         throw error;
-      }),
+      });
+    },
     [
       domEditSaveTimestampRef,
       editHistory,
@@ -373,12 +410,14 @@ export function useDomEditCommits({
 
   const {
     handleDomStyleCommit,
+    handleDomStyleCommitForSelection,
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
     handleDomAttributeQuietCommit,
     handleDomHtmlAttributeCommit,
     handleDomAttributesCommit,
     handleDomTextCommit,
+    handleDomTextCommitForSelection,
     handleDomRichTextCommit,
     commitDomTextFields,
     handleDomTextFieldStyleCommit,
@@ -401,7 +440,6 @@ export function useDomEditCommits({
   const commitPositionPatchToHtml = useDomEditPositionPatchCommit({
     activeCompPath,
     persistDomEditOperations,
-    queueDomEditSave,
     showToast,
   });
 
@@ -439,12 +477,14 @@ export function useDomEditCommits({
   return {
     resolveImportedFontAsset,
     handleDomStyleCommit,
+    handleDomStyleCommitForSelection,
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
     handleDomAttributeQuietCommit,
     handleDomHtmlAttributeCommit,
     handleDomAttributesCommit,
     handleDomTextCommit,
+    handleDomTextCommitForSelection,
     handleDomRichTextCommit,
     commitDomTextFields,
     handleDomTextFieldStyleCommit,

package/src/hooks/useDomEditPositionPatchCommit.test.tsx

@@ -55,14 +55,13 @@ function renderCommit(params: Parameters<typeof useDomEditPositionPatchCommit>[0
   return captured.commit;
 }
 
-function paramsWith(queueDomEditSave: (save: () => Promise<void>) => Promise<void>) {
+function paramsWith(persistDomEditOperations: () => Promise<undefined>) {
   const showToast = vi.fn();
   return {
     showToast,
     params: {
       activeCompPath: "index.html",
-      persistDomEditOperations: vi.fn().mockResolvedValue(undefined),
-      queueDomEditSave,
+      persistDomEditOperations,
       showToast,
     },
   };
@@ -104,7 +103,7 @@ describe("useDomEditPositionPatchCommit", () => {
   });
 
   it("resolves when the write lands", async () => {
-    const { showToast, params } = paramsWith((save) => save());
+    const { showToast, params } = paramsWith(() => Promise.resolve(undefined));
     const commit = renderCommit(params);
 
     await act(async () => {

package/src/hooks/useDomEditPositionPatchCommit.ts

@@ -8,7 +8,6 @@ import type { PersistDomEditOperations } from "./domEditCommitTypes";
 interface UseDomEditPositionPatchCommitParams {
   activeCompPath: string | null;
   persistDomEditOperations: PersistDomEditOperations;
-  queueDomEditSave: (save: () => Promise<void>) => Promise<void>;
   showToast: (message: string, tone?: "error" | "info") => void;
 }
 
@@ -22,39 +21,38 @@ interface PositionPatchOptions {
 export function useDomEditPositionPatchCommit({
   activeCompPath,
   persistDomEditOperations,
-  queueDomEditSave,
   showToast,
 }: UseDomEditPositionPatchCommitParams) {
   return useCallback(
     (selection: DomEditSelection, patches: PatchOperation[], options: PositionPatchOptions) => {
-      return queueDomEditSave(async () => {
-        await persistDomEditOperations(selection, patches, {
-          label: options.label,
-          coalesceKey: options.coalesceKey,
-          coalesceMs: options.coalesceMs,
-          skipRefresh: options.skipRefresh ?? true,
+      return persistDomEditOperations(selection, patches, {
+        label: options.label,
+        coalesceKey: options.coalesceKey,
+        coalesceMs: options.coalesceMs,
+        skipRefresh: options.skipRefresh ?? true,
+      })
+        .then(() => undefined)
+        .catch((error) => {
+          // A paused save queue is not worth a toast: the paused-save banner is
+          // already on screen, and one toast per blocked edit is what this branch
+          // exists to prevent. It still has to REJECT, though. Swallowing it
+          // resolved the commit, which skipped the caller's revert, so the element
+          // stayed where the drag put it while nothing reached the file.
+          if (error instanceof DomEditSaveQueueOpenError) throw error;
+          showToast(error instanceof Error ? error.message : "Failed to save position");
+          trackStudioSaveFailure({
+            source: "dom_edit",
+            error,
+            filePath: selection.sourceFile ?? activeCompPath ?? "index.html",
+            mutationType: "position",
+            label: options.label,
+            targetId: selection.id,
+            targetSelector: selection.selector,
+            targetSourceFile: selection.sourceFile,
+          });
+          throw error;
         });
-      }).catch((error) => {
-        // A paused save queue is not worth a toast: the paused-save banner is
-        // already on screen, and one toast per blocked edit is what this branch
-        // exists to prevent. It still has to REJECT, though. Swallowing it
-        // resolved the commit, which skipped the caller's revert, so the element
-        // stayed where the drag put it while nothing reached the file.
-        if (error instanceof DomEditSaveQueueOpenError) throw error;
-        showToast(error instanceof Error ? error.message : "Failed to save position");
-        trackStudioSaveFailure({
-          source: "dom_edit",
-          error,
-          filePath: selection.sourceFile ?? activeCompPath ?? "index.html",
-          mutationType: "position",
-          label: options.label,
-          targetId: selection.id,
-          targetSelector: selection.selector,
-          targetSourceFile: selection.sourceFile,
-        });
-        throw error;
-      });
     },
-    [activeCompPath, persistDomEditOperations, queueDomEditSave, showToast],
+    [activeCompPath, persistDomEditOperations, showToast],
   );
 }

package/src/hooks/useDomEditSession.ts

@@ -227,12 +227,14 @@ export function useDomEditSession({
   const {
     resolveImportedFontAsset,
     handleDomStyleCommit,
+    handleDomStyleCommitForSelection,
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
     handleDomAttributeQuietCommit,
     handleDomHtmlAttributeCommit,
     handleDomAttributesCommit,
     handleDomTextCommit,
+    handleDomTextCommitForSelection,
     handleDomRichTextCommit,
     handleDomTextFieldStyleCommit,
     handleDomAddTextField,
@@ -478,6 +480,7 @@ export function useDomEditSession({
     onClickToSource,
   });
   const {
+    getGsapAnimationsForSelection,
     handleGsapAwarePathOffsetCommit,
     handleGsapAwareGroupPathOffsetCommit,
     handleGsapAwareBoxSizeCommit,
@@ -506,7 +509,6 @@ export function useDomEditSession({
   const { handleUpdateSegmentEase, handleUpdateKeyframeEase, handleSetAllKeyframeEases } =
     useKeyframeEaseCommits({ gsapCommitMutation, domEditSelectionRef });
   return {
-    // State
     domEditSelection,
     domEditGroupSelections,
     domEditHoverSelection,
@@ -515,7 +517,6 @@ export function useDomEditSession({
     agentModalAnchorPoint,
     copiedAgentPrompt,
     agentPromptSelectionContext,
-    // Refs
     domEditSelectionRef,
     // Callbacks
     handleTimelineElementSelect,
@@ -525,6 +526,7 @@ export function useDomEditSession({
     applyDomSelection,
     clearDomSelection,
     handleDomStyleCommit,
+    handleDomStyleCommitForSelection,
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
     handleDomAttributeQuietCommit,
@@ -537,10 +539,12 @@ export function useDomEditSession({
     handleDomRotationCommit: handleGsapAwareRotationCommit,
     handleDomManualEditsReset,
     handleDomTextCommit,
+    handleDomTextCommitForSelection,
     handleDomRichTextCommit,
     handleDomTextFieldStyleCommit,
     handleDomAddTextField,
     handleDomRemoveTextField,
+    getGsapAnimationsForSelection,
     handleAskAgent,
     handleAgentModalSubmit,
     handleBlockedDomMove,