@hyperframes/studio 0.7.58 → 0.7.60

package/src/hooks/useRazorSplit.ts

@@ -16,7 +16,8 @@ interface UseRazorSplitOptions {
   projectId: string | null;
   activeCompPath: string | null;
   showToast: (message: string, tone?: "error" | "info") => void;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
+  observeProjectFileVersion?: (path: string, version: string | null) => void;
   recordEdit: (input: RecordEditInput) => Promise<void>;
   domEditSaveTimestampRef: React.MutableRefObject<number>;
   reloadPreview: () => void;
@@ -48,7 +49,7 @@ async function splitHtmlElement(
   newId: string,
   elementStart: number,
   elementDuration: number,
-): Promise<{ ok: boolean; changed?: boolean; content?: string }> {
+): Promise<{ ok: boolean; changed?: boolean; content?: string; version: string }> {
   const response = await fetch(
     `/api/projects/${projectId}/file-mutations/split-element/${encodeURIComponent(targetPath)}`,
     {
@@ -64,9 +65,18 @@ async function splitHtmlElement(
     },
   );
   if (!response.ok) throw new Error("Split request failed");
-  return (await response.json()) as { ok: boolean; changed?: boolean; content?: string };
+  const data = (await response.json()) as {
+    ok: boolean;
+    changed?: boolean;
+    content?: string;
+    version?: string;
+  };
+  const version = data.version ?? response.headers.get("etag");
+  if (!version) throw new Error("Split response did not include a content version");
+  return { ...data, version };
 }
 
+// fallow-ignore-next-line complexity
 async function splitGsapAnimations(
   projectId: string,
   targetPath: string,
@@ -75,7 +85,7 @@ async function splitGsapAnimations(
   splitTime: number,
   elementStart: number,
   elementDuration: number,
-): Promise<{ content: string | null; skippedSelectors?: string[] }> {
+): Promise<{ content: string | null; version?: string; skippedSelectors?: string[] }> {
   const response = await fetch(
     `/api/projects/${projectId}/gsap-mutations/${encodeURIComponent(targetPath)}`,
     {
@@ -101,10 +111,12 @@ async function splitGsapAnimations(
   const data = (await response.json()) as {
     ok?: boolean;
     after?: string;
+    version?: string;
     skippedSelectors?: string[];
   };
   return {
     content: data.ok && data.after ? data.after : null,
+    version: data.version ?? response.headers.get("etag") ?? undefined,
     skippedSelectors: data.skippedSelectors,
   };
 }
@@ -119,11 +131,11 @@ function getOriginalContent(originals: ReadonlyMap<string, string>, path: string
 
 async function restoreFilesToOriginal(
   originals: ReadonlyMap<string, string>,
-  paths: Iterable<string>,
-  writeProjectFile: (path: string, content: string) => Promise<void>,
+  snapshots: ReadonlyMap<string, { before: string; after: string }>,
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
 ): Promise<void> {
-  for (const path of paths) {
-    await writeProjectFile(path, getOriginalContent(originals, path));
+  for (const [path, snapshot] of snapshots) {
+    await writeProjectFile(path, getOriginalContent(originals, path), snapshot.after);
   }
 }
 
@@ -149,17 +161,25 @@ async function splitElementsAtTime(
   activeCompPath: string | null,
   originals: ReadonlyMap<string, string>,
   snapshots: Map<string, { before: string; after: string }>,
-  writeProjectFile: (path: string, content: string) => Promise<void>,
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
+  observeProjectFileVersion?: (path: string, version: string | null) => void,
 ): Promise<number> {
   let count = 0;
   for (const element of elements) {
-    const result = await executeSplit(pid, element, splitTime, activeCompPath, writeProjectFile);
+    const result = await executeSplit(
+      pid,
+      element,
+      splitTime,
+      activeCompPath,
+      writeProjectFile,
+      observeProjectFileVersion,
+    );
     if (!result.changed) continue;
     snapshots.set(result.targetPath, {
       before: getOriginalContent(originals, result.targetPath),
       after: result.patchedContent,
     });
-    await writeProjectFile(result.targetPath, result.patchedContent);
+    await writeProjectFile(result.targetPath, result.patchedContent, result.patchedContent);
     count++;
   }
   return count;
@@ -171,7 +191,8 @@ async function executeSplit(
   element: TimelineElement,
   splitTime: number,
   activeCompPath: string | null,
-  writeProjectFile: (path: string, content: string) => Promise<void>,
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
+  observeProjectFileVersion?: (path: string, version: string | null) => void,
 ): Promise<{
   targetPath: string;
   originalContent: string;
@@ -209,6 +230,7 @@ async function executeSplit(
   if (!splitResult.changed) {
     return { targetPath, originalContent, patchedContent: originalContent, changed: false };
   }
+  observeProjectFileVersion?.(targetPath, splitResult.version);
 
   let patchedContent =
     typeof splitResult.content === "string" ? splitResult.content : originalContent;
@@ -226,11 +248,12 @@ async function executeSplit(
         element.duration,
       );
       if (gsapResult.content) patchedContent = gsapResult.content;
+      if (gsapResult.version) observeProjectFileVersion?.(targetPath, gsapResult.version);
       if (gsapResult.skippedSelectors?.length) skippedSelectors = gsapResult.skippedSelectors;
     } catch (gsapError) {
       // GSAP mutation failed — the HTML split already wrote to disk.
       // Restore the original content to avoid a corrupt half-split state.
-      await writeProjectFile(targetPath, originalContent);
+      await writeProjectFile(targetPath, originalContent, patchedContent);
       throw gsapError;
     }
   }
@@ -243,6 +266,7 @@ export function useRazorSplit({
   activeCompPath,
   showToast,
   writeProjectFile,
+  observeProjectFileVersion,
   recordEdit,
   domEditSaveTimestampRef,
   reloadPreview,
@@ -265,7 +289,14 @@ export function useRazorSplit({
 
       try {
         const { targetPath, originalContent, patchedContent, changed, skippedSelectors } =
-          await executeSplit(pid, element, splitTime, activeCompPath, writeProjectFile);
+          await executeSplit(
+            pid,
+            element,
+            splitTime,
+            activeCompPath,
+            writeProjectFile,
+            observeProjectFileVersion,
+          );
 
         if (!changed) {
           showToast("Failed to split clip — playhead may be outside the clip", "error");
@@ -305,6 +336,7 @@ export function useRazorSplit({
       recordEdit,
       showToast,
       writeProjectFile,
+      observeProjectFileVersion,
       domEditSaveTimestampRef,
       reloadPreview,
       forceReloadSdkSession,
@@ -312,8 +344,8 @@ export function useRazorSplit({
     ],
   );
 
-  // fallow-ignore-next-line complexity
   const handleRazorSplitAll = useCallback(
+    // fallow-ignore-next-line complexity
     async (splitTime: number) => {
       if (isRecordingRef?.current) {
         showToast("Cannot edit timeline while recording", "error");
@@ -338,6 +370,7 @@ export function useRazorSplit({
           originals,
           finalSnapshots,
           writeProjectFile,
+          observeProjectFileVersion,
         );
         if (splitCount === 0) return;
 
@@ -358,7 +391,7 @@ export function useRazorSplit({
         // Best-effort rollback — a failing restore write must not swallow the
         // original error's toast, which is what tells the user the split failed.
         try {
-          await restoreFilesToOriginal(originals, finalSnapshots.keys(), writeProjectFile);
+          await restoreFilesToOriginal(originals, finalSnapshots, writeProjectFile);
         } catch {
           /* leave disk as-is; the original failure is reported below */
         }
@@ -371,6 +404,7 @@ export function useRazorSplit({
       recordEdit,
       showToast,
       writeProjectFile,
+      observeProjectFileVersion,
       domEditSaveTimestampRef,
       reloadPreview,
       forceReloadSdkSession,

package/src/hooks/useSdkSession.lifecycle.test.tsx

@@ -0,0 +1,137 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const openComposition = vi.fn();
+
+vi.mock("@hyperframes/sdk", () => ({
+  openComposition: (...args: unknown[]) => openComposition(...args),
+}));
+
+import type { Composition } from "@hyperframes/sdk";
+import { useSdkSession, type SdkSessionHandle } from "./useSdkSession";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function fakeSession(): Composition {
+  return { dispose: vi.fn() } as unknown as Composition;
+}
+
+function response(content: string): Response {
+  return { ok: true, json: async () => ({ content }) } as Response;
+}
+
+async function flushAsyncEffects(): Promise<void> {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+describe("useSdkSession ownership", () => {
+  beforeEach(() => {
+    openComposition.mockReset();
+    class FakeEventSource {
+      addEventListener(): void {}
+      close(): void {}
+    }
+    vi.stubGlobal("EventSource", FakeEventSource);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("hides project A immediately while project B with the same path is still opening", async () => {
+    const sessionA = fakeSession();
+    const publishedA = fakeSession();
+    const sessionB = fakeSession();
+    let resolveProjectB: ((value: Response) => void) | undefined;
+    const projectBResponse = new Promise<Response>((resolve) => {
+      resolveProjectB = resolve;
+    });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn((url: string) =>
+        url.includes("project-b") ? projectBResponse : Promise.resolve(response("PROJECT_A")),
+      ),
+    );
+    openComposition.mockImplementation(async (content: string) =>
+      content === "PROJECT_A" ? sessionA : sessionB,
+    );
+
+    const captured: { handle: SdkSessionHandle | null } = { handle: null };
+    function Probe({ projectId }: { projectId: string }) {
+      captured.handle = useSdkSession(projectId, "index.html");
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<Probe projectId="project-a" />));
+    await flushAsyncEffects();
+    expect(captured.handle?.session).toBe(sessionA);
+
+    let publication: ReturnType<SdkSessionHandle["publish"]> | undefined;
+    await act(async () => {
+      publication = captured.handle?.publish({
+        candidate: publishedA,
+        expectedSession: sessionA,
+        targetPath: "index.html",
+      });
+    });
+    expect(publication).toBe("published");
+    expect(captured.handle?.session).toBe(publishedA);
+
+    await act(async () => root.render(<Probe projectId="project-b" />));
+    expect(captured.handle?.session).toBeNull();
+    expect(publishedA.dispose).toHaveBeenCalledOnce();
+    expect(
+      captured.handle?.publish({
+        candidate: fakeSession(),
+        expectedSession: publishedA,
+        targetPath: "index.html",
+      }),
+    ).toBe("rejected-inactive-target");
+
+    resolveProjectB?.(response("PROJECT_B"));
+    await flushAsyncEffects();
+    expect(captured.handle?.session).toBe(sessionB);
+
+    await act(async () => root.unmount());
+    expect(sessionB.dispose).toHaveBeenCalledOnce();
+  });
+
+  it("disposes the currently published candidate when its owner unmounts", async () => {
+    const opened = fakeSession();
+    const published = fakeSession();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => response("PROJECT_A")),
+    );
+    openComposition.mockResolvedValue(opened);
+
+    const captured: { handle: SdkSessionHandle | null } = { handle: null };
+    function Probe() {
+      captured.handle = useSdkSession("project-a", "index.html");
+      return null;
+    }
+
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<Probe />));
+    await flushAsyncEffects();
+    expect(captured.handle?.session).toBe(opened);
+    let publication: ReturnType<SdkSessionHandle["publish"]> | undefined;
+    await act(async () => {
+      publication = captured.handle?.publish({
+        candidate: published,
+        expectedSession: opened,
+        targetPath: "index.html",
+      });
+    });
+    expect(publication).toBe("published");
+    expect(opened.dispose).toHaveBeenCalledOnce();
+
+    await act(async () => root.unmount());
+    expect(published.dispose).toHaveBeenCalledOnce();
+  });
+});

package/src/hooks/useSdkSession.ts

@@ -1,9 +1,11 @@
-import { useState, useEffect, useCallback } from "react";
+import { useState, useEffect, useCallback, useRef } from "react";
 import type { MutableRefObject } from "react";
 import { openComposition } from "@hyperframes/sdk";
 import type { Composition } from "@hyperframes/sdk";
 import { readStudioFileChangePath } from "../components/editor/manualEdits";
 import { isSelfWriteEcho } from "./sdkSelfWriteRegistry";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import type { PublishSdkSession } from "../utils/sdkCutover";
 
 /**
  * Read a project file's content, or undefined on a non-2xx (optional read).
@@ -82,6 +84,8 @@ export function shouldReloadOnFileChange(
 
 export interface SdkSessionHandle {
   session: Composition | null;
+  /** Atomically publish a fully persisted candidate session. */
+  publish: PublishSdkSession;
   /**
    * Force a session reload immediately, bypassing the self-write suppress
    * window. Call after undo/redo writes the active composition file so the
@@ -90,13 +94,82 @@ export interface SdkSessionHandle {
   forceReload: () => void;
 }
 
+interface SdkSessionOwner {
+  projectId: string;
+  path: string;
+  reloadToken: number;
+  generation: number;
+}
+
+interface OwnedSdkSession extends SdkSessionOwner {
+  session: Composition;
+}
+
+function isSessionOwnerActive(
+  owner: SdkSessionOwner | undefined,
+  projectId: string | null,
+  path: string | null,
+  targetPath: string,
+): owner is SdkSessionOwner {
+  if (!owner) return false;
+  return owner.projectId === projectId && owner.path === path && owner.path === targetPath;
+}
+
+function isSessionOwnerCurrent(
+  owner: SdkSessionOwner,
+  generation: number,
+  projectId: string | null,
+  path: string | null,
+  reloadToken: number,
+): boolean {
+  return (
+    owner.generation === generation &&
+    owner.projectId === projectId &&
+    owner.path === path &&
+    owner.reloadToken === reloadToken
+  );
+}
+
+function ownsExpectedSession(
+  current: OwnedSdkSession | null,
+  expectedOwner: SdkSessionOwner,
+  expectedSession: Composition,
+  reloadToken: number,
+): current is OwnedSdkSession {
+  if (!current) return false;
+  return (
+    current.session === expectedSession &&
+    current.generation === expectedOwner.generation &&
+    current.reloadToken === reloadToken
+  );
+}
+
+function disposeSdkSession(session: Composition): void {
+  try {
+    session.dispose();
+  } catch (error) {
+    trackStudioEvent("sdk_session_dispose_failed", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
 export function useSdkSession(
   projectId: string | null,
   activeCompPath: string | null,
   domEditSaveTimestampRef?: MutableRefObject<number>,
 ): SdkSessionHandle {
-  const [session, setSession] = useState<Composition | null>(null);
+  const [ownedSession, setOwnedSession] = useState<OwnedSdkSession | null>(null);
+  const ownedSessionRef = useRef<OwnedSdkSession | null>(null);
+  const sessionOwnersRef = useRef(new WeakMap<Composition, SdkSessionOwner>());
+  const generationRef = useRef(0);
+  const projectIdRef = useRef(projectId);
+  projectIdRef.current = projectId;
+  const activeCompPathRef = useRef(activeCompPath);
+  activeCompPathRef.current = activeCompPath;
   const [reloadToken, setReloadToken] = useState(0);
+  const reloadTokenRef = useRef(reloadToken);
+  reloadTokenRef.current = reloadToken;
 
   // ── Re-open on external change to the active composition ──
   useEffect(() => {
@@ -135,13 +208,28 @@ export function useSdkSession(
 
   // ── Open / re-open the session ──
   useEffect(() => {
+    const generation = ++generationRef.current;
+    let cancelled = false;
+
+    // The preceding effect normally released its generation first. Clear any
+    // remaining owner defensively so an invalid project/path cannot retain it.
+    const previous = ownedSessionRef.current;
+    ownedSessionRef.current = null;
+    setOwnedSession(null);
+    if (previous) disposeSdkSession(previous.session);
+
     if (!projectId || !activeCompPath) {
-      setSession(null);
-      return;
+      return () => {
+        cancelled = true;
+      };
     }
 
-    let cancelled = false;
-    const compRef = { current: null as Composition | null };
+    const owner: SdkSessionOwner = {
+      projectId,
+      path: activeCompPath,
+      reloadToken,
+      generation,
+    };
 
     readProjectFileOptional(projectId, activeCompPath)
       .then(async (content) => {
@@ -157,24 +245,77 @@ export function useSdkSession(
         const comp = await openComposition(content, { history: false });
         // Cleanup may have fired while openComposition was awaited; dispose immediately.
         if (cancelled) {
-          comp.dispose();
+          disposeSdkSession(comp);
+          return;
+        }
+        if (
+          !isSessionOwnerCurrent(
+            owner,
+            generationRef.current,
+            projectIdRef.current,
+            activeCompPathRef.current,
+            reloadTokenRef.current,
+          )
+        ) {
+          disposeSdkSession(comp);
           return;
         }
-        compRef.current = comp;
-        setSession(comp);
+        const displaced = ownedSessionRef.current;
+        const installed = { ...owner, session: comp };
+        sessionOwnersRef.current.set(comp, owner);
+        ownedSessionRef.current = installed;
+        setOwnedSession(installed);
+        if (displaced && displaced.session !== comp) disposeSdkSession(displaced.session);
       })
       .catch(() => {
-        if (!cancelled) setSession(null);
+        if (!cancelled && generationRef.current === generation) setOwnedSession(null);
       });
 
     return () => {
       cancelled = true;
-      // 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();
+      // Publication preserves this generation, so cleanup releases whichever
+      // session it currently owns (the initially opened one or its candidate).
+      const owned = ownedSessionRef.current;
+      if (owned?.generation === generation) {
+        ownedSessionRef.current = null;
+        disposeSdkSession(owned.session);
+      }
     };
   }, [projectId, activeCompPath, reloadToken]);
 
   const forceReload = useCallback(() => setReloadToken((t) => t + 1), []);
-  return { session, forceReload };
+  const publish = useCallback<PublishSdkSession>(({ candidate, expectedSession, targetPath }) => {
+    const expectedOwner = sessionOwnersRef.current.get(expectedSession);
+    const current = ownedSessionRef.current;
+    if (
+      !isSessionOwnerActive(
+        expectedOwner,
+        projectIdRef.current,
+        activeCompPathRef.current,
+        targetPath,
+      )
+    ) {
+      return "rejected-inactive-target";
+    }
+    if (!ownsExpectedSession(current, expectedOwner, expectedSession, reloadTokenRef.current)) {
+      // The durable write won, but another session was installed for this same
+      // path before publication. Its self-write echo will be suppressed, so
+      // explicitly re-open it from disk instead of leaving it stale.
+      setReloadToken((t) => t + 1);
+      return "rejected-active-target";
+    }
+    const next: OwnedSdkSession = { ...current, session: candidate };
+    sessionOwnersRef.current.set(candidate, current);
+    ownedSessionRef.current = next;
+    setOwnedSession(next);
+    if (current.session !== candidate) disposeSdkSession(current.session);
+    return "published";
+  }, []);
+  const session =
+    ownedSession?.projectId === projectId &&
+    ownedSession.path === activeCompPath &&
+    ownedSession.reloadToken === reloadToken
+      ? ownedSession.session
+      : null;
+  return { session, publish, forceReload };
 }

package/src/hooks/useSlideshowPersist.ts

@@ -2,6 +2,7 @@ import { useCallback, type MutableRefObject } from "react";
 import type { Composition } from "@hyperframes/sdk";
 import type { SlideshowManifest } from "@hyperframes/core/slideshow";
 import type { EditHistoryKind } from "../utils/editHistory";
+import type { PublishSdkSession } from "../utils/sdkCutover";
 import { persistSlideshowManifest } from "../utils/setSlideshowManifest";
 
 export interface UseSlideshowPersistParams {
@@ -16,6 +17,8 @@ export interface UseSlideshowPersistParams {
   }) => Promise<void>;
   reloadPreview: () => void;
   domEditSaveTimestampRef: MutableRefObject<number>;
+  /** Publish a fully persisted candidate SDK session. */
+  publishSdkSession?: PublishSdkSession;
   /**
    * When provided, rapid writes with the same key coalesce through the
    * save-queue infra (via recordEdit's coalesceKey) so back-to-back persists
@@ -33,6 +36,7 @@ export function useSlideshowPersist({
   recordEdit,
   reloadPreview,
   domEditSaveTimestampRef,
+  publishSdkSession,
   coalesceKey,
 }: UseSlideshowPersistParams): (manifest: SlideshowManifest) => Promise<void> {
   return useCallback(
@@ -42,7 +46,6 @@ export function useSlideshowPersist({
       const originalContent = await readProjectFile(path);
       await persistSlideshowManifest({
         manifest,
-        sdkSession,
         originalContent,
         targetPath: path,
         deps: {
@@ -50,6 +53,8 @@ export function useSlideshowPersist({
           writeProjectFile,
           reloadPreview,
           domEditSaveTimestampRef,
+          readProjectFile,
+          publishSession: publishSdkSession,
         },
         coalesceKey,
       });
@@ -62,6 +67,7 @@ export function useSlideshowPersist({
       recordEdit,
       reloadPreview,
       domEditSaveTimestampRef,
+      publishSdkSession,
       coalesceKey,
     ],
   );

package/src/hooks/useStoryboard.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import type {
   StoryboardFrame,
   StoryboardGlobals,
@@ -27,6 +27,8 @@ export interface StoryboardResponse {
   frames: StoryboardFrameView[];
   warnings: StoryboardWarning[];
   script?: StoryboardScript;
+  /** Project content signature this payload was derived from (poster cache-bust + change poll). */
+  signature?: string;
 }
 
 export interface UseStoryboardResult {
@@ -39,19 +41,30 @@ export interface UseStoryboardResult {
 /**
  * Load the parsed storyboard manifest for a project. Markdown stays canonical on
  * disk; this fetches the server-derived JSON the storyboard view renders.
+ *
+ * `reload()` refetches in place: the blocking spinner only shows on first load
+ * and project switches, so background refreshes (file-change polling, post-save
+ * reloads) swap data without flashing the board.
  */
 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 hasDataRef = useRef(false);
+  const lastProjectRef = useRef<string | null>(null);
 
   const reload = useCallback(() => setReloadKey((k) => k + 1), []);
 
   useEffect(() => {
     if (!projectId) return;
     let cancelled = false;
-    setLoading(true);
+    if (lastProjectRef.current !== projectId) {
+      lastProjectRef.current = projectId;
+      hasDataRef.current = false;
+      setData(null);
+    }
+    if (!hasDataRef.current) setLoading(true);
     setError(null);
 
     // Route through buildProjectApiPath so the (URL-derived) projectId is encoded
@@ -62,10 +75,16 @@ export function useStoryboard(projectId: string | null): UseStoryboardResult {
         return res.json() as Promise<StoryboardResponse>;
       })
       .then((json) => {
-        if (!cancelled) setData(json);
+        if (cancelled) return;
+        hasDataRef.current = true;
+        setData(json);
       })
       .catch((err: unknown) => {
-        if (!cancelled) setError(err instanceof Error ? err.message : "failed to load storyboard");
+        if (cancelled) return;
+        // A failed background refresh keeps the last good board on screen;
+        // the blocking error state is only for loads with nothing to show.
+        if (hasDataRef.current) return;
+        setError(err instanceof Error ? err.message : "failed to load storyboard");
       })
       .finally(() => {
         if (!cancelled) setLoading(false);