@hyperframes/studio 0.8.59 → 0.8.61

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

package/src/player/components/AudioWaveform.test.tsx

@@ -11,7 +11,7 @@ vi.mock("../../hooks/useThumbnailLease", () => ({
   useThumbnailLease: leaseSpy,
 }));
 
-import { AudioWaveform } from "./AudioWaveform";
+import { AudioWaveform, drawWaveformCanvas } from "./AudioWaveform";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -21,6 +21,30 @@ afterEach(() => {
 });
 
 describe("AudioWaveform", () => {
+  it("paints a baseline and peak bar for every mapped waveform bin", () => {
+    const fillRect = vi.fn();
+    const context = {
+      scale: vi.fn(),
+      clearRect: vi.fn(),
+      fillRect,
+      fillStyle: "",
+    } as unknown as CanvasRenderingContext2D;
+    const canvas = document.createElement("canvas");
+    Object.defineProperties(canvas, {
+      clientWidth: { value: 6 },
+      clientHeight: { value: 20 },
+    });
+    vi.spyOn(canvas, "getContext").mockReturnValue(context);
+    drawWaveformCanvas(canvas, [0.25, 1], false, 0, 1);
+    expect(fillRect).toHaveBeenCalledTimes(4);
+    expect(fillRect.mock.calls.map(([x, y, width, height]) => [x, y, width, height])).toEqual([
+      [0, 18, 3, 2],
+      [0, 15, 3, 5],
+      [3, 18, 3, 2],
+      [3, 0, 3, 20],
+    ]);
+  });
+
   it("leases waveform decoding with the clip's project, session, and viewport priority", () => {
     const host = document.createElement("div");
     document.body.append(host);
@@ -50,4 +74,32 @@ describe("AudioWaveform", () => {
 
     act(() => root.unmount());
   });
+
+  it("greys the clip in place when muted and draws the parent tick when linked", () => {
+    const host = document.createElement("div");
+    host.className = "timeline-clip is-audio";
+    document.body.append(host);
+    const root = createRoot(host);
+
+    act(() => {
+      root.render(
+        <AudioWaveform
+          audioUrl="/media/voice.wav"
+          label=""
+          labelColor="#fff"
+          projectId="project-a"
+          sessionEpoch={1}
+          priority="visible"
+          muted
+          linked
+        />,
+      );
+    });
+
+    expect(host.getAttribute("data-audio-muted")).toBe("true");
+    expect(host.querySelector(".timeline-audio-link")).not.toBeNull();
+
+    act(() => root.unmount());
+    expect(host.hasAttribute("data-audio-muted")).toBe(false);
+  });
 });