cursedbelt 4.1.0 → 4.3.0

package/src/react/media-gallery/MediaGallery.tsx

@@ -77,6 +77,12 @@ import {
 } from '../hooks/useCheckboxSelection';
 import { DenseGalleryDetail, DenseGalleryShell } from '../media/DenseGalleryShell';
 import { useHlsSource } from '../media/hlsSource';
+import {
+  isRecoverableFault,
+  probeSourceFault,
+  type SourceFault,
+  sourceFaultMessage,
+} from '../media/sourceFault';
 import { HoverScrubVideoThumb } from '../media/HoverScrubVideoThumb';
 import { isPlayPauseSpace } from '../media/playerSpaceKey';
 import {
@@ -218,6 +224,45 @@ function TurnVideoDialog({
   );
 }
 
+/**
+ * The picture editor, over the item's RESOLVED media — never over the raw row.
+ *
+ * 🔴 The same defect as {@link TurnVideoDialog}'s, and the worst of the five to leave in place:
+ * this dialog BAKES pixels. Mounted as `src={item.url ?? ''}` it showed an empty frame on any
+ * app that signs its URLs, with a live-looking row of sliders over it and a Save that could
+ * only write a blank or silently do nothing. The editor now states the reason and holds its
+ * saves (see `PictureEditor`'s `cannotShow`), and the source it is handed is the one
+ * {@link useItemMedia} resolved — `url`, because a picture has no stream and a thumbnail is
+ * the wrong bytes to re-encode.
+ */
+function EditPictureDialog({
+  item,
+  cache,
+  allowReplace,
+  onClose,
+  onSave,
+}: {
+  item: MediaGalleryItem;
+  cache: MediaCache;
+  allowReplace: boolean;
+  onClose: () => void;
+  onSave: (result: PictureEditResult) => void | Promise<void>;
+}) {
+  const { media, resolving } = useItemMedia(item, cache);
+  return (
+    <LazyPictureEditor
+      src={media.url ?? ''}
+      // So an unresolved picture reads as "still finding it" for the moment it takes, rather
+      // than flashing the "cannot show it" reason at somebody whose photograph is on its way.
+      resolving={resolving}
+      fileName={item.name}
+      allowReplace={allowReplace}
+      onClose={onClose}
+      onSave={onSave}
+    />
+  );
+}
+
 // Marking sections of a clip to cut out. Lazy for the usual reason and one extra: an app that
 // has no pipeline to execute a cut list never passes `onTrimVideo`, so it never loads a byte
 // of this — which is what makes "enabled for collections only, for now" a fact about the
@@ -225,12 +270,128 @@ function TurnVideoDialog({
 const LazyVideoCutEditor = React.lazy(() =>
   import('../media/VideoCutEditor').then((m) => ({ default: m.VideoCutEditor })),
 );
+/**
+ * The trim dialog, over the item's RESOLVED media — never over the raw row. Same defect, same
+ * fix and the same shared cache as {@link TurnVideoDialog}, whose header carries the whole
+ * story; what is particular to this one is that marking a cut means scrubbing to a moment, so
+ * a source-less player does not merely look broken, it makes the dialog's one output
+ * unreachable — which is why `VideoCutEditor` now says so rather than painting black.
+ */
+function TrimVideoDialog({
+  item,
+  cache,
+  note,
+  onClose,
+  onSubmit,
+}: {
+  item: MediaGalleryItem;
+  cache: MediaCache;
+  note?: React.ReactNode;
+  onClose: () => void;
+  onSubmit: (cuts: VideoCut[]) => void | Promise<void>;
+}) {
+  const { media, resolving } = useItemMedia(item, cache);
+  // `streamUrl ?? url`, the same preference the stage and the turner make: a plain `url` is not
+  // always a streamable source, and a scrubber given the wrong one cannot seek.
+  const src = media.streamUrl ?? media.url ?? '';
+  const poster = media.posterUrl ?? media.thumbnailUrl;
+  return (
+    <LazyVideoCutEditor
+      src={src}
+      {...(poster ? { posterUrl: poster } : {})}
+      resolving={resolving}
+      name={item.name}
+      durationSeconds={item.durationSeconds ?? null}
+      {...(note ? { note } : {})}
+      onClose={onClose}
+      onSubmit={onSubmit}
+    />
+  );
+}
 // Naming the parts of a clip. The same bargain as the cut editor one line up: an app that has
 // nowhere to PUT a chapter list never passes `onSaveChapters`, so it never loads a byte of
 // this dialog — the capability and the bundle cost turn on together, with no flag between them.
 const LazyVideoChapterEditor = React.lazy(() =>
   import('../media/VideoChapterEditor').then((m) => ({ default: m.VideoChapterEditor })),
 );
+/**
+ * The sections dialog, over the item's RESOLVED media — never over the raw row. Same defect,
+ * same fix and the same shared cache as {@link TurnVideoDialog}; what is particular here is
+ * that a section is metadata stored BESIDE the film, so a clip nobody can play is still a clip
+ * whose existing sections can be renamed, removed and saved — `VideoChapterEditor` says that
+ * in the same breath as it says there is nothing to scrub.
+ */
+function ChapterVideoDialog({
+  item,
+  cache,
+  onClose,
+  onSubmit,
+}: {
+  item: MediaGalleryItem;
+  cache: MediaCache;
+  onClose: () => void;
+  onSubmit: (chapters: VideoChapter[]) => void | Promise<void>;
+}) {
+  const { media, resolving } = useItemMedia(item, cache);
+  const src = media.streamUrl ?? media.url ?? '';
+  const poster = media.posterUrl ?? media.thumbnailUrl;
+  return (
+    <LazyVideoChapterEditor
+      src={src}
+      {...(poster ? { posterUrl: poster } : {})}
+      resolving={resolving}
+      name={item.name}
+      durationSeconds={item.durationSeconds ?? null}
+      {...(item.chapters ? { chapters: item.chapters } : {})}
+      onClose={onClose}
+      onSubmit={onSubmit}
+    />
+  );
+}
+/**
+ * The frame grabber, over the item's RESOLVED media — never over the raw row. Same defect,
+ * same fix and the same shared cache as {@link TurnVideoDialog}; what is particular here is
+ * that every output of that dialog is pixels read back off the `<video>`, so an unresolved
+ * source leaves it with nothing to save at all — which is why `FrameGrabber` now states the
+ * reason and holds its two save buttons rather than offering them over a black frame.
+ *
+ * `hasPoster` is read off the RESOLVED media too: an app that mints its poster URL alongside
+ * its stream would otherwise be told this film has no picture, and the thumbnail button would
+ * offer to "choose" one it is in fact about to replace.
+ */
+function GrabFrameDialog({
+  item,
+  at,
+  cache,
+  onClose,
+  onSaveThumbnail,
+  onSaveSnapshot,
+}: {
+  item: MediaGalleryItem;
+  at: number;
+  cache: MediaCache;
+  onClose: () => void;
+  onSaveThumbnail?: ((poster: Blob) => void | Promise<void>) | undefined;
+  onSaveSnapshot?: ((still: Blob, atSeconds: number) => void | Promise<void>) | undefined;
+}) {
+  const { media, resolving } = useItemMedia(item, cache);
+  const src = media.streamUrl ?? media.url ?? '';
+  return (
+    <LazyFrameGrabber
+      src={src}
+      resolving={resolving}
+      name={item.name}
+      startAt={at}
+      // So the dialog can SAY that saving replaces the picture this film shows now, rather
+      // than overwriting somebody's chosen poster silently — the owner's copy-not-overwrite
+      // ruling applied to the one case in that dialog where a replacement is unavoidable.
+      hasPoster={Boolean(media.posterUrl)}
+      onClose={onClose}
+      {...(onSaveThumbnail ? { onSaveThumbnail } : {})}
+      {...(onSaveSnapshot ? { onSaveSnapshot } : {})}
+    />
+  );
+}
 // Tagging and describing, on one file or on a ticked selection. Same bargain again: an app
 // with nowhere to PUT a tag never passes `onSaveMeta`, so it never loads a byte of this
 // dialog — and the gallery keeps reading whatever tags and descriptions its items already
@@ -800,12 +961,21 @@ function BytesStage({
  * listed here, so the feature was invisible with nothing anywhere reporting a fault. It is a
  * pure function so a test can read it directly; the rendered player is a Vidstack custom
  * element that happy-dom never brings to life, so no DOM assertion can see any of this.
+ *
+ * 🔴 The return type is spelled out rather than imported as `PlayerVideo` from
+ * `../media/VideoPlayer`, and the reason is BYTES, not taste. The player is reached from here
+ * through `React.lazy(() => import(…))` on purpose, and `scripts/styleAreas.ts`'s closure walk
+ * reads STATIC specifiers — an `import type` is one, and tsc erases it long after that walk has
+ * decided. Measured 2026-09-18: naming the type pulled the player's whole static closure into
+ * the `media-gallery` area stylesheet, 2023 candidates to 2190, for a line that emits nothing
+ * at runtime. The two definitions are structurally identical, so tsc still joins them at the
+ * one call site that matters (`<LazyVideoPlayer video={…}>` below).
  */
 export function stagePlayableVideo(
   item: MediaGalleryItem,
   media: MediaGalleryItemMedia,
   streamUrl: string,
-): ChapteredVideo {
+): ChapteredVideo & { playbackDegraded?: boolean } {
   return {
     id: item.id,
     name: item.name,
@@ -817,6 +987,14 @@ export function stagePlayableVideo(
      * upload, so its absence is the ordinary case, not an error.
      */
     ...(media.hlsUrl ? { hlsUrl: media.hlsUrl } : {}),
+    /*
+     * 🔴 …and the other half of that sentence: the app ASKED for the ladder and its store did
+     * not answer, so the line above is absent for a reason worth saying out loud. It rides the
+     * same mapping as `hlsUrl` because it is the same fact seen from the other side, and
+     * because a field that is not listed here is a field that reaches the player dead — which
+     * is exactly how `vttUrl`, `processingStatus` and the ladder itself each shipped invisible.
+     */
+    ...(media.playbackDegraded ? { playbackDegraded: true } : {}),
     ...(media.posterUrl ? { posterUrl: media.posterUrl } : {}),
     ...(item.durationSeconds != null ? { durationSeconds: item.durationSeconds } : {}),
     // Scrub-preview thumbnails and the "still optimizing" indicator. Both were already
@@ -888,15 +1066,18 @@ function NativeVideoStage({
   poster,
   repeat,
   onEnded,
+  onFault,
 }: {
   hlsUrl?: string | undefined;
   streamUrl: string;
   poster?: string | undefined;
   repeat?: boolean;
   onEnded?: () => void;
+  /** The source ANSWERED and there is nothing left to play — see {@link NativeVideoSurface}. */
+  onFault?: (fault: SourceFault) => void;
 }) {
   const ref = React.useRef<HTMLVideoElement>(null);
-  useHlsSource(ref, { hlsUrl, streamUrl });
+  useHlsSource(ref, { hlsUrl, streamUrl }, { ...(onFault ? { onFault } : {}) });
   useStageVolume(ref);
   return (
     // biome-ignore lint/a11y/useMediaCaption: arbitrary user-stored files carry no captions
@@ -915,6 +1096,155 @@ function NativeVideoStage({
   );
 }
 
+/**
+ * The stage for a source that ANSWERED — `404`, `410`, a spent `403`, anything that is not
+ * the bytes and is not still in flight.
+ *
+ * ── 🔴 Why this is a panel and not a longer spinner ─────────────────────────────────────
+ * Owner, 2026-09-17: *"make a 404 stop the media player spinner so I don't think it's going
+ * to eventually load."* One item in his catalogue has no ladder, so the first request the
+ * stage made was answered `404` in 0.2 s — and that was the one status every surface here
+ * treated as "still loading". **A hang and an answer must not look the same**, which is the
+ * whole report: a timeout may keep spinning, because something might still arrive; an answer
+ * may not, because nothing will.
+ *
+ * It borrows `.cbmg-stage-panel`, the same frame the audio stage and the no-viewer fallback
+ * already use, so a stage that cannot show its file looks like one thing across every
+ * category rather than three near-misses. `role='status'` because the sentence REPLACED
+ * something the viewer was waiting on, and a screen reader that was told "loading" has to be
+ * told how that ended.
+ */
+function StageSourceFault({
+  item,
+  category,
+  fault,
+  subject,
+}: {
+  item: MediaGalleryItem;
+  category: FileCategory;
+  fault: SourceFault;
+  /** The noun that leads the sentence — see {@link sourceFaultMessage}. */
+  subject: string;
+}) {
+  return (
+    <div className='cbmg-stage-panel' role='status'>
+      <FileTypeIcon category={category} size={48} />
+      <span className='cbmg-stage-panel-name'>{item.name}</span>
+      <span>{sourceFaultMessage(fault, subject)}</span>
+    </div>
+  );
+}
+
+/**
+ * One fault, and the single decision every stage makes about it: re-ask, or say it.
+ *
+ * 🔴 A `403` is the one fault that comes back on its own — this fleet's signed URLs carry
+ * `exp = iat + 2 × window`, so a page left open across a window boundary meets a stale token
+ * legitimately and the app can simply mint another. So the recoverable kind is spent on a
+ * re-ask FIRST and only becomes a sentence if there is no re-ask left ({@link useItemMedia}
+ * allows exactly one per item, which is what stops this being a loop).
+ */
+function useSourceFault(reAsk: () => boolean): {
+  fault: SourceFault | null;
+  report: (fault: SourceFault) => void;
+} {
+  const [fault, setFault] = useState<SourceFault | null>(null);
+  const report = useCallback(
+    (next: SourceFault) => {
+      if (isRecoverableFault(next) && reAsk()) return;
+      setFault(next);
+    },
+    [reAsk],
+  );
+  return { fault, report };
+}
+
+/**
+ * The `nativeVideoStage` element plus the one thing a `<video>` cannot say for itself.
+ *
+ * Mounted with a `key` on its source by {@link GalleryStage}, so stepping to another clip —
+ * or getting a freshly signed URL out of the re-ask — starts from no fault rather than
+ * inheriting the previous source's.
+ */
+function NativeVideoSurface({
+  item,
+  media,
+  streamUrl,
+  repeat,
+  onEnded,
+  reAsk,
+}: {
+  item: MediaGalleryItem;
+  media: MediaGalleryItemMedia;
+  streamUrl: string;
+  repeat?: boolean;
+  onEnded?: () => void;
+  reAsk: () => boolean;
+}) {
+  const { fault, report } = useSourceFault(reAsk);
+  if (fault) {
+    return <StageSourceFault item={item} category='video' fault={fault} subject='This video' />;
+  }
+  return (
+    /*
+     * 🔴 The source is ATTACHED, not declared, because a ladder is not a `src`.
+     *
+     * An `.m3u8` on `video.src` plays on Safari and every iPhone and on nothing else, so
+     * the choice between native HLS, hls.js and the progressive remux has to be made
+     * against the element — see `NativeVideoStage` / `hlsSource.ts`. A plain `src={src}`
+     * here is what made `hlsUrl` reach this stage and do nothing.
+     */
+    <NativeVideoStage
+      hlsUrl={media.hlsUrl}
+      streamUrl={streamUrl}
+      poster={media.posterUrl}
+      repeat={repeat}
+      onFault={report}
+      {...(onEnded ? { onEnded } : {})}
+    />
+  );
+}
+
+/**
+ * The picture stage, and the same distinction for an `<img>`.
+ *
+ * 🔴 An `<img>` that 404s is the image half of the owner's report: `onError` carries no
+ * status, so "the file is gone", "the token went stale" and "these bytes are not a picture"
+ * arrived as one undifferentiated failure, and the stage drew a torn-page glyph next to a
+ * title — which reads as the archive being broken. {@link probeSourceFault} is the only way
+ * to tell them apart and it runs solely on this path, after the browser has already given up.
+ */
+function ImageSurface({
+  item,
+  url,
+  reAsk,
+}: {
+  item: MediaGalleryItem;
+  url: string;
+  reAsk: () => boolean;
+}) {
+  const { fault, report } = useSourceFault(reAsk);
+  if (fault) {
+    return <StageSourceFault item={item} category='image' fault={fault} subject='This picture' />;
+  }
+  return (
+    <div className='cbgd-stage-img' data-turned={isTurned(item) ? 'true' : undefined}>
+      {/* A stored orientation is applied as a transform, never baked — see
+          `MediaGalleryItem.orientation`. `data-turned` lets the stylesheet swap the fit
+          constraint: a quarter-turned picture is laid out in its ORIGINAL box, so without it
+          a portrait scan turned upright overflows the frame it is centred in. */}
+      <img
+        src={url}
+        alt={item.name}
+        style={orientationStyle(item)}
+        onError={() => {
+          void probeSourceFault(url).then(report);
+        }}
+      />
+    </div>
+  );
+}
+
 /** The big stage — the right viewer per category. */
 function GalleryStage({
   item,
@@ -947,7 +1277,7 @@ function GalleryStage({
   fullscreenOnDoubleClick?: boolean;
 }) {
   const category = galleryItemCategory(item);
-  const { media, resolving } = useItemMedia(item, mediaCache);
+  const { media, resolving, refresh } = useItemMedia(item, mediaCache);
 
   if (category === 'video') {
     const src = media.streamUrl ?? media.url;
@@ -983,20 +1313,16 @@ function GalleryStage({
     );
     if (nativeVideoStage) {
       return frame(
-        /*
-         * 🔴 The source is ATTACHED, not declared, because a ladder is not a `src`.
-         *
-         * An `.m3u8` on `video.src` plays on Safari and every iPhone and on nothing else, so
-         * the choice between native HLS, hls.js and the progressive remux has to be made
-         * against the element — see `NativeVideoStage` / `hlsSource.ts`. A plain `src={src}`
-         * here is what made `hlsUrl` reach this stage and do nothing.
-         */
-        <NativeVideoStage
+        // `key`ed on the source: stepping to the next clip remounts rather than re-attaching
+        // into an element mid-buffer on the previous one — and it is what clears a recorded
+        // fault when a re-ask comes back with a freshly signed URL.
+        <NativeVideoSurface
           key={media.hlsUrl ?? src}
-          hlsUrl={media.hlsUrl}
+          item={item}
+          media={media}
           streamUrl={src}
-          poster={media.posterUrl}
           repeat={repeat}
+          reAsk={refresh}
           {...(onEnded ? { onEnded } : {})}
         />,
       );
@@ -1021,15 +1347,9 @@ function GalleryStage({
 
   if (category === 'image') {
     if (!media.url) return <StageLoading label={resolving ? 'Loading…' : 'Image unavailable.'} />;
-    return (
-      <div className='cbgd-stage-img' data-turned={isTurned(item) ? 'true' : undefined}>
-        {/* A stored orientation is applied as a transform, never baked — see
-            `MediaGalleryItem.orientation`. `data-turned` lets the stylesheet swap the fit
-            constraint: a quarter-turned picture is laid out in its ORIGINAL box, so without it
-            a portrait scan turned upright overflows the frame it is centred in. */}
-        <img src={media.url} alt={item.name} style={orientationStyle(item)} />
-      </div>
-    );
+    // `key`ed on the URL for the reason the video stage is: a new URL — including the one a
+    // re-ask mints — is a new attempt and must not inherit the previous one's fault.
+    return <ImageSurface key={media.url} item={item} url={media.url} reAsk={refresh} />;
   }
 
   if (category === 'audio') {
@@ -2122,9 +2442,9 @@ export function MediaGallery({
   const capabilityDialogs = (
     <React.Suspense fallback={null}>
       {editingPicture ? (
-        <LazyPictureEditor
-          src={editingPicture.url ?? ''}
-          fileName={editingPicture.name}
+        <EditPictureDialog
+          item={editingPicture}
+          cache={mediaCache}
           allowReplace={allowPictureReplace}
           onClose={() => setEditingPicture(null)}
           onSave={async (result: PictureEditResult) => {
@@ -2143,11 +2463,9 @@ export function MediaGallery({
         />
       ) : null}
       {trimmingVideo && onTrimVideo ? (
-        <LazyVideoCutEditor
-          src={trimmingVideo.streamUrl ?? trimmingVideo.url ?? ''}
-          {...(trimmingVideo.posterUrl ? { posterUrl: trimmingVideo.posterUrl } : {})}
-          name={trimmingVideo.name}
-          durationSeconds={trimmingVideo.durationSeconds ?? null}
+        <TrimVideoDialog
+          item={trimmingVideo}
+          cache={mediaCache}
           {...(trimNote ? { note: trimNote } : {})}
           onClose={() => setTrimmingVideo(null)}
           onSubmit={async (cuts: VideoCut[]) => {
@@ -2156,12 +2474,9 @@ export function MediaGallery({
         />
       ) : null}
       {chapteringVideo && onSaveChapters ? (
-        <LazyVideoChapterEditor
-          src={chapteringVideo.streamUrl ?? chapteringVideo.url ?? ''}
-          {...(chapteringVideo.posterUrl ? { posterUrl: chapteringVideo.posterUrl } : {})}
-          name={chapteringVideo.name}
-          durationSeconds={chapteringVideo.durationSeconds ?? null}
-          {...(chapteringVideo.chapters ? { chapters: chapteringVideo.chapters } : {})}
+        <ChapterVideoDialog
+          item={chapteringVideo}
+          cache={mediaCache}
           onClose={() => setChapteringVideo(null)}
           onSubmit={async (chapters: VideoChapter[]) => {
             await onSaveChapters(chapteringVideo, chapters);
@@ -2182,14 +2497,10 @@ export function MediaGallery({
         />
       ) : null}
       {grabbing ? (
-        <LazyFrameGrabber
-          src={grabbing.item.streamUrl ?? grabbing.item.url ?? ''}
-          name={grabbing.item.name}
-          startAt={grabbing.at}
-          // So the dialog can SAY that saving replaces the picture this film shows now, rather
-          // than overwriting somebody's chosen poster silently — the owner's copy-not-overwrite
-          // ruling applied to the one case in that dialog where a replacement is unavoidable.
-          hasPoster={Boolean(grabbing.item.posterUrl)}
+        <GrabFrameDialog
+          item={grabbing.item}
+          at={grabbing.at}
+          cache={mediaCache}
           onClose={() => setGrabbing(null)}
           {...(onSaveThumbnail
             ? { onSaveThumbnail: (poster: Blob) => onSaveThumbnail(grabbing.item, poster) }

package/src/react/media-gallery/galleryItemMedia.tsx

@@ -8,7 +8,7 @@
  * signed-URL app is a request per row per toggle. A module both import is the only shape
  * that cannot drift; re-implementing either inside the table is what this file prevents.
  */
-import { type MutableRefObject, useEffect, useState } from 'react';
+import { type MutableRefObject, useCallback, useEffect, useRef, useState } from 'react';
 import { staticItemMedia } from './mediaGalleryModel';
 import type { MediaGalleryItem, MediaGalleryItemMedia } from './types';
 
@@ -16,15 +16,37 @@ export type MediaCache = MutableRefObject<Map<string, Promise<MediaGalleryItemMe
 /**
  * The item's resolved media: static URL fields immediately, `resolveMedia` results merged
  * in when the item needs them (cached per id for the gallery's lifetime).
+ *
+ * `refresh` throws the cached answer away and asks the app again — see its own note; it is
+ * what makes a `403` from a stale signed URL recoverable instead of a sentence on screen.
  */
 export function useItemMedia(
   item: MediaGalleryItem,
   cache: MediaCache,
-): { media: MediaGalleryItemMedia; resolving: boolean } {
+): { media: MediaGalleryItemMedia; resolving: boolean; refresh: () => boolean } {
   const staticMedia = staticItemMedia(item);
   const needsResolve = Boolean(item.resolveMedia) && !item.url;
   const [resolved, setResolved] = useState<MediaGalleryItemMedia | null>(null);
   const [resolving, setResolving] = useState(needsResolve);
+  /** Bumped by {@link refresh} so the effect below re-runs against an emptied cache. */
+  const [attempt, setAttempt] = useState(0);
+  /**
+   * 🔴 ONE re-ask per item, for the life of this mount.
+   *
+   * The whole reason to re-ask is a signed URL that went stale, and the app's answer to that
+   * is a fresh token — so if the second URL fails the same way, asking a third time is an
+   * unbounded loop against something that is not going to change, which is the same spinner
+   * this batch removed with more requests in it. `RECOVERY_BUDGET` in `hlsSource.ts` bounds
+   * its retries for exactly this reason; this is that rule one layer up.
+   */
+  const reAsked = useRef<Set<string>>(new Set());
+  const refresh = useCallback((): boolean => {
+    if (!needsResolve || reAsked.current.has(item.id)) return false;
+    reAsked.current.add(item.id);
+    cache.current.delete(item.id);
+    setAttempt((n) => n + 1);
+    return true;
+  }, [item.id, needsResolve, cache]);
 
   useEffect(() => {
     if (!needsResolve) return;
@@ -49,9 +71,10 @@ export function useItemMedia(
     return () => {
       live = false;
     };
-  }, [item.id, needsResolve, cache, item.resolveMedia]);
+    // `attempt` is the re-ask: it is not read in the body, it is what re-runs it.
+  }, [item.id, needsResolve, cache, item.resolveMedia, attempt]);
 
-  return { media: { ...(resolved ?? {}), ...staticMedia }, resolving };
+  return { media: { ...(resolved ?? {}), ...staticMedia }, resolving, refresh };
 }
 
 /**

package/src/react/media-gallery/mediaGalleryModel.spec.ts

@@ -8,6 +8,7 @@ import {
   galleryTags,
   isMarkdownFile,
   sortGalleryItems,
+  staticItemMedia,
 } from './mediaGalleryModel';
 import type { MediaGalleryItem, MediaGalleryOrder } from './types';
 
@@ -180,3 +181,38 @@ describe('every sort pill is a two-way toggle', () => {
     expect(sortGalleryItems(ITEMS, 'oldest').map((i) => i.id)).toEqual(['b', 'c', 'a', 'd']);
   });
 });
+
+/**
+ * 🔴 A field inlined on the item has to survive `staticItemMedia`, because that is the other
+ * road into the stage — the one an app takes when it has no `resolveMedia` and simply puts the
+ * URLs on the row. A field missing from this function is a field that is silently gone for
+ * every such app, exactly as it would be missing from `stagePlayableVideo`.
+ */
+describe('staticItemMedia carries the transport facts, and only the true ones', () => {
+  test('an unreachable ladder rides along with the URLs', () => {
+    const media = staticItemMedia(
+      item({
+        id: 'v',
+        name: 'clip.mp4',
+        streamUrl: '/files/v.web.mp4',
+        playbackDegraded: true,
+      }),
+    );
+    expect(media.streamUrl).toBe('/files/v.web.mp4');
+    expect(media.playbackDegraded).toBe(true);
+  });
+
+  test('a video that simply has no ladder leaves the key ABSENT, so a spread cannot clobber it', () => {
+    // Every entry here is dropped when falsy on purpose: `{...staticMedia, ...resolved}` merges
+    // the two roads, and an explicit `playbackDegraded: false` would overwrite a resolver that
+    // had just found out otherwise.
+    const media = staticItemMedia(item({ id: 'v', name: 'clip.mp4', streamUrl: '/files/v.mp4' }));
+    expect('playbackDegraded' in media).toBe(false);
+    expect(
+      'playbackDegraded' in
+        staticItemMedia(
+          item({ id: 'v', name: 'clip.mp4', streamUrl: '/f.mp4', playbackDegraded: false }),
+        ),
+    ).toBe(false);
+  });
+});

package/src/react/media-gallery/mediaGalleryModel.ts

@@ -209,6 +209,10 @@ export function staticItemMedia(item: MediaGalleryItem): MediaGalleryItemMedia {
   if (item.streamUrl) media.streamUrl = item.streamUrl;
   // Additional to `streamUrl`, never instead of it — see `MediaGalleryItemMedia.hlsUrl`.
   if (item.hlsUrl) media.hlsUrl = item.hlsUrl;
+  // "We could not ASK about the ladder", which is not the same as not having one — see
+  // `MediaGalleryItemMedia.playbackDegraded`. Forwarded only when true, so the ordinary
+  // ladder-less video carries nothing and the stage has nothing to say about it.
+  if (item.playbackDegraded) media.playbackDegraded = true;
   if (item.vttUrl) media.vttUrl = item.vttUrl;
   if (item.processingStatus) media.processingStatus = item.processingStatus;
   return media;

package/src/react/media-gallery/types.ts

@@ -55,6 +55,29 @@ export interface MediaGalleryItemMedia {
    * and `preferBundledHls`, which decides where the engine comes from.
    */
   hlsUrl?: string;
+  /**
+   * The ladder was not ASKED ABOUT successfully — so this play is the progressive fallback and
+   * the app knows it, rather than merely having no ladder.
+   *
+   * 🔴 It is NOT "there is no ladder". A video whose ladder has simply never been built is the
+   * ordinary case and stays quiet: {@link hlsUrl} is absent, `streamUrl` plays, nothing is
+   * wrong. This flag is the other thing — the app's probe of its own media store did not
+   * answer, so it cannot tell a ladder that is missing from one it could not reach, and it has
+   * served the progressive copy on that ignorance.
+   *
+   * 🔴 And it is NOT {@link processingStatus} `'failed'`. That badge says the optimization
+   * failed; here the optimization may well have succeeded and we could not ask. Different
+   * cause, different fix, different lifetime — this one usually clears on the next open — so
+   * the player draws a SECOND badge rather than borrowing that one's sentence.
+   *
+   * Worth a badge because the fallback is expensive and silent: in `apps/collections` the
+   * progressive `.web.mp4` averages 467 MB and reaches 4.4 GB, which is past what Cloudflare
+   * will cache (`x-bs-edge-cache: MISS-TOO-LARGE`), so every play and every seek is pulled off
+   * the owner's own Mac; a ladder segment is ~1 MB and comes from the edge. For eight days
+   * nothing in the fleet could say which of the two it was serving, and the owner found out by
+   * watching a video stall.
+   */
+  playbackDegraded?: boolean;
   /**
    * WebVTT scrub-preview track — the sprite-sheet index that puts real frame thumbnails on
    * the scrub bar instead of a bare timecode. Passed straight to the player's `thumbnails`.

package/src/styles-areas/master-lock.css

@@ -15,7 +15,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 125 candidate(s) scanned.
+ * when this file is stale. 147 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are