npm - @hyperframes/studio - Versions diffs - 0.7.58 → 0.7.59 - Mend

@hyperframes/studio 0.7.58 → 0.7.59

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (156) hide show

package/dist/assets/{hyperframes-player-CtTDO63S.js → hyperframes-player-Bm07FLkl.js} +1 -1
package/dist/assets/{index-C47jAC3Q.js → index-B995FG46.js} +1 -1
package/dist/assets/index-CrkAdJkb.js +426 -0
package/dist/assets/index-Dj5p8U_A.css +1 -0
package/dist/assets/{index-DeQPzqwH.js → index-FvzmPhfG.js} +1 -1
package/dist/index.d.ts +12 -3
package/dist/index.html +2 -2
package/dist/index.js +13514 -8528
package/dist/index.js.map +1 -1
package/dist/styles/tailwind-preset.d.ts +5 -0
package/dist/styles/tailwind-preset.js +8 -1
package/dist/styles/tailwind-preset.js.map +1 -1
package/package.json +7 -7
package/src/App.tsx +3 -3
package/src/components/DesignPanelPromoteProvider.tsx +15 -2
package/src/components/StudioRightPanel.tsx +29 -51
package/src/components/editor/AnimationCard.test.tsx +134 -0
package/src/components/editor/AnimationCard.tsx +19 -4
package/src/components/editor/ArcPathControls.tsx +1 -0
package/src/components/editor/GestureRecordControl.tsx +7 -1
package/src/components/editor/GsapAnimationSection.tsx +109 -14
package/src/components/editor/InspectorHeaderActions.tsx +42 -4
package/src/components/editor/PropertyPanel.test.tsx +948 -0
package/src/components/editor/PropertyPanel.tsx +144 -148
package/src/components/editor/PropertyPanelEmptyState.test.tsx +74 -0
package/src/components/editor/PropertyPanelEmptyState.tsx +179 -1
package/src/components/editor/PropertyPanelFlat.tsx +580 -0
package/src/components/editor/PropertyPanelFlatFooter.test.tsx +83 -0
package/src/components/editor/PropertyPanelFlatFooter.tsx +73 -0
package/src/components/editor/PropertyPanelFlatHeader.test.tsx +79 -0
package/src/components/editor/PropertyPanelFlatHeader.tsx +112 -0
package/src/components/editor/gsapAnimationCallbacks.ts +27 -0
package/src/components/editor/gsapLivePreview.ts +34 -0
package/src/components/editor/manualEditingAvailability.test.ts +10 -0
package/src/components/editor/manualEditingAvailability.ts +9 -0
package/src/components/editor/propertyPanel3dTransform.tsx +5 -0
package/src/components/editor/propertyPanelColor.test.tsx +28 -0
package/src/components/editor/propertyPanelColor.tsx +31 -1
package/src/components/editor/propertyPanelColorGradingControls.tsx +11 -2
package/src/components/editor/propertyPanelColorGradingSection.tsx +45 -365
package/src/components/editor/propertyPanelColorGradingSlider.tsx +19 -5
package/src/components/editor/propertyPanelFill.tsx +22 -5
package/src/components/editor/propertyPanelFlatColorGradingSection.test.tsx +622 -0
package/src/components/editor/propertyPanelFlatColorGradingSection.tsx +570 -0
package/src/components/editor/propertyPanelFlatLayoutSection.test.tsx +293 -0
package/src/components/editor/propertyPanelFlatLayoutSection.tsx +383 -0
package/src/components/editor/propertyPanelFlatMaskInsetRows.tsx +102 -0
package/src/components/editor/propertyPanelFlatMediaSection.test.tsx +436 -0
package/src/components/editor/propertyPanelFlatMediaSection.tsx +286 -0
package/src/components/editor/propertyPanelFlatMotionSection.test.tsx +272 -0
package/src/components/editor/propertyPanelFlatMotionSection.tsx +315 -0
package/src/components/editor/propertyPanelFlatPrimitives.test.tsx +1174 -0
package/src/components/editor/propertyPanelFlatPrimitives.tsx +563 -0
package/src/components/editor/propertyPanelFlatSelectRow.tsx +101 -0
package/src/components/editor/propertyPanelFlatStyleHelpers.test.ts +23 -0
package/src/components/editor/propertyPanelFlatStyleHelpers.ts +27 -0
package/src/components/editor/propertyPanelFlatStyleSections.test.tsx +598 -0
package/src/components/editor/propertyPanelFlatStyleSections.tsx +516 -0
package/src/components/editor/propertyPanelFlatTextSection.test.tsx +465 -0
package/src/components/editor/propertyPanelFlatTextSection.tsx +407 -0
package/src/components/editor/propertyPanelFlatTimingDerivation.test.ts +71 -0
package/src/components/editor/propertyPanelFlatTimingDerivation.ts +59 -0
package/src/components/editor/propertyPanelFlatToggle.test.tsx +63 -0
package/src/components/editor/propertyPanelFlatToggle.tsx +53 -0
package/src/components/editor/propertyPanelFont.test.tsx +30 -0
package/src/components/editor/propertyPanelFont.tsx +136 -95
package/src/components/editor/propertyPanelHelpers.ts +73 -0
package/src/components/editor/propertyPanelInputCoverage.test.tsx +587 -0
package/src/components/editor/propertyPanelMediaSection.tsx +10 -0
package/src/components/editor/propertyPanelPrimitives.tsx +60 -29
package/src/components/editor/propertyPanelSections.test.tsx +161 -0
package/src/components/editor/propertyPanelSections.tsx +154 -90
package/src/components/editor/propertyPanelStyleSections.tsx +12 -1
package/src/components/editor/propertyPanelTimingSection.tsx +1 -1
package/src/components/editor/propertyPanelTypes.ts +14 -1
package/src/components/editor/propertyPanelValueTier.test.ts +32 -0
package/src/components/editor/propertyPanelValueTier.ts +28 -0
package/src/components/editor/useColorGradingController.test.ts +418 -0
package/src/components/editor/useColorGradingController.ts +596 -0
package/src/components/panels/VariablesPanel.tsx +4 -0
package/src/components/sidebar/CompositionsTab.test.ts +28 -2
package/src/components/sidebar/CompositionsTab.tsx +3 -1
package/src/components/storyboard/FramePoster.tsx +24 -4
package/src/components/storyboard/StoryboardFrameFocus.tsx +4 -0
package/src/components/storyboard/StoryboardFrameTile.tsx +30 -1
package/src/components/storyboard/StoryboardGrid.tsx +23 -1
package/src/components/storyboard/StoryboardLoaded.tsx +58 -2
package/src/components/storyboard/StoryboardView.tsx +9 -2
package/src/components/storyboard/frameComments.test.ts +95 -0
package/src/components/storyboard/frameComments.ts +115 -0
package/src/components/storyboard/useFrameComments.ts +82 -0
package/src/contexts/DesignPanelInputContext.test.tsx +81 -0
package/src/contexts/DesignPanelInputContext.tsx +48 -0
package/src/contexts/DomEditContext.tsx +4 -0
package/src/contexts/VariablePromoteContext.test.tsx +67 -0
package/src/contexts/VariablePromoteContext.tsx +10 -5
package/src/hooks/domEditCommitRunner.ts +11 -0
package/src/hooks/gsapScriptCommitTypes.ts +6 -4
package/src/hooks/timelineTrackVisibility.test.ts +52 -0
package/src/hooks/timelineTrackVisibility.ts +27 -10
package/src/hooks/useAppHotkeys.ts +9 -0
package/src/hooks/useDomEditAttributeCommits.ts +123 -1
package/src/hooks/useDomEditCommits.ts +29 -175
package/src/hooks/useDomEditCommitsHelpers.ts +158 -0
package/src/hooks/useDomEditSession.ts +17 -5
package/src/hooks/useDomEditTextCommits.ts +14 -9
package/src/hooks/useDomEditWiring.ts +10 -9
package/src/hooks/useElementLifecycleOps.ts +8 -3
package/src/hooks/useFileManager.projectOwnership.test.tsx +98 -0
package/src/hooks/useFileManager.ts +82 -60
package/src/hooks/useGsapAnimationOps.ts +7 -6
package/src/hooks/useGsapKeyframeOps.ts +6 -5
package/src/hooks/useGsapPropertyDebounce.ts +43 -28
package/src/hooks/useGsapPropertyDebounceFlush.test.ts +35 -0
package/src/hooks/useGsapScriptCommits.test.tsx +48 -2
package/src/hooks/useGsapScriptCommits.ts +150 -50
package/src/hooks/useGsapSelectionHandlers.test.tsx +116 -0
package/src/hooks/useGsapSelectionHandlers.ts +94 -31
package/src/hooks/useInspectorSplitResize.ts +51 -0
package/src/hooks/usePersistentEditHistory.projectOwnership.test.tsx +60 -0
package/src/hooks/usePersistentEditHistory.test.ts +49 -1
package/src/hooks/usePersistentEditHistory.ts +71 -31
package/src/hooks/useProjectCompositionVariables.ts +10 -10
package/src/hooks/useProjectSignaturePoll.test.tsx +135 -0
package/src/hooks/useProjectSignaturePoll.ts +68 -0
package/src/hooks/useSdkSession.lifecycle.test.tsx +137 -0
package/src/hooks/useSdkSession.ts +155 -14
package/src/hooks/useSlideshowPersist.ts +7 -1
package/src/hooks/useStoryboard.ts +23 -4
package/src/hooks/useTimelineEditing.test.tsx +4 -1
package/src/hooks/useTimelineEditing.ts +16 -10
package/src/hooks/useTimelineEditingTypes.ts +3 -0
package/src/hooks/useTimelineGroupEditing.ts +16 -2
package/src/hooks/useVariablesPersist.ts +9 -7
package/src/icons/SystemIcons.tsx +2 -0
package/src/styles/studio.css +22 -0
package/src/styles/tailwind-preset.shared.js +7 -0
package/src/utils/designInputTracking.test.ts +97 -0
package/src/utils/designInputTracking.ts +80 -0
package/src/utils/sdkCutover.gate.test.ts +7 -7
package/src/utils/sdkCutover.test.ts +490 -57
package/src/utils/sdkCutover.ts +181 -219
package/src/utils/sdkEditTransaction.ts +292 -0
package/src/utils/sdkResolverAttempts.ts +94 -0
package/src/utils/sdkResolverShadow.test.ts +148 -0
package/src/utils/sdkResolverShadow.ts +139 -106
package/src/utils/setSlideshowManifest.test.ts +0 -9
package/src/utils/setSlideshowManifest.ts +20 -27
package/src/utils/studioFileHistory.test.ts +41 -0
package/src/utils/studioFileHistory.ts +30 -27
package/src/utils/studioFileMutationCoordinator.ts +45 -0
package/src/utils/studioHelpers.test.ts +45 -0
package/src/utils/studioHelpers.ts +45 -14
package/src/utils/studioSaveDiagnostics.ts +17 -0
package/dist/assets/index-B_UvTX3E.js +0 -423
package/dist/assets/index-uahwWkgw.css +0 -1

