@hyperframes/studio 0.6.110 → 0.6.111

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 };
+}

package/src/hooks/useTimelineEditing.ts

@@ -1,11 +1,7 @@
 // Pre-existing-complex timeline hook (DOM patch + GSAP position shift/scale +
-// playback-start resolution); this PR adds guarded shadow-timing dispatches in
-// the move/resize .then() chains, which nudges several callbacks over the CC
-// threshold. The added branches are telemetry-only.
+// playback-start resolution).
 // fallow-ignore-file complexity
 import { useCallback, useRef } from "react";
-import type { Composition } from "@hyperframes/sdk";
-import { runShadowDelete, runShadowTiming } from "../utils/sdkShadow";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
 import { useRazorSplit } from "./useRazorSplit";
@@ -37,6 +33,8 @@ import {
   scaleGsapPositions,
 } from "./timelineEditingHelpers";
 import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
+import { sdkTimingPersist } from "../utils/sdkCutover";
+import type { Composition } from "@hyperframes/sdk";
 
 // ── Types ──
 
@@ -60,8 +58,10 @@ interface UseTimelineEditingOptions {
   pendingTimelineEditPathRef: React.MutableRefObject<Set<string>>;
   uploadProjectFiles: (files: Iterable<File>, dir?: string) => Promise<string[]>;
   isRecordingRef?: React.RefObject<boolean>;
-  /** Stage 7 Step 3b: SDK session for shadow timing dispatch (server stays authoritative). */
+  /** Stage 7 §3.2: SDK session for routing timing ops through setTiming. */
   sdkSession?: Composition | null;
+  /** Resync the SDK session after a server-authoritative timeline write. */
+  forceReloadSdkSession?: () => void;
 }
 
 // ── Hook ──
