@hyperframes/studio 0.6.110 → 0.6.111

package/src/hooks/useGsapPropertyDebounce.ts

@@ -1,11 +1,56 @@
 import { useCallback, useEffect, useRef } from "react";
+import type { Composition } from "@hyperframes/sdk";
+import { parseGsapScriptAcorn } from "@hyperframes/core/gsap-parser-acorn";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import {
+  sdkGsapTweenPersist,
+  sdkGsapRemovePropertyPersist,
+  type CutoverDeps,
+} from "../utils/sdkCutover";
+import { extractGsapScriptText } from "../utils/gsapSoftReload";
 import { PROPERTY_DEFAULTS } from "./gsapScriptCommitHelpers";
 import type { SafeGsapCommitMutation } from "./gsapScriptCommitTypes";
 
 const DEBOUNCE_MS = 150;
 
-export function useGsapPropertyDebounce(commitMutationSafely: SafeGsapCommitMutation) {
+/**
+ * The SDK `setGsapTween` 'set' path REPLACES a tween's editable property set
+ * (engine `handleSetGsapTween` → `updateAnimationInScript`), so sending only the
+ * single edited key would silently drop the tween's other animated props. Mirror
+ * the legacy server path (`{ ...anim.properties, [property]: val }`): read the
+ * tween's CURRENT properties from the in-memory SDK doc and merge the one edit in,
+ * so REPLACE semantics preserve siblings. Returns the single-key map unchanged
+ * when the tween/script can't be found (best-effort; before===after then falls
+ * back to the server path).
+ */
+export function mergeTweenProperties(
+  sdkSession: Composition,
+  animationId: string,
+  edited: Record<string, number | string>,
+  kind: "to" | "from",
+): Record<string, number | string> {
+  try {
+    const script = extractGsapScriptText(sdkSession.serialize());
+    if (!script) return { ...edited };
+    const anim = parseGsapScriptAcorn(script).animations.find((a) => a.id === animationId);
+    if (!anim) return { ...edited };
+    const existing = kind === "from" ? (anim.fromProperties ?? {}) : anim.properties;
+    return { ...existing, ...edited };
+  } catch {
+    return { ...edited };
+  }
+}
+
+interface SdkPropertyDeps {
+  sdkSession?: Composition | null;
+  sdkDeps?: CutoverDeps | null;
+  activeCompPath?: string | null;
+}
+
+export function useGsapPropertyDebounce(
+  commitMutationSafely: SafeGsapCommitMutation,
+  sdk?: SdkPropertyDeps,
+) {
   const pendingPropertyEditRef = useRef<{
     selection: DomEditSelection;
     animationId: string;
@@ -14,11 +59,38 @@ export function useGsapPropertyDebounce(commitMutationSafely: SafeGsapCommitMuta
   } | null>(null);
   const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  const flushPendingPropertyEdit = useCallback(() => {
+  // The caller passes `sdk` as a fresh object literal every render. Keying any
+  // callback's deps on it (esp. flushPendingPropertyEdit, whose identity drives
+  // the unmount-flush cleanup effect) re-fires the cleanup on EVERY parent
+  // re-render — so a playhead tick mid-slider-drag would flush + record an undo
+  // entry per render. Hold the latest value in a ref instead so every callback
+  // reads current deps without re-subscribing on identity churn.
+  const sdkRef = useRef(sdk);
+  sdkRef.current = sdk;
+
+  const flushPendingPropertyEdit = useCallback(async () => {
     const pending = pendingPropertyEditRef.current;
     if (!pending) return;
     pendingPropertyEditRef.current = null;
     const { selection, animationId, property, value } = pending;
+    const { sdkSession, sdkDeps, activeCompPath } = sdkRef.current ?? {};
+    if (sdkSession && sdkDeps) {
+      const targetPath = selection.sourceFile || activeCompPath || "index.html";
+      const handled = await sdkGsapTweenPersist(
+        targetPath,
+        {
+          kind: "set",
+          animationId,
+          properties: {
+            properties: mergeTweenProperties(sdkSession, animationId, { [property]: value }, "to"),
+          },
+        },
+        sdkSession,
+        sdkDeps,
+        { label: `Edit GSAP ${property}`, coalesceKey: `gsap:${animationId}:${property}` },
+      );
+      if (handled) return;
+    }
     commitMutationSafely(
       selection,
       { type: "update-property", animationId, property, value },
@@ -39,7 +111,9 @@ export function useGsapPropertyDebounce(commitMutationSafely: SafeGsapCommitMuta
     ) => {
       pendingPropertyEditRef.current = { selection, animationId, property, value };
       if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current);
-      debounceTimerRef.current = setTimeout(flushPendingPropertyEdit, DEBOUNCE_MS);
+      debounceTimerRef.current = setTimeout(() => {
+        void flushPendingPropertyEdit();
+      }, DEBOUNCE_MS);
     },
     [flushPendingPropertyEdit],
   );
@@ -47,12 +121,14 @@ export function useGsapPropertyDebounce(commitMutationSafely: SafeGsapCommitMuta
   useEffect(() => {
     return () => {
       if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current);
-      flushPendingPropertyEdit();
+      void flushPendingPropertyEdit();
     };
   }, [flushPendingPropertyEdit]);
 
+  // fallow-ignore-next-line complexity
   const addGsapProperty = useCallback(
-    (selection: DomEditSelection, animationId: string, property: string) => {
+    // fallow-ignore-next-line complexity
+    async (selection: DomEditSelection, animationId: string, property: string) => {
       let defaultValue = PROPERTY_DEFAULTS[property] ?? 0;
       const el = selection.element;
       if (property === "width" || property === "height") {
@@ -60,7 +136,33 @@ export function useGsapPropertyDebounce(commitMutationSafely: SafeGsapCommitMuta
         defaultValue = Math.round(property === "width" ? rect.width : rect.height);
       } else if (property === "opacity" || property === "autoAlpha") {
         const cs = el.ownerDocument.defaultView?.getComputedStyle(el);
-        defaultValue = cs ? Number.parseFloat(cs.opacity) || 1 : 1;
+        // Use `|| 1` only as a non-finite fallback, not a falsy fallback: an
+        // element currently at opacity 0 must seed 0, not 1.
+        const current = cs ? Number.parseFloat(cs.opacity) : Number.NaN;
+        defaultValue = Number.isFinite(current) ? current : 1;
+      }
+      const { sdkSession, sdkDeps, activeCompPath } = sdkRef.current ?? {};
+      if (sdkSession && sdkDeps) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkGsapTweenPersist(
+          targetPath,
+          {
+            kind: "set",
+            animationId,
+            properties: {
+              properties: mergeTweenProperties(
+                sdkSession,
+                animationId,
+                { [property]: defaultValue },
+                "to",
+              ),
+            },
+          },
+          sdkSession,
+          sdkDeps,
+          { label: `Add GSAP ${property}` },
+        );
+        if (handled) return;
       }
       commitMutationSafely(
         selection,
@@ -71,24 +173,82 @@ export function useGsapPropertyDebounce(commitMutationSafely: SafeGsapCommitMuta
     [commitMutationSafely],
   );
 
-  const removeGsapProperty = useCallback(
-    (selection: DomEditSelection, animationId: string, property: string) => {
-      commitMutationSafely(
-        selection,
-        { type: "remove-property", animationId, property },
-        { label: `Remove GSAP ${property}` },
-      );
+  const removeProperty = useCallback(
+    async (selection: DomEditSelection, animationId: string, property: string, from: boolean) => {
+      const { sdkSession, sdkDeps, activeCompPath } = sdkRef.current ?? {};
+      if (sdkSession && sdkDeps) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkGsapRemovePropertyPersist(
+          targetPath,
+          animationId,
+          property,
+          from,
+          sdkSession,
+          sdkDeps,
+          { label: `Remove GSAP ${from ? `from-${property}` : property}` },
+        );
+        if (handled) return;
+      }
+      if (from) {
+        commitMutationSafely(
+          selection,
+          { type: "remove-from-property", animationId, property },
+          {
+            label: `Remove GSAP from-${property}`,
+          },
+        );
+      } else {
+        commitMutationSafely(
+          selection,
+          { type: "remove-property", animationId, property },
+          {
+            label: `Remove GSAP ${property}`,
+          },
+        );
+      }
     },
     [commitMutationSafely],
   );
 
+  const removeGsapProperty = useCallback(
+    (selection: DomEditSelection, animationId: string, property: string) =>
+      removeProperty(selection, animationId, property, false),
+    [removeProperty],
+  );
+
   const updateGsapFromProperty = useCallback(
-    (
+    async (
       selection: DomEditSelection,
       animationId: string,
       property: string,
       value: number | string,
     ) => {
+      const { sdkSession, sdkDeps, activeCompPath } = sdkRef.current ?? {};
+      if (sdkSession && sdkDeps) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkGsapTweenPersist(
+          targetPath,
+          {
+            kind: "set",
+            animationId,
+            properties: {
+              fromProperties: mergeTweenProperties(
+                sdkSession,
+                animationId,
+                { [property]: value },
+                "from",
+              ),
+            },
+          },
+          sdkSession,
+          sdkDeps,
+          {
+            label: `Edit GSAP from-${property}`,
+            coalesceKey: `gsap:${animationId}:from:${property}`,
+          },
+        );
+        if (handled) return;
+      }
       commitMutationSafely(
         selection,
         { type: "update-from-property", animationId, property, value },
@@ -102,8 +262,31 @@ export function useGsapPropertyDebounce(commitMutationSafely: SafeGsapCommitMuta
   );
 
   const addGsapFromProperty = useCallback(
-    (selection: DomEditSelection, animationId: string, property: string) => {
+    async (selection: DomEditSelection, animationId: string, property: string) => {
       const defaultValue = PROPERTY_DEFAULTS[property] ?? 0;
+      const { sdkSession, sdkDeps, activeCompPath } = sdkRef.current ?? {};
+      if (sdkSession && sdkDeps) {
+        const targetPath = selection.sourceFile || activeCompPath || "index.html";
+        const handled = await sdkGsapTweenPersist(
+          targetPath,
+          {
+            kind: "set",
+            animationId,
+            properties: {
+              fromProperties: mergeTweenProperties(
+                sdkSession,
+                animationId,
+                { [property]: defaultValue },
+                "from",
+              ),
+            },
+          },
+          sdkSession,
+          sdkDeps,
+          { label: `Add GSAP from-${property}` },
+        );
+        if (handled) return;
+      }
       commitMutationSafely(
         selection,
         { type: "add-from-property", animationId, property, defaultValue },
@@ -114,14 +297,9 @@ export function useGsapPropertyDebounce(commitMutationSafely: SafeGsapCommitMuta
   );
 
   const removeGsapFromProperty = useCallback(
-    (selection: DomEditSelection, animationId: string, property: string) => {
-      commitMutationSafely(
-        selection,
-        { type: "remove-from-property", animationId, property },
-        { label: `Remove GSAP from-${property}` },
-      );
-    },
-    [commitMutationSafely],
+    (selection: DomEditSelection, animationId: string, property: string) =>
+      removeProperty(selection, animationId, property, true),
+    [removeProperty],
   );
 
   return {

package/src/hooks/useGsapPropertyDebounceFlush.test.ts

@@ -0,0 +1,85 @@
+// @vitest-environment happy-dom
+import React, { act, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useGsapPropertyDebounce } from "./useGsapPropertyDebounce";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+// The SDK path is gated on STUDIO_SDK_CUTOVER_ENABLED; keep it OFF so the flush
+// routes through commitMutationSafely (the spy we count), keeping the test about
+// flush TIMING, not the SDK write path.
+vi.mock("../components/editor/manualEditingAvailability", () => ({
+  STUDIO_SDK_CUTOVER_ENABLED: false,
+}));
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+const selection = { sourceFile: "index.html" } as unknown as DomEditSelection;
+
+describe("useGsapPropertyDebounce flush stability (finding #7)", () => {
+  let container: HTMLDivElement;
+  beforeEach(() => {
+    vi.useFakeTimers();
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    container.remove();
+  });
+
+  it("re-rendering the parent while an edit is pending does NOT flush early or duplicate commits", () => {
+    const commitMutationSafely = vi.fn();
+    let queueEdit: (() => void) | null = null;
+    let forceRerender: (() => void) | null = null;
+
+    function Harness() {
+      const [tick, setTick] = useState(0);
+      forceRerender = () => setTick((t) => t + 1);
+      // A FRESH sdk wrapper literal every render — the exact churn that, before
+      // the ref-stabilization fix, re-fired the unmount-flush cleanup effect.
+      const ops = useGsapPropertyDebounce(commitMutationSafely, {
+        sdkSession: null,
+        sdkDeps: null,
+        activeCompPath: "index.html",
+      });
+      queueEdit = () => ops.updateGsapProperty(selection, "tw-1", "x", tick + 1);
+      return React.createElement("div", null, String(tick));
+    }
+
+    const root = createRoot(container);
+    act(() => {
+      root.render(React.createElement(Harness));
+    });
+
+    // Queue one pending edit.
+    act(() => {
+      queueEdit?.();
+    });
+    expect(commitMutationSafely).not.toHaveBeenCalled();
+
+    // Re-render the parent several times BEFORE the debounce elapses. The bug
+    // flushed (and recorded a commit) on every re-render via the cleanup effect.
+    act(() => {
+      forceRerender?.();
+    });
+    act(() => {
+      forceRerender?.();
+    });
+    act(() => {
+      forceRerender?.();
+    });
+    expect(commitMutationSafely).not.toHaveBeenCalled();
+
+    // The debounce fires exactly once.
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(commitMutationSafely).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      root.unmount();
+    });
+  });
+});

package/src/hooks/useGsapScriptCommits.ts

@@ -1,9 +1,8 @@
-import { useCallback, useRef } from "react";
+import { useCallback, useMemo, useRef } from "react";
 import { findUnsafeMutationValues } from "@hyperframes/core/studio-api/finite-mutation";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
-import { applySoftReload } from "../utils/gsapSoftReload";
-import { resolveGsapFidelityArgs, runShadowGsapFidelity } from "../utils/sdkShadowGsapFidelity";
-import { runShadowGsapKeyframeFidelity } from "../utils/sdkShadowGsapKeyframe";
+import { applySoftReload, extractGsapScriptText } from "../utils/gsapSoftReload";
+import type { CutoverDeps } from "../utils/sdkCutover";
 import { updateKeyframeCacheFromParsed } from "./gsapKeyframeCacheHelpers";
 import { createKeyedSerializer } from "./serializeByKey";
 import {
@@ -46,15 +45,12 @@ async function mutateGsapScript(
 
 // oxfmt-ignore
 // fallow-ignore-next-line complexity
-export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast, sdkSession }: GsapScriptCommitsParams) {
+export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast, sdkSession, writeProjectFile, forceReloadSdkSession }: GsapScriptCommitsParams) {
   // Serializer for per-key commits (options.serializeKey). Keyed by
   // `gsap:${animationId}:meta`, it chains a meta commit onto the prior one for
-  // the same animationId so their POSTs can't interleave — which is what made
-  // the shadow fidelity diff pair an op with a stale server result and report
-  // false ease mismatches. Held in a ref so the chain survives re-renders.
+  // the same animationId so their POSTs can't interleave. Held in a ref so the
+  // chain survives re-renders.
   const serializerRef = useRef(createKeyedSerializer());
-  // Pre-existing complexity (server mutate + history + reload branches); this PR
-  // adds only a guarded shadow-fidelity dispatch.
   // fallow-ignore-next-line complexity
   const runCommit = useCallback(async (selection: DomEditSelection, mutation: Record<string, unknown>, options: CommitMutationOptions) => {
     const pid = projectIdRef.current;
@@ -76,32 +72,13 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
     }
     if (result.changed === false) return;
     domEditSaveTimestampRef.current = Date.now();
-    // Shadow value fidelity: diff the SDK's GSAP writer output against the
-    // server's, from the same pre-op file. Fire-and-forget; server authoritative.
-    // Meta-level ops carry shadowGsapOp (add / update-meta / delete via
-    // useGsapAnimationOps); keyframe ops carry shadowKeyframeOp (add/remove via
-    // useGsapKeyframeOps, handled by the gsap_keyframe block below). Per-property
-    // handlers (useGsapPropertyDebounce) don't synthesize one yet — deferred follow-up.
-    // scriptText is null when the composition has no GSAP script; nothing to diff.
-    const fidelityArgs = resolveGsapFidelityArgs(
-      sdkSession,
-      options.shadowGsapOp,
-      result.before,
-      result.scriptText,
-    );
-    if (fidelityArgs) {
-      void runShadowGsapFidelity(fidelityArgs.before, fidelityArgs.op, fidelityArgs.serverScript);
-    }
-    // Keyframe value fidelity (gsap_keyframe): same serialize-diff approach, but
-    // the SDK has no keyframe reader so there is no live-existence path — the diff
-    // is the only signal. Guarded on a live session + both scripts to diff.
-    if (sdkSession && options.shadowKeyframeOp && result.before != null && result.scriptText != null) {
-      void runShadowGsapKeyframeFidelity(result.before, options.shadowKeyframeOp, result.scriptText);
-    }
     if (result.before != null && result.after != null) {
       await editHistory.recordEdit({ label: options.label, kind: "manual", coalesceKey: options.coalesceKey, files: { [targetPath]: { before: result.before, after: result.after } } });
     }
     if (result.after != null) onFileContentChanged?.(targetPath, result.after);
+    // Server wrote the file; the in-memory SDK doc is now stale. Resync it so a
+    // later SDK-routed edit doesn't serialize the pre-write doc and revert this.
+    forceReloadSdkSession?.();
     if (options.skipReload) return;
     if (result.parsed?.animations) updateKeyframeCacheFromParsed(result.parsed.animations, targetPath, selection.id ?? undefined, mutation);
     options.beforeReload?.();
@@ -111,12 +88,10 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       reloadPreview();
     }
     onCacheInvalidate();
-  }, [projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast, sdkSession]);
+  }, [projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast, forceReloadSdkSession]);
   // Every GSAP-script commit is a read-modify-write of one file. Overlapping
-  // commits to the SAME file (any op type, any animation) interleave server-side
-  // and make the shadow fidelity diff pair an op with a stale server result —
-  // the false ease/value mismatches this serializer exists to prevent. So
-  // serialize per target file by default; an explicit serializeKey overrides.
+  // commits to the SAME file (any op type, any animation) interleave server-side,
+  // so serialize per target file by default; an explicit serializeKey overrides.
   const commitMutation = useCallback(
     (selection: DomEditSelection, mutation: Record<string, unknown>, options: CommitMutationOptions) => {
       const file = selection.sourceFile || activeCompPath || "index.html";
@@ -127,9 +102,89 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
   );
   const trackGsapSaveFailure = useGsapSaveFailureTelemetry(activeCompPath);
   const commitMutationSafely = useSafeGsapCommitMutation(commitMutation, trackGsapSaveFailure, showToast);
-  const propertyOps = useGsapPropertyDebounce(commitMutationSafely);
-  const animationOps = useGsapAnimationOps({ projectIdRef, activeCompPath, commitMutation, commitMutationSafely, showToast, sdkSession });
-  const keyframeOps = useGsapKeyframeOps({ activeCompPath, commitMutation, commitMutationSafely, trackGsapSaveFailure });
+
+  // One stable SDK-deps object shared by all GSAP child hooks. Memoized so the
+  // hooks' callbacks keep a stable identity (an inline literal here re-fired the
+  // property-debounce flush on every render). refresh() soft-reloads (preserving
+  // the playhead) and invalidates the panel cache, matching the server path.
+  const sdkRefresh = useCallback(
+    (after: string) => {
+      const script = extractGsapScriptText(after);
+      if (!(script && applySoftReload(previewIframeRef.current, script))) reloadPreview();
+      onCacheInvalidate();
+    },
+    [previewIframeRef, reloadPreview, onCacheInvalidate],
+  );
+  // Reuse the SAME per-file serializer the legacy commitMutation path uses, so
+  // SDK gsap-write flushes serialize against legacy commits AND each other —
+  // overlapping same-file read-modify-writes can't interleave and lose an edit.
+  const serializeByFile = useCallback(
+    <T>(key: string, task: () => Promise<T>): Promise<T> => serializerRef.current(key, task),
+    [],
+  );
+  // Read the on-disk bytes of targetPath so the SDK GSAP persist captures the
+  // exact prior content as its undo `before` (matching the style/delete paths),
+  // instead of a normalized full-DOM re-emit that would reformat the whole file.
+  const readProjectFileContent = useCallback(
+    async (path: string): Promise<string> => {
+      const pid = projectIdRef.current;
+      if (!pid) throw new Error("No active project");
+      const res = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`);
+      if (!res.ok) throw new Error(`Failed to read ${path}`);
+      const data = (await res.json()) as { content?: string };
+      if (typeof data.content !== "string") throw new Error(`Missing file contents for ${path}`);
+      return data.content;
+    },
+    [projectIdRef],
+  );
+  const sdkDeps = useMemo<CutoverDeps | null>(
+    () =>
+      writeProjectFile
+        ? {
+            editHistory: { recordEdit: editHistory.recordEdit },
+            writeProjectFile,
+            reloadPreview,
+            domEditSaveTimestampRef,
+            refresh: sdkRefresh,
+            compositionPath: activeCompPath,
+            serialize: serializeByFile,
+            readProjectFile: readProjectFileContent,
+          }
+        : null,
+    [
+      editHistory.recordEdit,
+      writeProjectFile,
+      reloadPreview,
+      domEditSaveTimestampRef,
+      sdkRefresh,
+      activeCompPath,
+      serializeByFile,
+      readProjectFileContent,
+    ],
+  );
+
+  const propertyOps = useGsapPropertyDebounce(commitMutationSafely, {
+    sdkSession,
+    sdkDeps,
+    activeCompPath,
+  });
+  const animationOps = useGsapAnimationOps({
+    projectIdRef,
+    activeCompPath,
+    commitMutation,
+    commitMutationSafely,
+    showToast,
+    sdkSession,
+    sdkDeps,
+  });
+  const keyframeOps = useGsapKeyframeOps({
+    activeCompPath,
+    commitMutation,
+    commitMutationSafely,
+    trackGsapSaveFailure,
+    sdkSession,
+    sdkDeps,
+  });
   const arcPathOps = useGsapArcPathOps(commitMutationSafely);
   return { commitMutation, ...propertyOps, ...animationOps, ...keyframeOps, ...arcPathOps };
 }

package/src/hooks/useSdkSession.test.ts

@@ -1,6 +1,18 @@
 import { describe, expect, it } from "vitest";
 import { shouldReloadSdkSession } from "./useSdkSession";
 
+// ── undo-sync contract ────────────────────────────────────────────────────────
+// useSdkSession exposes forceReload() so callers can bypass the 2 s self-write
+// suppress window. useAppHotkeys calls forceReload() after a successful
+// undo/redo that wrote the active composition path. Without it, the suppress
+// window swallows the file-change event and the SDK session stays stale.
+//
+// The React hook internals (useState / useEffect) cannot be unit-tested without
+// a full render environment; the correctness of the suppress-bypass path is
+// covered by the integration tests in usePersistentEditHistory.test.ts
+// (which verify undo writes the correct before-content to disk).
+// ─────────────────────────────────────────────────────────────────────────────
+
 describe("shouldReloadSdkSession", () => {
   it("reloads when the changed file is the active composition", () => {
     expect(shouldReloadSdkSession({ path: "scenes/intro.html" }, "scenes/intro.html")).toBe(true);