cursedbelt 4.1.0 → 4.3.0

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

@@ -1,7 +1,8 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { cleanup, render } from '@testing-library/react';
+import type React from 'react';
+import { cleanup, fireEvent, render } from '@testing-library/react';
 import { FrameGrabber } from './FrameGrabber';
 
 afterEach(cleanup);
@@ -173,3 +174,58 @@ describe('FrameGrabber — the exit is named in the dialog itself', () => {
     expect(text, 'nothing tells the reader how to leave without saving').toContain('escape');
   });
 });
+
+/**
+ * 🔴 The dialog SAYS when it has no film, and keeps its hands off the save buttons.
+ *
+ * The turn dialog's report (`ideas/collections-09-14.md`: *"When I click the turn the video
+ * button I see a black screen"*) turned out to be true of four siblings, this one included: it
+ * was mounted `src={item.streamUrl ?? item.url ?? ''}` off the raw row, and an item is allowed
+ * to carry neither field (`resolveMedia` is the documented path for a signed URL). Here the
+ * consequence is a step beyond a bad preview: every output of this dialog is pixels read back
+ * off the `<video>`, so a black frame came with two live-looking save buttons that could only
+ * fail at `toBlob` — after somebody had scrubbed for their moment.
+ */
+describe('FrameGrabber — when it cannot show the film', () => {
+  const openWith = (props: Partial<React.ComponentProps<typeof FrameGrabber>>) =>
+    render(
+      <FrameGrabber
+        src=''
+        name='wedding.mp4'
+        onClose={() => {}}
+        onSaveThumbnail={() => {}}
+        onSaveSnapshot={() => {}}
+        {...props}
+      />,
+    );
+
+  test('🔴 no source at all is a stated reason, not a black box', () => {
+    const { getByRole } = openWith({});
+    expect(body().querySelector('video')).toBeNull();
+    expect(getByRole('status').textContent).toContain('no video source');
+  });
+
+  test('🔴 the save button is HELD, because there is nothing to read a frame from', () => {
+    const { getByRole } = openWith({});
+    const keep = getByRole('button', { name: /thumbnail/i }) as HTMLButtonElement;
+    // DISABLED and still on screen, which is the `DESIGN.md` rule for a control that cannot
+    // work here: hiding it would make "this film has not arrived" look like "this app cannot
+    // choose a thumbnail", and the reason is already stated on the frame beside it.
+    expect(keep.disabled).toBe(true);
+    expect(body().contains(keep)).toBe(true);
+  });
+
+  test('🔴 a source that fails to load says so too', () => {
+    const { getByRole, queryByRole } = openWith({ src: '/films/gone.mp4' });
+    const film = body().querySelector('video');
+    expect(film).not.toBeNull();
+    expect(queryByRole('status')).toBeNull();
+    fireEvent.error(film 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', () => {
+    const { getByRole } = openWith({ src: '', resolving: true });
+    expect(getByRole('status').textContent).toContain('Finding this film');
+  });
+});

package/src/react/media/FrameGrabber.tsx

@@ -31,8 +31,22 @@ import {
 } from './posterFraming';
 
 export interface FrameGrabberProps {
-  /** The clip. 🔴 Must be reachable with CORS or the canvas is tainted — see below. */
+  /**
+   * The clip. 🔴 Must be reachable with CORS or the canvas is tainted — see below.
+   *
+   * 🔴 The RESOLVED source, not whatever URL field a record happens to carry — see
+   * `MediaGallery`'s `GrabFrameDialog`. A gallery item is allowed to carry no URL at all
+   * (`resolveMedia` is the documented path for a signed URL), and a `<video>` with an empty
+   * source never loads, never fires `error` and paints black forever, which is the owner's
+   * *"I see a black screen"* wearing a different dialog's clothes.
+   */
   src: 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;
   /** Open at this moment, in seconds — normally the playhead the stage had reached. */
   startAt?: number;
@@ -128,6 +142,7 @@ type Grab = 'thumbnail' | 'picture';
  */
 export function FrameGrabber({
   src,
+  resolving = false,
   name,
   startAt = 0,
   open = true,
@@ -148,6 +163,25 @@ export function FrameGrabber({
   const [busy, setBusy] = React.useState<null | 'thumb' | 'snap'>(null);
   const [error, setError] = React.useState<string | null>(null);
   const [dragging, setDragging] = React.useState(false);
+  // A source that changes is a fresh attempt: it must not inherit the previous one's failure,
+  // the same rule `VideoTurner` and the gallery's own `ThumbImg` keep.
+  const [failedSrc, setFailedSrc] = React.useState<string | null>(null);
+
+  /**
+   * Why there are no frames to pick from — `null` when there are.
+   *
+   * 🔴 Said out loud instead of drawn as a black rectangle. Every output of this dialog is
+   * pixels read back off the `<video>`, so an unresolved source is not a degraded dialog, it
+   * is an empty one — and the failure it used to present was a black frame with live-looking
+   * sliders, which is the shape of the owner's *"I see a black screen"* report.
+   */
+  const cannotShow: string | null = resolving
+    ? 'Finding this film…'
+    : !src
+      ? 'This file has no video source to play here, so there are no frames to pick from.'
+      : failedSrc === src
+        ? 'The film could not be loaded, so there are no frames to pick from.'
+        : null;
 
   const canThumb = Boolean(onSaveThumbnail);
   const canSnap = Boolean(onSaveSnapshot);
@@ -382,12 +416,16 @@ export function FrameGrabber({
             grab === 'thumbnail' && canThumb ? (
               <Button
                 variant='primary'
-                disabled={busy !== null}
+                // 🔴 Held while there is no film: every output here is pixels read back off the
+                // `<video>`, so a press with nothing decoded can only fail. See `cannotShow`.
+                disabled={busy !== null || cannotShow !== null}
                 onClick={() => void run('thumb')}
                 tooltip={
-                  hasPoster
-                    ? 'Replace the picture this film currently shows in the gallery'
-                    : 'Use this moment as the picture the gallery shows'
+                  cannotShow !== null
+                    ? 'The film has to load before a frame of it can be kept'
+                    : hasPoster
+                      ? 'Replace the picture this film currently shows in the gallery'
+                      : 'Use this moment as the picture the gallery shows'
                 }
               >
                 {busy === 'thumb'
@@ -399,9 +437,13 @@ export function FrameGrabber({
             ) : canSnap ? (
               <Button
                 variant='primary'
-                disabled={busy !== null}
+                disabled={busy !== null || cannotShow !== null}
                 onClick={() => void run('snap')}
-                tooltip='Keep this frame as a full-size picture of its own'
+                tooltip={
+                  cannotShow !== null
+                    ? 'The film has to load before a frame of it can be kept'
+                    : 'Keep this frame as a full-size picture of its own'
+                }
               >
                 {busy === 'snap' ? 'Saving…' : '📷 Keep this picture'}
               </Button>
@@ -425,89 +467,101 @@ export function FrameGrabber({
             onPointerUp={onPointerUp}
             onPointerCancel={onPointerUp}
           >
-            {/* biome-ignore lint/a11y/useMediaCaption: an arbitrary stored film carries no caption
-                track, and an empty <track> would advertise captions that do not exist. */}
-            <video
-              ref={videoRef}
-              src={src}
-              crossOrigin='anonymous'
-              playsInline
-              preload='metadata'
-              // Hidden — never unmounted — while the poster canvas is the visible surface. It is
-              // still the element every frame is decoded by, so removing it from the tree would
-              // stop the canvas having anything to draw.
-              style={{
-                maxWidth: '100%',
-                maxHeight: '100%',
-                filter,
-                ...(grab === 'thumbnail' ? { display: 'none' } : {}),
-              }}
-              draggable={false}
-              onLoadedMetadata={(event) => {
-                const el = event.currentTarget;
-                setDuration(Number.isFinite(el.duration) ? el.duration : 0);
-                // Seek to the playhead the stage had reached rather than to zero: real footage
-                // opens on black, on a lens cap or mid-motion-blur, and scrubbing back to the
-                // moment you were already looking at is the step this is meant to remove.
-                if (startAt > 0) el.currentTime = startAt;
-              }}
-              onTimeUpdate={(event) => setAt(event.currentTarget.currentTime)}
-            />
-            {grab === 'thumbnail' ? (
-              <canvas
-                ref={posterRef}
-                width={640}
-                height={Math.round(640 / POSTER_ASPECT)}
-                aria-label='How this film will look in the gallery'
-              />
-            ) : null}
-            {grab === 'picture' && !isFullCrop(crop) ? (
+            {cannotShow !== null ? (
+              <p className='cbpe-frame-note' role='status'>
+                {cannotShow}
+              </p>
+            ) : (
               <>
-                <div
-                  className='cbpe-shade'
-                  style={{ left: 0, right: 0, top: 0, height: `${marquee.y * 100}%` }}
-                />
-                <div
-                  className='cbpe-shade'
-                  style={{
-                    left: 0,
-                    right: 0,
-                    top: `${(marquee.y + marquee.height) * 100}%`,
-                    bottom: 0,
-                  }}
-                />
-                <div
-                  className='cbpe-shade'
+                {/* biome-ignore lint/a11y/useMediaCaption: an arbitrary stored film carries no
+                    caption track, and an empty <track> would advertise captions that do not
+                    exist. */}
+                <video
+                  ref={videoRef}
+                  // A new source is a new attempt — see `failedSrc`.
+                  key={src}
+                  src={src}
+                  crossOrigin='anonymous'
+                  playsInline
+                  preload='metadata'
+                  // Hidden — never unmounted — while the poster canvas is the visible surface. It
+                  // is still the element every frame is decoded by, so removing it from the tree
+                  // would stop the canvas having anything to draw.
                   style={{
-                    left: 0,
-                    width: `${marquee.x * 100}%`,
-                    top: `${marquee.y * 100}%`,
-                    height: `${marquee.height * 100}%`,
+                    maxWidth: '100%',
+                    maxHeight: '100%',
+                    filter,
+                    ...(grab === 'thumbnail' ? { display: 'none' } : {}),
                   }}
-                />
-                <div
-                  className='cbpe-shade'
-                  style={{
-                    left: `${(marquee.x + marquee.width) * 100}%`,
-                    right: 0,
-                    top: `${marquee.y * 100}%`,
-                    height: `${marquee.height * 100}%`,
-                  }}
-                />
-                <div
-                  className='cbpe-marquee'
-                  style={{
-                    left: `${marquee.x * 100}%`,
-                    top: `${marquee.y * 100}%`,
-                    width: `${marquee.width * 100}%`,
-                    height: `${marquee.height * 100}%`,
+                  draggable={false}
+                  onLoadedMetadata={(event) => {
+                    const el = event.currentTarget;
+                    setDuration(Number.isFinite(el.duration) ? el.duration : 0);
+                    // Seek to the playhead the stage had reached rather than to zero: real
+                    // footage opens on black, on a lens cap or mid-motion-blur, and scrubbing
+                    // back to the moment you were already looking at is the step this removes.
+                    if (startAt > 0) el.currentTime = startAt;
                   }}
+                  onTimeUpdate={(event) => setAt(event.currentTarget.currentTime)}
+                  onError={() => setFailedSrc(src)}
                 />
+                {grab === 'thumbnail' ? (
+                  <canvas
+                    ref={posterRef}
+                    width={640}
+                    height={Math.round(640 / POSTER_ASPECT)}
+                    aria-label='How this film will look in the gallery'
+                  />
+                ) : null}
+                {grab === 'picture' && !isFullCrop(crop) ? (
+                  <>
+                    <div
+                      className='cbpe-shade'
+                      style={{ left: 0, right: 0, top: 0, height: `${marquee.y * 100}%` }}
+                    />
+                    <div
+                      className='cbpe-shade'
+                      style={{
+                        left: 0,
+                        right: 0,
+                        top: `${(marquee.y + marquee.height) * 100}%`,
+                        bottom: 0,
+                      }}
+                    />
+                    <div
+                      className='cbpe-shade'
+                      style={{
+                        left: 0,
+                        width: `${marquee.x * 100}%`,
+                        top: `${marquee.y * 100}%`,
+                        height: `${marquee.height * 100}%`,
+                      }}
+                    />
+                    <div
+                      className='cbpe-shade'
+                      style={{
+                        left: `${(marquee.x + marquee.width) * 100}%`,
+                        right: 0,
+                        top: `${marquee.y * 100}%`,
+                        height: `${marquee.height * 100}%`,
+                      }}
+                    />
+                    <div
+                      className='cbpe-marquee'
+                      style={{
+                        left: `${marquee.x * 100}%`,
+                        top: `${marquee.y * 100}%`,
+                        width: `${marquee.width * 100}%`,
+                        height: `${marquee.height * 100}%`,
+                      }}
+                    />
+                  </>
+                ) : null}
+                {grab === 'picture' && isFullCrop(crop) ? (
+                  <span className='cbpe-hint'>Drag across the frame to keep just part of it</span>
+                ) : null}
               </>
-            ) : null}
-            {grab === 'picture' && isFullCrop(crop) ? (
-              <span className='cbpe-hint'>Drag across the frame to keep just part of it</span>
-            ) : null}
+            )}
           </div>
 
           <label className='cbpe-slider'>

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

@@ -0,0 +1,90 @@
+/**
+ * The picture editor, at the one edge that turned out to be reportable: WHAT IT DOES WHEN IT
+ * HAS NO PICTURE.
+ *
+ * ── Why this file exists ───────────────────────────────────────────────────────────────
+ * Owner, `ideas/collections-09-14.md`: *"When I click the turn the video button I see a black
+ * screen."* That was `VideoTurner`, and the cause — a dialog mounted over the RAW gallery row
+ * rather than over the item's resolved media — was shared by four siblings, this one included.
+ * It was `src={item.url ?? ''}`, and a `MediaGalleryItem` is allowed to carry no `url` at all:
+ * `resolveMedia` is the documented path for a signed URL, and it is what the reporting app
+ * uses. An `<img>` with an empty source draws nothing and, on a picture that never existed,
+ * never even fires `error`.
+ *
+ * 🔴 And here the stake is a step above a bad preview, because this dialog BAKES PIXELS. An
+ * empty frame came with a live row of sliders over it and a Save that read the `<img>` back
+ * through a canvas — which either did nothing at all or wrote a blank over a photograph. So
+ * the editor states the reason AND holds the saves; the gestures themselves are
+ * `pictureEdit.ts`'s and are unit-tested there.
+ *
+ * That the gallery hands over the RESOLVED source is the other half, asserted in
+ * `MediaGallery.spec.tsx` ("the PICTURE EDITOR is handed the RESOLVED source").
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import type React from 'react';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import { PictureEditor } from './PictureEditor';
+
+afterEach(cleanup);
+
+// The dialog is a portal, so everything it renders is queried off `document.body`.
+const body = () => document.body;
+
+const openWith = (props: Partial<React.ComponentProps<typeof PictureEditor>>) =>
+  render(
+    <PictureEditor
+      src=''
+      fileName='scan.jpg'
+      onClose={() => {}}
+      onSave={() => {}}
+      allowReplace
+      {...props}
+    />,
+  );
+
+describe('PictureEditor — when it cannot show the picture', () => {
+  test('🔴 no source at all is a stated reason, not an empty frame', () => {
+    const { getByRole } = openWith({});
+    expect(body().querySelector('.cbpe-frame img')).toBeNull();
+    expect(getByRole('status').textContent).toContain('no picture to show');
+  });
+
+  test('🔴 a source that fails to load says so too', () => {
+    const { getByRole, queryByRole } = openWith({ src: '/files/gone.jpg' });
+    const picture = body().querySelector('.cbpe-frame img');
+    expect(picture).not.toBeNull();
+    expect(queryByRole('status')).toBeNull();
+    fireEvent.error(picture as HTMLImageElement);
+    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 edit" at somebody
+    // whose photograph 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 picture');
+  });
+
+  test('🔴 BOTH saves are held — a bake with no picture can only write a blank', () => {
+    const { getByRole } = openWith({});
+    // Turn it, so the only thing standing between the press and a save is the missing picture.
+    fireEvent.click(getByRole('button', { name: '↻ Right' }));
+    for (const name of ['Save as a new copy', 'Replace the original']) {
+      const button = getByRole('button', { name }) as HTMLButtonElement;
+      // Disabled and still on screen — `DESIGN.md`'s rule for a control that cannot work here.
+      expect(button.disabled, name).toBe(true);
+      expect(body().contains(button)).toBe(true);
+    }
+  });
+
+  test('a picture that loads leaves the saves exactly as they were', () => {
+    // The ordinary path must be untouched by any of the above: no note, and a Save that is
+    // available the moment there is an edit to save.
+    const { getByRole, queryByRole } = openWith({ src: '/files/scan.jpg' });
+    expect(queryByRole('status')).toBeNull();
+    fireEvent.click(getByRole('button', { name: '↻ Right' }));
+    expect((getByRole('button', { name: 'Save as a new copy' }) as HTMLButtonElement).disabled).toBe(
+      false,
+    );
+  });
+});

package/src/react/media/PictureEditor.tsx

@@ -44,8 +44,23 @@ export interface PictureEditResult {
 }
 
 export interface PictureEditorProps {
-  /** The picture to edit. 🔴 Must be reachable with CORS — see {@link bakePicture}. */
+  /**
+   * The picture to edit. 🔴 Must be reachable with CORS — see {@link bakePicture}.
+   *
+   * 🔴 The RESOLVED source, not whatever URL field a record happens to carry — see
+   * `MediaGallery`'s `EditPictureDialog`. A gallery item is allowed to carry no `url` at all
+   * (`resolveMedia` is the documented path for a signed URL), and an `<img>` with an empty
+   * source never loads, never errors, and leaves this editor showing a blank frame it would
+   * then BAKE. An empty string here is a stated reason and a disabled Save rather than a
+   * silent one.
+   */
   src: string;
+  /**
+   * True while the app is still finding the picture (a signed URL being minted, bytes becoming
+   * an object URL). It is the difference between "on its way" and "cannot be shown", and only
+   * the caller knows which.
+   */
+  resolving?: boolean;
   fileName?: string;
   /** The MIME to bake to. Defaults to JPEG, which is what a photograph should come back as. */
   mimeType?: string;
@@ -75,6 +90,7 @@ export interface PictureEditorProps {
  */
 export function PictureEditor({
   src,
+  resolving = false,
   fileName,
   mimeType,
   open = true,
@@ -93,6 +109,26 @@ export function PictureEditor({
   const frameRef = React.useRef<HTMLDivElement | null>(null);
   const dragFrom = React.useRef<{ x: number; y: number } | null>(null);
   const [natural, setNatural] = React.useState<{ width: number; height: number } | 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` and `VideoTurner` keep.
+  const [failedSrc, setFailedSrc] = React.useState<string | null>(null);
+
+  /**
+   * Why there is no picture on the frame — `null` when there is one.
+   *
+   * 🔴 The editor SAYS this instead of showing an empty frame, and here the stakes are a step
+   * above the turner's: this dialog BAKES pixels. An empty `src` used to mean a blank frame,
+   * sliders that appeared to work, and a Save that either did nothing (no `<img>` to read) or
+   * wrote a blank picture over somebody's photograph. So the reason is stated AND the saves
+   * are held — there is no edit that can honestly be applied to a picture nobody has.
+   */
+  const cannotShow: string | null = resolving
+    ? 'Finding this picture…'
+    : !src
+      ? 'This file has no picture to show here, so there is nothing to edit. Nothing has been changed.'
+      : failedSrc === src
+        ? 'This picture could not be loaded, so there is nothing to edit. Nothing has been changed.'
+        : null;
 
   const dirty = isEdited(edit);
   const crop = edit.crop ?? FULL_CROP;
@@ -289,9 +325,15 @@ export function PictureEditor({
           primary={
             <Button
               variant='primary'
-              disabled={!dirty || saving !== null}
+              // 🔴 Held while there is no picture: the bake reads pixels back off the `<img>`,
+              // so a save here would either do nothing or write a blank. See `cannotShow`.
+              disabled={!dirty || saving !== null || cannotShow !== null}
               onClick={() => void save('copy')}
-              tooltip='Keep the original and save this version beside it'
+              tooltip={
+                cannotShow !== null
+                  ? 'The picture has to load before an edit of it can be saved'
+                  : 'Keep the original and save this version beside it'
+              }
             >
               {saving === 'copy' ? 'Saving…' : 'Save as a new copy'}
             </Button>
@@ -300,9 +342,13 @@ export function PictureEditor({
           {allowReplace ? (
             <Button
               variant='ghost'
-              disabled={!dirty || saving !== null}
+              disabled={!dirty || saving !== null || cannotShow !== null}
               onClick={() => void save('replace')}
-              tooltip='Overwrite the stored file with this version'
+              tooltip={
+                cannotShow !== null
+                  ? 'The picture has to load before an edit of it can be saved'
+                  : 'Overwrite the stored file with this version'
+              }
             >
               {saving === 'replace' ? 'Saving…' : 'Replace the original'}
             </Button>
@@ -320,24 +366,33 @@ export function PictureEditor({
             onPointerUp={onPointerUp}
             onPointerCancel={onPointerUp}
           >
-            <img
-              ref={imgRef}
-              src={src}
-              alt={fileName ?? 'The picture being edited'}
-              /*
-               * 🔴 Unconditional, not "only when a save is coming". Whether a canvas may be read
-               * back is decided when the browser FETCHES the picture, so a copy already cached
-               * without CORS stays unreadable and the refusal only surfaces at `toBlob`. Same
-               * trap `posterFraming.ts` documents for video.
-               */
-              crossOrigin='anonymous'
-              draggable={false}
-              onLoad={(event) => {
-                const el = event.currentTarget;
-                setNatural({ width: el.naturalWidth, height: el.naturalHeight });
-              }}
-              style={{ transform: previewTransform(edit), filter: lightFilter(edit.light) }}
-            />
+            {cannotShow === null ? (
+              <img
+                ref={imgRef}
+                // A new source is a new attempt — see `failedSrc`.
+                key={src}
+                src={src}
+                alt={fileName ?? 'The picture being edited'}
+                /*
+                 * 🔴 Unconditional, not "only when a save is coming". Whether a canvas may be
+                 * read back is decided when the browser FETCHES the picture, so a copy already
+                 * cached without CORS stays unreadable and the refusal only surfaces at
+                 * `toBlob`. Same trap `posterFraming.ts` documents for video.
+                 */
+                crossOrigin='anonymous'
+                draggable={false}
+                onLoad={(event) => {
+                  const el = event.currentTarget;
+                  setNatural({ width: el.naturalWidth, height: el.naturalHeight });
+                }}
+                onError={() => setFailedSrc(src)}
+                style={{ transform: previewTransform(edit), filter: lightFilter(edit.light) }}
+              />
+            ) : (
+              <p className='cbpe-frame-note' role='status'>
+                {cannotShow}
+              </p>
+            )}
             {/*
              * The sharpened copy, clipped to the seam. `clip-path` rather than a width, so the
              * two pictures stay laid out identically and the seam moves across ONE photograph

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

@@ -0,0 +1,86 @@
+/**
+ * The sections dialog, at the one edge that turned out to be reportable: WHAT IT DOES WHEN IT
+ * HAS NO FILM.
+ *
+ * ── Why this file exists ───────────────────────────────────────────────────────────────
+ * Owner, `ideas/collections-09-14.md`: *"When I click the turn the video button I see a black
+ * screen."* That was `VideoTurner`, and the cause — a dialog mounted over the RAW gallery row
+ * rather than over the item's resolved media — was shared by four siblings, this one included.
+ * It was `src={item.streamUrl ?? item.url ?? ''}`, and a `MediaGalleryItem` is allowed to carry
+ * neither field: `resolveMedia` is the documented path for a signed URL, and it is what the
+ * reporting app uses. A `<video>` with an empty source never loads, never fires `error` and
+ * paints black forever — which is why the only report anybody could file was "a black screen".
+ *
+ * 🔴 The chaptering rules are `videoChapters.ts`'s and are unit-tested there. What is asserted
+ * here is this dialog's own bargain when the film does not arrive: it says so, and it keeps the
+ * sections editable — a section is a name and a timestamp stored BESIDE the film, so refusing
+ * to let somebody fix a typo because the player is empty would turn a preview failure into a
+ * lost capability.
+ *
+ * That the gallery hands over the RESOLVED source is the other half, asserted in
+ * `MediaGallery.spec.tsx` ("the SECTIONS dialog is handed the RESOLVED source").
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import type React from 'react';
+import { cleanup, fireEvent, render, waitFor } from '@testing-library/react';
+import { VideoChapterEditor } from './VideoChapterEditor';
+import type { VideoChapter } from './videoChapters';
+
+afterEach(cleanup);
+
+// The dialog is a portal, so everything it renders is queried off `document.body`.
+const body = () => document.body;
+
+const openWith = (props: Partial<React.ComponentProps<typeof VideoChapterEditor>>) =>
+  render(
+    <VideoChapterEditor
+      src=''
+      name='clip.mp4'
+      durationSeconds={120}
+      onClose={() => {}}
+      onSubmit={() => {}}
+      {...props}
+    />,
+  );
+
+describe('VideoChapterEditor — when it cannot show the film', () => {
+  test('🔴 no source at all is a stated reason, not a black box', () => {
+    const { getByRole } = openWith({});
+    expect(body().querySelector('video')).toBeNull();
+    const said = getByRole('status').textContent ?? '';
+    expect(said).toContain('no video source');
+    // …and it says what is still true: the sections are metadata beside the film.
+    expect(said).toContain('still be edited and saved');
+  });
+
+  test('🔴 a source that fails to load says so too', () => {
+    const { getByRole, queryByRole } = openWith({ src: '/films/gone.mp4' });
+    const film = body().querySelector('video');
+    expect(film).not.toBeNull();
+    expect(queryByRole('status')).toBeNull();
+    fireEvent.error(film 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', () => {
+    const { getByRole } = openWith({ src: '', resolving: true });
+    expect(getByRole('status').textContent).toContain('Finding this film');
+  });
+
+  test('🔴 the sections it already has can still be renamed and SAVED with no film at all', async () => {
+    const chapters: VideoChapter[] = [{ startSeconds: 12, title: 'The speeches' }];
+    const saved: VideoChapter[][] = [];
+    const { getByRole, getByLabelText } = openWith({
+      chapters,
+      onSubmit: (next) => {
+        saved.push(next);
+      },
+    });
+    fireEvent.change(getByLabelText('Name of the section at 0:12.0'), {
+      target: { value: 'The toasts' },
+    });
+    fireEvent.click(getByRole('button', { name: 'Save sections' }));
+    // `waitFor`, because the save is async — and with it the state it sets lands inside act().
+    await waitFor(() => expect(saved).toEqual([[{ startSeconds: 12, title: 'The toasts' }]]));
+  });
+});