@ai-matrx/media 0.2.2 → 0.3.0

package/dist/react.js

@@ -465,9 +465,10 @@ function FileIcon2({
 
 // src/react/inline-media-ref.tsx
 import {
-  useCallback,
+  useCallback as useCallback2,
+  useEffect as useEffect4,
   useMemo as useMemo2,
-  useRef as useRef2,
+  useRef as useRef3,
   useState as useState3
 } from "react";
 
@@ -503,6 +504,54 @@ function useMediaHostPorts() {
   return useContext(portsContext());
 }
 
+// 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 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-blob.ts
 import { useEffect, useState } from "react";
 
@@ -516,8 +565,16 @@ function stableRefKey(ref) {
 }
 
 // src/core/use-media-blob.ts
+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] = useState({ url: null, blob: null, loading: !!ref, error: null });
   const [retryToken, setRetryToken] = useState(0);
@@ -542,6 +599,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 () => {
@@ -556,7 +621,7 @@ function useMediaBlob(ref) {
 }
 
 // src/core/use-media-load-recovery.ts
-import { useEffect as useEffect2, useRef, useState as useState2 } from "react";
+import { useEffect as useEffect2, useRef as useRef2, useState as useState2 } from "react";
 
 // src/types.ts
 function mintDurableSrc(url) {
@@ -564,26 +629,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] = useState2({ source: src, retryKey: 0, failed: false });
-  const attemptRef = useRef(0);
+  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,
@@ -591,11 +681,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);
       }
     );
@@ -608,24 +713,51 @@ function useMediaLoadRecovery(src, options) {
 }
 
 // src/core/use-media-resolution.ts
