@hyperframes/studio 0.7.92 → 0.7.93

package/src/hooks/useFileManager.projectOwnership.test.tsx

@@ -20,15 +20,65 @@ vi.mock("./useEditorSave", () => ({
   useEditorSave: () => ({
     saveRafRef: { current: null },
     handleContentChange: vi.fn(),
+    getPendingCandidate: vi.fn(() => null),
+    flushPendingSave: vi.fn(async () => ({ status: "clean" as const })),
+    discardPendingSave: vi.fn(),
   }),
 }));
 
 import { useFileManager } from "./useFileManager";
+import { resetStudioWriteTokens, studioFileContentVersion } from "../utils/studioFileVersion";
+import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
+function useTestFileManager(projectId: string) {
+  return useFileManager({
+    projectId,
+    showToast: vi.fn(),
+    recordEdit: vi.fn(async () => {}),
+    domEditSaveTimestampRef: { current: 0 },
+    setRefreshKey: vi.fn(),
+  });
+}
+
+async function mountTestFileManager(projectId = "project-a") {
+  const captured: { manager: ReturnType<typeof useFileManager> | null } = { manager: null };
+  function Probe() {
+    captured.manager = useTestFileManager(projectId);
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  await act(async () => root.render(<Probe />));
+  const manager = captured.manager;
+  if (!manager) throw new Error("file manager did not render");
+  return { manager, root };
+}
+
+async function mountOverwriteRequest(response: Response) {
+  const fetchMock = vi.fn((_url: string, init?: RequestInit) => {
+    if (init?.method !== "PUT") {
+      throw new Error("overwrite unexpectedly performed a preflight read");
+    }
+    return Promise.resolve(response);
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return { ...(await mountTestFileManager()), fetchMock };
+}
+
+function createOverwriteConflict(currentVersion: string | null, currentContent: string | null) {
+  return new StudioFileConflictError({
+    filePath: "index.html",
+    currentVersion,
+    currentContent,
+    attemptedContent: "STUDIO",
+  });
+}
+
 describe("useFileManager project ownership", () => {
   afterEach(() => {
+    resetStudioWriteTokens();
+    vi.useRealTimers();
     vi.unstubAllGlobals();
   });
 
@@ -54,13 +104,7 @@ describe("useFileManager project ownership", () => {
 
     const captured: { manager: ReturnType<typeof useFileManager> | null } = { manager: null };
     function Probe({ projectId }: { projectId: string }) {
-      captured.manager = useFileManager({
-        projectId,
-        showToast: vi.fn(),
-        recordEdit: vi.fn(async () => {}),
-        domEditSaveTimestampRef: { current: 0 },
-        setRefreshKey: vi.fn(),
-      });
+      captured.manager = useTestFileManager(projectId);
       return null;
     }
 
@@ -106,4 +150,92 @@ describe("useFileManager project ownership", () => {
 
     await act(async () => root.unmount());
   });
+
+  it("uses a fresh write token when a lost response retries a committed save", async () => {
+    vi.useFakeTimers();
+    let putAttempt = 0;
+    const fetchMock = vi.fn((_url: string, init?: RequestInit) => {
+      if (!init?.method) {
+        return Promise.resolve({
+          ok: true,
+          json: async () => ({ content: "BEFORE", version: "v1" }),
+        } as Response);
+      }
+      putAttempt += 1;
+      if (putAttempt === 1) return Promise.reject(new TypeError("response lost"));
+      return Promise.resolve({ ok: true, json: async () => ({ version: "v2" }) } as Response);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { manager, root } = await mountTestFileManager();
+    await manager.readProjectFile("index.html");
+
+    const write = manager.writeProjectFile("index.html", "AFTER");
+    await vi.runAllTimersAsync();
+    await write;
+
+    const writeTokens = fetchMock.mock.calls
+      .filter(([, init]) => init?.method === "PUT")
+      .map(([, init]) => new Headers(init?.headers).get("X-Hyperframes-Write-Token"));
+    expect(writeTokens).toHaveLength(2);
+    expect(writeTokens[0]).toBeTruthy();
+    expect(writeTokens[1]).not.toBe(writeTokens[0]);
+
+    await act(async () => root.unmount());
+  });
+
+  it("overwrites the exact external content version with an If-Match precondition", async () => {
+    const { manager, root, fetchMock } = await mountOverwriteRequest({
+      ok: true,
+      json: async () => ({ version: "v3" }),
+    } as Response);
+    const conflict = createOverwriteConflict("v2", "EXTERNAL");
+
+    await manager.overwriteExternalConflict(conflict);
+
+    const [, init] = fetchMock.mock.calls[0] ?? [];
+    const headers = new Headers(init?.headers);
+    expect(init).toMatchObject({ method: "PUT", body: "STUDIO" });
+    expect(headers.get("If-Match")).toBe(await studioFileContentVersion("EXTERNAL"));
+    expect(headers.get("If-None-Match")).toBeNull();
+    await act(async () => root.unmount());
+  });
+
+  it("preserves a newer third-party edit when a content-less conflict version is stale", async () => {
+    const { manager, root, fetchMock } = await mountOverwriteRequest({
+      ok: false,
+      status: 409,
+      json: async () => ({ currentVersion: "v3", currentContent: "THIRD PARTY" }),
+    } as Response);
+    const conflict = createOverwriteConflict("v2", null);
+
+    await expect(manager.overwriteExternalConflict(conflict)).rejects.toMatchObject({
+      name: "StudioFileConflictError",
+      currentVersion: "v3",
+      currentContent: "THIRD PARTY",
+      attemptedContent: "STUDIO",
+    });
+
+    const [, init] = fetchMock.mock.calls[0] ?? [];
+    const headers = new Headers(init?.headers);
+    expect(headers.get("If-Match")).toBe("v2");
+    expect(headers.get("If-None-Match")).toBeNull();
+    await act(async () => root.unmount());
+  });
+
+  it("uses create-only semantics when the conflicted file was deleted", async () => {
+    const { manager, root, fetchMock } = await mountOverwriteRequest({
+      ok: true,
+      json: async () => ({ version: "v1" }),
+    } as Response);
+    const conflict = createOverwriteConflict(null, null);
+
+    await manager.overwriteExternalConflict(conflict);
+
+    const [, init] = fetchMock.mock.calls[0] ?? [];
+    const headers = new Headers(init?.headers);
+    expect(headers.get("If-Match")).toBeNull();
+    expect(headers.get("If-None-Match")).toBe("*");
+    await act(async () => root.unmount());
+  });
 });

package/src/hooks/useFileManager.ts

@@ -10,7 +10,11 @@ import {
   StudioFileConflictError,
   StudioSaveNetworkError,
 } from "../utils/studioSaveDiagnostics";
-import { createStudioWriteToken, studioExpectedFileVersion } from "../utils/studioFileVersion";
+import {
+  createStudioWriteToken,
+  markStudioWriteToken,
+  studioExpectedFileVersion,
+} from "../utils/studioFileVersion";
 import { useFileTree } from "./useFileTree";
 import { useEditorSave } from "./useEditorSave";
 
@@ -117,8 +121,11 @@ export function useFileManager({
           throw await createStudioSaveHttpError(preflight, `Failed to read ${path} before save`);
         }
       }
-      const writeToken = createStudioWriteToken();
       await retryStudioSave(async () => {
+        // Each request gets its own receipt identity. If a committed request loses its response,
+        // the retry can produce a second filesystem receipt that must be suppressed independently.
+        const writeToken = createStudioWriteToken();
+        markStudioWriteToken(writeToken);
         let response: Response;
         try {
           response = await fetch(
@@ -191,7 +198,7 @@ export function useFileManager({
 
   // ── Editor save (debounced content change) ──
 
-  const { saveRafRef, handleContentChange } = useEditorSave({
+  const editorSave = useEditorSave({
     editingPathRef,
     projectIdRef,
     readProjectFile,
@@ -201,6 +208,24 @@ export function useFileManager({
     setRefreshKey,
     showToast,
   });
+  const { saveRafRef, handleContentChange } = editorSave;
+
+  const overwriteExternalConflict = useCallback(
+    async (conflict: StudioFileConflictError) => {
+      if (conflict.currentContent != null) {
+        await writeProjectFile(
+          conflict.filePath,
+          conflict.attemptedContent,
+          conflict.currentContent,
+        );
+      } else {
+        fileVersions.set(conflict.filePath, conflict.currentVersion);
+        await writeProjectFile(conflict.filePath, conflict.attemptedContent);
+      }
+      updateEditingFileContent(conflict.filePath, conflict.attemptedContent);
+    },
+    [fileVersions, updateEditingFileContent, writeProjectFile],
+  );
 
   // ── File select ──
 
@@ -491,11 +516,15 @@ export function useFileManager({
     editingPathRef,
     projectIdRef,
     saveRafRef,
+    flushPendingSourceSave: editorSave.flushPendingSave,
+    discardPendingSourceSave: editorSave.discardPendingSave,
+    getPendingSourceCandidate: editorSave.getPendingCandidate,
     importedFontAssetsRef,
 
     // Core I/O
     readProjectFile,
     writeProjectFile,
+    overwriteExternalConflict,
     readOptionalProjectFile,
     observeProjectFileVersion,
     updateEditingFileContent,

package/src/hooks/useGsapAnimationFetchFallback.ts

@@ -30,6 +30,11 @@ export type ElementAnimationsOutcome =
   | { kind: "fetch-error" }
   | { kind: "cold" };
 
+export interface GsapAnimationFetchOptions {
+  /** Refuse the edit when the parse endpoint is unavailable instead of treating it as no motion. */
+  failOnFetchError?: boolean;
+}
+
 /**
  * Classify a parse result for one element. Differentiates a hard fetch failure
  * (`parsed === null`) from a warm-but-empty cold parse (`animations.length === 0`)
@@ -44,32 +49,48 @@ export function selectElementAnimationsOrRetry(
   return { kind: "resolved", animations: getAnimationsForElement(parsed.animations, target) };
 }
 
+// Retry policy deliberately distinguishes cold parses from hard fetch errors.
+// fallow-ignore-next-line complexity
+async function fetchElementAnimationsWithRetry(
+  projectId: string,
+  gsapSourceFile: string,
+  target: { id: string | null; selector: string | null },
+  failOnFetchError: boolean,
+): Promise<GsapAnimation[]> {
+  let coldAttempts = 0;
+  let errorAttempts = 0;
+  for (;;) {
+    const parsed = await fetchParsedAnimations(projectId, gsapSourceFile);
+    const outcome = selectElementAnimationsOrRetry(parsed, target);
+    if (outcome.kind === "resolved") return outcome.animations;
+    if (outcome.kind === "fetch-error") {
+      if (errorAttempts >= FETCH_ERROR_RETRIES) {
+        if (failOnFetchError) throw new Error("GSAP animation ownership could not be verified");
+        return [];
+      }
+      errorAttempts++;
+      await delay(FETCH_ERROR_DELAY_MS);
+      continue;
+    }
+    if (coldAttempts >= COLD_PARSE_RETRIES) return [];
+    coldAttempts++;
+    await delay(COLD_PARSE_DELAY_MS);
+  }
+}
+
 export function useGsapAnimationFetchFallback(projectId: string | null, gsapSourceFile: string) {
   return useCallback(
-    (selection: DomEditSelection) => async (): Promise<GsapAnimation[]> => {
-      if (!projectId) return [];
-      const target = { id: selection.id ?? null, selector: selection.selector ?? null };
-      // A drag can fire before the async parse is warm; a cold parse must retry
-      // rather than fall through to the no-animation path (which duplicates the
-      // tween). A hard fetch error is a different failure — retry only briefly.
-      let coldAttempts = 0;
-      let errorAttempts = 0;
-      for (;;) {
-        const parsed = await fetchParsedAnimations(projectId, gsapSourceFile);
-        const outcome = selectElementAnimationsOrRetry(parsed, target);
-        if (outcome.kind === "resolved") return outcome.animations;
-        if (outcome.kind === "fetch-error") {
-          if (errorAttempts >= FETCH_ERROR_RETRIES) return [];
-          errorAttempts++;
-          await delay(FETCH_ERROR_DELAY_MS);
-          continue;
-        }
-        // cold
-        if (coldAttempts >= COLD_PARSE_RETRIES) return [];
-        coldAttempts++;
-        await delay(COLD_PARSE_DELAY_MS);
-      }
-    },
+    (selection: DomEditSelection, options?: GsapAnimationFetchOptions) =>
+      async (): Promise<GsapAnimation[]> => {
+        if (!projectId) return [];
+        const target = { id: selection.id ?? null, selector: selection.selector ?? null };
+        return fetchElementAnimationsWithRetry(
+          projectId,
+          gsapSourceFile,
+          target,
+          options?.failOnFetchError === true,
+        );
+      },
     [projectId, gsapSourceFile],
   );
 }

package/src/hooks/useGsapAwareEditing.test.tsx

@@ -14,6 +14,8 @@ const mocks = vi.hoisted(() => ({
   drag: vi.fn(),
   readPosition: vi.fn(),
   setPosition: vi.fn(),
+  commitAnimatedProperty: vi.fn(),
+  commitAnimatedProperties: vi.fn(),
 }));
 
 vi.mock("./gsapResizeIntercept", () => ({ tryGsapResizeIntercept: mocks.resize }));
@@ -28,8 +30,8 @@ vi.mock("./gsapPositionDetection", () => ({
 vi.mock("../utils/elementGsap", () => ({ setElementGsapPosition: mocks.setPosition }));
 vi.mock("./useAnimatedPropertyCommit", () => ({
   useAnimatedPropertyCommit: () => ({
-    commitAnimatedProperty: vi.fn(),
-    commitAnimatedProperties: vi.fn(),
+    commitAnimatedProperty: mocks.commitAnimatedProperty,
+    commitAnimatedProperties: mocks.commitAnimatedProperties,
   }),
 }));
 vi.mock("./useSafeGsapCommitMutation", () => ({
@@ -78,22 +80,51 @@ function mountResizeHandler(animations: GsapAnimation[]) {
   return { selection, fallback, commitMutation, resize: resize!, root };
 }
 
+type AwareEditingParams = Parameters<typeof useGsapAwareEditing>[0];
+
+function mountGroupHandler({
+  gsapCommitMutation,
+  makeFetchFallback,
+  trackGsapInteractionFailure = vi.fn(),
+}: Pick<AwareEditingParams, "gsapCommitMutation" | "makeFetchFallback"> &
+  Partial<Pick<AwareEditingParams, "trackGsapInteractionFailure">>) {
+  let groupCommit!: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void>;
+  function Harness() {
+    groupCommit = useGsapAwareEditing({
+      domEditSelection: null,
+      selectedGsapAnimations: [],
+      gsapCommitMutation,
+      previewIframeRef: { current: null },
+      showToast: vi.fn(),
+      bumpGsapCache: vi.fn(),
+      makeFetchFallback,
+      trackGsapInteractionFailure,
+      handleDomBoxSizeCommit: vi.fn(),
+      addGsapAnimation: vi.fn(),
+      convertToKeyframes: vi.fn(),
+      setArcPath: vi.fn(),
+      updateArcSegment: vi.fn(),
+    }).handleGsapAwareGroupPathOffsetCommit;
+    return null;
+  }
+  const root = mountReactHarness(<Harness />);
+  return { groupCommit: (updates: DomEditGroupPathOffsetCommit[]) => groupCommit(updates), root };
+}
+
 describe("useGsapAwareEditing anchored resize", () => {
-  it("forwards the anchor offset to the DOM fallback when GSAP does not handle resize", async () => {
-    mocks.resize.mockResolvedValue(false);
+  it("rejects a blocked resize instead of falling through to a competing DOM write", async () => {
+    mocks.resize.mockResolvedValue({ status: "blocked", reason: "source-uneditable" });
     const h = mountResizeHandler([]);
-    await act(() => h.resize(h.selection, { width: 300, height: 200 }, { x: -50, y: -25 }));
-    expect(h.fallback).toHaveBeenCalledWith(
-      h.selection,
-      { width: 300, height: 200 },
-      { x: -50, y: -25 },
-    );
+    await expect(
+      act(() => h.resize(h.selection, { width: 300, height: 200 }, { x: -50, y: -25 })),
+    ).rejects.toMatchObject({ reason: "source-uneditable" });
+    expect(h.fallback).not.toHaveBeenCalled();
     act(() => h.root.unmount());
   });
 
   it("persists the anchor exactly once through GSAP position when size route handles resize", async () => {
-    mocks.resize.mockResolvedValue(true);
-    mocks.drag.mockResolvedValue(true);
+    mocks.resize.mockResolvedValue({ status: "persisted" });
+    mocks.drag.mockResolvedValue({ status: "persisted" });
     const h = mountResizeHandler([]);
     await act(() => h.resize(h.selection, { width: 300, height: 200 }, { x: -50, y: -25 }));
     expect(h.fallback).not.toHaveBeenCalled();
@@ -103,12 +134,12 @@ describe("useGsapAwareEditing anchored resize", () => {
   });
 
   it("settles the live GSAP position before resize persistence reaches its first await", async () => {
-    let resolveResize!: (handled: boolean) => void;
-    const pendingResize = new Promise<boolean>((resolve) => {
+    let resolveResize!: (outcome: { status: "persisted" }) => void;
+    const pendingResize = new Promise<{ status: "persisted" }>((resolve) => {
       resolveResize = resolve;
     });
     mocks.resize.mockReturnValue(pendingResize);
-    mocks.drag.mockResolvedValue(true);
+    mocks.drag.mockResolvedValue({ status: "persisted" });
     mocks.readPosition.mockReturnValue({ x: 120.4, y: 80.2 });
     const h = mountResizeHandler([]);
     h.selection.element.setAttribute("data-hf-drag-gsap-base-x", "120.4");
@@ -126,7 +157,7 @@ describe("useGsapAwareEditing anchored resize", () => {
       mocks.resize.mock.invocationCallOrder[0]!,
     );
 
-    resolveResize(true);
+    resolveResize({ status: "persisted" });
     await act(() => commit);
     act(() => h.root.unmount());
   });
@@ -134,7 +165,7 @@ describe("useGsapAwareEditing anchored resize", () => {
   it("passes a transaction-scoped commit wrapper into the resize path", async () => {
     mocks.resize.mockImplementation(async (selection, _size, _animations, _iframe, commit) => {
       await commit(selection, { type: "resize" }, { label: "Resize", softReload: true });
-      return true;
+      return { status: "persisted" };
     });
     const h = mountResizeHandler([]);
 
@@ -164,9 +195,12 @@ describe("useGsapAwareEditing anchored resize", () => {
           m: unknown,
           o: { coalesceKey?: string; label?: string; softReload?: boolean },
         ) => Promise<void>,
+        _fetch: unknown,
+        options?: { preflightOnly?: boolean },
       ) => {
+        if (options?.preflightOnly) return { status: "persisted" };
         await commit(selection, { type: "move" }, { label: "Move", softReload: true });
-        return true;
+        return { status: "persisted" };
       },
     );
     const commitMutation = vi.fn(
@@ -175,26 +209,10 @@ describe("useGsapAwareEditing anchored resize", () => {
         return Promise.resolve();
       },
     );
-    let groupCommit!: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void>;
-    function Harness() {
-      groupCommit = useGsapAwareEditing({
-        domEditSelection: null,
-        selectedGsapAnimations: [],
-        gsapCommitMutation: commitMutation,
-        previewIframeRef: { current: null },
-        showToast: vi.fn(),
-        bumpGsapCache: vi.fn(),
-        makeFetchFallback: () => vi.fn().mockResolvedValue([]),
-        trackGsapInteractionFailure: vi.fn(),
-        handleDomBoxSizeCommit: vi.fn(),
-        addGsapAnimation: vi.fn(),
-        convertToKeyframes: vi.fn(),
-        setArcPath: vi.fn(),
-        updateArcSegment: vi.fn(),
-      }).handleGsapAwareGroupPathOffsetCommit;
-      return null;
-    }
-    const root = mountReactHarness(<Harness />);
+    const { groupCommit, root } = mountGroupHandler({
+      gsapCommitMutation: commitMutation,
+      makeFetchFallback: () => vi.fn().mockResolvedValue([]),
+    });
     const updates = [
       {
         selection: { element: document.createElement("div"), id: "a", selector: "#a" },
@@ -215,6 +233,74 @@ describe("useGsapAwareEditing anchored resize", () => {
     act(() => root.unmount());
   });
 
+  it("preflights every group member before the first mutation", async () => {
+    const commitMutation = vi.fn().mockResolvedValue(undefined);
+    const makeFetchFallback = vi.fn(() => vi.fn().mockResolvedValue([]));
+    mocks.drag.mockImplementation(
+      async (_selection, _next, _animations, _iframe, _commit, _fetch, options) => {
+        if (options?.preflightOnly) {
+          return _selection.id === "blocked"
+            ? { status: "blocked", reason: "source-uneditable" }
+            : { status: "persisted" };
+        }
+        await _commit(_selection, { type: "move" }, { label: "Move" });
+        return { status: "persisted" };
+      },
+    );
+    const { groupCommit, root } = mountGroupHandler({
+      gsapCommitMutation: commitMutation,
+      makeFetchFallback,
+    });
+    const updates = [
+      {
+        selection: { element: document.createElement("div"), id: "ok", selector: "#ok" },
+        next: { x: 10, y: 10 },
+      },
+      {
+        selection: {
+          element: document.createElement("div"),
+          id: "blocked",
+          selector: "#blocked",
+        },
+        next: { x: 10, y: 10 },
+      },
+    ] as unknown as DomEditGroupPathOffsetCommit[];
+
+    await expect(groupCommit(updates)).rejects.toMatchObject({
+      name: "GsapEditBlockedError",
+      reason: "source-uneditable",
+    });
+    expect(commitMutation).not.toHaveBeenCalled();
+    expect(mocks.drag).toHaveBeenCalledTimes(2);
+    expect(makeFetchFallback).toHaveBeenNthCalledWith(1, updates[0]!.selection, {
+      failOnFetchError: true,
+    });
+    expect(makeFetchFallback).toHaveBeenNthCalledWith(2, updates[1]!.selection, {
+      failOnFetchError: true,
+    });
+    act(() => root.unmount());
+  });
+
+  it("fails a group preflight closed when ownership cannot be fetched", async () => {
+    const fetchError = new Error("parse endpoint unavailable");
+    const commitMutation = vi.fn().mockResolvedValue(undefined);
+    const { groupCommit, root } = mountGroupHandler({
+      gsapCommitMutation: commitMutation,
+      makeFetchFallback: () => vi.fn().mockRejectedValue(fetchError),
+    });
+    const updates = [
+      {
+        selection: { element: document.createElement("div"), id: "a", selector: "#a" },
+        next: { x: 10, y: 10 },
+      },
+    ] as unknown as DomEditGroupPathOffsetCommit[];
+
+    await expect(groupCommit(updates)).rejects.toBe(fetchError);
+    expect(mocks.drag).not.toHaveBeenCalled();
+    expect(commitMutation).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+
   it("restores once when resize persistence fails", async () => {
     const error = new Error("resize failed");
     const restore = vi.fn();
@@ -228,7 +314,7 @@ describe("useGsapAwareEditing anchored resize", () => {
   });
 
   it("does not apply the anchor twice when scale route already settles the drop point", async () => {
-    mocks.resize.mockResolvedValue(true);
+    mocks.resize.mockResolvedValue({ status: "persisted" });
     const scale = { propertyGroup: "scale" } as GsapAnimation;
     const h = mountResizeHandler([scale]);
     await act(() => h.resize(h.selection, { width: 300, height: 200 }, { x: -50, y: -25 }));