@hyperframes/studio 0.7.92 → 0.7.93

package/src/components/editor/propertyPanelFlatPrimitives.test.tsx

@@ -90,6 +90,75 @@ describe("FlatRow", () => {
     act(() => root.unmount());
   });
 
+  it("restores its durable value when an async commit rejects", async () => {
+    let rejectCommit: ((error: Error) => void) | null = null;
+    const onCommit = vi.fn(
+      () =>
+        new Promise<void>((_resolve, reject) => {
+          rejectCommit = reject;
+        }),
+    );
+    const row = (value: string) => (
+      <FlatRow label="X" value={value} tier="explicitDefault" onCommit={onCommit} />
+    );
+    const { host, root } = renderInto(row("22px"));
+    const input = host.querySelector<HTMLInputElement>("input");
+    if (!input) throw new Error("expected an input");
+    act(() => {
+      const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype,
+        "value",
+      )?.set;
+      nativeInputValueSetter?.call(input, "99px");
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+      input.dispatchEvent(new Event("focusout", { bubbles: true }));
+    });
+    // The parent can echo the preview before persistence settles. That is not a
+    // durable acknowledgement and must not invalidate the pending rollback.
+    act(() => root.render(row("99px")));
+    await act(async () => {
+      rejectCommit?.(new Error("save failed"));
+      await Promise.resolve();
+    });
+
+    expect(onCommit).toHaveBeenCalledWith("99px");
+    expect(input.value).toBe("22px");
+    act(() => root.unmount());
+  });
+
+  it("does not let an older rejected commit overwrite a newer draft", async () => {
+    let rejectCommit: ((error: Error) => void) | null = null;
+    const onCommit = vi.fn(
+      () =>
+        new Promise<void>((_resolve, reject) => {
+          rejectCommit = reject;
+        }),
+    );
+    const { host, root } = renderInto(
+      <FlatRow label="X" value="22px" tier="explicitDefault" onCommit={onCommit} />,
+    );
+    const input = host.querySelector<HTMLInputElement>("input");
+    if (!input) throw new Error("expected an input");
+    const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+      window.HTMLInputElement.prototype,
+      "value",
+    )?.set;
+    act(() => {
+      nativeInputValueSetter?.call(input, "99px");
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+      input.dispatchEvent(new Event("focusout", { bubbles: true }));
+      nativeInputValueSetter?.call(input, "100px");
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+    await act(async () => {
+      rejectCommit?.(new Error("old save failed"));
+      await Promise.resolve();
+    });
+
+    expect(input.value).toBe("100px");
+    act(() => root.unmount());
+  });
+
   it("persists a rapid numeric arrow-key burst as one commit", () => {
     vi.useFakeTimers();
     const onCommit = vi.fn();

package/src/components/editor/propertyPanelFlatPrimitives.tsx

@@ -35,7 +35,7 @@ export function FlatRow({
   /** Renders a trailing 10px caret-down, for select-backed rows. */
   dropdown?: boolean;
   onPreview?: (nextValue: string) => void;
-  onCommit: (nextValue: string) => void;
+  onCommit: (nextValue: string) => void | Promise<void>;
   onReset?: () => void;
 }) {
   const track = useTrackDesignInput();
@@ -59,7 +59,7 @@ export function FlatRow({
             onPreview={onPreview}
             onCommit={(nextValue) => {
               track("metric", label);
-              onCommit(nextValue);
+              return onCommit(nextValue);
             }}
           />
         </span>

package/src/components/editor/propertyPanelPrimitives.tsx

@@ -29,14 +29,14 @@ export function MetricField({
   scrub?: boolean;
   suffix?: string;
   tooltip?: string;
-  onCommit: (nextValue: string) => void;
+  onCommit: (nextValue: string) => void | Promise<void>;
 }) {
   const track = useTrackDesignInput();
   const scrubRef = useRef<{ startX: number; startValue: number; pointerId: number } | null>(null);
   const commit = useCallback(
     (nextValue: string) => {
       if (nextValue !== value) track("metric", label);
-      onCommit(nextValue);
+      return onCommit(nextValue);
     },
     [label, onCommit, track, value],
   );

package/src/components/editor/propertyPanelTransformCommit.test.ts

@@ -0,0 +1,57 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "./domEditingTypes";
+import { GsapEditBlockedError } from "../../hooks/gsapEditOutcome";
+import { createTransformCommitHandlers } from "./propertyPanelTransformCommit";
+
+describe("createTransformCommitHandlers", () => {
+  it.each([
+    [
+      "position",
+      (handlers: ReturnType<typeof createTransformCommitHandlers>) =>
+        handlers.commitManualOffset("x", "20px"),
+    ],
+    [
+      "size",
+      (handlers: ReturnType<typeof createTransformCommitHandlers>) =>
+        handlers.commitManualSize("width", "200px"),
+    ],
+    [
+      "rotation",
+      (handlers: ReturnType<typeof createTransformCommitHandlers>) =>
+        handlers.commitManualRotation("45"),
+    ],
+  ])("propagates blocked %s edits so the field can roll back", async (_name, commit) => {
+    const blocked = new GsapEditBlockedError("unroll-required");
+    const onCommitAnimatedProperty = vi.fn().mockRejectedValue(blocked);
+    const onSetManualOffset = vi.fn();
+    const onSetManualSize = vi.fn();
+    const onSetManualRotation = vi.fn();
+    const element = {
+      id: "box",
+      selector: "#box",
+      element: document.createElement("div"),
+      boundingBox: { width: 100, height: 100 },
+    } as unknown as DomEditSelection;
+    const handlers = createTransformCommitHandlers({
+      element,
+      styles: {},
+      hasGsapAnimation: true,
+      gsapAnimId: "#box-to-position",
+      gsapKeyframes: null,
+      currentPct: 0,
+      onCommitAnimatedProperty,
+      onAddKeyframe: undefined,
+      onSetManualOffset,
+      onSetManualSize,
+      onSetManualRotation,
+      showToast: vi.fn(),
+    });
+
+    await expect(commit(handlers)).rejects.toBe(blocked);
+    expect(onSetManualOffset).not.toHaveBeenCalled();
+    expect(onSetManualSize).not.toHaveBeenCalled();
+    expect(onSetManualRotation).not.toHaveBeenCalled();
+  });
+});

package/src/components/editor/propertyPanelTransformCommit.ts

@@ -41,13 +41,13 @@ export function createTransformCommitHandlers({
   // Route a transform value into the GSAP animation (or a new keyframe) when the
   // element is animated. Returns true when handled, so callers fall through to
   // the manual-transform path only for non-animated elements.
-  const commitAnimatedTransformValue = (
+  const commitAnimatedTransformValue = async (
     property: string,
     value: number,
     noCallbacksMessage: string,
-  ): boolean => {
+  ): Promise<boolean> => {
     if (onCommitAnimatedProperty && hasGsapAnimation) {
-      void onCommitAnimatedProperty(element, property, value);
+      await onCommitAnimatedProperty(element, property, value);
       return true;
     }
     if (gsapKeyframes && gsapAnimId && onAddKeyframe) {
@@ -62,11 +62,11 @@ export function createTransformCommitHandlers({
     return false;
   };
 
-  const commitManualOffset = (axis: "x" | "y", nextValue: string) => {
+  const commitManualOffset = async (axis: "x" | "y", nextValue: string) => {
     const parsed = parsePxMetricValue(nextValue);
     if (parsed == null) return;
     if (
-      commitAnimatedTransformValue(
+      await commitAnimatedTransformValue(
         axis,
         parsed,
         "Cannot edit position — animation callbacks not available",
@@ -74,20 +74,20 @@ export function createTransformCommitHandlers({
     )
       return;
     const current = readStudioPathOffset(element.element);
-    void Promise.resolve(
+    await Promise.resolve(
       onSetManualOffset(element, {
         x: axis === "x" ? parsed : current.x,
         y: axis === "y" ? parsed : current.y,
       }),
-    ).catch(() => undefined);
+    );
   };
 
   // fallow-ignore-next-line complexity
-  const commitManualSize = (axis: "width" | "height", nextValue: string) => {
+  const commitManualSize = async (axis: "width" | "height", nextValue: string) => {
     const parsed = parsePxMetricValue(nextValue);
     if (parsed == null || parsed <= 0) return;
     if (onCommitAnimatedProperty && hasGsapAnimation) {
-      void onCommitAnimatedProperty(element, axis, parsed);
+      await onCommitAnimatedProperty(element, axis, parsed);
       return;
     }
     if (hasGsapAnimation) {
@@ -103,26 +103,26 @@ export function createTransformCommitHandlers({
       current.height > 0
         ? current.height
         : (parsePxMetricValue(styles.height ?? "") ?? element.boundingBox.height);
-    void Promise.resolve(
+    await Promise.resolve(
       onSetManualSize(element, {
         width: axis === "width" ? parsed : width,
         height: axis === "height" ? parsed : height,
       }),
-    ).catch(() => undefined);
+    );
   };
 
-  const commitManualRotation = (nextValue: string) => {
+  const commitManualRotation = async (nextValue: string) => {
     const parsed = Number.parseFloat(nextValue);
     if (!Number.isFinite(parsed)) return;
     if (
-      commitAnimatedTransformValue(
+      await commitAnimatedTransformValue(
         "rotation",
         parsed,
         "Cannot edit rotation — animation callbacks not available",
       )
     )
       return;
-    void Promise.resolve(onSetManualRotation(element, { angle: parsed })).catch(() => undefined);
+    await Promise.resolve(onSetManualRotation(element, { angle: parsed }));
   };
 
   return { commitManualOffset, commitManualSize, commitManualRotation };

package/src/components/editor/propertyPanelTypes.ts

@@ -71,9 +71,15 @@ export interface PropertyPanelProps {
       onProgress?: (progress: BackgroundRemovalProgress) => void;
     },
   ) => Promise<BackgroundRemovalResult>;
-  onSetManualOffset: (element: DomEditSelection, next: { x: number; y: number }) => void;
-  onSetManualSize: (element: DomEditSelection, next: { width: number; height: number }) => void;
-  onSetManualRotation: (element: DomEditSelection, next: { angle: number }) => void;
+  onSetManualOffset: (
+    element: DomEditSelection,
+    next: { x: number; y: number },
+  ) => void | Promise<void>;
+  onSetManualSize: (
+    element: DomEditSelection,
+    next: { width: number; height: number },
+  ) => void | Promise<void>;
+  onSetManualRotation: (element: DomEditSelection, next: { angle: number }) => void | Promise<void>;
   onSetText: (value: string, fieldKey?: string) => void;
   onSetTextFieldStyle: (fieldKey: string, property: string, value: string) => void;
   onPreviewTextFieldStyle?: (fieldKey: string, property: string, value: string) => void;

package/src/components/editor/useInspectorGestureTransaction.test.tsx

@@ -8,6 +8,30 @@ import { useInspectorGestureTransaction } from "./useInspectorGestureTransaction
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 describe("useInspectorGestureTransaction", () => {
+  it("restores the durable baseline when an inspector commit rejects", async () => {
+    const host = document.createElement("div");
+    const root = createRoot(host);
+    const onPreview = vi.fn();
+    const onCommit = vi.fn().mockRejectedValue(new Error("save failed"));
+    let gesture: ReturnType<typeof useInspectorGestureTransaction<number>> | null = null;
+
+    function Probe() {
+      gesture = useInspectorGestureTransaction({ sourceValue: 10, onPreview, onCommit });
+      return null;
+    }
+
+    act(() => root.render(<Probe />));
+    act(() => {
+      gesture?.preview(25);
+      gesture?.settle();
+    });
+    expect(onPreview.mock.calls.map(([value]) => value)).toEqual([25]);
+    await act(async () => Promise.resolve());
+
+    expect(onPreview.mock.calls.map(([value]) => value)).toEqual([25, 10]);
+    act(() => root.unmount());
+  });
+
   it("keeps a new gesture active when the prior async commit is acknowledged", () => {
     const host = document.createElement("div");
     const root = createRoot(host);
@@ -34,4 +58,45 @@ describe("useInspectorGestureTransaction", () => {
 
     act(() => root.unmount());
   });
+
+  it("does not let an older rejected commit roll back a newer successful gesture", async () => {
+    const host = document.createElement("div");
+    const root = createRoot(host);
+    const onPreview = vi.fn();
+    let rejectFirst: ((error: Error) => void) | null = null;
+    const onCommit = vi
+      .fn()
+      .mockImplementationOnce((value: number) => {
+        onPreview(value);
+        return new Promise<void>((_resolve, reject) => {
+          rejectFirst = reject;
+        });
+      })
+      .mockImplementationOnce((value: number) => {
+        onPreview(value);
+        return Promise.resolve();
+      });
+    let gesture: ReturnType<typeof useInspectorGestureTransaction<number>> | null = null;
+
+    function Probe() {
+      gesture = useInspectorGestureTransaction({ sourceValue: 10, onPreview, onCommit });
+      return null;
+    }
+
+    act(() => root.render(<Probe />));
+    act(() => {
+      gesture?.preview(20);
+      gesture?.settle();
+      gesture?.preview(30);
+      gesture?.settle();
+    });
+    await act(async () => {
+      rejectFirst?.(new Error("old save failed"));
+      await Promise.resolve();
+    });
+
+    expect(onCommit.mock.calls.map(([value]) => value)).toEqual([20, 30]);
+    expect(onPreview).toHaveBeenLastCalledWith(30);
+    act(() => root.unmount());
+  });
 });

package/src/components/editor/useInspectorGestureTransaction.ts

@@ -1,5 +1,9 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 
+function isPromiseCommit(result: void | Promise<void>): result is Promise<void> {
+  return Boolean(result && typeof result.then === "function");
+}
+
 /** One owner for continuous inspector edits: preview freely, persist once. */
 export function useInspectorGestureTransaction<T>({
   sourceValue,
@@ -8,44 +12,96 @@ export function useInspectorGestureTransaction<T>({
 }: {
   sourceValue: T;
   onPreview: (value: T) => void;
-  onCommit: (value: T) => void;
+  onCommit: (value: T) => void | Promise<void>;
 }) {
   const sourceRef = useRef(sourceValue);
   const activeRef = useRef<{ before: T; latest: T } | null>(null);
   const previewRef = useRef(onPreview);
   const commitRef = useRef(onCommit);
-  if (!activeRef.current) sourceRef.current = sourceValue;
+  const generationRef = useRef(0);
+  const pendingRef = useRef<{ before: T; latest: T } | null>(null);
+  const awaitingSourceAckRef = useRef<{ generation: number; value: T } | null>(null);
+  const lastSourceValueRef = useRef(sourceValue);
+  if (!Object.is(lastSourceValueRef.current, sourceValue)) {
+    lastSourceValueRef.current = sourceValue;
+    const matchesSourceAck = Object.is(awaitingSourceAckRef.current?.value, sourceValue);
+    const matchesOptimisticValue =
+      (activeRef.current && Object.is(activeRef.current.latest, sourceValue)) ||
+      (pendingRef.current && Object.is(pendingRef.current.latest, sourceValue)) ||
+      matchesSourceAck;
+    if (matchesSourceAck) awaitingSourceAckRef.current = null;
+    if (!matchesOptimisticValue) {
+      generationRef.current += 1;
+      activeRef.current = null;
+      pendingRef.current = null;
+      awaitingSourceAckRef.current = null;
+      sourceRef.current = sourceValue;
+    } else {
+      sourceRef.current = sourceValue;
+    }
+  }
   previewRef.current = onPreview;
   commitRef.current = onCommit;
 
   const begin = useCallback(() => {
     if (!activeRef.current) {
+      generationRef.current += 1;
       activeRef.current = { before: sourceRef.current, latest: sourceRef.current };
     }
   }, []);
 
   const preview = useCallback((value: T) => {
     if (!activeRef.current) {
+      generationRef.current += 1;
       activeRef.current = { before: sourceRef.current, latest: sourceRef.current };
     }
     activeRef.current.latest = value;
     previewRef.current(value);
   }, []);
 
+  const rollbackCommit = useCallback((active: { before: T; latest: T }, generation: number) => {
+    if (generation !== generationRef.current) return;
+    pendingRef.current = null;
+    if (awaitingSourceAckRef.current?.generation === generation) {
+      awaitingSourceAckRef.current = null;
+    }
+    sourceRef.current = active.before;
+    previewRef.current(active.before);
+  }, []);
+
   const settle = useCallback(() => {
     const active = activeRef.current;
     activeRef.current = null;
     if (active && !Object.is(active.before, active.latest)) {
+      const generation = ++generationRef.current;
       sourceRef.current = active.latest;
-      // Restore the captured baseline before the persistent commit captures
-      // rollback state. The commit reapplies `latest` synchronously, so this
-      // is not visible but a failed save can now correctly restore `before`.
-      previewRef.current(active.before);
-      commitRef.current(active.latest);
+      pendingRef.current = active;
+      awaitingSourceAckRef.current = { generation, value: active.latest };
+      try {
+        const result = commitRef.current(active.latest);
+        if (isPromiseCommit(result)) {
+          void result.then(
+            () => {
+              if (generation === generationRef.current) pendingRef.current = null;
+            },
+            () => rollbackCommit(active, generation),
+          );
+        } else if (generation === generationRef.current) {
+          pendingRef.current = null;
+          // Synchronous inspector consumers historically restore their preview
+          // after persisting (color pickers close, curves release the pointer).
+          // Async source mutations keep the optimistic preview until the write
+          // resolves so they do not flash back to the baseline while pending.
+          previewRef.current(active.before);
+        }
+      } catch {
+        rollbackCommit(active, generation);
+      }
     }
-  }, []);
+  }, [rollbackCommit]);
 
   const cancel = useCallback(() => {
+    generationRef.current += 1;
     const active = activeRef.current;
     activeRef.current = null;
     if (active && !Object.is(active.before, active.latest)) {
@@ -66,7 +122,7 @@ export function useInspectorGestureDraft<T>({
 }: {
   sourceValue: T;
   onPreview: (value: T) => void;
-  onCommit: (value: T) => void;
+  onCommit: (value: T) => void | Promise<void>;
 }) {
   const [draft, setDraft] = useState(sourceValue);
   const transaction = useInspectorGestureTransaction({
@@ -77,7 +133,7 @@ export function useInspectorGestureDraft<T>({
     },
     onCommit: (next) => {
       setDraft(next);
-      onCommit(next);
+      return onCommit(next);
     },
   });
 

package/src/components/sidebar/AssetCard.tsx

@@ -8,6 +8,7 @@ import { VIDEO_EXT, IMAGE_EXT } from "../../utils/mediaTypes";
 import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
 import { ContextMenu } from "./AssetContextMenu";
 import { usePlayerStore } from "../../player/store/playerStore";
+import { timelineClipFocusId } from "../../player/components/timelineNavigationIdentity";
 import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
 import { findClipForAsset, isPointerClick } from "../../utils/assetClickBehavior";
 import { basename, ext, truncateMiddle, formatDuration } from "./assetHelpers";
@@ -133,7 +134,7 @@ export function AssetCard({
   const pointerDownRef = useRef<{ x: number; y: number } | null>(null);
 
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
-  const requestClipReveal = usePlayerStore((s) => s.requestClipReveal);
+  const requestTimelineFocus = usePlayerStore((s) => s.requestTimelineFocus);
   const elements = usePlayerStore((s) => s.elements);
   const setPreviewAsset = useAssetPreviewStore((s) => s.setPreviewAsset);
   const clearPreviewAsset = useAssetPreviewStore((s) => s.clearPreviewAsset);
@@ -158,7 +159,7 @@ export function AssetCard({
           const clipKey = clip.key ?? clip.id;
           setSelectedElementId(clipKey);
           // Scroll the timeline so the selected clip is actually visible.
-          requestClipReveal(clipKey);
+          requestTimelineFocus(timelineClipFocusId(clipKey));
           return;
         }
       }
@@ -171,7 +172,7 @@ export function AssetCard({
       asset,
       projectId,
       setSelectedElementId,
-      requestClipReveal,
+      requestTimelineFocus,
       setPreviewAsset,
       clearPreviewAsset,
     ],

package/src/components/sidebar/AudioRow.tsx

@@ -6,6 +6,7 @@ import { usePlayerStore } from "../../player/store/playerStore";
 import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
 import { findClipForAsset, isPointerClick } from "../../utils/assetClickBehavior";
 import { resolveMediaPreviewUrl } from "../../player/components/thumbnailUtils";
+import { timelineClipFocusId } from "../../player/components/timelineNavigationIdentity";
 
 export function AudioRow({
   projectId,
@@ -43,7 +44,7 @@ export function AudioRow({
   // CapCut-style click behavior: drag-threshold gate.
   const pointerDownRef = useRef<{ x: number; y: number } | null>(null);
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
-  const requestClipReveal = usePlayerStore((s) => s.requestClipReveal);
+  const requestTimelineFocus = usePlayerStore((s) => s.requestTimelineFocus);
   const elements = usePlayerStore((s) => s.elements);
   const setPreviewAsset = useAssetPreviewStore((s) => s.setPreviewAsset);
   const clearPreviewAsset = useAssetPreviewStore((s) => s.clearPreviewAsset);
@@ -67,7 +68,7 @@ export function AudioRow({
           const clipKey = clip.key ?? clip.id;
           setSelectedElementId(clipKey);
           // Scroll the timeline so the selected clip is actually visible.
-          requestClipReveal(clipKey);
+          requestTimelineFocus(timelineClipFocusId(clipKey));
           return;
         }
       }
@@ -80,7 +81,7 @@ export function AudioRow({
       asset,
       projectId,
       setSelectedElementId,
-      requestClipReveal,
+      requestTimelineFocus,
       setPreviewAsset,
       clearPreviewAsset,
     ],

package/src/contexts/FileManagerContext.tsx

@@ -27,9 +27,13 @@ export function FileManagerProvider({
     editingPathRef,
     projectIdRef,
     saveRafRef,
+    flushPendingSourceSave,
+    discardPendingSourceSave,
+    getPendingSourceCandidate,
     importedFontAssetsRef,
     readProjectFile,
     writeProjectFile,
+    overwriteExternalConflict,
     readOptionalProjectFile,
     observeProjectFileVersion,
     updateEditingFileContent,
@@ -67,9 +71,13 @@ export function FileManagerProvider({
       editingPathRef,
       projectIdRef,
       saveRafRef,
+      flushPendingSourceSave,
+      discardPendingSourceSave,
+      getPendingSourceCandidate,
       importedFontAssetsRef,
       readProjectFile,
       writeProjectFile,
+      overwriteExternalConflict,
       readOptionalProjectFile,
       observeProjectFileVersion,
       updateEditingFileContent,
@@ -101,9 +109,13 @@ export function FileManagerProvider({
       editingPathRef,
       projectIdRef,
       saveRafRef,
+      flushPendingSourceSave,
+      discardPendingSourceSave,
+      getPendingSourceCandidate,
       importedFontAssetsRef,
       readProjectFile,
       writeProjectFile,
+      overwriteExternalConflict,
       readOptionalProjectFile,
       observeProjectFileVersion,
       updateEditingFileContent,

package/src/hooks/externalFileChangeOwnership.test.ts

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+describe("external file-change subscription ownership", () => {
+  it("has one subscriber instead of independent Preview and SDK listeners", () => {
+    const preview = readFileSync(new URL("./usePreviewPersistence.ts", import.meta.url), "utf8");
+    const sdk = readFileSync(new URL("./useSdkSession.ts", import.meta.url), "utf8");
+    const coordinator = readFileSync(
+      new URL("./useExternalFileChangeCoordinator.ts", import.meta.url),
+      "utf8",
+    );
+
+    expect(preview).not.toContain('hot.on("hf:file-change"');
+    expect(sdk).not.toContain('hot.on("hf:file-change"');
+    expect(coordinator.match(/hot\.on\("hf:file-change"/g)).toHaveLength(1);
+  });
+});

package/src/hooks/externalFileReloadBus.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from "vitest";
+import { addExternalFileReloadListener, notifyExternalFileReload } from "./externalFileReloadBus";
+
+describe("external file reload bus", () => {
+  it("lets the sole watcher reload every SDK owner of the changed path", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const removeFirst = addExternalFileReloadListener(first);
+    const removeSecond = addExternalFileReloadListener(second);
+
+    notifyExternalFileReload("scenes/card.html");
+    expect(first).toHaveBeenCalledWith("scenes/card.html");
+    expect(second).toHaveBeenCalledWith("scenes/card.html");
+
+    removeFirst();
+    removeSecond();
+  });
+
+  it("isolates a broken listener so later SDK owners still reload", () => {
+    const broken = vi.fn(() => {
+      throw new Error("stale owner");
+    });
+    const healthy = vi.fn();
+    const removeBroken = addExternalFileReloadListener(broken);
+    const removeHealthy = addExternalFileReloadListener(healthy);
+
+    expect(() => notifyExternalFileReload("scenes/card.html")).not.toThrow();
+    expect(broken).toHaveBeenCalledWith("scenes/card.html");
+    expect(healthy).toHaveBeenCalledWith("scenes/card.html");
+
+    removeBroken();
+    removeHealthy();
+  });
+});

package/src/hooks/externalFileReloadBus.ts

@@ -0,0 +1,18 @@
+type ExternalFileReloadListener = (path: string) => void;
+
+const listeners = new Set<ExternalFileReloadListener>();
+
+export function addExternalFileReloadListener(listener: ExternalFileReloadListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function notifyExternalFileReload(path: string): void {
+  for (const listener of listeners) {
+    try {
+      listener(path);
+    } catch {
+      // A stale SDK owner must not prevent sibling owners from reloading.
+    }
+  }
+}