cursedbelt 3.0.2 → 4.0.0

package/src/react/media/VideoPlayer.spec.tsx

@@ -143,7 +143,13 @@ describe('autoplay — a video opened as the SUBJECT plays on arrival, silently'
    * doesn't loudly surprise people but it should play right away."
    */
   test('the default is: play, and play silently', () => {
-    expect(resolveAutoplay({ reducedMotion: false })).toEqual({ autoPlay: true, muted: true });
+    expect(resolveAutoplay({ reducedMotion: false })).toEqual({
+      autoPlay: true,
+      muted: true,
+      // Full level UNDER the mute, so the control bar's unmute button behaves the way it did
+      // before session volume existed. See `SessionVolume`.
+      volume: 1,
+    });
   });
 
   test('muted follows autoPlay, because an UNMUTED autoplay is refused by every browser', () => {
@@ -157,6 +163,7 @@ describe('autoplay — a video opened as the SUBJECT plays on arrival, silently'
     expect(resolveAutoplay({ autoPlay: false, reducedMotion: false })).toEqual({
       autoPlay: false,
       muted: false,
+      volume: 1,
     });
   });
 
@@ -177,6 +184,109 @@ describe('autoplay — a video opened as the SUBJECT plays on arrival, silently'
   });
 });
 
+/**
+ * 🔴 The volume he set stays set until he refreshes.
+ *
+ * Owner, `ideas/collections-09-14.md`: *"Keep the media player volume where I set it after
+ * changing it during a session except if I refresh or first log in then continue starting it
+ * at mute. Then if I unmute it, keep that value as I change to other videos."*
+ *
+ * The STORE half — `sessionStorage`, and never `localStorage` — is asserted in
+ * `media-gallery/playbackPreferences.spec.ts`. This is the half that decides what a mounting
+ * player actually opens at, and it is a pure function for the reason the block above says:
+ * `volume` and `muted` are two attributes on one inert custom element under happy-dom, and
+ * getting the precedence backwards renders identically.
+ */
+describe('a restored session volume', () => {
+  test('no session is byte-for-byte the old rule — a refresh therefore starts at mute', () => {
+    expect(resolveAutoplay({ autoPlay: true, reducedMotion: false, session: null })).toEqual({
+      autoPlay: true,
+      muted: true,
+      volume: 1,
+    });
+  });
+
+  test('a level he set on one clip is what the NEXT clip opens at', () => {
+    expect(
+      resolveAutoplay({
+        autoPlay: true,
+        reducedMotion: false,
+        session: { volume: 0.4, muted: false },
+      }),
+    ).toEqual({ autoPlay: true, muted: false, volume: 0.4 });
+  });
+
+  test('🔴 a muted session still carries his level, so unmuting is not a jump to full', () => {
+    const resolved = resolveAutoplay({
+      autoPlay: true,
+      reducedMotion: false,
+      session: { volume: 0.4, muted: true },
+    });
+    expect(resolved.muted).toBe(true);
+    // The level is applied to the ELEMENT under the mute — which is the entire second
+    // sentence of the ask. `volume: 0` here would satisfy "it is muted" and lose it.
+    expect(resolved.volume).toBe(0.4);
+  });
+
+  test('an explicit `muted` prop still wins — an app that says silent means silent', () => {
+    expect(
+      resolveAutoplay({
+        muted: true,
+        reducedMotion: false,
+        session: { volume: 0.8, muted: false },
+      }).muted,
+    ).toBe(true);
+  });
+
+  test('a click-to-play player is not muted by a session that never mentioned it', () => {
+    // The `null`-vs-default distinction, seen from the consumer side: without it, every
+    // `autoPlay={false}` player in the fleet would come back silent on upgrade.
+    expect(resolveAutoplay({ autoPlay: false, reducedMotion: false, session: null }).muted).toBe(
+      false,
+    );
+  });
+
+  test('the player WIRES it — the props happy-dom cannot see for us', () => {
+    /*
+     * Vidstack's player is a custom element happy-dom never brings to life, so `volume`,
+     * `onVolumeChange` and `onAutoPlayFail` are unobservable in a rendered tree: dropping any
+     * of the three leaves every test above green and the feature gone. Asserted on the source
+     * the same way the hls.js engine is, two describes down.
+     */
+    const source = readFileSync(join(import.meta.dir, 'VideoPlayer.tsx'), 'utf8');
+    expect(/volume=\{startVolume\}/.test(source)).toBe(true);
+    // Read off the PLAYER's own event, not a React slider — he changes this in Vidstack's
+    // control bar, which no React state can see.
+    expect(source).toContain('onVolumeChange={(detail)');
+    expect(source).toContain('writeSessionVolume(volumeKey, applied.current)');
+    // A refused unmuted autoplay must not leave a slideshow sitting on frame one.
+    expect(source).toContain('onAutoPlayFail={(detail)');
+  });
+
+  test('🔴 a storage that THROWS does not take the render down', () => {
+    /*
+     * Safari's private mode and a sandboxed iframe throw on the ACCESS, not on the read, and
+     * an unguarded storage read on a player's mount path takes the whole gallery render down
+     * over a remembered volume. The session volume reaches for no web store at all — see
+     * `SessionVolume`, which is also why a refresh returns him to mute — so there is nothing
+     * here to be denied. Asserted rather than assumed: the day somebody moves it onto
+     * `localStorage`/`sessionStorage` without the `try` its neighbours carry, this reds.
+     */
+    const original = Object.getOwnPropertyDescriptor(globalThis, 'sessionStorage');
+    Object.defineProperty(globalThis, 'sessionStorage', {
+      configurable: true,
+      get() {
+        throw new Error('SecurityError: access to sessionStorage is denied');
+      },
+    });
+    try {
+      expect(() => render(<VideoPlayer video={video} />)).not.toThrow();
+    } finally {
+      if (original) Object.defineProperty(globalThis, 'sessionStorage', original);
+    }
+  });
+});
+
 /**
  * 🔴 The timeline follows the drag, live.
  *

package/src/react/media/VideoPlayer.tsx

@@ -9,6 +9,8 @@ import {
   MediaProvider,
   type MediaProviderAdapter,
   Poster,
+  Track,
+  useMediaState,
 } from '@vidstack/react';
 import {
   DefaultVideoLayout,
@@ -17,7 +19,14 @@ import {
 } from '@vidstack/react/player/layouts/default';
 import { type MouseEvent as ReactMouseEvent, type RefObject, useEffect, useMemo, useRef, useState } from 'react';
 import type { PlayableVideo } from 'cursedbelt-core/media';
+import {
+  PLAYER_VOLUME_KEY,
+  readSessionVolume,
+  type SessionVolume,
+  writeSessionVolume,
+} from '../media-gallery/playbackPreferences';
 import { isSurfaceControl } from './surfaceGesture';
+import { chapterSpans, type ChapteredVideo, type VideoChapter } from './videoChapters';
 
 /**
  * The reusable video player primitive. Consumes a {@link PlayableVideo} (URLs already
@@ -33,16 +42,36 @@ import { isSurfaceControl } from './surfaceGesture';
  * `<video>` element safe here — no canvas workaround. Scrub-preview thumbnails come from the
  * source's WebVTT track (`vttUrl`); while derivatives are still being built, a thin progress
  * bar rides the bottom edge of the surface (the original bytes stay playable behind it).
+ *
+ * Named sections (`chapters`) become a real `kind='chapters'` text track, which is what turns
+ * Vidstack's default layout from a bare bar into a YouTube-shaped one — dividers on the time
+ * slider, the current section's name above it, and a chapters menu. See {@link ChaptersTrack}.
  */
 export interface VideoPlayerProps {
-  video: PlayableVideo;
+  /**
+   * The clip, with every URL already resolved — and its named sections, when the app carries
+   * any. {@link ChapteredVideo} is `PlayableVideo` plus `chapters`, so every existing source
+   * still satisfies this unchanged.
+   */
+  video: ChapteredVideo;
   /**
    * Start playing on mount. **Defaults to `true`** — see {@link usePrefersReducedMotion} and
    * the block on {@link AUTOPLAY_DEFAULT}.
    */
   autoPlay?: boolean;
-  /** Start silent. **Defaults to `true` whenever autoplay is in effect** (see below). */
+  /**
+   * Start silent. **Defaults to `true` whenever autoplay is in effect** (see below) — unless
+   * the person has already set a volume on this surface THIS SESSION, which wins over both.
+   */
   muted?: boolean;
+  /**
+   * Where this surface's session volume is kept. Defaults to {@link PLAYER_VOLUME_KEY}.
+   *
+   * 🔴 Pass a different key for a player that is a DIFFERENT surface — the gallery stage
+   * passes `STAGE_VOLUME_KEY` — for the reason `media/stageResize.ts` keys the remembered
+   * height: one shared key makes two viewers on one page fight over a single number.
+   */
+  volumeKey?: string;
   className?: string;
   /**
    * Intrinsic aspect ratio (a CSS `aspect-ratio` value, e.g. `'16/9'` or `'4/3'`). Gives the
@@ -326,21 +355,45 @@ export const AUTOPLAY_DEFAULT = true;
  * preference", which is the behavior everything had before this existed.
  */
 /**
- * The autoplay decision, as a pure function so it can be asserted without a browser.
+ * The autoplay decision — and, since 2026-09-16, how loud the clip opens.
  *
  * 🔴 It is extracted rather than inlined because nothing below a real browser can see the
  * difference: `autoPlay` and `muted` are two props on one JSX element, and swapping them,
  * dropping the reduced-motion term, or letting `muted` default independently all typecheck
  * and render identically under happy-dom. The same reasoning `posterFraming.ts` and
  * `mediaGalleryModel.ts` already apply to their own decisions.
+ *
+ * ── 🔴 Where `session` sits in the precedence, and why ──────────────────────────────────
+ * Owner, `ideas/collections-09-14.md`: *"Keep the media player volume where I set it after
+ * changing it during a session except if I refresh or first log in then continue starting it
+ * at mute. Then if I unmute it, keep that value as I change to other videos."*
+ *
+ *   · an explicit `muted` prop still wins — an app that says "silent" means silent
+ *   · then what he set THIS SESSION ({@link readSessionVolume}, `null` until he touches it)
+ *   · then the old rule: muted follows autoPlay, because an unmuted autoplay is refused
+ *
+ * A `null` session is therefore byte-for-byte the behavior every consumer had before this
+ * existed, which is what makes "a refresh starts at mute" true rather than merely intended:
+ * a fresh tab has no session entry, so a fresh tab takes the third line.
+ *
+ * `volume` is returned separately from `muted` on purpose — see {@link SessionVolume}. A mute
+ * stored as `volume: 0` would make the control bar's unmute button return to silence, and
+ * *"if I unmute it, keep that value"* is the sentence that forbids it.
  */
 export function resolveAutoplay(opts: {
   autoPlay?: boolean;
   muted?: boolean;
   reducedMotion: boolean;
-}): { autoPlay: boolean; muted: boolean } {
+  /** What he set this session on this surface, or `null`/absent for "he has not". */
+  session?: SessionVolume | null;
+}): { autoPlay: boolean; muted: boolean; volume: number } {
   const autoPlay = (opts.autoPlay ?? AUTOPLAY_DEFAULT) && !opts.reducedMotion;
-  return { autoPlay, muted: opts.muted ?? autoPlay };
+  const session = opts.session ?? null;
+  return {
+    autoPlay,
+    muted: opts.muted ?? session?.muted ?? autoPlay,
+    volume: session?.volume ?? 1,
+  };
 }
 
 /**
@@ -459,6 +512,7 @@ export function VideoPlayer({
   video,
   autoPlay,
   muted,
+  volumeKey = PLAYER_VOLUME_KEY,
   className,
   aspectRatio = DEFAULT_VIDEO_ASPECT_RATIO,
   onEnded,
@@ -475,18 +529,37 @@ export function VideoPlayer({
     : video.streamUrl;
 
   // See AUTOPLAY_DEFAULT. `muted` follows `autoPlay` because an unmuted autoplay is refused
-  // by every browser and the refusal LOOKS like the spinner this batch removed.
+  // by every browser and the refusal LOOKS like the spinner this batch removed — unless he
+  // has already set a level on this surface this session, which is what `session` carries.
   const reducedMotion = usePrefersReducedMotion();
-  const { autoPlay: shouldAutoPlay, muted: shouldMute } = resolveAutoplay({
-    autoPlay,
-    muted,
-    reducedMotion,
-  });
+  // 🔴 Read ONCE, on mount, and never again: this is a starting value handed to a player that
+  // owns its own volume state from then on. Re-reading it on a later render would fight the
+  // control bar he is holding, and stepping to the next clip remounts this component anyway,
+  // which is exactly when the remembered level is supposed to be applied.
+  const [session] = useState<SessionVolume | null>(() => readSessionVolume(volumeKey));
+  const {
+    autoPlay: shouldAutoPlay,
+    muted: shouldMute,
+    volume: startVolume,
+  } = resolveAutoplay({ autoPlay, muted, reducedMotion, session });
 
   const hostRef = useRef<HTMLDivElement>(null);
   const playerRef = useRef<MediaPlayerInstance>(null);
   useLiveScrub(hostRef, playerRef, liveScrub);
 
+  /*
+   * 🔴 What is on the element right now, so the RESTORE is not mistaken for a change.
+   *
+   * Applying `volume`/`muted` above makes the element fire `volumechange` like any other
+   * change, so a naive listener writes the starting value straight back — minting a remembered
+   * preference for a person who has touched nothing, on every player that mounts. That
+   * quietly turns "he has not set a volume" into "he set it to the default", which is the one
+   * distinction `readSessionVolume` returns `null` to preserve.
+   */
+  const applied = useRef({ volume: startVolume, muted: shouldMute });
+  /** A mute the BROWSER forced on us — see `onAutoPlayFail` below. Never his choice, so never stored. */
+  const forcedMute = useRef(false);
+
   const status = video.processingStatus;
   const showProcessing = status != null && status !== 'ready';
 
