@hyperframes/studio 0.8.60 → 0.8.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.60",
+  "version": "0.8.62",
   "description": "",
   "repository": {
     "type": "git",
@@ -51,11 +51,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.60",
-    "@hyperframes/player": "0.8.60",
-    "@hyperframes/sdk": "0.8.60",
-    "@hyperframes/parsers": "0.8.60",
-    "@hyperframes/studio-server": "0.8.60"
+    "@hyperframes/core": "0.8.62",
+    "@hyperframes/parsers": "0.8.62",
+    "@hyperframes/sdk": "0.8.62",
+    "@hyperframes/player": "0.8.62",
+    "@hyperframes/studio-server": "0.8.62"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -71,7 +71,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.60"
+    "@hyperframes/producer": "0.8.62"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -130,6 +130,8 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
     projectId,
     activeCompPath,
     masterCompPath,
+    fileManager.fileTree,
+    fileManager.fileTreeLoaded,
   );
   const activeCompPathRef = useRef(activeCompPath);
   activeCompPathRef.current = activeCompPath;

package/src/hooks/useExternalFileChangeCoordinator.test.tsx

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 // @vitest-environment happy-dom
 import { act } from "react";
 import { createRoot } from "react-dom/client";
@@ -376,4 +377,59 @@ describe("external file change coordinator", () => {
       expect(reloadPreview).not.toHaveBeenCalled();
     });
   });
+
+  // `/api/events` is one connection per SERVER (CLI host), not per project — a
+  // tab left open from a `preview` run whose port was later reused by a
+  // different project's `preview` shares this stream with it. Both projects
+  // commonly use the same default composition path, so without the filter a
+  // stale tab reloads its preview and re-reads its own composition on every
+  // save the OTHER project makes.
+  describe("cross-project deliveries on a shared connection", () => {
+    it("ignores a delivery whose projectId does not match this tab's", async () => {
+      const drainPendingChanges = vi.fn(async () => ({ status: "clean" as const }));
+      const reloadPreview = vi.fn();
+      const reloadSdkSession = vi.fn();
+      await mountCoordinator({ drainPendingChanges, reloadPreview, reloadSdkSession });
+
+      await act(async () =>
+        handler?.({
+          path: "index.html",
+          content: "other project",
+          version: "v9",
+          projectId: "project-b",
+        }),
+      );
+
+      expect(drainPendingChanges).not.toHaveBeenCalled();
+      expect(reloadPreview).not.toHaveBeenCalled();
+      expect(reloadSdkSession).not.toHaveBeenCalled();
+    });
+
+    it("still reloads for a delivery whose projectId matches this tab's", async () => {
+      const reloadPreview = vi.fn();
+      await mountCoordinator({ reloadPreview });
+
+      await act(async () =>
+        handler?.({
+          path: "index.html",
+          content: "same project",
+          version: "v9",
+          projectId: "project-a",
+        }),
+      );
+
+      expect(reloadPreview).toHaveBeenCalledOnce();
+    });
+
+    it("still reloads when projectId is absent (older server, one release of skew)", async () => {
+      const reloadPreview = vi.fn();
+      await mountCoordinator({ reloadPreview });
+
+      await act(async () =>
+        handler?.({ path: "index.html", content: "no project id", version: "v9" }),
+      );
+
+      expect(reloadPreview).toHaveBeenCalledOnce();
+    });
+  });
 });

package/src/hooks/useExternalFileChangeCoordinator.ts

@@ -349,6 +349,19 @@ export function useExternalFileChangeCoordinator({
         logReload("file-change", { path: null, why: path ? "no project" : "no path in payload" });
         return;
       }
+      // `/api/events` is one connection per SERVER, not per project: under the
+      // CLI host, a tab left open from a `preview` run that has since exited
+      // shares this stream with whatever project now runs on that port. Both
+      // commonly use the same default composition path, so without this check
+      // a stale tab reloads its preview (which then 404s — the CLI host is
+      // single-project, so it can't resolve the OTHER project it's serving)
+      // and re-reads its own composition on every save the CURRENT project
+      // makes. Absent field (older server, one release of skew) still passes.
+      const deliveredProjectId = readFileChangeField(payload, "projectId");
+      if (deliveredProjectId && deliveredProjectId !== projectId) {
+        logReload("suppressed", { path, why: "other project" });
+        return;
+      }
       pendingTimelineEditPathRef.current.delete(path);
 
       const content = readFileChangeContent(payload);

package/src/hooks/useRenderClipContent.test.ts

@@ -13,7 +13,7 @@ import { useRenderClipContent } from "./useRenderClipContent";
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 afterEach(() => {
-  usePlayerStore.setState({ thumbnailMode: "hidden" });
+  usePlayerStore.setState({ thumbnailMode: "hidden", elements: [] });
   document.body.innerHTML = "";
 });
 
@@ -144,6 +144,36 @@ describe("useRenderClipContent", () => {
     }
   });
 
