@ai-matrx/media 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @ai-matrx/media
 
+## 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,28 @@ 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.
+
 ## Styling
 
 `/react` uses Tailwind utility classes with semantic tokens (`bg-muted`,

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