cursedbelt 5.7.2 → 5.8.0

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");