+  it("marks audio linked when a video clip uses the same file, and muted when hidden", () => {
+    usePlayerStore.setState({
+      thumbnailMode: "hidden",
+      elements: [
+        {
+          id: "picture",
+          tag: "video",
+          start: 0,
+          duration: 4,
+          track: 0,
+          src: "assets/clip.mp4",
+        },
+      ],
+    });
+    const linked = renderClipContent({
+      id: "bed",
+      tag: "audio",
+      start: 0,
+      duration: 4,
+      track: 1,
+      src: "assets/clip.mp4",
+      hidden: true,
+    });
+    expect(isValidElement<{ linked: boolean; muted: boolean }>(linked)).toBe(true);
+    if (isValidElement<{ linked: boolean; muted: boolean }>(linked)) {
+      expect(linked.props.linked).toBe(true);
+      expect(linked.props.muted).toBe(true);
+    }
+  });
+
   it("passes empty labels to thumbnail content so TimelineClip owns clip names", () => {
     usePlayerStore.setState({ thumbnailMode: "adaptive" });
 
@@ -208,7 +238,7 @@ describe("useRenderClipContent", () => {
     }
   });
 
-  it("forwards the viewport priority and interaction detail to media work", () => {
+  it("forwards the viewport priority to video media work", () => {
     usePlayerStore.setState({ thumbnailMode: "adaptive", timelineSessionEpoch: 7 });
 
     const content = renderClipContent(
@@ -229,7 +259,6 @@ describe("useRenderClipContent", () => {
         projectId: string;
         sessionEpoch: number;
         priority: string;
-        rich: boolean;
       }>(content),
     ).toBe(true);
     if (isValidElement(content)) {
@@ -237,8 +266,8 @@ describe("useRenderClipContent", () => {
         projectId: "my-project",
         sessionEpoch: 7,
         priority: "interaction",
-        rich: true,
       });
+      expect(content.props).not.toHaveProperty("rich");
     }
   });
 

package/src/hooks/useRenderClipContent.ts

@@ -4,6 +4,7 @@ import { createElement } from "react";
 import { CompositionThumbnail, VideoThumbnail } from "../player";
 import type { TimelineElement } from "../player";
 import type { TimelineClipRenderContext } from "../player/components/TimelineTypes";
+import { audioPillFlags } from "../player/components/audioClipLink";
 import { AudioWaveform } from "../player/components/AudioWaveform";
 import { ImageThumbnail } from "../player/components/ImageThumbnail";
 import { encodePreviewPath, resolveMediaPreviewUrl } from "../player/components/thumbnailUtils";
@@ -70,6 +71,7 @@ function renderAudioClip(
   sessionEpoch: number,
   labelColor: string,
   context: TimelineClipRenderContext,
+  elements: readonly TimelineElement[],
 ): ReactNode {
   const audioUrl = resolveMediaPreviewUrl(el.src ?? "", pid, window.location.origin);
   const srcRelative = resolvePreviewRelative(audioUrl, pid, window.location.origin);
@@ -91,6 +93,7 @@ function renderAudioClip(
     projectId: pid,
     sessionEpoch,
     priority: context.priority,
+    ...audioPillFlags(el, elements),
   });
 }
 
@@ -112,6 +115,7 @@ export function useRenderClipContent({
   const effectiveMode = effectiveThumbnailMode(thumbnailMode);
   const sessionEpoch = usePlayerStore((s) => s.timelineSessionEpoch);
   const contentRevision = usePlayerStore((s) => s.thumbnailContentRevision);
+  const elements = usePlayerStore((s) => s.elements);
   return useCallback(
     // Pre-existing clip-content dispatcher; reduced by extracting renderAudioClip.
     // fallow-ignore-next-line complexity
@@ -127,7 +131,7 @@ export function useRenderClipContent({
       // its waveform (cheap, not a frame thumbnail). Toggle: timeline toolbar.
       if (effectiveMode === "hidden") {
         return el.tag === "audio"
-          ? renderAudioClip(el, pid, sessionEpoch, style.label, context)
+          ? renderAudioClip(el, pid, sessionEpoch, style.label, context, elements)
           : null;
       }
 
@@ -165,7 +169,7 @@ export function useRenderClipContent({
       // activePreviewUrl thumbnail branch; audio rows need waveform data, not a
       // captured frame from the currently drilled composition preview.
       if (el.tag === "audio") {
-        return renderAudioClip(el, pid, sessionEpoch, style.label, context);
+        return renderAudioClip(el, pid, sessionEpoch, style.label, context, elements);
       }
 
       // When drilled into a composition, render all inner elements via
@@ -220,7 +224,6 @@ export function useRenderClipContent({
           projectId: pid,
           sessionEpoch,
           priority: context.priority,
-          rich: context.rich,
         });
       }
 
@@ -252,6 +255,7 @@ export function useRenderClipContent({
       effectiveMode,
       sessionEpoch,
       contentRevision,
+      elements,
     ],
   );
 }

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

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 // @vitest-environment happy-dom
 import { act } from "react";
 import { createRoot } from "react-dom/client";
@@ -263,6 +264,64 @@ describe("useSdkSession unavailable telemetry", () => {
       stage: "read",
       reason: "http_error",
       status: 404,
+      why: undefined,
+    });
+    await act(async () => root.unmount());
+  });
+
+  // `why` distinguishes the studio-server route's own 403/404 causes (the
+  // project's folder having been renamed or deleted out from under a running
+  // server, vs. a NUL byte, vs. a path escaping the project) from a bare
+  // status code. Optional and best-effort: an older server or a non-JSON body
+  // just omits it, which must not crash the read.
+  it("carries the server's why when the error body has one", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          ({
+            ok: false,
+            status: 404,
+            json: async () => ({ error: "not found", why: "project_dir_missing" }),
+          }) as Response,
+      ),
+    );
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<Probe projectId="project-a" />));
+    await flushAsyncEffects();
+
+    expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "read",
+      reason: "http_error",
+      status: 404,
+      why: "project_dir_missing",
+    });
+    await act(async () => root.unmount());
+  });
+
+  it("stays quiet about why when the response body cannot be parsed", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          ({
+            ok: false,
+            status: 500,
+            json: async () => {
+              throw new Error("not json");
+            },
+          }) as unknown as Response,
+      ),
+    );
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<Probe projectId="project-a" />));
+    await flushAsyncEffects();
+
+    expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "read",
+      reason: "http_error",
+      status: 500,
+      why: undefined,
     });
     await act(async () => root.unmount());
   });