@@ -80,6 +80,7 @@ export function useTimelineEditing({
   uploadProjectFiles,
   isRecordingRef,
   sdkSession,
+  forceReloadSdkSession,
 }: UseTimelineEditingOptions) {
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
@@ -92,6 +93,7 @@ export function useTimelineEditing({
       element: TimelineElement,
       label: string,
       buildPatches: PersistTimelineEditInput["buildPatches"],
+      coalesceKey?: string,
     ): Promise<void> => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");
@@ -99,19 +101,25 @@ export function useTimelineEditing({
       }
       const pid = projectIdRef.current;
       if (!pid) return Promise.resolve();
-      const queued = editQueueRef.current.then(() =>
-        persistTimelineEdit({
-          projectId: pid,
-          element,
-          activeCompPath,
-          label,
-          buildPatches,
-          writeProjectFile,
-          recordEdit,
-          domEditSaveTimestampRef,
-          pendingTimelineEditPathRef,
-        }),
-      );
+      const queued = editQueueRef.current
+        .then(() =>
+          persistTimelineEdit({
+            projectId: pid,
+            element,
+            activeCompPath,
+            label,
+            buildPatches,
+            writeProjectFile,
+            recordEdit,
+            domEditSaveTimestampRef,
+            pendingTimelineEditPathRef,
+            coalesceKey,
+          }),
+        )
+        .then(() => {
+          // Server wrote the file; resync the stale in-memory SDK doc.
+          forceReloadSdkSession?.();
+        });
       editQueueRef.current = queued.catch((error) => {
         console.error(`[Timeline] Failed to persist: ${label}`, error);
       });
@@ -125,18 +133,20 @@ export function useTimelineEditing({
       pendingTimelineEditPathRef,
       showToast,
       isRecordingRef,
+      forceReloadSdkSession,
     ],
   );
 
+  // fallow-ignore-next-line complexity
   const handleTimelineElementMove = useCallback(
+    // fallow-ignore-next-line complexity
     (element: TimelineElement, updates: Pick<TimelineElement, "start" | "track">) => {
       patchIframeDomTiming(previewIframeRef.current, element, [
         ["data-start", formatTimelineAttributeNumber(updates.start)],
         ["data-track-index", String(updates.track)],
       ]);
-      const delta = updates.start - element.start;
-      const filePath = element.sourceFile || activeCompPath || "index.html";
-      return enqueueEdit(element, "Move timeline clip", (original, target) => {
+      const targetPath = element.sourceFile || activeCompPath || "index.html";
+      const buildMovePatches: PersistTimelineEditInput["buildPatches"] = (original, target) => {
         let patched = applyPatchByTarget(original, target, {
           type: "attribute",
           property: "start",
@@ -147,24 +157,63 @@ export function useTimelineEditing({
           property: "track-index",
           value: String(updates.track),
         });
-      }).then(() => {
-        if (sdkSession)
-          runShadowTiming(sdkSession, element.hfId, {
-            start: updates.start,
-            trackIndex: updates.track,
-          });
-        const pid = projectIdRef.current;
-        if (delta !== 0 && element.domId && pid) {
-          return shiftGsapPositions(pid, filePath, element.domId, delta)
-            .then(() => reloadPreview())
-            .catch((err) => console.error("[Timeline] Failed to shift GSAP positions", err));
-        }
-      });
+      };
+      // Server-path fallback (no SDK session): persist the attr patch, then
+      // shift GSAP tween positions on the server and reload the preview — the
+      // SDK path folds both into setTiming, but the fallback must do them
+      // explicitly or the clip moves while its GSAP tweens stay put + the
+      // preview never refreshes. coalesceKey mirrors the SDK branch so undo
+      // granularity is identical on either path.
+      const coalesceKey = `timeline-move:${element.hfId ?? element.id}`;
+      const moveFallback = () =>
+        enqueueEdit(element, "Move timeline clip", buildMovePatches, coalesceKey).then(() => {
+          const pid = projectIdRef.current;
+          const delta = updates.start - element.start;
+          if (delta !== 0 && element.domId && pid) {
+            return shiftGsapPositions(pid, targetPath, element.domId, delta)
+              .then(() => reloadPreview())
+              .catch((err) => console.error("[Timeline] Failed to shift GSAP positions", err));
+          }
+          return reloadPreview();
+        });
+      if (sdkSession && element.hfId) {
+        return sdkTimingPersist(
+          element.hfId,
+          targetPath,
+          { start: updates.start, trackIndex: updates.track },
+          sdkSession,
+          {
+            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.
+            readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
+          },
+          { label: "Move timeline clip", coalesceKey },
+        ).then((handled) => {
+          if (!handled) return moveFallback();
+        });
+      }
+      return moveFallback();
     },
-    [previewIframeRef, enqueueEdit, activeCompPath, reloadPreview, sdkSession],
+    [
+      previewIframeRef,
+      enqueueEdit,
+      activeCompPath,
+      sdkSession,
+      recordEdit,
+      writeProjectFile,
+      reloadPreview,
+      domEditSaveTimestampRef,
+    ],
   );
 
+  // fallow-ignore-next-line complexity
   const handleTimelineElementResize = useCallback(
+    // fallow-ignore-next-line complexity
     (
       element: TimelineElement,
       updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
@@ -173,6 +222,9 @@ export function useTimelineEditing({
         ["data-start", formatTimelineAttributeNumber(updates.start)],
         ["data-duration", formatTimelineAttributeNumber(updates.duration)],
       ];
+      // Patch the live playback-start/media-start attr too, or a resize that
+      // trims the playback start leaves the preview showing the old in-point
+      // until the next reload (the persisted patch handles it via pbs below).
       if (updates.playbackStart != null) {
         const liveAttr =
           element.playbackStartAttr === "playback-start"
@@ -181,10 +233,8 @@ export function useTimelineEditing({
         liveAttrs.push([liveAttr, formatTimelineAttributeNumber(updates.playbackStart)]);
       }
       patchIframeDomTiming(previewIframeRef.current, element, liveAttrs);
-      const filePath = element.sourceFile || activeCompPath || "index.html";
-      const timingChanged =
-        updates.start !== element.start || updates.duration !== element.duration;
-      return enqueueEdit(element, "Resize timeline clip", (original, target) => {
+      const targetPath = element.sourceFile || activeCompPath || "index.html";
+      const buildResizePatches: PersistTimelineEditInput["buildPatches"] = (original, target) => {
         const pbs = resolveResizePlaybackStart(original, target, element, updates);
         let patched = applyPatchByTarget(original, target, {
           type: "attribute",
@@ -204,34 +254,77 @@ export function useTimelineEditing({
           });
         }
         return patched;
-      }).then(() => {
-        if (sdkSession)
-          runShadowTiming(sdkSession, element.hfId, {
-            start: updates.start,
-            duration: updates.duration,
-          });
-        const pid = projectIdRef.current;
-        if (timingChanged && element.domId && pid) {
-          return scaleGsapPositions(
-            pid,
-            filePath,
-            element.domId,
-            element.start,
-            element.duration,
-            updates.start,
-            updates.duration,
-          )
-            .then(() => reloadPreview())
-            .catch((err) => console.error("[Timeline] Failed to scale GSAP positions", err));
-        }
-        return reloadPreview();
-      });
+      };
+      // SDK path: skip when a playback-start adjustment is needed (setTiming has no pbs field).
+      // The second clause fires because trimming the start of a clip that has a
+      // playback-start attribute implicitly shifts that in-point — which the SDK
+      // setTiming op can't express — so those resizes must take the server path.
+      const hasPbsAdjustment =
+        updates.playbackStart != null ||
+        (updates.start !== element.start && element.playbackStart != null);
+      // Server-path fallback: after persisting the attr patch, scale GSAP tween
+      // positions/durations on the server and reload the preview. The SDK path
+      // folds both into setTiming; the fallback must do them explicitly or the
+      // clip resizes while its GSAP tweens keep their old timing + the preview
+      // never refreshes. coalesceKey mirrors the SDK branch for undo parity.
+      const coalesceKey = `timeline-resize:${element.hfId ?? element.id}`;
+      const timingChanged =
+        updates.start !== element.start || updates.duration !== element.duration;
+      const resizeFallback = () =>
+        enqueueEdit(element, "Resize timeline clip", buildResizePatches, coalesceKey).then(() => {
+          const pid = projectIdRef.current;
+          if (timingChanged && element.domId && pid) {
+            return scaleGsapPositions(
+              pid,
+              targetPath,
+              element.domId,
+              element.start,
+              element.duration,
+              updates.start,
+              updates.duration,
+            )
+              .then(() => reloadPreview())
+              .catch((err) => console.error("[Timeline] Failed to scale GSAP positions", err));
+          }
+          return reloadPreview();
+        });
+      if (sdkSession && element.hfId && !hasPbsAdjustment) {
+        return sdkTimingPersist(
+          element.hfId,
+          targetPath,
+          { start: updates.start, duration: updates.duration },
+          sdkSession,
+          {
+            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.
+            readProjectFile: (path) => readFileContent(projectIdRef.current ?? "", path),
+          },
+          { label: "Resize timeline clip", coalesceKey },
+        ).then((handled) => {
+          if (!handled) return resizeFallback();
+        });
+      }
+      return resizeFallback();
     },
-    [previewIframeRef, enqueueEdit, activeCompPath, reloadPreview, sdkSession],
+    [
+      previewIframeRef,
+      enqueueEdit,
+      activeCompPath,
+      sdkSession,
+      recordEdit,
+      writeProjectFile,
+      reloadPreview,
+      domEditSaveTimestampRef,
+    ],
   );
 
+  // fallow-ignore-next-line complexity
   const handleTimelineElementDelete = useCallback(
-    // Pre-existing handler complexity, unchanged by this PR.
     // fallow-ignore-next-line complexity
     async (element: TimelineElement) => {
       if (isRecordingRef?.current) {
@@ -287,8 +380,8 @@ export function useTimelineEditing({
             timelineElements.filter((te) => (te.key ?? te.id) !== (element.key ?? element.id)),
           );
         usePlayerStore.getState().setSelectedElementId(null);
+        forceReloadSdkSession?.();
         reloadPreview();
-        if (sdkSession) runShadowDelete(sdkSession, element.hfId);
         showToast(`Deleted ${label}. Use Undo to restore it.`, "info");
       } catch (error) {
         const message = error instanceof Error ? error.message : "Failed to delete timeline clip";
@@ -304,12 +397,12 @@ export function useTimelineEditing({
       domEditSaveTimestampRef,
       reloadPreview,
       isRecordingRef,
-      sdkSession,
+      forceReloadSdkSession,
     ],
   );
 
+  // fallow-ignore-next-line complexity
   const handleTimelineAssetDrop = useCallback(
-    // Pre-existing handler complexity, unchanged by this PR.
     // fallow-ignore-next-line complexity
     async (
       assetPath: string,
@@ -373,6 +466,7 @@ export function useTimelineEditing({
           recordEdit,
         });
 
+        forceReloadSdkSession?.();
         reloadPreview();
       } catch (error) {
         const message =
@@ -389,11 +483,12 @@ export function useTimelineEditing({
       domEditSaveTimestampRef,
       reloadPreview,
       isRecordingRef,
+      forceReloadSdkSession,
     ],
   );
 
+  // fallow-ignore-next-line complexity
   const handleTimelineFileDrop = useCallback(
-    // Pre-existing handler complexity, unchanged by this PR.
     // fallow-ignore-next-line complexity
     async (files: File[], placement?: Pick<TimelineElement, "start" | "track">) => {
       if (isRecordingRef?.current) {

package/src/utils/gsapSoftReload.ts

@@ -31,6 +31,19 @@ function findGsapScriptElements(doc: Document): HTMLScriptElement[] {
   return results;
 }
 
+/**
+ * Extract the GSAP timeline script text from a serialized HTML document, for
+ * feeding into applySoftReload. Returns null when zero or multiple GSAP scripts
+ * are present (ambiguous — caller should fall back to a full reload), matching
+ * applySoftReload's own single-script requirement.
+ */
+export function extractGsapScriptText(html: string): string | null {
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  const scripts = findGsapScriptElements(doc);
+  if (scripts.length !== 1) return null;
+  return scripts[0].textContent || null;
+}
+
 /** Check that the new script repopulated __timelines with at least one entry. */
 function verifyTimelinesPopulated(win: IframeWindow): boolean {
   const tlKeys = win.__timelines
@@ -73,6 +86,7 @@ export function applySoftReload(iframe: HTMLIFrameElement | null, scriptText: st
   // full iframe reload that destroys the very WebGL context we're preserving.
   let deferredToAsync = false;
 
+  // fallow-ignore-next-line complexity
   const doReload = () => {
     const timelines = win.__timelines;
     const allTargets: Element[] = [];