cursedbelt 0.0.0 → 2.3.0

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

@@ -0,0 +1,2431 @@
+import './mediaGallery.css';
+import { formatBytes } from 'cwip/format';
+import type { FileCategory } from 'cwip/file-kind';
+import React, {
+  type DragEvent,
+  type MutableRefObject,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import type { PlayableVideo } from '../../core/media';
+import { CATEGORY_LABEL, FileTypeIcon } from '../components/FileTypeIcon';
+import { DeleteButton } from '../components/DeleteButton';
+import {
+  type CheckboxHeaderState,
+  useCheckboxSelection,
+} from '../hooks/useCheckboxSelection';
+import { DenseGalleryDetail, DenseGalleryShell } from '../media/DenseGalleryShell';
+import { useHlsSource } from '../media/hlsSource';
+import { HoverScrubVideoThumb } from '../media/HoverScrubVideoThumb';
+import { isPlayPauseSpace } from '../media/playerSpaceKey';
+import {
+  LIGHT_RANGE,
+  lightFilter,
+  NO_EDIT,
+  NO_LIGHT,
+  type PictureLight,
+  isLightAdjusted,
+  previewTransform,
+  swapsAxes,
+} from '../media/pictureEdit';
+import type { PictureEditResult } from '../media/PictureEditor';
+import type { MediaOrientation } from '../media/VideoTurner';
+import type { VideoCut } from '../../core/media/videoCuts';
+import {
+  GALLERY_ORDER_OPTIONS,
+  filterGalleryItems,
+  galleryItemCategory,
+  galleryKindOptions,
+  galleryTags,
+  isMarkdownFile,
+  playsWithSpace,
+  snapsToStage,
+  sortGalleryItems,
+} from './mediaGalleryModel';
+import {
+  IMAGE_DWELL_OPTIONS,
+  PLAYBACK_END_LABELS,
+  type PlaybackEndBehavior,
+  nextPlaybackEnd,
+  readImageDwell,
+  readPinStage,
+  readPlaybackEnd,
+  readThumbAutoplay,
+  writeImageDwell,
+  writePinStage,
+  writePlaybackEnd,
+  writeThumbAutoplay,
+  type GalleryViewMode,
+  readViewMode,
+  writeViewMode,
+} from './playbackPreferences';
+import { GalleryTable } from './GalleryTable';
+import { nextInRun, runAdvances, runRepeatsOne, stepId } from './playbackRun';
+import type { MediaGalleryItem, MediaGalleryItemMedia, MediaGalleryOrder } from './types';
+import { createdLabel, type MediaCache, ThumbImg, useItemMedia } from './galleryItemMedia';
+import { Tooltip } from '../components/Tooltip';
+
+import { TruncatedText } from '../components/TruncatedText';
+// The reusable media gallery — the plugin-era mixed gallery generalised to EVERY binary
+// kind the fleet stores. Same design as plugin-media-gallery: a thumbnail-maximal browse
+// grid (hover-scrub video tiles, still photo tiles, type-icon tiles for other binaries)
+// that swaps to an in-page detail view — the right viewer as a big stage on top, actions
+// beside it, the rest of the grid underneath for quick jumping, with a layout-level
+// fullscreen toggle. Presentation + dispatch only: apps map their records to
+// `MediaGalleryItem` and keep auth/signing/deletion on their side.
+
+// Heavy viewers stay off the critical path — each loads only when a matching file opens.
+const LazyVideoPlayer = React.lazy(() =>
+  import('../media/VideoPlayer').then((m) => ({ default: m.VideoPlayer })),
+);
+const LazyPdfViewer = React.lazy(() =>
+  import('../pdf-viewer/PdfViewer').then((m) => ({ default: m.PdfViewer })),
+);
+const LazyWorkbookViewer = React.lazy(() =>
+  import('../workbook-viewer/WorkbookViewer').then((m) => ({ default: m.WorkbookViewer })),
+);
+const LazyMarkdownDoc = React.lazy(() =>
+  import('../markdown/MarkdownDoc').then((m) => ({ default: m.MarkdownDoc })),
+);
+// The rotate/crop/re-light dialog, and its own stylesheet, only once somebody opens it — so an
+// app that never edits a picture pays nothing for the capability being available.
+const LazyPictureEditor = React.lazy(() =>
+  import('../media/PictureEditor').then((m) => ({ default: m.PictureEditor })),
+);
+const LazyFrameGrabber = React.lazy(() =>
+  import('../media/FrameGrabber').then((m) => ({ default: m.FrameGrabber })),
+);
+// The same four gestures for FOOTAGE — a separate dialog from the picture editor because a
+// video's turn can only ever be stored, never baked. See `VideoTurner`'s header.
+const LazyVideoTurner = React.lazy(() =>
+  import('../media/VideoTurner').then((m) => ({ default: m.VideoTurner })),
+);
+// 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
+// bundle rather than a feature flag somebody has to remember to check.
+const LazyVideoCutEditor = React.lazy(() =>
+  import('../media/VideoCutEditor').then((m) => ({ default: m.VideoCutEditor })),
+);
+
+/**
+ * A stored orientation, as a CSS transform — the same `previewTransform` the editor previews
+ * with, so a saved turn and an unsaved one can never render differently.
+ *
+ * Returns an EMPTY style object rather than `transform: none` for the ordinary unturned case:
+ * a `transform` declaration of any value promotes the element to its own compositing layer,
+ * and a wall of gallery tiles is exactly where that is worth not paying for.
+ */
+function orientationStyle(item: MediaGalleryItem): React.CSSProperties {
+  const o = item.orientation;
+  if (!o || (o.turns === 0 && !o.flipX && !o.flipY)) return {};
+  return { transform: previewTransform({ ...NO_EDIT, turns: o.turns, flipX: !!o.flipX, flipY: !!o.flipY }) };
+}
+
+/** Does the stored orientation swap the picture's axes? Drives the fit constraint. */
+function isTurned(item: MediaGalleryItem): boolean {
+  return item.orientation ? swapsAxes(item.orientation.turns) : false;
+}
+
+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 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.
+  const created = createdLabel(item.createdAt);
+  return (
+    <div className='cbgd-meta'>
+      <TruncatedText as='div' className='cbgd-meta-title'>
+        {item.name}
+      </TruncatedText>
+      {line ? <div className='cbgd-meta-line'>{line}</div> : null}
+      {created ? <div className='cbgd-meta-date'>{created}</div> : null}
+    </div>
+  );
+}
+
+/** Extension shown on icon tiles, from the name's last dot (uppercased by CSS). */
+function extLabel(item: MediaGalleryItem): string {
+  const dot = item.name.lastIndexOf('.');
+  const ext = dot > 0 ? item.name.slice(dot + 1) : '';
+  return ext.length > 0 && ext.length <= 5 ? ext : CATEGORY_LABEL[galleryItemCategory(item)];
+}
+
+/** Present only when the consumer opted into `selectable`. */
+interface TileSelection {
+  selected: boolean;
+  /**
+   * True when the box is shown unconditionally. False puts the tile in the quiet mode
+   * described on {@link MediaGalleryProps.selectionReveal} — the CSS still reveals the box
+   * on hover, on keyboard focus, and whenever the tile is selected, so the control is never
+   * actually unreachable, only out of the way.
+   */
+  armed: boolean;
+  onToggle: (shiftKey: boolean) => void;
+}
+
+/** Present only when the consumer passed `onItemDragStart`. */
+interface TileDrag {
+  onDragStart: (event: DragEvent<HTMLElement>) => void;
+  onDragEnd?: () => void;
+}
+
+/**
+ * The wrapper that turns a bare tile into a selectable and/or draggable one.
+ *
+ * The checkbox is an overlay SIBLING of the tile rather than a child of it: every tile
+ * branch below is itself a button (or a HoverScrubVideoThumb that renders one), and a button
+ * inside a button is invalid HTML that browsers silently un-nest. Sitting on top also keeps
+ * the tile's own click meaning "open" — ticking the box must never navigate, which is what
+ * `stopPropagation` in {@link SelectBox} buys.
+ */
+function TileShell({
+  name,
+  selection,
+  drag,
+  children,
+}: {
+  name: string;
+  selection?: TileSelection;
+  drag?: TileDrag;
+  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' : ''}`}
+      // 🔴 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.
+      // Dragging the wrapper also means the drag image is the whole tile, which is what a
+      // person is aiming at.
+      {...(drag
+        ? {
+            draggable: true,
+            onDragStart: (event: DragEvent<HTMLDivElement>) => drag.onDragStart(event),
+            onDragEnd: () => drag.onDragEnd?.(),
+          }
+        : {})}
+    >
+      {children}
+      {selection ? (
+        <SelectBox name={name} selected={selected} onToggle={selection.onToggle} />
+      ) : null}
+    </div>
+  );
+}
+
+function SelectBox({
+  name,
+  selected,
+  onToggle,
+}: {
+  name: string;
+  selected: boolean;
+  onToggle: (shiftKey: boolean) => void;
+}) {
+  return (
+    <span className='cbmg-select-box'>
+      <input
+        // guardrails-ignore no-raw-inputs: a plain control inside a Tailwind-free, plain-CSS row. The Field layer has no slider, and its label chrome would duplicate the label already beside this one.
+        // guardrails-ignore no-raw-inputs: this module is self-contained plain CSS (no
+        // Tailwind in this file, same reason `.cbgd-search` states); cursedbelt's Radix
+        // Checkbox is a button, which cannot be nested over a button tile.
+        type='checkbox'
+        checked={selected}
+        // `readOnly` + `onClick`, not `onChange`: the shift key is only on the CLICK, and
+        // a range gesture is the difference between ticking 40 boxes and ticking two.
+        readOnly
+        onClick={(e) => {
+          e.stopPropagation();
+          onToggle(e.shiftKey);
+        }}
+        aria-label={`Select ${name} for bulk actions (shift-click for a range)`}
+      />
+    </span>
+  );
+}
+
+/** One tile: hover-scrub for videos, a still image for photos, a type-icon card otherwise. */
+function GalleryTile({
+  item,
+  cache,
+  onOpen,
+  selection,
+  drag,
+  autoPreview,
+}: {
+  item: MediaGalleryItem;
+  cache: MediaCache;
+  onOpen: () => void;
+  selection?: TileSelection;
+  drag?: TileDrag;
+  /** Preview every video tile without hovering it — see `readThumbAutoplay`. */
+  autoPreview?: boolean;
+}) {
+  /*
+   * 🔴 ALWAYS wrapped, even with no selection and no drag.
+   *
+   * `TileShell` is not only the checkbox host — it is the SIZING wrapper. `.cbmg-selectable`
+   * carries `height: 100%` on itself and on its first child, which is what makes a tile fill
+   * the cell the virtualized grid measured for it. Returning the bare tile when neither
+   * feature was requested therefore produced a tile with no height constraint at all, and the
+   * only grid that renders tiles that way is the detail view's "More files" strip — so videos
+   * there stretched the full width of the screen at a sliver of their proper height, while
+   * the identical items in the main grid looked correct. Owner report, 2026-08-13.
+   *
+   * With both props absent the shell renders exactly one plain div and no interaction
+   * 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>
+  );
+}
+
+/**
+ * A DOCUMENT's tile picture — page one where a renderer produced it, its FORMAT where not.
+ *
+ * ── 🔴 Why an `onError` and not just an `<img>` ─────────────────────────────────────────
+ * binary-server's derivative contract is that the key is COMPUTED and the object's absence is
+ * the "not ready yet" state, so a host that offers a thumbnail name for every row is offering
+ * one for rows nothing has rendered — and it cannot avoid that by probing, which costs a round
+ * trip per tile. `ThumbImg` beside this already solves it for a PICTURE, where the fallback is
+ * the full-size image; a document has no such fallback, because the full-size object is a PDF
+ * and an `<img>` pointed at one draws the browser's broken-image glyph.
+ *
+ * That glyph is precisely the *"torn page"* `apps/family` has a standing rule against: a
+ * document with no thumbnail must keep drawing its FORMAT, which is honest, rather than a
+ * picture that failed, which reads as the archive being broken. So the error falls back to the
+ * same mark the no-thumbnail branch draws — one appearance for "not rendered" and "not
+ * renderable", because to a reader they are the same fact.
+ *
+ * Falls back ONCE, like `ThumbImg`, and for the same reason: re-pointing `src` on every error
+ * is an infinite request loop on a slow connection.
+ */
+function DocThumb({
+  src,
+  alt,
+  category,
+  ext,
+}: {
+  src?: string;
+  alt: string;
+  category: FileCategory;
+  ext: string;
+}) {
+  const [failed, setFailed] = useState(false);
+  if (!src || failed) {
+    return (
+      <>
+        <FileTypeIcon category={category} size={34} />
+        <span className='cbmg-doc-ext'>{ext}</span>
+      </>
+    );
+  }
+  return (
+    <>
+      {/* `key={src}`: a new thumbnail URL is a new attempt and must not inherit the
+          previous one's recorded failure. */}
+      <img key={src} src={src} alt={alt} loading='lazy' onError={() => setFailed(true)} />
+      <span className='cbmg-doc-badge'>
+        <FileTypeIcon category={category} />
+      </span>
+    </>
+  );
+}
+
+function RawGalleryTile({
+  item,
+  cache,
+  onOpen,
+  autoPreview,
+}: {
+  item: MediaGalleryItem;
+  cache: MediaCache;
+  onOpen: () => void;
+  autoPreview?: boolean;
+}) {
+  const category = galleryItemCategory(item);
+  const { media } = useItemMedia(item, cache);
+
+  if (category === 'video') {
+    const video: PlayableVideo = {
+      id: item.id,
+      name: item.name,
+      streamUrl: media.streamUrl ?? media.url ?? '',
+      posterUrl: media.posterUrl ?? media.thumbnailUrl,
+      durationSeconds: item.durationSeconds,
+      ...(media.processingStatus ? { processingStatus: media.processingStatus } : {}),
+    };
+    return (
+      <HoverScrubVideoThumb
+        video={video}
+        onOpen={onOpen}
+        previewMode='scrub'
+        // The whole grid previewing at once, on request. The tile suppresses it on
+        // coarse-pointer devices by itself, so a phone never plays ninety clips under a thumb.
+        autoPlay={autoPreview ?? false}
+        // A stored turn turns the TILE too — otherwise the grid is a wall of sideways films
+        // whose detail view is upright, which reads as the fix not having worked.
+        {...(item.orientation ? { orientation: item.orientation } : {})}
+      >
+        <GalleryMeta item={item} />
+      </HoverScrubVideoThumb>
+    );
+  }
+
+
+  const full = category === 'image' ? media.url : undefined;
+  const thumb = media.thumbnailUrl ?? full;
+  return (
+    <button
+      // guardrails-ignore no-raw-action-button: opens the item — a full-tile navigation
+      // card styled by the dense gallery's own plain CSS (plugin-media-gallery precedent).
+      type='button'
+      className='cbgd-photo-tile'
+      onClick={onOpen}
+      aria-label={`Open ${item.name}`}
+    >
+      {category === 'image' ? (
+        <div className='cbgd-photo-media' data-turned={isTurned(item) ? 'true' : undefined}>
+          {/* `draggable={false}`: an <img> drags itself by default, which competes with the
+              tile wrapper's own drag payload (see HoverScrubVideoThumb for the full note). */}
+          {/* `key={thumb}`: a row whose thumbnail URL changes gets a fresh attempt rather than
+              inheriting the previous URL's recorded failure. */}
+          {thumb ? (
+            <ThumbImg
+              key={thumb}
+              src={thumb}
+              fallbackSrc={full}
+              alt={item.name}
+              draggable={false}
+              // A stored orientation turns the TILE too. Without this the grid shows a wall of
+              // sideways photographs whose detail view is upright, which reads as the fix not
+              // having worked.
+              style={orientationStyle(item)}
+            />
+          ) : null}
+        </div>
+      ) : (
+        <div className='cbmg-doc-media'>
+          <DocThumb
+            {...(thumb ? { src: thumb } : {})}
+            alt={item.name}
+            category={category}
+            ext={extLabel(item)}
+          />
+        </div>
+      )}
+      <GalleryMeta item={item} />
+    </button>
+  );
+}
+
+/** Bytes for the byte-fed viewers (pdf/sheet/text/code/html), fetched once per item. */
+function useItemBytes(
+  item: MediaGalleryItem,
+  url: string | undefined,
+  loadBytes: ((item: MediaGalleryItem) => Promise<ArrayBuffer>) | undefined,
+  cache: BytesCache,
+): { bytes: ArrayBuffer | null; error: string | null } {
+  const [bytes, setBytes] = useState<ArrayBuffer | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let live = true;
+    setBytes(null);
+    setError(null);
+    let promise = cache.current.get(item.id);
+    if (!promise) {
+      if (loadBytes) {
+        promise = loadBytes(item);
+      } else if (url) {
+        promise = fetch(url).then((res) => {
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          return res.arrayBuffer();
+        });
+      } else {
+        return;
+      }
+      cache.current.set(item.id, promise);
+    }
+    promise
+      .then((buf) => {
+        if (live) setBytes(buf);
+      })
+      .catch((err: unknown) => {
+        // A failed fetch shouldn't poison the cache — reopening the item retries.
+        cache.current.delete(item.id);
+        if (live) setError(err instanceof Error ? err.message : String(err));
+      });
+    return () => {
+      live = false;
+    };
+  }, [item, url, loadBytes, cache]);
+
+  return { bytes, error };
+}
+
+function StageLoading({ label = 'Loading…' }: { label?: string }) {
+  return <div className='cbmg-stage-loading'>{label}</div>;
+}
+
+/** Fallback stage for kinds with no inline viewer — the type icon + a download nudge. */
+function FallbackStage({ item, category }: { item: MediaGalleryItem; category: FileCategory }) {
+  return (
+    <div className='cbmg-stage-panel'>
+      <FileTypeIcon category={category} size={48} />
+      <span className='cbmg-stage-panel-name'>{item.name}</span>
+      <span>
+        {CATEGORY_LABEL[category]}
+        {item.sizeBytes != null ? ` · ${formatBytes(item.sizeBytes)}` : ''} — no inline
+        viewer; use Download.
+      </span>
+    </div>
+  );
+}
+
+function BytesStage({
+  item,
+  category,
+  url,
+  loadBytes,
+  cache,
+}: {
+  item: MediaGalleryItem;
+  category: FileCategory;
+  url: string | undefined;
+  loadBytes: ((item: MediaGalleryItem) => Promise<ArrayBuffer>) | undefined;
+  cache: BytesCache;
+}) {
+  const { bytes, error } = useItemBytes(item, url, loadBytes, cache);
+  if (error) return <StageLoading label={`Couldn't load ${item.name}: ${error}`} />;
+  if (!bytes) return <StageLoading />;
+
+  if (category === 'pdf') {
+    return (
+      <div className='cbmg-stage-doc'>
+        <React.Suspense fallback={<StageLoading label='Loading PDF viewer…' />}>
+          <LazyPdfViewer bytes={bytes} height='100%' />
+        </React.Suspense>
+      </div>
+    );
+  }
+  if (category === 'sheet') {
+    return (
+      <div className='cbmg-stage-doc'>
+        <React.Suspense fallback={<StageLoading label='Loading spreadsheet viewer…' />}>
+          <LazyWorkbookViewer bytes={bytes} />
+        </React.Suspense>
+      </div>
+    );
+  }
+  if (category === 'html') {
+    // Untrusted content: never rendered in-DOM — a fully sandboxed frame (no scripts,
+    // no same-origin), same convention as the notes file viewer.
+    return (
+      <div className='cbmg-stage-doc'>
+        <iframe
+          className='cbmg-stage-frame'
+          sandbox=''
+          title={item.name}
+          srcDoc={new TextDecoder().decode(bytes)}
+        />
+      </div>
+    );
+  }
+  const text = new TextDecoder().decode(bytes);
+  if (category === 'text' && isMarkdownFile(item)) {
+    return (
+      <div className='cbmg-stage-doc'>
+        <React.Suspense fallback={<StageLoading label='Loading renderer…' />}>
+          <div className='cbmg-stage-markdown'>
+            <LazyMarkdownDoc markdown={text} />
+          </div>
+        </React.Suspense>
+      </div>
+    );
+  }
+  return (
+    <div className='cbmg-stage-doc'>
+      <pre className='cbmg-stage-text'>{text}</pre>
+    </div>
+  );
+}
+
+/**
+ * What the stage hands the shared `<VideoPlayer>` — every URL the player can use, and
+ * nothing it cannot.
+ *
+ * 🔴 A separate function because this mapping is where a URL goes to be forgotten. Three
+ * fields the gallery already had — the scrub track, the processing status and now the
+ * adaptive ladder — were resolved by the app, carried on the item, and then simply not
+ * listed here, so the feature was invisible with nothing anywhere reporting a fault. It is a
+ * pure function so a test can read it directly; the rendered player is a Vidstack custom
+ * element that happy-dom never brings to life, so no DOM assertion can see any of this.
+ */
+export function stagePlayableVideo(
+  item: MediaGalleryItem,
+  media: MediaGalleryItemMedia,
+  streamUrl: string,
+): PlayableVideo {
+  return {
+    id: item.id,
+    name: item.name,
+    streamUrl,
+    /*
+     * 🔴 The adaptive ladder, when the app's store has built one — ADDITIONAL to `streamUrl`,
+     * never instead of it. The player prefers it, and every browser without native HLS or
+     * MSE falls back to the line above. A ladder is a real re-encode that arrives long after
+     * upload, so its absence is the ordinary case, not an error.
+     */
+    ...(media.hlsUrl ? { hlsUrl: media.hlsUrl } : {}),
+    ...(media.posterUrl ? { posterUrl: media.posterUrl } : {}),
+    ...(item.durationSeconds != null ? { durationSeconds: item.durationSeconds } : {}),
+    // Scrub-preview thumbnails and the "still optimizing" indicator. Both were already
+    // supported by the player primitive and simply never reached it from here, so every
+    // gallery consumer had a bare timecode scrub bar and no way to tell a slow video from a
+    // broken one.
+    ...(media.vttUrl ? { vttUrl: media.vttUrl } : {}),
+    ...(media.processingStatus ? { processingStatus: media.processingStatus } : {}),
+  };
+}
+
+/**
+ * The `nativeVideoStage` element — a plain `<video>` with the ladder attached to it.
+ *
+ * 🔴 It carries no `src` attribute, and that is the point. `hlsSource.ts` decides between
+ * native HLS (Safari, iPhone — hardware-decoded, no library), hls.js (everywhere else with
+ * MediaSource) and the progressive remux (everything else, and every video whose ladder has
+ * not been built), and it can only make that decision against a real element. React would
+ * also fight the effect for ownership of the attribute if both set it.
+ *
+ * `key`ed on the source by its parent, so stepping to the next clip remounts rather than
+ * re-attaching into a element that is mid-buffer on the previous one.
+ */
+function NativeVideoStage({
+  hlsUrl,
+  streamUrl,
+  poster,
+  repeat,
+  onEnded,
+}: {
+  hlsUrl?: string | undefined;
+  streamUrl: string;
+  poster?: string | undefined;
+  repeat?: boolean;
+  onEnded?: () => void;
+}) {
+  const ref = React.useRef<HTMLVideoElement>(null);
+  useHlsSource(ref, { hlsUrl, streamUrl });
+  return (
+    // biome-ignore lint/a11y/useMediaCaption: arbitrary user-stored files carry no captions
+    <video
+      ref={ref}
+      className='cbmg-stage-video'
+      poster={poster}
+      controls
+      autoPlay
+      playsInline
+      loop={repeat}
+      // A looping element never fires `ended`, so passing both would silently disable
+      // auto-advance rather than combining the two. See `VideoPlayerProps.loop`.
+      onEnded={repeat ? undefined : onEnded}
+    />
+  );
+}
+
+/** The big stage — the right viewer per category. */
+function GalleryStage({
+  item,
+  mediaCache,
+  bytesCache,
+  loadBytes,
+  nativeVideoStage,
+  repeat,
+  onEnded,
+  onStep,
+  canStep,
+  fullscreenOnDoubleClick,
+}: {
+  item: MediaGalleryItem;
+  mediaCache: MediaCache;
+  bytesCache: BytesCache;
+  loadBytes?: (item: MediaGalleryItem) => Promise<ArrayBuffer>;
+  nativeVideoStage?: boolean;
+  repeat?: boolean;
+  onEnded?: () => void;
+  /**
+   * 🔴 Handed to the PLAYER, not drawn on the stage. Vidstack puts these in its own control
+   * bar, which is the only chrome that exists once the video is in browser fullscreen —
+   * see `VideoPlayer`'s `stepSlots`. Every other kind of stage steps from the titlebar
+   * instead, which `DenseGalleryDetail` owns.
+   */
+  onStep?: (delta: -1 | 1) => void;
+  canStep?: boolean;
+  /** False while the SHELL is fullscreen — see `VideoPlayerProps.fullscreenOnDoubleClick`. */
+  fullscreenOnDoubleClick?: boolean;
+}) {
+  const category = galleryItemCategory(item);
+  const { media, resolving } = useItemMedia(item, mediaCache);
+
+  if (category === 'video') {
+    const src = media.streamUrl ?? media.url;
+    if (!src) return <StageLoading label={resolving ? 'Loading…' : 'Video unavailable.'} />;
+    /*
+     * 🔴 A stored orientation turns FOOTAGE too, and the wrapper is what makes that safe.
+     *
+     * A quarter-turned clip is still laid out in its original box, so a portrait clip turned
+     * widescreen overflows the stage it is centred in — the exact complaint that produced this
+     * (*"a video showing in portrait mode that is actually supposed to be widescreen to fill
+     * all the space correctly"*). `.cbmg-stage-turn[data-turned]` swaps the fit constraint the
+     * same way `.cbgd-stage-img` does for pictures. An unturned clip renders inside a plain
+     * `display: contents` wrapper, so the ordinary case is byte-for-byte the old layout.
+     */
+    const turned = isTurned(item);
+    /*
+     * 🔴 The turn travels as a CSS VARIABLE on the wrapper, not as an inline style on the
+     * element. The Vidstack path does not render the `<video>` — its provider does — so there
+     * is no element here to put a style on, and turning the wrapper itself would rotate the
+     * CONTROL BAR with the picture. A variable lets the stylesheet turn exactly the picture
+     * surfaces (the video and the poster) and leave the chrome upright, and it keeps the two
+     * player paths on one code path instead of two that can drift.
+     */
+    const turn = orientationStyle(item).transform;
+    const frame = (inner: React.ReactNode) => (
+      <div
+        className='cbmg-stage-turn'
+        data-turned={turned ? 'true' : undefined}
+        {...(turn ? { style: { '--cbmg-turn': turn } as React.CSSProperties } : {})}
+      >
+        {inner}
+      </div>
+    );
+    if (nativeVideoStage) {
+      return frame(
+        /*
+         * 🔴 The source is ATTACHED, not declared, because a ladder is not a `src`.
+         *
+         * An `.m3u8` on `video.src` plays on Safari and every iPhone and on nothing else, so
+         * the choice between native HLS, hls.js and the progressive remux has to be made
+         * against the element — see `NativeVideoStage` / `hlsSource.ts`. A plain `src={src}`
+         * here is what made `hlsUrl` reach this stage and do nothing.
+         */
+        <NativeVideoStage
+          key={media.hlsUrl ?? src}
+          hlsUrl={media.hlsUrl}
+          streamUrl={src}
+          poster={media.posterUrl}
+          repeat={repeat}
+          {...(onEnded ? { onEnded } : {})}
+        />,
+      );
+    }
+    return frame(
+      <React.Suspense fallback={<StageLoading label='Loading player…' />}>
+        <LazyVideoPlayer
+          video={stagePlayableVideo(item, media, src)}
+          autoPlay
+          loop={repeat}
+          {...(repeat ? {} : { onEnded })}
+          {...(onStep ? { onStep, canStep: canStep !== false } : {})}
+          {...(fullscreenOnDoubleClick === false ? { fullscreenOnDoubleClick: false } : {})}
+        />
+      </React.Suspense>
+    );
+  }
+
+  if (category === 'image') {
+    if (!media.url) return <StageLoading label={resolving ? 'Loading…' : 'Image unavailable.'} />;
+    return (
+      <div className='cbgd-stage-img' data-turned={isTurned(item) ? 'true' : undefined}>
+        {/* A stored orientation is applied as a transform, never baked — see
+            `MediaGalleryItem.orientation`. `data-turned` lets the stylesheet swap the fit
+            constraint: a quarter-turned picture is laid out in its ORIGINAL box, so without it
+            a portrait scan turned upright overflows the frame it is centred in. */}
+        <img src={media.url} alt={item.name} style={orientationStyle(item)} />
+      </div>
+    );
+  }
+
+  if (category === 'audio') {
+    if (!media.url) return <StageLoading label={resolving ? 'Loading…' : 'Audio unavailable.'} />;
+    return (
+      <div className='cbmg-stage-panel'>
+        <FileTypeIcon category='audio' size={48} />
+        <span className='cbmg-stage-panel-name'>{item.name}</span>
+        {/* 🔴 Audio takes the same `loop`/`onEnded` pair as video, and for the same reason a
+            still takes a dwell timer: a run that reaches a track it cannot advance past stops
+            dead. A mixed folder holding one voice memo used to end the album there. The two
+            props stay mutually exclusive — a looping element never fires `ended`. */}
+        {/* biome-ignore lint/a11y/useMediaCaption: arbitrary user-stored files carry no captions */}
+        <audio src={media.url} controls loop={repeat} {...(repeat ? {} : { onEnded })} />
+      </div>
+    );
+  }
+
+  if (
+    category === 'pdf' ||
+    category === 'sheet' ||
+    category === 'html' ||
+    category === 'text' ||
+    category === 'code' ||
+    category === 'data'
+  ) {
+    if (resolving) return <StageLoading />;
+    return (
+      <BytesStage
+        item={item}
+        category={category}
+        url={media.url}
+        loadBytes={loadBytes}
+        cache={bytesCache}
+      />
+    );
+  }
+
+  return <FallbackStage item={item} category={category} />;
+}
+
+function KindChips({
+  options,
+  value,
+  onChange,
+  tags,
+  activeTag,
+  onTagChange,
+}: {
+  options: { value: FileCategory; label: string }[];
+  value: FileCategory | null;
+  onChange: (kind: FileCategory | null) => void;
+  tags: string[];
+  activeTag: string | null;
+  onTagChange: (tag: string | null) => void;
+}) {
+  if (options.length === 0 && tags.length === 0) return null;
+  return (
+    <div className='cbgd-filterstrip'>
+      {options.length > 0 ? (
+        <>
+          <button
+            // guardrails-ignore no-raw-action-button: filter chip styled by the dense
+            // gallery's own plain CSS (`.cbgd-chip`), matching the plugin galleries.
+            type='button'
+            className={`cbgd-chip${value === null ? ' is-active' : ''}`}
+            aria-pressed={value === null}
+            onClick={() => onChange(null)}
+          >
+            All
+          </button>
+          {options.map((opt) => (
+            <button
+              // guardrails-ignore no-raw-action-button: filter chip — see above.
+              type='button'
+              key={opt.value}
+              className={`cbgd-chip${value === opt.value ? ' is-active' : ''}`}
+              aria-pressed={value === opt.value}
+              onClick={() => onChange(value === opt.value ? null : opt.value)}
+            >
+              {opt.label}
+            </button>
+          ))}
+        </>
+      ) : null}
+      {tags.map((tag) => (
+        <button
+          // guardrails-ignore no-raw-action-button: filter chip — see above.
+          type='button'
+          key={tag}
+          className={`cbgd-chip${activeTag === tag ? ' is-active' : ''}`}
+          aria-pressed={activeTag === tag}
+          onClick={() => onTagChange(activeTag === tag ? null : tag)}
+        >
+          {tag}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+export interface MediaGalleryProps {
+  items: MediaGalleryItem[];
+  /** Header title. */
+  title?: string;
+  loading?: boolean;
+  /** Infinite scroll — forwarded to the virtualized grids. */
+  onNearEnd?: () => void;
+  initialOrder?: MediaGalleryOrder;
+  /** Extra per-item actions in the detail view (use `cbgd-order-btn` styling to match). */
+  detailActions?: (item: MediaGalleryItem) => ReactNode;
+  /** When set, the detail view offers Delete (confirm-gated). Closes the detail on success. */
+  onDelete?: (item: MediaGalleryItem) => void | Promise<void>;
+  /** Header slot after the search box — e.g. the app's view toggle or an upload control. */
+  headerExtra?: ReactNode;
+  /**
+   * Draw the gallery's own header row, or not. Default `'header'`.
+   *
+   * See {@link DenseGalleryShellProps.chrome}. `'none'` is for an app that has moved this
+   * row's controls somewhere else — collections put them in a vertical activity bar — and
+   * it should be passed together with the controlled {@link viewMode} and {@link query}
+   * below, or the gallery keeps state that nothing on screen can reach.
+   */
+  chrome?: 'header' | 'none';
+  /**
+   * Preview every video tile at once, CONTROLLED by the app.
+   *
+   * 🔴 For an app rendering `chrome='none'`. The pill that toggles this lives in this
+   * component's header, so an app that moved its view controls into its own chrome had no way
+   * to reach the feature at all — `apps/collections`, 2026-09-09. Pass both or neither:
+   * `previewAll` alone would be a control the reader cannot move.
+   */
+  previewAll?: boolean;
+  /** Told when the app-owned toggle changes — see {@link MediaGalleryProps.previewAll}. */
+  onPreviewAllChange?: (next: boolean) => void;
+  /** Whether there is anything to preview, so an app's own button can hide itself the way the
+   *  header pill does — a toggle that provably does nothing is worse than an absent one. */
+  onPreviewableChange?: (hasVideo: boolean) => void;
+  /**
+   * Tiles or rows, when the CONSUMER owns that. Omit for the default, where the gallery
+   * holds it and remembers it across visits (`readViewMode`).
+   *
+   * 🔴 Controlled does NOT move the remembering. The gallery still writes the shared
+   * `readViewMode` key itself when the toggle is used, so an app whose pills live outside
+   * the gallery does not quietly stop remembering — see `setViewMode` in the body.
+   */
+  viewMode?: GalleryViewMode;
+  onViewModeChange?: (mode: GalleryViewMode) => void;
+  /** The search text, when the consumer owns it. Omit and the gallery's own box holds it. */
+  query?: string;
+  onQueryChange?: (query: string) => void;
+  /** Observe the open item. With `selectedId` set this becomes a request rather than a
+   *  notification — the consumer decides whether to honour it. */
+  onSelectedChange?: (item: MediaGalleryItem | null) => void;
+  /**
+   * Which item is open, when the CONSUMER owns that. Omit for the default behavior, where
+   * the gallery holds it. Pass it (with `onSelectedChange`) when the app needs to close the
+   * detail view from its own chrome — see the note by `selectedId` in the body.
+   */
+  selectedId?: string | null;
+  /** Custom byte loader for the pdf/sheet/text/html stages (default: `fetch(item.url)`). */
+  loadBytes?: (item: MediaGalleryItem) => Promise<ArrayBuffer>;
+  /** Shown when there are no items and not loading. */
+  empty?: ReactNode;
+  emptyAction?: ReactNode;
+  minColumnWidth?: number;
+  /** Big view uses a native `<video controls>` instead of the Vidstack player. */
+  nativeVideoStage?: boolean;
+  searchPlaceholder?: string;
+  /**
+   * Opt in to multi-select: a checkbox on every tile, plus a bulk bar with the count, a
+   * select-all/clear toggle and a confirm-gated Delete. Off by default, so no existing
+   * consumer changes behavior.
+   *
+   * The gallery owns the selection rather than taking it as a prop, because a ⇧ range means
+   * "the items between these two AS DISPLAYED" — and the display order is the gallery's
+   * (it holds the query, the kind/tag chips and the sort). A consumer-held set could not
+   * compute a range without duplicating all of that. `onSelectionChange` is there to
+   * OBSERVE it.
+   */
+  selectable?: boolean;
+  /**
+   * When the per-tile checkboxes are visible. Only consulted while `selectable`.
+   *
+   * `'always'` (the default, and what every consumer got before this existed) paints a box
+   * on every tile permanently. `'on-demand'` keeps the grid clean: a box appears on the tile
+   * under the pointer, on the tile holding keyboard focus, on any tile already selected, and
+   * on every tile at once while the bulk bar's **Select** toggle is on.
+   *
+   * 🔴 The toggle is not redundant with hover, and dropping it would make this mode a
+   * regression on a phone: a touch device has no hover, so without an explicit way to arm
+   * the grid the first box could never be reached. Hover is the shortcut for a mouse; the
+   * toggle is the one that always works.
+   */
+  selectionReveal?: 'always' | 'on-demand';
+  /** Runs on the bulk bar's confirmed Delete. The selection clears once it resolves. */
+  onBulkDelete?: (items: MediaGalleryItem[]) => void | Promise<void>;
+  /**
+   * App-specific actions for the current selection, rendered in the bulk bar beside Delete.
+   * Given the checked items and a `clearSelection` to call once the action has run.
+   *
+   * 🔴 Exists because Delete was the ONLY thing a selection could do, and an app whose files
+   * live in folders needs to MOVE them — which apps were expressing as drag-and-drop only.
+   * Drag is a pointer gesture with no keyboard equivalent and no touch equivalent worth
+   * having (dragging a tile onto a sidebar row on a phone is not a real gesture), so an
+   * app that offers only drag has a feature its owner cannot reach from half their devices.
+   */
+  bulkActions?: (items: MediaGalleryItem[], clearSelection: () => void) => ReactNode;
+  /** Observe the selection (a count elsewhere, URL sync). The gallery still owns it. */
+  onSelectionChange?: (items: MediaGalleryItem[]) => void;
+  /**
+   * Make every tile a drag SOURCE, so the app can accept a drop somewhere of its own — a
+   * folder tree, an album list, a trash target.
+   *
+   * The gallery deliberately does not know what a drag MEANS: it fires this with the item
+   * and the raw event, and the consumer fills the `DataTransfer` in whatever vocabulary its
+   * own drop targets read. Anything richer (a `dragType` string, a payload builder) would be
+   * this component taking a position on an app's data model, which is exactly what keeps a
+   * shared gallery shared.
+   *
+   * 🔴 A drag that carries the SELECTION rather than the one tile under the cursor is the
+   * app's call too, and both are reasonable — the consumer has `onSelectionChange` and can
+   * decide. The gallery only guarantees that dragging a tile does not also open it.
+   */
+  onItemDragStart?: (item: MediaGalleryItem, event: DragEvent<HTMLElement>) => void;
+  /** Paired with `onItemDragStart` — fires whether the drag was dropped or abandoned. */
+  onItemDragEnd?: () => void;
+
+  /*
+   * ── Standard detail-view capabilities ────────────────────────────────────────────────
+   *
+   * The owner, 2026-08-14, comparing `apps/family`'s viewer with `apps/collections`': *"the
+   * buttons under are missing for screenshots and thumbnails and more … These should be in cb
+   * and shouldn't have to have a separate media player in family that doesn't get all the
+   * enhancements for free, so share it."*
+   *
+   * He was reading a real structural problem. Prev/Next/Pin/Stop-at-the-end/Download/Delete
+   * were already shared, but Rename, the thumbnail picker and the picture adjustment were
+   * written INSIDE `apps/collections`' `detailActions` — so every one of them was a feature
+   * exactly one app had, and the next app to want one would have written a third copy.
+   *
+   * 🔴 Each is a HANDLER, not a boolean. An app that cannot persist the result does not pass
+   * the handler and the button is absent — which is the honest state, and it means a control
+   * can never appear on a surface that would then fail to save what it did. `detailActions`
+   * stays for what is genuinely one app's (collections' privacy lock, family's tagging panel).
+   */
+
+  /** Offer Rename. Renders an inline field in the action row rather than a `window.prompt`. */
+  onRename?: (item: MediaGalleryItem, name: string) => void | Promise<void>;
+  /**
+   * Offer "Choose thumbnail" on a VIDEO — scrub to a moment, frame it, save that still as the
+   * item's poster. An image is its own thumbnail, so the control is not offered on one.
+   */
+  onSaveThumbnail?: (item: MediaGalleryItem, poster: Blob) => void | Promise<void>;
+  /**
+   * Offer taking a full-resolution still out of a VIDEO — the "screenshot" half. Shares one
+   * dialog with the thumbnail picker, because both are the same gesture (find the moment) with
+   * two different outputs; see {@link FrameGrabber}.
+   */
+  onSaveSnapshot?: (
+    item: MediaGalleryItem,
+    still: Blob,
+    atSeconds: number,
+  ) => void | Promise<void>;
+  /**
+   * Offer "Edit picture" on an IMAGE — turn, mirror, crop and re-light it. See
+   * {@link PictureEditResult}: the app receives the baked bytes AND the edit as a value, so an
+   * app that can store an orientation losslessly may do that instead of keeping a re-encode.
+   */
+  onSaveEdit?: (item: MediaGalleryItem, result: PictureEditResult) => void | Promise<void>;
+  /**
+   * Store which way up a VIDEO plays — the other half of the owner's 2026-08-14 report:
+   * *"a video showing in portrait mode that is actually supposed to be widescreen to fill all
+   * the space correctly."*
+   *
+   * 🔴 Separate from `onSaveEdit` on purpose, and not because of the file type. `onSaveEdit`
+   * hands back BAKED BYTES beside the edit, so an app that takes it has to decide what to do
+   * with a blob; a video's turn has no bytes and never can (rotating footage means re-encoding
+   * every frame, invalidating the remux, poster, sprite and VTT already built for it). An app
+   * that stores an orientation on the row — see {@link MediaGalleryItem.orientation} — supplies
+   * this one and gets the turn control on its films for free.
+   *
+   * `undefined` means "no turn stored": the app should clear the row, not write zeroes it then
+   * has to interpret.
+   */
+  onSaveOrientation?: (
+    item: MediaGalleryItem,
+    orientation: MediaOrientation | undefined,
+  ) => void | Promise<void>;
+  /**
+   * Accept a list of sections to CUT OUT of a video.
+   *
+   * The owner's design, 2026-08-25: *"I will just mark them and send them to binary-server to
+   * handle it with the video software it uses ... It can then remove the parts of the video I
+   * don't want, save a new copy and I can view it when it's done."* So this is a REQUEST, not
+   * an edit: the gallery hands over a cut list and the app queues it. Nothing here is changed,
+   * and no byte is touched in the browser — see `VideoCutEditor`'s header for why that is the
+   * right place to draw the line.
+   *
+   * 🔴 Passing this is what turns the feature on, per app. There is no flag and no config:
+   * an app without a pipeline that can execute a cut list must not offer a control that
+   * queues one into nothing, and — because the editor is lazily imported — an app that does
+   * not pass it does not ship the dialog either.
+   *
+   * Rejecting keeps the dialog open with the marks intact; a failed request must not cost
+   * somebody the minutes of scrubbing that produced the list.
+   */
+  onTrimVideo?: (item: MediaGalleryItem, cuts: VideoCut[]) => 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
+   * will this be ready" is a question only the app can answer.
+   */
+  trimNote?: ReactNode;
+  /**
+   * Let "Edit picture" offer **Replace the original** as well as Save-a-copy. Off by default:
+   * `apps/family`'s first rule is that every byte in it is irreplaceable, and a default-on
+   * destructive save would be wrong in the app that asked for the feature.
+   */
+  allowPictureReplace?: boolean;
+  /**
+   * 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.
+   *
+   * 🔴 It reaches the stage through a CSS custom property on the gallery root rather than a
+   * prop threaded into the player, because the stage is Vidstack's and several components
+   * deep. Pass `false` in an app where adjusting the picture is meaningless.
+   */
+  pictureControls?: boolean;
+}
+
+/**
+ * The fleet's shared media gallery. Feed it `MediaGalleryItem`s (any binary kind); it
+ * renders the dense browse grid and the in-page detail view with the right viewer.
+ */
+export function MediaGallery({
+  items,
+  title = 'Media',
+  loading,
+  onNearEnd,
+  initialOrder = 'recent',
+  detailActions,
+  onDelete,
+  headerExtra,
+  chrome = 'header',
+  previewAll,
+  onPreviewAllChange,
+  onPreviewableChange,
+  viewMode: controlledViewMode,
+  onViewModeChange,
+  query: controlledQuery,
+  onQueryChange,
+  onSelectedChange,
+  selectedId: controlledSelectedId,
+  loadBytes,
+  empty,
+  emptyAction,
+  minColumnWidth,
+  nativeVideoStage,
+  searchPlaceholder = 'Search files…',
+  selectable = false,
+  selectionReveal = 'always',
+  onBulkDelete,
+  bulkActions,
+  onSelectionChange,
+  onItemDragStart,
+  onItemDragEnd,
+  onRename,
+  onSaveThumbnail,
+  onSaveSnapshot,
+  onSaveEdit,
+  onSaveOrientation,
+  allowPictureReplace = false,
+  pictureControls = true,
+  onTrimVideo,
+  trimNote,
+}: MediaGalleryProps) {
+  const [uncontrolledQuery, setUncontrolledQuery] = useState('');
+  /** Controlled when the consumer passes `query`, uncontrolled otherwise — see the prop. */
+  const query = controlledQuery !== undefined ? controlledQuery : uncontrolledQuery;
+  const setQuery = useCallback(
+    (next: string): void => {
+      if (controlledQuery === undefined) setUncontrolledQuery(next);
+      onQueryChange?.(next);
+    },
+    [controlledQuery, onQueryChange],
+  );
+  const [order, setOrder] = useState<MediaGalleryOrder>(initialOrder);
+  const [kind, setKind] = useState<FileCategory | null>(null);
+  const [tag, setTag] = useState<string | null>(null);
+  const [uncontrolledId, setUncontrolledId] = useState<string | null>(null);
+  /**
+   * Controlled when the consumer passes `selectedId`, uncontrolled otherwise — the standard
+   * React pattern, added so an app can close the detail view from its OWN chrome.
+   *
+   * 🔴 The case that needed it: a video fills the screen and the only way back to the grid
+   * was a button inside the gallery. Clicking the app's own "Collections" heading did
+   * nothing, because the gallery held the open item privately and nothing outside could
+   * reach it. Passing `selectedId` makes the app the owner of that decision.
+   */
+  const selectedId = controlledSelectedId !== undefined ? controlledSelectedId : uncontrolledId;
+  // Only meaningful under `selectionReveal='on-demand'` — see the prop's doc comment.
+  const [selectArmed, setSelectArmed] = useState(false);
+  // What happens when a video ends — remembered across visits. See playbackPreferences.ts.
+  const [playbackEnd, setPlaybackEnd] = useState<PlaybackEndBehavior>(readPlaybackEnd);
+  // Whether the stage stays pinned at the top while the related grid scrolls under it.
+  const [pinStage, setPinStage] = useState<boolean>(readPinStage);
+  /*
+   * 🔴 The shell's `⤢ Fullscreen` lives HERE rather than inside `DenseGalleryDetail`,
+   * because the video stage has to know about it.
+   *
+   * Owner, 2026-09-08: *"double clicking a full screen video should change back from full
+   * screen to non-full screen view."* Vidstack binds `dblpointerup` to `toggle:fullscreen`
+   * on the picture, and the shell binds `dblclick` on the frame to leaving ITS fullscreen —
+   * armed at the same time, one double-click does both and the video ends up in browser
+   * fullscreen instead of back in the grid. The state has to be visible to whoever renders
+   * the player so exactly one of the two is armed at a time, and this is that place.
+   * Deliberately NOT persisted: a full-bleed stage is a thing you do to one file, not a
+   * mode you live in, and `pinStage` above is the one that IS remembered.
+   */
+  const [fullStage, setFullStage] = useState(false);
+  // Seconds a still holds the stage during a run — the slideshow speed. See readImageDwell.
+  const [imageDwell, setImageDwell] = useState<number>(readImageDwell);
+  /*
+   * Do all the video TILES preview themselves without being hovered? Off by default.
+   *
+   * 🔴 CONTROLLABLE from outside since 2026-09-09, and the reason is `chrome='none'`. The
+   * toggle is a pill in this component's HEADER, so an app that moved its view controls
+   * elsewhere and turned the header off (apps/collections, whose sort, kind, privacy and
+   * grid/table all live in an activity bar now) lost the feature entirely — reported as
+   * *"We are missing the preview all button that let's all the videos play at once in the
+   * gallery and we need it back."* Uncontrolled behaviour is byte-for-byte unchanged.
+   */
+  const [uncontrolledThumbAutoplay, setUncontrolledThumbAutoplay] =
+    useState<boolean>(readThumbAutoplay);
+  const thumbAutoplay = previewAll ?? uncontrolledThumbAutoplay;
+  const setThumbAutoplay = (next: boolean): void => {
+    // The PREFERENCE is written either way — it is a fleet-shared key, and an app driving the
+    // toggle from its own chrome must not stop this gallery remembering the answer.
+    writeThumbAutoplay(next);
+    if (onPreviewAllChange) onPreviewAllChange(next);
+    else setUncontrolledThumbAutoplay(next);
+  };
+  /**
+   * Tiles or rows. Remembered, and `grid` by default — see `readViewMode` for why a shared
+   * component must not change what 17 apps look like on upgrade.
+   */
+  const [uncontrolledViewMode, setUncontrolledViewMode] = useState<GalleryViewMode>(readViewMode);
+  const viewMode = controlledViewMode !== undefined ? controlledViewMode : uncontrolledViewMode;
+  /**
+   * 🔴 The write to storage stays HERE, in both modes.
+   *
+   * A consumer that owns the value still shares the key with every other app (see
+   * `readViewMode`), so leaving the persistence to the caller is how one app quietly stops
+   * remembering — the failure would be invisible until somebody reloaded.
+   */
+  const setViewMode = useCallback(
+    (next: GalleryViewMode): void => {
+      if (controlledViewMode === undefined) setUncontrolledViewMode(next);
+      writeViewMode(next);
+      onViewModeChange?.(next);
+    },
+    [controlledViewMode, onViewModeChange],
+  );
+  const mediaCache: MediaCache = useRef(new Map());
+  const bytesCache: BytesCache = useRef(new Map());
+
+  const kindOptions = useMemo(() => galleryKindOptions(items), [items]);
+  const tags = useMemo(() => galleryTags(items), [items]);
+  const displayItems = useMemo(
+    () => sortGalleryItems(filterGalleryItems(items, { query, kind, tag }), order),
+    [items, query, kind, tag, order],
+  );
+
+  /*
+   * Is there anything to preview at all?
+   *
+   * 🔴 Reported to the app so its OWN Preview-all button can hide itself exactly as the header
+   * pill does. A toggle that provably does nothing to the grid in front of you is worse than
+   * an absent one, and an app rendering `chrome='none'` cannot work this out for itself — it
+   * hands this component a page and gets a filtered, sorted view back.
+   */
+  const hasPreviewable = useMemo(
+    () => displayItems.some((i) => galleryItemCategory(i) === 'video'),
+    [displayItems],
+  );
+  const previewableRef = useRef<boolean | null>(null);
+  useEffect(() => {
+    // Fired on a real CHANGE, never on an array's identity — the same rule (and the same
+    // hard-won reason) as the selection notifier below.
+    if (previewableRef.current === hasPreviewable) return;
+    previewableRef.current = hasPreviewable;
+    onPreviewableChange?.(hasPreviewable);
+  }, [hasPreviewable, onPreviewableChange]);
+
+  // Over the DISPLAYED order, so a ⇧ range is the range the owner can see, and so filtering
+  // a tile away drops it from the count instead of leaving the bulk bar lying.
+  const displayIds = useMemo(() => displayItems.map((i) => i.id), [displayItems]);
+  const checks = useCheckboxSelection(displayIds);
+  const checkedItems = useMemo(
+    () => checks.selectedIds.map((id) => displayItems.find((i) => i.id === id)).filter(isItem),
+    [checks.selectedIds, displayItems],
+  );
+  /*
+   * ── 🔴 Notify when the SELECTION changes — not when an array's identity does ──────────
+   *
+   * This was `useEffect(() => onSelectionChange?.(checkedItems), [checkedItems,
+   * onSelectionChange])`, and it is an infinite render loop for a completely ordinary
+   * consumer. Every link in the chain is a fresh object on each render:
+   *
+   *   `items={data?.items ?? []}`     a new `[]` while the query is in flight
+   *     → `displayItems` re-memoizes  (its dep changed by identity)
+   *     → `checkedItems` re-memoizes  (same)
+   *     → this effect fires           (dep changed by identity)
+   *     → the consumer's handler runs `setPicked(chosen.map(...))` — a NEW array, so
+   *       React cannot bail out — which re-renders and produces the next fresh `[]`.
+   *
+   * That is React error #185, *"Maximum update depth exceeded"*, and it takes the whole
+   * page down before first paint. `onSelectionChange` being an inline arrow — which every
+   * consumer in the fleet writes, because that is what the prop invites — closes the loop
+   * by itself even when `items` is stable.
+   *
+   * Measured in `apps/family` on 2026-08-23: `/#/p/<id>/media` never painted, in production
+   * as well as in a rehearsal, and it held six browser specs and a whole app's suite out of
+   * the deploy gate for four days while the cause was recorded as "something about that
+   * route's mounting".
+   *
+   * 🔴 The key is the selected IDS, joined — a value, not a reference — so the effect fires
+   * exactly when the answer changes and never merely because a render happened. Both the
+   * items and the callback are read through refs at fire time, which is the same discipline
+   * `advance` above already uses and for the same reason: these are inputs the effect needs
+   * CURRENT, not inputs whose identity should restart it. `\u0000` as the joiner because it
+   * cannot occur in an id.
+   */
+  const notifyRef = useRef(onSelectionChange);
+  notifyRef.current = onSelectionChange;
+  const checkedRef = useRef(checkedItems);
+  checkedRef.current = checkedItems;
+  const checkedKey = checks.selectedIds.join('\u0000');
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `checkedKey` is the value form of the only dependency that should restart this; the other two are read through refs on purpose — see the note above, and `advance` for the same pattern.
+  useEffect(() => {
+    notifyRef.current?.(checkedRef.current);
+  }, [checkedKey]);
+
+  const selected = selectedId ? (items.find((i) => i.id === selectedId) ?? null) : null;
+  const select = (item: MediaGalleryItem | null) => {
+    // Only move our own state when we own it; a controlled consumer decides for itself what
+    // the notification means.
+    if (controlledSelectedId === undefined) setUncontrolledId(item?.id ?? null);
+    onSelectedChange?.(item);
+  };
+
+  /**
+   * Step through the DISPLAYED order — the same order the grid shows, so "next" always means
+   * the tile to the right rather than a hidden neighbour from the unfiltered set.
+   *
+   * 🔴 It WRAPS, and that is `tsk_01KZZY085DFN8GW0RQJ8S7MYRS`. Owner, 2026-08-14: *"either
+   * button always goes to another image even on the edges."* This file used to argue the
+   * opposite in a comment right here — that looping back to the first item "reads as it
+   * restarted rather than it finished" — and the observable consequence was a `disabled`
+   * arrow on a full album, which reads as a broken button: nothing on the stage says which
+   * item of how many you are looking at, so there is no edge to have reached.
+   *
+   * Automatic advance does NOT share this rule; it asks {@link nextInRun}, where `next`
+   * still stops after the last item and only `all`/`shuffle` keep going. The two gestures
+   * mean different things — see the note on `stepId`.
+   */
+  const step = (delta: number): void => {
+    const nextId = stepId(displayIds, selectedId, delta);
+    const next = nextId ? displayItems.find((i) => i.id === nextId) : undefined;
+    if (next) select(next);
+  };
+
+  /*
+   * ── The standard detail capabilities' own state ───────────────────────────────────────
+   *
+   * All four are scoped to the OPEN item and cleared when the selection moves, which is why
+   * they live here rather than inside the action row: a rename field left open over the next
+   * file would rename the wrong one, and a light adjustment is about the picture in front of
+   * you. `light` deliberately does NOT persist across items or sessions — it is a way to look
+   * at something dark, not a setting, and a remembered filter silently re-tints every other
+   * photograph the owner opens afterwards.
+   */
+  const [renaming, setRenaming] = useState<string | null>(null);
+  const [renameDraft, setRenameDraft] = useState('');
+  const [editingPicture, setEditingPicture] = useState<MediaGalleryItem | null>(null);
+  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);
+  const [grabbing, setGrabbing] = useState<{ item: MediaGalleryItem; at: number } | null>(null);
+  const [showPicture, setShowPicture] = useState(false);
+  const [light, setLight] = useState<PictureLight>(NO_LIGHT);
+
+  // `selectedId` is the KEY this effect exists for, not a value it reads — the point is to
+  // clear the row's state whenever the open item changes. Biome sees an unread dependency;
+  // removing it would make the reset fire once and never again, so a rename field would
+  // survive onto the next file and rename the wrong one.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: explained immediately above
+  useEffect(() => {
+    setRenaming(null);
+    setEditingPicture(null);
+    setLight(NO_LIGHT);
+  }, [selectedId]);
+
+  // 🔴 Enabled whenever there is somewhere else to go, NOT only away from the edges — the
+  // arrows wrap now. A one-item album is the only set with no other item, so it is the only
+  // one where an arrow is genuinely dead.
+  const canStep = displayItems.length > 1;
+
+  /*
+   * ── The RUN: what plays after this one finishes ──────────────────────────────────────
+   *
+   * The rules are in `playbackRun.ts` (pure, tested); this is the state they need.
+   * `playedRef` is the shuffle pass — a ref rather than state because advancing must not
+   * re-render on its own, and because the value it must read is the one from the step that
+   * just happened, not the one from the last committed render.
+   *
+   * 🔴 Every input `advance` reads travels through a ref, and none of them are dependencies.
+   *
+   * `advance` is handed to a `<video>`'s `onEnded` and to a dwell `setTimeout`. If it were
+   * rebuilt whenever the displayed order or the selection changed, the timeout effect below
+   * would tear down and restart on every one of those changes — so a picture whose gallery
+   * re-sorted, or whose neighbour finished resolving its URLs, would silently restart its
+   * dwell and hold the stage forever. Reading through refs keeps ONE stable callback whose
+   * inputs are always current, which is the property both consumers actually need.
+   */
+  const playbackEndRef = useRef(playbackEnd);
+  const displayIdsRef = useRef(displayIds);
+  const selectedIdRef = useRef(selectedId);
+  const itemsRef = useRef(items);
+  const selectRef = useRef(select);
+  playbackEndRef.current = playbackEnd;
+  displayIdsRef.current = displayIds;
+  selectedIdRef.current = selectedId;
+  itemsRef.current = items;
+  selectRef.current = select;
+
+  const playedRef = useRef<string[]>([]);
+  const advance = useCallback(() => {
+    const step = nextInRun({
+      behavior: playbackEndRef.current,
+      ids: displayIdsRef.current,
+      currentId: selectedIdRef.current,
+      played: playedRef.current,
+    });
+    playedRef.current = step.played;
+    if (!step.nextId) return;
+    const next = itemsRef.current.find((i) => i.id === step.nextId);
+    if (next) selectRef.current(next);
+  }, []);
+
+  /*
+   * Changing the setting, or changing WHAT IS DISPLAYED, starts a fresh shuffle pass.
+   *
+   * A pass records ids, so a pass carried across a filter change is a pass holding ids that
+   * are no longer on screen — shuffle would then behave as though half the new folder had
+   * already played and refuse to reach it until the pass emptied. The selection is
+   * deliberately NOT part of this key: every automatic advance changes it, and resetting the
+   * pass there would make shuffle stateless, which is the bug the pass exists to prevent.
+   *
+   * `\u0000` as the joiner because it cannot occur in an id, so no two different sets can
+   * collide into one key.
+   */
+  const runKey = `${playbackEnd}\u0000${displayIds.join('\u0000')}`;
+  const lastRunKey = useRef(runKey);
+  if (lastRunKey.current !== runKey) {
+    lastRunKey.current = runKey;
+    playedRef.current = [];
+  }
+
+  /**
+   * A still picture (or a PDF, or a text file) has no `ended` event, so a run that reaches
+   * one would stop dead. This is the *"for images they can have a time to stay on them and
+   * play through like a slideshow"* half of the owner's spec, and it is what makes a mixed
+   * folder work: a video holds the stage until it finishes, everything else holds it for the
+   * configured dwell, and the run continues either way.
+   *
+   * 🔴 It deliberately does not run for `video` or `audio` even when they are broken. A clip
+   * whose bytes 404 never fires `ended`, so a dwell timer would advance past it — hiding the
+   * failure by making the album skip a file, which is far worse than a run that stops on the
+   * thing that is actually wrong.
+   */
+  const stageCategory = selected ? galleryItemCategory(selected) : null;
+  const dwells =
+    runAdvances(playbackEnd) &&
+    stageCategory !== null &&
+    stageCategory !== 'video' &&
+    stageCategory !== 'audio';
+  useEffect(() => {
+    if (!dwells || !selectedId) return;
+    const timer = setTimeout(advance, imageDwell * 1000);
+    return () => clearTimeout(timer);
+  }, [dwells, selectedId, imageDwell, advance]);
+
+  /**
+   * Picking a file brings the STAGE back into view.
+   *
+   * Owner, 2026-08-14: *"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 or image I
+   * picked instead of having to do it manually."*
+   *
+   * The detail view is one scroll container — stage on top, the rest of the grid underneath —
+   * so choosing from that lower grid changed what was playing while leaving the viewport
+   * hundreds of pixels below it. The video was playing, audible, and off-screen.
+   *
+   * 🔴 Keyed on `selectedId`, not on "a tile was clicked", so ⇧-arrow stepping and end-of-video
+   * auto-advance land the same way. It deliberately does NOT run when the detail view first
+   * OPENS from the browse grid — that swap already puts the stage at the top of a fresh view,
+   * and an animated scroll on top of it reads as a jolt. `hadSelection` is what distinguishes
+   * "changed file" from "opened the first one".
+   *
+   * `smooth` is the point: an instant jump gives no sense of having moved, and the owner's
+   * complaint is about losing his place. Honors `prefers-reduced-motion` via `behavior:'auto'`
+   * for anyone who has asked for less movement.
+   */
+  /*
+   * 🔴 A film SNAPS; everything else glides. Owner, 2026-08-25: *"media galleries like in
+   * collections app should snap to the top to play a video instead of slowly going to the
+   * top."*
+   *
+   * This is not a reversal of the `smooth` reasoning above, which is about not losing your
+   * place while stepping through stills — it is the case that reasoning does not cover.
+   * Playback has ALREADY STARTED by the time the scroll animation runs, so a smooth glide
+   * means several hundred milliseconds of a video you can hear and cannot see. There is no
+   * place to lose: the thing you are travelling to is the thing that is already happening.
+   */
+  const stageRef = useRef<HTMLDivElement | null>(null);
+  const hadSelection = useRef(false);
+  useEffect(() => {
+    if (!selectedId) {
+      hadSelection.current = false;
+      return;
+    }
+    const wasOpen = hadSelection.current;
+    hadSelection.current = true;
+    if (!wasOpen) return;
+    const el = stageRef.current;
+    if (!el?.scrollIntoView) return;
+    const reduced =
+      globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true;
+    el.scrollIntoView({ behavior: reduced || snapsToStage(selected) ? 'auto' : 'smooth', block: 'start' });
+  }, [selectedId, selected]);
+
+  /**
+   * Arrow keys step, Escape closes.
+   *
+   * 🔴 Bound to the WINDOW rather than to the detail container, because the video player is
+   * 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.
+   */
+  useEffect(() => {
+    if (!selectedId) return;
+    const onKey = (event: KeyboardEvent) => {
+      /*
+       * 🔴 Space is play/pause, and it is decided BEFORE the typing guard below — which is
+       * the opposite of how this read until 2026-08-22, and the change is the fix.
+       *
+       * Owner, 2026-08-13: *"clicking space bar on a video page should toggle pause or
+       * play."* Owner again, 2026-08-20, after it kept not working: *"Space key should not do
+       * anything else … no matter where I push it … This applies to other media galleries in
+       * all the other apps too."* The guard below stands down for a focused `<button>` on the
+       * reasonable grounds that Space activates one — but on a player page the controls ARE
+       * buttons, and the browser restores focus to the last-clicked one when the tab comes
+       * back, so Space activated it instead of pausing. `isPlayPauseSpace` is the fleet's one
+       * answer to "is this press ours"; see `media/playerSpaceKey.ts` for the whole story.
+       *
+       * Handled here rather than by focusing the player on open, because stealing focus
+       * breaks the ⇧-arrow stepping and the Escape below.
+       */
+      if (isPlayPauseSpace(event)) {
+        /*
+         * 🔴 The element is found through the STAGE REF, not by class name or tag — changed
+         * 2026-09-11, and the change is the fix.
+         *
+         * Owner: *"in collections when a video is selected make the space bar always play or
+         * pause the video whether it is focused or not. Currently there can be a video selected
+         * and if I click off of it such as clicking the side bar or if I never click it at all
+         * the space bar doesn't control the video."*
+         *
+         * The old lookup was `'.cbmg-stage-video, .cbgd-stage video, media-player video'` —
+         * three guesses at where the element might be, two of which could not match:
+         *
+         *   · `.cbmg-stage-video` is the NATIVE stage only (`nativeVideoStage`), which the
+         *     collections app does not use;
+         *   · `.cbgd-stage` does not exist and has not for some time — the shell's frame is
+         *     `.cbgd-watch-player-box`, so that arm of the list was dead;
+         *   · 🔴 and `media-player video` NEVER MATCHED ANYTHING, which is the whole bug.
+         *     `@vidstack/react`'s `<MediaPlayer>` does not render a `<media-player>` custom
+         *     element — measured against the installed version on 2026-09-11, it renders
+         *     `<div data-media-player>` with the provider as `<div data-media-provider>`
+         *     inside it. So the selector was a tag name nothing in the document has, and
+         *     every arm of the list was dead on the Vidstack path that every app except the
+         *     `nativeVideoStage` consumers uses.
+         *
+         * A tag name that matches nothing is the worst shape this could have had: it
+         * typechecks, it throws nothing, it logs nothing, and `document.querySelector`
+         * answering `null` was indistinguishable from "the player has not mounted yet".
+         * Hence the second half below — the key is taken whether or not anything is found.
+         *
+         * `stageRef` is the `.cbmg-stage-anchor` div this component already keeps for the
+         * scroll-into-view effect, and every stage renders inside it: the native `<video>`,
+         * Vidstack's provider-built `<video>`, and the audio card's `<audio>`. One ref
+         * therefore answers all three, cannot go stale against a renamed class, and cannot
+         * pick up a `<video>` from a PREVIEWING TILE in the grid below — which a
+         * document-wide `video` selector would have done the moment "preview all" was on.
+         */
+        const media =
+          stageRef.current?.querySelector<HTMLMediaElement>('video, audio') ?? null;
+        /*
+         * 🔴 The key is consumed whenever the open file is PLAYABLE, found or not.
+         *
+         * This is the half that answers *"whether it is focused or not"*. Falling through on a
+         * not-yet-mounted player left Space meaning "press the focused button" for the first
+         * second of every video — and the focused button, after clicking a tile or a sidebar
+         * row, is the one the owner just used. Cancelling the keydown is also what stops the
+         * browser activating that button on the KEYUP, and what stops the page scrolling.
+         *
+         * Narrowed to video and audio on purpose: on a PDF or a text stage Space is paging
+         * down, which is the gesture a reader wants and not one to steal.
+         */
+        if (playsWithSpace(selected)) {
+          event.preventDefault();
+          event.stopPropagation();
+          if (media) {
+            if (media.paused) void media.play().catch(() => {});
+            else media.pause();
+          }
+        }
+        return;
+      }
+      // Never steal a key from a field, and never from a chord the browser or the player owns
+      // (⌘←/⌥← are history and word-jump; Vidstack binds bare arrows to seek only while the
+      // player has focus, which is why ⇧ is the modifier that means "the gallery").
+      const target = event.target as HTMLElement | null;
+      if (
+        target?.isContentEditable === true ||
+        ['INPUT', 'TEXTAREA', 'SELECT'].includes(target?.tagName ?? '') ||
+        event.metaKey ||
+        event.ctrlKey ||
+        event.altKey
+      )
+        return;
+      if (event.key === 'Escape') {
+        select(null);
+        return;
+      }
+      // ⇧+arrow, so a bare ← / → still seeks within the video (the player's own binding) and
+      // the two never fight over the same key.
+      if (!event.shiftKey) return;
+      // `step` wraps now and always moves, so the key is always ours to consume — the old
+      // form used its boolean return to let the edges fall through to the browser's scroll.
+      if (event.key === 'ArrowRight' && canStep) {
+        event.preventDefault();
+        step(1);
+      }
+      if (event.key === 'ArrowLeft' && canStep) {
+        event.preventDefault();
+        step(-1);
+      }
+    };
+    // Capture, so a focused transport control never gets the press first. See
+    // `media/playerSpaceKey.ts`.
+    window.addEventListener('keydown', onKey, true);
+    return () => window.removeEventListener('keydown', onKey, true);
+  });
+
+  // A selection in progress arms the grid on its own: hiding the boxes again the moment the
+  // pointer leaves a ticked tile would make "which ones did I pick" a hover-only fact.
+  const boxesArmed = selectionReveal === 'always' || selectArmed || checks.count > 0;
+
+  const tileSelection = (item: MediaGalleryItem): TileSelection | undefined =>
+    selectable
+      ? {
+          selected: checks.isSelected(item.id),
+          armed: boxesArmed,
+          onToggle: (shiftKey: boolean) => checks.toggle(item.id, { shiftKey }),
+        }
+      : undefined;
+
+  const tileDrag = (item: MediaGalleryItem): TileDrag | undefined =>
+    onItemDragStart
+      ? {
+          onDragStart: (event: DragEvent<HTMLElement>) => onItemDragStart(item, event),
+          ...(onItemDragEnd ? { onDragEnd: onItemDragEnd } : {}),
+        }
+      : undefined;
+
+  /*
+   * The capability dialogs. Rendered beside the detail view rather than inside the action row
+   * so that closing the row's own state (a rename, the sliders) cannot unmount an open editor
+   * mid-save, and so a `React.lazy` chunk is fetched only when one is actually opened.
+   */
+  const capabilityDialogs = (
+    <React.Suspense fallback={null}>
+      {editingPicture ? (
+        <LazyPictureEditor
+          src={editingPicture.url ?? ''}
+          fileName={editingPicture.name}
+          allowReplace={allowPictureReplace}
+          onClose={() => setEditingPicture(null)}
+          onSave={async (result: PictureEditResult) => {
+            await onSaveEdit?.(editingPicture, result);
+          }}
+        />
+      ) : null}
+      {turningVideo ? (
+        <LazyVideoTurner
+          src={turningVideo.streamUrl ?? turningVideo.url ?? ''}
+          {...(turningVideo.posterUrl ? { posterUrl: turningVideo.posterUrl } : {})}
+          name={turningVideo.name}
+          orientation={turningVideo.orientation}
+          onClose={() => setTurningVideo(null)}
+          onSave={async (next: MediaOrientation | undefined) => {
+            await onSaveOrientation?.(turningVideo, next);
+          }}
+        />
+      ) : null}
+      {trimmingVideo && onTrimVideo ? (
+        <LazyVideoCutEditor
+          src={trimmingVideo.streamUrl ?? trimmingVideo.url ?? ''}
+          {...(trimmingVideo.posterUrl ? { posterUrl: trimmingVideo.posterUrl } : {})}
+          name={trimmingVideo.name}
+          durationSeconds={trimmingVideo.durationSeconds ?? null}
+          {...(trimNote ? { note: trimNote } : {})}
+          onClose={() => setTrimmingVideo(null)}
+          onSubmit={async (cuts: VideoCut[]) => {
+            await onTrimVideo(trimmingVideo, cuts);
+          }}
+        />
+      ) : null}
+      {grabbing ? (
+        <LazyFrameGrabber
+          src={grabbing.item.streamUrl ?? grabbing.item.url ?? ''}
+          name={grabbing.item.name}
+          startAt={grabbing.at}
+          // So the dialog can SAY that saving replaces the picture this film shows now, rather
+          // than overwriting somebody's chosen poster silently — the owner's copy-not-overwrite
+          // ruling applied to the one case in that dialog where a replacement is unavoidable.
+          hasPoster={Boolean(grabbing.item.posterUrl)}
+          onClose={() => setGrabbing(null)}
+          {...(onSaveThumbnail
+            ? { onSaveThumbnail: (poster: Blob) => onSaveThumbnail(grabbing.item, poster) }
+            : {})}
+          {...(onSaveSnapshot
+            ? {
+                onSaveSnapshot: (still: Blob, atSeconds: number) =>
+                  onSaveSnapshot(grabbing.item, still, atSeconds),
+              }
+            : {})}
+        />
+      ) : null}
+    </React.Suspense>
+  );
+
+  if (selected) {
+    const category = galleryItemCategory(selected);
+    const others = displayItems.filter((i) => i.id !== selected.id);
+    const downloadHref = selected.downloadUrl ?? selected.url;
+    return (
+      <>
+      {capabilityDialogs}
+      <DenseGalleryDetail
+        fullStage={fullStage}
+        onFullStageChange={setFullStage}
+        /* 🔴 A VIDEO enters browser fullscreen from its own player, so the frame must not also
+           claim the gesture; every other kind of file has no player, so the frame's
+           `⤢ Fullscreen` is what a double-click means on it. Owner, 2026-09-11:
+           *"Doubleclicking an image to toggle full screen is not working at all."* */
+        stageOwnsDoubleClick={category === 'video'}
+        title={selected.name}
+        meta={
+          // 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
+        }
+        sticky={pinStage}
+        stage={
+          // The div is the scroll anchor the effect above targets — the stage content itself is
+          // a lazy viewer that may not have mounted yet when the selection changes.
+          <div
+            ref={stageRef}
+            className='cbmg-stage-anchor'
+            /*
+             * 🔴 The picture adjustment reaches the stage through a CSS custom property, not
+             * through a prop on the player. The video stage is Vidstack's and is several
+             * components deep; threading a filter into it would mean every consumer of the
+             * player primitive learning about a control only the gallery offers. The rule that
+             * consumes this lives in `mediaGallery.css` beside the stage it targets.
+             */
+            style={{ '--cbmg-picture-filter': lightFilter(light) } as React.CSSProperties}
+          >
+            <GalleryStage
+              item={selected}
+              mediaCache={mediaCache}
+              bytesCache={bytesCache}
+              loadBytes={loadBytes}
+              nativeVideoStage={nativeVideoStage}
+              onStep={step}
+              canStep={canStep}
+              /* 🔴 The player's own double-click gesture stands down while the SHELL is
+                 fullscreen, so the one gesture the owner asked for ("double clicking a full
+                 screen video should change back … to non-full screen view") has exactly one
+                 meaning. `DenseGalleryDetail` handles it from the frame instead. */
+              fullscreenOnDoubleClick={!fullStage}
+              repeat={runRepeatsOne(playbackEnd)}
+              // 🔴 `advance`, not `step(1)`. The arrows wrap and the RUN does not: `next`
+              // stops after the last item, `all` starts over, `shuffle` draws from the pass.
+              // Handing the wrapping stepper to `onEnded` would turn every setting into
+              // "play all", silently.
+              onEnded={runAdvances(playbackEnd) ? advance : undefined}
+            />
+          </div>
+        }
+        /* 🔴 Stepping is now in TWO places and neither is an overlay on the picture
+           (owner, 2026-08-25: "remove the big previous and next buttons off the sides of
+           the video"). A video gets its pair inside the player's own control bar, beside
+           the cog, because that bar is the only chrome that exists in browser fullscreen —
+           see `VideoPlayer`'s `stepSlots`, and note the same `step` is handed to
+           `GalleryStage` above. Every other kind of file gets its pair at the START of the
+           titlebar's action row, which is what keeps the 2026-08-23 "the buttons shift"
+           property: the row grows to the RIGHT, so a consumer wiring three actions or nine
+           does not move them. The ⇧←/⇧→ shortcuts and the aria-labels are unchanged. */
+        onStep={step}
+        canStep={canStep}
+        actions={
+          <>
+            {/* Pin the stage so the thumbnails scroll UNDER the video rather than past it.
+                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. */}
+            <Tooltip content={
+                pinStage
+                  ? 'Unpin — let the stage scroll away with the page'
+                  : 'Pin the stage to the top while the thumbnails scroll under it'
+              }>
+              <button
+                // guardrails-ignore no-raw-action-button: see the previous button.
+                type='button'
+                className='cbgd-order-btn'
+                aria-pressed={pinStage}
+                onClick={() => {
+                  const next = !pinStage;
+                  setPinStage(next);
+                  writePinStage(next);
+                }}
+              >
+                {pinStage ? '📌 Pinned' : '📌 Pin'}
+              </button>
+            </Tooltip>
+            {/* 🔴 Shown for EVERY kind, not only video. Three of the five settings run the
+                whole album, and an album of photographs is exactly what a slideshow is —
+                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}>
+              <button
+                // guardrails-ignore no-raw-action-button: see the previous button.
+                type='button'
+                className={`cbgd-order-btn${playbackEnd === 'stop' ? '' : ' is-active'}`}
+                onClick={() => {
+                  const next = nextPlaybackEnd(playbackEnd);
+                  setPlaybackEnd(next);
+                  writePlaybackEnd(next);
+                }}
+                aria-label={`When an item ends: ${PLAYBACK_END_LABELS[playbackEnd].label}`}
+              >
+                {PLAYBACK_END_LABELS[playbackEnd].glyph} {PLAYBACK_END_LABELS[playbackEnd].label}
+              </button>
+            </Tooltip>
+            {/* The slideshow speed, and ONLY while a setting that advances is chosen — a
+                dwell control beside "Stop at the end" configures something that cannot
+                happen. Owner: "The time should be configurable for slow to fast slideshows." */}
+            {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>
+                  <select
+                    // guardrails-ignore no-raw-inputs: `.cbgd-dwell` is this module's own
+                    // self-contained plain-CSS control, for the same reason `.cbgd-search`
+                    // states — cursedbelt's Tailwind field layer would fight it on cascade.
+                    className='cbgd-dwell-select'
+                    value={imageDwell}
+                    onChange={(event) => {
+                      const next = Number(event.target.value);
+                      setImageDwell(next);
+                      writeImageDwell(next);
+                    }}
+                    aria-label='How long each picture holds the screen'
+                  >
+                    {IMAGE_DWELL_OPTIONS.map((seconds) => (
+                      <option key={seconds} value={seconds}>
+                        {seconds}s
+                      </option>
+                    ))}
+                  </select>
+                </label>
+              </Tooltip>
+            ) : null}
+            {/*
+              ── The standard capabilities ────────────────────────────────────────────────
+              Each renders only when the app passed the handler that makes it work. Placed
+              BEFORE `detailActions` so the shared row reads the same in every app and an app's
+              own buttons collect at the end, next to Download and Delete.
+            */}
+            {onRename ? (
+              renaming === selected.id ? (
+                <form
+                  className='cbmg-inline-rename'
+                  onSubmit={(event) => {
+                    event.preventDefault();
+                    const next = renameDraft.trim();
+                    setRenaming(null);
+                    // An empty or unchanged name is a cancel, not a rename to "". Deciding that
+                    // here rather than in each app is what stops one of them storing a blank.
+                    if (next && next !== selected.name) void onRename(selected, next);
+                  }}
+                >
+                      gallery's plain-CSS action row, which has no Tailwind and no Field layer;
+                  <input
+                    // guardrails-ignore no-raw-inputs: a plain control inside a Tailwind-free, plain-CSS row. The Field layer has no slider, and its label chrome would duplicate the label already beside this one.
+                    // The field is opened by an explicit press of Rename, so focus is the
+                    // thing that was just asked for — and without it the control appears and
+                    // does nothing until you find it again with the pointer.
+                    // biome-ignore lint/a11y/noAutofocus: explained immediately above
+                    autoFocus
+                    aria-label={`Rename ${selected.name}`}
+                    value={renameDraft}
+                    onChange={(event) => setRenameDraft(event.target.value)}
+                    onKeyDown={(event) => {
+                      if (event.key === 'Escape') setRenaming(null);
+                    }}
+                  />
+                  <button
+                    // guardrails-ignore no-raw-action-button: action pill styled by the dense
+                    // gallery's own plain CSS, matching its neighbours in this row.
+                    type='submit'
+                    className='cbgd-order-btn'
+                  >
+                    Save
+                  </button>
+                  <button
+                    // guardrails-ignore no-raw-action-button: see the Save button above.
+                    type='button'
+                    className='cbgd-order-btn'
+                    onClick={() => setRenaming(null)}
+                  >
+                    Cancel
+                  </button>
+                </form>
+              ) : (
+                <Tooltip content="Change this file's name">
+                  <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={() => {
+                      setRenameDraft(selected.name);
+                      setRenaming(selected.id);
+                    }}
+                  >
+                    Rename
+                  </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' ? (
+              <Tooltip content={
+                  onSaveThumbnail
+                    ? 'Pick which moment the thumbnail comes from, and keep stills'
+                    : 'Keep a full-size picture of a moment in this film'
+                }>
+                <button
+                  // guardrails-ignore no-raw-action-button: see above.
+                  type='button'
+                  className='cbgd-order-btn'
+                  onClick={() => {
+                    /*
+                     * 🔴 Carry the PLAYHEAD across, read off the DOM rather than plumbed through.
+                     * The stage player is Vidstack's and owns its own time; this is one number at
+                     * one moment, and threading a prop for it would couple the player primitive
+                     * to a control only the gallery offers. Owner, 2026-08-13, about the same
+                     * gesture in collections: *"should open to the same spot in the timeline I
+                     * click it at because that's usually about where I want the snapshot."*
+                     */
+                    const stage = stageRef.current?.querySelector<HTMLVideoElement>(
+                      '.cbmg-stage-video, video',
+                    );
+                    const at = stage && Number.isFinite(stage.currentTime) ? stage.currentTime : 0;
+                    setGrabbing({ item: selected, at });
+                  }}
+                >
+                  {onSaveThumbnail
+                    ? selected.posterUrl
+                      ? '🖼 Change thumbnail'
+                      : '🖼 Choose thumbnail'
+                    : '📷 Take a picture'}
+                </button>
+              </Tooltip>
+            ) : null}
+            {onSaveEdit && category === 'image' ? (
+              <Tooltip content='Turn, mirror, crop or re-light this picture'>
+                <button
+                  // guardrails-ignore no-raw-action-button: see above.
+                  type='button'
+                  className='cbgd-order-btn'
+                  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
+                </button>
+              </Tooltip>
+            ) : null}
+            {/* The film's own version of the button above. Offered on video ONLY — an image
+                already has the fuller editor, and two controls that both say "turn" on the same
+                item is the confusion this split was made to avoid. */}
+            {onSaveOrientation && category === 'video' ? (
+              <Tooltip content='Fix a clip filmed sideways — stored, never re-encoded'>
+                <button
+                  // guardrails-ignore no-raw-action-button: see above.
+                  type='button'
+                  className='cbgd-order-btn'
+                  onClick={() => setTurningVideo(selected)}
+                >
+                  ⟳ Turn video
+                </button>
+              </Tooltip>
+            ) : null}
+            {onTrimVideo && category === 'video' ? (
+              <Tooltip content='Mark sections to cut out — a trimmed copy is made beside the original'>
+                <button
+                  // guardrails-ignore no-raw-action-button: see above.
+                  type='button'
+                  className='cbgd-order-btn'
+                  onClick={() => setTrimmingVideo(selected)}
+                >
+                  ✂ Trim
+                </button>
+              </Tooltip>
+            ) : null}
+            {pictureControls && (category === 'image' || category === 'video') ? (
+              <Tooltip content='Brightness, contrast and colour for what you are looking at'>
+                <button
+                  // guardrails-ignore no-raw-action-button: see above.
+                  type='button'
+                  className={`cbgd-order-btn${showPicture || isLightAdjusted(light) ? ' is-active' : ''}`}
+                  aria-pressed={showPicture}
+                  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) ? ' ·' : ''}
+                </button>
+              </Tooltip>
+            ) : null}
+            {/* The sliders ride the SAME wrapping row as the buttons rather than getting a slot
+                of their own on `DenseGalleryDetail`. A second slot would be a layout every
+                consumer inherits for a control most of them never open; the row already wraps. */}
+            {showPicture ? (
+              <span className='cbmg-picture-sliders'>
+                {(
+                  [
+                    ['brightness', 'Brightness'],
+                    ['contrast', 'Contrast'],
+                    ['saturation', 'Colour'],
+                  ] as const
+                ).map(([key, label]) => (
+                  <label key={key}>
+                    <span>{label}</span>
+                    <input
+                      // guardrails-ignore no-raw-inputs: a plain control inside a Tailwind-free, plain-CSS row. The Field layer has no slider, and its label chrome would duplicate the label already beside this one.
+                      type='range'
+                      min={LIGHT_RANGE.min}
+                      max={LIGHT_RANGE.max}
+                      step={LIGHT_RANGE.step}
+                      value={light[key]}
+                      onChange={(event) =>
+                        setLight((l) => ({ ...l, [key]: Number(event.target.value) }))
+                      }
+                    />
+                  </label>
+                ))}
+                <button
+                  // guardrails-ignore no-raw-action-button: see above.
+                  type='button'
+                  className='cbgd-order-btn'
+                  disabled={!isLightAdjusted(light)}
+                  onClick={() => setLight(NO_LIGHT)}
+                >
+                  Reset
+                </button>
+              </span>
+            ) : null}
+            {detailActions?.(selected)}
+            {downloadHref ? (
+              <Tooltip content={`Download ${selected.name}`}>
+                <a
+                  className='cbgd-order-btn'
+                  href={downloadHref}
+                  download={selected.name}
+                >
+                  ⬇ Download
+                </a>
+              </Tooltip>
+            ) : null}
+            {onDelete ? (
+              <DeleteButton
+                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>
+          </>
+        }
+        relatedLabel='More files'
+        itemCount={others.length}
+        loading={loading}
+        onNearEnd={onNearEnd}
+        minColumnWidth={minColumnWidth}
+        /*
+         * 🔴 The rows/tiles toggle reaches THIS screen too (2026-09-10).
+         *
+         * 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.
+         */
+        {...(viewMode === 'table'
+          ? {
+              relatedBody: (
+                <GalleryTable
+                  items={others}
+                  cache={mediaCache}
+                  order={order}
+                  onOrderChange={setOrder}
+                  onOpen={select}
+                  {...(onNearEnd ? { onNearEnd } : {})}
+                  {...(loading === undefined ? {} : { loading })}
+                  /* 🔴 The same `thumbAutoplay` the tiles take. Owner, 2026-09-11: *"in table
+                     view the play all thumbnails isn't working but if I go back to grid view it
+                     works."* This is the RELATED list under an open file, and it is the same
+                     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}
+                />
+              ),
+            }
+          : {})}
+        renderTile={(index) => {
+          const item = others[index];
+          return item ? (
+            <GalleryTile
+              key={item.id}
+              item={item}
+              cache={mediaCache}
+              onOpen={() => select(item)}
+              // 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}
+            />
+          ) : null;
+        }}
+      />
+      </>
+    );
+  }
+
+  return (
+    <DenseGalleryShell<MediaGalleryOrder>
+      title={title}
+      order={{
+        value: order,
+        options: GALLERY_ORDER_OPTIONS,
+        onChange: setOrder,
+        ariaLabel: 'Sort files',
+      }}
+      query={query}
+      onQueryChange={setQuery}
+      searchPlaceholder={searchPlaceholder}
+      chrome={chrome}
+      headerExtra={
+        <>
+          {/*
+           * Grid ⇄ table. Two pills rather than one that toggles, because a single button
+           * labelled with the view you are NOT in is the control everyone misreads — and a
+           * pressed pair says which one is live without the reader having to work it out.
+           */}
+          {/* A `<fieldset>`, matching `OrderPills` next to it — a group of related controls
+              with a name, which is what `role="group"` on a span was only pretending to be. */}
+          <fieldset className='cbgd-order' aria-label='How files are shown'>
+            {(
+              [
+                { mode: 'grid', glyph: '▦', label: 'Grid', hint: 'Show files as thumbnails' },
+                {
+                  mode: 'table',
+                  glyph: '☰',
+                  label: 'Table',
+                  hint: 'Show files as rows with size, length and date',
+                },
+              ] as const
+            ).map((option) => (
+              <Tooltip content={option.hint} key={option.mode}>
+                <button
+                  // 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' : ''}`}
+                  aria-pressed={viewMode === option.mode}
+                  onClick={() => setViewMode(option.mode)}
+                >
+                  <span aria-hidden='true'>{option.glyph}</span> {option.label}
+                </button>
+              </Tooltip>
+            ))}
+          </fieldset>
+          {/* 🔴 Off by default and remembered — `readThumbAutoplay` says why the default is a
+              requirement rather than a taste. Rendered only when there is a video to preview:
+              a toggle that provably does nothing to the grid in front of you is worse than an
+              absent one.
+
+              🔴 And rendered in BOTH views since 2026-09-11. It used to carry
+              `viewMode === 'grid' &&`, on the note *"the TABLE has no tiles to preview, so it is
+              not offered there"* — which was true of the table and is not any more: a video row
+              previews its thumbnail exactly as a tile does (`GalleryTable`'s `autoPreview`).
+              That gate was also only half the owner's report — *"in table view the play all
+              thumbnails isn't working but if I go back to grid view it works"* — because the app
+              he hit it in renders `chrome='none'` and drives the toggle from its activity bar, so
+              there the control was present and inert rather than absent. Both halves are fixed
+              together, or the two surfaces disagree about whether the feature exists. */}
+          {hasPreviewable ? (
+            <Tooltip
+              content={
+                thumbAutoplay
+                  ? 'Stop previewing every clip — hover one to preview it'
+                  : 'Preview every clip at once, without hovering'
+              }
+            >
+              <button
+                // 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' : ''}`}
+                aria-pressed={thumbAutoplay}
+                onClick={() => setThumbAutoplay(!thumbAutoplay)}
+              >
+                ▶ Preview all
+              </button>
+            </Tooltip>
+          ) : null}
+          {headerExtra}
+        </>
+      }
+      filterStrip={
+        <KindChips
+          options={kindOptions}
+          value={kind}
+          onChange={setKind}
+          tags={tags}
+          activeTag={tag}
+          onTagChange={setTag}
+        />
+      }
+      bulkBar={
+        selectable ? (
+          <BulkBar
+            count={checks.count}
+            total={displayItems.length}
+            headerState={checks.headerState}
+            onToggleAll={checks.toggleAll}
+            onClear={() => {
+              checks.clear();
+              setSelectArmed(false);
+            }}
+            {...(selectionReveal === 'on-demand'
+              ? { armed: selectArmed, onToggleArmed: () => setSelectArmed((on) => !on) }
+              : {})}
+            onDelete={
+              onBulkDelete
+                ? async () => {
+                    await onBulkDelete(checkedItems);
+                    checks.clear();
+                  }
+                : undefined
+            }
+            extra={bulkActions?.(checkedItems, checks.clear)}
+          />
+        ) : null
+      }
+      itemCount={displayItems.length}
+      loading={loading}
+      onNearEnd={onNearEnd}
+      empty={empty ?? <div className='cbgd-empty'>No files yet.</div>}
+      emptyAction={emptyAction}
+      minColumnWidth={minColumnWidth}
+      body={
+        viewMode === 'table' ? (
+          <GalleryTable
+            items={displayItems}
+            cache={mediaCache}
+            order={order}
+            // 🔴 The table drives the gallery's OWN sort. Two views with two sorts is a
+            // question nobody should have to answer; see GalleryTable's header.
+            onOrderChange={setOrder}
+            onOpen={select}
+            {...(onNearEnd ? { onNearEnd } : {})}
+            {...(loading === undefined ? {} : { loading })}
+            {...(empty === undefined ? {} : { empty })}
+            /* 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}
+            {...(selectable
+              ? {
+                  selection: (item: MediaGalleryItem) => ({
+                    selected: checks.isSelected(item.id),
+                    onToggle: (shiftKey: boolean) => checks.toggle(item.id, { shiftKey }),
+                  }),
+                }
+              : {})}
+            {...(onItemDragStart ? { drag: tileDrag } : {})}
+          />
+        ) : null
+      }
+      renderTile={(index) => {
+        const item = displayItems[index];
+        return item ? (
+          <GalleryTile
+            key={item.id}
+            item={item}
+            cache={mediaCache}
+            onOpen={() => select(item)}
+            selection={tileSelection(item)}
+            drag={tileDrag(item)}
+            autoPreview={thumbAutoplay}
+          />
+        ) : null;
+      }}
+    />
+  );
+}
+
+const isItem = (i: MediaGalleryItem | undefined): i is MediaGalleryItem => i !== undefined;
+
+/**
+ * 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
+ * once something is actually selected.
+ */
+function BulkBar({
+  count,
+  total,
+  headerState,
+  armed,
+  onToggleArmed,
+  onToggleAll,
+  onClear,
+  onDelete,
+  extra,
+}: {
+  count: number;
+  total: number;
+  headerState: CheckboxHeaderState;
+  /** Present only under `selectionReveal='on-demand'`; absent means the boxes always show. */
+  armed?: boolean;
+  onToggleArmed?: () => void;
+  onToggleAll: () => void;
+  onClear: () => void;
+  onDelete?: () => Promise<void>;
+  /** App-specific actions, rendered before Delete. See `bulkActions` on the gallery. */
+  extra?: ReactNode;
+}) {
+  return (
+    <div className='cbmg-bulkbar'>
+      {onToggleArmed ? (
+        <Tooltip content={armed ? 'Hide the tick boxes again' : 'Show a tick box on every tile'}>
+          <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${armed ? ' is-active' : ''}`}
+            aria-pressed={armed === true}
+            onClick={onToggleArmed}
+          >
+            {armed ? 'Done selecting' : 'Select'}
+          </button>
+        </Tooltip>
+      ) : null}
+      <label className='cbmg-bulkbar-all'>
+        <input
+          // guardrails-ignore no-raw-inputs: a plain control inside a Tailwind-free, plain-CSS row. The Field layer has no slider, and its label chrome would duplicate the label already beside this one.
+          // guardrails-ignore no-raw-inputs: plain-CSS module — see TileSelect.
+          type='checkbox'
+          checked={headerState === true}
+          ref={(el) => {
+            if (el) el.indeterminate = headerState === 'indeterminate';
+          }}
+          readOnly
+          onClick={onToggleAll}
+          disabled={total === 0}
+        />
+        <span>{count > 0 ? `${count} selected` : 'Select all'}</span>
+      </label>
+      {count > 0 ? (
+        <>
+          <span className='cbmg-bulkbar-spacer' />
+          {/* 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. */}
+          {extra}
+          {onDelete ? (
+            <DeleteButton
+              size='sm'
+              // The gallery holds ANY binary kind, so the copy says "item", not "file".
+              // An explicit accessible name, because the visible label is a glyph + a
+              // count — "✕ Delete 2" tells a screen reader nothing about what it deletes.
+              aria-label={`Delete the ${count} selected item${count === 1 ? '' : 's'}`}
+              tooltip={`Delete the ${count} selected item${count === 1 ? '' : 's'}`}
+              confirmOptions={{
+                title: `Delete ${count} item${count === 1 ? '' : 's'}?`,
+                message: 'This cannot be undone.',
+              }}
+              onDelete={onDelete}
+            >
+              ✕ Delete {count}
+            </DeleteButton>
+          ) : 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>
+        </>
+      ) : null}
+    </div>
+  );
+}