package/src/utils/sdkCutover.test.ts CHANGED Viewed

@@ -6,6 +6,9 @@ import {
   sdkTimingPersist,
   sdkGsapTweenPersist,
   sdkGsapKeyframePersist,
+  cutoverCommittedOrThrow,
+  persistSdkCandidateMutation,
+  persistSdkSerialize,
 } from "./sdkCutover";
 import { openComposition } from "@hyperframes/sdk";
 import { createMemoryAdapter } from "@hyperframes/sdk/adapters/memory";
@@ -44,6 +47,14 @@ const htmlAttrOp = (property: string, value: string): PatchOperation => ({
   value,
 });
+const candidateTestDeps = () => ({
+  publishSession: vi.fn(),
+  createCandidateSession: async (
+    _serialized: string,
+    live: Parameters<typeof sdkCutoverPersist>[4],
+  ) => live!,
+});
 describe("shouldUseSdkCutover", () => {
   it("returns false when flag disabled", () => {
     expect(shouldUseSdkCutover(false, true, "hf-abc", [styleOp("color", "red")])).toBe(false);
@@ -148,6 +159,7 @@ describe("sdkCutoverPersist", () => {
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
     domEditSaveTimestampRef: makeRef(0),
+    ...candidateTestDeps(),
     ...overrides,
   });
@@ -175,7 +187,7 @@ describe("sdkCutoverPersist", () => {
       null,
       deps,
     );
-    expect(result).toBe(false);
+    expect(result.status).toBe("declined");
   });
   it("returns false when element not found in session", async () => {
@@ -190,7 +202,7 @@ describe("sdkCutoverPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(false);
+    expect(result.status).toBe("declined");
   });
   it("dispatches setStyle for inline-style ops", async () => {
@@ -205,7 +217,7 @@ describe("sdkCutoverPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(true);
+    expect(result.status).toBe("committed");
     expect(session!.dispatch).toHaveBeenCalledWith({
       type: "setStyle",
       target: "hf-abc",
@@ -227,7 +239,7 @@ describe("sdkCutoverPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(true);
+    expect(result.status).toBe("committed");
     expect(session!.dispatch).toHaveBeenCalledWith({
       type: "setText",
       target: "hf-abc",
@@ -251,7 +263,7 @@ describe("sdkCutoverPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(false);
+    expect(result.status).toBe("declined");
     expect(session!.dispatch).not.toHaveBeenCalled();
     expect(deps.writeProjectFile).not.toHaveBeenCalled();
   });
@@ -268,7 +280,7 @@ describe("sdkCutoverPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(true);
+    expect(result.status).toBe("committed");
     expect(session!.dispatch).toHaveBeenCalledWith({
       type: "setAttribute",
       target: "hf-abc",
@@ -289,7 +301,7 @@ describe("sdkCutoverPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(true);
+    expect(result.status).toBe("committed");
     expect(session!.dispatch).toHaveBeenCalledWith({
       type: "setAttribute",
       target: "hf-abc",
@@ -337,7 +349,7 @@ describe("sdkCutoverPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(false);
+    expect(result.status).toBe("failed");
     expect(deps.reloadPreview).not.toHaveBeenCalled();
   });
@@ -376,12 +388,430 @@ describe("sdkCutoverPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(false);
+    expect(result.status).toBe("failed");
     expect(deps.writeProjectFile).not.toHaveBeenCalled();
     expect(deps.reloadPreview).not.toHaveBeenCalled();
   });
 });
+describe("transactional SDK candidate publication", () => {
+  const html = `<!DOCTYPE html><html data-composition-variables='[]'><body>
+<div data-hf-id="hf-stage" data-hf-root><div data-hf-id="hf-box" data-start="0" data-duration="1"></div>
+<script>var tl = gsap.timeline({ paused: true });
+tl.to('[data-hf-id="hf-box"]', { duration: 1, x: 100 }, 0);
+window.__timelines = { main: tl };</script></div>
+</body></html>`;
+  it.each([
+    [
+      "style",
+      (session: Awaited<ReturnType<typeof openComposition>>) =>
+        session.setStyle("hf-box", { color: "red" }),
+    ],
+    [
+      "timing",
+      (session: Awaited<ReturnType<typeof openComposition>>) =>
+        session.setTiming("hf-box", { start: 2 }),
+    ],
+    [
+      "delete",
+      (session: Awaited<ReturnType<typeof openComposition>>) => session.removeElement("hf-box"),
+    ],
+    [
+      "variables",
+      (session: Awaited<ReturnType<typeof openComposition>>) =>
+        session.declareVariable({ id: "title", type: "string", label: "Title", default: "Hello" }),
+    ],
+    [
+      "grouping/structure",
+      (session: Awaited<ReturnType<typeof openComposition>>) =>
+        session.addElement(null, 0, '<div data-hf-group="group-1"></div>'),
+    ],
+    [
+      "GSAP",
+      (session: Awaited<ReturnType<typeof openComposition>>) => {
+        const animationId = session.getElement("hf-box")?.animationIds[0];
+        if (!animationId) throw new Error("missing fixture animation");
+        session.setGsapTween(animationId, { ease: "power2.in" });
+      },
+    ],
+  ])(
+    "restores disk and keeps the live session unchanged when %s history fails",
+    async (_name, mutate) => {
+      const live = await openComposition(html, { history: false });
+      const liveBefore = live.serialize();
+      let disk = html;
+      const publishSession = vi.fn();
+      const result = await persistSdkCandidateMutation(
+        live,
+        "/comp.html",
+        html,
+        {
+          editHistory: { recordEdit: vi.fn().mockRejectedValue(new Error("history failed")) },
+          writeProjectFile: vi.fn(async (_path: string, content: string) => {
+            disk = content;
+          }),
+          reloadPreview: vi.fn(),
+          domEditSaveTimestampRef: { current: 0 },
+          publishSession,
+        },
+        mutate,
+        { label: `Edit ${_name}` },
+      );
+      expect(result.status).toBe("failed");
+      expect(disk).toBe(html);
+      expect(live.serialize()).toBe(liveBefore);
+      expect(publishSession).not.toHaveBeenCalled();
+      expect(() => cutoverCommittedOrThrow(result)).toThrow("history failed");
+      live.dispose();
+    },
+  );
+  it("disposes a mutated real candidate and leaves the live session unpublished when the write fails", async () => {
+    const live = await openComposition(html, { history: false });
+    const liveBefore = live.serialize();
+    let candidate: Awaited<ReturnType<typeof openComposition>> | undefined;
+    let disposeCandidate: ReturnType<typeof vi.spyOn> | undefined;
+    const publishSession = vi.fn().mockReturnValue("published");
+    const writeError = new Error("write failed");
+    const writeProjectFile = vi.fn().mockRejectedValue(writeError);
+    const result = await persistSdkCandidateMutation(
+      live,
+      "/comp.html",
+      html,
+      {
+        editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
+        writeProjectFile,
+        reloadPreview: vi.fn(),
+        domEditSaveTimestampRef: { current: 0 },
+        createCandidateSession: async (source) => {
+          candidate = await openComposition(source, { history: false });
+          disposeCandidate = vi.spyOn(candidate, "dispose");
+          return candidate;
+        },
+        publishSession,
+      },
+      (next) => next.setStyle("hf-box", { color: "red" }),
+    );
+    expect(result).toMatchObject({ status: "failed", error: writeError });
+    expect(writeProjectFile).toHaveBeenCalledOnce();
+    expect(writeProjectFile.mock.calls[0]?.[0]).toBe("/comp.html");
+    expect(writeProjectFile.mock.calls[0]?.[1]).toContain("color: red");
+    expect(live.serialize()).toBe(liveBefore);
+    expect(publishSession).not.toHaveBeenCalled();
+    expect(disposeCandidate).toHaveBeenCalledOnce();
+    live.dispose();
+  });
+  it("publishes the candidate only after write and history commit", async () => {
+    const live = await openComposition(html, { history: false });
+    const liveBefore = live.serialize();
+    const order: string[] = [];
+    let published: Awaited<ReturnType<typeof openComposition>> | undefined;
+    const result = await persistSdkCandidateMutation(
+      live,
+      "/comp.html",
+      html,
+      {
+        editHistory: {
+          recordEdit: vi.fn(async () => {
+            order.push("history");
+          }),
+        },
+        writeProjectFile: vi.fn(async () => {
+          order.push("write");
+        }),
+        reloadPreview: vi.fn(() => order.push("refresh")),
+        domEditSaveTimestampRef: { current: 0 },
+        publishSession: ({ candidate }) => {
+          order.push("publish");
+          published = candidate;
+          return "published";
+        },
+      },
+      (candidate) => candidate.setStyle("hf-box", { color: "red" }),
+    );
+    expect(result.status).toBe("committed");
+    expect(order).toEqual(["write", "history", "publish", "refresh"]);
+    expect(live.serialize()).toBe(liveBefore);
+    expect(published?.serialize()).toContain("color: red");
+    live.dispose();
+    published?.dispose();
+  });
+  it("keeps the durable commit authoritative when a publisher throws after publication", async () => {
+    const live = await openComposition(html, { history: false });
+    let disk = html;
+    let published: Awaited<ReturnType<typeof openComposition>> | undefined;
+    const recordEdit = vi.fn().mockResolvedValue(undefined);
+    const writeProjectFile = vi.fn(async (_path: string, content: string) => {
+      disk = content;
+    });
+    const result = await persistSdkCandidateMutation(
+      live,
+      "/comp.html",
+      html,
+      {
+        editHistory: { recordEdit },
+        writeProjectFile,
+        reloadPreview: vi.fn(),
+        domEditSaveTimestampRef: { current: 0 },
+        publishSession: ({ candidate }) => {
+          published = candidate;
+          throw new Error("cleanup after publish failed");
+        },
+      },
+      (candidate) => candidate.setStyle("hf-box", { color: "red" }),
+    );
+    expect(result.status).toBe("committed");
+    expect(disk).toContain("color: red");
+    expect(writeProjectFile).toHaveBeenCalledTimes(1);
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    expect(published?.serialize()).toContain("color: red");
+    live.dispose();
+    published?.dispose();
+  });
+  it("serializes overlapping SDK edits and rebases each candidate on the latest disk bytes", async () => {
+    const live = await openComposition(html, { history: false });
+    let disk = html;
+    const published: Array<Awaited<ReturnType<typeof openComposition>>> = [];
+    const writeProjectFile = vi.fn(async (_path: string, content: string) => {
+      // Yield inside the write to make overlap deterministic.
+      await Promise.resolve();
+      disk = content;
+    });
+    const deps = {
+      editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
+      writeProjectFile,
+      readProjectFile: vi.fn(async () => disk),
+      reloadPreview: vi.fn(),
+      domEditSaveTimestampRef: { current: 0 },
+      publishSession: ({ candidate }) => {
+        published.push(candidate);
+        return "published";
+      },
+    };
+    const [first, second] = await Promise.all([
+      persistSdkCandidateMutation(live, "/comp.html", html, deps, (candidate) =>
+        candidate.setStyle("hf-box", { color: "red" }),
+      ),
+      persistSdkCandidateMutation(live, "/comp.html", html, deps, (candidate) =>
+        candidate.setStyle("hf-box", { backgroundColor: "blue" }),
+      ),
+    ]);
+    expect(first.status).toBe("committed");
+    expect(second.status).toBe("committed");
+    expect(disk).toContain("color: red");
+    expect(disk).toContain("background-color: blue");
+    expect(writeProjectFile).toHaveBeenCalledTimes(2);
+    live.dispose();
+    for (const candidate of published) candidate.dispose();
+  });
+  it("fails instead of cloning stale bytes when the authoritative queued read rejects", async () => {
+    const live = await openComposition(html, { history: false });
+    let disk = html;
+    let readCount = 0;
+    const writeProjectFile = vi.fn(async (_path: string, content: string) => {
+      disk = content;
+    });
+    const deps = {
+      editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
+      writeProjectFile,
+      readProjectFile: vi.fn(async () => {
+        readCount++;
+        if (readCount === 1) return disk;
+        throw new Error("transient read failure");
+      }),
+      reloadPreview: vi.fn(),
+      domEditSaveTimestampRef: { current: 0 },
+      publishSession: vi.fn().mockReturnValue("published"),
+    };
+    const first = await persistSdkCandidateMutation(live, "/comp.html", html, deps, (candidate) =>
+      candidate.setStyle("hf-box", { color: "red" }),
+    );
+    const second = await persistSdkCandidateMutation(live, "/comp.html", html, deps, (candidate) =>
+      candidate.setStyle("hf-box", { backgroundColor: "blue" }),
+    );
+    expect(first.status).toBe("committed");
+    expect(second).toMatchObject({ status: "failed", error: new Error("transient read failure") });
+    expect(disk).toContain("color: red");
+    expect(disk).not.toContain("background-color: blue");
+    expect(writeProjectFile).toHaveBeenCalledTimes(1);
+    live.dispose();
+  });
+  it("does not publish a delayed candidate after the active composition switches", async () => {
+    const liveA = await openComposition(html, { history: false });
+    const liveB = await openComposition(html.replace("hf-box", "hf-other"), { history: false });
+    const candidateA = await openComposition(html, { history: false });
+    const disposeCandidate = vi.spyOn(candidateA, "dispose");
+    let activePath = "/a.html";
+    let currentSession = liveA;
+    let releaseHistory: (() => void) | undefined;
+    const historyStarted = new Promise<void>((resolve) => {
+      releaseHistory = resolve;
+    });
+    let notifyHistoryStarted: (() => void) | undefined;
+    const didStartHistory = new Promise<void>((resolve) => {
+      notifyHistoryStarted = resolve;
+    });
+    const published: Array<Awaited<ReturnType<typeof openComposition>>> = [];
+    const refresh = vi.fn();
+    const pending = persistSdkCandidateMutation(
+      liveA,
+      "/a.html",
+      html,
+      {
+        editHistory: {
+          recordEdit: vi.fn(async () => {
+            notifyHistoryStarted?.();
+            await historyStarted;
+          }),
+        },
+        writeProjectFile: vi.fn().mockResolvedValue(undefined),
+        readProjectFile: vi.fn().mockResolvedValue(html),
+        reloadPreview: vi.fn(),
+        refresh,
+        domEditSaveTimestampRef: { current: 0 },
+        createCandidateSession: vi.fn().mockResolvedValue(candidateA),
+        publishSession: ({ candidate, expectedSession, targetPath }) => {
+          if (activePath !== targetPath || currentSession !== expectedSession) {
+            return "rejected-inactive-target";
+          }
+          currentSession = candidate;
+          published.push(candidate);
+          return "published";
+        },
+      },
+      (candidate) => candidate.setStyle("hf-box", { color: "red" }),
+    );
+    await didStartHistory;
+    activePath = "/b.html";
+    currentSession = liveB;
+    releaseHistory?.();
+    expect((await pending).status).toBe("committed");
+    expect(currentSession).toBe(liveB);
+    expect(published).toHaveLength(0);
+    expect(disposeCandidate).toHaveBeenCalledOnce();
+    expect(refresh).not.toHaveBeenCalled();
+    liveA.dispose();
+    liveB.dispose();
+  });
+});
+describe("persistSdkSerialize — shared per-file transaction boundary", () => {
+  const html = `<!DOCTYPE html><html data-composition-variables='[]'><body>
+<div data-hf-id="hf-stage" data-hf-root><div data-hf-id="hf-box" data-start="0" data-duration="1"></div></div>
+</body></html>`;
+  const makeDeps = (disk: { current: string }) => ({
+    editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
+    writeProjectFile: vi.fn(async (_path: string, content: string) => {
+      disk.current = content;
+    }),
+    readProjectFile: vi.fn(async () => disk.current),
+    reloadPreview: vi.fn(),
+    domEditSaveTimestampRef: { current: 0 },
+  });
+  it("rebases overlapping whole-file transforms on the latest committed bytes", async () => {
+    const disk = { current: "<html><body></body></html>" };
+    let releaseFirstWrite: (() => void) | undefined;
+    const firstWriteStarted = new Promise<void>((resolve) => {
+      releaseFirstWrite = resolve;
+    });
+    let notifyFirstWriteStarted: (() => void) | undefined;
+    const didStartFirstWrite = new Promise<void>((resolve) => {
+      notifyFirstWriteStarted = resolve;
+    });
+    const deps = makeDeps(disk);
+    deps.writeProjectFile.mockImplementationOnce(async (_path: string, content: string) => {
+      notifyFirstWriteStarted?.();
+      await firstWriteStarted;
+      disk.current = content;
+    });
+    const first = persistSdkSerialize(
+      (before) => before.replace("</body>", "<div>A</div></body>"),
+      "/comp.html",
+      disk.current,
+      deps,
+    );
+    await didStartFirstWrite;
+    const second = persistSdkSerialize(
+      (before) => before.replace("</body>", "<div>B</div></body>"),
+      "/comp.html",
+      disk.current,
+      deps,
+    );
+    releaseFirstWrite?.();
+    await Promise.all([first, second]);
+    expect(disk.current).toContain("<div>A</div>");
+    expect(disk.current).toContain("<div>B</div>");
+  });
+  it("shares the same queue with candidate mutations", async () => {
+    const disk = { current: html };
+    const live = await openComposition(html, { history: false });
+    const published: Array<Awaited<ReturnType<typeof openComposition>>> = [];
+    const deps = {
+      ...makeDeps(disk),
+      publishSession: ({
+        candidate,
+      }: {
+        candidate: Awaited<ReturnType<typeof openComposition>>;
+      }) => {
+        published.push(candidate);
+        return "published";
+      },
+    };
+    let releaseCandidateWrite: (() => void) | undefined;
+    const candidateWriteGate = new Promise<void>((resolve) => {
+      releaseCandidateWrite = resolve;
+    });
+    let notifyCandidateWriteStarted: (() => void) | undefined;
+    const candidateWriteStarted = new Promise<void>((resolve) => {
+      notifyCandidateWriteStarted = resolve;
+    });
+    deps.writeProjectFile.mockImplementationOnce(async (_path: string, content: string) => {
+      notifyCandidateWriteStarted?.();
+      await candidateWriteGate;
+      disk.current = content;
+    });
+    const candidateEdit = persistSdkCandidateMutation(live, "/comp.html", html, deps, (candidate) =>
+      candidate.setStyle("hf-box", { color: "red" }),
+    );
+    await candidateWriteStarted;
+    const islandEdit = persistSdkSerialize(
+      (before) => before.replace("</body>", "<script>island</script></body>"),
+      "/comp.html",
+      html,
+      deps,
+    );
+    releaseCandidateWrite?.();
+    await Promise.all([candidateEdit, islandEdit]);
+    expect(disk.current).toContain("color: red");
+    expect(disk.current).toContain("<script>island</script>");
+    live.dispose();
+    for (const candidate of published) candidate.dispose();
+  });
+});
 describe("sdkDeletePersist", () => {
   const makeRef = <T>(val: T): MutableRefObject<T> => ({ current: val });
   const makeDeps = () => ({
@@ -389,6 +819,7 @@ describe("sdkDeletePersist", () => {
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
     domEditSaveTimestampRef: makeRef(0),
+    ...candidateTestDeps(),
   });
   const makeSession = (hasEl = true) =>
@@ -403,21 +834,23 @@ describe("sdkDeletePersist", () => {
     }) as unknown as Parameters<typeof sdkDeletePersist>[3];
   it("returns false when session is null", async () => {
-    expect(await sdkDeletePersist("hf-abc", "before", "/comp.html", null, makeDeps())).toBe(false);
+    expect(
+      (await sdkDeletePersist("hf-abc", "before", "/comp.html", null, makeDeps())).status,
+    ).toBe("declined");
   });
   it("returns false when element not found in session", async () => {
     const session = makeSession(false);
-    expect(await sdkDeletePersist("hf-abc", "before", "/comp.html", session, makeDeps())).toBe(
-      false,
-    );
+    expect(
+      (await sdkDeletePersist("hf-abc", "before", "/comp.html", session, makeDeps())).status,
+    ).toBe("declined");
   });
   it("calls removeElement and writes serialized content", async () => {
     const deps = makeDeps();
     const session = makeSession(true);
     const result = await sdkDeletePersist("hf-abc", "before", "/comp.html", session, deps);
-    expect(result).toBe(true);
+    expect(result.status).toBe("committed");
     expect(session!.removeElement).toHaveBeenCalledWith("hf-abc");
     expect(deps.writeProjectFile).toHaveBeenCalledWith("/comp.html", "<html>after</html>");
   });
@@ -448,7 +881,7 @@ describe("sdkDeletePersist", () => {
       throw new Error("remove failed");
     });
     const result = await sdkDeletePersist("hf-abc", "before", "/comp.html", session, deps);
-    expect(result).toBe(false);
+    expect(result.status).toBe("failed");
     expect(deps.writeProjectFile).not.toHaveBeenCalled();
     expect(deps.reloadPreview).not.toHaveBeenCalled();
   });
@@ -461,6 +894,7 @@ describe("sdkTimingPersist", () => {
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
     domEditSaveTimestampRef: makeRef(0),
+    ...candidateTestDeps(),
   });
   const makeSession = (hasEl = true) =>
@@ -475,16 +909,16 @@ describe("sdkTimingPersist", () => {
     }) as unknown as Parameters<typeof sdkTimingPersist>[3];
   it("returns false when session is null", async () => {
-    expect(await sdkTimingPersist("hf-clip", "/comp.html", { start: 1 }, null, makeDeps())).toBe(
-      false,
-    );
+    expect(
+      (await sdkTimingPersist("hf-clip", "/comp.html", { start: 1 }, null, makeDeps())).status,
+    ).toBe("declined");
   });
   it("returns false when element not found in session", async () => {
     const session = makeSession(false);
-    expect(await sdkTimingPersist("hf-clip", "/comp.html", { start: 1 }, session, makeDeps())).toBe(
-      false,
-    );
+    expect(
+      (await sdkTimingPersist("hf-clip", "/comp.html", { start: 1 }, session, makeDeps())).status,
+    ).toBe("declined");
   });
   it("calls setTiming with provided update and writes serialized content", async () => {
@@ -497,7 +931,7 @@ describe("sdkTimingPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(true);
+    expect(result.status).toBe("committed");
     expect(session!.setTiming).toHaveBeenCalledWith("hf-clip", {
       start: 2,
       duration: 5,
@@ -524,7 +958,7 @@ describe("sdkTimingPersist", () => {
       throw new Error("timing error");
     });
     const result = await sdkTimingPersist("hf-clip", "/comp.html", { start: 1 }, session, deps);
-    expect(result).toBe(false);
+    expect(result.status).toBe("failed");
     expect(deps.writeProjectFile).not.toHaveBeenCalled();
   });
@@ -539,6 +973,7 @@ describe("sdkTimingPersist", () => {
     const session = makeSession(true);
     await sdkTimingPersist("hf-clip", "/comp.html", { start: 3 }, session, deps);
     expect(deps.readProjectFile).toHaveBeenCalledWith("/comp.html");
+    expect(deps.readProjectFile).toHaveBeenCalledOnce();
     expect(deps.editHistory.recordEdit).toHaveBeenCalledWith(
       expect.objectContaining({
         files: {
@@ -548,18 +983,16 @@ describe("sdkTimingPersist", () => {
     );
   });
-  it("falls back to serialize() before when the reader throws", async () => {
+  it("fails without writing when the authoritative reader throws", async () => {
     const deps = {
       ...makeDeps(),
       readProjectFile: vi.fn().mockRejectedValue(new Error("read failed")),
     };
     const session = makeSession(true);
-    await sdkTimingPersist("hf-clip", "/comp.html", { start: 3 }, session, deps);
-    expect(deps.editHistory.recordEdit).toHaveBeenCalledWith(
-      expect.objectContaining({
-        files: { "/comp.html": { before: "<html>before</html>", after: "<html>after</html>" } },
-      }),
-    );
+    const result = await sdkTimingPersist("hf-clip", "/comp.html", { start: 3 }, session, deps);
+    expect(result).toMatchObject({ status: "failed", error: new Error("read failed") });
+    expect(deps.writeProjectFile).not.toHaveBeenCalled();
+    expect(deps.editHistory.recordEdit).not.toHaveBeenCalled();
   });
 });
@@ -583,6 +1016,7 @@ describe("sdkGsapTweenPersist — undo baseline (finding #12)", () => {
       reloadPreview: vi.fn(),
       domEditSaveTimestampRef: makeRef(0),
       readProjectFile: vi.fn().mockResolvedValue("<html>on-disk gsap bytes</html>"),
+      ...candidateTestDeps(),
     };
     const session = makeSession();
     await sdkGsapTweenPersist(
@@ -591,6 +1025,7 @@ describe("sdkGsapTweenPersist — undo baseline (finding #12)", () => {
       session,
       deps,
     );
+    expect(deps.readProjectFile).toHaveBeenCalledOnce();
     expect(deps.editHistory.recordEdit).toHaveBeenCalledWith(
       expect.objectContaining({
         files: {
@@ -604,16 +1039,18 @@ describe("sdkGsapTweenPersist — undo baseline (finding #12)", () => {
 describe("sdkGsapTweenPersist — per-file serialization (finding #8)", () => {
   const makeRef = <T>(val: T): MutableRefObject<T> => ({ current: val });
-  it("routes the read-modify-write through the keyed serializer so same-file flushes can't interleave", async () => {
+  it("routes the read-modify-write through the shared file coordinator", async () => {
     const order: string[] = [];
     let writeResolve: (() => void) | null = null;
+    let writeCall = 0;
     const deps = {
       editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
       // First write blocks until we release it, so without serialization the
       // second op's serialize()/dispatch would interleave ahead of it.
       writeProjectFile: vi.fn().mockImplementation((_p: string, content: string) => {
+        writeCall++;
         order.push(`write-start:${content}`);
-        if (content === "<html>after-1</html>") {
+        if (writeCall === 1) {
           return new Promise<void>((res) => {
             writeResolve = () => {
               order.push(`write-done:${content}`);
@@ -626,16 +1063,7 @@ describe("sdkGsapTweenPersist — per-file serialization (finding #8)", () => {
       }),
       reloadPreview: vi.fn(),
       domEditSaveTimestampRef: makeRef(0),
-      // A real per-key serializer: tasks under the same key run strictly in order.
-      serialize: (() => {
-        const inFlight = new Map<string, Promise<unknown>>();
-        return <T>(key: string, task: () => Promise<T>): Promise<T> => {
-          const prior = inFlight.get(key) ?? Promise.resolve();
-          const next = prior.then(task, task);
-          inFlight.set(key, next);
-          return next as Promise<T>;
-        };
-      })(),
+      ...candidateTestDeps(),
     };
     let serializeCall = 0;
@@ -662,15 +1090,17 @@ describe("sdkGsapTweenPersist — per-file serialization (finding #8)", () => {
       session,
       deps,
     );
-    // Let the first op reach its (blocked) write before releasing it.
-    await Promise.resolve();
-    await Promise.resolve();
+    // Let the first op finish candidate construction and reach its blocked write.
+    await vi.waitFor(() => expect(writeResolve).not.toBeNull());
     writeResolve?.();
     await Promise.all([p1, p2]);
     // The second op's write must NOT start before the first op's write completes.
-    const firstWriteDone = order.indexOf("write-done:<html>after-1</html>");
-    const secondWriteStart = order.indexOf("write-start:<html>after-2</html>");
+    const firstWriteDone = order.findIndex((entry) => entry.startsWith("write-done:"));
+    const writeStarts = order
+      .map((entry, index) => (entry.startsWith("write-start:") ? index : -1))
+      .filter((index) => index >= 0);
+    const secondWriteStart = writeStarts[1] ?? -1;
     expect(firstWriteDone).toBeGreaterThanOrEqual(0);
     expect(secondWriteStart).toBeGreaterThan(firstWriteDone);
   });
@@ -683,6 +1113,7 @@ describe("sdkGsapTweenPersist", () => {
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
     domEditSaveTimestampRef: makeRef(0),
+    ...candidateTestDeps(),
   });
   const makeSession = (opts?: { addGsapTween?: string; hasEl?: boolean }) =>
@@ -706,7 +1137,7 @@ describe("sdkGsapTweenPersist", () => {
         null,
         makeDeps(),
       ),
-    ).toBe(false);
+    ).toMatchObject({ status: "declined" });
   });
   it("calls addGsapTween and writes for kind=add", async () => {
@@ -722,7 +1153,7 @@ describe("sdkGsapTweenPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(true);
+    expect(result.status).toBe("committed");
     expect(session!.addGsapTween).toHaveBeenCalledWith(
       "hf-box",
       expect.objectContaining({ method: "to" }),
@@ -739,7 +1170,7 @@ describe("sdkGsapTweenPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(false);
+    expect(result.status).toBe("declined");
     expect(deps.writeProjectFile).not.toHaveBeenCalled();
   });
@@ -752,7 +1183,7 @@ describe("sdkGsapTweenPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(true);
+    expect(result.status).toBe("committed");
     expect(session!.setGsapTween).toHaveBeenCalledWith("tw-1", { ease: "power3.in" });
     expect(deps.reloadPreview).toHaveBeenCalled();
   });
@@ -766,7 +1197,7 @@ describe("sdkGsapTweenPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(true);
+    expect(result.status).toBe("committed");
     expect(session!.removeGsapTween).toHaveBeenCalledWith("tw-1");
   });
@@ -782,7 +1213,7 @@ describe("sdkGsapTweenPersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(false);
+    expect(result.status).toBe("failed");
     expect(deps.writeProjectFile).not.toHaveBeenCalled();
   });
 });
@@ -794,6 +1225,7 @@ describe("sdkGsapKeyframePersist", () => {
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
     domEditSaveTimestampRef: makeRef(0),
+    ...candidateTestDeps(),
   });
   const makeSession = () =>
@@ -809,7 +1241,7 @@ describe("sdkGsapKeyframePersist", () => {
   it("returns false when session is null", async () => {
     expect(
       await sdkGsapKeyframePersist("/comp.html", "tw-1", 50, { opacity: 0.5 }, null, makeDeps()),
-    ).toBe(false);
+    ).toMatchObject({ status: "declined" });
   });
   it("dispatches addGsapKeyframe and writes serialized content", async () => {
@@ -823,7 +1255,7 @@ describe("sdkGsapKeyframePersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(true);
+    expect(result.status).toBe("committed");
     expect(session!.dispatch).toHaveBeenCalledWith({
       type: "addGsapKeyframe",
       animationId: "tw-1",
@@ -848,7 +1280,7 @@ describe("sdkGsapKeyframePersist", () => {
       session,
       deps,
     );
-    expect(result).toBe(false);
+    expect(result.status).toBe("failed");
     expect(deps.writeProjectFile).not.toHaveBeenCalled();
   });
 });
@@ -860,6 +1292,7 @@ describe("sdkCutoverPersist — GSAP script preservation (integration)", () => {
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
     domEditSaveTimestampRef: makeRef(0),
+    ...candidateTestDeps(),
   });
   it("preserves GSAP <script> block and data-position-mode through setStyle dispatch", async () => {
@@ -880,7 +1313,7 @@ gsap.timeline().to('[data-hf-id="hf-layer"]', { duration: 1, x: 100 });
       comp,
       deps,
     );
-    expect(result).toBe(true);
+    expect(result.status).toBe("committed");
     const written = (deps.writeProjectFile as ReturnType<typeof vi.fn>).mock
       .calls[0]?.[1] as string;
     expect(written).toContain("data-hf-gsap");