cursedbelt 5.7.3 → 5.9.0

package/src/react/filter-rail/railResize.tsx

@@ -0,0 +1,156 @@
+/**
+ * Drag a sidebar's right edge to resize it, like VS Code's side bar — the gesture half, for
+ * any rail, not only `FilterRail`.
+ *
+ * Owner, 2026-09-24: *"the cb filetree sidebars should allow grabbing their right edge and
+ * dragging to resize them like in vscode."* 5.8.0 shipped the handle INSIDE `FilterRail`; the
+ * sidebars in music (`LibraryRail`) and others are their own columns around a `FileTree`, so
+ * the handle came out here once rather than being copied into each app. `FilterRail` uses
+ * exactly this, so there is one gesture to get right:
+ *
+ * - **pointer capture**, or the drag ends the first time the pointer outruns the strip;
+ * - **←/→** (Shift for bigger steps), because a drag-only control is one some people cannot
+ *   reach;
+ * - **a `separator` role with real `aria-value*`**, the ARIA splitter pattern;
+ * - **double-click resets** to the rail's own default width, and forgets the stored one;
+ * - remembered on RELEASE — a drag is one decision, not sixty writes a second.
+ *
+ * Clamp and storage are `railWidth.ts`, so the width is announced through `preferenceSync`
+ * like every other viewer preference.
+ */
+import type { CSSProperties, KeyboardEvent as ReactKeyboardEvent, PointerEvent as ReactPointerEvent, RefObject } from 'react';
+import { useCallback, useRef, useState } from 'react';
+import { cn } from '../lib/cn.js';
+import { clampRailWidth, MAX_RAIL_PX, MIN_RAIL_PX, readRailWidth, writeRailWidth } from './railWidth.js';
+
+export interface UseRailResizeOptions {
+  /** Where the width is remembered. Absent: not resizable — no handle, no stored width. */
+  resizeKey: string | undefined;
+  /** The rail's accessible name; the handle announces as "Resize <label>". */
+  label: string;
+  /** False hides the handle and drops the dragged width (a collapsed rail). Default true. */
+  enabled?: boolean;
+}
+
+export interface RailResize<E extends HTMLElement = HTMLElement> {
+  /** Put on the rail element — the handle measures it to start a drag. */
+  railRef: RefObject<E | null>;
+  /** Whether a handle is drawn: a `resizeKey` was given and `enabled` is true. */
+  active: boolean;
+  /** The dragged width in px, or `null` for "the rail's own default width". Null while inactive. */
+  width: number | null;
+  /** `{ width }` while there is a dragged width, else `undefined` — spread onto the rail's `style`. */
+  style: CSSProperties | undefined;
+  /** Forget the dragged width (what a double-click on the handle does). */
+  reset: () => void;
+  /** @internal — read by `RailResizeHandle`. */
+  readonly handle: {
+    label: string;
+    onPointerDown: (event: ReactPointerEvent<HTMLElement>) => void;
+    onKeyDown: (event: ReactKeyboardEvent<HTMLElement>) => void;
+    /** The rail's current rendered width, for `aria-valuenow` before any drag. */
+    measure: () => number;
+  };
+}
+
+export function useRailResize<E extends HTMLElement = HTMLElement>({
+  resizeKey,
+  label,
+  enabled = true,
+}: UseRailResizeOptions): RailResize<E> {
+  const railRef = useRef<E | null>(null);
+  const [dragged, setDragged] = useState<number | null>(() => (resizeKey ? readRailWidth(resizeKey) : null));
+  const active = Boolean(resizeKey) && enabled;
+  const measure = useCallback(() => railRef.current?.getBoundingClientRect().width ?? MIN_RAIL_PX, []);
+
+  const onPointerDown = useCallback(
+    (event: ReactPointerEvent<HTMLElement>) => {
+      if (!resizeKey || event.button !== 0) return;
+      const handle = event.currentTarget;
+      const startX = event.clientX;
+      const startWidth = measure();
+      let latest = startWidth;
+      handle.setPointerCapture?.(event.pointerId);
+      const move = (moveEvent: PointerEvent) => {
+        latest = clampRailWidth(startWidth + moveEvent.clientX - startX);
+        setDragged(latest);
+      };
+      const end = () => {
+        if (handle.hasPointerCapture?.(event.pointerId)) handle.releasePointerCapture(event.pointerId);
+        handle.removeEventListener('pointermove', move);
+        handle.removeEventListener('pointerup', end);
+        handle.removeEventListener('pointercancel', end);
+        writeRailWidth(resizeKey, latest);
+      };
+      handle.addEventListener('pointermove', move);
+      handle.addEventListener('pointerup', end);
+      handle.addEventListener('pointercancel', end);
+      event.preventDefault();
+    },
+    [resizeKey, measure],
+  );
+
+  const onKeyDown = useCallback(
+    (event: ReactKeyboardEvent<HTMLElement>) => {
+      if (!resizeKey) return;
+      const step = event.shiftKey ? 64 : 16;
+      const delta = event.key === 'ArrowRight' ? step : event.key === 'ArrowLeft' ? -step : 0;
+      if (!delta) return;
+      event.preventDefault();
+      const next = clampRailWidth((dragged ?? measure()) + delta);
+      setDragged(next);
+      writeRailWidth(resizeKey, next);
+    },
+    [resizeKey, dragged, measure],
+  );
+
+  const reset = useCallback(() => {
+    setDragged(null);
+    if (resizeKey) writeRailWidth(resizeKey, null);
+  }, [resizeKey]);
+
+  const width = active ? dragged : null;
+  return {
+    railRef,
+    active,
+    width,
+    style: width === null ? undefined : { width },
+    reset,
+    handle: { label, onPointerDown, onKeyDown, measure },
+  };
+}
+
+/**
+ * The handle itself — a 12px hotspot centred on the rail's right border. The RAIL must be
+ * `position: relative` (the handle is absolutely positioned against it). Renders nothing while
+ * the resize is inactive.
+ *
+ * Only utilities the stylesheet already ships, so it adds no CSS to any app that imports the
+ * `filter-rail` area (`fixtureAppCss.spec.ts` budgets that).
+ */
+export function RailResizeHandle({ rail, className }: { rail: RailResize; className?: string }) {
+  if (!rail.active) return null;
+  const { label, onPointerDown, onKeyDown, measure } = rail.handle;
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: an <hr> cannot take focus or a drag; a focusable separator is the ARIA splitter pattern.
+    <div
+      role='separator'
+      aria-orientation='vertical'
+      aria-label={`Resize ${label}`}
+      aria-valuemin={MIN_RAIL_PX}
+      aria-valuemax={MAX_RAIL_PX}
+      aria-valuenow={Math.round(rail.width ?? measure())}
+      tabIndex={0}
+      data-cb-rail-resize=''
+      onPointerDown={onPointerDown}
+      onKeyDown={onKeyDown}
+      onDoubleClick={rail.reset}
+      // A 1px edge you cannot hit is not a handle: the hotspot is 12px, centred on the border,
+      // and only the hairline tints — no layout shift, like `PanelSeparator`.
+      className={cn(
+        'absolute inset-y-0 -right-1.5 z-20 w-3 cursor-col-resize touch-none bg-transparent transition-colors hover:bg-accent/20 active:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        className,
+      )}
+    />
+  );
+}

