@hyperframes/studio 0.7.58 → 0.7.59

package/src/hooks/useProjectSignaturePoll.test.tsx

@@ -0,0 +1,135 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useProjectSignaturePoll } from "./useProjectSignaturePoll";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+function HookHost({
+  signature,
+  onChange,
+}: {
+  signature: string | undefined;
+  onChange: () => void;
+}) {
+  useProjectSignaturePoll("demo", signature, onChange);
+  return null;
+}
+
+let root: Root | null = null;
+let container: HTMLElement | null = null;
+
+function mount(signature: string | undefined, onChange: () => void): void {
+  act(() => {
+    if (!root) {
+      container = document.createElement("div");
+      document.body.appendChild(container);
+      root = createRoot(container);
+    }
+    root.render(<HookHost signature={signature} onChange={onChange} />);
+  });
+}
+
+function unmount(): void {
+  if (root) {
+    act(() => root?.unmount());
+    root = null;
+  }
+  container?.remove();
+  container = null;
+}
+
+function mockSignatureResponse(signature: string): ReturnType<typeof vi.fn> {
+  const fetchMock = vi.fn(async () => ({ ok: true, json: async () => ({ signature }) }));
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+describe("useProjectSignaturePoll", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    unmount();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("fires onChange when the polled signature moves past the loaded one", async () => {
+    const fetchMock = mockSignatureResponse("sig-b");
+    const onChange = vi.fn();
+    mount("sig-a", onChange);
+
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(fetchMock).toHaveBeenCalledWith("/api/projects/demo/signature");
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("stays quiet while the polled signature matches", async () => {
+    mockSignatureResponse("sig-a");
+    const onChange = vi.fn();
+    mount("sig-a", onChange);
+
+    await vi.advanceTimersByTimeAsync(6000);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("does not poll before a baseline signature exists", async () => {
+    const fetchMock = mockSignatureResponse("sig-a");
+    const onChange = vi.fn();
+    mount(undefined, onChange);
+
+    await vi.advanceTimersByTimeAsync(6000);
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("re-arms against the caller's refreshed signature without re-mounting", async () => {
+    mockSignatureResponse("sig-b");
+    const onChange = vi.fn();
+    mount("sig-a", onChange);
+
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(onChange).toHaveBeenCalledTimes(1);
+
+    // The caller refetched and now holds the polled signature — no more firing.
+    mount("sig-b", onChange);
+    await vi.advanceTimersByTimeAsync(6000);
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips ticks while the tab is hidden and re-checks on visibility", async () => {
+    const fetchMock = mockSignatureResponse("sig-b");
+    const onChange = vi.fn();
+    let hidden = true;
+    vi.spyOn(document, "hidden", "get").mockImplementation(() => hidden);
+    mount("sig-a", onChange);
+
+    await vi.advanceTimersByTimeAsync(6000);
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    hidden = false;
+    await act(async () => {
+      document.dispatchEvent(new Event("visibilitychange"));
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("stops polling after unmount", async () => {
+    mockSignatureResponse("sig-b");
+    const onChange = vi.fn();
+    mount("sig-a", onChange);
+
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(onChange).toHaveBeenCalledTimes(1);
+
+    unmount();
+    await vi.advanceTimersByTimeAsync(10_000);
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useProjectSignaturePoll.ts

@@ -0,0 +1,68 @@
+import { useEffect, useRef } from "react";
+import { buildProjectApiPath } from "../utils/projectRouting";
+
+const POLL_INTERVAL_MS = 2000;
+
+/** One poll: the current signature, or null on any failure (skip this tick). */
+async function fetchProjectSignature(projectId: string): Promise<string | null> {
+  try {
+    const res = await fetch(buildProjectApiPath(projectId, "/signature"));
+    if (!res.ok) return null;
+    const body = (await res.json()) as { signature?: string };
+    return typeof body.signature === "string" ? body.signature : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Poll the project's content signature and fire `onChange` when it no longer
+ * matches `currentSignature` — the storyboard board uses this to refresh itself
+ * while an agent writes sketch frames to disk.
+ *
+ * The comparison baseline is the signature the caller's data was loaded with,
+ * so a refetch triggered by `onChange` naturally re-arms the poll with the new
+ * value. Ticks are skipped while the tab is hidden (a visibility flip re-checks
+ * immediately) and while a previous request is still in flight; request
+ * failures are ignored — polling degrades to today's manual-reload behavior.
+ */
+export function useProjectSignaturePoll(
+  projectId: string | null,
+  currentSignature: string | undefined,
+  onChange: () => void,
+): void {
+  const signatureRef = useRef(currentSignature);
+  const onChangeRef = useRef(onChange);
+  signatureRef.current = currentSignature;
+  onChangeRef.current = onChange;
+
+  useEffect(() => {
+    if (!projectId) return;
+    let disposed = false;
+    let inFlight = false;
+
+    const tick = async () => {
+      if (disposed || inFlight || document.hidden) return;
+      // No baseline yet (initial storyboard fetch still loading, or an older
+      // server without the signature field) — nothing to compare against.
+      if (signatureRef.current === undefined) return;
+      inFlight = true;
+      const latest = await fetchProjectSignature(projectId);
+      inFlight = false;
+      if (disposed || latest === null) return;
+      if (latest !== signatureRef.current) onChangeRef.current();
+    };
+
+    const interval = window.setInterval(() => void tick(), POLL_INTERVAL_MS);
+    const onVisibilityChange = () => {
+      if (!document.hidden) void tick();
+    };
+    document.addEventListener("visibilitychange", onVisibilityChange);
+
+    return () => {
+      disposed = true;
+      window.clearInterval(interval);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, [projectId]);
+}

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