@ai-matrx/media 0.2.2 → 0.3.0

package/dist/core.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { MediaClient, MediaHostPorts, MediaRefLike, MediaResolution, MediaUnavailableReason, DurableSrc, MediaActionContext, MediaActionKind, MediaSlotComponent, MediaSharePopoverProps } from './index.js';
+import { MediaClient, MediaHostPorts, MediaRefLike, MediaFailureInfo, MediaResolution, MediaUnavailableReason, DurableSrc, MediaActionContext, MediaActionKind, MediaSlotComponent, MediaSharePopoverProps } from './index.js';
 export { M as MediaUploadEntry, a as MediaUploadEntryStatus, b as MediaUploadProgress, U as UseMediaUploadResult, u as useMediaUpload } from './use-media-upload-Dg2HSvTq.js';
 
 interface MediaProviderProps {
@@ -29,6 +29,58 @@ declare function useMediaHostPorts(): MediaHostPorts;
 
 declare function stableRefKey(ref: MediaRefLike | null | undefined): string;
 
+/**
+ * src/core/diagnostics.ts — the terminal-failure capture machinery.
+ *
+ * Born from the 2026-08-30 prod outage: server-side cookie-secret drift
+ * killed every private image, the package rendered its honest "unavailable"
+ * panel — and nothing reached the host's Error Inspector or error DB,
+ * because the package had no diagnostics port and the host cannot capture
+ * what it never learns about. Per ruling C22 the capture logic lives HERE,
+ * so every consuming repo inherits it.
+ *
+ * The contract:
+ *
+ *   - every terminal failure path emits exactly ONE {@link MediaFailureInfo}
+ *     per media identity (latched — re-renders, remounts and the unavailable
+ *     panel backstop never spam);
+ *   - a bound `MediaHostPorts.diagnostics.capture` receives the payload;
+ *     WITHOUT one (or if it throws) the package `console.error`s the same
+ *     structured payload — the loud default. A media failure is NEVER silent;
+ *   - the payload never carries a signed URL: identity is the file id or a
+ *     query-stripped URL key ({@link failureMediaIdentity}).
+ *
+ * The latch lives on `globalThis` under a `Symbol.for` slot (same reason as
+ * context.ts: with `splitting: false` + dual formats, module-level state
+ * silently duplicates across bundle/loader graphs).
+ */
+
+/**
+ * Clear the once-per-failure latch. For tests, and for hosts at auth
+ * boundaries (a sign-in can genuinely fix a previously-terminal failure, and
+ * a recurrence after it deserves a fresh capture).
+ */
+declare function resetMediaFailureLatch(): void;
+/**
+ * Durable diagnostics identity for a media reference. NEVER a signed URL:
+ * file ids win, and any URL is stripped to origin + path (signatures ride
+ * query strings).
+ */
+declare function failureMediaIdentity(ref: MediaRefLike | null | undefined, src?: string | null): string;
+/**
+ * Emit one media-failure capture through the host sink, or the loud
+ * console.error default when no sink is bound (or the sink throws).
+ * Latched per (terminal|warning, mediaRef) — one capture per failure,
+ * however many renders, hooks, or backstops observe it.
+ */
+declare function emitMediaFailure(capture: ((info: MediaFailureInfo) => void) | undefined, info: MediaFailureInfo): void;
+/**
+ * Hook form: a stable capture function wired to the host ports. Every core
+ * hook and the unavailable-panel backstop route through this — the phase
+ * vocabulary and the latch stay in ONE place.
+ */
+declare function useMediaFailureCapture(): (info: Omit<MediaFailureInfo, "source">) => void;
+
 /**
  * src/core/use-media-resolution.ts — ref → durable resolution, as state.
  *
@@ -36,8 +88,10 @@ declare function stableRefKey(ref: MediaRefLike | null | undefined): string;
  * even a caller-supplied URL string is classified, never trusted. Law 15 of
  * the handler (unavailable is a rendered state): a throwing `resolve()` is
  * classified via `classifyError` and returned as typed state — never
- * re-thrown, never console.error'd here (the client owns loud recovery for
- * unexpected failures via its own diagnostics sink).
+ * re-thrown. It IS however a terminal failure, so it also emits exactly one
+ * `MediaFailureInfo` (phase "resolve") through the diagnostics machinery —
+ * the 2026-08-30 outage rule: an unavailable render is honest to the USER but
+ * must never be silent to the SYSTEM.
  */
 
 interface MediaResolutionState {
@@ -65,6 +119,26 @@ declare function useMediaResolution(ref: MediaRefLike | null | undefined): Media
  * `recoverable: false` resolutions (foreign URLs, blob: object URLs) skip the
  * client and fail straight through — a session refresh can't resurrect
  * someone else's link rot.
+ *
+ * Every terminal outcome emits exactly one `MediaFailureInfo` through the
+ * diagnostics machinery (the 2026-08-30 outage rule):
+ *
+ *   - element error, recovery impossible      → phase "element-load",
+ *                                               retryOutcome "not-attempted"
+ *   - terminal verdict after a granted retry  → phase "element-load",
+ *                                               retryOutcome "retried"
+ *   - terminal verdict on the FIRST attempt   → phase "recovery",
+ *                                               retryOutcome "not-attempted"
+ *     (the recovery machinery itself declined — usually the session mint
+ *     came back unusable)
+ *   - `recoverLoadError` rejected             → phase "session",
+ *                                               retryOutcome "recovery-failed"
+ *
+ * A structured `MediaRecoveryReport` verdict may additionally carry the
+ * `/files/session` mint's `secret_source`; `"ephemeral"` emits a NON-terminal
+ * warning ("private renders will break across restarts/instances") the moment
+ * the client sees it — before the outage, not after. The bare string verdict
+ * stays fully supported; the field is tolerated absent.
  */
 
 interface MediaLoadRecovery {
@@ -82,6 +156,12 @@ declare function useMediaLoadRecovery(src: DurableSrc | string | null, options?:
     recoverable?: boolean | undefined;
     /** Fires once recovery is exhausted, with the original element event. */
     onTerminal?: ((event?: unknown) => void) | undefined;
+    /**
+     * Durable identity of the media being recovered, for diagnostics —
+     * failures are reported against the file id / ref key, never the URL.
+     * Falls back to the query-stripped src when absent.
+     */
+    failureRef?: MediaRefLike | null | undefined;
 }): MediaLoadRecovery;
 
 /**
@@ -211,4 +291,4 @@ declare function getFileKindDetails(fileName: string, mimeType?: string | null):
 /** Folder icon details (open picks the open-folder glyph). */
 declare function getFolderKindDetails(open?: boolean): FileKindDetails;
 
-export { type FileCategory, type FileIconName, type FileKindDetails, type MediaActionsState, type MediaBlobState, type MediaLoadRecovery, MediaProvider, type MediaProviderProps, type MediaResolutionState, type ThumbnailMode, type ThumbnailSourceState, type UseMediaActionsOptions, type UseThumbnailSourceOptions, getFileKindDetails, getFolderKindDetails, stableRefKey, useMediaActions, useMediaBlob, useMediaClient, useMediaHostPorts, useMediaLoadRecovery, useMediaResolution, useThumbnailSource };
+export { type FileCategory, type FileIconName, type FileKindDetails, type MediaActionsState, type MediaBlobState, type MediaLoadRecovery, MediaProvider, type MediaProviderProps, type MediaResolutionState, type ThumbnailMode, type ThumbnailSourceState, type UseMediaActionsOptions, type UseThumbnailSourceOptions, emitMediaFailure, failureMediaIdentity, getFileKindDetails, getFolderKindDetails, resetMediaFailureLatch, stableRefKey, useMediaActions, useMediaBlob, useMediaClient, useMediaFailureCapture, useMediaHostPorts, useMediaLoadRecovery, useMediaResolution, useThumbnailSource };

package/dist/core.js

@@ -50,29 +50,107 @@ function stableRefKey(ref) {
   return "<empty-ref>";
 }
 
+// src/core/diagnostics.ts
+import { useCallback, useRef } from "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 = useRef(capture);
+  captureRef.current = capture;
+  return useCallback((info) => {
+    emitMediaFailure(captureRef.current, { source: "media", ...info });
+  }, []);
+}
+
 // src/core/use-media-resolution.ts
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 function useMediaResolution(ref) {
   const client = useMediaClient();
+  const capture = useMediaFailureCapture();
   const refKey = stableRefKey(ref);
-  return useMemo(() => {
-    if (!ref) return { resolution: null, status: "empty", reason: null };
+  const { state, failureMessage } = 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]);
+  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
-import { useEffect, useRef, useState } from "react";
+import { useEffect as useEffect2, useRef as useRef2, useState } from "react";
 
 // src/types.ts
 function mintDurableSrc(url) {
@@ -80,26 +158,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 failureRef = options?.failureRef;
   const [result, setResult] = useState({ source: src, retryKey: 0, failed: false });
-  const attemptRef = useRef(0);
-  useEffect(() => {
+  const attemptRef = useRef2(0);
+  useEffect2(() => {
     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,
@@ -107,11 +210,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);
       }
     );
@@ -124,13 +242,21 @@ function useMediaLoadRecovery(src, options) {
 }
 
 // src/core/use-media-blob.ts
-import { useEffect as useEffect2, useState as useState2 } from "react";
+import { useEffect as useEffect3, useState as useState2 } from "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] = useState2({ url: null, blob: null, loading: !!ref, error: null });
   const [retryToken, setRetryToken] = useState2(0);
-  useEffect2(() => {
+  useEffect3(() => {
     if (!ref) {
       setState({ url: null, blob: null, loading: false, error: null });
       return void 0;
@@ -151,6 +277,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 () => {
@@ -165,7 +299,7 @@ function useMediaBlob(ref) {
 }
 
 // src/core/use-media-upload.ts
-import { useCallback, useRef as useRef2, useState as useState3 } from "react";
+import { useCallback as useCallback2, useRef as useRef3, useState as useState3 } from "react";
 var entrySeq = 0;
 function useMediaUpload() {
   const client = useMediaClient();
@@ -174,8 +308,8 @@ function useMediaUpload() {
   const [result, setResult] = useState3(null);
   const [error, setError] = useState3(null);
   const [entries, setEntries] = useState3([]);
-  const activeCount = useRef2(0);
-  const patchEntry = useCallback(
+  const activeCount = useRef3(0);
+  const patchEntry = useCallback2(
     (id, patch) => {
       setEntries(
         (current) => current.map((e) => e.id === id ? { ...e, ...patch } : e)
@@ -183,7 +317,7 @@ function useMediaUpload() {
     },
     []
   );
-  const upload = useCallback(
+  const upload = useCallback2(
     async (file, opts = {}) => {
       const id = `up-${++entrySeq}`;
       const fileName = opts.fileName ?? (file instanceof File ? file.name : "file");
@@ -237,7 +371,7 @@ function useMediaUpload() {
     },
     [client, patchEntry]
   );
-  const uploadMany = useCallback(
+  const uploadMany = useCallback2(
     async (files, opts = {}) => {
       if (client.uploadMany) {
         activeCount.current += 1;
@@ -266,10 +400,10 @@ function useMediaUpload() {
     },
     [client, upload]
   );
-  const clearEntry = useCallback((id) => {
+  const clearEntry = useCallback2((id) => {
     setEntries((current) => current.filter((e) => e.id !== id));
   }, []);
-  const reset = useCallback(() => {
+  const reset = useCallback2(() => {
     setResult(null);
     setError(null);
     setProgress(null);
@@ -361,7 +495,7 @@ function useThumbnailSource(ref, options = {}) {
 }
 
 // src/core/use-media-actions.ts
-import { useCallback as useCallback2, useMemo as useMemo3, useState as useState4 } from "react";
+import { useCallback as useCallback3, useMemo as useMemo3, useState as useState4 } from "react";
 function useMediaActions(ref, options = {}) {
   const ports = useMediaHostPorts();
   const { resolution } = useMediaResolution(ref);
@@ -373,7 +507,7 @@ function useMediaActions(ref, options = {}) {
     if (!ref) return null;
     return { ref, resolution, fileName, alt };
   }, [ref, resolution, fileName, alt]);
-  const isAvailable = useCallback2(
+  const isAvailable = useCallback3(
     (kind) => {
       if (!context || !actions) return false;
       if (kind === "share") return Boolean(actions.share || actions.SharePopover);
@@ -381,7 +515,7 @@ function useMediaActions(ref, options = {}) {
     },
     [context, actions]
   );
-  const run = useCallback2(
+  const run = useCallback3(
     async (kind) => {
       if (!context || !actions) return;
       const handler = actions[kind];
@@ -544,12 +678,16 @@ function getFolderKindDetails(open = false) {
 }
 export {
   MediaProvider,
+  emitMediaFailure,
+  failureMediaIdentity,
   getFileKindDetails,
   getFolderKindDetails,
+  resetMediaFailureLatch,
   stableRefKey,
   useMediaActions,
   useMediaBlob,
   useMediaClient,
+  useMediaFailureCapture,
   useMediaHostPorts,
   useMediaLoadRecovery,
   useMediaResolution,