@hyperframes/studio 0.8.55 → 0.8.57

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -12,10 +12,30 @@ import {
   readStudioPathOffset,
   readStudioRotation,
 } from "../components/editor/manualEdits";
-import { useDomGeometryCommits } from "./useDomGeometryCommits";
+import { useDomGeometryCommits, type UseDomGeometryCommitsParams } from "./useDomGeometryCommits";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
+function mountCommits(
+  commitPositionPatchToHtml: UseDomGeometryCommitsParams["commitPositionPatchToHtml"],
+  readOnlyPreview = false,
+) {
+  let commits: ReturnType<typeof useDomGeometryCommits> | null = null;
+  function Probe() {
+    commits = useDomGeometryCommits({
+      previewIframeRef: { current: null },
+      showToast: vi.fn(),
+      commitPositionPatchToHtml,
+      readOnlyPreview,
+    });
+    return null;
+  }
+  const host = document.createElement("div");
+  const root = createRoot(host);
+  act(() => root.render(<Probe />));
+  return { commits: () => commits!, unmount: () => act(() => root.unmount()) };
+}
+
 describe("useDomGeometryCommits rollback", () => {
   it("restores every optimistic geometry mutation when persistence rejects", async () => {
     const element = document.createElement("div");
@@ -30,7 +50,9 @@ describe("useDomGeometryCommits rollback", () => {
       element,
     } as unknown as DomEditSelection;
     const failure = new Error("save failed");
-    const commitPositionPatchToHtml = vi.fn().mockRejectedValue(failure);
+    const commitPositionPatchToHtml = vi
+      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
+      .mockRejectedValue(failure);
     let commits: ReturnType<typeof useDomGeometryCommits> | null = null;
     const host = document.createElement("div");
     const root = createRoot(host);
@@ -40,6 +62,7 @@ describe("useDomGeometryCommits rollback", () => {
         previewIframeRef: { current: null },
         showToast: vi.fn(),
         commitPositionPatchToHtml,
+        readOnlyPreview: false,
       });
       return null;
     }
@@ -60,3 +83,63 @@ describe("useDomGeometryCommits rollback", () => {
     act(() => root.unmount());
   });
 });
+
+describe("useDomGeometryCommits read-only preview", () => {
+  const selectionOn = (element: HTMLElement) =>
+    ({ id: element.id, selector: `#${element.id}`, element }) as unknown as DomEditSelection;
+
+  it("refuses a manual offset commit: no write, no history entry", async () => {
+    const element = document.createElement("div");
+    element.id = "ro-offset";
+    document.body.append(element);
+    applyStudioPathOffset(element, { x: 1, y: 2 });
+    const commitPositionPatchToHtml =
+      vi.fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>();
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml, true);
+    await commits().handleDomPathOffsetCommit(selectionOn(element), { x: 99, y: 99 });
+    expect(readStudioPathOffset(element)).toEqual({ x: 1, y: 2 });
+    expect(commitPositionPatchToHtml).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("refuses a manual box-size commit: no write, no history entry", async () => {
+    const element = document.createElement("div");
+    element.id = "ro-size";
+    document.body.append(element);
+    applyStudioBoxSize(element, { width: 10, height: 20 });
+    const commitPositionPatchToHtml =
+      vi.fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>();
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml, true);
+    await commits().handleDomBoxSizeCommit(selectionOn(element), { width: 999, height: 999 });
+    expect(readStudioBoxSize(element)).toEqual({ width: 10, height: 20 });
+    expect(commitPositionPatchToHtml).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("refuses a manual rotation commit: no write, no history entry", async () => {
+    const element = document.createElement("div");
+    element.id = "ro-rotate";
+    document.body.append(element);
+    applyStudioRotation(element, { angle: 5 });
+    const commitPositionPatchToHtml =
+      vi.fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>();
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml, true);
+    await commits().handleDomRotationCommit(selectionOn(element), { angle: 350 });
+    expect(readStudioRotation(element)).toEqual({ angle: 5 });
+    expect(commitPositionPatchToHtml).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("still commits an offset with the flag off", async () => {
+    const element = document.createElement("div");
+    element.id = "rw-offset";
+    document.body.append(element);
+    const commitPositionPatchToHtml = vi
+      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
+      .mockResolvedValue(undefined);
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml);
+    await commits().handleDomPathOffsetCommit(selectionOn(element), { x: 5, y: 6 });
+    expect(commitPositionPatchToHtml).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+});

package/src/hooks/useDomGeometryCommits.ts

@@ -28,9 +28,20 @@ import { isElementGsapTargeted } from "./gsapTargetCache";
 const GSAP_CSS_FALLBACK_BLOCKED_MESSAGE =
   "This element is GSAP-animated — dragging via CSS would corrupt keyframes";
 
+function rejectGsapCssFallback(
+  selection: DomEditSelection,
+  previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>,
+  showToast: (message: string, tone?: "error" | "info") => void,
+): Promise<never> | null {
+  if (!isElementGsapTargeted(previewIframeRef.current, selection.element)) return null;
+  const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
+  showToast(error.message, "error");
+  return Promise.reject(error);
+}
+
 // ── Hook ──
 
-interface UseDomGeometryCommitsParams {
+export interface UseDomGeometryCommitsParams {
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
   commitPositionPatchToHtml: (
@@ -38,25 +49,24 @@ interface UseDomGeometryCommitsParams {
     patches: PatchOperation[],
     options: { label: string; coalesceKey: string; skipRefresh?: boolean },
   ) => Promise<void>;
+  readOnlyPreview: boolean;
 }
 
 export function useDomGeometryCommits({
   previewIframeRef,
   showToast,
   commitPositionPatchToHtml,
+  readOnlyPreview,
 }: UseDomGeometryCommitsParams) {
   const handleDomPathOffsetCommit = useCallback(
     (selection: DomEditSelection, next: { x: number; y: number }) => {
+      if (readOnlyPreview) return Promise.resolve();
       // ponytail: GSAP-targeted elements are blocked (no SDK position-in-script op); CSS-path
       // elements fall through to commitPositionPatchToHtml → persistDomEditOperations →
       // onTrySdkPersist and are already SDK-cut-over as setStyle/setAttribute (§3.3 done).
       // Upgrade path for GSAP: add a moveElementGsap SDK op in a separate SDK PR.
-      const gsapTargeted = isElementGsapTargeted(previewIframeRef.current, selection.element);
-      if (gsapTargeted) {
-        const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
-        showToast(error.message, "error");
-        return Promise.reject(error);
-      }
+      const gsapFallback = rejectGsapCssFallback(selection, previewIframeRef, showToast);
+      if (gsapFallback) return gsapFallback;
       const before = captureStudioPathOffset(selection.element);
       applyStudioPathOffset(selection.element, next);
       return commitPositionPatchToHtml(selection, buildPathOffsetPatches(selection.element), {
@@ -67,7 +77,7 @@ export function useDomGeometryCommits({
         throw error;
       });
     },
-    [commitPositionPatchToHtml, previewIframeRef, showToast],
+    [commitPositionPatchToHtml, previewIframeRef, showToast, readOnlyPreview],
   );
 
   const handleDomBoxSizeCommit = useCallback(
@@ -76,11 +86,9 @@ export function useDomGeometryCommits({
       next: { width: number; height: number },
       offset?: { x: number; y: number },
     ) => {
-      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
-        const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
-        showToast(error.message, "error");
-        return Promise.reject(error);
-      }
+      if (readOnlyPreview) return Promise.resolve();
+      const gsapFallback = rejectGsapCssFallback(selection, previewIframeRef, showToast);
+      if (gsapFallback) return gsapFallback;
       const beforeSize = captureStudioBoxSize(selection.element);
       const beforeOffset = offset ? captureStudioPathOffset(selection.element) : null;
       applyStudioBoxSize(selection.element, next);
@@ -104,16 +112,14 @@ export function useDomGeometryCommits({
         throw error;
       });
     },
-    [commitPositionPatchToHtml, previewIframeRef, showToast],
+    [commitPositionPatchToHtml, previewIframeRef, showToast, readOnlyPreview],
   );
 
   const handleDomRotationCommit = useCallback(
     (selection: DomEditSelection, next: { angle: number }) => {
-      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
-        const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
-        showToast(error.message, "error");
-        return Promise.reject(error);
-      }
+      if (readOnlyPreview) return Promise.resolve();
+      const gsapFallback = rejectGsapCssFallback(selection, previewIframeRef, showToast);
+      if (gsapFallback) return gsapFallback;
       const before = captureStudioRotation(selection.element);
       applyStudioRotation(selection.element, next);
       return commitPositionPatchToHtml(selection, buildRotationPatches(selection.element), {
@@ -124,7 +130,7 @@ export function useDomGeometryCommits({
         throw error;
       });
     },
-    [commitPositionPatchToHtml, previewIframeRef, showToast],
+    [commitPositionPatchToHtml, previewIframeRef, showToast, readOnlyPreview],
   );
 
   const handleDomManualEditsReset = useCallback(

package/src/hooks/useFileTree.test.tsx

@@ -5,6 +5,12 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { useFileTree } from "./useFileTree";
 
+vi.mock("../components/feedback/projectProvenance", () => ({
+  captureProjectProvenance: vi.fn(),
+}));
+
+import { captureProjectProvenance } from "../components/feedback/projectProvenance";
+
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 let root: Root | null = null;
@@ -52,6 +58,56 @@ async function renderHarness(projectId: string): Promise<{ current: Handle | nul
   return handleRef;
 }
 
+describe("useFileTree unresolved project", () => {
+  const provenance = vi.mocked(captureProjectProvenance);
+
+  afterEach(() => {
+    provenance.mockClear();
+  });
+
+  /** Render the tree for `projectId` against one canned response. */
+  async function renderWithResponse(
+    projectId: string,
+    build: () => Response,
+  ): Promise<{ current: Handle | null }> {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockImplementation(async () => build());
+    const handleRef = await renderHarness(projectId);
+    fetchSpy.mockRestore();
+    return handleRef;
+  }
+
+  const notFound = () =>
+    new Response(JSON.stringify({ error: "not found" }), {
+      status: 404,
+      headers: { "content-type": "application/json" },
+    });
+  const emptyListing = () =>
+    new Response(JSON.stringify({ files: [], compositions: [] }), { status: 200 });
+
+  // An unresolvable project answers 404 with a JSON body. Without an `r.ok`
+  // check that parsed cleanly and took the SUCCESS branch, recording an empty
+  // tree and an empty provenance snapshot for a project that was never read —
+  // so a bug report filed from that tab described a project that does not
+  // exist. The tree itself stays empty either way; the provenance lie is the
+  // part that leaves the browser.
+  it("does not snapshot provenance for a project the server could not resolve", async () => {
+    const handleRef = await renderWithResponse("gone-project", notFound);
+
+    expect(handleRef.current?.compositions).toEqual([]);
+    expect(provenance).not.toHaveBeenCalled();
+  });
+
+  // The counterpart, and the reason the check above cannot be collapsed into
+  // "skip provenance whenever the tree is empty": a project with no
+  // compositions yet is a real, successful read and must still be snapshotted.
+  it("still snapshots provenance when a resolved project has no compositions", async () => {
+    const handleRef = await renderWithResponse("empty-project", emptyListing);
+
+    expect(handleRef.current?.compositions).toEqual([]);
+    expect(provenance).toHaveBeenCalledWith("empty-project", [], []);
+  });
+});
+
 describe("useFileTree.refreshFileTree", () => {
   it("updates compositions, not just the raw file list, on refresh", async () => {
     let call = 0;

package/src/hooks/useFileTree.ts

@@ -39,7 +39,14 @@ export function useFileTree({ projectId, projectIdRef }: UseFileTreeOptions) {
     let cancelled = false;
     setFetched({ projectId, loaded: false, fileTree: [], compositionPaths: [], projectDir: null });
     fetch(buildProjectApiPath(projectId))
-      .then((r) => r.json())
+      // An unresolvable project answers 404 with a JSON body, so without this
+      // the error path parsed cleanly and the success branch below recorded an
+      // empty tree — and an empty provenance snapshot — for a project that was
+      // never read. Throwing hands it to the catch instead.
+      .then((r) => {
+        if (!r.ok) throw new Error(`tree fetch failed: ${r.status}`);
+        return r.json();
+      })
       .then((data: { files?: string[]; dir?: string; compositions?: string[] }) => {
         if (cancelled) return;
         setFetched({

package/src/hooks/useGestureCommit.test.tsx

@@ -107,6 +107,7 @@ describe("useGestureCommit", () => {
         previewIframeRef: { current: iframe },
         showToast: vi.fn(),
         isGestureRecordingRef: { current: false },
+        readOnlyPreview: false,
       });
       return null;
     }
@@ -127,4 +128,32 @@ describe("useGestureCommit", () => {
     expect(options[1]).toEqual(expect.objectContaining({ coalesceMs: Infinity, softReload: true }));
     expect(options[1]).not.toHaveProperty("skipReload");
   });
+
+  it("does not start a recording while the preview is read-only", () => {
+    const element = document.createElement("div");
+    const commitMutation = vi.fn(async () => {});
+    const captured: { hook: ReturnType<typeof useGestureCommit> | null } = { hook: null };
+    function Probe() {
+      captured.hook = useGestureCommit({
+        domEditSessionRef: {
+          current: {
+            domEditSelection: makeSelection(element),
+            selectedGsapAnimations: [],
+            commitMutation,
+          },
+        },
+        previewIframeRef: { current: document.createElement("iframe") },
+        showToast: vi.fn(),
+        isGestureRecordingRef: { current: false },
+        readOnlyPreview: true,
+      });
+      return null;
+    }
+    const root = mountReactHarness(<Probe />);
+    cleanup = () => act(() => root.unmount());
+
+    act(() => captured.hook?.handleToggleRecording());
+    expect(gestureRecording.startRecording).not.toHaveBeenCalled();
+    expect(commitMutation).not.toHaveBeenCalled();
+  });
 });

package/src/hooks/useGestureCommit.ts

@@ -87,6 +87,7 @@ interface UseGestureCommitParams {
   previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
   isGestureRecordingRef: React.MutableRefObject<boolean>;
+  readOnlyPreview: boolean;
 }
 
 export interface UseGestureCommitResult {
@@ -101,6 +102,7 @@ export function useGestureCommit({
   previewIframeRef,
   showToast,
   isGestureRecordingRef,
+  readOnlyPreview,
 }: UseGestureCommitParams): UseGestureCommitResult {
   const gestureRecording = useGestureRecording();
   const [gestureState, setGestureState] = useState<"idle" | "recording">("idle");
@@ -115,6 +117,20 @@ export function useGestureCommit({
   // Unmount: clear auto-stop interval
   useEffect(() => () => clearInterval(recordingAutoStopRef.current), []);
 
+  const cancelRecording = useCallback(() => {
+    clearInterval(recordingAutoStopRef.current);
+    gestureRecording.stopRecording();
+    gestureRecording.clearSamples();
+    gestureStateRef.current = "idle";
+    isGestureRecordingRef.current = false;
+    capturedSelectionRef.current = null;
+    setGestureState("idle");
+  }, [gestureRecording, isGestureRecordingRef]);
+
+  useEffect(() => {
+    if (readOnlyPreview && gestureStateRef.current === "recording") cancelRecording();
+  }, [cancelRecording, readOnlyPreview]);
+
   // fallow-ignore-next-line complexity
   const stopAndCommitRecording = useCallback(async () => {
     clearInterval(recordingAutoStopRef.current);
@@ -335,9 +351,14 @@ export function useGestureCommit({
   // fallow-ignore-next-line complexity
   const handleToggleRecording = useCallback(() => {
     if (gestureStateRef.current === "recording") {
+      if (readOnlyPreview) {
+        cancelRecording();
+        return;
+      }
       void stopAndCommitRecording();
       return;
     }
+    if (readOnlyPreview) return;
     const sel = domEditSessionRef.current.domEditSelection;
     if (!sel) {
       showToast("Select an element first", "error");
@@ -373,9 +394,11 @@ export function useGestureCommit({
     gestureRecording,
     showToast,
     stopAndCommitRecording,
+    cancelRecording,
     previewIframeRef,
     domEditSessionRef,
     isGestureRecordingRef,
+    readOnlyPreview,
   ]);
 
   return { gestureState, gestureRecording, handleToggleRecording };

package/src/hooks/useInlineTextEdit.test.tsx

@@ -3,6 +3,7 @@
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { PreviewReadOnlyProvider } from "../components/editor/previewReadOnlyContext";
 import { useInlineTextEdit, type InlineTextEditControls } from "./useInlineTextEdit";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -20,7 +21,7 @@ function heading(text = "Motion Playground"): HTMLElement {
   return element;
 }
 
-function mount(onCommit = vi.fn(), onPause = vi.fn()) {
+function mount(onCommit = vi.fn(), onPause = vi.fn(), readOnly = false) {
   const controls: { current: InlineTextEditControls | null } = { current: null };
   function Probe() {
     controls.current = useInlineTextEdit({ onCommit, onPause });
@@ -29,7 +30,13 @@ function mount(onCommit = vi.fn(), onPause = vi.fn()) {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
-  act(() => root.render(<Probe />));
+  act(() =>
+    root.render(
+      <PreviewReadOnlyProvider readOnly={readOnly}>
+        <Probe />
+      </PreviewReadOnlyProvider>,
+    ),
+  );
   return { controls: () => controls.current!, root, onCommit, onPause };
 }
 
@@ -552,4 +559,18 @@ describe("useInlineTextEdit with styled runs", () => {
     expect(insertText).toHaveBeenCalledWith("insertText", false, "plain words");
     act(() => root.unmount());
   });
+
+  it("refuses to open an edit while the preview is read-only", () => {
+    const element = heading();
+    const { controls, root, onCommit, onPause } = mount(vi.fn(), vi.fn(), true);
+    let opened = true;
+    act(() => {
+      opened = controls().start(element);
+    });
+    expect(opened).toBe(false);
+    expect(element.hasAttribute("contenteditable")).toBe(false);
+    expect(onPause).not.toHaveBeenCalled();
+    expect(onCommit).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
 });

package/src/hooks/useInlineTextEdit.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { sanitizeRichTextChildren } from "@hyperframes/core/rich-text-sanitize";
+import { usePreviewReadOnly } from "../components/editor/previewReadOnlyContext";
 
 /**
  * Editing an element's text where it sits, in the composition itself.
@@ -89,6 +90,7 @@ export function useInlineTextEdit({
   /** Stop playback, so the element is not animating under the caret. */
   onPause?: () => void;
 }): InlineTextEditControls {
+  const readOnly = usePreviewReadOnly();
   const [session, setSession] = useState<InlineTextEditSession | null>(null);
   // The teardown reads this rather than the state, so an exit path that runs
   // before React re-renders still sees the element it has to clean up.
@@ -123,7 +125,7 @@ export function useInlineTextEdit({
 
   const start = useCallback(
     (element: HTMLElement, caretAt?: { x: number; y: number }): boolean => {
-      if (openRef.current) return false;
+      if (openRef.current || readOnly) return false;
 
       const open = {
         element,
@@ -156,7 +158,7 @@ export function useInlineTextEdit({
       framesRef.current = raf ?? null;
       return true;
     },
-    [onPause],
+    [onPause, readOnly],
   );
 
   const commit = useCallback(() => {
@@ -179,6 +181,13 @@ export function useInlineTextEdit({
     teardown();
   }, [teardown]);
 
+  // Read-only can be enabled while an edit is already open. Close that
+  // session as a cancellation so the preview cannot keep committing through
+  // the now-disabled editing surface.
+  useEffect(() => {
+    if (readOnly && openRef.current) cancel();
+  }, [cancel, readOnly]);
+
   // The keys belong to the element, not to the document: the element lives in
   // the preview's own document, so a listener on Studio's would never see them.
   useEffect(() => {

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

@@ -147,6 +147,86 @@ describe("useSdkSession ownership", () => {
   });
 });
 
+describe("useSdkSession unreachable project", () => {
+  beforeEach(() => {
+    openComposition.mockReset();
+    trackMock.mockClear();
+    class FakeEventSource {
+      addEventListener(): void {}
+      close(): void {}
+    }
+    vi.stubGlobal("EventSource", FakeEventSource);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function probeHandle(projectId: string) {
+    const captured: { handle: SdkSessionHandle | null } = { handle: null };
+    function HandleProbe() {
+      captured.handle = useSdkSession(projectId, "index.html");
+      return null;
+    }
+    return { captured, HandleProbe };
+  }
+
+  const failedRead = (status: number) => async () =>
+    ({ ok: false, status, json: async () => ({}) }) as Response;
+
+  /** Render the hook for `projectId` against a stubbed read and let it settle. */
+  async function readOutcome(
+    projectId: string,
+    read: () => Promise<Response>,
+  ): Promise<{ captured: { handle: SdkSessionHandle | null }; unmount: () => Promise<void> }> {
+    vi.stubGlobal("fetch", vi.fn(read));
+    const { captured, HandleProbe } = probeHandle(projectId);
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<HandleProbe />));
+    await flushAsyncEffects();
+    return { captured, unmount: () => act(async () => root.unmount()) };
+  }
+
+  // A 404 on the composition read is the one failure that says something about
+  // the PROJECT rather than the request: under the CLI host it means this
+  // Studio serves a different one. Every edit then fails silently, so the UI
+  // needs the id to explain that.
+  it("names the project when the read is a 404", async () => {
+    const { captured, unmount } = await readOutcome("gone-project", failedRead(404));
+
+    expect(captured.handle?.unreachableProject).toBe("gone-project");
+    await unmount();
+  });
+
+  // A 500 says the request failed, not that the project is elsewhere. Claiming
+  // otherwise would tell a user their tab is pointed at the wrong project when
+  // the server is merely unwell.
+  it("stays quiet on a failure that says nothing about the project", async () => {
+    const { captured, unmount } = await readOutcome("project-a", failedRead(500));
+
+    expect(captured.handle?.unreachableProject).toBeNull();
+    await unmount();
+  });
+
+  it("clears the state once the project resolves", async () => {
+    const { captured, unmount } = await readOutcome("gone-project", failedRead(404));
+    expect(captured.handle?.unreachableProject).toBe("gone-project");
+
+    openComposition.mockResolvedValue(fakeSession());
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => response("PROJECT_A")),
+    );
+    await act(async () => {
+      captured.handle?.forceReload();
+    });
+    await flushAsyncEffects();
+
+    expect(captured.handle?.unreachableProject).toBeNull();
+    await unmount();
+  });
+});
+
 describe("useSdkSession unavailable telemetry", () => {
   beforeEach(() => {
     openComposition.mockReset();