package/src/react/filter-rail/railWidth.ts

@@ -0,0 +1,47 @@
+/**
+ * How wide the person dragged a sidebar — the pure half, so the clamp is testable without a
+ * pointer.
+ *
+ * Owner, 2026-09-24: *"the cb filetree sidebars should allow grabbing their right edge and
+ * dragging to resize them like in vscode … in collections app I should be able to drag it to
+ * the right to see the full file names or shrink it by moving it to the left."*
+ *
+ * Remembered under a key the APP names (`FilterRail`'s `resizeKey`), for the reason
+ * `media/stageResize.ts` keys its heights: two rails on one origin must not resize each other.
+ * Announced through `preferenceSync`, so an app that keeps preferences on its server carries
+ * the width to every device like the rest of them.
+ */
+import { announcePreference } from '../media-gallery/preferenceBus.js';
+
+/** Narrower than this and a row is an icon and an ellipsis. */
+export const MIN_RAIL_PX = 160;
+/** Wider than this and the rail is eating the page it navigates. */
+export const MAX_RAIL_PX = 640;
+
+export const clampRailWidth = (px: number): number =>
+  Math.round(Math.min(MAX_RAIL_PX, Math.max(MIN_RAIL_PX, px)));
+
+/** The remembered width, or null for "the rail's default". Wrapped: `localStorage` throws in
+ *  a sandboxed iframe and in Safari's private mode. */
+export function readRailWidth(key: string): number | null {
+  try {
+    const raw = globalThis.localStorage?.getItem(key);
+    if (raw == null) return null;
+    const stored = Number(raw);
+    return Number.isFinite(stored) && stored > 0 ? clampRailWidth(stored) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Remember it, or forget it (`null` — the double-click reset). */
+export function writeRailWidth(key: string, width: number | null): void {
+  const value = width === null ? null : String(clampRailWidth(width));
+  try {
+    if (value === null) globalThis.localStorage?.removeItem(key);
+    else globalThis.localStorage?.setItem(key, value);
+  } catch {
+    // A width that cannot be remembered is still a width that works this session.
+  }
+  announcePreference(key, value);
+}

package/src/react/media/VirtualMediaGrid.tsx

@@ -21,6 +21,10 @@ import { VirtualCardGrid, type VirtualCardGridProps } from '../VirtualCardGrid.j
  */
 export const CBGD_META_HEIGHT = 67;
 
+/** A tile with its caption turned off (`MediaGallery`'s `tileCaptions={false}`): only the
+ *  photo tile's 1px border top and bottom remain below the media box. */
+export const CBGD_BARE_TILE_HEIGHT = 2;
+
 export interface VirtualMediaGridProps
   extends Omit<VirtualCardGridProps, 'aspect' | 'cardExtraHeight'> {
   /** Media aspect ratio (height/width). Default 9/16 (landscape). */

package/src/react/media/stageResize.ts

@@ -15,6 +15,8 @@
  * thumbnails underneath" stays literally true at every point of the drag.
  */
 
+import { announcePreference } from '../media-gallery/preferenceBus.js';
+
 /** Below this the stage is a letterbox sliver — no picture, all chrome. */
 export const MIN_STAGE_PX = 180;
 
@@ -83,6 +85,7 @@ export function writeStageHeight(key: string, height: number | null): void {
   try {
     if (height === null) globalThis.localStorage?.removeItem(key);
     else globalThis.localStorage?.setItem(key, String(Math.round(height)));
+    announcePreference(key, height === null ? null : String(Math.round(height)));
   } catch {
     // A size that cannot be remembered is still a size that works this session.
   }

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

@@ -76,6 +76,7 @@ import {
   useCheckboxSelection,
 } from '../hooks/useCheckboxSelection.js';
 import { DenseGalleryDetail, DenseGalleryShell } from '../media/DenseGalleryShell.js';
+import { CBGD_BARE_TILE_HEIGHT } from '../media/VirtualMediaGrid.js';
 import { useHlsSource } from '../media/hlsSource.js';
 import {
   isRecoverableFault,
@@ -651,6 +652,7 @@ function GalleryTile({
   autoPreview,
   measure,
   stageMark,
+  caption = true,
 }: {
   item: MediaGalleryItem;
   cache: MediaCache;
@@ -663,6 +665,8 @@ function GalleryTile({
   measure?: TileMeasure;
   /** See {@link TileShell}'s `stageMark` — the label for the tile that is ON the stage. */
   stageMark?: string;
+  /** Draw the name/size/date under the picture — see {@link MediaGalleryProps.tileCaptions}. */
+  caption?: boolean;
 }) {
   /*
    * 🔴 ALWAYS wrapped, even with no selection and no drag.
@@ -686,6 +690,7 @@ function GalleryTile({
         onOpen={onOpen}
         autoPreview={autoPreview}
         measure={measure}
+        caption={caption}
       />
     </TileShell>
   );
@@ -757,12 +762,14 @@ function RawGalleryTile({
   onOpen,
   autoPreview,
   measure,
+  caption = true,
 }: {
   item: MediaGalleryItem;
   cache: MediaCache;
   onOpen: () => void;
   autoPreview?: boolean;
   measure?: TileMeasure;
+  caption?: boolean;
 }) {
   const category = galleryItemCategory(item);
   const { media } = useItemMedia(item, cache);
@@ -788,7 +795,7 @@ function RawGalleryTile({
         // whose detail view is upright, which reads as the fix not having worked.
         {...(item.orientation ? { orientation: item.orientation } : {})}
       >
-        <GalleryMeta item={item} measure={measure} />
+        {caption ? <GalleryMeta item={item} measure={measure} /> : null}
       </HoverScrubVideoThumb>
     );
   }
@@ -835,7 +842,7 @@ function RawGalleryTile({
           />
         </div>
       )}
-      <GalleryMeta item={item} measure={measure} />
+      {caption ? <GalleryMeta item={item} measure={measure} /> : null}
     </button>
   );
 }
@@ -1505,6 +1512,17 @@ export interface MediaGalleryProps {
   previewAll?: boolean;
   /** Told when the app-owned toggle changes — see {@link MediaGalleryProps.previewAll}. */
   onPreviewAllChange?: (next: boolean) => void;
+  /**
+   * The name, size and date under every tile. `false` leaves the picture alone on the card, and
+   * the row shrinks by exactly the caption's height, so more of the grid fits on screen.
+   *
+   * Owner, collections, 2026-09-21: *"I want a way to see more of the media files sometimes …
+   * add a button to toggle hiding and showing all the text under the media gallery images."*
+   * CONTROLLED by the app for the same reason `previewAll` is — the button lives in the app's
+   * own chrome. The name is still the tile's accessible label, so nothing is lost to a reader.
+   * Default `true`: every existing consumer keeps its captions.
+   */
+  tileCaptions?: boolean;
   /** 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;
@@ -1799,6 +1817,7 @@ export function MediaGallery({
   headerExtra,
   chrome = 'header',
   previewAll,
+  tileCaptions = true,
   onPreviewAllChange,
   onPreviewableChange,
   viewMode: controlledViewMode,
@@ -2577,6 +2596,7 @@ export function MediaGallery({
       <>
       {capabilityDialogs}
       <DenseGalleryDetail
+        {...(tileCaptions ? {} : { rowExtraHeight: CBGD_BARE_TILE_HEIGHT })}
         fullStage={fullStage}
         onFullStageChange={setFullStage}
         /* 🔴 A VIDEO enters browser fullscreen from its own player, so the frame must not also
@@ -3119,6 +3139,7 @@ export function MediaGallery({
               // file is the same grid, and a tile that told you its length on one screen and
               // its size on the other would be two tiles.
               measure={meta?.tileMeasure || undefined}
+              caption={tileCaptions}
               // The one tile the stage is showing. Clicking it re-selects what is already
               // open, which `select` makes a no-op change — it stays a live tile rather than
               // a dead one, because a tile you cannot press reads as broken.
@@ -3141,6 +3162,7 @@ export function MediaGallery({
         about separately. */}
     {capabilityDialogs}
     <DenseGalleryShell<MediaGalleryOrder>
+      {...(tileCaptions ? {} : { rowExtraHeight: CBGD_BARE_TILE_HEIGHT })}
       title={title}
       order={{
         value: order,
@@ -3317,6 +3339,7 @@ export function MediaGallery({
             drag={tileDrag(item)}
             autoPreview={thumbAutoplay}
             measure={meta?.tileMeasure || undefined}
+            caption={tileCaptions}
           />
         ) : null;
       }}

package/src/react/media-gallery/index.ts

@@ -59,6 +59,10 @@ export {
   writeThumbAutoplay,
   writeViewMode,
 } from './playbackPreferences.js';
+// Server-side memory for the above, for an app that opts in — see `preferenceSync.ts`.
+export { onPreferenceWrite, seedPreferences } from './preferenceSync.js';
+export { STAGE_VOLUME_KEY } from './playbackPreferences.js';
+export { FOCUS_HEIGHT_KEY, STAGE_HEIGHT_KEY } from '../media/stageResize.js';
 // The run algebra — pure, so an app that drives its own player (music's queue, roms' reel)
 // can share the shuffle bag and the wrapping stepper without mounting the gallery.
 export {

package/src/react/media-gallery/playbackPreferences.ts

@@ -29,6 +29,8 @@
  * is only the value, its labels and its storage.
  */
 
+import { announcePreference } from './preferenceBus.js';
+
 /** What happens when the item on the stage finishes. */
 export type PlaybackEndBehavior =
   /** Stop on the last frame — the browser default, and the least surprising. */
@@ -97,6 +99,7 @@ export function readPlaybackEnd(): PlaybackEndBehavior {
 export function writePlaybackEnd(behavior: PlaybackEndBehavior): void {
   try {
     globalThis.localStorage?.setItem(STORAGE_KEY, behavior);
+    announcePreference(STORAGE_KEY, behavior);
   } catch {
     // A preference that cannot be remembered is still a preference that works this session.
   }
@@ -144,6 +147,7 @@ export function readImageDwell(): number {
 export function writeImageDwell(seconds: number): void {
   try {
     globalThis.localStorage?.setItem(DWELL_KEY, String(seconds));
+    announcePreference(DWELL_KEY, String(seconds));
   } catch {
     // Unremembered is still usable this session.
   }
@@ -175,6 +179,7 @@ export function readPinStage(): boolean {
 export function writePinStage(pinned: boolean): void {
   try {
     globalThis.localStorage?.setItem(PIN_KEY, pinned ? '1' : '0');
+    announcePreference(PIN_KEY, pinned ? '1' : '0');
   } catch {
     // Unremembered is still usable this session.
   }
@@ -213,6 +218,7 @@ export function readThumbAutoplay(): boolean {
 export function writeThumbAutoplay(on: boolean): void {
   try {
     globalThis.localStorage?.setItem(THUMB_AUTOPLAY_KEY, on ? '1' : '0');
+    announcePreference(THUMB_AUTOPLAY_KEY, on ? '1' : '0');
   } catch {
     // Unremembered is still usable this session.
   }
@@ -253,6 +259,7 @@ export function readViewMode(): GalleryViewMode {
 export function writeViewMode(mode: GalleryViewMode): void {
   try {
     globalThis.localStorage?.setItem(VIEW_MODE_KEY, mode);
+    announcePreference(VIEW_MODE_KEY, mode);
   } catch {
     // Unremembered is still usable this session.
   }
@@ -350,10 +357,27 @@ export function readSessionVolume(key: string): SessionVolume | null {
 
 /** Remember it for the rest of this PAGE. Never longer — see {@link SessionVolume}. */
 export function writeSessionVolume(key: string, value: SessionVolume): void {
-  sessionVolumes.set(key, {
+  const held = writeSessionVolumeSilently(key, value);
+  // Announced for an app that keeps it longer than the page — see `preferenceSync.ts`. This
+  // module still never does; the owner's 09-14 rule holds for every app that does not opt in.
+  announcePreference(key, JSON.stringify(held));
+}
+
+/**
+ * The same write without the announcement — what `seedPreferences` uses to put a stored level
+ * back, so restoring it is never reported as the person changing it.
+ */
+export function writeSessionVolumeSilently(key: string, value: SessionVolume): SessionVolume {
+  const held = {
     // Clamped here rather than at every call site: this lands on `HTMLMediaElement.volume`,
     // which throws `IndexSizeError` outside 0–1.
     volume: Math.min(1, Math.max(0, value.volume)),
     muted: value.muted,
-  });
+  };
+  sessionVolumes.set(key, held);
+  return { ...held };
 }
+
+/** Is `key` one of the in-memory session volumes rather than a `localStorage` preference? */
+export const isSessionVolumeKey = (key: string): boolean =>
+  key === STAGE_VOLUME_KEY || key === PLAYER_VOLUME_KEY;

package/src/react/media-gallery/preferenceBus.ts

@@ -0,0 +1,28 @@
+/**
+ * The listener set behind `preferenceSync.ts`, in a module of its own so that the writers
+ * (`playbackPreferences.ts`, `media/stageResize.ts`) and the seeder can both import it
+ * without importing each other. See `preferenceSync.ts` for what it is for.
+ */
+export type PreferenceListener = (key: string, value: string | null) => void;
+
+const listeners = new Set<PreferenceListener>();
+
+/** Hear every preference this package remembers. Returns the unsubscribe. */
+export function onPreferenceWrite(listener: PreferenceListener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Called by each writer in this package — not part of the public surface. */
+export function announcePreference(key: string, value: string | null): void {
+  for (const listener of listeners) {
+    try {
+      listener(key, value);
+    } catch {
+      // A listener that throws must not take a volume slider down with it.
+    }
+  }
+}
+

package/src/react/media-gallery/preferenceSync.spec.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { readStageHeight, STAGE_HEIGHT_KEY, writeStageHeight } from '../media/stageResize.js';
+import {
+  readSessionVolume,
+  readThumbAutoplay,
+  STAGE_VOLUME_KEY,
+  writeSessionVolume,
+  writeThumbAutoplay,
+} from './playbackPreferences.js';
+import { onPreferenceWrite, seedPreferences } from './preferenceSync.js';
+
+/**
+ * 🔴 The seam an app uses to keep these preferences on its SERVER — owner, collections,
+ * 2026-09-21: *"remember my settings in the db and utilize them when I sign back in on any
+ * device."* Three promises, each of which fails silently if broken:
+ *
+ *   · every writer ANNOUNCES — a writer that forgets is a setting that quietly stays on one device
+ *   · a seed lands where the READER reads — or the restore is a no-op nobody sees
+ *   · a seed announces NOTHING — or signing in writes every stored value straight back
+ */
+const heard: [string, string | null][] = [];
+let stop: (() => void) | null = null;
+const listen = (): void => {
+  stop = onPreferenceWrite((key, value) => heard.push([key, value]));
+};
+afterEach(() => {
+  stop?.();
+  stop = null;
+  heard.length = 0;
+  globalThis.localStorage?.clear();
+});
+
+describe('preferenceSync', () => {
+  test('the writers announce what they remembered', () => {
+    listen();
+    writeThumbAutoplay(true);
+    writeStageHeight(STAGE_HEIGHT_KEY, 512.4);
+    writeSessionVolume(STAGE_VOLUME_KEY, { volume: 0.4, muted: false });
+    writeStageHeight(STAGE_HEIGHT_KEY, null);
+    expect(heard).toEqual([
+      ['cbmg:thumb-autoplay', '1'],
+      [STAGE_HEIGHT_KEY, '512'],
+      [STAGE_VOLUME_KEY, '{"volume":0.4,"muted":false}'],
+      [STAGE_HEIGHT_KEY, null],
+    ]);
+  });
+
+  test('a seed lands where each reader reads it, and announces nothing', () => {
+    listen();
+    seedPreferences({
+      'cbmg:thumb-autoplay': '1',
+      [STAGE_HEIGHT_KEY]: '640',
+      [STAGE_VOLUME_KEY]: '{"volume":0.25,"muted":false}',
+    });
+    expect(readThumbAutoplay()).toBe(true);
+    expect(readStageHeight(STAGE_HEIGHT_KEY)).toBe(640);
+    expect(readSessionVolume(STAGE_VOLUME_KEY)).toEqual({ volume: 0.25, muted: false });
+    expect(heard).toEqual([]);
+  });
+
+  test('a malformed stored volume is ignored, and null forgets a stored value', () => {
+    writeStageHeight(STAGE_HEIGHT_KEY, 700);
+    seedPreferences({ [STAGE_VOLUME_KEY]: 'not json', [STAGE_HEIGHT_KEY]: null });
+    expect(readStageHeight(STAGE_HEIGHT_KEY)).toBeNull();
+  });
+
+  test('an app that never subscribes changes nothing — the listener is gone after unsubscribe', () => {
+    listen();
+    stop?.();
+    stop = null;
+    writeThumbAutoplay(false);
+    expect(heard).toEqual([]);
+  });
+});

package/src/react/media-gallery/preferenceSync.ts

@@ -0,0 +1,60 @@
+/**
+ * A viewer preference that follows the PERSON, not the browser — the seam an app opts into.
+ *
+ * Every preference in this package is remembered on one device: `localStorage` for ways of
+ * working (the stage height, preview-all, the end behaviour), page memory for loudness
+ * (`playbackPreferences.ts` → `SessionVolume`). That is the right default for a shared
+ * component, because only the APP knows who is signed in and where it could keep a value.
+ *
+ * Owner, collections, 2026-09-21: *"remember my settings in the db and utilize them when I
+ * sign back in on any device … It should use debouncing for settings that may change a lot."*
+ *
+ * So this module is two verbs and nothing else:
+ *
+ *   · {@link onPreferenceWrite} — every writer in this package announces what it just
+ *     remembered, as `(key, value)`. An app that wants server-side memory listens, filters
+ *     the keys it cares about, and debounces its own writes (a volume slider announces on
+ *     every tick; the debounce is the app's, because the app owns the request).
+ *   · {@link seedPreferences} — the app hands back what it stored, once it knows who is
+ *     signed in, and each value lands in the SAME place the package reads it from. Seeding
+ *     announces nothing, so a restore never echoes back to the server as a change.
+ *
+ * 🔴 An app that never calls either behaves exactly as before — nothing here writes on its
+ * own, and a listener set with no listeners is a loop over nothing.
+ *
+ * Values are strings (or `null` for "forget it"), because that is what the underlying stores
+ * hold; a session volume travels as its JSON, `{"volume":0.4,"muted":false}`.
+ */
+import { isSessionVolumeKey, writeSessionVolumeSilently } from './playbackPreferences.js';
+
+export { onPreferenceWrite, type PreferenceListener } from './preferenceBus.js';
+
+/**
+ * Put stored values back where this package reads them from, without announcing them.
+ *
+ * A session-volume key goes into page memory (where every player reads its opening level);
+ * everything else goes into `localStorage` under the same key its reader uses. `null`
+ * forgets. Wrapped for the reason every storage access here is — `localStorage` throws in a
+ * sandboxed iframe and Safari's private mode.
+ */
+export function seedPreferences(values: Readonly<Record<string, string | null>>): void {
+  for (const [key, value] of Object.entries(values)) {
+    if (isSessionVolumeKey(key)) {
+      if (value === null) continue;
+      try {
+        const parsed = JSON.parse(value) as { volume?: unknown; muted?: unknown };
+        if (typeof parsed.volume === 'number' && typeof parsed.muted === 'boolean')
+          writeSessionVolumeSilently(key, { volume: parsed.volume, muted: parsed.muted });
+      } catch {
+        // A malformed stored volume is no stored volume.
+      }
+      continue;
+    }
+    try {
+      if (value === null) globalThis.localStorage?.removeItem(key);
+      else globalThis.localStorage?.setItem(key, value);
+    } catch {
+      // Unremembered is still usable this session.
+    }
+  }
+}

package/src/styles-areas/filter-rail.css

@@ -18,7 +18,7 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 32 candidate(s).
+ * 33 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
@@ -30,4 +30,4 @@
 @source inline("opacity-100 outline-2 outline-accent outline-dashed outline-offset-[-2px] pb-1");
 @source inline("place-items-center pointer-coarse:[&_button]:min-h-11 pointer-coarse:[&_button]:min-w-11");
 @source inline("pointer-coarse:[&_button]:size-11 pt-1 self-stretch shadow-[inset_3px_0_0_0_var(--accent)] w-14");
-@source inline("w-56");
+@source inline("w-3 w-56");