cursedbelt 5.46.2 → 5.48.0

package/src/react/file-tree/folderViewTree.spec.tsx

@@ -1,10 +1,11 @@
 import { afterEach, beforeAll, beforeEach, describe, expect, spyOn, test } from 'bun:test';
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
 import type { FileTreeNode } from 'cursedbelt-core/file-tree/file-tree-model';
 import { onPreferenceWrite } from '../media-gallery/preferenceBus.js';
 import { toast } from '../Toast.js';
 import { FileTree, type FileTreeProps, preloadFileTreePanels } from './FileTree.js';
-import { useFolderView } from './useFolderView.js';
+import { type UseFolderViewOptions, useFolderView } from './useFolderView.js';
 
 /**
  * Hidden folders and folder tags, through the gestures the owner named: right-click a folder,
@@ -27,8 +28,8 @@ const TREE: FileTreeNode[] = [
   { id: 'readme', name: 'readme.md', kind: 'file' },
 ];
 
-function Harness(props: Partial<FileTreeProps>) {
-  const folderView = useFolderView({ key: KEY });
+function Harness({ options, ...props }: Partial<FileTreeProps> & { options?: Partial<UseFolderViewOptions> }) {
+  const folderView = useFolderView({ key: KEY, ...options });
   return (
     <div>
       {/* biome-ignore lint/a11y/noStaticElementInteractions: stands in for an app's header bar, whose right-click is exactly what is under test. */}
