@hyperframes/studio 0.8.70 → 0.8.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.70",
+  "version": "0.8.72",
   "description": "",
   "repository": {
     "type": "git",
@@ -24,6 +24,7 @@
       "types": "./dist/styles/tailwind-preset.d.ts"
     },
     "./theme.css": "./src/styles/theme.css",
+    "./components.css": "./src/styles/components.css",
     "./styles.css": "./dist/styles.css",
     "./package.json": "./package.json"
   },
@@ -51,11 +52,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.70",
-    "@hyperframes/parsers": "0.8.70",
-    "@hyperframes/player": "0.8.70",
-    "@hyperframes/sdk": "0.8.70",
-    "@hyperframes/studio-server": "0.8.70"
+    "@hyperframes/core": "0.8.72",
+    "@hyperframes/parsers": "0.8.72",
+    "@hyperframes/player": "0.8.72",
+    "@hyperframes/studio-server": "0.8.72",
+    "@hyperframes/sdk": "0.8.72"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -71,7 +72,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.70"
+    "@hyperframes/producer": "0.8.72"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -8,6 +8,7 @@ import { StudioOverlays } from "./components/StudioOverlays";
 import { SaveQueuePausedBanner } from "./components/SaveQueuePausedBanner";
 import { ExternalFileConflictBanner } from "./components/ExternalFileConflictBanner";
 import { ProjectUnreachableBanner } from "./components/ProjectUnreachableBanner";
+import { CompositionMissingBanner } from "./components/CompositionMissingBanner";
 import { useCaptionStore } from "./captions/store";
 import { useCaptionSync } from "./captions/hooks/useCaptionSync";
 import { usePersistentEditHistory } from "./hooks/usePersistentEditHistory";
@@ -132,6 +133,7 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
     masterCompPath,
     fileManager.fileTree,
     fileManager.fileTreeLoaded,
+    fileManager.refreshFileTree,
   );
   const activeCompPathRef = useRef(activeCompPath);
   activeCompPathRef.current = activeCompPath;
@@ -481,6 +483,9 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
                 {sdkHandle.unreachableProject && (
                   <ProjectUnreachableBanner projectId={sdkHandle.unreachableProject} />
                 )}
+                {sdkHandle.compositionMissing && activeCompPath && (
+                  <CompositionMissingBanner path={activeCompPath} />
+                )}
                 <EditorShell
                   readOnlyPreview={readOnlyPreview}
                   readOnlyPreviewReason={readOnlyPreviewReason}

package/src/components/CompositionMissingBanner.test.tsx

@@ -0,0 +1,35 @@
+// fallow-ignore-file code-duplication
+// The mount/unmount harness matches ProjectUnreachableBanner.test.tsx's — the
+// same small React-root scaffold every banner test in this directory uses.
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { CompositionMissingBanner } from "./CompositionMissingBanner";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | null = null;
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  root = null;
+  document.body.replaceChildren();
+});
+
+describe("CompositionMissingBanner", () => {
+  it("names the missing composition and does not claim the whole project is gone", async () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    root = createRoot(host);
+    await act(async () => {
+      root?.render(<CompositionMissingBanner path="scenes/intro.html" />);
+    });
+
+    expect(host.textContent).toContain("scenes/intro.html");
+    expect(host.textContent).toContain("no longer on disk");
+    // Distinct from ProjectUnreachableBanner's wording — this is one file
+    // inside a project that resolves fine, not the whole project.
+    expect(host.textContent).not.toContain("This Studio is serving");
+  });
+});

package/src/components/CompositionMissingBanner.tsx

