@hyperframes/studio 0.8.49 → 0.8.51

package/src/hooks/useClipboard.ts

@@ -2,14 +2,23 @@ import { useCallback, useRef } from "react";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
-import { type ClipboardPayload, deduplicateIds, insertAsSibling } from "../utils/clipboardPayload";
+import {
+  type ClipboardPayload,
+  type TimelineClipboardClip,
+  ID_ATTR_RE,
+  deduplicateIds,
+  insertAsSibling,
+} from "../utils/clipboardPayload";
 import { collectHtmlIds } from "../utils/studioHelpers";
 import { insertTimelineAssetIntoSource } from "../utils/timelineAssetDrop";
+import { extendRootDurationInSource } from "../utils/rootDuration";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import type { EditHistoryKind } from "../utils/editHistory";
 import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
 import { findElementForSelection } from "../components/editor/domEditingElement";
-import { readFileContent } from "./timelineEditingHelpers";
+import { findTimelineElementInIframe, readFileContent } from "./timelineEditingHelpers";
+import { buildTimelineElementKey } from "../player/lib/timelineElementHelpers";
+import { timeRangesOverlap } from "../player/components/timelineCollision";
 
 interface RecordEditInput {
   label: string;
@@ -26,11 +35,34 @@ interface UseClipboardOptions {
   writeProjectFile: (path: string, content: string) => Promise<void>;
   recordEdit: (input: RecordEditInput) => Promise<void>;
   reloadPreview: () => void;
-  handleTimelineElementDelete: (element: TimelineElement) => Promise<void>;
+  handleTimelineElementsDelete: (elements: TimelineElement[]) => Promise<void>;
   handleDomEditElementDelete: (selection: DomEditSelection) => Promise<void>;
   previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
 }
 
+/** The timeline element(s) a copy/cut/duplicate acts on: the multi-selection
+ *  when one is active, else the single primary selection. */
+function getSelectedElements(): TimelineElement[] {
+  const { selectedElementId, selectedElementIds, elements } = usePlayerStore.getState();
+  if (!selectedElementId) return [];
+  const ids = selectedElementIds.size > 1 ? selectedElementIds : new Set([selectedElementId]);
+  return elements.filter((el) => ids.has(el.key ?? el.id));
+}
+
+function elementKey(domId: string, sourceFile: string): string {
+  return buildTimelineElementKey({ id: domId, fallbackIndex: 0, domId, sourceFile });
+}
+
+/** "Paste clip" / "Paste clips" — the edit-history label, no count shown. */
+function clipLabel(verb: string, clipCount: number): string {
+  return `${verb} ${clipCount > 1 ? "clips" : "clip"}`;
+}
+
+/** "Pasted clip" / "Pasted 3 clips" — the toast message, count shown once plural. */
+function clipToast(verbPast: string, clipCount: number): string {
+  return clipCount > 1 ? `${verbPast} ${clipCount} clips` : `${verbPast} clip`;
+}
+
 function getElementOuterHtml(
   iframeRef: React.MutableRefObject<HTMLIFrameElement | null>,
   selection: DomEditSelection,
@@ -47,6 +79,94 @@ function getElementOuterHtml(
   return findElementForSelection(doc, selection, activeCompositionPath)?.outerHTML ?? null;
 }
 
+export interface PlacedClip {
+  track: number;
+  start: number;
+  duration: number;
+}
+
+function tracksOverlap(a: PlacedClip, b: PlacedClip): boolean {
+  return (
+    a.track === b.track &&
+    timeRangesOverlap(a.start, a.start + a.duration, b.start, b.start + b.duration)
+  );
+}
+
+/** CapCut: keeps the preferred track if free at the new time, else the next
+ *  unused track index. Exported so placement is tested with values directly. */
+export function resolveFreeTrack(preferred: PlacedClip, taken: readonly PlacedClip[]): number {
+  if (!taken.some((t) => tracksOverlap(preferred, t))) return preferred.track;
+  const maxTrack = taken.reduce((max, t) => Math.max(max, t.track), preferred.track);
+  return maxTrack + 1;
+}
+
+/** Strips data-hf-id from the root and every descendant so a clone re-mints
+ *  its own. DOMParser, not a bracket-scoped regex, so a `>` inside an earlier
+ *  attribute value or a single-quoted id can't defeat the strip. */
+function stripHfIds(html: string, parser: DOMParser): string {
+  const root = parser.parseFromString(html, "text/html").body.firstElementChild;
+  if (!root) {
+    // A tag the HTML parser hoists out of <body> (title/meta/style/base/link)
+    // never reaches the walk above — fall back to a direct strip so
+    // data-hf-id still can't survive, even though no real clip root is one
+    // of these tags today.
+    return html.replace(/\sdata-hf-id=("[^"]*"|'[^']*')/g, "");
+  }
+  root.querySelectorAll("[data-hf-id]").forEach((el) => el.removeAttribute("data-hf-id"));
+  root.removeAttribute("data-hf-id");
+  return root.outerHTML;
+}
+
+/** Shared insertion path for paste and duplicate, anchored at the playhead or
+ *  the selection's end respectively. Returns the final ids so the caller can
+ *  select what it just placed, and the furthest end any clip lands at so the
+ *  caller can grow the root composition's duration to cover it. */
+export function pasteTimelineClips(
+  content: string,
+  clips: readonly TimelineClipboardClip[],
+  anchorTime: number,
+  liveElements: readonly TimelineElement[],
+): { content: string; ids: string[]; requiredEnd: number } {
+  const groupMinStart = Math.min(...clips.map((c) => c.start));
+  let existingIds = collectHtmlIds(content);
+  const taken: PlacedClip[] = liveElements.map((el) => ({
+    track: el.authoredTrack ?? el.track,
+    start: el.start,
+    duration: el.duration,
+  }));
+  const ids: string[] = [];
+  let result = content;
+  let requiredEnd = 0;
+  const domParser = new DOMParser();
+  for (const clip of clips) {
+    const stripped = stripHfIds(clip.html, domParser);
+    const deduped = deduplicateIds(stripped, existingIds);
+    existingIds = existingIds.concat(collectHtmlIds(deduped));
+    const newStart = anchorTime + (clip.start - groupMinStart);
+    const newTrack = resolveFreeTrack(
+      { track: clip.track, start: newStart, duration: clip.duration },
+      taken,
+    );
+    taken.push({ track: newTrack, start: newStart, duration: clip.duration });
+    requiredEnd = Math.max(requiredEnd, newStart + clip.duration);
+
+    // Only rewrite the outermost opening tag. The non-global regex matches
+    // the first occurrence, which is always in the root tag since outerHTML
+    // starts with it. Nested clips keep their own timing and track.
+    const rootTagEnd = deduped.indexOf(">");
+    const rootTag = rootTagEnd >= 0 ? deduped.slice(0, rootTagEnd + 1) : deduped;
+    const patchedRootTag = rootTag
+      .replace(/data-start="[^"]*"/, `data-start="${formatTimelineAttributeNumber(newStart)}"`)
+      .replace(/data-track-index="[^"]*"/, `data-track-index="${newTrack}"`);
+    const withPatched = patchedRootTag + deduped.slice(rootTagEnd + 1);
+    result = insertTimelineAssetIntoSource(result, withPatched);
+
+    const id = patchedRootTag.match(ID_ATTR_RE)?.[1];
+    if (id) ids.push(id);
+  }
+  return { content: result, ids, requiredEnd };
+}
+
 export function useClipboard({
   projectId,
   activeCompPath,
@@ -55,7 +175,7 @@ export function useClipboard({
   writeProjectFile,
   recordEdit,
   reloadPreview,
-  handleTimelineElementDelete,
+  handleTimelineElementsDelete,
   handleDomEditElementDelete,
   previewIframeRef,
 }: UseClipboardOptions) {
@@ -63,47 +183,50 @@ export function useClipboard({
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
 
-  // The copy-mode branches predate this change; this diff only replaces its
-  // duplicated DOM lookup with the canonical composition-aware resolver.
-  // fallow-ignore-next-line complexity
-  const handleCopy = useCallback((): boolean => {
-    const { selectedElementId, elements } = usePlayerStore.getState();
-
-    // Timeline clip copy
-    if (selectedElementId) {
-      const element = elements.find((el) => (el.key ?? el.id) === selectedElementId);
-      if (!element) return false;
-      const targetPath = element.sourceFile || activeCompPath || "index.html";
-
-      let html: string | null = null;
-      try {
-        const doc = previewIframeRef.current?.contentDocument;
-        if (doc) {
-          html =
-            findElementForSelection(
-              doc,
-              {
-                hfId: element.hfId,
-                id: element.domId,
-                selector: element.selector,
-                selectorIndex: element.selectorIndex,
-                sourceFile: targetPath,
-              },
-              activeCompPath,
-            )?.outerHTML ?? null;
-        }
-      } catch {
-        // cross-origin frame
-      }
+  // Resolved through findTimelineElementInIframe, the same composition-aware
+  // lookup every other timeline editor uses — unlike findElementForSelection,
+  // it can address a composition-instance clip's root.
+  const collectSelectedClips = useCallback((): {
+    elements: TimelineElement[];
+    clips: TimelineClipboardClip[];
+  } | null => {
+    const selected = getSelectedElements();
+    if (selected.length === 0) return null;
 
+    const clips: TimelineClipboardClip[] = [];
+    for (const element of selected) {
+      const html =
+        findTimelineElementInIframe(previewIframeRef.current, element, activeCompPath)?.outerHTML ??
+        null;
       if (!html) {
-        showToast("Unable to copy this element.", "info");
-        return false;
+        showToast(`Unable to copy "${element.label ?? element.id}".`, "info");
+        return null;
       }
+      clips.push({
+        html,
+        start: element.start,
+        duration: element.duration,
+        // authoredTrack, not track: `track` can be a display-lane number
+        // remapped by normalizeToZones, and writing THAT into data-track-index
+        // re-targets the wrong track in the sparse authored file.
+        track: element.authoredTrack ?? element.track,
+      });
+    }
+    return { elements: selected, clips };
+  }, [activeCompPath, previewIframeRef, showToast]);
 
-      const payload: ClipboardPayload = { kind: "timeline-clip", html, sourceFile: targetPath };
-      clipboardRef.current = payload;
-      showToast("Copied clip", "info");
+  // Two independent copy modes (timeline clip vs DOM element) in one handler.
+  // fallow-ignore-next-line complexity
+  const handleCopy = useCallback((): boolean => {
+    if (usePlayerStore.getState().selectedElementId) {
+      const result = collectSelectedClips();
+      if (!result) return false;
+      const targetPath = result.elements[0]?.sourceFile || activeCompPath || "index.html";
+      clipboardRef.current = { kind: "timeline-clip", clips: result.clips, sourceFile: targetPath };
+      showToast(
+        result.clips.length > 1 ? `Copied ${result.clips.length} clips` : "Copied clip",
+        "info",
+      );
       return true;
     }
 
@@ -116,21 +239,23 @@ export function useClipboard({
         return false;
       }
       const targetPath = domSelection.sourceFile || activeCompPath || "index.html";
-      const payload: ClipboardPayload = {
+      clipboardRef.current = {
         kind: "dom-element",
         html,
         sourceFile: targetPath,
         originSelector: domSelection.selector,
         originSelectorIndex: domSelection.selectorIndex,
       };
-      clipboardRef.current = payload;
       showToast("Copied element", "info");
       return true;
     }
 
+    showToast("Nothing selected to copy.", "info");
     return false;
-  }, [activeCompPath, domEditSelectionRef, previewIframeRef, showToast]);
+  }, [activeCompPath, collectSelectedClips, domEditSelectionRef, previewIframeRef, showToast]);
 
+  // Two independent paste modes (timeline clip vs DOM element) behind one guarded save.
+  // fallow-ignore-next-line complexity
   const handlePaste = useCallback(async () => {
     const payload = clipboardRef.current;
     if (!payload) {
@@ -143,24 +268,19 @@ export function useClipboard({
     const targetPath = activeCompPath || "index.html";
     try {
       const originalContent = await readFileContent(pid, targetPath);
-      const existingIds = collectHtmlIds(originalContent);
-      const deduped = deduplicateIds(payload.html, existingIds);
-
       let patchedContent: string;
+      let pastedIds: string[] = [];
+
       if (payload.kind === "timeline-clip") {
-        // Only rewrite data-start on the outermost opening tag. The non-global
-        // regex matches the first occurrence, which is always in the root tag
-        // since outerHTML starts with it. Nested clips keep their own timing.
-        const { currentTime } = usePlayerStore.getState();
-        const rootTagEnd = deduped.indexOf(">");
-        const rootTag = rootTagEnd >= 0 ? deduped.slice(0, rootTagEnd + 1) : deduped;
-        const patchedRootTag = rootTag.replace(
-          /data-start="[^"]*"/,
-          `data-start="${formatTimelineAttributeNumber(currentTime)}"`,
-        );
-        const withNewStart = patchedRootTag + deduped.slice(rootTagEnd + 1);
-        patchedContent = insertTimelineAssetIntoSource(originalContent, withNewStart);
+        const { currentTime, elements } = usePlayerStore.getState();
+        const pasted = pasteTimelineClips(originalContent, payload.clips, currentTime, elements);
+        // A clip pasted past the current composition end would exist in the
+        // file but never appear on the timeline or in playback/export (the
+        // root's data-duration is what actually bounds the render).
+        patchedContent = extendRootDurationInSource(pasted.content, pasted.requiredEnd);
+        pastedIds = pasted.ids;
       } else {
+        const deduped = deduplicateIds(payload.html, collectHtmlIds(originalContent));
         patchedContent = insertAsSibling(
           originalContent,
           deduped,
@@ -169,9 +289,14 @@ export function useClipboard({
         );
       }
 
+      const label =
+        payload.kind === "timeline-clip"
+          ? clipLabel("Paste", payload.clips.length)
+          : "Paste element";
+
       await saveProjectFilesWithHistory({
         projectId: pid,
-        label: payload.kind === "timeline-clip" ? "Paste clip" : "Paste element",
+        label,
         kind: "timeline" as EditHistoryKind,
         files: { [targetPath]: patchedContent },
         readFile: async () => originalContent,
@@ -179,25 +304,92 @@ export function useClipboard({
         recordEdit,
       });
 
+      // CapCut: the pasted clip(s) become the selection; the playhead does not
+      // move. reloadPreview is a bare refresh-key bump with no selection
+      // snapshot of its own; calling setSelection before it is what makes the
+      // post-reload store state land on the pasted ids instead of stale ones.
+      if (pastedIds.length > 0) {
+        usePlayerStore.getState().setSelection(pastedIds.map((id) => elementKey(id, targetPath)));
+      }
       reloadPreview();
-      showToast(payload.kind === "timeline-clip" ? "Pasted clip" : "Pasted element", "info");
+      showToast(
+        payload.kind === "timeline-clip"
+          ? clipToast("Pasted", payload.clips.length)
+          : "Pasted element",
+        "info",
+      );
     } catch (error) {
       const message = error instanceof Error ? error.message : "Failed to paste";
       showToast(message);
     }
   }, [activeCompPath, recordEdit, reloadPreview, showToast, writeProjectFile]);
 
+  // Duplicates the current selection in place, immediately after it, without
+  // touching the clipboard — a pending copy must survive a Cmd+D. Shares
+  // pasteTimelineClips with handlePaste; only the anchor and clip source
+  // differ (the selection's own end here, the playhead there).
+  const handleDuplicate = useCallback(async (): Promise<boolean> => {
+    const result = collectSelectedClips();
+    if (!result) return false;
+    const pid = projectIdRef.current;
+    if (!pid) return false;
+
+    const { elements, clips } = result;
+    const targetPath = elements[0]?.sourceFile || activeCompPath || "index.html";
+    const anchorTime = Math.max(...elements.map((el) => el.start + el.duration));
+
+    try {
+      const originalContent = await readFileContent(pid, targetPath);
+      const liveElements = usePlayerStore.getState().elements;
+      const pasted = pasteTimelineClips(originalContent, clips, anchorTime, liveElements);
+      const patchedContent = extendRootDurationInSource(pasted.content, pasted.requiredEnd);
+      const ids = pasted.ids;
+
+      await saveProjectFilesWithHistory({
+        projectId: pid,
+        label: clipLabel("Duplicate", clips.length),
+        kind: "timeline" as EditHistoryKind,
+        files: { [targetPath]: patchedContent },
+        readFile: async () => originalContent,
+        writeFile: writeProjectFile,
+        recordEdit,
+      });
+
+      // The duplicate becomes the selection, mirroring CapCut's own paste
+      // convention — there is no CapCut Duplicate to match directly (Cmd+D is
+      // a no-op there); this is our own choice for consistency with paste.
+      // Select before reloading, same reason as handlePaste above.
+      if (ids.length > 0) {
+        usePlayerStore.getState().setSelection(ids.map((id) => elementKey(id, targetPath)));
+      }
+      reloadPreview();
+      showToast(clipToast("Duplicated", clips.length), "info");
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to duplicate";
+      showToast(message);
+      return false;
+    }
+  }, [
+    activeCompPath,
+    collectSelectedClips,
+    recordEdit,
+    reloadPreview,
+    showToast,
+    writeProjectFile,
+  ]);
+
   const handleCut = useCallback(async (): Promise<boolean> => {
+    const selected = getSelectedElements();
     const copied = handleCopy();
     if (!copied) return false;
 
-    const { selectedElementId, elements } = usePlayerStore.getState();
-    if (selectedElementId) {
-      const element = elements.find((el) => (el.key ?? el.id) === selectedElementId);
-      if (element) {
-        await handleTimelineElementDelete(element);
-        return true;
-      }
+    if (selected.length > 0) {
+      // One call for the whole selection, not one per element: the batched
+      // delete writes and records history once, so a multi-clip Cmd+X undoes
+      // in a single Cmd+Z instead of needing one per clip.
+      await handleTimelineElementsDelete(selected);
+      return true;
     }
 
     const domSelection = domEditSelectionRef.current;
@@ -206,7 +398,9 @@ export function useClipboard({
       return true;
     }
     return true;
-  }, [handleCopy, domEditSelectionRef, handleTimelineElementDelete, handleDomEditElementDelete]);
+  }, [handleCopy, domEditSelectionRef, handleTimelineElementsDelete, handleDomEditElementDelete]);
+
+  const canPaste = useCallback(() => clipboardRef.current !== null, []);
 
-  return { handleCopy, handlePaste, handleCut };
+  return { handleCopy, handlePaste, handleCut, handleDuplicate, canPaste };
 }

package/src/hooks/useGroupCommits.test.ts

@@ -11,7 +11,6 @@ const timelineElement = (over: Partial<TimelineElement> = {}): TimelineElement =
   start: 0,
   duration: 4,
   track: 0,
-  timingSource: "authored",
   sourceFile: "index.html",
   ...over,
 });

package/src/hooks/useLintModal.test.tsx

@@ -0,0 +1,65 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useLintModal } from "./useLintModal";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | null = null;
+let latest: ReturnType<typeof useLintModal> | null = null;
+
+function Probe() {
+  latest = useLintModal("demo");
+  return null;
+}
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  root = null;
+  latest = null;
+  vi.unstubAllGlobals();
+});
+
+async function mountWithLint(response: () => Promise<unknown>) {
+  vi.stubGlobal("fetch", vi.fn(response));
+  root = createRoot(document.createElement("div"));
+  await act(async () => root?.render(<Probe />));
+  await act(async () => {
+    await latest?.handleLint();
+  });
+}
+
+const lintResponse = (findings: Array<{ severity: string; message: string }>) => async () => ({
+  json: async () => ({ findings }),
+});
+
+describe("useLintModal hasLintError", () => {
+  it("is true when a finding is an error and false for warnings only", async () => {
+    await mountWithLint(lintResponse([{ severity: "error", message: "nested" }]));
+    expect(latest?.hasLintError).toBe(true);
+    act(() => root?.unmount());
+    root = null;
+    await mountWithLint(lintResponse([{ severity: "warning", message: "soft" }]));
+    expect(latest?.hasLintError).toBe(false);
+  });
+
+  it("is true for a mixed error and warning list", async () => {
+    await mountWithLint(
+      lintResponse([
+        { severity: "warning", message: "soft" },
+        { severity: "error", message: "nested" },
+      ]),
+    );
+    expect(latest?.hasLintError).toBe(true);
+  });
+
+  it("is true when the manual lint itself fails, matching the badge count", async () => {
+    await mountWithLint(async () => {
+      throw new Error("offline");
+    });
+    expect(latest?.lintModal).toHaveLength(1);
+    expect(latest?.hasLintError).toBe(true);
+  });
+});

package/src/hooks/useLintModal.ts

@@ -96,6 +96,8 @@ export function useLintModal(projectId: string | null, refreshKey?: number) {
 
   const findingsByElement = useMemo(() => groupFindings((f) => f.elementId), [groupFindings]);
   const findingsByFile = useMemo(() => groupFindings((f) => f.file), [groupFindings]);
+  // Reads the list the badge count reads: the manual result when present, else the background one.
+  const hasLintError = (lintModal ?? backgroundFindings).some((f) => f.severity === "error");
 
   // Sync lint findings directly to the player store — eliminates the
   // mirroring useEffect that was previously in App.tsx.
@@ -111,5 +113,6 @@ export function useLintModal(projectId: string | null, refreshKey?: number) {
     backgroundFindings,
     findingsByElement,
     findingsByFile,
+    hasLintError,
   };
 }

package/src/hooks/useRazorSplit.history.test.tsx

@@ -29,7 +29,6 @@ const element: TimelineElement = {
   track: 0,
   domId: "clip1",
   sourceFile: "index.html",
-  timingSource: "authored",
 };
 
 type Split = (element: TimelineElement, splitTime: number) => Promise<void>;

package/src/hooks/useRazorSplit.test.ts

@@ -24,7 +24,6 @@ const rootElement: TimelineElement = {
   track: 0,
   domId: "root-clip",
   sourceFile: ROOT_FILE,
-  timingSource: "authored",
 };
 
 // An expanded sub-comp child: `start` is in MASTER coordinates (offset by the
@@ -38,7 +37,6 @@ const expandedChild: TimelineElement = {
   track: 1,
   domId: "child-clip",
   sourceFile: SUBCOMP_FILE,
-  timingSource: "authored",
   expandedParentStart: 2,
 };
 

package/src/hooks/useRazorSplit.test.tsx

@@ -82,7 +82,6 @@ describe("useRazorSplit mutation versions", () => {
           start: 0,
           duration: 4,
           track: 0,
-          timingSource: "authored",
         },
         2,
       );

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

@@ -164,17 +164,62 @@ describe("useSdkSession unavailable telemetry", () => {
 
   // Every cutover chokepoint silently takes the server path when there is no
   // session, and the shadow never runs either — so a missing session is a total,
-  // otherwise-invisible SDK bypass. These three exits are its only origin.
-  it("reports an unreadable composition", async () => {
+  // otherwise-invisible SDK bypass. These exits are its only origin.
+  //
+  // `stage: read` carries a reason because it was the largest remaining class
+  // and a single opaque string: 56 users hit it in a 7-day window and never
+  // landed one successful SDK edit between them, with no way to tell a genuinely
+  // absent file from a request that never reached one.
+  it("reports the HTTP status when the read fails", async () => {
     vi.stubGlobal(
       "fetch",
-      vi.fn(async () => ({ ok: false, json: async () => ({}) }) as Response),
+      vi.fn(async () => ({ ok: false, status: 404, json: async () => ({}) }) 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" });
+    expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "read",
+      reason: "http_error",
+      status: 404,
+    });
+    await act(async () => root.unmount());
+  });
+
+  it("separates an unexpected response shape from a failed request", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: true, json: async () => ({}) }) 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: "missing_content",
+    });
+    await act(async () => root.unmount());
+  });
+
+  // `optional=1` answers a file that is not on disk with 200 + an empty string,
+  // so this is what "the composition genuinely is not there" looks like on the
+  // wire — previously indistinguishable from a broken request. The shim and a
+  // real 0-byte file are the same response, hence the name.
+  it("separates a file that is not on disk", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: true, json: async () => ({ content: "" }) }) 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: "absent_or_empty",
+    });
     await act(async () => root.unmount());
   });