@ai-matrx/media 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,190 @@
 # @ai-matrx/media
 
+## 0.4.0 — 2026-08-30
+
+**The package renders FILES now, not just media elements** — and it knows what
+Next.js is. Two new subpaths close this package's ALL-INCLUSIVE-LAW retrofit
+row: `./next` (the framework seam every Next host was rebuilding) and
+`./viewers` (the full-pane file viewers matrx-frontend owned).
+
+### Consumer action (C28)
+
+- **`./next` replaces every hand-written `next/image` adapter.** A host's
+  `ImageComponent` port collapses to
+  `ImageComponent: NextMediaImage` (or `createNextMediaImageComponent({…})`).
+  Delete the local wrapper — including the four `as React.*Handler` casts it
+  needed; the package owns those now. `next` is an **optional peer** (`>=14`),
+  so non-Next consumers are unaffected and nothing new installs for them.
+- **`./viewers` replaces host-owned text / code / SVG / HTML / generic
+  previewers.** A host now registers only what the package cannot ship — its
+  heavy engines — and renders `<MediaFileViewer>`:
+
+  ```tsx
+  registerMediaViewer("pdf", HostPdfViewer);        // PDF.js, react-pdf…
+  registerMediaCodeHighlighter(PrismHighlighter);   // optional: colour
+  <MediaFileViewer source={{ kind: "ref", ref }} fileName={name} />
+  ```
+
+  Delete the absorbed bodies. Anything NOT registered renders the announcing
+  default, never a dead pane.
+- 🚨 **`formatFileSize` behavior change (`/react`).** It now accepts
+  `number | null | undefined` and returns `"—"` for null / undefined / NaN /
+  negative, where it previously returned a confident, wrong `"0 B"`. Any
+  consumer asserting `"0 B"` for a missing size must update. (Defect found
+  while absorbing the viewers: matrx-frontend's own `formatFileSize` already
+  had this guard and the package's did not — C22 says the package carries the
+  better one.)
+- **No other existing export changed shape.**
+
+### `./next` — the Next.js binding (NEW)
+
+- `NextMediaImage` and `createNextMediaImageComponent({ unoptimized?, quality?,
+  sizes?, priority?, loader?, className? })` — a `MediaHostPorts.ImageComponent`
+  implementation over `next/image`, with `unoptimized: true` as the default
+  because Matrx durable URLs are session-cookie authenticated and Next's
+  optimizer fetches them SERVER-side, where there is no user session.
+- **The deliberate divergence from `@ai-matrx/data`'s `/next`** (which imports
+  no `next/*` module): `next/image` is not data crossing a seam, it IS the
+  renderer, so no structural seam can express it — the ALL-INCLUSIVE LAW names
+  this exact wrapper as package-owned. Confined to this one entry; the
+  package's components still reach Next only through the `ImageComponent` port.
+- The port's structurally-typed handlers are narrowed to DOM handler types
+  here, once, instead of in every host.
+
+### `./viewers` — full-pane file viewers (NEW)
+
+Absorbed from matrx-frontend `features/files/components/core/FilePreview/`:
+`PreviewerSwitch` (the dispatcher) plus the `TextPreview`, `CodePreview`,
+`SvgPreview`, `HtmlPreview` and `GenericPreview` bodies. Behavior ported
+verbatim except where noted below.
+
+- `MediaFileViewer` — kind dispatch with the C23 resolution order: a host
+  registration wins, else the package's built-in body, else the **announcing
+  default** that names the missing engine and the remedy and still offers
+  download / view-as-text. A blank pane is not a reachable state.
+- Built-in bodies: `TextViewer`, `CodeViewer`, `SvgViewer` (rendered + XML
+  source), `HtmlViewer` (sandboxed frame + source), `GenericViewer`.
+- `registerMediaViewer(kind, Component)` / `registerMediaCodeHighlighter(fn)` —
+  the heavy-engine seam, on `globalThis` `Symbol.for` slots so a registration
+  made in one loader graph is visible from the other (the tarball canary
+  proves it across ESM/CJS). Both return an unregister function.
+- `getPreviewKind(fileName, mimeType?)` — kind derivation from the package's
+  own file-kind registry, so a fresh app dispatches correctly with zero setup.
+  A host with a richer registry passes `previewKind` explicitly.
+- `MediaViewerSource` has two lanes: `{kind:"ref"}` (everything through the
+  MediaClient) and `{kind:"blob"}` (bytes the host already downloaded — proven
+  by test to make **zero** client calls).
+- The markup viewers take OPTIONAL `markupControls`; a host control rail drives
+  mode / viewport / reload, and without one the viewer draws its own toolbar
+  and is fully capable (the original hard-wired itself to an app context).
+- **Why `CodeViewer` ships without a highlighter** (C8, the diff-package Monaco
+  precedent): Prism is a ~150KB browser-only engine and a headless consumer
+  must not carry it. The package ships monospace, line-numbered, wrap-toggling,
+  copyable, truncation-honest code — everything but colour — and the engine
+  rides `registerMediaCodeHighlighter`. That default announces nothing because
+  nothing failed.
+- **`HtmlViewer`'s sandbox is non-configurable**: `allow-scripts allow-popups
+  allow-forms`, never `allow-same-origin`, plus `referrerPolicy="no-referrer"`.
+  One wrong token is a real XSS against the host origin, so hosts do not get a
+  knob. Asserted in the source suite AND on the packed artifact.
+
+### Defects fixed in the port (never silently — C22)
+
+- **A user-visible debug artifact is gone.** `GenericPreview` shipped a
+  fuchsia `ring-2` and a "GenericPreview" corner badge — a layering-debug
+  visualization commented "Rip this out when done" — to every user opening an
+  unpreviewable file. The package has no debug chrome.
+- **`blob.text()` is no longer assumed.** All four absorbed text-reading
+  previewers called it directly; it does not exist in Safari < 14, older
+  WebViews (the Tauri shell's floor), or jsdom, and the failure surfaced to the
+  user as `blob.text is not a function` — as though the FILE were broken.
+  `readBlobText` falls back through `arrayBuffer()` and `FileReader`.
+- **`formatFileSize`** — see Consumer action above.
+- **Four copies of the read-cap-truncate-report machinery became one**
+  (`useViewerText`), as did the error card, skeleton and copy button.
+
+### Gate
+
+`pnpm typecheck && pnpm test && pnpm check:package` green: 125 tests
+(14 new C23 tests across three targets — the announcing default incl. its
+falsifiability leg, the built-in bodies unregistered, and dispatch with zero
+host configuration), publint, attw node16, and a tarball canary extended with
+the `/next` no-cast `MediaHostPorts` assignment, the `/viewers` ESM+CJS export
+and render legs, the packed-artifact sandbox assertion, and the viewer-registry
+dual-graph proof. `/next` is not loaded in the bare-node ESM leg by design:
+Next publishes `next/image` extensionless with no `exports` map, so only
+bundlers and TypeScript resolve it — it is proven via attw, the type canary,
+and a real `require()` in the CJS leg.
+
+### Deliberately NOT absorbed (recorded, not forgotten)
+
+- **The PDF viewer tree** (`matrx-frontend/features/pdf`, 49 files): PDF.js +
+  annotation layer + document scanner + surface registry + server-side
+  extraction API. It is a FEATURE, not a viewer body, and it rides the
+  `registerMediaViewer("pdf", …)` seam.
+- **Markdown / spreadsheet / Office viewers**: remark+rehype+KaTeX, SheetJS +
+  PapaParse, and a server extraction endpoint respectively — heavy engines or
+  host-server-coupled. Same seam.
+- **Image / video / audio viewers**: they bind host domain systems (a
+  zoom/rotate control rail, the unified playback-session registry, a
+  design-system slider). They already consume `/core`; absorbing their bodies
+  is the next wave, not this one.
+
+## 0.3.0 — 2026-08-30
+
+**A terminal media failure can never be silent again.** Born from the
+2026-08-30 outage: server-side cookie-secret drift killed every private image
+on prod, the honest "unavailable" panel rendered — and nothing reached the
+host's error system, because the package had no diagnostics port and the host
+cannot capture what it never learns about. Per ruling C22 the capture logic
+now lives IN the package. Additive; no default behavior changes for renders.
+
+- **New `diagnostics` port on `MediaHostPorts`** —
+  `diagnostics?: { capture?: (info: MediaFailureInfo) => void }`.
+  `MediaFailureInfo` is strictly typed: `source: "media"`, a
+  `phase` (`"resolve" | "session" | "blob" | "element-load" | "recovery"`),
+  a durable `mediaRef` identity (file id / query-stripped URL key — NEVER a
+  signed URL), `status?` when known, a typed `retryOutcome?`, `terminal`,
+  and `message`. **Absent port → the package `console.error`s the same
+  structured payload** (the loud default) — never fully silent. A throwing
+  sink also falls back to the console.
+- **Every terminal failure path emits exactly one capture**, latched per
+  media identity (no spam across re-renders, remounts, or the panel
+  backstop): a throwing `resolve()` (phase `resolve`), a `getBlob()`
+  rejection (phase `blob`, with the structural HTTP status when the error
+  carries one), a rejecting `recoverLoadError` (phase `session`,
+  `recovery-failed`), a terminal verdict after the ONE granted retry (phase
+  `element-load`, `retried`), a terminal verdict on the first attempt (phase
+  `recovery`, `not-attempted`), an unrecoverable element failure (phase
+  `element-load`, `not-attempted`) — plus the unavailable panel mount as a
+  latch-deduped BACKSTOP (if the panel is on screen and no path captured,
+  the mount screams).
+- **`MediaClient.recoverLoadError` may now return a structured
+  `MediaRecoveryReport`** (`{ verdict, status?, secretSource? }`) alongside
+  the still-fully-supported bare `"retry" | "terminal"` strings — a widening,
+  zero change required in any implementation. When the client forwards the
+  `/files/session` mint's `secret_source` and it is `"ephemeral"`, the
+  package captures ONE app-wide non-terminal warning ("server cookie secret
+  is ephemeral — private renders will break across restarts/instances") the
+  moment it is seen — before the outage, not after. The field is tolerated
+  absent.
+- New `/core` exports: `useMediaFailureCapture`, `emitMediaFailure`,
+  `failureMediaIdentity`, `resetMediaFailureLatch` (tests + auth boundaries).
+  Root types: `MediaFailureInfo`, `MediaFailurePhase`, `MediaRetryOutcome`,
+  `MediaDiagnosticsPort`, `MediaRecoveryVerdict`, `MediaRecoveryReport`.
+- `useMediaLoadRecovery` gains an optional `failureRef` option so failures
+  are reported against the durable ref identity instead of the (stripped)
+  URL; `InlineMediaRef`/`MediaThumbnail` pass it automatically.
+
+**Consumer action:** bind the port —
+`ports.diagnostics = { capture: (info) => yourErrorCapture(info) }` on the
+object passed to `MediaProvider`/`MediaHostPorts` (matrx-frontend: wire to
+`captureError` in `lib/diagnostics/errorCaptureStore`). Without the binding
+you get loud console.error diagnostics; with it, failures land in your error
+system. Clients implementing `MediaClient` SHOULD start returning
+`MediaRecoveryReport` from `recoverLoadError` with the mint's
+`secret_source` when the server sends one.
+
 ## 0.2.3 — 2026-08-30
 
 - `@ai-matrx/associations` is now a REAL dependency (`^0.5.2`) instead of an

package/README.md

@@ -124,6 +124,85 @@ automatically (it brings `@ai-matrx/design-system` with it). Nothing extra to
 resolve; association affordances still degrade to absent at runtime when no
 `AssociationsProvider` wraps the tree. The other entries never touch it.
 
+### Diagnostics — a terminal failure is never silent
+
+Every dead render (a refused `resolve()`, failed private-pixel bytes, a load
+error the ONE recovery retry couldn't fix, a failed session mint) emits
+exactly one strictly-typed `MediaFailureInfo` — `phase`, durable `mediaRef`
+identity (never a signed URL), `status?`, `retryOutcome?`, `terminal`,
+`message` — latched per media identity so re-renders never spam. Bind the
+sink to your error system:
+
+```tsx
+<MediaProvider
+  client={client}
+  ports={{ diagnostics: { capture: (info) => myErrorCapture(info) } }}
+>
+```
+
+Without a bound sink the package `console.error`s the same payload — loud by
+default, never silent. If your `MediaClient.recoverLoadError` returns a
+`MediaRecoveryReport` carrying the session mint's
+`secret_source: "ephemeral"`, the package immediately captures an app-wide
+warning that private renders will break across server restarts/instances.
+
+## File viewers (`/viewers`)
+
+Full-pane rendering of ONE file — a preview pane, a file tab, a code editor's
+binary-file fallback. `MediaFileViewer` dispatches on the file kind and ships
+working bodies for text, code, SVG, HTML and unknown files.
+
+```tsx
+import { MediaFileViewer } from "@ai-matrx/media/viewers";
+
+<MediaFileViewer
+  source={{ kind: "ref", ref: { file_id } }}
+  fileName={file.name}
+  fileSize={file.size}
+  generic={{ onDownload }}
+/>;
+```
+
+Kinds whose rendering IS a heavy browser-only engine — PDF, Markdown,
+spreadsheets, Office documents — are yours to register, so a consumer that only
+shows text files never carries a PDF engine:
+
+```tsx
+import { registerMediaViewer, registerMediaCodeHighlighter } from "@ai-matrx/media/viewers";
+
+registerMediaViewer("pdf", MyPdfViewer);          // gets MediaViewerProps
+registerMediaCodeHighlighter(MyPrismHighlighter); // optional: colour for code
+```
+
+Until you register one, that kind renders an **announcing default**: it names
+the missing engine and the remedy and still offers download / view-as-text. It
+is never a blank pane. (Code is different: with no highlighter registered it
+renders complete — monospace, line-numbered, copyable — just without colour,
+so it announces nothing.)
+
+Registering a kind the package already renders replaces the built-in, which is
+how you plug in a domain-specific viewer of your own.
+
+The `blob` source lane (`{ kind: "blob", blob, url }`) renders bytes you
+already have without touching the `MediaClient` at all.
+
+## Next.js (`/next`)
+
+The `ImageComponent` port, implemented over `next/image` so you never write
+that wrapper again. `next` is an optional peer — nothing installs it for you,
+and no other entry imports it.
+
+```tsx
+import { NextMediaImage } from "@ai-matrx/media/next";
+
+const ports: MediaHostPorts = { ImageComponent: NextMediaImage };
+// or: createNextMediaImageComponent({ unoptimized: false, quality: 90 })
+```
+
+It defaults to `unoptimized`, which is correct for Matrx media: durable file
+URLs are session-cookie authenticated and Next's optimizer fetches them from
+the server, where there is no user session.
+
 ## Styling
 
 `/react` uses Tailwind utility classes with semantic tokens (`bg-muted`,
@@ -135,9 +214,9 @@ resolve; association affordances still degrade to absent at runtime when no
 
 ## SSR / RSC
 
-The root entry is server-safe (types + one pure function). `/core`, `/react`
-and `/share` are client modules (`"use client"` is stamped per entry).
-Nothing touches `window` at import time.
+The root entry is server-safe (types + one pure function). `/core`, `/react`,
+`/share`, `/viewers` and `/next` are client modules (`"use client"` is stamped
+per entry). Nothing touches `window` at import time.
 
 ## License
 

package/dist/core.cjs

@@ -22,12 +22,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var core_exports = {};
 __export(core_exports, {
   MediaProvider: () => MediaProvider,
+  emitMediaFailure: () => emitMediaFailure,
+  failureMediaIdentity: () => failureMediaIdentity,
   getFileKindDetails: () => getFileKindDetails,
   getFolderKindDetails: () => getFolderKindDetails,
+  resetMediaFailureLatch: () => resetMediaFailureLatch,
   stableRefKey: () => stableRefKey,
   useMediaActions: () => useMediaActions,
   useMediaBlob: () => useMediaBlob,
   useMediaClient: () => useMediaClient,
+  useMediaFailureCapture: () => useMediaFailureCapture,
   useMediaHostPorts: () => useMediaHostPorts,
   useMediaLoadRecovery: () => useMediaLoadRecovery,
   useMediaResolution: () => useMediaResolution,
@@ -82,29 +86,107 @@ function stableRefKey(ref) {
   return "<empty-ref>";
 }
 
-// src/core/use-media-resolution.ts
+// src/core/diagnostics.ts
 var import_react2 = require("react");
+var LATCH_SLOT = /* @__PURE__ */ Symbol.for("ai-matrx.media.failure-latch");
+function latch() {
+  const host = globalThis;
+  host[LATCH_SLOT] ??= /* @__PURE__ */ new Set();
+  return host[LATCH_SLOT];
+}
+function resetMediaFailureLatch() {
+  latch().clear();
+}
+function failureMediaIdentity(ref, src) {
+  if (ref && typeof ref === "object" && ref.file_id) return `file:${ref.file_id}`;
+  const raw = typeof ref === "string" ? ref : (ref && typeof ref === "object" ? ref.url ?? null : null) ?? src ?? null;
+  if (!raw) return "<unknown-media>";
+  if (raw.startsWith("blob:")) return "blob:object-url";
+  try {
+    const u = new URL(raw);
+    return `url:${u.origin}${u.pathname}`;
+  } catch {
+    const clean = raw.split(/[?#]/, 1)[0] ?? raw;
+    return `ref:${clean}`;
+  }
+}
+function emitMediaFailure(capture, info) {
+  const key = `${info.terminal ? "terminal" : "warning"}|${info.mediaRef}`;
+  const seen = latch();
+  if (seen.has(key)) return;
+  seen.add(key);
+  if (capture) {
+    try {
+      capture(info);
+      return;
+    } catch {
+    }
+  }
+  console.error(
+    "[@ai-matrx/media] media failure (no diagnostics sink captured it \u2014 bind MediaHostPorts.diagnostics.capture to your error system)",
+    info
+  );
+}
+function useMediaFailureCapture() {
+  const ports = useMediaHostPorts();
+  const capture = ports.diagnostics?.capture;
+  const captureRef = (0, import_react2.useRef)(capture);
+  captureRef.current = capture;
+  return (0, import_react2.useCallback)((info) => {
+    emitMediaFailure(captureRef.current, { source: "media", ...info });
+  }, []);
+}
+
+// src/core/use-media-resolution.ts
+var import_react3 = require("react");
 function useMediaResolution(ref) {
   const client = useMediaClient();
+  const capture = useMediaFailureCapture();
   const refKey = stableRefKey(ref);
-  return (0, import_react2.useMemo)(() => {
-    if (!ref) return { resolution: null, status: "empty", reason: null };
+  const { state, failureMessage } = (0, import_react3.useMemo)(() => {
+    if (!ref) {
+      return {
+        state: { resolution: null, status: "empty", reason: null },
+        failureMessage: null
+      };
+    }
     try {
       const resolution = client.resolve(ref);
-      if (!resolution) return { resolution: null, status: "empty", reason: null };
-      return { resolution, status: "ready", reason: null };
+      if (!resolution) {
+        return {
+          state: { resolution: null, status: "empty", reason: null },
+          failureMessage: null
+        };
+      }
+      return {
+        state: { resolution, status: "ready", reason: null },
+        failureMessage: null
+      };
     } catch (err) {
       return {
-        resolution: null,
-        status: "unavailable",
-        reason: client.classifyError(err)
+        state: {
+          resolution: null,
+          status: "unavailable",
+          reason: client.classifyError(err)
+        },
+        failureMessage: err instanceof Error ? err.message : String(err ?? "resolve() failed")
       };
     }
   }, [client, refKey]);
+  (0, import_react3.useEffect)(() => {
+    if (state.status !== "unavailable") return;
+    capture({
+      phase: "resolve",
+      mediaRef: failureMediaIdentity(ref ?? null),
+      terminal: true,
+      message: `resolve() refused (${state.reason ?? "unknown"}): ${failureMessage ?? "no error message"}`
+    });
+  }, [refKey, state.status]);
+  return state;
 }
 
 // src/core/use-media-load-recovery.ts
-var import_react3 = require("react");
+var import_react4 = require("react");
 
 // src/types.ts
 function mintDurableSrc(url) {
@@ -112,26 +194,51 @@ function mintDurableSrc(url) {
 }
 
 // src/core/use-media-load-recovery.ts
+function normalizeOutcome(outcome) {
+  return typeof outcome === "string" ? { verdict: outcome } : outcome;
+}
+var EPHEMERAL_SECRET_IDENTITY = "server:files-session-secret";
 function useMediaLoadRecovery(src, options) {
   const client = useMediaClient();
+  const capture = useMediaFailureCapture();
   const recoverable = options?.recoverable !== false;
   const onTerminal = options?.onTerminal;
-  const [result, setResult] = (0, import_react3.useState)({ source: src, retryKey: 0, failed: false });
-  const attemptRef = (0, import_react3.useRef)(0);
-  (0, import_react3.useEffect)(() => {
+  const failureRef = options?.failureRef;
+  const [result, setResult] = (0, import_react4.useState)({ source: src, retryKey: 0, failed: false });
+  const attemptRef = (0, import_react4.useRef)(0);
+  (0, import_react4.useEffect)(() => {
     attemptRef.current = 0;
   }, [src]);
+  const identity = () => failureMediaIdentity(failureRef ?? null, src);
   const onLoadError = (event) => {
     if (!src || !recoverable) {
       setResult({ source: src, retryKey: 0, failed: true });
+      if (src) {
+        capture({
+          phase: "element-load",
+          mediaRef: identity(),
+          terminal: true,
+          retryOutcome: "not-attempted",
+          message: "media element failed to load and the source is unrecoverable (foreign/object URL \u2014 a session refresh cannot fix it)"
+        });
+      }
       onTerminal?.(event);
       return;
     }
     attemptRef.current += 1;
     const attempt = attemptRef.current;
     client.recoverLoadError(mintDurableSrc(src), attempt).then(
-      (verdict) => {
-        if (verdict === "retry") {
+      (outcome) => {
+        const report = normalizeOutcome(outcome);
+        if (report.secretSource === "ephemeral") {
+          capture({
+            phase: "session",
+            mediaRef: EPHEMERAL_SECRET_IDENTITY,
+            terminal: false,
+            message: "server cookie secret is ephemeral \u2014 private renders will break across restarts/instances (set a persistent files-session secret on the server)"
+          });
+        }
+        if (report.verdict === "retry") {
           setResult((current) => ({
             source: src,
             retryKey: current.source === src ? current.retryKey + 1 : 1,
@@ -139,11 +246,26 @@ function useMediaLoadRecovery(src, options) {
           }));
         } else {
           setResult({ source: src, retryKey: 0, failed: true });
+          capture({
+            phase: attempt > 1 ? "element-load" : "recovery",
+            mediaRef: identity(),
+            terminal: true,
+            retryOutcome: attempt > 1 ? "retried" : "not-attempted",
+            message: attempt > 1 ? "media element failed to load after the session-refresh retry" : "media load recovery declined on the first attempt (session refresh did not produce a usable session)",
+            ...report.status !== void 0 ? { status: report.status } : {}
+          });
           onTerminal?.(event);
         }
       },
-      () => {
+      (err) => {
         setResult({ source: src, retryKey: 0, failed: true });
+        capture({
+          phase: "session",
+          mediaRef: identity(),
+          terminal: true,
+          retryOutcome: "recovery-failed",
+          message: `session recovery failed: ${err instanceof Error ? err.message : String(err ?? "unknown error")}`
+        });
         onTerminal?.(event);
       }
     );
@@ -156,13 +278,21 @@ function useMediaLoadRecovery(src, options) {
 }
 
 // src/core/use-media-blob.ts
-var import_react4 = require("react");
+var import_react5 = require("react");
+function statusOf(err) {
+  if (err && typeof err === "object") {
+    const candidate = err.status ?? err.statusCode;
+    if (typeof candidate === "number") return candidate;
+  }
+  return void 0;
+}
 function useMediaBlob(ref) {
   const client = useMediaClient();
+  const capture = useMediaFailureCapture();
   const refKey = stableRefKey(ref);
-  const [state, setState] = (0, import_react4.useState)({ url: null, blob: null, loading: !!ref, error: null });
-  const [retryToken, setRetryToken] = (0, import_react4.useState)(0);
-  (0, import_react4.useEffect)(() => {
+  const [state, setState] = (0, import_react5.useState)({ url: null, blob: null, loading: !!ref, error: null });
+  const [retryToken, setRetryToken] = (0, import_react5.useState)(0);
+  (0, import_react5.useEffect)(() => {
     if (!ref) {
       setState({ url: null, blob: null, loading: false, error: null });
       return void 0;
@@ -183,6 +313,14 @@ function useMediaBlob(ref) {
         if (cancelled) return;
         const message = err instanceof Error ? err.message : String(err ?? "Failed to load file");
         setState({ url: null, blob: null, loading: false, error: message });
+        const status = statusOf(err);
+        capture({
+          phase: "blob",
+          mediaRef: failureMediaIdentity(ref),
+          terminal: true,
+          message: `getBlob() failed: ${message}`,
+          ...status !== void 0 ? { status } : {}
+        });
       }
     );
     return () => {
@@ -197,17 +335,17 @@ function useMediaBlob(ref) {
 }
 
 // src/core/use-media-upload.ts
-var import_react5 = require("react");
+var import_react6 = require("react");
 var entrySeq = 0;
 function useMediaUpload() {
   const client = useMediaClient();
-  const [uploading, setUploading] = (0, import_react5.useState)(false);
-  const [progress, setProgress] = (0, import_react5.useState)(null);
-  const [result, setResult] = (0, import_react5.useState)(null);
-  const [error, setError] = (0, import_react5.useState)(null);
-  const [entries, setEntries] = (0, import_react5.useState)([]);
-  const activeCount = (0, import_react5.useRef)(0);
-  const patchEntry = (0, import_react5.useCallback)(
+  const [uploading, setUploading] = (0, import_react6.useState)(false);
+  const [progress, setProgress] = (0, import_react6.useState)(null);
+  const [result, setResult] = (0, import_react6.useState)(null);
+  const [error, setError] = (0, import_react6.useState)(null);
+  const [entries, setEntries] = (0, import_react6.useState)([]);
+  const activeCount = (0, import_react6.useRef)(0);
+  const patchEntry = (0, import_react6.useCallback)(
     (id, patch) => {
       setEntries(
         (current) => current.map((e) => e.id === id ? { ...e, ...patch } : e)
@@ -215,7 +353,7 @@ function useMediaUpload() {
     },
     []
   );
-  const upload = (0, import_react5.useCallback)(
+  const upload = (0, import_react6.useCallback)(
     async (file, opts = {}) => {
       const id = `up-${++entrySeq}`;
       const fileName = opts.fileName ?? (file instanceof File ? file.name : "file");
@@ -269,7 +407,7 @@ function useMediaUpload() {
     },
     [client, patchEntry]
   );
-  const uploadMany = (0, import_react5.useCallback)(
+  const uploadMany = (0, import_react6.useCallback)(
     async (files, opts = {}) => {
       if (client.uploadMany) {
         activeCount.current += 1;
@@ -298,10 +436,10 @@ function useMediaUpload() {
     },
     [client, upload]
   );
-  const clearEntry = (0, import_react5.useCallback)((id) => {
+  const clearEntry = (0, import_react6.useCallback)((id) => {
     setEntries((current) => current.filter((e) => e.id !== id));
   }, []);
-  const reset = (0, import_react5.useCallback)(() => {
+  const reset = (0, import_react6.useCallback)(() => {
     setResult(null);
     setError(null);
     setProgress(null);
@@ -321,12 +459,12 @@ function useMediaUpload() {
 }
 
 // src/core/use-thumbnail-source.ts
-var import_react6 = require("react");
+var import_react7 = require("react");
 function useThumbnailSource(ref, options = {}) {
   const { thumbnailUrl, allowSourceFallback = true } = options;
   const client = useMediaClient();
   const { resolution } = useMediaResolution(ref);
-  const explicitThumb = (0, import_react6.useMemo)(() => {
+  const explicitThumb = (0, import_react7.useMemo)(() => {
     if (!thumbnailUrl) return null;
     try {
       return client.resolve(thumbnailUrl);
@@ -393,19 +531,19 @@ function useThumbnailSource(ref, options = {}) {
 }
 
 // src/core/use-media-actions.ts
-var import_react7 = require("react");
+var import_react8 = require("react");
 function useMediaActions(ref, options = {}) {
   const ports = useMediaHostPorts();
   const { resolution } = useMediaResolution(ref);
-  const [busy, setBusy] = (0, import_react7.useState)(null);
-  const [lastError, setLastError] = (0, import_react7.useState)(null);
+  const [busy, setBusy] = (0, import_react8.useState)(null);
+  const [lastError, setLastError] = (0, import_react8.useState)(null);
   const actions = ports.actions;
   const { fileName, alt } = options;
-  const context = (0, import_react7.useMemo)(() => {
+  const context = (0, import_react8.useMemo)(() => {
     if (!ref) return null;
     return { ref, resolution, fileName, alt };
   }, [ref, resolution, fileName, alt]);
-  const isAvailable = (0, import_react7.useCallback)(
+  const isAvailable = (0, import_react8.useCallback)(
     (kind) => {
       if (!context || !actions) return false;
       if (kind === "share") return Boolean(actions.share || actions.SharePopover);
@@ -413,7 +551,7 @@ function useMediaActions(ref, options = {}) {
     },
     [context, actions]
   );
-  const run = (0, import_react7.useCallback)(
+  const run = (0, import_react8.useCallback)(
     async (kind) => {
       if (!context || !actions) return;
       const handler = actions[kind];