@@ -0,0 +1,32 @@
+interface CompositionMissingBannerProps {
+  /** The composition this tab has open, that the server can no longer find. */
+  path: string;
+}
+
+/**
+ * Shown when the currently open composition's file has vanished from disk
+ * mid-session — the `absent` read reason (#4325): the file tree listed it and
+ * the read cannot get it.
+ *
+ * Distinct from `ProjectUnreachableBanner`: there the whole PROJECT fails to
+ * resolve; here the project is fine and this one file inside it is not. Proven
+ * 2026-09-23 to be a stale tree, not a placeholder or a path-encoding gap:
+ * `refreshFileTree` only ran after Studio's own file operations, so an agent
+ * removing or replacing a composition updated the preview and the SDK session
+ * but never the listing — the file stayed clickable, and every edit through
+ * it failed silently, with nothing to tell the user why. The tree is now
+ * refreshed as soon as this fires (`useSdkSession`'s `onAbsentRead`); this
+ * banner is the only thing that explains the failure while that catches up.
+ */
+export function CompositionMissingBanner({ path }: CompositionMissingBannerProps) {
+  return (
+    <div
+      role="alert"
+      className="hf-backdrop-in absolute left-1/2 top-14 z-92 flex max-w-[calc(100vw-32px)] -translate-x-1/2 items-center gap-3 rounded-md border border-amber-500/30 bg-amber-950/85 px-4 py-2 text-[12px] font-medium text-amber-100 shadow-lg shadow-black/30"
+    >
+      <span>
+        <strong>{path}</strong> is no longer on disk. Select another composition to keep editing.
+      </span>
+    </div>
+  );
+}

package/src/components/nle/NLEPreview.test.ts

@@ -80,6 +80,10 @@ function renderPreview(
   previewSlots: Array<{ gen: number; role: "live" | "shadow"; url?: string }> = [
     { gen: 0, role: "live" },
   ],
+  {
+    box = { width: 800, height: 600 },
+    fillBox,
+  }: { box?: { width: number; height: number }; fillBox?: boolean } = {},
 ) {
   resizeCallbacks = [];
   const host = document.createElement("div");
@@ -99,6 +103,7 @@ function renderPreview(
         onShadowError: () => {},
         setShadowIframeNode: () => {},
         resetPreviewSlots: () => {},
+        fillBox,
       }),
     );
   });
