cursedbelt 3.0.2 → 4.1.0

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

@@ -29,7 +29,7 @@ for (const prop of ['clientHeight', 'offsetHeight'] as const) {
 }
 HTMLElement.prototype.getBoundingClientRect = () => RECT;
 
-import { MediaGallery, stagePlayableVideo } from './MediaGallery';
+import { MediaGallery, galleryTileLine, stagePlayableVideo } from './MediaGallery';
 import type { MediaGalleryItem } from './types';
 
 afterEach(cleanup);
@@ -294,7 +294,7 @@ describe('MediaGallery multi-select (opt-in)', () => {
       fireEvent.click(boxes(container)[0] as HTMLInputElement);
       expect(quiet(container)).toHaveLength(0);
       // …and Clear puts the grid back to quiet rather than leaving it armed forever.
-      fireEvent.click(getByRole('button', { name: 'Clear' }));
+      fireEvent.click(getByRole('button', { name: 'Clear the selection' }));
       expect(quiet(container)).toHaveLength(ITEMS.length);
     });
   });
@@ -307,9 +307,11 @@ describe('MediaGallery detail view', () => {
     // The stage shows the full image (url, not thumbnail).
     const stage = container.querySelector('.cbgd-stage-img img');
     expect(stage?.getAttribute('src')).toBe('/files/img1');
-    // Related grid below with the OTHER items.
-    expect(getByText('More files')).toBeDefined();
+    // The strip below, holding every displayed file — the open one included, which is why the
+    // heading is no longer "More files". See the suite at the foot of this file.
+    expect(getByText('Files')).toBeDefined();
     expect(getByRole('button', { name: 'Open clip.mp4' })).toBeDefined();
+    expect(getByRole('button', { name: 'Open beach.jpg' })).toBeDefined();
     // Download + fullscreen affordances.
     expect(getByRole('link', { name: /download/i }).getAttribute('href')).toBe('/files/img1');
     expect(getByRole('button', { name: /fullscreen/i })).toBeDefined();
@@ -477,6 +479,37 @@ describe('MediaGallery — turning a video', () => {
     expect(frame?.getAttribute('data-turned')).toBe('true');
   });
 
+  /**
+   * 🔴 A quarter turn has to REFIT the panel, not just spin the picture inside it.
+   *
+   * Owner, `ideas/collections-09-14.md`: *"If I rotate a portait style video 90 degrees it
+   * should be changed to fit the wide screen panel if I save it so I can watch it like it was
+   * recorded with wide screen."* The rotation above shipped without the fit, and the assertion
+   * above is exactly what let it through: it reads the transform and stops there.
+   *
+   * The fit is a pair of declarations rather than a scale factor on that transform, and the
+   * stylesheet says why at length — a scale does not know the film's shape, so it can only be
+   * right for footage whose aspect is the panel's inverse and crops everything else. What a
+   * happy-dom test CAN prove is that the axis swap is declared where the turn is applied; that
+   * the film then covers the panel is a rectangle, measured in `e2e/video-turn.spec.ts`.
+   */
+  test('🔴 a quarter turn also carries the axis-swapped FIT, or it is a film in a letterbox', () => {
+    const css = readFileSync(join(import.meta.dir, 'mediaGallery.css'), 'utf8');
+    const block = css
+      .slice(css.indexOf(".cbmg-stage-turn[data-turned='true'] video"))
+      .slice(0, css.slice(css.indexOf(".cbmg-stage-turn[data-turned='true'] video")).indexOf('}') + 1);
+    // Width read from the container's BLOCK size and height from its INLINE size — the swap.
+    expect(block).toContain('width: 100cqb');
+    expect(block).toContain('height: 100cqi');
+    // `max-*` alone is what shipped, and it can only shrink: a clip the player had already
+    // sized stayed exactly as it was, which is the pillar in the middle of a black panel.
+    expect(block).not.toContain('max-block-size: 100cqi');
+    expect(block).not.toContain('max-inline-size: 100cqb');
+    // A rotation turns about the element's own centre, so the element has to BE at the panel's
+    // centre — off-centre by a quarter of the panel is what the first browser run measured.
+    expect(css).toContain(".cbmg-stage-turn[data-turned='true'] [data-media-provider]");
+  });
+
   test('an UNturned clip adds no box, no layer and no transform', () => {
     const plain: MediaGalleryItem[] = [{ ...TURNED[0], orientation: undefined } as MediaGalleryItem];
     const { container, getByRole } = render(<MediaGallery items={plain} nativeVideoStage />);
@@ -489,26 +522,61 @@ describe('MediaGallery — turning a video', () => {
   });
 
   test('the Turn control is offered on a film, and only when the app can store the answer', () => {
+    // By accessible NAME rather than by text: the pill is an icon now, so `queryByText`
+    // would find nothing in either arm and the test would pass without proving anything.
     const withoutHandler = render(<MediaGallery items={TURNED} />);
     fireEvent.click(withoutHandler.getByRole('button', { name: 'Open clip.mp4' }));
-    expect(withoutHandler.queryByText('⟳ Turn video')).toBeNull();
+    expect(withoutHandler.queryByRole('button', { name: 'Turn video' })).toBeNull();
     withoutHandler.unmount();
 
     const withHandler = render(<MediaGallery items={TURNED} onSaveOrientation={() => {}} />);
     fireEvent.click(withHandler.getByRole('button', { name: 'Open clip.mp4' }));
-    expect(withHandler.queryByText('⟳ Turn video')).not.toBeNull();
+    expect(withHandler.queryByRole('button', { name: 'Turn video' })).not.toBeNull();
+  });
+
+  /**
+   * 🔴 The dialog is handed the RESOLVED source — the owner's *"When I click the turn the video
+   * button I see a black screen."*
+   *
+   * It read `item.streamUrl ?? item.url` straight off the row, and an item is allowed to carry
+   * neither: `resolveMedia` is the documented path for a signed URL, and it is what the app that
+   * reported this uses. Both fields `undefined` meant `src=''`, which React renders as a
+   * `<video>` with no source at all — an element that never loads, never errors, and paints
+   * black forever. Every other surface in the gallery reads an item through `useItemMedia`;
+   * this is the one that did not.
+   */
+  test('🔴 the turn dialog is handed the RESOLVED source, not the raw row', async () => {
+    const signed: MediaGalleryItem[] = [
+      {
+        id: 'vid2',
+        name: 'signed.mp4',
+        mime: 'video/mp4',
+        createdAt: 10,
+        // No `url` and no `streamUrl`: the app mints them when something needs them.
+        resolveMedia: async () => ({ streamUrl: '/signed/vid2', posterUrl: '/signed/poster2' }),
+      },
+    ];
+    const view = render(<MediaGallery items={signed} onSaveOrientation={() => {}} />);
+    await waitFor(() => expect(view.queryByRole('button', { name: 'Open signed.mp4' })).not.toBeNull());
+    fireEvent.click(view.getByRole('button', { name: 'Open signed.mp4' }));
+    fireEvent.click(view.getByRole('button', { name: 'Turn video' }));
+    // The dialog is a lazy chunk and a portal — wait for it, then read it off `baseElement`.
+    await waitFor(() => expect(view.queryByText('Turn this video')).not.toBeNull());
+    const preview = view.baseElement.querySelector<HTMLVideoElement>('.cbpe-frame-film video');
+    expect(preview?.getAttribute('src')).toBe('/signed/vid2');
+    expect(preview?.getAttribute('poster')).toBe('/signed/poster2');
   });
 
   test('🔴 a PICTURE never gets the video control — it already has the fuller editor', () => {
     const picture: MediaGalleryItem[] = [
       { id: 'img1', name: 'beach.jpg', url: '/files/img1', createdAt: 1 },
     ];
-    const { getByRole, queryByText } = render(
+    const { getByRole, queryByRole } = render(
       <MediaGallery items={picture} onSaveOrientation={() => {}} />,
     );
     fireEvent.click(getByRole('button', { name: 'Open beach.jpg' }));
     // Two controls that both say "turn" on the same item is the confusion the split avoids.
-    expect(queryByText('⟳ Turn video')).toBeNull();
+    expect(queryByRole('button', { name: 'Turn video' })).toBeNull();
   });
 });
 
@@ -523,11 +591,20 @@ describe('MediaGallery — turning a video', () => {
  * kind of thing a refactor drops silently.
  */
 describe('MediaGallery — the playback run', () => {
-  /** Press the cycling button until it reads `label`, and return the button. */
+  /**
+   * Press the cycling button until it reads `label`, and return the button.
+   *
+   * 🔴 Read off the ACCESSIBLE NAME, not `textContent`. The pill is a bare glyph since
+   * 2026-09-16 (owner: *"icons only, instead of words in the strip of tools"*), so its text
+   * content is the empty string for all five settings — a `textContent` probe would loop six
+   * times and throw on every call, which is how a cosmetic change takes a behavioural suite
+   * with it. The name is where the value lives now, and asserting through it is also the
+   * point: it is the thing a screen reader gets.
+   */
   function cycleTo(getByRole: ReturnType<typeof render>['getByRole'], label: RegExp) {
     for (let i = 0; i < 6; i++) {
       const button = getByRole('button', { name: /^When an item ends:/ });
-      if (label.test(button.textContent ?? '')) return button;
+      if (label.test(button.getAttribute('aria-label') ?? '')) return button;
       fireEvent.click(button);
     }
     throw new Error(`the playback button never reached ${label}`);
@@ -792,6 +869,162 @@ describe('MediaGallery table view', () => {
   });
 });
 
+/**
+ * SIZE and LENGTH, reported where they are useful — the `meta` prop.
+ *
+ * Three asks from two drafts, one surface. `ideas/collections-09-14.md`: *"In collections I
+ * want to see the exact file size in bytes as a column option so I can easily tell if two
+ * files are the exact same byte size to help me know if they are duplicates or not"* and
+ * *"in the grid view show the video length instead of the size."* `ideas/binary-server-09-15.md`
+ * asked for both facts on the same tiles and guessed the right home: *"maybe controlled
+ * through param on media gallery in cb."*
+ *
+ * 🔴 Every one of these is OFF unless asked for, which is why the last test in the block is
+ * the one that would catch a regression in four apps rather than in this feature.
+ */
+describe('MediaGallery — size and length', () => {
+  /** Two near-duplicates one byte apart, and a document. `formatBytes` calls both films `1.3 GB`. */
+  const MEASURED: MediaGalleryItem[] = [
+    {
+      id: 'v1',
+      name: 'holiday.mp4',
+      category: 'video',
+      streamUrl: '/files/v1',
+      posterUrl: '/thumbs/v1',
+      durationSeconds: 187,
+      sizeBytes: 1_402_653_184,
+      createdAt: 30,
+    },
+    {
+      id: 'v2',
+      name: 'holiday-copy.mp4',
+      category: 'video',
+      streamUrl: '/files/v2',
+      posterUrl: '/thumbs/v2',
+      durationSeconds: 187,
+      sizeBytes: 1_402_653_185,
+      createdAt: 20,
+    },
+    { id: 'd1', name: 'notes.pdf', url: '/files/d1', sizeBytes: 5_242_880, createdAt: 10 },
+  ];
+
+  /** The caption's second line for the tile whose title is `name` — see `GalleryMeta`. */
+  const tileLine = (container: HTMLElement, name: string): string | null => {
+    const block = Array.from(container.querySelectorAll('.cbgd-meta')).find(
+      (meta) => meta.querySelector('.cbgd-meta-title')?.textContent === name,
+    );
+    return block?.querySelector('.cbgd-meta-line')?.textContent ?? null;
+  };
+
+  const showTable = (getByRole: ReturnType<typeof render>['getByRole']): void => {
+    fireEvent.click(getByRole('button', { name: /Table/ }));
+  };
+
+  test('a video tile leads with its running time, and a document keeps its size', () => {
+    const { container } = render(
+      <MediaGallery items={MEASURED} meta={{ tileMeasure: true }} />,
+    );
+    expect(tileLine(container, 'holiday.mp4')).toBe('3:07');
+    // Everything that is not time-based is unchanged by the same switch: a PDF has no
+    // running time, and its size is the measurement that means something for it.
+    expect(tileLine(container, 'notes.pdf')).toBe('5.0 MB');
+  });
+
+  test('tags keep their line and the running time joins them on it', () => {
+    // 🔴 Never a fourth line: the caption block is a fixed 65px (`CBGD_META_HEIGHT`), and a
+    // tile taller than its neighbour is what made rows lap each other across the fleet.
+    const tagged: MediaGalleryItem[] = [
+      { ...(MEASURED[0] as MediaGalleryItem), tags: ['holiday', 'beach'] },
+    ];
+    const { container } = render(<MediaGallery items={tagged} meta={{ tileMeasure: true }} />);
+    expect(tileLine(container, 'holiday.mp4')).toBe('holiday · beach · 3:07');
+  });
+
+  test('a film nobody measured falls back to its size, never to an empty caption', () => {
+    const unmeasured: MediaGalleryItem[] = [
+      { id: 'v9', name: 'unknown.mp4', category: 'video', streamUrl: '/files/v9', sizeBytes: 2048 },
+      { id: 'v8', name: 'nothing.mp4', category: 'video', streamUrl: '/files/v8' },
+    ];
+    const { container } = render(<MediaGallery items={unmeasured} meta={{ tileMeasure: true }} />);
+    expect(tileLine(container, 'unknown.mp4')).toBe('2.0 KB');
+    // Neither fact known: the same em dash the table's columns show, not a blank line.
+    expect(tileLine(container, 'nothing.mp4')).toBe('—');
+  });
+
+  test('🔴 the exact-bytes column separates two files a rounded size cannot', () => {
+    const { getByRole, container } = render(
+      <MediaGallery items={MEASURED} meta={{ exactBytes: true }} />,
+    );
+    showTable(getByRole);
+    expect(container.querySelector('th.cbgt-cell--bytes')?.textContent).toBe('Bytes');
+    const bytesFor = (name: string): string | undefined =>
+      Array.from(container.querySelectorAll('.cbgt-row'))
+        .find((row) => row.textContent?.includes(name))
+        ?.querySelector('.cbgt-cell--bytes')?.textContent ?? undefined;
+    // The whole ask: one byte apart, and the column says so.
+    expect(bytesFor('holiday.mp4')).toMatch(/^1\D?402\D?653\D?184$/);
+    expect(bytesFor('holiday-copy.mp4')).toMatch(/^1\D?402\D?653\D?185$/);
+    expect(bytesFor('holiday.mp4')).not.toBe(bytesFor('holiday-copy.mp4'));
+    // …while the rounded column beside it calls them the same file, which is the defect.
+    const sizeFor = (name: string): string | undefined =>
+      Array.from(container.querySelectorAll('.cbgt-row'))
+        .find((row) => row.textContent?.includes(name))
+        ?.querySelectorAll('.cbgt-cell--num')[0]?.textContent ?? undefined;
+    expect(sizeFor('holiday.mp4')).toBe(sizeFor('holiday-copy.mp4'));
+  });
+
+  test('the column is an ADDITION — Size, Length and the sort are where they were', () => {
+    const { getByRole, container } = render(
+      <MediaGallery items={MEASURED} meta={{ exactBytes: true }} />,
+    );
+    showTable(getByRole);
+    // Without the direction glyph a sorted header carries — the active sort is Date's, and
+    // this test is about which columns exist and in what order.
+    const headers = Array.from(container.querySelectorAll('thead th')).map((th) =>
+      th.textContent?.replace(/[▲▼]/g, '').trim(),
+    );
+    expect(headers).toEqual(['Preview', 'Name', 'Kind', 'Size', 'Bytes', 'Length', 'Date']);
+    // The size SORT is still the rounded column's, and it still sorts on the number: the
+    // exact column carries no sort of its own, so there is one ordering, not two.
+    fireEvent.click(container.querySelector('.cbgt-cell--num .cbgt-sort') as HTMLElement);
+    expect(container.querySelector('.cbgt-row')?.textContent).toContain('holiday-copy.mp4');
+  });
+
+  test('🔴 a consumer that passes nothing renders exactly what it rendered before', () => {
+    const { getByRole, container } = render(<MediaGallery items={MEASURED} />);
+    // The grid: a film shows its rounded SIZE, the way it always has.
+    expect(tileLine(container, 'holiday.mp4')).toBe('1.3 GB');
+    showTable(getByRole);
+    // The table: six columns, no exact-bytes cell anywhere.
+    expect(container.querySelectorAll('thead th')).toHaveLength(6);
+    expect(container.querySelector('.cbgt-cell--bytes')).toBeNull();
+  });
+
+  /**
+   * The line itself, called directly — the branch table is wider than any fixture, and two of
+   * these combinations never appear in a rendered tile in this file.
+   */
+  test('the caption line, branch by branch', () => {
+    const film = MEASURED[0] as MediaGalleryItem;
+    expect(galleryTileLine(film)).toBe('1.3 GB');
+    expect(galleryTileLine(film, { measure: true })).toBe('3:07');
+    // Only the first three tags, as the line has always done.
+    expect(
+      galleryTileLine({ ...film, tags: ['a', 'b', 'c', 'd'] }, { measure: true }),
+    ).toBe('a · b · c · 3:07');
+    // An AUDIO track is time-based too — the same argument as a film, and the same fix.
+    expect(
+      galleryTileLine(
+        { id: 'a1', name: 'memo.m4a', category: 'audio', durationSeconds: 65, sizeBytes: 900 },
+        { measure: true },
+      ),
+    ).toBe('1:05');
+    // Off, nothing about the line moves — tags win, then the size, then nothing at all.
+    expect(galleryTileLine({ ...film, tags: ['holiday'] })).toBe('holiday');
+    expect(galleryTileLine({ id: 'x', name: 'bare.bin' })).toBeNull();
+  });
+});
+
 /**
  * 🔴 The render loop that took `apps/family`'s `/#/p/<id>/media` off the air.
  *
@@ -1006,6 +1239,90 @@ describe('🔴 the stage hands the player every transport the app resolved', ()
     expect(video.processingStatus).toBe('processing');
     expect(video.durationSeconds).toBe(12);
   });
+
+  /*
+   * 🔴 The named sections are the FOURTH field to come down this road, and the only assertion
+   * that can catch it being forgotten. The header above this function names the other three:
+   * each was resolved by the app, carried on the item, and then simply not listed in the
+   * mapping — so the feature was invisible with nothing anywhere reporting a fault. A chapter
+   * list would fail exactly that way, and more quietly than the rest: the player would draw a
+   * bare scrub bar, which is precisely what a video with no chapters is supposed to look like.
+   */
+  test('🔴 the named sections reach the player', () => {
+    const chaptered: MediaGalleryItem = {
+      ...item,
+      chapters: [
+        { startSeconds: 0, title: 'Cold open' },
+        { startSeconds: 6, title: 'The walk home' },
+      ],
+    };
+    const video = stagePlayableVideo(chaptered, {}, '/files/v1.web.mp4');
+    expect(video.chapters).toEqual([
+      { startSeconds: 0, title: 'Cold open' },
+      { startSeconds: 6, title: 'The walk home' },
+    ]);
+  });
+
+  test('a video with no sections leaves the field ABSENT, not empty', () => {
+    // An empty chapters track is not neutral: the layout draws a chapter-title area and a menu
+    // entry for a film that has no chapters.
+    expect('chapters' in stagePlayableVideo(item, {}, '/files/v1.web.mp4')).toBe(false);
+    expect('chapters' in stagePlayableVideo({ ...item, chapters: [] }, {}, '/files/v1.web.mp4')).toBe(
+      false,
+    );
+  });
+});
+
+/**
+ * Naming the parts of a film — the owner's `media-gallery-cb.md` ask, at the component edge.
+ *
+ * 🔴 What the chapter MODEL does is asserted in `react/media/videoChapters.spec.ts`, where it
+ * is pure. What can only be checked here is the capability rule: the control exists exactly
+ * when the app passed somewhere to put the answer, and never otherwise. That rule is the whole
+ * of how a feature gets turned on in this component — there is no flag and no config — so it
+ * is the thing a refactor can silently invert.
+ */
+describe('MediaGallery — naming the sections of a video', () => {
+  const FILM: MediaGalleryItem[] = [
+    {
+      id: 'vid1',
+      name: 'clip.mp4',
+      streamUrl: '/files/vid1',
+      mime: 'video/mp4',
+      createdAt: 10,
+      durationSeconds: 60,
+    },
+  ];
+
+  test('🔴 the Sections control appears only when the app can STORE the answer', () => {
+    const withoutHandler = render(<MediaGallery items={FILM} />);
+    fireEvent.click(withoutHandler.getByRole('button', { name: 'Open clip.mp4' }));
+    expect(withoutHandler.queryByRole('button', { name: 'Sections' })).toBeNull();
+    withoutHandler.unmount();
+
+    const withHandler = render(<MediaGallery items={FILM} onSaveChapters={() => {}} />);
+    fireEvent.click(withHandler.getByRole('button', { name: 'Open clip.mp4' }));
+    expect(withHandler.queryByRole('button', { name: 'Sections' })).not.toBeNull();
+  });
+
+  test('🔴 a PICTURE never gets it — there is no timeline to put a marker on', () => {
+    const picture: MediaGalleryItem[] = [
+      { id: 'img1', name: 'beach.jpg', url: '/files/img1', createdAt: 1 },
+    ];
+    const { getByRole, queryByRole } = render(
+      <MediaGallery items={picture} onSaveChapters={() => {}} />,
+    );
+    fireEvent.click(getByRole('button', { name: 'Open beach.jpg' }));
+    expect(queryByRole('button', { name: 'Sections' })).toBeNull();
+  });
+
+  test('🔴 READING sections needs no handler — only writing them is gated', () => {
+    // An app that merely lists someone else's films still shows their chapters; what it cannot
+    // do is save new ones. Asserted on the mapping, because the rendered player is a Vidstack
+    // custom element happy-dom never brings to life.
+    const item = { ...(FILM[0] as MediaGalleryItem), chapters: [{ startSeconds: 3, title: 'Two' }] };
+    expect(stagePlayableVideo(item, {}, '/files/vid1')?.chapters).toHaveLength(1);
+  });
 });
 
 /**
@@ -1300,3 +1617,832 @@ describe('🔴 Preview all reaches the TABLE, not only the grid', () => {
     expect(view.container.querySelectorAll('.cbgt-play')).toHaveLength(1);
   });
 });
+
+/**
+ * 🔴 A CAPABILITY DIALOG MAY NOT OUTLIVE THE FILE IT WAS OPENED FOR.
+ *
+ * The owner, `ideas/collections-09-14.md`, 2026-09-14, on the thumbnail chooser:
+ *
+ *   *"In collections app I chose a thumbnail for a video but then I could not get back to the
+ *   normal viewing area … Clicking on other folders also did not move to view them and the
+ *   thumbnail selection screen for the first video stayed on the screen. Selecting other
+ *   sidebar files and icons should also leave that screen."*
+ *
+ * The reset effect keyed on `selectedId` cleared the rename field and the picture editor and
+ * nothing else, so four of the five dialogs survived the selection that opened them — and a
+ * surviving dialog is not merely stale, it is WRONG: its title, its `src`, its carried playhead
+ * and the item every save handler is closed over all still name the file you navigated away
+ * from. The worst shape that has is the chooser's, because its Save writes a thumbnail onto
+ * whichever film it is still holding.
+ *
+ * Driven through the CONTROLLED `selectedId`, because that is the wire the sidebar is on: an
+ * app moves the selection and the gallery has to follow.
+ */
+describe('🔴 selecting another file leaves the thumbnail chooser', () => {
+  const VIDEOS: MediaGalleryItem[] = [
+    {
+      id: 'vid1',
+      name: 'first.mp4',
+      streamUrl: '/files/vid1',
+      mime: 'video/mp4',
+      durationSeconds: 12,
+      createdAt: 20,
+    },
+    {
+      id: 'vid2',
+      name: 'second.mp4',
+      streamUrl: '/files/vid2',
+      mime: 'video/mp4',
+      durationSeconds: 9,
+      createdAt: 10,
+    },
+  ];
+
+  const gallery = (selectedId: string) => (
+    <MediaGallery
+      items={VIDEOS}
+      selectedId={selectedId}
+      nativeVideoStage
+      onSaveThumbnail={() => {}}
+      onSaveSnapshot={() => {}}
+    />
+  );
+
+  /** Press `Choose thumbnail` and wait for the lazily-imported dialog to arrive. */
+  const openChooser = async (view: ReturnType<typeof render>, name: string) => {
+    fireEvent.click(view.getByRole('button', { name: /thumbnail/ }));
+    await waitFor(() =>
+      expect(document.body.textContent).toContain(`Pick a moment in ${name}`),
+    );
+  };
+
+  test('the chooser closes when the selection moves to another film', async () => {
+    const view = render(gallery('vid1'));
+    await openChooser(view, 'first.mp4');
+    view.rerender(gallery('vid2'));
+    await waitFor(() =>
+      expect(document.body.textContent, 'the chooser stayed on screen').not.toContain(
+        'Pick a moment in',
+      ),
+    );
+  });
+
+  test('🔴 and it never comes back describing the wrong film', async () => {
+    // The half a "did it disappear" check cannot see. If the dialog were merely hidden and
+    // re-shown, or if `grabbing` held the OLD item, this is where that shows up — the title is
+    // read straight off the item every save handler is closed over.
+    const view = render(gallery('vid1'));
+    await openChooser(view, 'first.mp4');
+    view.rerender(gallery('vid2'));
+    await waitFor(() => expect(document.body.textContent).not.toContain('Pick a moment in'));
+    await openChooser(view, 'second.mp4');
+    // Scoped to the DIALOG: `first.mp4` is legitimately on the page, in the "Files" strip
+    // beside the stage. What must not name it is the chooser.
+    const dialog = document.body.querySelector('[role="dialog"]');
+    expect(dialog?.textContent, 'the chooser is still holding the old film').not.toContain(
+      'first.mp4',
+    );
+  });
+
+  test('closing the file entirely leaves it too', async () => {
+    const view = render(gallery('vid1'));
+    await openChooser(view, 'first.mp4');
+    // Escape / the back arrow — the app clears the selection.
+    view.rerender(
+      <MediaGallery
+        items={VIDEOS}
+        selectedId={null}
+        nativeVideoStage
+        onSaveThumbnail={() => {}}
+        onSaveSnapshot={() => {}}
+      />,
+    );
+    await waitFor(() => expect(document.body.textContent).not.toContain('Pick a moment in'));
+  });
+
+  test('🔴 while the chooser is open, Space does not toggle the film BEHIND it', async () => {
+    /*
+     * The owner, same report: *"the space bar should toggle playing the video no matter what is
+     * focused but isn't working on the thumbnail selection page."*
+     *
+     * It was working — on the wrong film. This component binds `isPlayPauseSpace` at CAPTURE on
+     * `window` whenever a file is open, so a press inside the dialog reached the STAGE player
+     * first. `stopPropagation` is no help: it does not stop other listeners on the same target,
+     * so once `FrameGrabber` bound the same rule BOTH films would have toggled on one press.
+     * The gallery yields instead — whoever is on top owns the key.
+     */
+    const view = render(gallery('vid1'));
+    const stage = view.container.querySelector('.cbmg-stage-video') as HTMLVideoElement;
+    let paused = true;
+    const calls: string[] = [];
+    Object.defineProperty(stage, 'paused', { configurable: true, get: () => paused });
+    stage.play = (() => {
+      calls.push('play');
+      paused = false;
+      return Promise.resolve();
+    }) as HTMLVideoElement['play'];
+    stage.pause = () => {
+      calls.push('pause');
+      paused = true;
+    };
+
+    // With no dialog up the gallery owns the key — the behaviour this must not cost us.
+    const press = () => {
+      const event = new KeyboardEvent('keydown', { key: ' ', bubbles: true, cancelable: true });
+      Object.defineProperty(event, 'target', { value: document.body });
+      window.dispatchEvent(event);
+      return event.defaultPrevented;
+    };
+    expect(press()).toBe(true);
+    expect(calls).toEqual(['play']);
+
+    await openChooser(view, 'first.mp4');
+    // The dialog's own `<video>` is what a press must reach now; happy-dom implements neither
+    // method on it, so it is stubbed to keep the press from throwing rather than to be asserted
+    // on — `FrameGrabber.spec.tsx` owns that half.
+    const inDialog = document.body.querySelector(
+      '[role="dialog"] video',
+    ) as HTMLVideoElement | null;
+    expect(inDialog, 'the chooser rendered no player').not.toBeNull();
+    Object.defineProperty(inDialog, 'paused', { configurable: true, get: () => true });
+    if (inDialog) {
+      inDialog.play = (() => Promise.resolve()) as HTMLVideoElement['play'];
+      inDialog.pause = () => {};
+    }
+
+    press();
+    expect(calls, 'the film behind the dialog moved').toEqual(['play']);
+  });
+});
+
+/**
+ * 🔴 The strip under the stage keeps the file that is PLAYING, and keeps its place.
+ *
+ * Owner, `ideas/collections-09-14.md`: *"In collections sometimes I click on a video and while
+ * it's playing I click on a different video in the thumbnails under the playing video and the
+ * video I click on gets taken out of the list. I want to change this cb media gallery behavior
+ * so that I can still see the playing video in the list and nothing about the list changes as I
+ * pick other videos."*
+ *
+ * The cause was one line — the strip was `displayItems.filter(i => i.id !== selected.id)` — and
+ * the consequence is the one he describes: each pick removed the tile he had just clicked and
+ * put the previous one back, so every tile between the two moved by one. *"Nothing about the
+ * list changes"* is a claim about the ids AND their ORDER, which is why the first test below
+ * compares the whole sequence rather than a count; a count cannot tell a re-sort from a rest.
+ */
+describe('MediaGallery — the strip keeps the file that is playing', () => {
+  /** Five clips, `createdAt` descending so the default Newest sort is the order written here. */
+  const CLIPS: MediaGalleryItem[] = ['one', 'two', 'three', 'four', 'five'].map((word, i) => ({
+    id: `c${i}`,
+    name: `${word}.mp4`,
+    streamUrl: `/files/c${i}`,
+    posterUrl: `/thumbs/c${i}`,
+    mime: 'video/mp4',
+    durationSeconds: 10 + i,
+    createdAt: 500 - i * 10,
+  }));
+
+  /** Every tile caption the gallery is drawing, in the order it draws them. */
+  const captions = (c: HTMLElement): (string | null)[] =>
+    [...c.querySelectorAll('.cbgd-meta-title')].map((el) => el.textContent);
+
+  const title = (c: HTMLElement) => c.querySelector('.cbgd-watch-title')?.textContent;
+
+  const open = (view: ReturnType<typeof render>, name: string) =>
+    fireEvent.click(view.getByRole('button', { name: `Open ${name}` }));
+
+  test('🔴 the ids AND their order are identical before and after every pick', () => {
+    const view = render(<MediaGallery items={CLIPS} />);
+    const browse = captions(view.container);
+    expect(browse).toEqual(['one.mp4', 'two.mp4', 'three.mp4', 'four.mp4', 'five.mp4']);
+
+    // The first pick. Before the fix this came back four long, missing `two.mp4` — the tile he
+    // had just clicked, gone from under his pointer.
+    open(view, 'two.mp4');
+    expect(captions(view.container), 'the strip dropped the file it opened').toEqual(browse);
+
+    // …and it stays that way however many he picks, including picking the one already playing.
+    for (const name of ['four.mp4', 'one.mp4', 'five.mp4', 'five.mp4', 'three.mp4']) {
+      open(view, name);
+      expect(captions(view.container), `the strip moved when ${name} was picked`).toEqual(browse);
+      expect(title(view.container)).toBe(name);
+    }
+  });
+
+  test('🔴 the one that is playing is IN the strip, and is marked', () => {
+    const view = render(<MediaGallery items={CLIPS} />);
+    open(view, 'three.mp4');
+
+    const marked = view.container.querySelectorAll('[data-playing]');
+    expect(marked.length, 'exactly one tile is the one on the stage').toBe(1);
+    const tile = marked[0] as HTMLElement;
+    expect(tile.textContent).toContain('three.mp4');
+    expect(tile.className).toContain('is-playing');
+    // A ring drawn by a stylesheet says nothing to a screen reader; these two do.
+    expect(tile.getAttribute('aria-current')).toBe('true');
+    expect(tile.textContent).toContain('Now playing');
+
+    // The mark MOVES rather than accumulating, and the tile it leaves goes back to plain.
+    open(view, 'five.mp4');
+    const after = view.container.querySelectorAll('[data-playing]');
+    expect(after.length).toBe(1);
+    expect((after[0] as HTMLElement).textContent).toContain('five.mp4');
+  });
+
+  test('a still is "On screen", not "Now playing" — the album holds any kind of file', () => {
+    const view = render(<MediaGallery items={ITEMS} />);
+    open(view, 'beach.jpg');
+    const tile = view.container.querySelector('[data-playing]');
+    expect(tile?.textContent).toContain('beach.jpg');
+    expect(tile?.textContent).toContain('On screen');
+    expect(tile?.textContent).not.toContain('Now playing');
+  });
+
+  test('🔴 the heading no longer says "More files" — the open one is one of them', () => {
+    const view = render(<MediaGallery items={CLIPS} />);
+    open(view, 'two.mp4');
+    const head = view.container.querySelector('.cbgd-section-head');
+    expect(head?.textContent).toBe('Files');
+  });
+
+  test('the TABLE view of the same strip marks the same row, and keeps it', () => {
+    const view = render(<MediaGallery items={CLIPS} />);
+    fireEvent.click(view.getByRole('button', { name: /Table/ }));
+    open(view, 'two.mp4');
+
+    const rows = view.container.querySelectorAll('.cbgt-row');
+    expect(rows.length, 'the open file left the table').toBe(CLIPS.length);
+    const playing = view.container.querySelectorAll('.cbgt-row.is-playing');
+    expect(playing.length).toBe(1);
+    expect((playing[0] as HTMLElement).textContent).toContain('two.mp4');
+    expect((playing[0] as HTMLElement).getAttribute('aria-current')).toBe('true');
+    expect((playing[0] as HTMLElement).getAttribute('data-playing')).toBe('true');
+    // The name a screen reader reads, since the row's mark is a tint and a bar.
+    expect((playing[0] as HTMLElement).textContent).toContain('Now playing');
+  });
+
+  /*
+   * 🔴 The trap the strip change walks straight into, if `advance` ever reads the strip.
+   *
+   * `nextInRun` is handed `displayIds` — the whole displayed order, which has ALWAYS included
+   * the open item — and it excludes the current one itself (`playbackRun.ts`, asserted there
+   * over hundreds of steps with an injected generator). What that pure test cannot see is the
+   * WIRING: an `advance` that started counting the strip instead would now be offered the item
+   * already on the stage, and `shuffle` would sit on one clip replaying it forever — the exact
+   * failure `playbackPreferences.ts` describes for `loop` + `ended`.
+   */
+  const cycleTo = (view: ReturnType<typeof render>, label: RegExp) => {
+    for (let i = 0; i < 6; i++) {
+      const button = view.getByRole('button', { name: /^When an item ends:/ });
+      // The pill is a bare glyph — see the note on the other `cycleTo` in this file.
+      if (label.test(button.getAttribute('aria-label') ?? '')) return;
+      fireEvent.click(button);
+    }
+    throw new Error(`the playback button never reached ${label}`);
+  };
+
+  /** End the clip on the stage the way the element does. */
+  const endStage = (view: ReturnType<typeof render>) => {
+    const video = view.container.querySelector('.cbmg-stage-video');
+    expect(video, 'the native stage did not render a player').not.toBeNull();
+    if (video) fireEvent.ended(video);
+  };
+
+  test('🔴 shuffle never offers the item already playing as its next', () => {
+    const view = render(<MediaGallery items={CLIPS} nativeVideoStage />);
+    open(view, 'one.mp4');
+    cycleTo(view, /Shuffle/);
+    // Ten hand-offs over five clips: two full passes plus the refill between them, which is
+    // where a shuffle that counts the current item as a candidate repeats.
+    for (let i = 0; i < 10; i++) {
+      const before = title(view.container);
+      endStage(view);
+      expect(title(view.container), `shuffle replayed ${before}`).not.toBe(before);
+    }
+  });
+
+  test('🔴 play all steps to the NEXT file, never back to the one that just ended', () => {
+    const view = render(<MediaGallery items={CLIPS} nativeVideoStage />);
+    open(view, 'one.mp4');
+    cycleTo(view, /Play all/);
+    // The displayed order, wrapping past the last — and never the item that just played.
+    for (const next of ['two.mp4', 'three.mp4', 'four.mp4', 'five.mp4', 'one.mp4']) {
+      endStage(view);
+      expect(title(view.container)).toBe(next);
+    }
+  });
+
+  test('⇧-arrow stepping still walks the displayed order, which now matches the strip', () => {
+    const view = render(<MediaGallery items={CLIPS} />);
+    open(view, 'two.mp4');
+    // Dispatched at the BODY rather than at `window`: the gallery's handler is a capture
+    // listener on the window, so a press anywhere reaches it — and `fireEvent` is what wraps
+    // the state change it causes in `act`, which a raw `dispatchEvent` does not.
+    const press = (key: string) => fireEvent.keyDown(document.body, { key, shiftKey: true });
+    press('ArrowRight');
+    expect(title(view.container)).toBe('three.mp4');
+    press('ArrowLeft');
+    press('ArrowLeft');
+    expect(title(view.container)).toBe('one.mp4');
+    // The strip did not move while the stepping did.
+    expect(captions(view.container)).toEqual([
+      'one.mp4',
+      'two.mp4',
+      'three.mp4',
+      'four.mp4',
+      'five.mp4',
+    ]);
+  });
+});
+
+/**
+ * The REVEAL — bringing the marked tile back into view.
+ *
+ * Owner, same report: *"I can still see the playing video in the list."* A tile that stays in
+ * the list but forty rows above the fold is not one he can see, so the strip scrolls to it —
+ * the same thing `FileTree`'s reveal does, with the same two limits (only when it is off
+ * screen, never mid-drag) and one more: only while the stage is PINNED, because the watch view
+ * is one scroller and scrolling the strip in the unpinned mode would scroll the playing film
+ * off the top, which is the 2026-08-14 report ("navigate automatically back to the top to see
+ * the movie I am playing") re-opened.
+ *
+ * happy-dom lays nothing out, so every rect in this file is the same 800×600 stub — which
+ * reads as "everything is on screen" and would make the reveal untestable. These tests give
+ * the marked tile a rect of its own, which is the only part of the geometry that matters.
+ */
+describe('MediaGallery — the playing tile is scrolled back into view', () => {
+  const CLIPS: MediaGalleryItem[] = ['one', 'two', 'three', 'four', 'five'].map((word, i) => ({
+    id: `c${i}`,
+    name: `${word}.mp4`,
+    streamUrl: `/files/c${i}`,
+    posterUrl: `/thumbs/c${i}`,
+    mime: 'video/mp4',
+    createdAt: 500 - i * 10,
+  }));
+
+  const rect = (top: number, bottom: number): DOMRect =>
+    ({
+      top,
+      bottom,
+      height: bottom - top,
+      left: 0,
+      right: 800,
+      width: 800,
+      x: 0,
+      y: top,
+      toJSON: () => ({}),
+    }) as DOMRect;
+
+  /** The file-wide stub, restored after each test here. */
+  const FLAT = HTMLElement.prototype.getBoundingClientRect;
+  afterEach(() => {
+    HTMLElement.prototype.getBoundingClientRect = FLAT;
+  });
+
+  /**
+   * Lay the view out: the scroller and the pinned stage as written, the MARKED tile wherever
+   * the test puts it. Everything else keeps the file's flat 0–600 stub.
+   */
+  const layOut = (playing: DOMRect) => {
+    HTMLElement.prototype.getBoundingClientRect = function (this: HTMLElement): DOMRect {
+      if (this.getAttribute('data-playing') === 'true') return playing;
+      // The pinned top region covers the first half of the scroller, so a tile revealed to
+      // the frame's own top edge would land behind the film.
+      if (this.classList.contains('cbgd-watch-top')) return rect(0, 300);
+      return rect(0, 600);
+    };
+  };
+
+  /** Open a file with the stage pinned, and hand back the watch scroller. */
+  const pinned = (view: ReturnType<typeof render>, name: string): HTMLElement => {
+    fireEvent.click(view.getByRole('button', { name: `Open ${name}` }));
+    fireEvent.click(view.getByRole('button', { name: /Pin/ }));
+    return view.container.querySelector('.cbgd-watch') as HTMLElement;
+  };
+
+  test('🔴 a tile BELOW the fold is brought up to the bottom edge', () => {
+    const view = render(<MediaGallery items={CLIPS} />);
+    const scroller = pinned(view, 'one.mp4');
+    scroller.scrollTop = 0;
+    // The next pick's tile is 300px below the strip's bottom edge.
+    layOut(rect(900, 1100));
+    fireEvent.click(view.getByRole('button', { name: 'Open three.mp4' }));
+    // Exactly enough to bring its bottom edge into the frame, and not one pixel more.
+    expect(scroller.scrollTop).toBe(500);
+  });
+
+  test('🔴 a tile hidden BEHIND the pinned stage is brought below it, not to the top', () => {
+    const view = render(<MediaGallery items={CLIPS} />);
+    const scroller = pinned(view, 'one.mp4');
+    scroller.scrollTop = 400;
+    // 100–250: inside the scroller, but under the pinned region that ends at 300. Revealing
+    // to the frame's top (`scrollIntoView`'s `nearest`) would leave it there, behind the film.
+    layOut(rect(100, 250));
+    fireEvent.click(view.getByRole('button', { name: 'Open three.mp4' }));
+    expect(scroller.scrollTop).toBe(200);
+  });
+
+  test('a tile already in view does not move the strip — limit 2', () => {
+    const view = render(<MediaGallery items={CLIPS} />);
+    const scroller = pinned(view, 'one.mp4');
+    scroller.scrollTop = 120;
+    layOut(rect(320, 460));
+    fireEvent.click(view.getByRole('button', { name: 'Open three.mp4' }));
+    expect(scroller.scrollTop).toBe(120);
+  });
+
+  test('🔴 UNPINNED, the strip does not move — going back to the stage wins', () => {
+    const view = render(<MediaGallery items={CLIPS} />);
+    fireEvent.click(view.getByRole('button', { name: 'Open one.mp4' }));
+    const scroller = view.container.querySelector('.cbgd-watch') as HTMLElement;
+    scroller.scrollTop = 0;
+    layOut(rect(900, 1100));
+    fireEvent.click(view.getByRole('button', { name: 'Open three.mp4' }));
+    // The effect above this one scrolls the STAGE back into view; a reveal here would undo it
+    // every single time and play the film off the top of the screen.
+    expect(scroller.scrollTop).toBe(0);
+  });
+
+  /*
+   * Limit 3 — *never mid-drag* — is vacuous in this strip rather than skipped, and this is what
+   * keeps it that way: the detail view hands its tiles no `drag` prop, so there is no drag of
+   * ours to scroll out from under. A strip that becomes a drag source fails here, which is the
+   * moment to write the guard `FileTree` has.
+   */
+  test('the strip is not a drag source, which is what makes the reveal safe mid-drag', () => {
+    const view = render(<MediaGallery items={CLIPS} onItemDragStart={() => {}} />);
+    // The BROWSE grid is one — that is the feature, and it is what makes this assertion mean
+    // something rather than pass by accident.
+    expect(view.container.querySelector('.cbmg-selectable[draggable="true"]')).not.toBeNull();
+    fireEvent.click(view.getByRole('button', { name: 'Open one.mp4' }));
+    expect(view.container.querySelector('.cbmg-selectable[draggable="true"]')).toBeNull();
+  });
+});
+
+/**
+ * ── 🔴 The icon-only toolbar ─────────────────────────────────────────────────────────────
+ *
+ * Owner, `ideas/collections-09-14.md`, 2026-09-14: *"In the cb media galleries like collections
+ * uses I want to make the toolbar look more professional. Make it have icons only, instead of
+ * words in the strip of tools where have things like pin, stop at the end, and turn video.
+ * Hovering over the tooltip can show the words."*
+ *
+ * A visual change, so what is worth asserting is exactly what a visual change silently drops:
+ *
+ *   1. **The name.** A pill whose only content is an `<svg>` has no accessible name unless
+ *      somebody put one there. Deleting the words deletes the name unless an `aria-label`
+ *      takes over, and nothing about the page LOOKS broken when it happens — the toolbar is
+ *      simply unusable with a screen reader from that commit on. Every control the owner
+ *      named is listed here, plus the ones in the same strip he meant by *"things like"*.
+ *   2. **The state that was a word.** `📌 Pin` vs `📌 Pinned` and the five end-behaviour
+ *      labels were readouts, not names. One glyph in two states removes information he was
+ *      reading off the strip, so the value has to be somewhere a test can see it.
+ *   3. **That the words are actually GONE.** Otherwise "icons only" is a change that half
+ *      happened — a pill still printing its label passes (1) and (2) perfectly.
+ *
+ * The 44px floor is the fourth thing this change could drop and is deliberately NOT here:
+ * happy-dom computes no layout, so every rectangle in this file is the 800×600 stub at the
+ * top. `e2e/touch-targets.spec.ts` measures it in a real engine on a coarse pointer, which is
+ * this repo's standing lesson (task 69, and the 36×36 false green of 2026-09-14).
+ */
+describe('MediaGallery — the toolbar is icons, and the words are its names', () => {
+  /** Every capability wired, so the whole strip renders on one item. */
+  const wired = (items: MediaGalleryItem[]) =>
+    render(
+      <MediaGallery
+        items={items}
+        onRename={() => {}}
+        onSaveThumbnail={() => {}}
+        onSaveEdit={() => {}}
+        onSaveOrientation={() => {}}
+        onTrimVideo={() => {}}
+        onSaveChapters={() => {}}
+        onDelete={() => {}}
+      />,
+    );
+
+  test('🔴 every converted control still exposes its accessible name', () => {
+    const view = wired(ITEMS);
+    fireEvent.click(view.getByRole('button', { name: 'Open clip.mp4' }));
+    for (const name of [
+      // The three the owner named by hand…
+      'Pin the stage',
+      'When an item ends: Stop at the end',
+      'Turn video',
+      // …and the rest of the same strip, which "things like" is his phrasing for.
+      'Rename',
+      // `clip.mp4` already carries a `posterUrl`, so it is CHANGE rather than choose — which
+      // is the distinction the next test is about.
+      'Change thumbnail',
+      'Trim',
+      'Sections',
+      'Picture',
+      'Delete this item',
+      'Back to grid',
+      'Fullscreen',
+    ]) {
+      expect(view.getByRole('button', { name }), `no control named "${name}"`).toBeDefined();
+    }
+  });
+
+  test('🔴 …and so does the download, which is a LINK — same rule, different role', () => {
+    // On the photograph, because `clip.mp4` in this file's fixture has a `streamUrl` and no
+    // downloadable `url` — so the film renders no link at all and the assertion would be
+    // measuring an absence.
+    const view = wired(ITEMS);
+    fireEvent.click(view.getByRole('button', { name: 'Open beach.jpg' }));
+    const link = view.getByRole('link', { name: 'Download beach.jpg' });
+    expect(link.getAttribute('href')).toBe('/files/img1');
+    expect(link.textContent?.trim()).toBe('');
+  });
+
+  test('🔴 the strip prints no words at all — the half of "icons only" a name check cannot see', () => {
+    const view = wired(ITEMS);
+    fireEvent.click(view.getByRole('button', { name: 'Open clip.mp4' }));
+    const row = view.container.querySelector('.cbgd-watch-actions') as HTMLElement;
+    expect(row).not.toBeNull();
+    const wordy = [...row.querySelectorAll<HTMLElement>('.cbgd-order-btn')]
+      .filter((el) => (el.textContent ?? '').trim().length > 0)
+      .map((el) => `${el.getAttribute('aria-label')}: "${el.textContent?.trim()}"`);
+    expect(wordy, `pills still printing a label:\n${wordy.join('\n')}`).toEqual([]);
+    // …and it is a real strip that was measured, not an empty one the filter walked past.
+    expect(row.querySelectorAll('.cbgd-order-btn').length).toBeGreaterThan(8);
+  });
+
+  test('🔴 Pin says WHICH WAY it goes — the state that used to be the word', () => {
+    const view = wired(ITEMS);
+    fireEvent.click(view.getByRole('button', { name: 'Open clip.mp4' }));
+    const pin = () => view.getByRole('button', { name: /[Pp]in/ });
+    // Unpinned: not pressed, not lit, and the name is the verb.
+    expect(pin().getAttribute('aria-pressed')).toBe('false');
+    expect(pin().className).not.toContain('is-active');
+    expect(pin().getAttribute('aria-label')).toBe('Pin the stage');
+
+    fireEvent.click(pin());
+    // Pinned: all three flip together. The lit pill is what a sighted reader sees instead of
+    // the word "Pinned" — this control had no `is-active` at all before the conversion,
+    // because the word was carrying the whole state on its own.
+    expect(pin().getAttribute('aria-pressed')).toBe('true');
+    expect(pin().className).toContain('is-active');
+    expect(pin().getAttribute('aria-label')).toBe('Pinned — unpin the stage');
+  });
+
+  test('🔴 the end-behaviour control names its CURRENT setting, all five of them', () => {
+    const view = wired(ITEMS);
+    fireEvent.click(view.getByRole('button', { name: 'Open beach.jpg' }));
+    const button = () => view.getByRole('button', { name: /^When an item ends:/ });
+    const seen: string[] = [];
+    for (let i = 0; i < 5; i++) {
+      seen.push(button().getAttribute('aria-label') ?? '');
+      fireEvent.click(button());
+    }
+    expect(seen).toEqual([
+      'When an item ends: Stop at the end',
+      'When an item ends: Repeat one',
+      'When an item ends: Play next',
+      'When an item ends: Play all',
+      'When an item ends: Shuffle',
+    ]);
+  });
+
+  test('🔴 …and it draws a DIFFERENT glyph for each one, so the value is legible unhovered', () => {
+    const view = wired(ITEMS);
+    fireEvent.click(view.getByRole('button', { name: 'Open beach.jpg' }));
+    const button = () => view.getByRole('button', { name: /^When an item ends:/ });
+    // lucide stamps the icon's name onto the rendered `<svg>` as a class — `lucide-repeat-1`,
+    // `lucide-shuffle` — which is the one handle a DOM test has on which glyph is drawn. Five
+    // settings sharing one icon would collapse this set to a single entry.
+    const glyphs = new Set<string>();
+    for (let i = 0; i < 5; i++) {
+      glyphs.add(button().querySelector('svg')?.getAttribute('class') ?? '');
+      fireEvent.click(button());
+    }
+    expect(glyphs.size).toBe(5);
+  });
+
+  test('the Picture pill says so when the light has been moved, not only when it is open', () => {
+    const view = wired(ITEMS);
+    fireEvent.click(view.getByRole('button', { name: 'Open beach.jpg' }));
+    // The `·` this pill used to print meant "you have already moved these sliders" — it is a
+    // word in the name now, because a bare glyph has nowhere to put a dot.
+    expect(view.getByRole('button', { name: 'Picture' })).toBeDefined();
+    fireEvent.click(view.getByRole('button', { name: 'Picture' }));
+    const slider = view.container.querySelector<HTMLInputElement>(
+      '.cbmg-picture-sliders input[type="range"]',
+    ) as HTMLInputElement;
+    // `LIGHT_RANGE` is 0.2–2 around a neutral 1, not a percentage.
+    fireEvent.change(slider, { target: { value: '1.3' } });
+    expect(view.getByRole('button', { name: 'Picture — adjusted' })).toBeDefined();
+  });
+
+  test('the thumbnail control still says whether a poster exists — three different names', () => {
+    const noPoster: MediaGalleryItem[] = [
+      { id: 'p1', name: 'clip.mp4', streamUrl: '/f/p1', createdAt: 1 },
+    ];
+    const a = wired(noPoster);
+    fireEvent.click(a.getByRole('button', { name: 'Open clip.mp4' }));
+    expect(a.getByRole('button', { name: 'Choose thumbnail' })).toBeDefined();
+    a.unmount();
+
+    // `onSaveSnapshot` without `onSaveThumbnail` is a different capability, not a different
+    // wording — hence a camera rather than a picture frame.
+    const b = render(<MediaGallery items={noPoster} onSaveSnapshot={() => {}} />);
+    fireEvent.click(b.getByRole('button', { name: 'Open clip.mp4' }));
+    expect(b.getByRole('button', { name: 'Take a picture' })).toBeDefined();
+  });
+
+  test('the header pills and the selection bar went with it, rather than half converting', () => {
+    const view = render(<MediaGallery items={ITEMS} selectable selectionReveal='on-demand' />);
+    for (const name of ['Grid', 'Table', 'Select']) {
+      expect(view.getByRole('button', { name }), `no control named "${name}"`).toBeDefined();
+    }
+    expect(view.getByRole('button', { name: 'Grid' }).textContent?.trim()).toBe('');
+    expect(view.getByRole('button', { name: 'Table' }).textContent?.trim()).toBe('');
+    // Which one is live is still readable without a word, because they are a PAIR.
+    expect(view.getByRole('button', { name: 'Grid' }).getAttribute('aria-pressed')).toBe('true');
+    expect(view.getByRole('button', { name: 'Table' }).getAttribute('aria-pressed')).toBe('false');
+    // The count stays a WORD: it is a value you read, and the bar is the only place it is said.
+    expect(view.getByText('Select all')).toBeDefined();
+  });
+});
+
+/**
+ * ── 🔴 Tagging and describing — the capability, not a flag ──────────────────────────────
+ *
+ * Owner, `ideas/collections-09-14.md`, 2026-09-14: *"In media galleries have an option for apps
+ * to tag media and aadd descriptions to media. In collections allow these features so I can tag
+ * and add descriptions to its media."*
+ *
+ * The gallery could already READ `tags` and had no way to write one and no `description` field
+ * at all. These assert the three claims that make the new half real: the control is absent
+ * without a handler and present with one (the `onTrimVideo` rule, held here too), a bulk tag
+ * reports every ticked id in ONE call, and a description renders on the stage without touching
+ * the tile caption — which is two lines by design and already contested.
+ */
+describe('MediaGallery — tags and descriptions', () => {
+  const TAGGABLE: MediaGalleryItem[] = [
+    { id: 'img1', name: 'beach.jpg', url: '/files/img1', createdAt: 30, tags: ['holiday'] },
+    { id: 'img2', name: 'dog.jpg', url: '/files/img2', createdAt: 20 },
+    { id: 'img3', name: 'receipt.pdf', url: '/files/pdf1', createdAt: 10 },
+  ];
+  const boxes = (c: HTMLElement) =>
+    [...c.querySelectorAll('.cbmg-select-box input')] as HTMLInputElement[];
+
+  test('🔴 the control appears only when the app can STORE the answer', () => {
+    const withoutHandler = render(<MediaGallery items={TAGGABLE} />);
+    fireEvent.click(withoutHandler.getByRole('button', { name: 'Open beach.jpg' }));
+    expect(withoutHandler.queryByRole('button', { name: 'Tags and description' })).toBeNull();
+    withoutHandler.unmount();
+
+    const withHandler = render(<MediaGallery items={TAGGABLE} onSaveMeta={() => {}} />);
+    fireEvent.click(withHandler.getByRole('button', { name: 'Open beach.jpg' }));
+    expect(withHandler.queryByRole('button', { name: 'Tags and description' })).not.toBeNull();
+  });
+
+  test('🔴 the bulk verb is gated by the same handler, and by nothing else', () => {
+    const { container, queryByRole, rerender } = render(
+      <MediaGallery items={TAGGABLE} selectable />,
+    );
+    fireEvent.click(boxes(container)[0] as HTMLInputElement);
+    expect(queryByRole('button', { name: /^Tag the 1 selected item$/ })).toBeNull();
+
+    rerender(<MediaGallery items={TAGGABLE} selectable onSaveMeta={() => {}} />);
+    expect(queryByRole('button', { name: /^Tag the 1 selected item$/ })).not.toBeNull();
+  });
+
+  test('🔴 a bulk tag reports EVERY selected id in one call, not one call per item', async () => {
+    // The whole reason the handler takes a list. A gallery that looped the singular would call
+    // this three times with one item, and an app re-deriving its rows between the writes is how
+    // a batch tag half-lands — the failure `tasks/Completed/240-*.md` records for the tree's
+    // batch move, in the same words.
+    const calls: { ids: string[]; add: string[]; remove: string[] }[] = [];
+    const { container, getByRole, getByLabelText, findByRole } = render(
+      <MediaGallery
+        items={TAGGABLE}
+        selectable
+        onSaveMeta={(items, change) => {
+          calls.push({
+            ids: items.map((i) => i.id),
+            add: change.addTags,
+            remove: change.removeTags,
+          });
+        }}
+      />,
+    );
+    fireEvent.click(container.querySelector('.cbmg-bulkbar-all input') as HTMLInputElement);
+    fireEvent.click(getByRole('button', { name: 'Tag the 3 selected items' }));
+
+    const add = (await findByRole('dialog')) && getByLabelText('Tags to add to all 3 selected items');
+    fireEvent.change(add, { target: { value: 'greece' } });
+    fireEvent.keyDown(add, { key: 'Enter' });
+    fireEvent.click(getByRole('button', { name: /^Save$/ }));
+
+    await waitFor(() => expect(calls).toHaveLength(1));
+    expect(calls[0]).toEqual({
+      ids: ['img1', 'img2', 'img3'],
+      add: ['greece'],
+      remove: [],
+    });
+  });
+
+  test('🔴 the single-item save arrives as the SAME add/remove pair a bulk one sends', async () => {
+    // An array rather than a `let … = null`: TypeScript narrows a local that is only ever
+    // written inside a callback back to `null`, so the assertion below would not compile.
+    const calls: { ids: string[]; add: string[]; remove: string[]; description?: string }[] = [];
+    const { getByRole, getByLabelText, findByRole } = render(
+      <MediaGallery
+        items={TAGGABLE}
+        onSaveMeta={(items, change) => {
+          calls.push({
+            ids: items.map((i) => i.id),
+            add: change.addTags,
+            remove: change.removeTags,
+            ...(change.description === undefined ? {} : { description: change.description }),
+          });
+        }}
+      />,
+    );
+    fireEvent.click(getByRole('button', { name: 'Open beach.jpg' }));
+    fireEvent.click(getByRole('button', { name: 'Tags and description' }));
+    await findByRole('dialog');
+
+    const tags = getByLabelText('Tags for beach.jpg');
+    fireEvent.change(tags, { target: { value: 'greece' } });
+    fireEvent.keyDown(tags, { key: 'Enter' });
+    fireEvent.change(getByLabelText('Description of beach.jpg'), {
+      target: { value: 'The last morning in Naxos.' },
+    });
+    fireEvent.click(getByRole('button', { name: /^Save$/ }));
+
+    await waitFor(() => expect(calls).toHaveLength(1));
+    expect(calls[0]).toEqual({
+      ids: ['img1'],
+      add: ['greece'],
+      remove: [],
+      description: 'The last morning in Naxos.',
+    });
+  });
+
+  test('🔴 the bulk form offers no description — one sentence cannot describe three files', async () => {
+    const { container, getByRole, queryByLabelText, findByRole } = render(
+      <MediaGallery items={TAGGABLE} selectable onSaveMeta={() => {}} />,
+    );
+    fireEvent.click(container.querySelector('.cbmg-bulkbar-all input') as HTMLInputElement);
+    fireEvent.click(getByRole('button', { name: 'Tag the 3 selected items' }));
+    await findByRole('dialog');
+    expect(queryByLabelText(/^Description of/)).toBeNull();
+    expect(queryByLabelText('Tags to remove from all 3 selected items')).not.toBeNull();
+  });
+
+  test('a description RENDERS on the stage, under the title', () => {
+    const described: MediaGalleryItem[] = [
+      {
+        id: 'img1',
+        name: 'beach.jpg',
+        url: '/files/img1',
+        createdAt: 30,
+        description: 'The last morning in Naxos.',
+      },
+    ];
+    const { container, getByRole, getByText } = render(<MediaGallery items={described} />);
+    fireEvent.click(getByRole('button', { name: 'Open beach.jpg' }));
+    expect(getByText('The last morning in Naxos.')).toBeDefined();
+    // Its own element rather than appended to the ` · ` facts line, which is nowrap with an
+    // ellipsis because the same class captions every tile in the grid.
+    expect(container.querySelector('.cbmg-stage-description')?.textContent).toBe(
+      'The last morning in Naxos.',
+    );
+  });
+
+  test('🔴 reading a description needs NO handler — only writing is gated', () => {
+    const described: MediaGalleryItem[] = [
+      { id: 'img1', name: 'beach.jpg', url: '/files/img1', createdAt: 30, description: 'Naxos.' },
+    ];
+    const { container, getByRole } = render(<MediaGallery items={described} />);
+    fireEvent.click(getByRole('button', { name: 'Open beach.jpg' }));
+    expect(container.querySelector('.cbmg-stage-description')).not.toBeNull();
+    expect(container.querySelector('button[aria-label="Tags and description"]')).toBeNull();
+  });
+
+  test('🔴 the TILE caption is unchanged by a description', () => {
+    // The caption is two lines by design and already contested between the tags and the
+    // measurement; a sentence there would be an ellipsis or a third line on every tile.
+    const bare: MediaGalleryItem = { id: 'i', name: 'beach.jpg', sizeBytes: 2_048, createdAt: 1 };
+    const described: MediaGalleryItem = { ...bare, description: 'A very long sentence indeed.' };
+    expect(galleryTileLine(described)).toBe(galleryTileLine(bare));
+    expect(galleryTileLine(described, { measure: true })).toBe(
+      galleryTileLine(bare, { measure: true }),
+    );
+
+    const { container } = render(<MediaGallery items={[described]} />);
+    expect(container.querySelector('.cbgd-meta-line')?.textContent).toBe('2.0 KB');
+  });
+
+  test('a gallery with no description renders exactly the meta line it rendered before', () => {
+    const { container, getByRole } = render(<MediaGallery items={TAGGABLE} />);
+    fireEvent.click(getByRole('button', { name: 'Open beach.jpg' }));
+    const line = container.querySelector('.cbgd-watch-titlebar .cbgd-meta-line');
+    expect(line?.querySelector('.cbmg-stage-description')).toBeNull();
+    expect(line?.textContent).toContain('holiday');
+  });
+});