-import { useMemo } from "react";
+import { useEffect as useEffect3, 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]);
+  useEffect3(() => {
+    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/react/inline-media-ref.tsx
@@ -671,7 +803,7 @@ function prettifyUrl(url) {
 }
 var INERT_PLAYBACK = {
   useMediaElementSink(forward) {
-    return useCallback(
+    return useCallback2(
       (node) => {
         if (!forward) return;
         if (typeof forward === "function") forward(node);
@@ -715,10 +847,21 @@ function InformativeErrorFallback({
   alt,
   elementType,
   mediaRef,
+  failurePhase,
   dimensions,
   rounded,
   className
 }) {
+  const capture = useMediaFailureCapture();
+  const identity = failureMediaIdentity(mediaRef ?? null, url);
+  useEffect4(() => {
+    capture({
+      phase: failurePhase,
+      mediaRef: identity,
+      terminal: true,
+      message: `media unavailable panel rendered for ${elementType} (${failurePhase} failure)`
+    });
+  }, [identity, failurePhase]);
   const shortAxis = dimensions === "fill" ? Number.POSITIVE_INFINITY : Math.min(dimensions.width, dimensions.height);
   const isCompact = dimensions !== "fill" && shortAxis < 64;
   const isMidsize = shortAxis < 140;
@@ -778,7 +921,7 @@ function InformativeErrorPanel({
   const [copied, setCopied] = useState3(false);
   const isFill = dimensions === "fill";
   const { host, tail } = prettifyUrl(url);
-  const handleCopy = useCallback(
+  const handleCopy = useCallback2(
     (event) => {
       event.stopPropagation();
       event.preventDefault();
@@ -897,12 +1040,13 @@ function InlineMediaRef({
   const url = needsBlob ? blob.url : resolution?.src ?? null;
   const recovery = useMediaLoadRecovery(url, {
     recoverable: !needsBlob && resolution?.recoverable !== false,
+    failureRef: mediaRef,
     onTerminal: (event) => onError?.(
       event
     )
   });
   const playback = ports.playbackSession ?? INERT_PLAYBACK;
-  const sessionElRef = useRef2(null);
+  const sessionElRef = useRef3(null);
   const [isMediaPlaying, setIsMediaPlaying] = useState3(false);
   const portSinkRef = playback.useMediaElementSink(
     mediaElementRef
@@ -949,6 +1093,7 @@ function InlineMediaRef({
             alt,
             elementType,
             mediaRef,
+            failurePhase: status === "unavailable" ? "resolve" : "blob",
             dimensions,
             rounded,
             className
@@ -1003,6 +1148,7 @@ function InlineMediaRef({
           alt,
           elementType,
           mediaRef,
+          failurePhase: "element-load",
           dimensions,
           rounded,
           className
@@ -1129,7 +1275,7 @@ function InlineMediaRef({
 }
 
 // src/react/media-thumbnail.tsx
-import { useEffect as useEffect3, useRef as useRef3 } from "react";
+import { useEffect as useEffect5, useRef as useRef4 } from "react";
 
 // src/core/use-thumbnail-source.ts
 import { useMemo as useMemo3 } from "react";
@@ -1227,6 +1373,7 @@ function MediaThumbnail({
         VideoPosterThumb,
         {
           url: source.src,
+          mediaRef,
           recoverable: source.recoverable,
           fallback
         }
@@ -1237,6 +1384,7 @@ function MediaThumbnail({
         {
           url: source.src,
           alt: fileName,
+          mediaRef,
           recoverable: source.recoverable,
           fallback
         }
@@ -1254,11 +1402,13 @@ function MediaThumbnail({
 function ImageThumb({
   url,
   alt,
+  mediaRef,
   recoverable,
   fallback
 }) {
   const { retryKey, onLoadError, failed } = useMediaLoadRecovery(url, {
-    recoverable
+    recoverable,
+    failureRef: mediaRef
   });
   if (failed) return /* @__PURE__ */ jsx4(Fragment2, { children: fallback });
   return /* @__PURE__ */ jsx4(
@@ -1275,14 +1425,16 @@ function ImageThumb({
 }
 function VideoPosterThumb({
   url,
+  mediaRef,
   recoverable,
   fallback
 }) {
   const { retryKey, onLoadError, failed } = useMediaLoadRecovery(url, {
-    recoverable
+    recoverable,
+    failureRef: mediaRef
   });
-  const ref = useRef3(null);
-  useEffect3(() => {
+  const ref = useRef4(null);
+  useEffect5(() => {
     const v = ref.current;
     if (!v) return void 0;
     const onMeta = () => {
@@ -1312,10 +1464,10 @@ function VideoPosterThumb({
 
 // src/react/use-media-dropzone.ts
 import {
-  useCallback as useCallback2,
-  useEffect as useEffect4,
+  useCallback as useCallback3,
+  useEffect as useEffect6,
   useMemo as useMemo4,
-  useRef as useRef4,
+  useRef as useRef5,
   useState as useState4
 } from "react";
 function matchesAccept(file, accept) {
@@ -1343,14 +1495,14 @@ function useMediaDropzone(options) {
   } = options;
   const [isDragActive, setIsDragActive] = useState4(false);
   const [pasteHighlight, setPasteHighlight] = useState4(false);
-  const dragDepth = useRef4(0);
-  const inputRef = useRef4(null);
-  const onFilesRef = useRef4(onFiles);
+  const dragDepth = useRef5(0);
+  const inputRef = useRef5(null);
+  const onFilesRef = useRef5(onFiles);
   onFilesRef.current = onFiles;
-  const onRejectedRef = useRef4(onRejected);
+  const onRejectedRef = useRef5(onRejected);
   onRejectedRef.current = onRejected;
   const acceptKey = accept?.join(",") ?? "";
-  const filterFiles = useCallback2(
+  const filterFiles = useCallback3(
     (files) => {
       const accepted = [];
       const rejected = [];
@@ -1368,23 +1520,23 @@ function useMediaDropzone(options) {
     },
     [acceptKey, maxSize]
   );
-  const emit = useCallback2(
+  const emit = useCallback3(
     (files) => {
       const accepted = filterFiles(files);
       if (accepted.length) onFilesRef.current(accepted);
     },
     [filterFiles]
   );
-  const openPicker = useCallback2(() => {
+  const openPicker = useCallback3(() => {
     if (!disabled) inputRef.current?.click();
   }, [disabled]);
-  useEffect4(() => {
+  useEffect6(() => {
     if (!pickerEventName || typeof window === "undefined") return void 0;
     const handler = () => openPicker();
     window.addEventListener(pickerEventName, handler);
     return () => window.removeEventListener(pickerEventName, handler);
   }, [openPicker, pickerEventName]);
-  useEffect4(() => {
+  useEffect6(() => {
     if (!enablePaste || disabled || typeof window === "undefined") {
       return void 0;
     }
@@ -1410,7 +1562,7 @@ function useMediaDropzone(options) {
     window.addEventListener("paste", handler);
     return () => window.removeEventListener("paste", handler);
   }, [enablePaste, disabled, emit]);
-  const getRootProps = useCallback2(
+  const getRootProps = useCallback3(
     () => ({
       onDragEnter: (event) => {
         if (disabled) return;
@@ -1443,7 +1595,7 @@ function useMediaDropzone(options) {
     () => acceptKey.length ? acceptKey : void 0,
     [acceptKey]
   );
-  const getInputProps = useCallback2(
+  const getInputProps = useCallback3(
     () => ({
       ref: (node) => {
         inputRef.current = node;
@@ -1465,10 +1617,10 @@ function useMediaDropzone(options) {
 }
 
 // src/react/file-upload-dropzone.tsx
-import { useCallback as useCallback4 } from "react";
+import { useCallback as useCallback5 } from "react";
 
 // src/core/use-media-upload.ts
-import { useCallback as useCallback3, useRef as useRef5, useState as useState5 } from "react";
+import { useCallback as useCallback4, useRef as useRef6, useState as useState5 } from "react";
 var entrySeq = 0;
 function useMediaUpload() {
   const client = useMediaClient();
@@ -1477,8 +1629,8 @@ function useMediaUpload() {
   const [result, setResult] = useState5(null);
   const [error, setError] = useState5(null);
   const [entries, setEntries] = useState5([]);
-  const activeCount = useRef5(0);
-  const patchEntry = useCallback3(
+  const activeCount = useRef6(0);
+  const patchEntry = useCallback4(
     (id, patch) => {
       setEntries(
         (current) => current.map((e) => e.id === id ? { ...e, ...patch } : e)
@@ -1486,7 +1638,7 @@ function useMediaUpload() {
     },
     []
   );
-  const upload = useCallback3(
+  const upload = useCallback4(
     async (file, opts = {}) => {
       const id = `up-${++entrySeq}`;
       const fileName = opts.fileName ?? (file instanceof File ? file.name : "file");
@@ -1540,7 +1692,7 @@ function useMediaUpload() {
     },
     [client, patchEntry]
   );
-  const uploadMany = useCallback3(
+  const uploadMany = useCallback4(
     async (files, opts = {}) => {
       if (client.uploadMany) {
         activeCount.current += 1;
@@ -1569,10 +1721,10 @@ function useMediaUpload() {
     },
     [client, upload]
   );
-  const clearEntry = useCallback3((id) => {
+  const clearEntry = useCallback4((id) => {
     setEntries((current) => current.filter((e) => e.id !== id));
   }, []);
-  const reset = useCallback3(() => {
+  const reset = useCallback4(() => {
     setResult(null);
     setError(null);
     setProgress(null);
@@ -1592,7 +1744,7 @@ function useMediaUpload() {
 }
 
 // src/react/upload-progress-list.tsx
-import { memo, useEffect as useEffect5, useRef as useRef6, useState as useState6 } from "react";
+import { memo, useEffect as useEffect7, useRef as useRef7, useState as useState6 } from "react";
 import { jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
 var AUTO_DISMISS_MS = 1e4;
 function formatFileSize(bytes) {
@@ -1617,12 +1769,12 @@ function UploadProgressListImpl({
   const activeCount = uploads.filter((u) => u.status === "uploading").length;
   const successCount = uploads.filter((u) => u.status === "success").length;
   const errorCount = uploads.filter((u) => u.status === "error").length;
-  const timersRef = useRef6(
+  const timersRef = useRef7(
     /* @__PURE__ */ new Map()
   );
-  const onDismissRef = useRef6(onDismiss);
+  const onDismissRef = useRef7(onDismiss);
   onDismissRef.current = onDismiss;
-  useEffect5(() => {
+  useEffect7(() => {
     const timers = timersRef.current;
     if (hovered) {
       timers.forEach((t) => clearTimeout(t));
@@ -1650,7 +1802,7 @@ function UploadProgressListImpl({
       }
     }
   }, [uploads, hovered]);
-  useEffect5(() => {
+  useEffect7(() => {
     const timers = timersRef.current;
     return () => {
       timers.forEach((t) => clearTimeout(t));
@@ -1782,7 +1934,7 @@ function FileUploadDropzone({
   pickerEventName
 }) {
   const { uploadMany, entries, clearEntry } = useMediaUpload();
-  const handleUpload = useCallback4(
+  const handleUpload = useCallback5(
     async (files) => {
       if (!files.length) return;
       try {
@@ -1892,7 +2044,7 @@ function FileUploadDropzone({
 import { useState as useState8 } from "react";
 
 // src/core/use-media-actions.ts
-import { useCallback as useCallback5, useMemo as useMemo5, useState as useState7 } from "react";
+import { useCallback as useCallback6, useMemo as useMemo5, useState as useState7 } from "react";
 function useMediaActions(ref, options = {}) {
   const ports = useMediaHostPorts();
   const { resolution } = useMediaResolution(ref);
@@ -1904,7 +2056,7 @@ function useMediaActions(ref, options = {}) {
     if (!ref) return null;
     return { ref, resolution, fileName, alt };
   }, [ref, resolution, fileName, alt]);
-  const isAvailable = useCallback5(
+  const isAvailable = useCallback6(
     (kind) => {
       if (!context || !actions) return false;
       if (kind === "share") return Boolean(actions.share || actions.SharePopover);
@@ -1912,7 +2064,7 @@ function useMediaActions(ref, options = {}) {
     },
     [context, actions]
   );
-  const run = useCallback5(
+  const run = useCallback6(
     async (kind) => {
       if (!context || !actions) return;
       const handler = actions[kind];
@@ -2018,7 +2170,7 @@ function MediaActionToolbar({
 }
 
 // src/react/media-lightbox.tsx
-import { useEffect as useEffect6 } from "react";
+import { useEffect as useEffect8 } from "react";
 import { jsx as jsx8, jsxs as jsxs6 } from "react/jsx-runtime";
 function MediaLightbox({
   open,
@@ -2036,7 +2188,7 @@ function MediaLightbox({
   headerExtra,
   className
 }) {
-  useEffect6(() => {
+  useEffect8(() => {
     if (!open || typeof window === "undefined") return void 0;
     const handler = (event) => {
       if (event.key === "Escape") {