@@ -287,6 +346,8 @@ describe("useSdkSession unavailable telemetry", () => {
     expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
       stage: "read",
       reason: "network",
+      elapsed_ms: expect.any(Number),
+      hidden: expect.any(Boolean),
     });
     expect(trackMock).not.toHaveBeenCalledWith("sdk_session_unavailable", {
       stage: "open",
@@ -295,6 +356,70 @@ describe("useSdkSession unavailable telemetry", () => {
     await act(async () => root.unmount());
   });
 
+  // `elapsed_ms` is the discriminator this event exists for: a policy block
+  // (CSP, PNA, an extension rewriting fetch) rejects near-instantly; a dropped
+  // connection (the tab or `preview` server going away mid-flight) rejects
+  // after a real delay. Both look identical without the timing.
+  it("times the network rejection from fetch start to reject", async () => {
+    // Fake only the clock `performance.now` reads, not timers: other code in
+    // this tree (React's own scheduler included) also calls `performance.now`,
+    // so pinning return values by call order (`mockReturnValueOnce`) is
+    // unreliable — a real run showed React consuming the queued values first.
+    // A fake clock that only advances when we say so sidesteps that entirely.
+    vi.useFakeTimers({ toFake: ["performance"] });
+    let rejectFetch: ((error: unknown) => void) | undefined;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        () =>
+          new Promise((_resolve, reject) => {
+            rejectFetch = reject;
+          }),
+      ),
+    );
+    const root = createRoot(document.createElement("div"));
+    // The effect runs synchronously up to `await fetch(...)`, capturing
+    // `fetchStarted` at the current (fake) clock value before this returns.
+    await act(async () => root.render(<Probe projectId="project-a" />));
+    await vi.advanceTimersByTimeAsync(3_200);
+    await act(async () => rejectFetch?.(new TypeError("Failed to fetch")));
+
+    expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "read",
+      reason: "network",
+      elapsed_ms: 3_200,
+      hidden: false,
+    });
+    vi.useRealTimers();
+    await act(async () => root.unmount());
+  });
+
+  it("records the page as hidden when the rejection lands after the tab is backgrounded", async () => {
+    const originalDescriptor = Object.getOwnPropertyDescriptor(document, "visibilityState");
+    Object.defineProperty(document, "visibilityState", {
+      configurable: true,
+      get: () => "hidden",
+    });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new TypeError("Failed to fetch");
+      }),
+    );
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<Probe projectId="project-a" />));
+    await flushAsyncEffects();
+
+    expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "read",
+      reason: "network",
+      elapsed_ms: expect.any(Number),
+      hidden: true,
+    });
+    await act(async () => root.unmount());
+    if (originalDescriptor) Object.defineProperty(document, "visibilityState", originalDescriptor);
+  });
+
   it("separates an unexpected response shape from a failed request", async () => {
     vi.stubGlobal(
       "fetch",
@@ -324,13 +449,67 @@ describe("useSdkSession unavailable telemetry", () => {
     await act(async () => root.render(<Probe projectId="project-a" />));
     await flushAsyncEffects();
 
+    // No fileTree passed (this Probe doesn't have one) — path_in_tree stays
+    // null, same as before the tree loads. See the tree-aware tests below.
     expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
       stage: "read",
       reason: "absent_or_empty",
+      path_in_tree: null,
     });
     await act(async () => root.unmount());
   });
 
+  // The graveyard-refuted fix's proposed next step: instrument, don't act.
+  // `path_in_tree` separates "genuinely not in the loaded tree" from
+  // "concurrent/duplicate open" without deciding anything on Studio's behalf.
+  // Two separate mounts (not a re-render of one): fileTree/fileTreeLoaded are
+  // deliberately outside the open effect's deps — re-running the whole
+  // open/dispose cycle on every tree refresh would drop a perfectly good
+  // session far more often than the tree actually changes — so a prop-only
+  // change on an already-mounted probe would never re-fire the read this
+  // event comes from.
+  it("reports path_in_tree against the caller's loaded file tree", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: true, json: async () => ({ content: "" }) }) as Response),
+    );
+    function TreeProbe({
+      fileTree,
+      fileTreeLoaded,
+    }: {
+      fileTree: string[];
+      fileTreeLoaded: boolean;
+    }) {
+      useSdkSession("project-a", "index.html", fileTree, fileTreeLoaded);
+      return null;
+    }
+
+    const rootA = createRoot(document.createElement("div"));
+    await act(async () =>
+      rootA.render(<TreeProbe fileTree={["other.html"]} fileTreeLoaded={true} />),
+    );
+    await flushAsyncEffects();
+    expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "read",
+      reason: "absent_or_empty",
+      path_in_tree: false,
+    });
+    await act(async () => rootA.unmount());
+
+    trackMock.mockClear();
+    const rootB = createRoot(document.createElement("div"));
+    await act(async () =>
+      rootB.render(<TreeProbe fileTree={["index.html"]} fileTreeLoaded={true} />),
+    );
+    await flushAsyncEffects();
+    expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "read",
+      reason: "absent_or_empty",
+      path_in_tree: true,
+    });
+    await act(async () => rootB.unmount());
+  });
+
   it("reports a parse failure with its message", async () => {
     vi.stubGlobal(
       "fetch",

package/src/hooks/useSdkSession.ts

@@ -26,13 +26,22 @@ import { addExternalFileReloadListener } from "./externalFileReloadBus";
  * "Failed to fetch", "Load failed", "NetworkError when attempting to fetch
  * resource." — so the class was a network problem filed under a parser one, and
  * unaddressable in that bucket.
+ *
+ * `network` carries `elapsedMs` (time from fetch start to rejection) and
+ * `hidden` (`document.visibilityState` at the moment of rejection) because
+ * "the fetch rejected" alone conflates two very different situations: a
+ * closing tab or a server that exited under a live one (rejects after a real
+ * delay, `hidden` often true by the time it lands) versus a request blocked
+ * before it left the browser — CSP `connect-src`, Private Network Access, an
+ * extension rewriting `fetch` (rejects near-instantly, tab stays visible and
+ * alive). Telemetry before this change could not tell the two apart.
  */
 type ProjectFileReadFailure =
   | { ok: false; reason: "unsafe_path" }
-  | { ok: false; reason: "http_error"; status: number }
+  | { ok: false; reason: "http_error"; status: number; why?: string }
   | { ok: false; reason: "missing_content" }
   | { ok: false; reason: "absent_or_empty" }
-  | { ok: false; reason: "network" };
+  | { ok: false; reason: "network"; elapsedMs: number; hidden: boolean };
 
 type ProjectFileReadResult = { ok: true; content: string } | ProjectFileReadFailure;
 
@@ -54,16 +63,61 @@ type ProjectFileReadResult = { ok: true; content: string } | ProjectFileReadFail
  * called from is a long pre-existing async body already near the complexity
  * threshold, and this branch is one coherent unit.
  */
-function reportReadFailure(read: ProjectFileReadFailure, projectId: string): string | null {
+function reportReadFailure(
+  read: ProjectFileReadFailure,
+  projectId: string,
+  pathInTree: boolean | null,
+): string | null {
   trackStudioEvent("sdk_session_unavailable", {
     stage: "read",
     reason: read.reason,
-    ...(read.reason === "http_error" ? { status: read.status } : {}),
+    ...(read.reason === "http_error" ? { status: read.status, why: read.why } : {}),
+    ...(read.reason === "network" ? { elapsed_ms: read.elapsedMs, hidden: read.hidden } : {}),
+    // Only meaningful for `absent_or_empty` — the graveyard-refuted "clear
+    // activeCompPath when it's not in the tree" fix's proposed next step,
+    // scoped to instrumentation only. `null` while the tree hasn't loaded
+    // yet: a false-negative there would read as "genuinely absent" when it is
+    // really "haven't looked".
+    ...(read.reason === "absent_or_empty" ? { path_in_tree: pathInTree } : {}),
   });
   if (read.reason !== "http_error") return null;
   return read.status === 404 ? projectId : null;
 }
 
+// The request never produced a response: offline, the dev server gone, a
+// CSP/Private-Network-Access block, or an extension rewriting fetch. Called
+// from the fetch's own catch so it is reported as a READ failure — left to
+// propagate, the effect's outer catch reported it as `stage: "open"`, which
+// claims the composition failed to parse. Every `stage: open` event before
+// this change was this branch, so the label made the largest class
+// unaddressable.
+//
+// `elapsedMs` and `hidden` (read synchronously, right at the moment of
+// rejection, so they survive whenever the event itself does) are the
+// discriminator between "blocked before send" (near-zero elapsed) and "the
+// tab/server went away mid-flight" (real elapsed, often already hidden) —
+// see the type's doc comment.
+function networkReadFailure(
+  fetchStarted: number,
+): Extract<ProjectFileReadFailure, { reason: "network" }> {
+  return {
+    ok: false,
+    reason: "network",
+    elapsedMs: Math.round(performance.now() - fetchStarted),
+    hidden: typeof document !== "undefined" && document.visibilityState === "hidden",
+  };
+}
+
+// `why` distinguishes the studio-server route's own 403/404 causes (a NUL
+// byte, a path escaping the project, or — the one that used to read as a
+// plain path-traversal 403 — this project's folder having been renamed or
+// deleted out from under a still-running server) that a bare status code
+// cannot. Best-effort: an older server or a non-JSON error body just omits it.
+async function httpReadFailureWhy(res: Response): Promise<string | undefined> {
+  const body = (await res.json().catch(() => null)) as { why?: unknown } | null;
+  return typeof body?.why === "string" ? body.why : undefined;
+}
+
 /**
  * Read a project file's content (optional read — a missing file is not an
  * error). Replaces the removed SDK http adapter's `read()` — the only thing
@@ -80,20 +134,18 @@ async function readProjectFileOptional(
   // already confines both values to single segments of this same-origin URL.
   if (path.includes("\0") || path.includes("..")) return { ok: false, reason: "unsafe_path" };
   let res: Response;
+  const fetchStarted = performance.now();
   try {
     res = await fetch(
       `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}?optional=1`,
     );
   } catch {
-    // The request never produced a response: offline, the dev server gone, a
-    // CSP/Private-Network-Access block, or an extension rewriting fetch. Caught
-    // here so it is reported as a READ failure — left to propagate, the effect's
-    // outer catch reported it as `stage: "open"`, which claims the composition
-    // failed to parse. Every `stage: open` event before this change was this
-    // branch, so the label made the largest class unaddressable.
-    return { ok: false, reason: "network" };
+    return networkReadFailure(fetchStarted);
+  }
+  if (!res.ok) {
+    const why = await httpReadFailureWhy(res);
+    return { ok: false, reason: "http_error", status: res.status, ...(why ? { why } : {}) };
   }
-  if (!res.ok) return { ok: false, reason: "http_error", status: res.status };
   const data = (await res.json()) as { content?: string };
   // `optional=1` answers a missing file with 200 + `content: ""`, so a
   // non-string here means a response shape we did not expect, not absence.
@@ -224,6 +276,13 @@ function disposeSdkSession(session: Composition): void {
 export function useSdkSession(
   projectId: string | null,
   activeCompPath: string | null,
+  // Optional: only the app's primary session (App.tsx, wired to
+  // useFileManager's tree) can answer `path_in_tree` on an `absent_or_empty`
+  // read. A secondary session opened for a promote/bind target
+  // (DesignPanelPromoteProvider) has no tree of its own to check against and
+  // reports `null`, same as before the tree loads.
+  fileTree: readonly string[] = [],
+  fileTreeLoaded = false,
 ): SdkSessionHandle {
   const [ownedSession, setOwnedSession] = useState<OwnedSdkSession | null>(null);
   const ownedSessionRef = useRef<OwnedSdkSession | null>(null);
@@ -276,7 +335,8 @@ export function useSdkSession(
       .then(async (read) => {
         if (cancelled) return;
         if (!read.ok) {
-          setUnreachableProject(reportReadFailure(read, projectId));
+          const pathInTree = fileTreeLoaded ? fileTree.includes(activeCompPath) : null;
+          setUnreachableProject(reportReadFailure(read, projectId, pathInTree));
           return;
         }
         setUnreachableProject(null);
@@ -305,7 +365,11 @@ export function useSdkSession(
           )
         ) {
           disposeSdkSession(comp);
-          trackStudioEvent("sdk_session_unavailable", { stage: "ownership" });
+          // Not a failure: project/path/reloadToken moved on while this open was
+          // in flight, and the effect that owns the new identity already opened
+          // (or is opening) its own session. Emitting this as `sdk_session_unavailable`
+          // counted a benign race as a broken precondition on the cutover dashboard.
+          trackStudioEvent("sdk_session_superseded", {});
           return;
         }
         const displaced = ownedSessionRef.current;
@@ -343,6 +407,12 @@ 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.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [projectId, activeCompPath, reloadToken]);
 
   const forceReload = useCallback(() => setReloadToken((t) => t + 1), []);

package/src/hooks/useStudioSdkSessions.ts

@@ -18,12 +18,19 @@ export function useStudioSdkSessions(
   projectId: string | null,
   activeCompPath: string | null,
   masterCompPath: string | null,
+  fileTree: readonly string[] = [],
+  fileTreeLoaded = false,
 ) {
   // 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
   // "index.html" that may not exist. `null` when the project has no composition
   // yet, which correctly leaves the session (and the panels) empty.
-  const sdkHandle = useSdkSession(projectId, activeCompPath ?? masterCompPath);
+  const sdkHandle = useSdkSession(
+    projectId,
+    activeCompPath ?? masterCompPath,
+    fileTree,
+    fileTreeLoaded,
+  );
   const editFlowSdkSession = activeCompPath ? sdkHandle.session : null;
   useEffect(() => {
     usePreviewVariablesStore.getState().setValues(null);