@@ -527,6 +600,40 @@ export function VideoPlayer({
         playsInline
         autoPlay={shouldAutoPlay}
         muted={shouldMute}
+        // 🔴 The level he set this session, restored on the element — see `resolveAutoplay`
+        // and `SessionVolume`. Both values are constant for the life of this mount, so
+        // Vidstack's own volume state is never overwritten while he is using the control bar;
+        // the next clip is a fresh mount, which is when the restore is meant to happen.
+        volume={startVolume}
+        /* 🔴 Read off the PLAYER, not off a React slider: he changes this in Vidstack's own
+           control bar (or with ↑/↓), which no React-side state can see. `volume-change` fires
+           for both facts at once, which is the shape `SessionVolume` stores. */
+        onVolumeChange={(detail) => {
+          // The echo of our own restore is not a change he made. See `applied`.
+          if (detail.volume === applied.current.volume && detail.muted === applied.current.muted)
+            return;
+          applied.current = { volume: detail.volume, muted: detail.muted };
+          if (forcedMute.current) {
+            // The browser's refusal, not his preference — leave the stored level alone so
+            // unmuting still returns to it.
+            forcedMute.current = false;
+            return;
+          }
+          writeSessionVolume(volumeKey, applied.current);
+        }}
+        /* 🔴 A restored volume must not be able to break the slideshow.
+           `playbackRun.ts` drives whole folders by mounting the next clip with `autoPlay`,
+           and a browser refuses an unmuted autoplay without a prior gesture — so a session
+           that remembers "unmuted" could, on the first clip after a restore, leave the run
+           sitting on frame one. Falling back to a muted play keeps the run running; the level
+           stays on the element, so one press of unmute is still HIS level rather than full. */
+        onAutoPlayFail={(detail) => {
+          const player = playerRef.current;
+          if (!player || detail.muted) return;
+          forcedMute.current = true;
+          player.muted = true;
+          void player.play().catch(() => {});
+        }}
         // Load eagerly rather than on-visible: the watch surface can size to a
         // zero-height box during iOS Safari's container-query resolution, so a
         // `visible` gate never fired and the player sat on a perpetual spinner.
@@ -552,6 +659,7 @@ export function VideoPlayer({
               single-click gesture stays a gesture: `toggle:paused` over the centre band is
               exactly what it is for, and Vidstack already declines it over the controls. */}
           <Gesture className='vds-gesture' event='pointerup' action='toggle:paused' />
+          <ChaptersTrack chapters={video.chapters} />
         </MediaProvider>
         <DefaultVideoLayout
           icons={defaultLayoutIcons}
@@ -578,6 +686,45 @@ export function VideoPlayer({
   );
 }
 
+/**
+ * The named sections, as the `kind='chapters'` text track Vidstack's default layout is already
+ * looking for.
+ *
+ * ── 🔴 Why this is a component and not three lines inside the player ──────────────────
+ * Because a chapter cue needs an END, and the only place the clip's real length is known is
+ * INSIDE the player. `PlayableVideo.durationSeconds` is optional and frequently absent — and
+ * where it is present it is whatever the app's catalogue recorded, which is routinely rounded
+ * to the second. Building the cues from that would put every divider a fraction out on the one
+ * surface where they are compared against the picture, and would draw nothing at all for the
+ * ordinary video whose row has no duration on it. `useMediaState('duration')` is the decoder's
+ * own number, and it only reads it from a component mounted within the player's context —
+ * which is what this one is.
+ *
+ * Handed `content` rather than a `src`, so no URL has to be minted, served, signed or revoked
+ * for a list of strings the browser already has. Vidstack's `type='json'` parser takes the cue
+ * objects directly.
+ *
+ * Renders nothing until there is a real duration and at least one section: an empty chapters
+ * track is not neutral, it makes the layout draw a chapter title area and a menu entry for a
+ * video that has no chapters.
+ */
+function ChaptersTrack({ chapters }: { chapters?: readonly VideoChapter[] }) {
+  const duration = useMediaState('duration');
+  const content = useMemo(() => {
+    const spans = chapterSpans(chapters ?? [], duration);
+    if (spans.length === 0) return null;
+    return {
+      cues: spans.map((span) => ({
+        startTime: span.startSeconds,
+        endTime: span.endSeconds,
+        text: span.title,
+      })),
+    };
+  }, [chapters, duration]);
+  if (!content) return null;
+  return <Track content={content} type='json' kind='chapters' label='Chapters' default />;
+}
+
 /**
  * The processing state for a video surface: a thin progress bar pinned across the bottom edge
  * while derivatives build (indeterminate shimmer until real progress arrives), or a compact

package/src/react/media/VideoTurner.spec.tsx

@@ -9,6 +9,7 @@
  * with itself.
  */
 import { describe, expect, test } from 'bun:test';
+import type React from 'react';
 import { fireEvent, render } from '@testing-library/react';
 import { type MediaOrientation, VideoTurner } from './VideoTurner';
 
@@ -60,6 +61,72 @@ describe('VideoTurner', () => {
     );
   });
 
+  /**
+   * 🔴 The dialog SAYS when it cannot show the footage — the owner's `ideas/collections-09-14.md`
+   * report: *"When I click the turn the video button I see a black screen."*
+   *
+   * It was mounted with an empty `src` (see `MediaGallery`'s `TurnVideoDialog` for the cause),
+   * and a `<video>` with nothing to load never fires `error` — it paints black and stays that
+   * way. So a preview that cannot happen must be a sentence, not a dark rectangle: that is the
+   * difference between a report anyone can act on and *"I see a black screen"*.
+   */
+  describe('when it cannot show the footage', () => {
+    const openWith = (props: Partial<React.ComponentProps<typeof VideoTurner>>) =>
+      render(<VideoTurner src='' onClose={() => {}} onSave={() => {}} {...props} />);
+
+    test('🔴 no source at all is a stated reason, not a black box', () => {
+      // `baseElement`, not `container`: the dialog is a portal, so its frame is not under the
+      // render root. The same reason every assertion here goes through a Testing Library query.
+      const { baseElement, getByRole } = openWith({});
+      expect(baseElement.querySelector('video')).toBeNull();
+      const said = getByRole('status').textContent ?? '';
+      expect(said).toContain('no video source');
+      // …and it says what is still true: the turn is metadata, so it can be set without a
+      // preview. Withholding that would turn a preview failure into a lost capability.
+      expect(said).toContain('save');
+    });
+
+    test('🔴 a source that fails to load says so too', () => {
+      const { baseElement, getByRole, queryByRole } = openWith({ src: '/files/gone' });
+      const video = baseElement.querySelector('video');
+      expect(video).not.toBeNull();
+      expect(queryByRole('status')).toBeNull();
+      fireEvent.error(video as HTMLVideoElement);
+      expect(getByRole('status').textContent).toContain('could not be loaded');
+    });
+
+    test('a source still being resolved reads as "on its way", not as a failure', () => {
+      // A signed URL takes a round trip to mint. Flashing "there is nothing to preview" at
+      // somebody whose film is on its way would be a false report the dialog invented itself.
+      const { getByRole } = openWith({ src: '', resolving: true });
+      expect(getByRole('status').textContent).toContain('Finding this film');
+    });
+
+    test('the poster stands in when the film will not play, so a turn still has a picture', () => {
+      const { baseElement } = openWith({ src: '', posterUrl: '/thumbs/clip' });
+      const poster = baseElement.querySelector<HTMLImageElement>('.cbpe-frame-film img');
+      expect(poster?.getAttribute('src')).toBe('/thumbs/clip');
+      // It is the picture being turned, so it carries the same transform the film would have.
+      expect(poster?.style.transform).toBe('none');
+    });
+
+    test('🔴 the turn can still be set and SAVED with no preview at all', () => {
+      const saved: (MediaOrientation | undefined)[] = [];
+      const { getByText } = render(
+        <VideoTurner
+          src=''
+          onClose={() => {}}
+          onSave={(next) => {
+            saved.push(next);
+          }}
+        />,
+      );
+      fireEvent.click(getByText('↻ Right'));
+      fireEvent.click(getByText('Save the turn'));
+      expect(saved).toEqual([{ turns: 1 }]);
+    });
+  });
+
   test('a video is never re-encoded — there is no crop or light control to press', () => {
     // Both are real for a picture (the canvas bakes them) and impossible for a clip in the
     // browser. Offering them here would either lie or silently drop what somebody asked for.

package/src/react/media/VideoTurner.tsx

@@ -14,10 +14,23 @@ export interface MediaOrientation {
 }
 
 export interface VideoTurnerProps {
-  /** The clip to turn. Plays muted in the dialog so the preview is the real footage. */
+  /**
+   * The clip to turn. Plays muted in the dialog so the preview is the real footage.
+   *
+   * 🔴 The RESOLVED source, not whatever URL field an item happens to carry — see
+   * `MediaGallery`'s `TurnVideoDialog`, where handing over an empty string was the whole of
+   * the owner's *"I see a black screen"*. An empty string here is now a stated reason rather
+   * than a black rectangle, but it is still nothing to preview.
+   */
   src: string;
   /** Shown until the first frame decodes — a black box reads as a broken player. */
   posterUrl?: string;
+  /**
+   * True while the app is still finding the source (a signed URL being minted, bytes being
+   * fetched). It is the difference between "on its way" and "cannot be shown", and only the
+   * caller knows which.
+   */
+  resolving?: boolean;
   name?: string;
   /** What is stored today, so re-opening the dialog starts from the current state. */
   orientation?: MediaOrientation | undefined;
@@ -49,6 +62,7 @@ export interface VideoTurnerProps {
 export function VideoTurner({
   src,
   posterUrl,
+  resolving = false,
   name,
   orientation,
   open = true,
@@ -67,6 +81,30 @@ export function VideoTurner({
   const [edit, setEdit] = React.useState<PictureEdit>(initial);
   const [saving, setSaving] = React.useState(false);
   const [error, setError] = React.useState<string | null>(null);
+  // A source that changes is a fresh attempt: it must not inherit the previous one's failure,
+  // the same rule the gallery's own `ThumbImg` keeps.
+  const [failedSrc, setFailedSrc] = React.useState<string | null>(null);
+
+  /**
+   * Why there is no moving picture — `null` when there is one.
+   *
+   * 🔴 The dialog SAYS this instead of rendering black, which is the whole of the owner's
+   * report: *"When I click the turn the video button I see a black screen."* He could not tell
+   * a broken dialog from a dark frame, and neither could anyone reading a bug report about it.
+   * Each reason also says what is still true — the turn is three integers on a row, so it can
+   * be set and saved with no preview at all, and refusing to let him would turn a preview
+   * failure into a lost capability.
+   */
+  const cannotShow: string | null = resolving
+    ? 'Finding this film…'
+    : !src
+      ? 'This file has no video source to play here, so there is nothing to preview. The turn is stored beside the film rather than encoded into it, so you can still set it and save.'
+      : failedSrc === src
+        ? 'The film could not be loaded, so there is nothing to preview. The turn is stored beside the film rather than encoded into it, so you can still set it and save.'
+        : null;
+  // A poster is the next best picture of the film, and it turns with the same transform — so a
+  // clip that will not play is still something to aim a turn at rather than a blank panel.
+  const posterStandsIn = cannotShow !== null && !resolving && Boolean(posterUrl);
 
   const dirty =
     edit.turns !== initial.turns || edit.flipX !== initial.flipX || edit.flipY !== initial.flipY;
@@ -124,21 +162,38 @@ export function VideoTurner({
       }
     >
       <div className='cbpe'>
-        {/* `data-turned` swaps the fit constraint for the odd quarter turns: the clip is still
-            LAID OUT in its original box, so a portrait clip turned upright overflows the frame
-            it is centred in without it. Same correction the gallery stage makes. */}
+        {/* `data-turned` swaps the box's axes for the odd quarter turns: the clip is still LAID
+            OUT the way it was filmed, so without it a portrait clip turned upright is previewed
+            at whatever size it already had — a pillar, where the stage is about to show it
+            full-width. Same correction, and the same measurement, as the gallery stage makes. */}
         <div className='cbpe-frame cbpe-frame-film' data-turned={swapsAxes(edit.turns) ? 'true' : undefined}>
-          {/* biome-ignore lint/a11y/useMediaCaption: arbitrary user-stored footage carries none */}
-          <video
-            src={src}
-            poster={posterUrl}
-            muted
-            loop
-            autoPlay
-            playsInline
-            controls={false}
-            style={{ transform: previewTransform(edit) }}
-          />
+          {cannotShow === null ? (
+            /* biome-ignore lint/a11y/useMediaCaption: arbitrary user-stored footage carries none */
+            <video
+              // A new source is a new attempt — see `failedSrc`.
+              key={src}
+              src={src}
+              poster={posterUrl}
+              muted
+              loop
+              autoPlay
+              playsInline
+              controls={false}
+              // 🔴 `metadata` at least. `preload='none'` would leave the element with nothing
+              // decoded and nothing drawn until something pressed play, which is a black frame
+              // wearing the same face as a broken source.
+              preload='metadata'
+              onError={() => setFailedSrc(src)}
+              style={{ transform: previewTransform(edit) }}
+            />
+          ) : posterStandsIn ? (
+            <img src={posterUrl} alt={name ?? 'The film'} style={{ transform: previewTransform(edit) }} />
+          ) : null}
+          {cannotShow ? (
+            <p className='cbpe-frame-note' role='status'>
+              {cannotShow}
+            </p>
+          ) : null}
         </div>
 
         <div className='cbpe-row'>