@@ -66,10 +67,10 @@ beforeEach(() => globalThis.localStorage.clear());
 afterEach(cleanup);
 
 describe('hiding a folder', () => {
-  test('🔴 right-click a folder → Hide folder → it and its contents leave the tree', () => {
+  test('🔴 right-click a folder → Hide everywhere → it and its contents leave the tree', () => {
     render(<Harness />);
     fireEvent.contextMenu(row('Work'), { clientX: 10, clientY: 10 });
-    fireEvent.click(item('Hide folder'));
+    fireEvent.click(item('Hide everywhere'));
     expect(screen.queryByText('Work')).toBeNull();
     expect(screen.queryByText('Dynatrace')).toBeNull();
     expect(screen.getByText('Home')).toBeDefined();
@@ -87,17 +88,17 @@ describe('hiding a folder', () => {
     try {
       render(<Harness />);
       fireEvent.contextMenu(row('Work'));
-      fireEvent.click(item('Hide folder'));
+      fireEvent.click(item('Hide everywhere'));
       expect(said.map((s) => s.message)).toEqual(['Hid “Work”, on every device']);
       expect(screen.queryByText('Work')).toBeNull();
       act(() => said[0]?.undo());
       expect(screen.getByText('Work')).toBeDefined();
 
       fireEvent.contextMenu(row('Work'));
-      fireEvent.click(item('Hide folder'));
+      fireEvent.click(item('Hide everywhere'));
       fireEvent.keyDown(row('Home'), { key: '.', code: 'Period', shiftKey: true, metaKey: true });
       fireEvent.contextMenu(row('Work'));
-      fireEvent.click(item('Unhide folder'));
+      fireEvent.click(item('Unhide everywhere'));
       expect(said.at(-1)?.message).toBe('“Work” is back in the tree, on every device');
       expect(row('Work').getAttribute('data-hidden')).toBeNull();
       act(() => said.at(-1)?.undo());
@@ -110,7 +111,7 @@ describe('hiding a folder', () => {
   test('🔴 "Show hidden folders" draws them back — the hidden one italic-marked, its contents faded-marked', () => {
     render(<Harness />);
     fireEvent.contextMenu(row('Work'));
-    fireEvent.click(item('Hide folder'));
+    fireEvent.click(item('Hide everywhere'));
     fireEvent.contextMenu(blank(), { clientX: 5, clientY: 300 });
     fireEvent.click(item(/Show hidden folders \(1\)/));
     expect(row('Work').getAttribute('data-hidden')).toBe('self');
@@ -121,14 +122,14 @@ describe('hiding a folder', () => {
     // Still hideable — the owner's "showing hidden folders still keeps them hideable": its own
     // menu now offers the way back.
     fireEvent.contextMenu(row('Work'));
-    fireEvent.click(item('Unhide folder'));
+    fireEvent.click(item('Unhide everywhere'));
     expect(row('Work').getAttribute('data-hidden')).toBeNull();
   });
 
   test('the strip says hidden folders are showing, and its button leaves them out again', () => {
     render(<Harness />);
     fireEvent.contextMenu(row('Work'));
-    fireEvent.click(item('Hide folder'));
+    fireEvent.click(item('Hide everywhere'));
     fireEvent.contextMenu(blank());
     fireEvent.click(item(/Show hidden folders/));
     expect(screen.getByText('Showing hidden')).toBeDefined();
@@ -140,7 +141,7 @@ describe('hiding a folder', () => {
   test('⇧⌘. on a row toggles hidden folders — Finder\'s chord', () => {
     render(<Harness />);
     fireEvent.contextMenu(row('Work'));
-    fireEvent.click(item('Hide folder'));
+    fireEvent.click(item('Hide everywhere'));
     fireEvent.keyDown(row('Home'), { key: '>', code: 'Period', shiftKey: true, metaKey: true });
     expect(row('Work').getAttribute('data-hidden')).toBe('self');
     fireEvent.keyDown(row('Home'), { key: '>', code: 'Period', shiftKey: true, metaKey: true });
@@ -223,7 +224,7 @@ describe('🔴 what reaches other devices, and what does not', () => {
     try {
       render(<Harness />);
       fireEvent.contextMenu(row('Work'));
-      fireEvent.click(item('Hide folder'));
+      fireEvent.click(item('Hide everywhere'));
       expect(heard).toEqual([KEY]);
       fireEvent.contextMenu(blank());
       fireEvent.click(item(/Show hidden folders/));
@@ -235,7 +236,100 @@ describe('🔴 what reaches other devices, and what does not', () => {
   });
 });
 
+describe('🔴 hidden on THIS device only — desk\'s two lists, in the belt', () => {
+  test('Hide on this device leaves the tree, is never announced, and is stored on this device', () => {
+    const heard: string[] = [];
+    const stop = onPreferenceWrite((key) => heard.push(key));
+    try {
+      render(<Harness />);
+      fireEvent.contextMenu(row('Work'));
+      fireEvent.click(item('Hide on this device'));
+      expect(screen.queryByText('Work')).toBeNull();
+      expect(heard).toEqual([]);
+      expect(globalThis.localStorage.getItem(KEY)).toBeNull();
+      expect(globalThis.localStorage.getItem(`${KEY}:device`)).toContain('"hidden":["work"]');
+    } finally {
+      stop();
+    }
+  });
+
+  test('under Show hidden, the menu says WHICH list a folder is in, and unhides from that one', () => {
+    render(<Harness />);
+    fireEvent.contextMenu(row('Work'));
+    fireEvent.click(item('Hide on this device'));
+    fireEvent.contextMenu(row('Home'));
+    fireEvent.click(item('Hide everywhere'));
+    fireEvent.keyDown(row('readme.md'), { key: '>', code: 'Period', shiftKey: true, metaKey: true });
+
+    fireEvent.contextMenu(row('Work'));
+    expect(() => item('Unhide everywhere')).toThrow();
+    fireEvent.click(item('Unhide on this device'));
+    expect(row('Work').getAttribute('data-hidden')).toBeNull();
+
+    fireEvent.contextMenu(row('Home'));
+    expect(() => item('Unhide on this device')).toThrow();
+    fireEvent.click(item('Unhide everywhere'));
+    expect(row('Home').getAttribute('data-hidden')).toBeNull();
+  });
+});
+
+describe('🔴 the marks kept by the app — `store` and `device: \'memory\'`', () => {
+  test('with a store, a hide goes to the store and NOTHING touches localStorage or the bus', () => {
+    const written: (string | null)[] = [];
+    const heard: string[] = [];
+    const stop = onPreferenceWrite((key) => heard.push(key));
+    try {
+      function Kept() {
+        const [marks, setMarks] = useState<string | null>(null);
+        return (
+          <Harness
+            options={{
+              store: {
+                marks,
+                write: (next) => {
+                  written.push(next);
+                  setMarks(next);
+                },
+              },
+              device: 'memory',
+            }}
+          />
+        );
+      }
+      render(<Kept />);
+      fireEvent.contextMenu(row('Work'));
+      // No device half kept → one hide, which means everywhere.
+      expect(() => item('Hide on this device')).toThrow();
+      fireEvent.click(item('Hide folder'));
+      expect(screen.queryByText('Work')).toBeNull();
+      expect(written).toHaveLength(1);
+      expect(written[0]).toContain('"hidden":["work"]');
+      fireEvent.keyDown(row('Home'), { key: '>', code: 'Period', shiftKey: true, metaKey: true });
+      expect(row('Work').getAttribute('data-hidden')).toBe('self');
+      expect(globalThis.localStorage.length).toBe(0);
+      expect(heard).toEqual([]);
+    } finally {
+      stop();
+    }
+  });
+
+  test('the store is the truth: a value it hands in is what the tree draws', () => {
+    render(<Harness options={{ store: { marks: '{"hidden":["home"],"tags":{}}', write: () => undefined } }} />);
+    expect(screen.queryByText('Home')).toBeNull();
+    expect(screen.getByText('Work')).toBeDefined();
+  });
+});
+
 describe('a row menu of the app\'s own', () => {
+  test('🔴 with onRowMenu and no rowMenu, right-click opens the APP\'s menu at the pointer', () => {
+    const opened: { id: string; x: number; y: number }[] = [];
+    render(<Harness onRowMenu={(node, at) => opened.push({ id: node.id, ...at })} />);
+    expect(fireEvent.contextMenu(row('readme.md'), { clientX: 40, clientY: 50 })).toBe(false);
+    expect(opened).toEqual([{ id: 'readme', x: 40, y: 50 }]);
+    // The tree drew no menu of its own over the app's.
+    expect(items()).toHaveLength(0);
+  });
+
   test('rowMenu items open on right-click, with Hide and Tags… after them on a folder', () => {
     let renamed = '';
     render(
@@ -246,7 +340,7 @@ describe('a row menu of the app\'s own', () => {
     fireEvent.contextMenu(row('Home'));
     const labels = items().map((el) => el.textContent);
     expect(labels[0]).toBe('Rename');
-    expect(labels.some((l) => l?.startsWith('Hide folder'))).toBe(true);
+    expect(labels.some((l) => l?.startsWith('Hide everywhere'))).toBe(true);
     fireEvent.click(item('Rename'));
     expect(renamed).toBe('home');
   });
@@ -264,7 +358,8 @@ describe('a row menu of the app\'s own', () => {
     fireEvent.contextMenu(row('Home'));
     expect(items().map((el) => el.querySelector('.truncate')?.textContent)).toEqual([
       'Rename',
-      'Hide folder',
+      'Hide on this device',
+      'Hide everywhere',
       'Tags…',
       'Delete folder',
     ]);
@@ -274,7 +369,7 @@ describe('a row menu of the app\'s own', () => {
     render(<Harness />);
     act(() => row('Home').focus());
     fireEvent.keyDown(row('Home'), { key: 'F10', shiftKey: true });
-    expect(item('Hide folder')).toBeDefined();
+    expect(item('Hide everywhere')).toBeDefined();
   });
 
   test('a tree with neither rowMenu nor folderView leaves right-click to the browser', () => {

package/src/react/file-tree/index.ts

@@ -65,4 +65,18 @@ export {
   folderViewMenuItems,
   withFolderItems,
 } from './FolderViewMenus.js';
-export { type FolderView, type UseFolderViewOptions, useFolderView } from './useFolderView.js';
+export {
+  type FolderMarks,
+  type FolderViewLocal,
+  type HiddenScope,
+  parseFolderMarks,
+  remapFolderMarks,
+  serializeFolderMarks,
+} from './folderView.js';
+export {
+  type FolderMarksStore,
+  type FolderView,
+  type HideScope,
+  type UseFolderViewOptions,
+  useFolderView,
+} from './useFolderView.js';

package/src/react/file-tree/useFolderView.ts

@@ -17,6 +17,13 @@
  *     announced — *"Hiding or showing by tag can be stored per machine, so viewing the 'home'
  *     tag at home doesn't change my work computer."*
  *
+ * An app that already keeps its own settings record hands the marks over instead — `store` — and
+ * then nothing goes to `localStorage` or the bus: desk carries them in its global settings blob
+ * beside the rest of its synced state, and vault seals them inside the vault, because its folder
+ * ids are folder NAMES and must never reach a disk in plaintext. `device: 'memory'` keeps the
+ * device half in page memory for the same reason; with it, "Hide on this device" is not offered,
+ * since a device list forgotten on reload would be a hide that silently undoes itself.
+ *
  * And because the tree's header belongs to the APP (collections' `FilterRail` section, desk's
  * explorer bar), the view menu has to be openable from outside the tree: the hook holds which
  * menu is open, and the tree draws it. `onContextMenu` is the one handler an app puts on its
@@ -27,6 +34,8 @@ import { useRememberedPreference } from '../media-gallery/rememberedPreference.j
 import {
   type FolderMarks,
   type FolderViewLocal,
+  type HiddenScope,
+  hiddenScope,
   normalizeTag,
   parseFolderMarks,
   parseFolderViewLocal,
@@ -50,14 +59,23 @@ export type FolderViewPanel =
   | { kind: 'view'; at: FolderViewPoint }
   | { kind: 'tags'; at: FolderViewPoint | null; ids: readonly string[] };
 
+/** Which list a hide writes to, or an unhide takes from. */
+export type HideScope = 'everywhere' | 'device';
+
 export interface FolderView {
   marks: FolderMarks;
   local: FolderViewLocal;
   /** Every tag in use, most-used first. */
   tags: readonly TagCount[];
+  /** Whether "Hide on this device" is offered — false when the device half is not kept. */
+  deviceHiding: boolean;
+  /** Which of the two lists hide this folder, if any. */
+  hiddenIn: (id: string) => HiddenScope | null;
 
-  hide: (ids: readonly string[]) => void;
-  unhide: (ids: readonly string[]) => void;
+  /** Hide these folders — everywhere unless `scope: 'device'`. */
+  hide: (ids: readonly string[], options?: { scope?: HideScope }) => void;
+  /** Unhide these folders from the one list named, or from both when none is. */
+  unhide: (ids: readonly string[], options?: { scope?: HideScope }) => void;
   /** Add or take away one tag on each folder named. */
   toggleTag: (ids: readonly string[], tag: string) => void;
   /** Replace one folder's tags. */
@@ -88,11 +106,39 @@ export interface UseFolderViewOptions {
    * origin must not hide each other's folders.
    */
   key: string;
+  /**
+   * The app keeps the marks itself — its own synced settings, or a sealed record. `marks` is
+   * what it holds now (`null` for none) and `write` is called with the next value to keep.
+   * Given a store, the marks never touch `localStorage` or the preference bus.
+   */
+  store?: FolderMarksStore;
+  /**
+   * Where this device's view (show hidden, the tag filter, the device-only hidden list) lives:
+   * `'local'` (the default) is `localStorage` under `${key}:device`, never announced;
+   * `'memory'` is this page only, for an app whose folder ids may not be written to disk.
+   */
+  device?: 'local' | 'memory';
 }
 
-export function useFolderView({ key }: UseFolderViewOptions): FolderView {
-  const [rawMarks, writeMarks] = useRememberedPreference(key);
-  const [rawLocal, writeLocal] = useRememberedPreference(`${key}:device`, { announce: false });
+/** The marks, kept by the app — see {@link UseFolderViewOptions.store}. */
+export interface FolderMarksStore {
+  /** The stored form (`serializeFolderMarks`), or `null` for no marks. */
+  marks: string | null;
+  write: (next: string | null) => void;
+}
+
+export function useFolderView({ key, store, device = 'local' }: UseFolderViewOptions): FolderView {
+  // Hooks run unconditionally; an undefined key is the remembered preference that keeps nothing.
+  const [rememberedMarks, rememberMarks] = useRememberedPreference(store ? undefined : key);
+  const [rememberedLocal, rememberLocal] = useRememberedPreference(
+    device === 'local' ? `${key}:device` : undefined,
+    { announce: false },
+  );
+  const [memoryLocal, setMemoryLocal] = useState<string | null>(null);
+  const rawMarks = store ? store.marks : rememberedMarks;
+  const writeMarks = store ? store.write : rememberMarks;
+  const rawLocal = device === 'local' ? rememberedLocal : memoryLocal;
+  const writeLocal = device === 'local' ? rememberLocal : setMemoryLocal;
   const marks = useMemo(() => parseFolderMarks(rawMarks), [rawMarks]);
   const local = useMemo(() => parseFolderViewLocal(rawLocal), [rawLocal]);
   const tags = useMemo(() => tagCounts(marks), [marks]);
@@ -114,13 +160,20 @@ export function useFolderView({ key }: UseFolderViewOptions): FolderView {
     },
     [writeMarks],
   );
+  // The same rule for this device's view: an Undo of "Hide on this device" must see the hide.
+  const latestLocal = useRef(local);
+  latestLocal.current = local;
   const saveLocal = useCallback(
     (next: FolderViewLocal) => {
-      const empty = !next.showHidden && next.only.length === 0 && next.hide.length === 0;
+      if (next === latestLocal.current) return;
+      latestLocal.current = next;
+      const empty =
+        !next.showHidden && next.only.length === 0 && next.hide.length === 0 && next.hidden.length === 0;
       writeLocal(empty ? null : JSON.stringify(next));
     },
     [writeLocal],
   );
+  const deviceHiding = device === 'local';
 
   const onContextMenu = useCallback((event: { clientX: number; clientY: number; preventDefault: () => void }) => {
     event.preventDefault();
@@ -132,8 +185,16 @@ export function useFolderView({ key }: UseFolderViewOptions): FolderView {
       marks,
       local,
       tags,
-      hide: (ids) => saveMarks(setHidden(latest.current, ids, true)),
-      unhide: (ids) => saveMarks(setHidden(latest.current, ids, false)),
+      deviceHiding,
+      hiddenIn: (id) => hiddenScope(marks, local, id),
+      hide: (ids, options) => {
+        if (options?.scope === 'device' && deviceHiding) saveLocal(setHidden(latestLocal.current, ids, true));
+        else saveMarks(setHidden(latest.current, ids, true));
+      },
+      unhide: (ids, options) => {
+        if (options?.scope !== 'device') saveMarks(setHidden(latest.current, ids, false));
+        if (options?.scope !== 'everywhere') saveLocal(setHidden(latestLocal.current, ids, false));
+      },
       toggleTag: (ids, raw) => {
         const tag = normalizeTag(raw);
         if (!tag || ids.length === 0) return;
@@ -148,15 +209,15 @@ export function useFolderView({ key }: UseFolderViewOptions): FolderView {
         saveMarks(next);
       },
       setTags: (id, list) => saveMarks(setFolderTags(latest.current, id, list)),
-      setShowHidden: (show) => saveLocal({ ...local, showHidden: show }),
-      filterTag: (tag, mode) => saveLocal(setTagFilter(local, tag, mode)),
-      clearTagFilter: () => saveLocal({ ...local, only: [], hide: [] }),
+      setShowHidden: (show) => saveLocal({ ...latestLocal.current, showHidden: show }),
+      filterTag: (tag, mode) => saveLocal(setTagFilter(latestLocal.current, tag, mode)),
+      clearTagFilter: () => saveLocal({ ...latestLocal.current, only: [], hide: [] }),
       panel,
       openViewMenu: (at) => setPanel({ kind: 'view', at }),
       openTagEditor: (ids, at) => setPanel({ kind: 'tags', at: at ?? null, ids }),
       closePanel: () => setPanel(null),
       onContextMenu,
     }),
-    [marks, local, tags, panel, saveMarks, saveLocal, onContextMenu],
+    [marks, local, tags, deviceHiding, panel, saveMarks, saveLocal, onContextMenu],
   );
 }

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

@@ -16,7 +16,7 @@ describe('DenseGalleryDetail fullscreen toggle', () => {
       />,
     );
     expect(container.querySelector('.cbgd-watch')?.className).not.toContain('cbgd-watch-full');
-    expect(getByRole('button', { name: /fullscreen/i })).toBeDefined();
+    expect(getByRole('button', { name: 'Full window' })).toBeDefined();
   });
 
   test('clicking the toggle adds cbgd-watch-full and flips the button label', () => {
@@ -29,12 +29,14 @@ describe('DenseGalleryDetail fullscreen toggle', () => {
         renderTile={() => null}
       />,
     );
-    const toggle = getByRole('button', { name: /fullscreen/i });
+    const toggle = getByRole('button', { name: 'Full window' });
     fireEvent.click(toggle);
     expect(container.querySelector('.cbgd-watch')?.className).toContain('cbgd-watch-full');
-    expect(getByRole('button', { name: /shrink/i })).toBeDefined();
+    expect(toggle.getAttribute('aria-pressed')).toBe('true');
 
-    fireEvent.click(getByRole('button', { name: /shrink/i }));
+    // The floating way out — the titlebar's toggle is below the fold once the picture fills
+    // the window.
+    fireEvent.click(getByRole('button', { name: 'Leave full window' }));
     expect(container.querySelector('.cbgd-watch')?.className).not.toContain('cbgd-watch-full');
   });
 });
@@ -149,7 +151,7 @@ describe('leaving full-stage by double-clicking the picture', () => {
 
   test('a double-click on the frame leaves full-stage', () => {
     const { container, getByRole } = detail();
-    fireEvent.click(getByRole('button', { name: /fullscreen/i }));
+    fireEvent.click(getByRole('button', { name: 'Full window' }));
     const frame = container.querySelector('.cbgd-watch-player-box');
     expect(frame).not.toBeNull();
     fireEvent.doubleClick(frame as Element);
@@ -186,7 +188,7 @@ describe('leaving full-stage by double-clicking the picture', () => {
     // `MediaGallery` passes `fullscreenOnDoubleClick={!fullStage}`, so while the shell is full
     // there is exactly one claimant on the gesture and it is this one.
     const { container, getByRole } = detail({ stageOwnsDoubleClick: true });
-    fireEvent.click(getByRole('button', { name: /fullscreen/i }));
+    fireEvent.click(getByRole('button', { name: 'Full window' }));
     expect(container.querySelector('.cbgd-watch')?.className).toContain('cbgd-watch-full');
     fireEvent.doubleClick(container.querySelector('.cbgd-watch-player-box') as Element);
     expect(container.querySelector('.cbgd-watch')?.className).not.toContain('cbgd-watch-full');
@@ -232,6 +234,6 @@ describe('leaving full-stage by double-clicking the picture', () => {
       />,
     );
     expect(container.querySelector('.cbgd-watch')?.className).not.toContain('cbgd-watch-full');
-    expect(getByRole('button', { name: /fullscreen/i })).toBeDefined();
+    expect(getByRole('button', { name: 'Full window' })).toBeDefined();
   });
 });

package/src/react/media/DenseGalleryShell.tsx

@@ -434,6 +434,13 @@ export interface DenseGalleryDetailProps {
    * player is told to stand down there. See `leaveFullStage`.
    */
   stageOwnsDoubleClick?: boolean;
+  /**
+   * Does the STAGE draw its own full-window toggle? `true` for a Vidstack video, whose control
+   * bar carries one beside fullscreen (`VideoPlayer`'s `fillWindowSlots`). Otherwise the shell
+   * floats its own way out over the corner of the window while `fullStage` is on, because the
+   * titlebar's toggle is below the fold whenever the picture fills the window's height.
+   */
+  stageOffersFullStageToggle?: boolean;
 }
 
 /**
@@ -467,6 +474,7 @@ export function DenseGalleryDetail({
   fullStage: fullStageProp,
   onFullStageChange,
   stageOwnsDoubleClick = false,
+  stageOffersFullStageToggle = false,
 }: DenseGalleryDetailProps) {
   // The watch view is ONE scroll container; the related grid windows against it so the
   // stage scrolls off in normal flow rather than the grid owning a nested inner scroller.
@@ -565,10 +573,23 @@ export function DenseGalleryDetail({
     apply();
     return () => observer.disconnect();
   }, [watchEl]);
-  // Fullscreen here means "take over the whole plugin container" — the rail and the
-  // related grid below hide and the stage grows to fill the space they vacate. This is
-  // independent of any player-level browser Fullscreen API toggle (e.g. CanvasVideoPlayer's
-  // own button, which fullscreens just the `<video>`/`<canvas>` element).
+  /*
+   * 🔴 Full-stage means FULL WINDOW — the browser window, not the plugin and not the screen.
+   *
+   * Owner, 2026-10-02: *"I often want the video as big as it can be to fill the browser
+   * window, while still keeping the aspect ratio and every part of the content visible … I
+   * still want to be able to scroll down to see other media files … This mode should also
+   * hide the top rows above the video … and hide the sidebar area too, but still allow
+   * scrolling."* Until then this filled only the gallery's own container — the app's
+   * toolstrip, its sidebar and its activity column still took their share of the window —
+   * and hid the related grid outright, so there was nothing to scroll to.
+   *
+   * So the detail view lifts itself over the WHOLE window (`.cbgd-watch-full`, `position:
+   * fixed`), the frame is exactly one window tall, and the titlebar and the related grid
+   * follow it in the same scroll. It is not browser fullscreen, which takes the physical
+   * screen; that stays the player's own button. Lifting with CSS rather than a portal is the
+   * point: a portal remounts the stage, and the video would start over.
+   */
   const [ownFullStage, setOwnFullStage] = useState(false);
   // Controlled when the consumer passes it, uncontrolled otherwise — the ordinary React
   // shape, so a consumer that never heard of the prop is byte-for-byte unchanged.
@@ -580,6 +601,16 @@ export function DenseGalleryDetail({
     },
     [onFullStageChange],
   );
+  // Esc leaves full window, as it leaves every other mode that covers the page. Not while
+  // something else claimed the key first — an open menu or dialog closes and stays at that.
+  useEffect(() => {
+    if (!fullStage) return;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && !event.defaultPrevented) setFullStage(false);
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [fullStage, setFullStage]);
 
   /*
    * 🔴 Double-click the picture to ENTER and LEAVE the shell's fullscreen.
@@ -752,8 +783,8 @@ export function DenseGalleryDetail({
               {actions}
               <Tooltip content={
                   fullStage
-                    ? 'Shrink back — restore the sidebar and related grid'
-                    : 'Fill the plugin — hide the sidebar and related grid'
+                    ? 'Leave full window (Esc)'
+                    : 'Fill the window — the picture as big as the window, the files below'
                 }>
                 <button
                   // guardrails-ignore no-raw-action-button: same self-contained `.cbgd-`
@@ -762,11 +793,10 @@ export function DenseGalleryDetail({
                   type='button'
                   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'}
+                  // 🔴 One NAME, and the state in `aria-pressed` — the toggle-button pattern.
+                  // It was `Fullscreen`/`Shrink` until 2026-10-02, and `Fullscreen` stopped being
+                  // true the day this began filling the WINDOW rather than the screen.
+                  aria-label='Full window'
                   onClick={() => setFullStage(!fullStage)}
                 >
                   {fullStage ? <Minimize2 aria-hidden /> : <Maximize2 aria-hidden />}
@@ -782,6 +812,18 @@ export function DenseGalleryDetail({
         ) : null}
       </div>
 
+      {fullStage && !stageOffersFullStageToggle ? (
+        <span className='cbgd-full-exit'>
+          <GalleryActionButton
+            iconOnly
+            tooltip='Leave full window (Esc)'
+            aria-label='Leave full window'
+            onClick={() => setFullStage(false)}
+          >
+            <Minimize2 aria-hidden />
+          </GalleryActionButton>
+        </span>
+      ) : null}
       <div className='cbgd-related'>
         {relatedLabel ? <div className='cbgd-section-head'>{relatedLabel}</div> : null}
         {relatedBody ?? (