cursedbelt 3.0.2 → 4.0.0

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

@@ -1,4 +1,61 @@
 import './mediaGallery.css';
+/*
+ * ── 🔴 The toolbar's icons ─────────────────────────────────────────────────────────────
+ *
+ * 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."*
+ *
+ * `lucide-react`, not the 📌 ⟳ 🖼 ✂ these pills carried until 2026-09-16. An emoji is drawn
+ * by whichever font the operating system picked, at whatever optical size and weight that
+ * font chose, in colour on some platforms and monochrome on others — so the one thing a
+ * toolbar of them cannot look is designed, which is the opposite of what was asked for. The
+ * package is already a dependency (`DropdownMenu`, `PlayerStrip`, `icons.tsx`), so this adds
+ * no weight and no second icon vocabulary.
+ *
+ * 🔴 Three rules every conversion below keeps, because a visual change is exactly where each
+ * is silently dropped:
+ *
+ *   1. **The accessible name survives.** Every icon-only pill carries an `aria-label`, and
+ *      the glyph itself is `aria-hidden`. The words did double duty as the name.
+ *   2. **The 44px tap floor survives.** The hit target is the pill, not the glyph — see
+ *      `.cbgd-order-btn.is-icon` in `denseGallery.css`, measured by
+ *      `e2e/touch-targets.spec.ts` at a real coarse-pointer viewport.
+ *   3. **A word that was a VALUE keeps a home.** `📌 Pin` vs `📌 Pinned` and the five
+ *      end-behaviour labels were not names, they were readouts; an icon identical in both
+ *      states deletes information. They move into the pressed state, the accessible name and
+ *      the tooltip together — `MediaGallery.spec.tsx` asserts each one.
+ *
+ * What stays a word: the dwell READING (`5s`), the selection count, the sort pills, and the
+ * inline rename form's Save/Cancel. Those are values you read or a form's action row
+ * (`DESIGN.md` §6), not tools in the strip.
+ */
+import {
+  ArrowLeft,
+  ArrowRightToLine,
+  Camera,
+  Crop,
+  Download,
+  Image as ImageIcon,
+  LayoutGrid,
+  ListVideo,
+  Pencil,
+  Pin,
+  Play,
+  Repeat,
+  Repeat1,
+  RotateCw,
+  Rows3,
+  Scissors,
+  Shuffle,
+  SkipForward,
+  SquareCheck,
+  Sun,
+  Tags,
+  Timer,
+  X,
+} from 'lucide-react';
 import { formatBytes } from 'cwip/format';
 import type { FileCategory } from 'cwip/file-kind';
 import React, {
@@ -34,6 +91,7 @@ import {
 } from '../media/pictureEdit';
 import type { PictureEditResult } from '../media/PictureEditor';
 import type { MediaOrientation } from '../media/VideoTurner';
+import type { ChapteredVideo, VideoChapter } from '../media/videoChapters';
 import type { VideoCut } from 'cursedbelt-core/media/video-cuts';
 import {
   GALLERY_ORDER_OPTIONS,
@@ -54,8 +112,11 @@ import {
   readImageDwell,
   readPinStage,
   readPlaybackEnd,
+  readSessionVolume,
   readThumbAutoplay,
+  STAGE_VOLUME_KEY,
   writeImageDwell,
+  writeSessionVolume,
   writePinStage,
   writePlaybackEnd,
   writeThumbAutoplay,
@@ -63,7 +124,8 @@ import {
   readViewMode,
   writeViewMode,
 } from './playbackPreferences';
-import { GalleryTable } from './GalleryTable';
+import type { MediaMetaChange } from './mediaMeta';
+import { GalleryTable, durationLabel } from './GalleryTable';
 import { nextInRun, runAdvances, runRepeatsOne, stepId } from './playbackRun';
 import type { MediaGalleryItem, MediaGalleryItemMedia, MediaGalleryOrder } from './types';
 import { createdLabel, type MediaCache, ThumbImg, useItemMedia } from './galleryItemMedia';
@@ -104,6 +166,58 @@ const LazyFrameGrabber = React.lazy(() =>
 const LazyVideoTurner = React.lazy(() =>
   import('../media/VideoTurner').then((m) => ({ default: m.VideoTurner })),
 );
+/**
+ * The turn dialog, over the item's RESOLVED media — never over the raw row.
+ *
+ * ── 🔴 The black box, and where it came from ───────────────────────────────────────────
+ * Owner, `ideas/collections-09-14.md`: *"When I click the turn the video button I see a black
+ * screen. It should show me the video so I can see how the turn impacts it."*
+ *
+ * The dialog was mounted as `src={item.streamUrl ?? item.url ?? ''}` — the fields ON THE ROW.
+ * But a gallery item is allowed to carry no URL at all: {@link MediaGalleryItem.resolveMedia}
+ * is the documented path for signed URLs and for bytes that become an object URL, and every
+ * other surface in this file reads an item through {@link useItemMedia}, which merges that
+ * resolver's answer into the row's own fields and caches it per id. So on any app that signs
+ * its URLs — which is the app that reported this — both fields were `undefined`, the dialog
+ * mounted a `<video>` with no `src` and no `poster`, and an element with nothing to load never
+ * even fires `error`: it paints black, forever, silently. Reproduced in
+ * `MediaGallery.spec.tsx`'s "the dialog is handed the RESOLVED source" before this existed.
+ *
+ * 🔴 It shares the gallery's own cache rather than calling the resolver again. A second cache
+ * would re-sign the URL every time the dialog opened, which is the cost `galleryItemMedia.tsx`
+ * was extracted to stop.
+ */
+function TurnVideoDialog({
+  item,
+  cache,
+  onClose,
+  onSave,
+}: {
+  item: MediaGalleryItem;
+  cache: MediaCache;
+  onClose: () => void;
+  onSave: (next: MediaOrientation | undefined) => void | Promise<void>;
+}) {
+  const { media, resolving } = useItemMedia(item, cache);
+  // `streamUrl ?? url`, the same preference the stage and the frame grabber make: a plain `url`
+  // is not always a streamable source, and a turner given the wrong one shows a black box.
+  const src = media.streamUrl ?? media.url ?? '';
+  const poster = media.posterUrl ?? media.thumbnailUrl;
+  return (
+    <LazyVideoTurner
+      src={src}
+      {...(poster ? { posterUrl: poster } : {})}
+      // So an unresolved source reads as "still finding it" for the moment it takes, rather
+      // than flashing the "cannot show it" reason at somebody whose film is on its way.
+      resolving={resolving}
+      name={item.name}
+      orientation={item.orientation}
+      onClose={onClose}
+      onSave={onSave}
+    />
+  );
+}
+
 // Marking sections of a clip to cut out. Lazy for the usual reason and one extra: an app that
 // has no pipeline to execute a cut list never passes `onTrimVideo`, so it never loads a byte
 // of this — which is what makes "enabled for collections only, for now" a fact about the
@@ -111,6 +225,45 @@ const LazyVideoTurner = React.lazy(() =>
 const LazyVideoCutEditor = React.lazy(() =>
   import('../media/VideoCutEditor').then((m) => ({ default: m.VideoCutEditor })),
 );
+// Naming the parts of a clip. The same bargain as the cut editor one line up: an app that has
+// nowhere to PUT a chapter list never passes `onSaveChapters`, so it never loads a byte of
+// this dialog — the capability and the bundle cost turn on together, with no flag between them.
+const LazyVideoChapterEditor = React.lazy(() =>
+  import('../media/VideoChapterEditor').then((m) => ({ default: m.VideoChapterEditor })),
+);
+// Tagging and describing, on one file or on a ticked selection. Same bargain again: an app
+// with nowhere to PUT a tag never passes `onSaveMeta`, so it never loads a byte of this
+// dialog — and the gallery keeps reading whatever tags and descriptions its items already
+// carry either way, because reading was never the capability that was missing.
+const LazyMediaMetaEditor = React.lazy(() =>
+  import('./MediaMetaEditor').then((m) => ({ default: m.MediaMetaEditor })),
+);
+
+/**
+ * One glyph per end-behaviour — the five values the cycling pill used to spell out.
+ *
+ * 🔴 Five DISTINCT icons, not one icon plus a lit state. The button cycles through settings
+ * rather than toggling one, so `Stop at the end` and `Shuffle` have to be told apart at a
+ * glance or the only way to read the current value is to hover — and the owner's own words
+ * for this control ("stop at the end") are a value he was reading off the strip, not a name
+ * for the button. `aria-label` still spells the value out in full; this is the sighted half
+ * of the same fact.
+ *
+ * `stop` is `ArrowRightToLine` because it is exactly the `→|` the pill drew before, and it
+ * is the one setting that renders UNLIT (`is-active` is withheld for `stop`) — so "nothing
+ * happens at the end" reads as an off state, which is what it is.
+ *
+ * Deliberately NOT in `playbackPreferences.ts` beside the labels: that module is pure data
+ * and storage, imported by apps that drive their own player, and adding a React component to
+ * it would pull `lucide-react` into every one of them for a table they never render.
+ */
+const PLAYBACK_END_ICONS: Record<PlaybackEndBehavior, typeof Repeat> = {
+  stop: ArrowRightToLine,
+  repeat: Repeat1,
+  next: SkipForward,
+  all: Repeat,
+  shuffle: Shuffle,
+};
 
 /**
  * A stored orientation, as a CSS transform — the same `previewTransform` the editor previews
@@ -133,13 +286,45 @@ function isTurned(item: MediaGalleryItem): boolean {
 
 type BytesCache = MutableRefObject<Map<string, Promise<ArrayBuffer>>>;
 
-function GalleryMeta({ item }: { item: MediaGalleryItem }) {
-  const line =
-    item.tags && item.tags.length > 0
-      ? item.tags.slice(0, 3).join(' · ')
-      : item.sizeBytes != null
-        ? formatBytes(item.sizeBytes)
-        : null;
+/**
+ * The one meta line under a tile's picture — its tags, its measurement, or both.
+ *
+ * ── 🔴 What `measure` turns on, and why it is not the default ──────────────────────────
+ * Owner, `ideas/collections-09-14.md`: *"in the grid view show the video length instead of
+ * the size"*, and `ideas/binary-server-09-15.md`: *"show the video length on thumbnail
+ * components … show the file size on thumbnail components (maybe controlled through param on
+ * media gallery in cb)"*. He guessed the right home for it: ONE param on this gallery, so an
+ * app that asks for nothing renders the line it already had, byte for byte.
+ *
+ * With it on, the measurement a tile leads with is the one that means something for its kind
+ * — a film and a track show their RUNNING TIME, everything else its size. A clip whose
+ * duration nobody measured falls back to its size rather than to a blank caption, and a file
+ * with neither shows `—`, the same mark the table's columns use for an absent measurement.
+ *
+ * 🔴 Tags and the measurement share this line rather than taking one each. The caption block
+ * is a fixed 65px — title, this line, the date — pinned to `CBGD_META_HEIGHT` because a
+ * caption whose height varied per tile is what made rows lap one another across the fleet
+ * (see `denseGallery.css`). A fourth line is not available at any price, so a tagged video
+ * reads `holiday · beach · 3:07`.
+ *
+ * Exported for its own spec: the branch table here is wider than the tile is, and a rendered
+ * assertion can only reach the combinations a fixture happens to contain.
+ */
+export function galleryTileLine(
+  item: MediaGalleryItem,
+  options: { measure?: boolean } = {},
+): string | null {
+  const tags = item.tags && item.tags.length > 0 ? item.tags.slice(0, 3).join(' · ') : null;
+  const size = item.sizeBytes != null ? formatBytes(item.sizeBytes) : null;
+  if (!options.measure) return tags ?? size;
+  const category = galleryItemCategory(item);
+  const timeBased = category === 'video' || category === 'audio';
+  const measure = timeBased ? (durationLabel(item.durationSeconds) ?? size ?? '—') : size;
+  return tags && measure ? `${tags} · ${measure}` : (tags ?? measure);
+}
+
+function GalleryMeta({ item, measure }: { item: MediaGalleryItem; measure?: boolean }) {
+  const line = galleryTileLine(item, { measure: measure === true });
   // The date is its OWN line rather than appended to the one above, because that line is
   // already whichever of tags/size exists — folding a third fact into it would push the tags
   // out of a tile caption that is two lines tall by design.
@@ -194,18 +379,34 @@ function TileShell({
   name,
   selection,
   drag,
+  stageMark,
   children,
 }: {
   name: string;
   selection?: TileSelection;
   drag?: TileDrag;
+  /**
+   * The mark for the tile the STAGE is showing — `'Now playing'` on a film, `'On screen'` on
+   * a still. Absent on every other tile, and absent entirely in the browse grid, where
+   * nothing is on a stage.
+   *
+   * 🔴 A STATE on the tile, not a second control. The tile that is playing stays exactly the
+   * tile it was — same position, same size, same click — and gains a ring and one capsule
+   * (DESIGN.md §3). `aria-current` is what carries the same fact to a screen reader, because
+   * a ring drawn by a stylesheet says nothing to one.
+   */
+  stageMark?: string;
   children: ReactNode;
 }) {
   const selected = selection?.selected === true;
   const quiet = selection !== undefined && !selection.armed;
   return (
     <div
-      className={`cbmg-selectable${selected ? ' is-selected' : ''}${quiet ? ' cbmg-selectable--quiet' : ''}`}
+      className={`cbmg-selectable${selected ? ' is-selected' : ''}${stageMark ? ' is-playing' : ''}${quiet ? ' cbmg-selectable--quiet' : ''}`}
+      // The hook the reveal below finds the tile by — see `MediaGallery`'s `revealPlaying`.
+      // An attribute rather than the class, so the query cannot be broken by a styling change.
+      data-playing={stageMark ? 'true' : undefined}
+      aria-current={stageMark ? 'true' : undefined}
       // 🔴 The DRAGGABLE element is this wrapper, not the tile inside it. Every tile branch
       // is a <button>, and a draggable button is a browser-by-browser coin toss: some start
       // a drag, some treat the pointer-down as a press and never fire dragstart at all.
@@ -220,6 +421,14 @@ function TileShell({
         : {})}
     >
       {children}
+      {/* Real text, never `aria-hidden`: "the one that is playing" is the whole point of the
+          mark, so it has to be readable rather than only visible. The glyph beside it is the
+          decoration, and it is the only part hidden. */}
+      {stageMark ? (
+        <span className='cbmg-playing-chip'>
+          <span aria-hidden='true'>▶</span> {stageMark}
+        </span>
+      ) : null}
       {selection ? (
         <SelectBox name={name} selected={selected} onToggle={selection.onToggle} />
       ) : null}
@@ -266,6 +475,8 @@ function GalleryTile({
   selection,
   drag,
   autoPreview,
+  measure,
+  stageMark,
 }: {
   item: MediaGalleryItem;
   cache: MediaCache;
@@ -274,6 +485,10 @@ function GalleryTile({
   drag?: TileDrag;
   /** Preview every video tile without hovering it — see `readThumbAutoplay`. */
   autoPreview?: boolean;
+  /** Lead the caption with a running time / a size — see {@link galleryTileLine}. */
+  measure?: boolean;
+  /** See {@link TileShell}'s `stageMark` — the label for the tile that is ON the stage. */
+  stageMark?: string;
 }) {
   /*
    * 🔴 ALWAYS wrapped, even with no selection and no drag.
@@ -290,8 +505,14 @@ function GalleryTile({
    * handlers, so this costs nothing and cannot change behavior anywhere else.
    */
   return (
-    <TileShell name={item.name} selection={selection} drag={drag}>
-      <RawGalleryTile item={item} cache={cache} onOpen={onOpen} autoPreview={autoPreview} />
+    <TileShell name={item.name} selection={selection} drag={drag} stageMark={stageMark}>
+      <RawGalleryTile
+        item={item}
+        cache={cache}
+        onOpen={onOpen}
+        autoPreview={autoPreview}
+        measure={measure}
+      />
     </TileShell>
   );
 }
@@ -353,11 +574,13 @@ function RawGalleryTile({
   cache,
   onOpen,
   autoPreview,
+  measure,
 }: {
   item: MediaGalleryItem;
   cache: MediaCache;
   onOpen: () => void;
   autoPreview?: boolean;
+  measure?: boolean;
 }) {
   const category = galleryItemCategory(item);
   const { media } = useItemMedia(item, cache);
@@ -383,7 +606,7 @@ function RawGalleryTile({
         // whose detail view is upright, which reads as the fix not having worked.
         {...(item.orientation ? { orientation: item.orientation } : {})}
       >
-        <GalleryMeta item={item} />
+        <GalleryMeta item={item} measure={measure} />
       </HoverScrubVideoThumb>
     );
   }
@@ -430,7 +653,7 @@ function RawGalleryTile({
           />
         </div>
       )}
-      <GalleryMeta item={item} />
+      <GalleryMeta item={item} measure={measure} />
     </button>
   );
 }
@@ -582,7 +805,7 @@ export function stagePlayableVideo(
   item: MediaGalleryItem,
   media: MediaGalleryItemMedia,
   streamUrl: string,
-): PlayableVideo {
+): ChapteredVideo {
   return {
     id: item.id,
     name: item.name,
@@ -602,9 +825,51 @@ export function stagePlayableVideo(
     // broken one.
     ...(media.vttUrl ? { vttUrl: media.vttUrl } : {}),
     ...(media.processingStatus ? { processingStatus: media.processingStatus } : {}),
+    // The named sections, straight off the ITEM rather than out of `media`: chapters are a
+    // property of the film, not of a resolved URL, and they are the same list whichever
+    // transport the stage ends up playing. Absent when there are none, so a video with no
+    // sections hands the player nothing to draw a chapters menu for.
+    ...(item.chapters && item.chapters.length > 0 ? { chapters: item.chapters } : {}),
   };
 }
 
+/**
+ * 🔴 The stage's session volume, on the NATIVE transport.
+ *
+ * The Vidstack stage gets this from `VideoPlayer` (`volumeKey`, read off the player's own
+ * `volume-change`); this is the same rule for the plain `<video>` an app opts into with
+ * `nativeVideoStage`. Same {@link STAGE_VOLUME_KEY}, because it is the same surface — the two
+ * transports are never mounted at once, and keying them apart would mean an app that switched
+ * transports lost the level mid-session for no reason a person could name.
+ *
+ * Owner, `ideas/collections-09-14.md`: *"Keep the media player volume where I set it after
+ * changing it during a session except if I refresh or first log in then continue starting it
+ * at mute. Then if I unmute it, keep that value as I change to other videos."*
+ *
+ * 🔴 The `else` branch is not a no-op: this element carries `autoPlay` and no `muted`, so the
+ * fresh-session case starts it silent — which is both what he asked for and the only state a
+ * browser will actually auto-play. The native control bar is right there to unmute.
+ */
+function useStageVolume(ref: React.RefObject<HTMLVideoElement | null>): void {
+  React.useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const stored = readSessionVolume(STAGE_VOLUME_KEY);
+    el.volume = stored?.volume ?? 1;
+    el.muted = stored?.muted ?? true;
+    // What we just applied — the element fires `volumechange` for it, and writing that back
+    // would mint a preference nobody set. Only what he does after this is his.
+    let applied = { volume: el.volume, muted: el.muted };
+    const onChange = () => {
+      if (el.volume === applied.volume && el.muted === applied.muted) return;
+      applied = { volume: el.volume, muted: el.muted };
+      writeSessionVolume(STAGE_VOLUME_KEY, applied);
+    };
+    el.addEventListener('volumechange', onChange);
+    return () => el.removeEventListener('volumechange', onChange);
+  }, [ref]);
+}
+
 /**
  * The `nativeVideoStage` element — a plain `<video>` with the ladder attached to it.
  *
@@ -632,6 +897,7 @@ function NativeVideoStage({
 }) {
   const ref = React.useRef<HTMLVideoElement>(null);
   useHlsSource(ref, { hlsUrl, streamUrl });
+  useStageVolume(ref);
   return (
     // biome-ignore lint/a11y/useMediaCaption: arbitrary user-stored files carry no captions
     <video
@@ -740,6 +1006,10 @@ function GalleryStage({
         <LazyVideoPlayer
           video={stagePlayableVideo(item, media, src)}
           autoPlay
+          // 🔴 The STAGE's own volume memory, not the shared primitive's default key — see
+          // `playbackPreferences.ts`. It is what makes the level he set on this clip apply to
+          // the next one, and it is per session, so a refresh is silent again.
+          volumeKey={STAGE_VOLUME_KEY}
           loop={repeat}
           {...(repeat ? {} : { onEnded })}
           {...(onStep ? { onStep, canStep: canStep !== false } : {})}
@@ -1068,6 +1338,57 @@ export interface MediaGalleryProps {
    * somebody the minutes of scrubbing that produced the list.
    */
   onTrimVideo?: (item: MediaGalleryItem, cuts: VideoCut[]) => void | Promise<void>;
+  /**
+   * Store the named sections of a video — YouTube chapters.
+   *
+   * The owner's ask, 2026-09-15: *"allow putting markers on videos at points in time and giving
+   * them a title for the section for knowing what that part of the video is about, like youtube
+   * chapters."* So this is a SAVE, not a request: the list applies the moment it comes back on
+   * {@link MediaGalleryItem.chapters}, costs no encode, and touches no byte of the file.
+   *
+   * 🔴 Passing this is what turns authoring on, per app — the same rule as `onTrimVideo`, and
+   * for a different reason worth stating: chapters have somewhere to GO only in an app that
+   * keeps a row per file it can write to. An app that merely lists someone else's videos must
+   * not offer a control that saves into nothing, and because the editor is lazily imported, an
+   * app that does not pass this does not ship the dialog either.
+   *
+   * 🔴 READING chapters needs nothing: an item that carries `chapters` shows them on the scrub
+   * bar whether or not this is passed. The capability being gated is writing them.
+   *
+   * An EMPTY list is how every section is removed. Rejecting keeps the dialog open with the
+   * names intact, because a failed request must not cost somebody the minutes of scrubbing and
+   * naming that produced them.
+   */
+  onSaveChapters?: (item: MediaGalleryItem, chapters: VideoChapter[]) => void | Promise<void>;
+  /**
+   * Store TAGS and a DESCRIPTION — on the open file, or on everything that is ticked.
+   *
+   * The owner's ask, `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` — the tile prints the first three and the chips filter on them — and had no way to
+   * write one and no `description` field at all, so an app could display a vocabulary it
+   * already had and nothing in here could create a word of it.
+   *
+   * 🔴 Passing this is what turns authoring on, per app — the same rule as `onTrimVideo`, and
+   * for the same two reasons: an app that cannot persist a tag must not offer a control that
+   * saves into nothing, and because the editor is lazily imported, an app that does not pass
+   * this does not ship the dialog either. READING needs nothing, exactly as chapters do.
+   *
+   * 🔴 The first argument is a LIST, always — one item is `[item]`. Tagging forty holiday
+   * photographs at once is the case he will actually hit, and a plural verb that a consumer
+   * can only implement by looping the singular is the shape `tasks/Completed/240-*.md`
+   * refuses in as many words: *"One request for N ids, not N requests."* The change arrives
+   * as `addTags`/`removeTags` rather than as a new list for exactly this reason — forty items
+   * do not share one tag list, so "the new tags" would wipe thirty-nine nobody looked at.
+   * `applyMetaChange` (exported from this subpath) is the merge, so no app writes it twice.
+   *
+   * Rejecting keeps the dialog open with the draft intact.
+   */
+  onSaveMeta?: (
+    items: MediaGalleryItem[],
+    change: MediaMetaChange,
+  ) => void | Promise<void>;
   /**
    * What happens after a trim is queued, in the app's own words — rendered under the strip.
    * Apps differ: one runs it on the spot, another drains a queue on a schedule, and "when
@@ -1081,7 +1402,7 @@ export interface MediaGalleryProps {
    */
   allowPictureReplace?: boolean;
   /**
-   * The ☀ Picture control — brightness, contrast and colour for what is on the stage. On by
+   * The Picture control — brightness, contrast and colour for what is on the stage. On by
    * default, because it needs nothing from the app: it is a CSS filter over the stage and
    * nothing is saved, so there is no capability to be missing.
    *
@@ -1090,6 +1411,33 @@ export interface MediaGalleryProps {
    * deep. Pass `false` in an app where adjusting the picture is meaningless.
    */
   pictureControls?: boolean;
+  /**
+   * What the tiles and the table say about SIZE and LENGTH — the one param he guessed at.
+   *
+   * 🔴 Two asks, one prop, because they are one surface. `ideas/collections-09-14.md`, twice:
+   * *"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."*
+   * Then `ideas/binary-server-09-15.md` asked for both facts on the same tiles and named the
+   * right home: *"maybe controlled through param on media gallery in cb."*
+   *
+   * 🔴 Everything here is OFF by default, so a consumer that passes nothing renders exactly
+   * what it renders today — the compatibility rule every other prop on this component holds.
+   */
+  meta?: {
+    /**
+     * A tile's caption leads with the measurement that means something for its kind: the
+     * RUNNING TIME on a film or a track, the size on everything else. Tags keep the line
+     * they had and the measurement joins them on it — see {@link galleryTileLine}.
+     */
+    tileMeasure?: boolean;
+    /**
+     * The table offers the exact byte count as its own column, beside the rounded Size one
+     * rather than instead of it — see `exactBytesLabel` in `GalleryTable.tsx`. A rounded size cannot answer
+     * *"are these two the same file"*, which is the job he named for it.
+     */
+    exactBytes?: boolean;
+  };
 }
 
 /**
@@ -1136,7 +1484,10 @@ export function MediaGallery({
   allowPictureReplace = false,
   pictureControls = true,
   onTrimVideo,
+  onSaveChapters,
+  onSaveMeta,
   trimNote,
+  meta,
 }: MediaGalleryProps) {
   const [uncontrolledQuery, setUncontrolledQuery] = useState('');
   /** Controlled when the consumer passes `query`, uncontrolled otherwise — see the prop. */
@@ -1350,6 +1701,17 @@ export function MediaGallery({
   const [turningVideo, setTurningVideo] = useState<MediaGalleryItem | null>(null);
   /** The clip whose cut marks are being made, or null. See `onTrimVideo`. */
   const [trimmingVideo, setTrimmingVideo] = useState<MediaGalleryItem | null>(null);
+  /** The clip whose sections are being named, or null. See `onSaveChapters`. */
+  const [chapteringVideo, setChapteringVideo] = useState<MediaGalleryItem | null>(null);
+  /**
+   * What the tag/description editor is open over, or null. See `onSaveMeta`.
+   *
+   * 🔴 A LIST rather than one item, because this is the one capability dialog reachable from
+   * BOTH screens: the open file's strip passes `[selected]`, and the bulk bar passes the whole
+   * ticked set. One piece of state for both is what keeps the two paths from becoming two
+   * dialogs that drift — and it is why `items` is the editor's prop rather than `item`.
+   */
+  const [taggingItems, setTaggingItems] = useState<MediaGalleryItem[] | null>(null);
   const [grabbing, setGrabbing] = useState<{ item: MediaGalleryItem; at: number } | null>(null);
   const [showPicture, setShowPicture] = useState(false);
   const [light, setLight] = useState<PictureLight>(NO_LIGHT);
@@ -1361,8 +1723,26 @@ export function MediaGallery({
   // biome-ignore lint/correctness/useExhaustiveDependencies: explained immediately above
   useEffect(() => {
     setRenaming(null);
-    setEditingPicture(null);
     setLight(NO_LIGHT);
+    /*
+     * 🔴 EVERY capability dialog, not just the picture editor — the owner, 2026-09-14, on the
+     * thumbnail chooser in `apps/collections`: *"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."*
+     *
+     * Only `editingPicture` was cleared here, so a dialog opened against the file you WERE
+     * looking at outlived the selection and then described the wrong file: its title, its
+     * `src`, its `startAt` and — the part that loses work — the item every save handler above
+     * is closed over. The fix is one line per dialog rather than a rule in a doc comment,
+     * because "remember to clear yours" is exactly the instruction the four dialogs added
+     * after this one would not have read.
+     */
+    setEditingPicture(null);
+    setTurningVideo(null);
+    setTrimmingVideo(null);
+    setChapteringVideo(null);
+    setTaggingItems(null);
+    setGrabbing(null);
   }, [selectedId]);
 
   // 🔴 Enabled whenever there is somewhere else to go, NOT only away from the edges — the
@@ -1504,6 +1884,78 @@ export function MediaGallery({
     el.scrollIntoView({ behavior: reduced || snapsToStage(selected) ? 'auto' : 'smooth', block: 'start' });
   }, [selectedId, selected]);
 
+  /**
+   * ── Bring the tile the stage is showing back into view — the strip's REVEAL ─────────────
+   *
+   * Owner, `ideas/collections-09-14.md`: *"I want to … still see the playing video in the
+   * list."* Keeping it IN the list (the strip above) is only half of that: on a folder of
+   * ninety files the marked tile is forty rows away, and a mark nobody can find is a mark
+   * nobody has. This is `file-tree/FileTree.tsx`'s reveal, applied to the same problem, and
+   * it keeps that one's limits:
+   *
+   * 1. **Only when the tile is off screen.** A strip that jumps a few pixels every time you
+   *    click a tile you can already see reads as a bug.
+   * 2. **Never mid-drag** — vacuous here rather than skipped: the strip's tiles are handed no
+   *    `drag` prop at all (see `renderTile` below), so there is no drag of ours to be in the
+   *    middle of. `MediaGallery.spec.tsx` asserts that, so a future strip that DOES become a
+   *    drag source fails a test pointing at this note instead of silently yanking the list
+   *    out from under a pointer.
+   *
+   * 🔴 …and one limit the tree has no need of: it runs only while the stage is PINNED.
+   *
+   * The watch view is ONE scroller — stage on top, strip underneath — so scrolling the strip
+   * scrolls the stage away. The owner has already ruled on that collision, from the other
+   * side: *"when I scroll down through thumbnails and click one to play it then I want to
+   * navigate automatically back to the top to see the movie I am playing"* (2026-08-14, the
+   * effect directly above). Revealing the tile in that mode would undo, every single time,
+   * the thing that effect exists to do — the film would be playing off the top of the screen
+   * again, which is the older report re-opened.
+   *
+   * Pinning is his own answer to it: *"a button to lock the video in place on top so I can
+   * scroll thumbnails and still see the full video."* With the top region sticky the stage
+   * cannot scroll away, the effect above finds it already in place and moves nothing, and the
+   * strip's scroll is free — so that is exactly the mode where this reveal is not taking
+   * something away to give something else.
+   *
+   * 🔴 It scrolls by a computed delta rather than by `scrollIntoView`, and the sticky region
+   * is why: `block: 'nearest'` on a tile ABOVE the fold aligns it to the top of the scroller,
+   * which is the seventy percent of it the pinned stage is sitting on — a "reveal" that puts
+   * the tile behind the video. The visible band starts where the pinned region ends.
+   */
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `selectedId` is the TRIGGER and is deliberately not read in the body — the tile is found through the DOM by the mark that identifies it. `pinStage` is a GUARD and not a trigger: pressing the pin would otherwise scroll the strip on its own, which is movement nobody asked for.
+  useEffect(() => {
+    const stage = stageRef.current;
+    if (!selectedId || !pinStage || !stage) return;
+    const scroller = stage.closest<HTMLElement>('.cbgd-watch');
+    // The strip's own marked element, in whichever view is on: a tile shell in the grid, a
+    // row in the table. Both carry `data-playing` for exactly this.
+    const mark = scroller?.querySelector<HTMLElement>('[data-playing]');
+    if (!scroller || !mark) return;
+    // The table scrolls inside its own frame (`.cbgt-root`), where the stage is not even a
+    // sibling; the tile grid windows against the watch scroller itself.
+    const frame = mark.closest<HTMLElement>('.cbgt-root') ?? scroller;
+    const view = frame.getBoundingClientRect();
+    // Where the pinned region stops covering the strip. Absent (or not pinned) → the frame's
+    // own top edge, which is what the table's separate scroller always uses.
+    const pinned = frame === scroller ? scroller.querySelector('.cbgd-watch-top') : null;
+    const top = pinned ? Math.max(view.top, pinned.getBoundingClientRect().bottom) : view.top;
+    const box = mark.getBoundingClientRect();
+    const delta =
+      box.top < top ? box.top - top : box.bottom > view.bottom ? box.bottom - view.bottom : 0;
+    // Limit 1: already in the band, so nothing moves.
+    if (delta === 0) return;
+    frame.scrollTop += delta;
+  }, [selectedId]);
+
+  /**
+   * Is one of the capability dialogs on screen? Every one of them is a focus-trapped modal
+   * over the gallery, so for as long as one is up the window-level shortcuts below are not
+   * the gallery's to take — see the guard in the effect that follows.
+   */
+  const capabilityDialogOpen = Boolean(
+    editingPicture || turningVideo || trimmingVideo || chapteringVideo || grabbing,
+  );
+
   /**
    * Arrow keys step, Escape closes.
    *
@@ -1511,9 +1963,22 @@ export function MediaGallery({
    * the thing the owner just clicked and it owns focus — a handler on an ancestor div only
    * fires when focus happens to be outside the player, which is the state a person watching a
    * video is never in. The typing guard below is what makes a window binding safe.
+   *
+   * ── 🔴 …and it stands DOWN while a capability dialog is open ─────────────────────────────
+   * The owner, 2026-09-14, on the thumbnail chooser: *"the space bar should toggle playing
+   * the video no matter what is focused but isn't working on the thumbnail selection page."*
+   *
+   * It was firing — on the wrong film. This handler binds at CAPTURE on `window`, so a press
+   * inside an open dialog reached it first and toggled the STAGE player behind the dialog,
+   * which is a video the reader cannot see. `FrameGrabber` now binds the same fleet rule
+   * (`usePlayPauseSpace`) to its own `<video>`, and two capture listeners on one window both
+   * "working" is how a single press pauses two different films — `stopPropagation` does not
+   * help, because it does not stop other listeners on the same target. So the gallery yields
+   * the key instead: whoever is on top owns it. The same guard is what stops Escape closing
+   * the gallery's selection out from under a dialog that Radix was about to close on its own.
    */
   useEffect(() => {
-    if (!selectedId) return;
+    if (!selectedId || capabilityDialogOpen) return;
     const onKey = (event: KeyboardEvent) => {
       /*
        * 🔴 Space is play/pause, and it is decided BEFORE the typing guard below — which is
@@ -1668,11 +2133,9 @@ export function MediaGallery({
         />
       ) : null}
       {turningVideo ? (
-        <LazyVideoTurner
-          src={turningVideo.streamUrl ?? turningVideo.url ?? ''}
-          {...(turningVideo.posterUrl ? { posterUrl: turningVideo.posterUrl } : {})}
-          name={turningVideo.name}
-          orientation={turningVideo.orientation}
+        <TurnVideoDialog
+          item={turningVideo}
+          cache={mediaCache}
           onClose={() => setTurningVideo(null)}
           onSave={async (next: MediaOrientation | undefined) => {
             await onSaveOrientation?.(turningVideo, next);
@@ -1692,6 +2155,32 @@ export function MediaGallery({
           }}
         />
       ) : null}
+      {chapteringVideo && onSaveChapters ? (
+        <LazyVideoChapterEditor
+          src={chapteringVideo.streamUrl ?? chapteringVideo.url ?? ''}
+          {...(chapteringVideo.posterUrl ? { posterUrl: chapteringVideo.posterUrl } : {})}
+          name={chapteringVideo.name}
+          durationSeconds={chapteringVideo.durationSeconds ?? null}
+          {...(chapteringVideo.chapters ? { chapters: chapteringVideo.chapters } : {})}
+          onClose={() => setChapteringVideo(null)}
+          onSubmit={async (chapters: VideoChapter[]) => {
+            await onSaveChapters(chapteringVideo, chapters);
+          }}
+        />
+      ) : null}
+      {taggingItems && taggingItems.length > 0 && onSaveMeta ? (
+        <LazyMediaMetaEditor
+          items={taggingItems}
+          // The album's own vocabulary, which is already computed for the filter chips —
+          // offering it is what stops `holiday`, `Holiday` and `holidays` being minted as
+          // three chips that each find a third of the set.
+          suggestions={tags}
+          onClose={() => setTaggingItems(null)}
+          onSubmit={async (change: MediaMetaChange) => {
+            await onSaveMeta(taggingItems, change);
+          }}
+        />
+      ) : null}
       {grabbing ? (
         <LazyFrameGrabber
           src={grabbing.item.streamUrl ?? grabbing.item.url ?? ''}
@@ -1718,8 +2207,37 @@ export function MediaGallery({
 
   if (selected) {
     const category = galleryItemCategory(selected);
-    const others = displayItems.filter((i) => i.id !== selected.id);
+    /*
+     * ── 🔴 The strip under the stage is EVERY displayed item, the open one included ───────
+     *
+     * Owner, `ideas/collections-09-14.md`: *"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."*
+     *
+     * This line was `displayItems.filter((i) => i.id !== selected.id)` — the strip was
+     * everything EXCEPT what was playing. So every pick removed one item and put the previous
+     * one back, and because the two sit at different places in the sort, every tile between
+     * them shifted by one: the list re-sorted itself under his pointer on every click, which
+     * is what *"the video I click on gets taken out of the list"* is describing. His
+     * requirement is stated twice and is the exact opposite, so there is no filter here at
+     * all now — the strip is `displayItems`, in `displayItems`' order, and the open one is
+     * MARKED (`stageMark` below) instead of removed.
+     *
+     * 🔴 Nothing downstream ever depended on the exclusion. `step`/⇧-arrows and `advance`
+     * have always run over `displayIds` — the unfiltered displayed order — so their
+     * arithmetic is untouched by this, and `nextInRun` already refuses to draw the current
+     * item as the next one (`playbackRun.ts`, and `MediaGallery.spec.tsx` asserts it from
+     * this edge). What DID depend on it was the heading, which said *"More files"*; with the
+     * open file in the list that word is no longer true, so it is gone too.
+     */
+    const stageMark =
+      category === 'video' || category === 'audio' ? 'Now playing' : 'On screen';
     const downloadHref = selected.downloadUrl ?? selected.url;
+    // Capitalised so JSX reads it as a component rather than an HTML tag — see
+    // `PLAYBACK_END_ICONS` for why the setting gets five glyphs and not one.
+    const PlaybackEndIcon = PLAYBACK_END_ICONS[playbackEnd];
     return (
       <>
       {capabilityDialogs}
@@ -1736,16 +2254,19 @@ export function MediaGallery({
           // The date joins the line rather than replacing what was there — beside the title is
           // exactly where the owner asked for it, and the titlebar has the room a tile caption
           // does not.
-          [
-            selected.tags && selected.tags.length > 0
-              ? selected.tags.join(' · ')
-              : selected.sizeBytes != null
-                ? formatBytes(selected.sizeBytes)
-                : null,
-            createdLabel(selected.createdAt),
-          ]
-            .filter(Boolean)
-            .join(' · ') || undefined
+          stageMeta(
+            [
+              selected.tags && selected.tags.length > 0
+                ? selected.tags.join(' · ')
+                : selected.sizeBytes != null
+                  ? formatBytes(selected.sizeBytes)
+                  : null,
+              createdLabel(selected.createdAt),
+            ]
+              .filter(Boolean)
+              .join(' · ') || undefined,
+            selected.description,
+          )
         }
         sticky={pinStage}
         stage={
@@ -1802,6 +2323,11 @@ export function MediaGallery({
                 Owner, 2026-08-14: "a button to lock the video in place on top so I can scroll
                 thumbnails and still see the full video." Shown for every kind — browsing a
                 folder while keeping a photograph on screen is the same need. */}
+            {/* 🔴 `Pin` vs `Pinned` was a READOUT, and one glyph cannot be both. It moves into
+                three places at once: the lit pill (`is-active`, which this control never had
+                — the word was carrying the whole state on its own), `aria-pressed`, and the
+                accessible name, which says which way the press goes. The tooltip below
+                already named both states and is unchanged. */}
             <Tooltip content={
                 pinStage
                   ? 'Unpin — let the stage scroll away with the page'
@@ -1810,15 +2336,16 @@ export function MediaGallery({
               <button
                 // guardrails-ignore no-raw-action-button: see the previous button.
                 type='button'
-                className='cbgd-order-btn'
+                className={`cbgd-order-btn is-icon${pinStage ? ' is-active' : ''}`}
                 aria-pressed={pinStage}
+                aria-label={pinStage ? 'Pinned — unpin the stage' : 'Pin the stage'}
                 onClick={() => {
                   const next = !pinStage;
                   setPinStage(next);
                   writePinStage(next);
                 }}
               >
-                {pinStage ? '📌 Pinned' : '📌 Pin'}
+                <Pin aria-hidden />
               </button>
             </Tooltip>
             {/* 🔴 Shown for EVERY kind, not only video. Three of the five settings run the
@@ -1826,11 +2353,18 @@ export function MediaGallery({
                 gating this on `category === 'video'` meant the owner could not start one from
                 a picture, which is the item most folders open on. `playbackPreferences.ts`
                 explains why five settings on one button rather than a row of toggles. */}
-            <Tooltip content={PLAYBACK_END_LABELS[playbackEnd].hint}>
+            {/* 🔴 The tooltip LEADS with the current value now. It used to carry the hint
+                alone, which was enough while the label was printed on the pill beside it;
+                with the word gone, a hover that explains what the setting does without
+                saying which one is set has dropped the half he was reading. The
+                `aria-label` is unchanged — it always carried the value in full. */}
+            <Tooltip
+              content={`${PLAYBACK_END_LABELS[playbackEnd].label} — ${PLAYBACK_END_LABELS[playbackEnd].hint}`}
+            >
               <button
                 // guardrails-ignore no-raw-action-button: see the previous button.
                 type='button'
-                className={`cbgd-order-btn${playbackEnd === 'stop' ? '' : ' is-active'}`}
+                className={`cbgd-order-btn is-icon${playbackEnd === 'stop' ? '' : ' is-active'}`}
                 onClick={() => {
                   const next = nextPlaybackEnd(playbackEnd);
                   setPlaybackEnd(next);
@@ -1838,7 +2372,7 @@ export function MediaGallery({
                 }}
                 aria-label={`When an item ends: ${PLAYBACK_END_LABELS[playbackEnd].label}`}
               >
-                {PLAYBACK_END_LABELS[playbackEnd].glyph} {PLAYBACK_END_LABELS[playbackEnd].label}
+                <PlaybackEndIcon aria-hidden />
               </button>
             </Tooltip>
             {/* The slideshow speed, and ONLY while a setting that advances is chosen — a
@@ -1847,7 +2381,13 @@ export function MediaGallery({
             {runAdvances(playbackEnd) ? (
               <Tooltip content='How long each picture holds the screen before the next item'>
                 <label className='cbgd-dwell'>
-                  <span className='cbgd-dwell-label'>Hold</span>
+                  {/* The word `Hold` was the control's NAME and is now the hourglass; the
+                      `5s` beside it is its VALUE and stays printed, because a duration you
+                      have to hover to read is a duration you cannot compare. The select
+                      keeps its own `aria-label`, so the glyph is decoration. */}
+                  <span className='cbgd-dwell-label'>
+                    <Timer aria-hidden />
+                  </span>
                   <select
                     // guardrails-ignore no-raw-inputs: `.cbgd-dwell` is this module's own
                     // self-contained plain-CSS control, for the same reason `.cbgd-search`
@@ -1927,17 +2467,43 @@ export function MediaGallery({
                     // guardrails-ignore no-raw-action-button: action pill styled by the dense
                     // gallery's own plain CSS, matching its neighbors.
                     type='button'
-                    className='cbgd-order-btn'
+                    className='cbgd-order-btn is-icon'
+                    aria-label='Rename'
                     onClick={() => {
                       setRenameDraft(selected.name);
                       setRenaming(selected.id);
                     }}
                   >
-                    Rename
+                    <Pencil aria-hidden />
                   </button>
                 </Tooltip>
               )
             ) : null}
+            {/* Rename's neighbour, and for the same reason: both are about what this file IS
+                rather than about the picture on the stage. Offered on EVERY kind — a PDF and a
+                spreadsheet are exactly as worth tagging as a photograph, which is the whole
+                point of a gallery that holds any binary. See `onSaveMeta`. */}
+            {onSaveMeta ? (
+              <Tooltip content='Tag this file and say what it is'>
+                <button
+                  // guardrails-ignore no-raw-action-button: see above.
+                  type='button'
+                  className={`cbgd-order-btn is-icon${
+                    (selected.tags && selected.tags.length > 0) || selected.description
+                      ? ' is-active'
+                      : ''
+                  }`}
+                  /* Lit when the file already carries one, which is the readout the strip
+                     would otherwise have no way to give: "has this been described yet" is the
+                     question somebody browsing an untagged album is actually asking, and it
+                     is invisible from the stage once the meta line scrolls past. */
+                  aria-label='Tags and description'
+                  onClick={() => setTaggingItems([selected])}
+                >
+                  <Tags aria-hidden />
+                </button>
+              </Tooltip>
+            ) : null}
             {/* Only a video has frames to choose between. An image IS its own thumbnail, and
                 offering the picker on one would be a control with nothing to pick. */}
             {(onSaveThumbnail || onSaveSnapshot) && category === 'video' ? (
@@ -1949,7 +2515,19 @@ export function MediaGallery({
                 <button
                   // guardrails-ignore no-raw-action-button: see above.
                   type='button'
-                  className='cbgd-order-btn'
+                  className='cbgd-order-btn is-icon'
+                  /* 🔴 The three words this pill used to print, kept verbatim as its name —
+                     they are not interchangeable. "Change" vs "Choose" says whether a poster
+                     already exists, and "Take a picture" is a DIFFERENT capability (the app
+                     wired `onSaveSnapshot` and not `onSaveThumbnail`), which is why the glyph
+                     changes with it: a camera, not a picture frame. */
+                  aria-label={
+                    onSaveThumbnail
+                      ? selected.posterUrl
+                        ? 'Change thumbnail'
+                        : 'Choose thumbnail'
+                      : 'Take a picture'
+                  }
                   onClick={() => {
                     /*
                      * 🔴 Carry the PLAYHEAD across, read off the DOM rather than plumbed through.
@@ -1966,11 +2544,7 @@ export function MediaGallery({
                     setGrabbing({ item: selected, at });
                   }}
                 >
-                  {onSaveThumbnail
-                    ? selected.posterUrl
-                      ? '🖼 Change thumbnail'
-                      : '🖼 Choose thumbnail'
-                    : '📷 Take a picture'}
+                  {onSaveThumbnail ? <ImageIcon aria-hidden /> : <Camera aria-hidden />}
                 </button>
               </Tooltip>
             ) : null}
@@ -1979,12 +2553,17 @@ export function MediaGallery({
                 <button
                   // guardrails-ignore no-raw-action-button: see above.
                   type='button'
-                  className='cbgd-order-btn'
+                  className='cbgd-order-btn is-icon'
+                  aria-label='Edit picture'
                   onClick={() => setEditingPicture(selected)}
                   // The commonest press by far is one turn on a scan or a phone photograph stored
                   // a quarter turn from how it should read, which is why the tooltip leads on it.
                 >
-                  ⟳ Edit picture
+                  {/* A crop frame rather than the `⟳` this printed: the pill opens the whole
+                      picture editor (turn, mirror, crop, re-light), and a rotate arrow here
+                      would be the same glyph as the video's turn button one row down while
+                      meaning something four times larger. */}
+                  <Crop aria-hidden />
                 </button>
               </Tooltip>
             ) : null}
@@ -1996,10 +2575,11 @@ export function MediaGallery({
                 <button
                   // guardrails-ignore no-raw-action-button: see above.
                   type='button'
-                  className='cbgd-order-btn'
+                  className='cbgd-order-btn is-icon'
+                  aria-label='Turn video'
                   onClick={() => setTurningVideo(selected)}
                 >
-                  ⟳ Turn video
+                  <RotateCw aria-hidden />
                 </button>
               </Tooltip>
             ) : null}
@@ -2008,10 +2588,27 @@ export function MediaGallery({
                 <button
                   // guardrails-ignore no-raw-action-button: see above.
                   type='button'
-                  className='cbgd-order-btn'
+                  className='cbgd-order-btn is-icon'
+                  aria-label='Trim'
                   onClick={() => setTrimmingVideo(selected)}
                 >
-                  ✂ Trim
+                  <Scissors aria-hidden />
+                </button>
+              </Tooltip>
+            ) : null}
+            {/* Trim's neighbour, and its opposite: the scissors mark what goes, this marks
+                what a part IS and keeps it. Offered on video only, and only where the app can
+                store the answer — see `onSaveChapters`. */}
+            {onSaveChapters && category === 'video' ? (
+              <Tooltip content='Name the parts of this film — the player shows them on the scrub bar'>
+                <button
+                  // guardrails-ignore no-raw-action-button: see above.
+                  type='button'
+                  className='cbgd-order-btn is-icon'
+                  aria-label='Sections'
+                  onClick={() => setChapteringVideo(selected)}
+                >
+                  <ListVideo aria-hidden />
                 </button>
               </Tooltip>
             ) : null}
@@ -2020,13 +2617,21 @@ export function MediaGallery({
                 <button
                   // guardrails-ignore no-raw-action-button: see above.
                   type='button'
-                  className={`cbgd-order-btn${showPicture || isLightAdjusted(light) ? ' is-active' : ''}`}
+                  className={`cbgd-order-btn is-icon${showPicture || isLightAdjusted(light) ? ' is-active' : ''}`}
                   aria-pressed={showPicture}
+                  /* 🔴 The trailing `·` this used to print was the one thing on the pill that
+                     was not a name: it meant "you have already moved these sliders", which is
+                     the difference between a stage that looks wrong and a stage you made look
+                     that way. The dot has nowhere to go on a bare glyph, so it becomes a word
+                     in the accessible name — the lit pill already says it to the eye, because
+                     `is-active` is held whenever the light is adjusted even with the sliders
+                     put away. */
+                  aria-label={isLightAdjusted(light) ? 'Picture — adjusted' : 'Picture'}
                   onClick={() => setShowPicture((on) => !on)}
                   // Offered for pictures as well as video: a dark photograph is exactly as hard
                   // to look at as a dark clip, and the stage renders both.
                 >
-                  ☀ Picture{isLightAdjusted(light) ? ' ·' : ''}
+                  <Sun aria-hidden />
                 </button>
               </Tooltip>
             ) : null}
@@ -2072,39 +2677,58 @@ export function MediaGallery({
             {downloadHref ? (
               <Tooltip content={`Download ${selected.name}`}>
                 <a
-                  className='cbgd-order-btn'
+                  className='cbgd-order-btn is-icon'
                   href={downloadHref}
                   download={selected.name}
+                  // A link, so it has no `aria-pressed` to carry state and needs none — but it
+                  // does need a name, and the file it fetches is the interesting half.
+                  aria-label={`Download ${selected.name}`}
                 >
-                  ⬇ Download
+                  <Download aria-hidden />
                 </a>
               </Tooltip>
             ) : null}
             {onDelete ? (
+              /* `iconOnly` is `DeleteButton`'s OWN prop, not a second icon convention
+                 invented here — it draws the trash glyph and keeps the confirmation gate
+                 that is the component's whole reason to exist. `aria-label` is explicit
+                 because the children it would otherwise name itself from are gone. */
               <DeleteButton
+                iconOnly
+                /* Not the bare word "Delete": that is the CONFIRMATION dialog's button, and
+                   two controls with one name is a query — a person's or a test's — that
+                   cannot say which it means. */
+                aria-label='Delete this item'
                 itemLabel={CATEGORY_LABEL[category].toLowerCase()}
                 tooltip='Delete this item'
                 onDelete={async () => {
                   await onDelete(selected);
                   select(null);
                 }}
-              >
-                ✕ Delete
-              </DeleteButton>
+              />
             ) : null}
-            <button
-              // guardrails-ignore no-raw-action-button: back-to-grid navigation, styled by
-              // the dense gallery's own plain CSS (plugin-media-gallery precedent).
-              type='button'
-              className='cbgd-order-btn'
-              onClick={() => select(null)}
-            >
-              Back to grid
-            </button>
+            <Tooltip content='Close this file and go back to the grid'>
+              <button
+                // guardrails-ignore no-raw-action-button: back-to-grid navigation, styled by
+                // the dense gallery's own plain CSS (plugin-media-gallery precedent).
+                type='button'
+                className='cbgd-order-btn is-icon'
+                aria-label='Back to grid'
+                onClick={() => select(null)}
+              >
+                {/* A back ARROW, not a grid glyph: the grid icon is taken by the view
+                    toggle in the header, and two pills drawing the same square while one
+                    changes the layout and the other leaves the screen is the ambiguity an
+                    icon-only strip is most likely to introduce. */}
+                <ArrowLeft aria-hidden />
+              </button>
+            </Tooltip>
           </>
         }
-        relatedLabel='More files'
-        itemCount={others.length}
+        /* Not "More files" — the strip holds the open file too now, so "more" would be the
+           heading contradicting the list under it. */
+        relatedLabel='Files'
+        itemCount={displayItems.length}
         loading={loading}
         onNearEnd={onNearEnd}
         minColumnWidth={minColumnWidth}
@@ -2114,14 +2738,17 @@ export function MediaGallery({
          * Owner: *"toggling to rows from thumbnails did not work in the gallery with a video
          * active."* The detail view drew tiles unconditionally, so the control was live, the
          * preference was written, and nothing changed — a pressed button doing provably
-         * nothing. It is the same `GalleryTable` the browse view uses, over the same `others`
-         * the tiles would have been, so the two screens cannot drift into two tables.
+         * nothing. It is the same `GalleryTable` the browse view uses, over the same items the
+         * tiles would have been, so the two screens cannot drift into two tables.
          */
         {...(viewMode === 'table'
           ? {
               relatedBody: (
                 <GalleryTable
-                  items={others}
+                  items={displayItems}
+                  // The open file is in this list exactly as it is in the tile strip, so it is
+                  // marked here exactly as it is there.
+                  playing={{ id: selected.id, label: stageMark }}
                   cache={mediaCache}
                   order={order}
                   onOrderChange={setOrder}
@@ -2134,12 +2761,16 @@ export function MediaGallery({
                      table as the browse view's — so leaving it out here would fix the toggle on
                      one of the two screens it is wrong on. */
                   autoPreview={thumbAutoplay}
+                  /* Same argument for the exact-bytes column: this IS the browse view's
+                     table, so a column it offered and this one withheld would be the
+                     feature vanishing the moment you opened a file. */
+                  exactBytes={meta?.exactBytes === true}
                 />
               ),
             }
           : {})}
         renderTile={(index) => {
-          const item = others[index];
+          const item = displayItems[index];
           return item ? (
             <GalleryTile
               key={item.id}
@@ -2149,6 +2780,14 @@ export function MediaGallery({
               // The toggle means what it says on both screens — "Preview all" that stopped
               // applying the moment you opened something would be a different feature.
               autoPreview={thumbAutoplay}
+              // …and so does the running time on a film's caption: the strip under an open
+              // file is the same grid, and a tile that told you its length on one screen and
+              // its size on the other would be two tiles.
+              measure={meta?.tileMeasure === true}
+              // The one tile the stage is showing. Clicking it re-selects what is already
+              // open, which `select` makes a no-op change — it stays a live tile rather than
+              // a dead one, because a tile you cannot press reads as broken.
+              {...(item.id === selected.id ? { stageMark } : {})}
             />
           ) : null;
         }}
@@ -2158,6 +2797,14 @@ export function MediaGallery({
   }
 
   return (
+    <>
+    {/* 🔴 The SAME dialog host as the detail view's, because exactly one capability is
+        reachable from the browse screen: tagging a ticked selection (`onSaveMeta`). Every
+        other dialog here is scoped to an open file and is null on this screen by
+        construction, so rendering the one host in both places is what stops the bulk editor
+        needing a second mount point that the `selectedId` reset would then have to know
+        about separately. */}
+    {capabilityDialogs}
     <DenseGalleryShell<MediaGalleryOrder>
       title={title}
       order={{
@@ -2182,10 +2829,10 @@ export function MediaGallery({
           <fieldset className='cbgd-order' aria-label='How files are shown'>
             {(
               [
-                { mode: 'grid', glyph: '▦', label: 'Grid', hint: 'Show files as thumbnails' },
+                { mode: 'grid', Icon: LayoutGrid, label: 'Grid', hint: 'Show files as thumbnails' },
                 {
                   mode: 'table',
-                  glyph: '☰',
+                  Icon: Rows3,
                   label: 'Table',
                   hint: 'Show files as rows with size, length and date',
                 },
@@ -2196,11 +2843,15 @@ export function MediaGallery({
                   // guardrails-ignore no-raw-action-button: header pill styled by the dense
                   // gallery's own plain CSS, matching its sort neighbours.
                   type='button'
-                  className={`cbgd-order-btn${viewMode === option.mode ? ' is-active' : ''}`}
+                  className={`cbgd-order-btn is-icon${viewMode === option.mode ? ' is-active' : ''}`}
                   aria-pressed={viewMode === option.mode}
+                  /* The pair still says which one is live WITHOUT a word, because it is a
+                     pair: one pill is lit and the other is not, which is the whole argument
+                     for two pills rather than one toggle (see the note above). */
+                  aria-label={option.label}
                   onClick={() => setViewMode(option.mode)}
                 >
-                  <span aria-hidden='true'>{option.glyph}</span> {option.label}
+                  <option.Icon aria-hidden />
                 </button>
               </Tooltip>
             ))}
@@ -2231,11 +2882,12 @@ export function MediaGallery({
                 // guardrails-ignore no-raw-action-button: header pill styled by the dense
                 // gallery's own plain CSS, matching its sort neighbours.
                 type='button'
-                className={`cbgd-order-btn${thumbAutoplay ? ' is-active' : ''}`}
+                className={`cbgd-order-btn is-icon${thumbAutoplay ? ' is-active' : ''}`}
                 aria-pressed={thumbAutoplay}
+                aria-label='Preview all'
                 onClick={() => setThumbAutoplay(!thumbAutoplay)}
               >
-                ▶ Preview all
+                <Play aria-hidden />
               </button>
             </Tooltip>
           ) : null}
@@ -2274,6 +2926,11 @@ export function MediaGallery({
                   }
                 : undefined
             }
+            /* 🔴 The SAME handler and the same dialog the open file's strip uses — it is
+               handed a list either way, so there is no singular path for a plural gesture to
+               drift away from. Tagging forty holiday photographs one at a time is the case
+               the owner will actually hit, and it is one call carrying forty ids. */
+            onTag={onSaveMeta ? () => setTaggingItems(checkedItems) : undefined}
             extra={bulkActions?.(checkedItems, checks.clear)}
           />
         ) : null
@@ -2300,6 +2957,7 @@ export function MediaGallery({
             /* See the related table in the detail view above — "Preview all" has to mean the
                same thing in both views or it is two features wearing one label. */
             autoPreview={thumbAutoplay}
+            exactBytes={meta?.exactBytes === true}
             {...(selectable
               ? {
                   selection: (item: MediaGalleryItem) => ({
@@ -2323,15 +2981,43 @@ export function MediaGallery({
             selection={tileSelection(item)}
             drag={tileDrag(item)}
             autoPreview={thumbAutoplay}
+            measure={meta?.tileMeasure === true}
           />
         ) : null;
       }}
     />
+    </>
   );
 }
 
 const isItem = (i: MediaGalleryItem | undefined): i is MediaGalleryItem => i !== undefined;
 
+/**
+ * The titlebar's meta slot — the one-line facts, plus the DESCRIPTION under them.
+ *
+ * 🔴 The description gets its OWN element rather than joining the ` · ` line, and that is a
+ * layout fact rather than a preference: `.cbgd-meta-line` is `white-space: nowrap` with an
+ * ellipsis, because the same class captions every tile in the grid. A sentence appended to
+ * that line is a sentence nobody can read past its first few words — the exact failure the
+ * task warns about for the TILE caption, one element further up.
+ *
+ * So the slot becomes two children of the titlebar's own wrapping flex row: the facts stay on
+ * the nowrap line they were always on, and `.cbmg-stage-description` is a block that wraps and
+ * is width-capped for readability (`mediaGallery.css`). An item with no description renders
+ * byte-for-byte what it rendered before — `undefined` in, `undefined` out — which is what
+ * keeps this from restyling every gallery in the fleet.
+ */
+function stageMeta(line: string | undefined, description?: string): ReactNode {
+  const words = description?.trim();
+  if (!words) return line;
+  return (
+    <>
+      {line ? <span className='cbmg-stage-facts'>{line}</span> : null}
+      <span className='cbmg-stage-description'>{words}</span>
+    </>
+  );
+}
+
 /**
  * The multi-select bar. Always mounted while `selectable` (never conditionally, so the grid
  * does not jump the moment the first box is ticked) — the destructive half only appears
@@ -2346,6 +3032,7 @@ function BulkBar({
   onToggleAll,
   onClear,
   onDelete,
+  onTag,
   extra,
 }: {
   count: number;
@@ -2357,6 +3044,8 @@ function BulkBar({
   onToggleAll: () => void;
   onClear: () => void;
   onDelete?: () => Promise<void>;
+  /** Open the tag editor over the whole selection. Absent unless the app wired `onSaveMeta`. */
+  onTag?: () => void;
   /** App-specific actions, rendered before Delete. See `bulkActions` on the gallery. */
   extra?: ReactNode;
 }) {
@@ -2368,11 +3057,13 @@ function BulkBar({
             // guardrails-ignore no-raw-action-button: action pill styled by the dense
             // gallery's own plain CSS, matching its neighbors.
             type='button'
-            className={`cbgd-order-btn${armed ? ' is-active' : ''}`}
+            className={`cbgd-order-btn is-icon${armed ? ' is-active' : ''}`}
             aria-pressed={armed === true}
+            // Same bargain as Pin: the two words were the readout, and they stay the name.
+            aria-label={armed ? 'Done selecting' : 'Select'}
             onClick={onToggleArmed}
           >
-            {armed ? 'Done selecting' : 'Select'}
+            <SquareCheck aria-hidden />
           </button>
         </Tooltip>
       ) : null}
@@ -2394,6 +3085,26 @@ function BulkBar({
       {count > 0 ? (
         <>
           <span className='cbmg-bulkbar-spacer' />
+          {/* The gallery's own bulk verb, ahead of the app's: this row reads the same in
+              every app that wires it, for the same reason the detail strip puts the shared
+              capabilities before `detailActions`. */}
+          {onTag ? (
+            <Tooltip content={`Tag the ${count} selected item${count === 1 ? '' : 's'} in one go`}>
+              <button
+                // guardrails-ignore no-raw-action-button: action pill styled by the dense
+                // gallery's own plain CSS, matching its neighbors.
+                type='button'
+                className='cbgd-order-btn is-icon'
+                // The count is in the NAME, because the visible label is a glyph and "tag"
+                // without a number tells a screen reader nothing about what it acts on —
+                // the same argument the delete pill three lines down records.
+                aria-label={`Tag the ${count} selected item${count === 1 ? '' : 's'}`}
+                onClick={onTag}
+              >
+                <Tags aria-hidden />
+              </button>
+            </Tooltip>
+          ) : null}
           {/* App actions come BEFORE Delete on purpose: Delete is the destructive one and
               belongs at the end, furthest from the pointer's resting place after the
               selection is made. */}
@@ -2411,19 +3122,26 @@ function BulkBar({
                 message: 'This cannot be undone.',
               }}
               onDelete={onDelete}
-            >
-              ✕ Delete {count}
-            </DeleteButton>
+              /* 🔴 The COUNT drops off the pill and loses nothing, because this bar prints
+                 "{count} selected" three controls to the left — it was the one number in
+                 the strip that was already stated twice. Both the name and the tooltip
+                 above still carry it, so a reader hovering the trash still learns how many
+                 it takes. */
+              iconOnly
+            />
           ) : null}
-          <button
-            // guardrails-ignore no-raw-action-button: action pill styled by the dense
-            // gallery's own plain CSS, matching its neighbors.
-            type='button'
-            className='cbgd-order-btn'
-            onClick={onClear}
-          >
-            Clear
-          </button>
+          <Tooltip content='Untick everything and leave the tiles alone'>
+            <button
+              // guardrails-ignore no-raw-action-button: action pill styled by the dense
+              // gallery's own plain CSS, matching its neighbors.
+              type='button'
+              className='cbgd-order-btn is-icon'
+              aria-label='Clear the selection'
+              onClick={onClear}
+            >
+              <X aria-hidden />
+            </button>
+          </Tooltip>
         </>
       ) : null}
     </div>