cursedbelt 3.0.2 → 4.0.0

package/src/react/media/DenseGalleryShell.tsx

@@ -1,4 +1,5 @@
 import './denseGallery.css';
+import { ChevronLeft, ChevronRight, Maximize2, Minimize2 } from 'lucide-react';
 import {
   type ButtonHTMLAttributes,
   type CSSProperties,
@@ -43,11 +44,28 @@ export interface GalleryActionButtonProps
   active?: boolean;
   /** Hover/focus explanation. A pill with a non-obvious effect should always carry one. */
   tooltip?: ReactNode;
+  /**
+   * Draw `children` as a bare glyph in a square pill instead of a labelled one — the shape
+   * the whole gallery toolbar uses since 2026-09-16 (owner: *"Make it have icons only,
+   * instead of words in the strip of tools"*).
+   *
+   * 🔴 An `aria-label` becomes REQUIRED, and this prop cannot supply one for you: a pill
+   * whose only content is an `<svg>` has no accessible name at all, and a toolbar of
+   * unnamed glyphs is unusable with a screen reader. The same bargain
+   * {@link DeleteButton}'s `iconOnly` already makes — named so a consumer meets one word
+   * for one idea across the design system.
+   *
+   * The 44px tap floor comes with it, in `denseGallery.css`'s `.is-icon` — a consumer
+   * cannot get that wrong from out here, which is the reason this is a prop rather than a
+   * class name in a doc.
+   */
+  iconOnly?: boolean;
 }
 
 export function GalleryActionButton({
   active,
   tooltip,
+  iconOnly,
   children,
   type,
   ...props
@@ -57,7 +75,7 @@ export function GalleryActionButton({
       // guardrails-ignore no-raw-action-button: THE shared dense-gallery action pill —
       // this is the component consumers use instead of hand-rolling one.
       type={type === 'submit' || type === 'reset' ? type : 'button'}
-      className={`cbgd-order-btn${active ? ' is-active' : ''}`}
+      className={`cbgd-order-btn${active ? ' is-active' : ''}${iconOnly ? ' is-icon' : ''}`}
       {...(active === undefined ? {} : { 'aria-pressed': active })}
       {...props}
     >
@@ -363,7 +381,7 @@ export interface DenseGalleryDetailProps {
   /** See {@link DenseGalleryShellProps.rowExtraHeight} — leave unset. */
   rowExtraHeight?: number;
   /**
-   * Full-stage mode as a CONTROLLED value — the shell's own `⤢ Fullscreen`, which hides the
+   * Full-stage mode as a CONTROLLED value — the shell's own `Fullscreen`, which hides the
    * rail and the related grid so the picture takes the whole container.
    *
    * Omit both and the toggle keeps its own state, which is what every consumer had before
@@ -385,7 +403,7 @@ export interface DenseGalleryDetailProps {
    * `false` (the default) for everything else, and since 2026-09-11 that is a FEATURE rather
    * than an absence. Owner: *"Doubleclicking an image to toggle full screen is not working at
    * all and may be a new feature to add now."* A still picture has no player and therefore no
-   * gesture of its own, so the shell's `⤢ Fullscreen` is what a double-click means on one —
+   * gesture of its own, so the shell's `Fullscreen` is what a double-click means on one —
    * in BOTH directions, which is the half that was missing (it used only to LEAVE).
    *
    * 🔴 Either way the shell still handles the leave while `fullStage` is on, because the video
@@ -451,6 +469,20 @@ export function DenseGalleryDetail({
    * pass. A consumer that knows better still wins — it sets `--cbgd-stage-h`, which
    * this never writes.
    */
+  /**
+   * How tall the resize rail is, right now.
+   *
+   * 🔴 Lifted into state on 2026-09-16 because TWO things need it and they must not disagree:
+   * the automatic fit below, and the DRAG's own ceiling (`containerPx`, further down). The
+   * rail is the strip of chrome the grips moved into when they came off the picture — 64px on
+   * a mouse, 84px under a coarse pointer — and a `MAX_STAGE_SHARE` computed against a
+   * container that pretends the rail is not there hands the stage 86% of a box it does not
+   * have, which puts the related grid back below the fold at the top of the drag. That is the
+   * 2026-08-23 *"the bottom gets cut off … instead of showing more of the thumbnails under
+   * it"* report, arriving from the control added to serve it, for the second time.
+   */
+  const [railPx, setRailPx] = useState(0);
+
   useEffect(() => {
     if (!watchEl || typeof ResizeObserver === 'undefined') return;
     const host = watchEl.parentElement ?? watchEl;
@@ -458,21 +490,46 @@ export function DenseGalleryDetail({
     const apply = () => {
       const available = host.clientHeight;
       if (!available) return; // unmeasurable — the stylesheet's default stands
-      // 🔴 Minus the resize bar, which is chrome the stage OWNS but is not part of the
-      // frame it sizes. Once the player became a column (see `.cbgd-watch-player`) the bar
-      // took real height out of the same box, so a fit computed from the raw container
-      // overshot by exactly that much and pushed the last row of thumbnails through the
-      // bottom of the gallery — the 2026-08-23 report, arriving from a control added to
-      // serve it. Measured from the element rather than written as a constant, because a
-      // constant here is a second copy of a number that lives in `mediaResize.css`.
-      const grip = watchEl.querySelector('.cbmr-bar');
+      const grip = watchEl.querySelector('.cbmr-rail');
       const gripPx = grip ? Math.round(grip.getBoundingClientRect().height) : 0;
+      // Compared before setting, like every other measurement in this file: an observer that
+      // wrote state on each sub-pixel reflow would re-render the whole detail view forever.
+      setRailPx((current) => (current === gripPx ? current : gripPx));
+      /*
+       * 🔴 Minus EVERY pixel of the top region that is not the frame — the resize rail, the
+       * titlebar and the padding around both.
+       *
+       * `STAGE_SHARE` is a share of what is LEFT for the grid to live in, so a fit computed
+       * from the raw container hands the stage 58% of a box that also has to hold the chrome,
+       * and the grid gets 42% minus all of it. That is the 2026-08-23 *"the bottom gets cut
+       * off for empty space instead of showing more of the thumbnails under it"* report, and
+       * it arrives from whatever control is added under the picture next.
+       *
+       * It used to subtract only `.cbmr-bar`, which was a 22px strip and left the sum just
+       * inside the margin. The grips moved into a 64px rail on 2026-09-16 and it stopped
+       * being inside it — `e2e/stage-layout.spec.ts` caught the first row of tiles hanging
+       * 10px through the bottom of the gallery — so the measurement is the general one now
+       * rather than one more named control.
+       *
+       * 🔴 A DIFFERENCE, and that is what makes it loop-proof: the chrome's height does not
+       * depend on the frame's, so shrinking the frame shrinks the region and leaves this
+       * number alone. The same shape `FocusViewer` uses for its own ceiling. Falls back to
+       * the rail alone if either box is missing, which is never worse than what it replaced.
+       */
+      const top = watchEl.querySelector('.cbgd-watch-top');
+      const frame = watchEl.querySelector('.cbgd-watch-player-box');
+      const chromePx =
+        top && frame
+          ? Math.round(
+              top.getBoundingClientRect().height - frame.getBoundingClientRect().height,
+            )
+          : gripPx;
       // A ternary rather than `Math.max`, deliberately: `denseGallery.layout.spec.ts` asserts
       // the fit expression contains no `max(` — the CSS `min()` there may never become a
       // `max()`, because a rule that can GROW the stage tracks the content it is measuring
       // and chases itself. That guard reads the source text, so the JS clamp is written in a
       // form that cannot be mistaken for the thing it forbids.
-      const usable = available > gripPx ? available - gripPx : 0;
+      const usable = available > chromePx ? available - chromePx : 0;
       const fit = `min(${Math.round(usable * STAGE_SHARE)}px, var(--cbgd-stage-default))`;
       if (fit === last) return;
       last = fit;
@@ -559,7 +616,11 @@ export function DenseGalleryDetail({
     handle: resizeHandle,
   } = useMediaResize({
     storageKey: STAGE_HEIGHT_KEY,
-    containerPx: watchEl?.clientHeight ?? 0,
+    // 🔴 Minus the rail — the SAME subtraction the automatic fit makes a few lines up, and for
+    // the same reason. `MAX_STAGE_SHARE` promises a band of tiles is still on screen at the
+    // largest size the handle can reach; that promise is about the space the FRAME may take,
+    // and the rail is chrome below the frame rather than part of it.
+    containerPx: Math.max(0, (watchEl?.clientHeight ?? 0) - railPx),
     frameEl,
   });
 
@@ -582,7 +643,7 @@ export function DenseGalleryDetail({
         <div className='cbgd-watch-main'>
           <div className='cbgd-watch-player'>
             {/* biome-ignore lint/a11y/noStaticElementInteractions: the frame is a picture,
-                not a control — the double-click is a SHORTCUT for the `⤢ Fullscreen` toggle
+                not a control — the double-click is a SHORTCUT for the `Fullscreen` toggle
                 in the titlebar, which is the keyboard-reachable route and stays the only
                 one a screen reader is told about. See `onStageDoubleClick`. */}
             <div
@@ -595,27 +656,26 @@ export function DenseGalleryDetail({
               onDoubleClick={onStageDoubleClick}
             >
               {stage}
-              {/*
-               * The corner grip — the owner's literal words, *"dragging the corner"*.
-               *
-               * 🔴 Inside the clipped frame, on the picture. The note that used to stand
-               * here said a handle in this box "would be painted over by a full-bleed
-               * video and unreachable"; the big ⟨ ⟩ step arrows that USED to hang in this
-               * same box were the counter-example — absolutely positioned over arbitrary
-               * media, clickable every day they existed. (They are gone: the owner asked
-               * for them off the sides of the video on 2026-08-25, and stepping now lives
-               * in the titlebar and the player's control bar. Do not read this as a reason
-               * to bring them back.) What the old reasoning bought instead was a bar nobody
-               * found, reported on 2026-08-25 as the feature not existing.
-               */}
-              {fullStage ? null : <MediaResizeCorner {...resizeHandle} label='Viewer height' />}
             </div>
             {/*
-             * And the bottom edge, kept beside the corner: a corner is a small target on a
-             * phone, and on a portrait clip the picture's corner is empty letterboxing
-             * while the bottom edge is always exactly where the picture ends.
+             * 🔴 The resize rail — a SIBLING of the frame, never a child of it.
+             *
+             * Owner, `ideas/collections-09-14.md`: *"Fix the drag to resize area to no longer
+             * overlap part of the horizontal play timeline area … It should only be draggable
+             * when my mouse pointer is at the bottom right corner of the video player, just
+             * like mac windows for other apps work."* The corner grip was a 64px overlay in
+             * the box above until 2026-09-16, and no gutter in the player's control bar can
+             * clear it — `mediaResize.css`'s header has the measurement. Out here, nothing of
+             * either grip is inside the frame at any size.
+             *
+             * The bar beside it is shown on coarse pointers only; see `MediaResize.tsx`.
              */}
-            {fullStage ? null : <MediaResizeBar {...resizeHandle} label='Viewer height' />}
+            {fullStage ? null : (
+              <div className='cbmr-rail'>
+                <MediaResizeBar {...resizeHandle} label='Viewer height' />
+                <MediaResizeCorner {...resizeHandle} label='Viewer height' />
+              </div>
+            )}
           </div>
           <div className='cbgd-watch-titlebar'>
             <span className='cbgd-watch-title'>{title}</span>
@@ -640,21 +700,28 @@ export function DenseGalleryDetail({
                */}
               {onStep ? (
                 <span className='cbgd-watch-step'>
+                  {/* Lucide chevrons rather than the `‹ ›` characters these were until
+                      2026-09-16: the rest of this row is a lucide set now, and a typographic
+                      glyph beside real icons is the seam that reads as unfinished — its
+                      weight, its baseline and its optical size come from whichever font the
+                      host happens to have. */}
                   <GalleryActionButton
+                    iconOnly
                     tooltip='Previous file (⇧←)'
                     aria-label='Previous file'
                     disabled={!canStep}
                     onClick={() => onStep(-1)}
                   >
-                    <span aria-hidden='true'>‹</span>
+                    <ChevronLeft aria-hidden />
                   </GalleryActionButton>
                   <GalleryActionButton
+                    iconOnly
                     tooltip='Next file (⇧→)'
                     aria-label='Next file'
                     disabled={!canStep}
                     onClick={() => onStep(1)}
                   >
-                    <span aria-hidden='true'>›</span>
+                    <ChevronRight aria-hidden />
                   </GalleryActionButton>
                 </span>
               ) : null}
@@ -669,11 +736,16 @@ export function DenseGalleryDetail({
                   // pill styling as the sort pills above — a UI-preference toggle (not
                   // persisted, not destructive) styled by this module's own plain CSS.
                   type='button'
-                  className='cbgd-order-btn'
+                  className='cbgd-order-btn is-icon'
                   aria-pressed={fullStage}
+                  // 🔴 The word moved into the accessible name rather than being deleted with
+                  // the glyph. It is also the STATE — `Shrink` is only offered while the stage
+                  // is already filling the frame — so a reader who cannot see which of the two
+                  // arrows is drawn still learns which way this press goes.
+                  aria-label={fullStage ? 'Shrink' : 'Fullscreen'}
                   onClick={() => setFullStage(!fullStage)}
                 >
-                  {fullStage ? '⤡ Shrink' : '⤢ Fullscreen'}
+                  {fullStage ? <Minimize2 aria-hidden /> : <Maximize2 aria-hidden />}
                 </button>
               </Tooltip>
             </span>

package/src/react/media/FocusViewer.tsx

@@ -680,16 +680,23 @@ export function FocusViewer({
 					/>
 					{marquee ? <span className="inspector__marquee" style={marqueeStyle(marquee)} /> : null}
 				</div>
-				{/*
-				 * 🔴 A child of the VIEWPORT, not of `.inspector__frame`. The frame's every
-				 * fraction is a coordinate — the marquee, the pan and the snapshot crop are all
-				 * fractions of that box — so an extra child there is a pointer target sitting
-				 * inside the drawing surface, and its `onPointerDown` would race the marquee's.
-				 * The viewport is the same rectangle visually and owns no geometry.
-				 */}
+			</div>
+			{/*
+			 * 🔴 The resize rail — OUTSIDE the viewport, the same shape the gallery stage uses.
+			 *
+			 * The corner grip used to be a child of `.inspector__viewport` (never of
+			 * `.inspector__frame`, whose every fraction is a marquee/pan/crop coordinate). It is
+			 * out here now for the 2026-09-14 report — *"It should only be draggable when my mouse
+			 * pointer is at the bottom right corner … just like mac windows"* — and because the
+			 * bar's old `margin-block: -11px` reach hung over the picture above it AND over
+			 * `.inspector__timeline` below it, which is the *"horizontal play timeline area"* in
+			 * that same sentence. Both grips are inside the strip now, and the viewport is once
+			 * again exactly the picture — no pointer target of ours inside the drawing surface.
+			 */}
+			<div className="cbmr-rail">
+				<MediaResizeBar {...resizeHandle} label="Picture height" />
 				<MediaResizeCorner {...resizeHandle} label="Picture height" />
 			</div>
-			<MediaResizeBar {...resizeHandle} label="Picture height" />
 
 			<div className="inspector__transport">
 				<Button onClick={() => stepFrame(-1)} tooltip="Back one frame (←)" variant="ghost">

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

@@ -0,0 +1,175 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { cleanup, render } from '@testing-library/react';
+import { FrameGrabber } from './FrameGrabber';
+
+afterEach(cleanup);
+
+// The dialog is a Radix portal, so everything it renders is queried off `document.body`.
+const body = () => document.body;
+
+/**
+ * The dialog's `<video>`, with a recording stub for the two methods happy-dom does not
+ * implement. Same technique, and the same reason, as `MediaGallery.spec.tsx`'s.
+ */
+function stubVideo(): { calls: string[]; video: HTMLVideoElement } {
+  const video = body().querySelector('video') as HTMLVideoElement;
+  expect(video, 'the dialog rendered no <video> to toggle').not.toBeNull();
+  let paused = true;
+  const calls: string[] = [];
+  Object.defineProperty(video, 'paused', { configurable: true, get: () => paused });
+  video.play = (() => {
+    calls.push('play');
+    paused = false;
+    return Promise.resolve();
+  }) as HTMLVideoElement['play'];
+  video.pause = () => {
+    calls.push('pause');
+    paused = true;
+  };
+  return { calls, video };
+}
+
+/** Dispatch a bare Space at `target`, and report whether the dialog claimed it. */
+function press(target: EventTarget): boolean {
+  const event = new KeyboardEvent('keydown', { key: ' ', bubbles: true, cancelable: true });
+  Object.defineProperty(event, 'target', { value: target });
+  window.dispatchEvent(event);
+  return event.defaultPrevented;
+}
+
+function open(props: { open?: boolean; startAt?: number } = {}) {
+  return render(
+    <FrameGrabber
+      src='/films/wedding.mp4'
+      name='wedding.mp4'
+      onClose={() => {}}
+      onSaveThumbnail={() => {}}
+      onSaveSnapshot={() => {}}
+      {...props}
+    />,
+  );
+}
+
+/**
+ * 🔴 SPACE IS PLAY/PAUSE IN HERE TOO.
+ *
+ * The owner, 2026-09-14, on the thumbnail chooser in `apps/collections`: *"the space bar
+ * should toggle playing the video no matter what is focused but isn't working on the
+ * thumbnail selection page."*
+ *
+ * Finding one frame in a two-hour wedding video is not a job for a slider you nudge — you let
+ * it run and stop where you want it. The press was not being dropped, either: `MediaGallery`
+ * binds the same rule at capture on `window`, so it was toggling the STAGE player behind this
+ * dialog, a film the reader cannot see. That handler now stands down while a capability dialog
+ * is open (asserted in `MediaGallery.spec.tsx`), and this is the other half.
+ */
+describe('🔴 FrameGrabber — Space toggles the clip you are scrubbing', () => {
+  test('a press with nothing focused plays, and the next one pauses', () => {
+    open();
+    const { calls } = stubVideo();
+    expect(press(body()), 'the dialog did not claim the press').toBe(true);
+    expect(calls).toEqual(['play']);
+    press(body());
+    expect(calls).toEqual(['play', 'pause']);
+  });
+
+  test('🔴 …and it still toggles while one of the dialog’s own buttons has focus', () => {
+    // The state the hand is actually in: Cancel, Centre it, a crop pill or the segment was the
+    // last thing pressed, and the browser would otherwise activate it on the Space KEYUP. That
+    // inversion is the whole point of `playerSpaceKey` — see its header.
+    open();
+    const { calls } = stubVideo();
+    const cancel = Array.from(body().querySelectorAll('button')).find(
+      (b) => b.textContent === 'Cancel',
+    );
+    expect(cancel, 'no Cancel button to focus').toBeDefined();
+    expect(press(cancel as HTMLElement)).toBe(true);
+    expect(calls).toEqual(['play']);
+  });
+
+  test('🔴 a press on the MOMENT slider toggles playback rather than nudging the frame', () => {
+    // `<input type="range">` is deliberately NOT text entry: the dialog is made of sliders, so
+    // standing down for one would turn the shortcut off exactly where the pointer has been.
+    open();
+    const { calls } = stubVideo();
+    const slider = body().querySelector('input[type="range"]') as HTMLElement;
+    expect(slider, 'the dialog rendered no slider').not.toBeNull();
+    expect(press(slider)).toBe(true);
+    expect(calls).toEqual(['play']);
+  });
+
+  test('typing a space in a text field is never stolen', () => {
+    open();
+    const { calls } = stubVideo();
+    for (const tag of ['input', 'textarea'] as const) {
+      const field = document.createElement(tag);
+      body().appendChild(field);
+      expect(press(field), `${tag} lost its space`).toBe(false);
+      field.remove();
+    }
+    const editable = document.createElement('div');
+    editable.setAttribute('contenteditable', 'true');
+    body().appendChild(editable);
+    expect(press(editable), 'a contenteditable lost its space').toBe(false);
+    editable.remove();
+    expect(calls, 'a text field must never reach the player').toEqual([]);
+  });
+
+  test('a CLOSED grabber does not own the space bar', () => {
+    // It is mounted-but-closed for as long as a caller holds `open={false}`, and a dialog
+    // nobody can see claiming a global key is the bug one file over.
+    open({ open: false });
+    expect(body().querySelector('video'), 'a closed dialog rendered a player').toBeNull();
+    expect(press(body())).toBe(false);
+  });
+
+  test('🔴 the rule is IMPORTED from playerSpaceKey, not re-implemented here', () => {
+    // The three previous copies of this rule disagreed in the one case the owner hits, which is
+    // why `playerSpaceKey.ts` exists. A behavioural test cannot tell a fourth copy that happens
+    // to agree today from the shared rule; this can.
+    const source = readFileSync(resolve(import.meta.dir, 'FrameGrabber.tsx'), 'utf8');
+    expect(source).toInclude("from './playerSpaceKey'");
+    expect(source).toInclude('usePlayPauseSpace(');
+    expect(source, 'a hand-rolled Space test means the shared rule was bypassed').not.toInclude(
+      "=== ' '",
+    );
+  });
+});
+
+/**
+ * The owner's OTHER ask about this dialog, from 2026-08-13 — *"should open to the same spot in
+ * the timeline I click it at because that's usually about where I want the snapshot"* — was
+ * already built. This is the check that it stays built: `startAt` is React state from the first
+ * render, so the readout says where it opened before the clip has decoded a single frame.
+ */
+describe('FrameGrabber — it opens at the playhead it was handed', () => {
+  test('the Moment readout shows the carried time, not 0:00', () => {
+    open({ startAt: 214.6 });
+    const readout = body().querySelector('.cbpe-readout');
+    expect(readout?.textContent).toBe('3:34');
+  });
+
+  test('no playhead means the start of the clip', () => {
+    open();
+    expect(body().querySelector('.cbpe-readout')?.textContent).toBe('0:00');
+  });
+});
+
+/**
+ * 🔴 The way out is SAID, not discovered.
+ *
+ * Owner, 2026-09-14: *"I did not see the 'Done' button for a while and thought that refreshing
+ * was the only way I could find to get out of it."* The button was on screen — that is measured
+ * at his window height in `e2e/dialog-reach.spec.ts` — so this is the second, separate defect in
+ * the same sentence, and it is not one geometry can answer.
+ */
+describe('FrameGrabber — the exit is named in the dialog itself', () => {
+  test('the subtitle says where the keep button is and what Escape does', () => {
+    open();
+    const text = (document.body.querySelector('[role="dialog"]')?.textContent ?? '').toLowerCase();
+    expect(text, 'nothing tells the reader where the keep button is').toContain('bottom');
+    expect(text, 'nothing tells the reader how to leave without saving').toContain('escape');
+  });
+});

package/src/react/media/FrameGrabber.tsx

@@ -16,6 +16,7 @@ import {
   NO_LIGHT,
   type PictureLight,
 } from './pictureEdit';
+import { usePlayPauseSpace } from './playerSpaceKey';
 import {
   DEFAULT_FRAMING,
   drawFramedPoster,
@@ -101,6 +102,29 @@ type Grab = 'thumbnail' | 'picture';
  *    gallery and two cannot be kept. That is the case the ruling bites on, so the button SAYS
  *    it is a replacement when there is something to replace (`hasPoster`) rather than quietly
  *    overwriting the poster somebody chose last week.
+ *
+ * ── 🔴 STILL A DIALOG, and the owner asked for a page. Here is the reasoning ──────────────
+ * `ideas/collections-09-14.md`, 2026-09-14, ends: *"Let's put the thumbnail selector on it's own
+ * page to make this less confusing."* Read with the sentence before it, that is a proposed FIX
+ * for four complaints, not a fifth want — the footer he could not reach, the folders that would
+ * not respond, the selection that did not clear this away, and the space bar.
+ *
+ * It stays a dialog, because all four are now answered where they belong and a page would cost
+ * the one thing this shape buys: **the gallery's player stays mounted behind it**, which is what
+ * makes "open at the moment I was watching" a carried number rather than a second load and a
+ * second seek of a two-hour film. A route would also have to invent a way back, and "back" from
+ * a route is the browser's history — the control that, in the report one file over, took him out
+ * of the app.
+ *
+ *   · the footer cannot leave the screen: `Modal` caps the card and pins the action bar, and
+ *     `e2e/dialog-reach.spec.ts` MEASURES both at a 420px-tall window (proven to go red when
+ *     the cap is removed — no unit test can see it, happy-dom computes no layout);
+ *   · selecting anything else leaves this screen: `MediaGallery` clears the dialog with the
+ *     selection, which is the wire a sidebar is on;
+ *   · Space plays and pauses the clip you are scrubbing, through `playerSpaceKey`;
+ *   · and the way out is now SAID rather than discovered — see the `subtitle` below, which is
+ *     the half of *"I did not see the 'Done' button for a while and thought that refreshing was
+ *     the only way I could find to get out of it"* that geometry does not fix.
  */
 export function FrameGrabber({
   src,
@@ -178,6 +202,38 @@ export function FrameGrabber({
     return () => stage.removeEventListener('wheel', onWheel);
   }, [grab]);
 
+  /*
+   * 🔴 Space is play/pause HERE TOO, through the fleet's one rule rather than a fourth copy.
+   *
+   * The owner, 2026-09-14: *"the space bar should toggle playing the video no matter what is
+   * focused but isn't working on the thumbnail selection page."*
+   *
+   * Two things were wrong and only one of them was here. `MediaGallery` binds the same rule at
+   * capture on `window` whenever a file is open, so the press WAS being handled — against the
+   * stage player behind this dialog, a film the reader cannot see. That handler now stands
+   * down while a capability dialog is up (see its comment), which leaves the key for this one.
+   *
+   * Finding the moment is what this dialog is for, and letting it RUN is how you find it: a
+   * two-hour wedding video is not scrubbable a slider-nudge at a time. `usePlayPauseSpace`
+   * carries the whole rule — capture phase, `preventDefault` on the keydown so a focused
+   * Cancel button is not activated on the keyup, and the text-entry exemption. Every control
+   * in here is a button or a `range`, which that rule deliberately takes the key back from.
+   *
+   * `enabled: open` rather than always: this component is mounted by a caller that may hold it
+   * closed, and a closed dialog owning the space bar is the bug one file over.
+   */
+  usePlayPauseSpace(
+    () => {
+      const video = videoRef.current;
+      if (!video) return;
+      // `.play()` rejects if the element is torn down mid-gesture; there is nothing to say
+      // about that to somebody who pressed a key, and an unhandled rejection is noise.
+      if (video.paused) void video.play().catch(() => {});
+      else video.pause();
+    },
+    { enabled: open },
+  );
+
   const setCrop = (rect: CropRect | undefined) => setCropState(rect);
 
   /** A pointer position as a fraction of the stage box — the marquee's coordinate system. */
@@ -292,6 +348,17 @@ export function FrameGrabber({
       onClose={onClose}
       size='lg'
       title={name ? `Pick a moment in ${name}` : 'Pick a moment'}
+      /*
+       * 🔴 The way OUT, stated. Owner, 2026-09-14: *"I did not see the 'Done' button for a
+       * while and thought that refreshing was the only way I could find to get out of it."*
+       *
+       * The button was on screen (that is measured now, at his window height), so this is not
+       * a layout fix wearing a sentence — it is the other defect in the same report. The
+       * dialog is a wide two-column workspace whose one exit is a pill in the bottom corner,
+       * and a reader hunting for it has no reason to believe the corner is where it lives.
+       * `DESIGN.md` §6 keeps this to two muted lines; one is enough.
+       */
+      subtitle='Scrub to the moment you want, then keep it with the button at the bottom. Escape leaves it as it was.'
       scrollBody
       /*
        * Scrubbing to a moment, framing it and re-lighting it IS unsaved work, even though