@ai-matrx/media 0.5.12 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @ai-matrx/media
 
+## 0.6.1
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/media/v0.6.0..npm/media/v0.6.1 -- apps/shared/media`).
+No source changes intended and no consumer action required.
+
+## 0.6.0
+
+**The heal ladder — the user is never denied while any lane works, and a
+render that heals itself is logged as loudly as one that dies.**
+
+- `MediaClient.healLoadError?(ref, {src, attempts})` (optional): runs AFTER the
+  ONE retry policy is exhausted; returns `MediaHealResult` — the lanes tried
+  (`MediaHealAttempt[]`: lane, outcome, status, ms, host), the lane that
+  healed (`healedBy`), a NAMED root cause (`MediaHealDiagnosis`, e.g.
+  `cookie-not-sent-by-browser`, `bearer-rejected`, `primary-host-down-alternate-served`)
+  and a plain-English `summary`.
+- `useMediaLoadRecovery` returns `healedSrc` (a `blob:` object URL from the
+  bearer lane) — bind it instead of the dead src. `InlineMediaRef` and the
+  thumbnails do so already.
+- `MediaFailureInfo` gains `healed`, `healedBy`, `attempts`, `diagnosis` and
+  the `"heal"` phase. A healed render captures `terminal: false, healed: true`
+  with the full ladder; hosts MUST persist it like a dead one (matrx-frontend
+  does: `code = "healed:<diagnosis>"`, `durable: true`).
+- Clients without a ladder keep the pre-0.6 phases/messages exactly, with a
+  suffix saying no ladder ran.
+
+Why: 2026-09-16, a private image 401'd twice in Arman's Chrome (third-party
+cookies blocked) and rendered "Image unavailable" while the bearer lane would
+have served it the whole time; the DB row said only "failed after retry".
+
 ## 0.5.12
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/dist/core.cjs

@@ -207,7 +207,7 @@ function useMediaLoadRecovery(src, options) {
   const recoverable = options?.recoverable !== false;
   const onTerminal = options?.onTerminal;
   const failureRef = options?.failureRef;
-  const [result, setResult] = (0, import_react4.useState)({ source: src, retryKey: 0, failed: false });
+  const [result, setResult] = (0, import_react4.useState)({ source: src, retryKey: 0, failed: false, healedSrc: null });
   const attemptRef = (0, import_react4.useRef)(0);
   const recoveryInFlightRef = (0, import_react4.useRef)(false);
   (0, import_react4.useEffect)(() => {
@@ -221,7 +221,7 @@ function useMediaLoadRecovery(src, options) {
   const onLoadError = (event) => {
     if (recoveryInFlightRef.current) return;
     if (!src || !recoverable) {
-      setResult({ source: src, retryKey: 0, failed: true });
+      setResult({ source: src, retryKey: 0, failed: true, healedSrc: null });
       if (src) {
         capture({
           phase: "element-load",
@@ -252,23 +252,90 @@ function useMediaLoadRecovery(src, options) {
           setResult((current) => ({
             source: src,
             retryKey: current.source === src ? current.retryKey + 1 : 1,
-            failed: false
+            failed: false,
+            healedSrc: null
           }));
-        } else {
-          setResult({ source: src, retryKey: 0, failed: true });
+          return;
+        }
+        const lane1 = {
+          lane: "session-refresh-retry",
+          outcome: attempt > 1 ? "http-error" : "unavailable",
+          ms: 0,
+          ...report.status !== void 0 ? { status: report.status } : {},
+          detail: attempt > 1 ? "cookie re-minted, same durable URL retried in the element, element errored again" : "recovery declined on the first attempt (no usable session)"
+        };
+        if (!failureRef || !client.healLoadError) {
+          setResult({ source: src, retryKey: 0, failed: true, healedSrc: null });
           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)",
+            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)") + (failureRef ? " \u2014 no heal ladder on this client (healLoadError not implemented)" : " \u2014 no durable ref supplied, so no heal lane could run"),
             ...report.status !== void 0 ? { status: report.status } : {}
           });
           onTerminal?.(event);
+          return;
         }
+        const heal = client.healLoadError(failureRef, {
+          src: mintDurableSrc(src),
+          attempts: [lane1]
+        });
+        heal.then(
+          (verdict) => {
+            if (verdict.src) {
+              setResult({
+                source: src,
+                retryKey: 0,
+                failed: false,
+                healedSrc: verdict.src
+              });
+              capture({
+                phase: "heal",
+                mediaRef: identity(),
+                terminal: false,
+                healed: true,
+                healedBy: verdict.healedBy,
+                attempts: verdict.attempts,
+                diagnosis: verdict.diagnosis,
+                retryOutcome: "retried",
+                message: `HEALED (${verdict.healedBy ?? "unknown lane"}): ${verdict.summary}`,
+                ...report.status !== void 0 ? { status: report.status } : {}
+              });
+              return;
+            }
+            setResult({ source: src, retryKey: 0, failed: true, healedSrc: null });
+            capture({
+              phase: "heal",
+              mediaRef: identity(),
+              terminal: true,
+              healed: false,
+              attempts: verdict.attempts,
+              diagnosis: verdict.diagnosis,
+              retryOutcome: "retried",
+              message: `DEAD after ${verdict.attempts.length} lane(s): ${verdict.summary}`,
+              ...report.status !== void 0 ? { status: report.status } : {}
+            });
+            onTerminal?.(event);
+          },
+          (err) => {
+            setResult({ source: src, retryKey: 0, failed: true, healedSrc: null });
+            capture({
+              phase: "heal",
+              mediaRef: identity(),
+              terminal: true,
+              healed: false,
+              attempts: [lane1],
+              diagnosis: "unknown",
+              retryOutcome: "recovery-failed",
+              message: `heal ladder threw: ${err instanceof Error ? err.message : String(err ?? "unknown error")}`
+            });
+            onTerminal?.(event);
+          }
+        );
       },
       (err) => {
-        setResult({ source: src, retryKey: 0, failed: true });
+        setResult({ source: src, retryKey: 0, failed: true, healedSrc: null });
         capture({
           phase: "session",
           mediaRef: identity(),
@@ -283,7 +350,8 @@ function useMediaLoadRecovery(src, options) {
   return {
     retryKey: result.source === src ? result.retryKey : 0,
     onLoadError,
-    failed: result.source === src ? result.failed : false
+    failed: result.source === src ? result.failed : false,
+    healedSrc: result.source === src ? result.healedSrc : null
   };
 }