@@ -108,7 +113,7 @@ function renderPreview(
   expect(viewport).toBeTruthy();
   expect(stage).toBeTruthy();
 
-  setRect(viewport, { width: 800, height: 600 });
+  setRect(viewport, box);
   act(() => {
     for (const fire of resizeCallbacks) fire();
   });
@@ -251,6 +256,19 @@ describe("NLEPreview", () => {
     view.cleanup();
   });
 
+  it("insets the picture by default and fills a same-shape box when fillBox is on", () => {
+    const box = { width: 640, height: 360 };
+    const inset = renderPreview(undefined, { box });
+    expect([inset.stage.style.width, inset.stage.style.height]).toEqual(["611.5556px", "344px"]);
+    expect(parseFloat(inset.stage.parentElement!.style.inset)).toBe(8);
+    inset.cleanup();
+
+    const filled = renderPreview(undefined, { box, fillBox: true });
+    expect([filled.stage.style.width, filled.stage.style.height]).toEqual(["640px", "360px"]);
+    expect(parseFloat(filled.stage.parentElement!.style.inset)).toBe(0);
+    filled.cleanup();
+  });
+
   it("clips a shadow reload so its own loading overlay cannot paint over the live frame", () => {
     const view = renderPreview([
       { gen: 0, role: "live" },

package/src/components/nle/NLEPreview.tsx

@@ -36,6 +36,8 @@ interface NLEPreviewProps {
   onStageRef?: (ref: React.RefObject<HTMLDivElement | null>) => void;
   /** Reports the authored composition size measured from the loaded preview. */
   onCompositionSizeChange?: (size: PreviewCompositionSize | null) => void;
+  /** Draws the picture edge to edge in this box, without Studio's inset band. */
+  fillBox?: boolean;
 }
 
 export function getPreviewPlayerKey({
@@ -50,7 +52,7 @@ export function getPreviewPlayerKey({
 
 const ZOOM_HUD_TIMEOUT_MS = 1200;
 const ZOOM_SETTLE_MS = 200;
-const PREVIEW_STAGE_INSET_PX = 16;
+const PREVIEW_STAGE_INSET_PX = 8;
 
 // clip-path as well as visibility: the player's loading overlay sets its own
 // visibility:visible and would otherwise paint over the live frame.
@@ -87,9 +89,10 @@ export function resolvePreviewStageSize(
   compositionSize: PreviewCompositionSize | null,
   portrait: boolean | undefined,
   gutterPx = 0,
+  insetPx = PREVIEW_STAGE_INSET_PX,
 ): { width: number; height: number } {
-  const availableWidth = Math.max(0, viewportWidth - PREVIEW_STAGE_INSET_PX - 2 * gutterPx);
-  const availableHeight = Math.max(0, viewportHeight - PREVIEW_STAGE_INSET_PX - 2 * gutterPx);
+  const availableWidth = Math.max(0, viewportWidth - 2 * (insetPx + gutterPx));
+  const availableHeight = Math.max(0, viewportHeight - 2 * (insetPx + gutterPx));
   const aspectRatio =
     compositionSize && compositionSize.width > 0 && compositionSize.height > 0
       ? compositionSize.width / compositionSize.height
@@ -130,6 +133,7 @@ export const NLEPreview = memo(function NLEPreview({
   suppressLoadingOverlay,
   onStageRef,
   onCompositionSizeChange,
+  fillBox,
 }: NLEPreviewProps) {
   const activeKey = getPreviewPlayerKey({ projectId, directUrl });
   const viewportRef = useRef<HTMLDivElement>(null);
@@ -151,6 +155,7 @@ export const NLEPreview = memo(function NLEPreview({
   const reportPreviewFirstFrame = usePreviewFirstFrameTelemetry(previewSlots);
   const [compositionSize, setCompositionSize] = useState<PreviewCompositionSize | null>(null);
   const gutterPx = usePreviewGuidesStore((s) => (s.rulerVisible ? RULER_GUTTER_PX : 0));
+  const insetPx = fillBox ? 0 : PREVIEW_STAGE_INSET_PX;
   const [stageSize, setStageSize] = useState(() => resolvePreviewStageSize(0, 0, null, portrait));
 
   const zoomRef = useRef<PreviewZoomState>(loadInitialZoom());
@@ -181,7 +186,14 @@ export const NLEPreview = memo(function NLEPreview({
     const updateStageSize = () => {
       const rect = viewport.getBoundingClientRect();
       setStageSize(
-        resolvePreviewStageSize(rect.width, rect.height, compositionSize, portrait, gutterPx),
+        resolvePreviewStageSize(
+          rect.width,
+          rect.height,
+          compositionSize,
+          portrait,
+          gutterPx,
+          insetPx,
+        ),
       );
     };
 
@@ -189,7 +201,7 @@ export const NLEPreview = memo(function NLEPreview({
     const observer = new ResizeObserver(updateStageSize);
     observer.observe(viewport);
     return () => observer.disconnect();
-  }, [compositionSize, portrait, gutterPx]);
+  }, [compositionSize, portrait, gutterPx, insetPx]);
 
   const onCompositionSizeChangeRef = useRef(onCompositionSizeChange);
   onCompositionSizeChangeRef.current = onCompositionSizeChange;
@@ -467,11 +479,14 @@ export const NLEPreview = memo(function NLEPreview({
     <div className="flex flex-col h-full min-h-0">
       <div
         ref={viewportRef}
-        className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-hidden focus:ring-1 focus:ring-studio-accent/40 bg-[var(--studio-preview-bg,var(--color-neutral-950))]"
+        className="relative flex-1 flex items-center justify-center overflow-hidden min-h-0 outline-hidden focus:ring-1 focus:ring-studio-accent/40 bg-[var(--studio-preview-bg,var(--color-neutral-950))]"
         tabIndex={0}
         aria-label="Composition preview"
       >
-        <div className="absolute inset-2 flex items-center justify-center pointer-events-none">
+        <div
+          className="absolute flex items-center justify-center pointer-events-none"
+          style={{ inset: insetPx }}
+        >
           <div
             ref={stageRef}
             className="relative shrink-0 pointer-events-auto"

package/src/hooks/useExternalFileChangeCoordinator.test.tsx

@@ -74,9 +74,44 @@ describe("external file change coordinator", () => {
       onAcceptedPersistedFileChange: () => order.push("thumbnail"),
       reloadPreview: () => order.push("preview"),
       reloadSdkSession: () => order.push("sdk"),
+      refreshFileTree: () => {
+        order.push("tree");
+      },
     });
     await act(async () => handler?.({ path: "index.html", content: "external", version: "v2" }));
-    expect(order).toEqual(["drain", "thumbnail", "preview", "sdk"]);
+    expect(order).toEqual(["drain", "thumbnail", "preview", "sdk", "tree"]);
+    expect(captured.handle?.blocked).toBeNull();
+  });
+
+  // The file tree (useFileTree) is only ever refreshed from Studio's own file
+  // operations (create/delete/rename/upload) — never on an external change.
+  // Without this call, an agent removing or replacing a composition updates
+  // the preview and the SDK session but leaves the listing stale forever.
+  it("refreshes the file tree on an accepted external change", async () => {
+    const refreshFileTree = vi.fn();
+    await mountCoordinator({ refreshFileTree });
+    await act(async () => handler?.({ path: "index.html", content: "external", version: "v2" }));
+    expect(refreshFileTree).toHaveBeenCalledOnce();
+  });
+
+  it("does not refresh the tree for a suppressed self-write echo", async () => {
+    const refreshFileTree = vi.fn();
+    await mountCoordinator({ refreshFileTree });
+    markStudioWriteToken("studio-write-1");
+    await act(async () =>
+      handler?.({
+        path: "index.html",
+        content: "studio",
+        version: "v2",
+        writeToken: "studio-write-1",
+      }),
+    );
+    expect(refreshFileTree).not.toHaveBeenCalled();
+  });
+
+  it("is optional — an accepted change with no refreshFileTree collaborator does not throw", async () => {
+    const { captured } = await mountCoordinator({ refreshFileTree: undefined });
+    await act(async () => handler?.({ path: "index.html", content: "external", version: "v2" }));
     expect(captured.handle?.blocked).toBeNull();
   });
 

package/src/hooks/useExternalFileChangeCoordinator.ts

@@ -64,6 +64,17 @@ interface ExternalFileChangeCoordinatorOptions {
     path: string,
     affectedCompositions: readonly string[] | null,
   ) => void;
+  /**
+   * Called alongside `reloadPreview`/`reloadSdkSession` on every accepted
+   * external change. The file tree (`useFileTree`) is only ever refreshed
+   * from Studio's OWN file operations (create/delete/rename/upload) — an
+   * external change (an agent writing outside Studio) reloads the preview
+   * and the SDK session but, without this, never the listing. A composition
+   * an agent removed or replaced then stays in the tree until the user does
+   * a Studio-side file op or reloads the tab; clicking it opens a session
+   * that can never resolve (`reason: "absent"`, proven stale-tree 2026-09-23).
+   */
+  refreshFileTree?: () => void | Promise<void>;
 }
 
 export interface ExternalFileChangeCoordinatorHandle {
@@ -149,6 +160,7 @@ export function useExternalFileChangeCoordinator({
   onUseExternalFile,
   resetSaveQueues,
   onAcceptedPersistedFileChange,
+  refreshFileTree,
 }: ExternalFileChangeCoordinatorOptions): ExternalFileChangeCoordinatorHandle {
   const [blocked, setBlocked] = useState<ExternalFileChangeBlockedState | null>(null);
   const generationRef = useRef(0);
@@ -223,8 +235,14 @@ export function useExternalFileChangeCoordinator({
       logReload("reload", { path, by: "external-change coordinator" });
       reloadPreview();
       reloadSdkSession(path);
+      // Fire-and-forget: a failed refresh leaves the tree as stale as it was,
+      // which is the status quo this exists to improve on, not a new failure
+      // mode to surface. The `absent`-triggered fallback in useSdkSession
+      // covers the case where this call is missed entirely (server restart,
+      // a watcher event the SSE never delivered).
+      void refreshFileTree?.();
     },
-    [reloadPreview, reloadSdkSession],
+    [reloadPreview, reloadSdkSession, refreshFileTree],
   );
 
   const persistSnapshotInOrder = useCallback(async (write: () => Promise<void>) => {

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

@@ -587,6 +587,152 @@ describe("useSdkSession unavailable telemetry", () => {
     await act(async () => rootB.unmount());
   });
 
+  // `compositionMissing` and the once-per-path refresh fallback: proven
+  // 2026-09-23 that `absent` means a stale tree (refreshFileTree only runs
+  // after Studio's own file ops, never on an external change), so an `absent`
+  // read is the one signal that should make the tree self-correct even when
+  // the SSE-driven refresh in useExternalFileChangeCoordinator is missed.
+  describe("compositionMissing and the absent-read refresh fallback", () => {
+    function HandleProbe({
+      projectId,
+      path,
+      onAbsentRead,
+    }: {
+      projectId: string;
+      path: string;
+      onAbsentRead?: (path: string) => void;
+    }) {
+      captured.handle = useSdkSession(projectId, path, [], false, onAbsentRead);
+      return null;
+    }
+    const captured: { handle: SdkSessionHandle | null } = { handle: null };
+
+    it("sets compositionMissing and calls onAbsentRead once for an absent read", async () => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn(
+          async () =>
+            ({ ok: true, json: async () => ({ content: "", missing: true }) }) as Response,
+        ),
+      );
+      const onAbsentRead = vi.fn();
+      const root = createRoot(document.createElement("div"));
+      await act(async () =>
+        root.render(
+          <HandleProbe projectId="project-a" path="index.html" onAbsentRead={onAbsentRead} />,
+        ),
+      );
+      await flushAsyncEffects();
+
+      expect(captured.handle?.compositionMissing).toBe(true);
+      expect(onAbsentRead).toHaveBeenCalledOnce();
+      expect(onAbsentRead).toHaveBeenCalledWith("index.html");
+
+      // A second absent read for the SAME path must not refresh again — the
+      // refresh already ran and didn't fix it (the file really is gone).
+      await act(async () => {
+        captured.handle?.forceReload();
+      });
+      await flushAsyncEffects();
+      expect(onAbsentRead).toHaveBeenCalledOnce();
+
+      await act(async () => root.unmount());
+    });
+
+    it("calls onAbsentRead again for a different path", async () => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn(
+          async () =>
+            ({ ok: true, json: async () => ({ content: "", missing: true }) }) as Response,
+        ),
+      );
+      const onAbsentRead = vi.fn();
+      const root = createRoot(document.createElement("div"));
+      await act(async () =>
+        root.render(
+          <HandleProbe projectId="project-a" path="scenes/a.html" onAbsentRead={onAbsentRead} />,
+        ),
+      );
+      await flushAsyncEffects();
+      await act(async () =>
+        root.render(
+          <HandleProbe projectId="project-a" path="scenes/b.html" onAbsentRead={onAbsentRead} />,
+        ),
+      );
+      await flushAsyncEffects();
+
+      expect(onAbsentRead).toHaveBeenCalledTimes(2);
+      expect(onAbsentRead).toHaveBeenNthCalledWith(1, "scenes/a.html");
+      expect(onAbsentRead).toHaveBeenNthCalledWith(2, "scenes/b.html");
+      await act(async () => root.unmount());
+    });
+
+    it("resets the guard on project change, so the same path can refresh again", async () => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn(
+          async () =>
+            ({ ok: true, json: async () => ({ content: "", missing: true }) }) as Response,
+        ),
+      );
+      const onAbsentRead = vi.fn();
+      const root = createRoot(document.createElement("div"));
+      await act(async () =>
+        root.render(
+          <HandleProbe projectId="project-a" path="index.html" onAbsentRead={onAbsentRead} />,
+        ),
+      );
+      await flushAsyncEffects();
+      await act(async () =>
+        root.render(
+          <HandleProbe projectId="project-b" path="index.html" onAbsentRead={onAbsentRead} />,
+        ),
+      );
+      await flushAsyncEffects();
+
+      expect(onAbsentRead).toHaveBeenCalledTimes(2);
+      await act(async () => root.unmount());
+    });
+
+    it("clears compositionMissing once a later read succeeds", async () => {
+      const fetchMock = vi.fn(
+        async () => ({ ok: true, json: async () => ({ content: "", missing: true }) }) as Response,
+      );
+      vi.stubGlobal("fetch", fetchMock);
+      openComposition.mockResolvedValue(fakeSession());
+      const root = createRoot(document.createElement("div"));
+      await act(async () => root.render(<HandleProbe projectId="project-a" path="index.html" />));
+      await flushAsyncEffects();
+      expect(captured.handle?.compositionMissing).toBe(true);
+
+      fetchMock.mockImplementation(async () => response("PROJECT_A"));
+      await act(async () => {
+        captured.handle?.forceReload();
+      });
+      await flushAsyncEffects();
+
+      expect(captured.handle?.compositionMissing).toBe(false);
+      await act(async () => root.unmount());
+    });
+
+    it("does not throw when onAbsentRead is not supplied", async () => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn(
+          async () =>
+            ({ ok: true, json: async () => ({ content: "", missing: true }) }) as Response,
+        ),
+      );
+      const root = createRoot(document.createElement("div"));
+      await act(async () => root.render(<HandleProbe projectId="project-a" path="index.html" />));
+      await flushAsyncEffects();
+
+      expect(captured.handle?.compositionMissing).toBe(true);
+      await act(async () => root.unmount());
+    });
+  });
+
   it("reports a parse failure with its message", async () => {
     vi.stubGlobal(
       "fetch",

package/src/hooks/useSdkSession.ts

@@ -273,6 +273,16 @@ export interface SdkSessionHandle {
    * `missing_content` say nothing about the project at all.
    */
   unreachableProject: string | null;
+  /**
+   * True when the most recent read of `activeCompPath` reported `reason:
+   * "absent"` — the file tree lists this path and the server cannot get it.
+   * Proven 2026-09-23 to mean a stale tree: `refreshFileTree` only runs after
+   * Studio's own file operations, so an external change (an agent removing
+   * or replacing the file) updates the preview and this session but never
+   * the listing, and the file stays clickable forever. Every edit then fails
+   * silently with nothing to tell the user why — this is that signal.
+   */
+  compositionMissing: boolean;
 }
 
 interface SdkSessionOwner {
@@ -345,6 +355,12 @@ export function useSdkSession(
   // reports `null`, same as before the tree loads.
   fileTree: readonly string[] = [],
   fileTreeLoaded = false,
+  // Fallback for the SSE-driven refresh in useExternalFileChangeCoordinator:
+  // called at most once per (projectId, path) so the tree self-corrects even
+  // when that delivery is missed (server restart, a watcher event the SSE
+  // never sent). Optional for the same reason fileTree is: a secondary
+  // session has no tree of its own to refresh.
+  onAbsentRead?: (path: string) => void,
 ): SdkSessionHandle {
   const [ownedSession, setOwnedSession] = useState<OwnedSdkSession | null>(null);
   const ownedSessionRef = useRef<OwnedSdkSession | null>(null);
@@ -358,6 +374,35 @@ export function useSdkSession(
   const reloadTokenRef = useRef(reloadToken);
   reloadTokenRef.current = reloadToken;
   const [unreachableProject, setUnreachableProject] = useState<string | null>(null);
+  const [compositionMissing, setCompositionMissing] = useState(false);
+  // Keyed `${projectId}:${path}` so a refresh that doesn't fix it (the file
+  // really is gone) can't loop, and so it fires again for a genuinely
+  // different path or project.
+  const refreshedAbsentPathsRef = useRef<Set<string>>(new Set());
+  useEffect(() => {
+    refreshedAbsentPathsRef.current.clear();
+  }, [projectId]);
+
+  /**
+   * Update `unreachableProject`/`compositionMissing` for one failed read, and
+   * fire the once-per-path tree-refresh fallback on `absent`. Pulled out of
+   * the open effect's `.then` — the branching there was pushing that
+   * callback over the complexity threshold on its own.
+   */
+  function handleReadFailure(
+    read: ProjectFileReadFailure,
+    forProjectId: string,
+    forPath: string,
+  ): void {
+    const pathInTree = fileTreeLoaded ? fileTree.includes(forPath) : null;
+    setUnreachableProject(reportReadFailure(read, forProjectId, pathInTree));
+    setCompositionMissing(read.reason === "absent");
+    if (read.reason !== "absent") return;
+    const key = `${forProjectId}:${forPath}`;
+    if (refreshedAbsentPathsRef.current.has(key)) return;
+    refreshedAbsentPathsRef.current.add(key);
+    onAbsentRead?.(forPath);
+  }
 
   useEffect(
     () =>
@@ -381,6 +426,7 @@ export function useSdkSession(
 
     if (!projectId || !activeCompPath) {
       setUnreachableProject(null);
+      setCompositionMissing(false);
       return () => {
         cancelled = true;
       };
@@ -397,11 +443,11 @@ export function useSdkSession(
       .then(async (read) => {
         if (cancelled) return;
         if (!read.ok) {
-          const pathInTree = fileTreeLoaded ? fileTree.includes(activeCompPath) : null;
-          setUnreachableProject(reportReadFailure(read, projectId, pathInTree));
+          handleReadFailure(read, projectId, activeCompPath);
           return;
         }
         setUnreachableProject(null);
+        setCompositionMissing(false);
         const content = read.content;
         // No persist queue: Studio's writeProjectFile (via sdkCutover's
         // persistSdkSerialize) is the SINGLE writer. Wiring the SDK persist
@@ -469,11 +515,13 @@ export function useSdkSession(
         disposeSdkSession(owned.session);
       }
     };
-    // fileTree/fileTreeLoaded deliberately excluded: they only annotate a
-    // read-failure event fired from this same effect run (the diagnostic
-    // "was the path in the last-loaded tree" snapshot), and re-running the
-    // whole open/dispose cycle on every tree refresh would drop and reopen a
-    // perfectly good session far more often than the tree actually changes.
+    // fileTree/fileTreeLoaded/onAbsentRead deliberately excluded: they only
+    // annotate or react to a read-failure event fired from this same effect
+    // run (the diagnostic "was the path in the last-loaded tree" snapshot,
+    // and the tree-refresh fallback), and re-running the whole open/dispose
+    // cycle on every tree refresh or on every render (callers are not
+    // required to memoize onAbsentRead) would drop and reopen a perfectly
+    // good session far more often than the tree actually changes.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [projectId, activeCompPath, reloadToken]);
 
@@ -511,5 +559,5 @@ export function useSdkSession(
     ownedSession.reloadToken === reloadToken
       ? ownedSession.session
       : null;
-  return { session, publish, forceReload, unreachableProject };
+  return { session, publish, forceReload, unreachableProject, compositionMissing };
 }

package/src/hooks/useStudioExternalFileChanges.ts

@@ -20,6 +20,7 @@ type FileManager = Pick<
   | "overwriteExternalConflict"
   | "readProjectFile"
   | "updateEditingFileContent"
+  | "refreshFileTree"
 >;
 
 type PreviewPersistence = Pick<
@@ -85,5 +86,6 @@ export function useStudioExternalFileChanges({
     onUseExternalFile: fileManager.updateEditingFileContent,
     resetSaveQueues: resetDomEditSaveQueueBreaker,
     onAcceptedPersistedFileChange,
+    refreshFileTree: fileManager.refreshFileTree,
   });
 }

package/src/hooks/useStudioSdkSessions.ts

@@ -20,6 +20,7 @@ export function useStudioSdkSessions(
   masterCompPath: string | null,
   fileTree: readonly string[] = [],
   fileTreeLoaded = false,
+  refreshFileTree?: () => void | Promise<void>,
 ) {
   // On the master view (no explicit comp) the schema panels target the project's
   // resolved main composition — the first `.html` in the tree, not a hardcoded
@@ -30,6 +31,7 @@ export function useStudioSdkSessions(
     activeCompPath ?? masterCompPath,
     fileTree,
     fileTreeLoaded,
+    refreshFileTree,
   );
   const editFlowSdkSession = activeCompPath ? sdkHandle.session : null;
   useEffect(() => {

package/src/player/components/VolumeControl.styles.test.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 
-const studioCss = readFileSync(new URL("../../styles/studio.css", import.meta.url), "utf8");
+const studioCss = readFileSync(new URL("../../styles/components.css", import.meta.url), "utf8");
 
 describe("preview volume range styles", () => {
   it("uses the same compact thumb in Chromium and Firefox", () => {