@hyperframes/studio 0.6.109 → 0.6.111

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/useGsapTweenCache.ts

@@ -366,13 +366,6 @@ export function usePopulateKeyframeCacheForFile(
       const { setKeyframeCache } = usePlayerStore.getState();
       clearKeyframeCacheForFile(sf);
       const { elements } = usePlayerStore.getState();
-      console.log(
-        "[kf:static] elements in store:",
-        elements
-          .map((e) => e.domId)
-          .filter(Boolean)
-          .join(", "),
-      );
       const mergedByElement = new Map<string, GsapKeyframesData>();
       for (const anim of parsed.animations) {
         const id = extractIdFromSelector(anim.targetSelector);
@@ -415,12 +408,6 @@ export function usePopulateKeyframeCacheForFile(
           mergedByElement.set(id, { ...kfData, keyframes: clipKeyframes });
         }
       }
-      console.log(
-        "[kf:static] merged elements:",
-        [...mergedByElement.keys()].join(", "),
-        "kf counts:",
-        [...mergedByElement.entries()].map(([k, v]) => `${k}:${v.keyframes.length}`).join(", "),
-      );
       for (const [id, kfData] of mergedByElement) {
         setKeyframeCache(`${sf}#${id}`, kfData);
         setKeyframeCache(id, kfData);
@@ -454,12 +441,6 @@ export function usePopulateKeyframeCacheForFile(
         if (el.domId) clipById.set(el.domId, { start: el.start, duration: el.duration });
       }
       const scanned = scanAllRuntimeKeyframes(iframe, clipById);
-      console.log(
-        "[kf:runtime] scanned",
-        scanned.size,
-        "elements:",
-        [...scanned.keys()].join(", "),
-      );
       if (scanned.size === 0) return false;
       const { setKeyframeCache, keyframeCache } = usePlayerStore.getState();
       for (const [id, data] of scanned) {
@@ -470,14 +451,6 @@ export function usePopulateKeyframeCacheForFile(
         if (alreadyCached) {
           continue;
         }
-        console.log(
-          "[kf:runtime] adding runtime entry:",
-          id,
-          "kfs:",
-          data.keyframes.length,
-          "arc:",
-          !!data.arcPath,
-        );
         const entry = {
           format: "percentage" as const,
           keyframes: data.keyframes,

package/src/hooks/useRazorSplit.ts

@@ -5,10 +5,10 @@ import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import { getTimelineElementLabel, collectHtmlIds } from "../utils/studioHelpers";
 import { trackStudioRazorSplit } from "../telemetry/events";
 import {
-  canSplitElement,
+  canSplitElementAt,
+  selectSplittableElements,
   buildPatchTarget,
   readFileContent,
-  isSplitTimeWithinBounds,
 } from "../utils/timelineElementSplit";
 import type { RecordEditInput } from "./timelineEditingHelpers";
 
@@ -170,11 +170,7 @@ export function useRazorSplit({
       }
 
       const pid = projectIdRef.current;
-      if (!pid || !canSplitElement(element)) return;
-
-      if (!isSplitTimeWithinBounds(splitTime, element.start, element.duration)) {
-        return;
-      }
+      if (!pid || !canSplitElementAt(element, splitTime)) return;
 
       try {
         const { targetPath, originalContent, patchedContent, changed, skippedSelectors } =
@@ -232,9 +228,7 @@ export function useRazorSplit({
       const pid = projectIdRef.current;
       if (!pid) return;
       const { elements } = usePlayerStore.getState();
-      const splittable = elements.filter(
-        (el) => canSplitElement(el) && splitTime > el.start && splitTime < el.start + el.duration,
-      );
+      const splittable = selectSplittableElements(elements, splitTime);
       if (splittable.length === 0) return;
 
       try {

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);

package/src/hooks/useSdkSession.ts

@@ -1,8 +1,10 @@
-import { useState, useEffect } from "react";
+import { useState, useEffect, useCallback } from "react";
+import type { MutableRefObject } from "react";
 import { openComposition } from "@hyperframes/sdk";
 import { createHttpAdapter } from "@hyperframes/sdk/adapters/http";
 import type { Composition } from "@hyperframes/sdk";
 import { readStudioFileChangePath } from "../components/editor/manualEdits";
+import { isSelfWriteEcho } from "./sdkSelfWriteRegistry";
 
 /**
  * True when an external file-change payload targets the active composition and
@@ -20,33 +22,88 @@ export function shouldReloadSdkSession(payload: unknown, activeCompPath: string
  * (projectId, activeCompPath) change, disposes the old one on cleanup, and
  * re-opens it when the active composition file changes on disk (code editor,
  * agent, or server-side patch) so the in-memory linkedom document never goes
- * stale.
- *
- * Opened WITHOUT a persist queue: this session is shadow-telemetry +
- * selection-sync only — it reads from the server but must NEVER write back.
- * Shadow dispatch ops mutate the in-memory model and are discarded on the next
- * reload-on-change (the studio's own authoritative write triggers it). Routing
- * authoritative writes through this session (cutover, Step 3c+) must re-add
- * persist TOGETHER WITH self-write suppression — without it, the SDK's
- * serialize() output races and clobbers the studio's authoritative write.
+ * stale. The session has NO persist queue — Studio is the sole file writer; see
+ * the open effect below.
+ */
+// Reload-suppression baseline: a file-change within this window of our own SDK
+// cutover write is a CANDIDATE echo, but the decision is content-identity based
+// (isSelfWriteEcho) not time-only — so an undo write that lands inside the window
+// still reloads (its reverted bytes were never registered as a self-write). The
+// window only bounds how long a registered self-write stays suppressible.
+const SELF_WRITE_SUPPRESS_MS = 2000;
+
+/** Best-effort read of the changed file's content from a file-change payload. */
+function readFileChangeContent(payload: unknown): string | null {
+  if (!payload || typeof payload !== "object") return null;
+  const record = payload as Record<string, unknown>;
+  if (typeof record.content === "string") return record.content;
+  if ("data" in record) return readFileChangeContent(record.data);
+  return null;
+}
+
+/**
+ * Decide whether a file-change for the active composition should reload the SDK
+ * session. `content` is the new on-disk bytes (from the payload or a re-read);
+ * pass null when unavailable. Content-identity wins: a change whose bytes match a
+ * registered self-write is our own echo (suppress). Without content we can't prove
+ * identity, so we fall back to the time window ONLY to suppress an echo — an undo
+ * write outside the window (or any non-self-write) still reloads. Exported for test.
  */
+export function shouldReloadOnFileChange(
+  activeCompPath: string,
+  content: string | null,
+  withinSuppressWindow: boolean,
+): boolean {
+  if (content != null) return !isSelfWriteEcho(activeCompPath, content);
+  // No content to compare — preserve the old time-window echo suppression.
+  return !withinSuppressWindow;
+}
+
+export interface SdkSessionHandle {
+  session: Composition | null;
+  /**
+   * Force a session reload immediately, bypassing the self-write suppress
+   * window. Call after undo/redo writes the active composition file so the
+   * SDK in-memory document reflects the reverted content.
+   */
+  forceReload: () => void;
+}
+
 export function useSdkSession(
   projectId: string | null,
   activeCompPath: string | null,
-): Composition | null {
+  domEditSaveTimestampRef?: MutableRefObject<number>,
+): SdkSessionHandle {
   const [session, setSession] = useState<Composition | null>(null);
   const [reloadToken, setReloadToken] = useState(0);
 
   // ── Re-open on external change to the active composition ──
   useEffect(() => {
     if (!activeCompPath) return;
-    // Pre-existing clone of the file-change reload handler (usePreviewPersistence);
-    // surfaced by this PR's adjacent edits, not introduced by it.
-    // fallow-ignore-next-line code-duplication
+    const compPath = activeCompPath;
+    const readAdapter =
+      projectId != null
+        ? createHttpAdapter({ projectFilesUrl: `/api/projects/${projectId}` })
+        : null;
     const handler = (payload?: unknown) => {
-      if (shouldReloadSdkSession(payload, activeCompPath)) {
-        setReloadToken((t) => t + 1);
+      if (!shouldReloadSdkSession(payload, compPath)) return;
+      const withinWindow =
+        !!domEditSaveTimestampRef &&
+        Date.now() - domEditSaveTimestampRef.current < SELF_WRITE_SUPPRESS_MS;
+      const decide = (content: string | null) => {
+        if (shouldReloadOnFileChange(compPath, content, withinWindow)) setReloadToken((t) => t + 1);
+      };
+      const payloadContent = readFileChangeContent(payload);
+      // Prefer payload content; otherwise re-read so the decision is by IDENTITY
+      // (an undo's reverted bytes won't match a registered self-write → reload).
+      if (payloadContent != null || !readAdapter) {
+        decide(payloadContent);
+        return;
       }
+      readAdapter
+        .read(compPath)
+        .then((c) => decide(typeof c === "string" ? c : null))
+        .catch(() => decide(null));
     };
     if (import.meta.hot) {
       import.meta.hot.on("hf:file-change", handler);
@@ -56,7 +113,8 @@ export function useSdkSession(
     const es = new EventSource("/api/events");
     es.addEventListener("file-change", handler);
     return () => es.close();
-  }, [activeCompPath]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [activeCompPath, projectId]);
 
   // ── Open / re-open the session ──
   useEffect(() => {
@@ -66,7 +124,7 @@ export function useSdkSession(
     }
 
     let cancelled = false;
-    let comp: Composition | null = null;
+    const compRef = { current: null as Composition | null };
 
     const adapter = createHttpAdapter({
       projectFilesUrl: `/api/projects/${projectId}`,
@@ -75,15 +133,21 @@ export function useSdkSession(
       .read(activeCompPath)
       .then(async (content) => {
         if (cancelled || typeof content !== "string") return;
-        // No persist — shadow/selection only; see the hook docstring. The SDK
-        // must not write back to the server while it shadows the authoritative
-        // studio path.
-        comp = await openComposition(content);
+        // No persist queue: Studio's writeProjectFile (via sdkCutover's
+        // persistSdkSerialize) is the SINGLE writer. Wiring the SDK persist
+        // queue too would double-write the file (queue auto-writes on every
+        // 'change' AND Studio writes explicitly) and race on disk; it would
+        // also write the full active-composition serialization to the fixed
+        // persistPath even when an edit targeted a sub-composition file.
+        // Studio's editHistory is the authoritative undo stack — SDK history
+        // is unused dead weight here (forceReloadSdkSession discards it on undo).
+        const comp = await openComposition(content, { history: false });
         // Cleanup may have fired while openComposition was awaited; dispose immediately.
         if (cancelled) {
           comp.dispose();
           return;
         }
+        compRef.current = comp;
         setSession(comp);
       })
       .catch(() => {
@@ -92,10 +156,12 @@ export function useSdkSession(
 
     return () => {
       cancelled = true;
-      const c = comp;
-      if (c) void c.flush().finally(() => c.dispose());
+      // No queue to flush; dispose only. (Flushing here would serialize the
+      // pre-undo in-memory doc and race the revert write on undo/redo reload.)
+      compRef.current?.dispose();
     };
   }, [projectId, activeCompPath, reloadToken]);
 
-  return session;
+  const forceReload = useCallback(() => setReloadToken((t) => t + 1), []);
+  return { session, forceReload };
 }

package/src/hooks/useStoryboard.ts

@@ -0,0 +1,80 @@
+import { useCallback, useEffect, useState } from "react";
+import type {
+  StoryboardFrame,
+  StoryboardGlobals,
+  StoryboardWarning,
+} from "@hyperframes/core/storyboard";
+import { buildProjectApiPath } from "../utils/projectRouting";
+
+/** A frame as returned by the API: parsed frame + disk-resolution info. */
+export interface StoryboardFrameView extends StoryboardFrame {
+  /** Whether `src` resolves to an existing file inside the project. */
+  srcExists: boolean;
+}
+
+/** The companion narration script (SCRIPT.md), when present alongside the storyboard. */
+export interface StoryboardScript {
+  exists: boolean;
+  path: string;
+  content: string;
+}
+
+/** Shape of `GET /api/projects/:id/storyboard`. */
+export interface StoryboardResponse {
+  exists: boolean;
+  path: string;
+  globals: StoryboardGlobals;
+  frames: StoryboardFrameView[];
+  warnings: StoryboardWarning[];
+  script?: StoryboardScript;
+}
+
+export interface UseStoryboardResult {
+  data: StoryboardResponse | null;
+  loading: boolean;
+  error: string | null;
+  reload: () => void;
+}
+
+/**
+ * Load the parsed storyboard manifest for a project. Markdown stays canonical on
+ * disk; this fetches the server-derived JSON the storyboard view renders.
+ */
+export function useStoryboard(projectId: string | null): UseStoryboardResult {
+  const [data, setData] = useState<StoryboardResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [reloadKey, setReloadKey] = useState(0);
+
+  const reload = useCallback(() => setReloadKey((k) => k + 1), []);
+
+  useEffect(() => {
+    if (!projectId) return;
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+
+    // Route through buildProjectApiPath so the (URL-derived) projectId is encoded
+    // into the path rather than interpolated raw (CodeQL js/client-side-request-forgery).
+    fetch(buildProjectApiPath(projectId, "/storyboard"))
+      .then((res) => {
+        if (!res.ok) throw new Error(`storyboard request failed: ${res.status}`);
+        return res.json() as Promise<StoryboardResponse>;
+      })
+      .then((json) => {
+        if (!cancelled) setData(json);
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) setError(err instanceof Error ? err.message : "failed to load storyboard");
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [projectId, reloadKey]);
+
+  return { data, loading, error, reload };
+}