@hyperframes/studio 0.8.34 → 0.8.36

package/src/hooks/useTimelineEditing.ts

@@ -43,7 +43,6 @@ export function useTimelineEditing({
   writeProjectFile,
   observeProjectFileVersion,
   recordEdit,
-  domEditSaveTimestampRef,
   reloadPreview,
   previewIframeRef,
   pendingTimelineEditPathRef,
@@ -82,7 +81,6 @@ export function useTimelineEditing({
             buildPatches,
             writeProjectFile,
             recordEdit,
-            domEditSaveTimestampRef,
             pendingTimelineEditPathRef,
             coalesceKey,
           }),
@@ -99,7 +97,6 @@ export function useTimelineEditing({
       activeCompPath,
       recordEdit,
       writeProjectFile,
-      domEditSaveTimestampRef,
       pendingTimelineEditPathRef,
       showToast,
       isRecordingRef,
@@ -108,7 +105,6 @@ export function useTimelineEditing({
   );
   const groupEditing = useTimelineGroupEditing({
     activeCompPath,
-    domEditSaveTimestampRef,
     editQueueRef,
     forceReloadSdkSession,
     invalidateGsapCache,
@@ -211,7 +207,6 @@ export function useTimelineEditing({
                   editHistory: { recordEdit },
                   writeProjectFile,
                   reloadPreview,
-                  domEditSaveTimestampRef,
                   compositionPath: activeCompPath,
                   // Capture on-disk bytes as the undo `before` so undoing a timing move
                   // restores the file verbatim, not a normalized full-DOM re-emit.
@@ -244,7 +239,6 @@ export function useTimelineEditing({
       recordEdit,
       writeProjectFile,
       reloadPreview,
-      domEditSaveTimestampRef,
       timelineElements,
       handleDomZIndexReorderCommitRef,
       showToast,
@@ -317,7 +311,6 @@ export function useTimelineEditing({
                 editHistory: { recordEdit },
                 writeProjectFile,
                 reloadPreview,
-                domEditSaveTimestampRef,
                 compositionPath: activeCompPath,
                 // Capture on-disk bytes as the undo `before` so undoing a timing
                 // resize restores the file verbatim, not a normalized full-DOM re-emit.
@@ -346,7 +339,6 @@ export function useTimelineEditing({
       recordEdit,
       writeProjectFile,
       reloadPreview,
-      domEditSaveTimestampRef,
       showToast,
       invalidateGsapCache,
     ],
@@ -359,7 +351,6 @@ export function useTimelineEditing({
     showToast,
     writeProjectFile,
     recordEdit,
-    domEditSaveTimestampRef,
     previewIframeRef,
     pendingTimelineEditPathRef,
     isRecordingRef,
@@ -372,7 +363,6 @@ export function useTimelineEditing({
     showToast,
     writeProjectFile,
     recordEdit,
-    domEditSaveTimestampRef,
     previewIframeRef,
     pendingTimelineEditPathRef,
     isRecordingRef,
@@ -385,7 +375,6 @@ export function useTimelineEditing({
     showToast,
     writeProjectFile,
     recordEdit,
-    domEditSaveTimestampRef,
     previewIframeRef,
     pendingTimelineEditPathRef,
     isRecordingRef,
@@ -397,7 +386,6 @@ export function useTimelineEditing({
     showToast,
     writeProjectFile,
     recordEdit,
-    domEditSaveTimestampRef,
     previewIframeRef,
     pendingTimelineEditPathRef,
     isRecordingRef,
@@ -409,7 +397,6 @@ export function useTimelineEditing({
     showToast,
     writeProjectFile,
     recordEdit,
-    domEditSaveTimestampRef,
     previewIframeRef,
     pendingTimelineEditPathRef,
     isRecordingRef,
@@ -422,7 +409,6 @@ export function useTimelineEditing({
     showToast,
     writeProjectFile,
     recordEdit,
-    domEditSaveTimestampRef,
     reloadPreview,
     isRecordingRef,
     forceReloadSdkSession,
@@ -437,7 +423,6 @@ export function useTimelineEditing({
       showToast,
       writeProjectFile,
       recordEdit,
-      domEditSaveTimestampRef,
       reloadPreview,
       uploadProjectFiles,
       isRecordingRef,
@@ -454,7 +439,6 @@ export function useTimelineEditing({
     writeProjectFile,
     observeProjectFileVersion,
     recordEdit,
-    domEditSaveTimestampRef,
     reloadPreview,
     isRecordingRef,
     forceReloadSdkSession,

package/src/hooks/useTimelineEditingTypes.ts

@@ -35,7 +35,6 @@ export interface UseTimelineEditingOptions {
   writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
   observeProjectFileVersion?: (path: string, version: string | null) => void;
   recordEdit: (input: RecordEditInput) => Promise<void>;
-  domEditSaveTimestampRef: MutableRefObject<number>;
   reloadPreview: () => void;
   previewIframeRef: RefObject<HTMLIFrameElement | null>;
   pendingTimelineEditPathRef: MutableRefObject<Set<string>>;

package/src/hooks/useTimelineGroupEditing.ts

@@ -51,7 +51,6 @@ export interface TimelineGroupCommitOptions {
 
 interface UseTimelineGroupEditingOptions {
   activeCompPath: string | null;
-  domEditSaveTimestampRef: MutableRefObject<number>;
   editQueueRef: MutableRefObject<Promise<unknown>>;
   forceReloadSdkSession?: () => void;
   invalidateGsapCache?: () => void;
@@ -108,7 +107,6 @@ function resizeHasPlaybackStartAdjustment(change: TimelineGroupResizeChange): bo
 
 export function useTimelineGroupEditing({
   activeCompPath,
-  domEditSaveTimestampRef,
   editQueueRef,
   forceReloadSdkSession,
   invalidateGsapCache,
@@ -160,7 +158,6 @@ export function useTimelineGroupEditing({
         changes: batchChanges,
         writeProjectFile,
         recordEdit,
-        domEditSaveTimestampRef,
         pendingTimelineEditPathRef,
         coalesceKey,
         coalesceMs,
@@ -169,7 +166,6 @@ export function useTimelineGroupEditing({
     },
     [
       activeCompPath,
-      domEditSaveTimestampRef,
       forceReloadSdkSession,
       pendingTimelineEditPathRef,
       recordEdit,
@@ -209,7 +205,6 @@ export function useTimelineGroupEditing({
           editHistory: { recordEdit },
           writeProjectFile,
           reloadPreview,
-          domEditSaveTimestampRef,
           compositionPath: activeCompPath,
           readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
           publishSession: publishSdkSession,
@@ -225,7 +220,6 @@ export function useTimelineGroupEditing({
     },
     [
       activeCompPath,
-      domEditSaveTimestampRef,
       projectIdRef,
       publishSdkSession,
       recordEdit,

package/src/hooks/useVariablesPersist.ts

@@ -20,7 +20,6 @@ export function useVariablesPersist({
   writeProjectFile,
   recordEdit,
   reloadPreview,
-  domEditSaveTimestampRef,
   publishSdkSession,
 }: UseVariablesPersistParams): (
   label: string,
@@ -39,7 +38,6 @@ export function useVariablesPersist({
           editHistory: { recordEdit },
           writeProjectFile,
           reloadPreview,
-          domEditSaveTimestampRef,
           compositionPath: activeCompPath,
           readProjectFile,
           publishSession: publishSdkSession,
@@ -56,7 +54,6 @@ export function useVariablesPersist({
       writeProjectFile,
       recordEdit,
       reloadPreview,
-      domEditSaveTimestampRef,
       publishSdkSession,
     ],
   );

package/src/player/components/Player.tsx

@@ -4,9 +4,23 @@ import { isLottieAnimationLoaded } from "@hyperframes/core/runtime/lottie-readin
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
 import { HyperframesLoader } from "../../components/ui";
-// NOTE: importing "@hyperframes/player" registers a class extending HTMLElement
-// at module load, which throws under SSR. Defer the import to the mount effect
-// so it only runs in the browser.
+// Importing "@hyperframes/player" registers a class extending HTMLElement at
+// module load, which throws under SSR, hence the dynamic import behind a
+// `typeof window` guard. Kicking it here rather than in the mount effect puts
+// the chunk request in flight before the shell's first layout. Clearing the memo
+// on rejection stops one failure poisoning every later mount; the browser's
+// module map still caches a failed fetch, so recovery is a page reload.
+let playerModule: Promise<unknown> | null = null;
+
+export function loadPlayerModule(): Promise<unknown> {
+  playerModule ??= import("@hyperframes/player").catch((err: unknown) => {
+    playerModule = null;
+    throw err;
+  });
+  return playerModule;
+}
+
+if (typeof window !== "undefined") void loadPlayerModule().catch(() => {});
 
 interface PlayerProps {
   projectId?: string;
@@ -166,8 +180,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       let canceled = false;
       let cleanup: (() => void) | undefined;
 
-      // Dynamic import registers the custom element in the browser only.
-      import("@hyperframes/player").then(() => {
+      void loadPlayerModule().then(() => {
         if (canceled) return;
 
         // Create the web component imperatively to avoid JSX custom-element typing.

package/src/player/components/playerModuleRetry.test.ts

@@ -0,0 +1,41 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi } from "vitest";
+
+// The module-scope kick in Player.tsx consumes the first attempt at import time,
+// so this starts failing; the first test asserts that kick happened.
+const state = vi.hoisted(() => ({ attempts: 0, failing: true }));
+
+vi.mock("@hyperframes/player", () => {
+  state.attempts += 1;
+  if (state.failing) throw new Error("chunk load failed");
+  return {};
+});
+
+import { loadPlayerModule } from "./Player";
+
+describe("loadPlayerModule", () => {
+  it("kicks the import at module scope, before any mount", () => {
+    expect(state.attempts).toBe(1);
+  });
+
+  it("does not hand a later mount the promise a failed load already rejected", async () => {
+    // vitest rewraps a throwing mock factory, so assert the rejection, not its text.
+    await expect(loadPlayerModule()).rejects.toThrow();
+    const failedAttempts = state.attempts;
+
+    state.failing = false;
+
+    await expect(loadPlayerModule()).resolves.toBeDefined();
+    expect(state.attempts).toBeGreaterThan(failedAttempts);
+  });
+
+  it("hands every mount the same resolved promise", async () => {
+    state.failing = false;
+    const first = loadPlayerModule();
+    await first;
+
+    expect(loadPlayerModule()).toBe(first);
+    expect(loadPlayerModule()).toBe(first);
+  });
+});

package/src/player/lib/playbackTypes.ts

@@ -60,4 +60,11 @@ export type IframeWindow = Window & {
   __timeline?: TimelineLike;
   __timelines?: Record<string, TimelineLike>;
   __clipManifest?: ClipManifest;
+  /** Declared runtime-side in core's window.d.ts, which this package cannot see.
+   *  Every member stays optional and is optional-called, so a runtime that
+   *  predates the hook degrades to a no-op instead of throwing. */
+  __hf?: {
+    leasePausedMedia?: (el: HTMLMediaElement) => void;
+    releasePausedMedia?: (el: HTMLMediaElement) => void;
+  };
 };

package/src/player/lib/timelineIframeHelpers.test.ts

@@ -123,6 +123,36 @@ describe("scrubPreviewAudio", () => {
     expect(voiceover.play).not.toHaveBeenCalled();
     stopScrubPreviewAudio();
   });
+
+  /** A scrub audition is media running under a paused clock, which the runtime now
+   *  stops on sight. So it borrows the element. That a leased element survives the
+   *  tick is asserted runtime-side in core's `transportPark.test.ts`; here the
+   *  contract is that the hook is called with the right element and given back. */
+  it("borrows the element from the runtime for the audition and returns it on stop", () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const previewDoc = iframe.contentDocument;
+    if (!previewDoc?.body) throw new Error("expected an iframe document");
+
+    const music = previewDoc.createElement("audio");
+    music.id = "music";
+    music.play = vi.fn(async () => {});
+    music.pause = vi.fn();
+    previewDoc.body.append(music);
+
+    const leasePausedMedia = vi.fn();
+    const releasePausedMedia = vi.fn();
+    (previewDoc.defaultView as IframeWindow).__hf = { leasePausedMedia, releasePausedMedia };
+
+    scrubPreviewAudio(iframe, 0.5, "music", 1);
+
+    expect(leasePausedMedia).toHaveBeenCalledWith(music);
+    expect(releasePausedMedia).not.toHaveBeenCalled();
+
+    stopScrubPreviewAudio();
+
+    expect(releasePausedMedia).toHaveBeenCalledWith(music);
+  });
 });
 
 describe("applyPreviewAudioFlags", () => {

package/src/player/lib/timelineIframeHelpers.ts

@@ -245,11 +245,24 @@ function resolveScrubAudioEl(doc: Document, musicId?: string | null): HTMLAudioE
   );
 }
 
+/** The runtime stops any media running under a paused clock, and a scrub audition
+ *  IS media running under a paused clock, so it has to borrow the element. Every
+ *  hop is optional: a runtime predating the hook must no-op, not throw. Wrapped in
+ *  named calls so `applyScrub` does not carry the optional chains' branches. */
+function leaseScrubElement(el: HTMLAudioElement): void {
+  (el.ownerDocument.defaultView as IframeWindow | null)?.__hf?.leasePausedMedia?.(el);
+}
+
+function releaseScrubElement(el: HTMLAudioElement): void {
+  (el.ownerDocument.defaultView as IframeWindow | null)?.__hf?.releasePausedMedia?.(el);
+}
+
 function applyScrub(el: HTMLAudioElement, audioFileTime: number, previewVolume: number): void {
   if (scrubAudioEl && scrubAudioEl !== el) stopScrubPreviewAudio();
   if (scrubPrevMuted === null) scrubPrevMuted = el.muted;
   if (scrubPrevVolume === null) scrubPrevVolume = el.volume;
   scrubAudioEl = el;
+  leaseScrubElement(el);
   try {
     el.muted = false;
     el.volume = SCRUB_VOLUME * normalizePreviewVolume(previewVolume);
@@ -296,6 +309,9 @@ export function stopScrubPreviewAudio(): void {
   const el = scrubAudioEl;
   scrubAudioEl = null;
   if (!el) return;
+  // `scrubStopTimer` guarantees this runs within ~140 ms of the last scrub, so
+  // the borrow cannot outlive the audition.
+  releaseScrubElement(el);
   try {
     el.pause();
     if (scrubPrevMuted !== null) el.muted = scrubPrevMuted;

package/src/utils/sdkCutover.familyGate.test.ts

@@ -18,7 +18,6 @@ const deps = {
   editHistory: { recordEdit: vi.fn() },
   writeProjectFile: vi.fn(),
   reloadPreview: vi.fn(),
-  domEditSaveTimestampRef: { current: 0 },
 } as never;
 
 describe("SDK family gate mapping", () => {

package/src/utils/sdkCutover.gate.test.ts

@@ -28,7 +28,6 @@ const makeDeps = () =>
     editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
-    domEditSaveTimestampRef: { current: 0 },
   }) as never;
 
 describe("dark-launch gate — STUDIO_SDK_CUTOVER_ENABLED=false ⇒ persist declines", () => {

package/src/utils/sdkCutover.test.ts

@@ -14,7 +14,6 @@ import {
 import { openComposition } from "@hyperframes/sdk";
 import { createMemoryAdapter } from "@hyperframes/sdk/adapters/memory";
 import type { PatchOperation } from "./sourcePatcher";
-import type { MutableRefObject } from "react";
 
 vi.mock("../components/editor/manualEditingAvailability", () => ({
   STUDIO_SDK_CUTOVER_ENABLED: true,
@@ -153,13 +152,10 @@ describe("shouldUseSdkCutover", () => {
 });
 
 describe("sdkCutoverPersist", () => {
-  const makeRef = <T>(val: T): MutableRefObject<T> => ({ current: val });
-
   const makeDeps = (overrides: Partial<Parameters<typeof sdkCutoverPersist>[5]> = {}) => ({
     editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
-    domEditSaveTimestampRef: makeRef(0),
     ...candidateTestDeps(),
     ...overrides,
   });
@@ -453,7 +449,6 @@ window.__timelines = { main: tl };</script></div>
             disk = content;
           }),
           reloadPreview: vi.fn(),
-          domEditSaveTimestampRef: { current: 0 },
           publishSession,
         },
         mutate,
@@ -485,7 +480,6 @@ window.__timelines = { main: tl };</script></div>
         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");
@@ -525,7 +519,6 @@ window.__timelines = { main: tl };</script></div>
           order.push("write");
         }),
         reloadPreview: vi.fn(() => order.push("refresh")),
-        domEditSaveTimestampRef: { current: 0 },
         publishSession: ({ candidate }) => {
           order.push("publish");
           published = candidate;
@@ -559,7 +552,6 @@ window.__timelines = { main: tl };</script></div>
         editHistory: { recordEdit },
         writeProjectFile,
         reloadPreview: vi.fn(),
-        domEditSaveTimestampRef: { current: 0 },
         publishSession: ({ candidate }) => {
           published = candidate;
           throw new Error("cleanup after publish failed");
@@ -591,7 +583,6 @@ window.__timelines = { main: tl };</script></div>
       writeProjectFile,
       readProjectFile: vi.fn(async () => disk),
       reloadPreview: vi.fn(),
-      domEditSaveTimestampRef: { current: 0 },
       publishSession: ({ candidate }) => {
         published.push(candidate);
         return "published";
@@ -632,7 +623,6 @@ window.__timelines = { main: tl };</script></div>
         throw new Error("transient read failure");
       }),
       reloadPreview: vi.fn(),
-      domEditSaveTimestampRef: { current: 0 },
       publishSession: vi.fn().mockReturnValue("published"),
     };
 
@@ -683,7 +673,6 @@ window.__timelines = { main: tl };</script></div>
         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) {
@@ -724,7 +713,6 @@ describe("persistSdkSerialize — shared per-file transaction boundary", () => {
     }),
     readProjectFile: vi.fn(async () => disk.current),
     reloadPreview: vi.fn(),
-    domEditSaveTimestampRef: { current: 0 },
   });
 
   it("rebases overlapping whole-file transforms on the latest committed bytes", async () => {
@@ -814,12 +802,10 @@ describe("persistSdkSerialize — shared per-file transaction boundary", () => {
 });
 
 describe("sdkDeletePersist", () => {
-  const makeRef = <T>(val: T): MutableRefObject<T> => ({ current: val });
   const makeDeps = () => ({
     editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
-    domEditSaveTimestampRef: makeRef(0),
     ...candidateTestDeps(),
   });
 
@@ -893,12 +879,10 @@ describe("sdkDeletePersist", () => {
 });
 
 describe("sdkTimingPersist", () => {
-  const makeRef = <T>(val: T): MutableRefObject<T> => ({ current: val });
   const makeDeps = () => ({
     editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
-    domEditSaveTimestampRef: makeRef(0),
     ...candidateTestDeps(),
   });
 
@@ -1006,7 +990,6 @@ describe("sdkTimingPersist", () => {
 });
 
 describe("sdkGsapTweenPersist — undo baseline (finding #12)", () => {
-  const makeRef = <T>(val: T): MutableRefObject<T> => ({ current: val });
   const makeSession = () =>
     ({
       getElement: vi.fn().mockReturnValue({ id: "hf-box" }),
@@ -1023,7 +1006,6 @@ describe("sdkGsapTweenPersist — undo baseline (finding #12)", () => {
       editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
       writeProjectFile: vi.fn().mockResolvedValue(undefined),
       reloadPreview: vi.fn(),
-      domEditSaveTimestampRef: makeRef(0),
       readProjectFile: vi.fn().mockResolvedValue("<html>on-disk gsap bytes</html>"),
       ...candidateTestDeps(),
     };
@@ -1046,8 +1028,6 @@ 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 shared file coordinator", async () => {
     const order: string[] = [];
     let writeResolve: (() => void) | null = null;
@@ -1071,7 +1051,6 @@ describe("sdkGsapTweenPersist — per-file serialization (finding #8)", () => {
         return Promise.resolve();
       }),
       reloadPreview: vi.fn(),
-      domEditSaveTimestampRef: makeRef(0),
       ...candidateTestDeps(),
     };
 
@@ -1116,12 +1095,10 @@ describe("sdkGsapTweenPersist — per-file serialization (finding #8)", () => {
 });
 
 describe("sdkGsapTweenPersist", () => {
-  const makeRef = <T>(val: T): MutableRefObject<T> => ({ current: val });
   const makeDeps = () => ({
     editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
-    domEditSaveTimestampRef: makeRef(0),
     ...candidateTestDeps(),
   });
 
@@ -1232,12 +1209,10 @@ describe("sdkGsapTweenPersist", () => {
 });
 
 describe("sdkGsapKeyframePersist", () => {
-  const makeRef = <T>(val: T): MutableRefObject<T> => ({ current: val });
   const makeDeps = () => ({
     editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
-    domEditSaveTimestampRef: makeRef(0),
     ...candidateTestDeps(),
   });
 
@@ -1303,12 +1278,10 @@ describe("sdkGsapKeyframePersist", () => {
 });
 
 describe("sdkCutoverPersist — GSAP script preservation (integration)", () => {
-  const makeRef = <T>(val: T): MutableRefObject<T> => ({ current: val });
   const makeDeps = () => ({
     editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
     writeProjectFile: vi.fn().mockResolvedValue(undefined),
     reloadPreview: vi.fn(),
-    domEditSaveTimestampRef: makeRef(0),
     ...candidateTestDeps(),
   });
 

package/src/utils/sdkEditTransaction.ts

@@ -1,4 +1,3 @@
-import type { MutableRefObject } from "react";
 import { openComposition, type Composition } from "@hyperframes/sdk";
 import type { EditHistoryKind } from "./editHistory";
 import { hashContent, markSelfWrite } from "../hooks/sdkSelfWriteRegistry";
@@ -39,7 +38,6 @@ export interface CutoverDeps {
    */
   writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
   reloadPreview: () => void;
-  domEditSaveTimestampRef: MutableRefObject<number>;
   refresh?: (after: string) => void;
   compositionPath?: string | null;
   readProjectFile?: (path: string) => Promise<string>;
@@ -153,7 +151,6 @@ async function rollbackWrite(
   cause: Error,
 ): Promise<Error> {
   try {
-    deps.domEditSaveTimestampRef.current = Date.now();
     markSelfWrite(targetPath, originalContent);
     await deps.writeProjectFile(targetPath, originalContent, expectedCurrentContent);
     return cause;
@@ -172,7 +169,6 @@ async function writeAndRecord(
   deps: CutoverDeps,
   options?: CutoverOptions,
 ): Promise<Error | null> {
-  deps.domEditSaveTimestampRef.current = Date.now();
   markSelfWrite(targetPath, after);
   try {
     await deps.writeProjectFile(targetPath, after, originalContent);

package/src/utils/setSlideshowManifest.test.ts

@@ -59,7 +59,6 @@ describe("persistSlideshowManifest — op construction", () => {
       editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
       writeProjectFile,
       reloadPreview: vi.fn(),
-      domEditSaveTimestampRef: { current: 0 },
     };
   }
 

package/src/utils/studioFileHistory.ts

@@ -16,7 +16,6 @@ export interface DomEditCommitBaseParams {
   activeCompPath: string | null;
   showToast: (message: string, tone?: "error" | "info") => void;
   writeProjectFile: ProjectFileWriter;
-  domEditSaveTimestampRef: MutableRefObject<number>;
   editHistory: { recordEdit: (entry: RecordEditInput) => Promise<void> };
   projectIdRef: MutableRefObject<string | null>;
   reloadPreview: () => void;

package/src/webmcp/types.ts

@@ -57,8 +57,12 @@ export interface ModelContextTool {
    * A rejection is NOT a usable error channel: the spec discards the reason and
    * rejects the caller with a bare UnknownError. Resolve with a tagged failure
    * instead. See `toolResult.ts`.
+   *
+   * `options` is optional here although the spec always passes it: the
+   * `@mcp-b/global` polyfill (through 5.1.0) calls `execute(input)` with no
+   * second argument, so a Studio handler must not depend on receiving one.
    */
-  execute: (input: object, options: ToolExecuteCallbackOptions) => Promise<unknown>;
+  execute: (input: object, options?: ToolExecuteCallbackOptions) => Promise<unknown>;
   annotations?: ModelContextToolAnnotations;
 }