@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/shared/lib/schedule/parse.ts

@@ -0,0 +1,303 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Schedule-expression parsing, shared by the modal (inline validation and the
+ * "next run" preview) and the server runtime (when the next fire is due).
+ *
+ * Two grammars, both deliberately small:
+ *
+ * - `every` — a duration: `30s`, `5m`, `1h30m`, `2d`, `1w`, and the human
+ *   spellings `5 mins`, `2 hours`, `1 day`. Compact units may be concatenated
+ *   (`1h30m`); a bare number means minutes.
+ * - `cron`  — 5 fields (`min hour dom month dow`) with `*`, `N`, `a-b`,
+ *   `a,b,c`, star-slash-n and `a-b/n`. Day-of-week is 0-7, both 0 and 7 being
+ *   Sunday.
+ *   When BOTH day-of-month and day-of-week are restricted, a day matches if
+ *   either does — Vixie cron's rule, which is what every other scheduler's
+ *   users expect and what a naive AND would silently get wrong.
+ *
+ * `nextCronOccurrence` walks DAYS rather than minutes: a `0 0 29 2 *` (Feb 29)
+ * is 1461 minutes-free day steps away, while a minute walk would be 2.1 M
+ * iterations. Months are skipped whole when the month field excludes them.
+ */
+
+import type { ScheduleKind } from '@/shared/types/schedule';
+
+/** Shortest interval the runtime can honour: it ticks once a minute. */
+export const MIN_INTERVAL_MS = 60_000;
+
+
+const UNIT_MS: Record<string, number> = {
+  s: 1_000,
+  sec: 1_000,
+  secs: 1_000,
+  second: 1_000,
+  seconds: 1_000,
+  m: 60_000,
+  min: 60_000,
+  mins: 60_000,
+  minute: 60_000,
+  minutes: 60_000,
+  h: 3_600_000,
+  hr: 3_600_000,
+  hrs: 3_600_000,
+  hour: 3_600_000,
+  hours: 3_600_000,
+  d: 86_400_000,
+  day: 86_400_000,
+  days: 86_400_000,
+  w: 604_800_000,
+  week: 604_800_000,
+  weeks: 604_800_000,
+};
+
+/**
+ * Parse an interval expression to milliseconds, or null when it is not one.
+ *
+ * Accepts the compact and the spaced spelling, mixed: `1h30m`, `1 h 30 m`,
+ * `5 mins`, `2 days`. A bare number is minutes, which is what the modal's
+ * placeholder implies.
+ */
+export function parseInterval(spec: string): number | null {
+  const text = spec.trim().toLowerCase();
+  if (!text) return null;
+  if (/^\d+(\.\d+)?$/.test(text)) {
+    const minutes = Number(text);
+    return minutes > 0 ? Math.round(minutes * 60_000) : null;
+  }
+  const parts = text.match(/(\d+(?:\.\d+)?)\s*([a-z]+)/g);
+  if (!parts) return null;
+  // The whole string must be consumed by unit parts, or `5m x` would parse.
+  const consumed = parts.join('').replace(/\s+/g, '');
+  if (consumed.length !== text.replace(/\s+/g, '').length) return null;
+  let total = 0;
+  for (const part of parts) {
+    const match = part.match(/^(\d+(?:\.\d+)?)\s*([a-z]+)$/);
+    if (!match) return null;
+    const unit = UNIT_MS[match[2]];
+    if (!unit) return null;
+    total += Number(match[1]) * unit;
+  }
+  return total > 0 ? Math.round(total) : null;
+}
+
+export interface CronFields {
+  minutes: number[];
+  hours: number[];
+  daysOfMonth: number[];
+  months: number[];
+  daysOfWeek: number[];
+  /** True when the field was written `*` — the OR rule keys off this. */
+  domRestricted: boolean;
+  dowRestricted: boolean;
+}
+
+const CRON_BOUNDS: [number, number][] = [
+  [0, 59], // minute
+  [0, 23], // hour
+  [1, 31], // day of month
+  [1, 12], // month
+  [0, 7], // day of week
+];
+
+function parseCronField(field: string, min: number, max: number): number[] | null {
+  const values = new Set<number>();
+  for (const chunk of field.split(',')) {
+    const [rangePart, stepPart] = chunk.split('/');
+    const step = stepPart === undefined ? 1 : Number(stepPart);
+    if (!Number.isInteger(step) || step < 1) return null;
+
+    let start: number;
+    let end: number;
+    if (rangePart === '*') {
+      start = min;
+      end = max;
+    } else if (rangePart.includes('-')) {
+      const [a, b] = rangePart.split('-');
+      start = Number(a);
+      end = Number(b);
+    } else {
+      start = Number(rangePart);
+      // `5/15` means "from 5, every 15" — cron's own meaning.
+      end = stepPart === undefined ? start : max;
+    }
+    if (!Number.isInteger(start) || !Number.isInteger(end)) return null;
+    if (start < min || end > max || start > end) return null;
+    for (let value = start; value <= end; value += step) values.add(value);
+  }
+  return values.size ? [...values].sort((a, b) => a - b) : null;
+}
+
+/** Parse a 5-field cron expression, or null when it is not one. */
+export function parseCron(spec: string): CronFields | null {
+  const fields = spec.trim().split(/\s+/);
+  if (fields.length !== 5) return null;
+  const parsed = fields.map((field, index) => {
+    const [min, max] = CRON_BOUNDS[index];
+    return parseCronField(field, min, max);
+  });
+  if (parsed.some((field) => field === null)) return null;
+  const [minutes, hours, daysOfMonth, months, daysOfWeek] = parsed as number[][];
+  return {
+    minutes,
+    hours,
+    daysOfMonth,
+    months,
+    // Sunday is spelled 0 or 7; fold so the match test has one value.
+    daysOfWeek: [...new Set(daysOfWeek.map((day) => (day === 7 ? 0 : day)))].sort((a, b) => a - b),
+    domRestricted: fields[2].trim() !== '*',
+    dowRestricted: fields[4].trim() !== '*',
+  };
+}
+
+function dayMatches(fields: CronFields, date: Date): boolean {
+  const dom = date.getDate();
+  const dow = date.getDay();
+  const byDom = fields.daysOfMonth.includes(dom);
+  const byDow = fields.daysOfWeek.includes(dow);
+  // Vixie cron: with both fields restricted the day matches if EITHER does.
+  if (fields.domRestricted && fields.dowRestricted) return byDom || byDow;
+  if (fields.domRestricted) return byDom;
+  if (fields.dowRestricted) return byDow;
+  return true;
+}
+
+function firstAtLeast(values: number[], floor: number): number | null {
+  for (const value of values) if (value >= floor) return value;
+  return null;
+}
+
+/**
+ * The first fire strictly after `from`, in local time. Null when the
+ * expression never matches inside the horizon (an impossible date such as
+ * `0 0 30 2 *`).
+ */
+export function nextCronOccurrence(fields: CronFields, from: Date): number | null {
+  // Cron fires on minute boundaries; the next candidate is the start of the
+  // minute after `from`, so a fire at exactly `from` is not re-scheduled.
+  const cursor = new Date(from.getTime());
+  cursor.setSeconds(0, 0);
+  cursor.setMinutes(cursor.getMinutes() + 1);
+
+  const cursorDayStart = new Date(cursor.getFullYear(), cursor.getMonth(), cursor.getDate()).getTime();
+  const horizon = new Date(cursorDayStart);
+  horizon.setFullYear(horizon.getFullYear() + 8);
+
+  // The walk advances one CALENDAR DAY at a time, and a month the month-field
+  // excludes is jumped whole. Advancing by an offset instead would land
+  // mid-month after a skip and miss the first of the month it jumped to.
+  for (let day = new Date(cursorDayStart); day.getTime() <= horizon.getTime(); ) {
+    if (!fields.months.includes(day.getMonth() + 1)) {
+      day = new Date(day.getFullYear(), day.getMonth() + 1, 1);
+      continue;
+    }
+    if (dayMatches(fields, day)) {
+      const sameDay = day.getTime() === cursorDayStart;
+      const hourFloor = sameDay ? cursor.getHours() : 0;
+      const hour = firstAtLeast(fields.hours, hourFloor);
+      if (hour !== null) {
+        const minuteFloor = sameDay && hour === cursor.getHours() ? cursor.getMinutes() : 0;
+        const minute = firstAtLeast(fields.minutes, minuteFloor);
+        if (minute !== null) {
+          return new Date(day.getFullYear(), day.getMonth(), day.getDate(), hour, minute, 0, 0).getTime();
+        }
+      }
+    }
+    day = new Date(day.getFullYear(), day.getMonth(), day.getDate() + 1);
+  }
+  return null;
+}
+
+/** Parse a `once` spec (ISO-8601 timestamp, or epoch ms). */
+export function parseOnce(spec: string): number | null {
+  const text = spec.trim();
+  if (!text) return null;
+  if (/^\d+$/.test(text)) {
+    const ms = Number(text);
+    return ms > 0 ? ms : null;
+  }
+  const ms = Date.parse(text);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+export type ScheduleValidation =
+  | { ok: true; nextRunAt: number }
+  | { ok: false; error: string };
+
+/**
+ * Validate a schedule expression and compute its first fire. The single gate
+ * both the modal (inline feedback) and the route (a stale client) use, so a
+ * row can never be written with a spec the runtime cannot schedule.
+ */
+export function validateSchedule(kind: ScheduleKind, spec: string, now = Date.now()): ScheduleValidation {
+  if (!spec.trim()) return { ok: false, error: 'Enter a schedule.' };
+  if (kind === 'once') {
+    const at = parseOnce(spec);
+    if (at === null) return { ok: false, error: 'Use an ISO timestamp, e.g. 2026-10-01T09:00.' };
+    if (at <= now) return { ok: false, error: 'That time is already in the past.' };
+    return { ok: true, nextRunAt: at };
+  }
+  if (kind === 'every') {
+    const interval = parseInterval(spec);
+    if (interval === null) return { ok: false, error: 'Use a duration, e.g. 30m, 1h30m, 2 days.' };
+    if (interval < MIN_INTERVAL_MS) return { ok: false, error: 'The shortest interval is 1 minute.' };
+    return { ok: true, nextRunAt: now + interval };
+  }
+  const fields = parseCron(spec);
+  if (!fields) {
+    return { ok: false, error: 'Use 5 fields: minute hour day-of-month month day-of-week.' };
+  }
+  const next = nextCronOccurrence(fields, new Date(now));
+  if (next === null) return { ok: false, error: 'That expression never matches a date.' };
+  return { ok: true, nextRunAt: next };
+}
+
+/**
+ * The fire after `after` for an already-validated task, or null when there is
+ * none (a spent `once`). Used by the runtime to advance a task's schedule.
+ */
+export function nextRunAfter(
+  kind: ScheduleKind,
+  spec: string,
+  after: number,
+): number | null {
+  if (kind === 'once') return null;
+  if (kind === 'every') {
+    const interval = parseInterval(spec);
+    return interval === null ? null : after + interval;
+  }
+  const fields = parseCron(spec);
+  return fields ? nextCronOccurrence(fields, new Date(after)) : null;
+}
+
+/** Human summary of a schedule for the task list and the run log. */
+export function describeSchedule(kind: ScheduleKind, spec: string): string {
+  const text = spec.trim();
+  if (kind === 'once') {
+    const at = parseOnce(text);
+    return at === null ? text : `Once at ${new Date(at).toLocaleString()}`;
+  }
+  if (kind === 'every') {
+    const interval = parseInterval(text);
+    return interval === null ? text : `Every ${formatDuration(interval)}`;
+  }
+  return `Cron ${text}`;
+}
+
+/** `90000` → `1m 30s`; the largest two units are enough to read a cadence. */
+export function formatDuration(ms: number): string {
+  const seconds = Math.round(ms / 1000);
+  const days = Math.floor(seconds / 86_400);
+  const hours = Math.floor((seconds % 86_400) / 3_600);
+  const minutes = Math.floor((seconds % 3_600) / 60);
+  const rest = seconds % 60;
+  const parts: string[] = [];
+  if (days) parts.push(`${days}d`);
+  if (hours) parts.push(`${hours}h`);
+  if (minutes) parts.push(`${minutes}m`);
+  if (rest && !days) parts.push(`${rest}s`);
+  return parts.length ? parts.join(' ') : '0s';
+}

package/src/shared/lib/settings/client.test.ts

@@ -0,0 +1,72 @@
+import { test, expect, afterAll, beforeEach } from 'bun:test';
+import {
+  primeKabmoSettings,
+  readKabmoSetting,
+  mergeKabmoSettings,
+  writeSetting,
+  writeKabmoSettings,
+} from '@/shared/lib/settings/client';
+
+const bootstrap = {
+  omp_sidebar_sort: 'A-Z',
+  desktopLayoutSizes: { sidebar: 268 },
+  omp_chamber_settings: { theme: 'paper', editorFont: 'Menlo' },
+};
+
+beforeEach(() => {
+  primeKabmoSettings(bootstrap);
+});
+
+test('reads expose top-level keys and blob keys flat', () => {
+  expect(readKabmoSetting<string>('omp_sidebar_sort')).toBe('A-Z');
+  expect(readKabmoSetting<string>('theme')).toBe('paper');
+  expect(readKabmoSetting<string>('editorFont')).toBe('Menlo');
+  expect(readKabmoSetting('absent')).toBeUndefined();
+});
+
+test('the raw blob key is not exposed as a flat key', () => {
+  expect(readKabmoSetting('omp_chamber_settings')).toBeUndefined();
+});
+
+test('readKabmoSetting accepts candidate key lists in priority order', () => {
+  expect(readKabmoSetting<string>(['missing', 'theme'])).toBe('paper');
+  expect(readKabmoSetting<string>(['theme', 'missing'])).toBe('paper');
+  expect(readKabmoSetting(['missing', 'alsoMissing'])).toBeUndefined();
+});
+
+test('mergeKabmoSettings layers only the blob, never top-level keys', () => {
+  const merged = mergeKabmoSettings({ theme: 'fallback', fontSize: 14 });
+  expect(merged.theme).toBe('paper');
+  expect(merged.fontSize).toBe(14);
+  expect((merged as Record<string, unknown>).omp_sidebar_sort).toBeUndefined();
+  expect((merged as Record<string, unknown>).desktopLayoutSizes).toBeUndefined();
+});
+
+test('writeSetting updates the snapshot so the next read sees it', () => {
+  writeSetting('omp_sidebar_sort', 'Z-A');
+  expect(readKabmoSetting<string>('omp_sidebar_sort')).toBe('Z-A');
+});
+
+test('writeKabmoSettings updates flat keys and keeps sibling blob keys', () => {
+  writeKabmoSettings({ theme: 'noir' });
+  expect(readKabmoSetting<string>('theme')).toBe('noir');
+  expect(readKabmoSetting<string>('editorFont')).toBe('Menlo');
+  expect(readKabmoSetting('omp_chamber_settings')).toBeUndefined();
+});
+
+test('a later write does not clobber previously written flat keys', () => {
+  writeSetting('showRightPanel', false);
+  writeKabmoSettings({ theme: 'noir' });
+  expect(readKabmoSetting<boolean>('showRightPanel')).toBe(false);
+  expect(readKabmoSetting<string>('theme')).toBe('noir');
+});
+
+/**
+ * The snapshot is module state shared by every suite in one `bun test`
+ * process; the last case here leaves it holding this file's fixtures. Restore
+ * the pristine (unprimed) snapshot so a later file that reads a Kabmo
+ * setting sees the default rather than the fixture.
+ */
+afterAll(() => {
+  primeKabmoSettings({});
+});

package/src/shared/lib/settings/client.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Client-side Kabmo settings. SQLite is the single source of truth: the
+ * server reads `app_settings` and injects the whole map into the page as
+ * `window.__OMP_BOOTSTRAP__.appSettings`, and every write POSTs back to
+ * `/api/settings`.
+ *
+ * There is deliberately no localStorage. An in-memory snapshot — primed once
+ * from the bootstrap — keeps reads synchronous, so a theme flip or transport
+ * change applies to the next render without waiting for a loader round-trip,
+ * while the durable copy lives in SQLite and survives a reload.
+ *
+ * Reads are flat: top-level `app_settings` keys (`omp_sidebar_sort`,
+ * `desktopLayoutSizes`, …) and the `kabmo_settings` blob (`theme`,
+ * `chatCompletionSound`, …) share one namespace, with the blob's keys overlaid.
+ *
+ * The blob key is `kabmo_settings`. The pre-rename `omp_chamber_settings` row is
+ * still read and merged BENEATH it (see `./keys`), so an upgrade keeps every
+ * stored preference; only the new key is written, so the old row drains as
+ * values are rewritten.
+ */
+
+import { LEGACY_SETTINGS_BLOB_KEY, readSettingsBlob, SETTINGS_BLOB_KEY } from '@/shared/lib/settings/keys';
+
+let snapshot: Record<string, any> | null = null;
+let settingsBlob: Record<string, any> = {};
+
+/**
+ * Prime the snapshot from the server-injected bootstrap. Call once at boot
+ * (see `main.tsx`); calling again re-primes from the same payload.
+ */
+export function primeKabmoSettings(appSettings?: Record<string, any>): void {
+  settingsBlob = readSettingsBlob(appSettings);
+  const flat = { ...(appSettings ?? {}) };
+  delete flat[SETTINGS_BLOB_KEY];
+  // The legacy row is consumed into the blob above; exposing it flat as well
+  // would make `readKabmoSetting('omp_chamber_settings')` answer with the raw
+  // map, which no caller wants and one test pins as absent.
+  delete flat[LEGACY_SETTINGS_BLOB_KEY];
+  snapshot = { ...flat, ...settingsBlob };
+}
+
+function current(appSettings?: Record<string, any>): Record<string, any> {
+  if (!snapshot) primeKabmoSettings(appSettings);
+  return snapshot ?? {};
+}
+
+/**
+ * Resolve one setting (or the first present of several candidate keys) from the
+ * snapshot. Returns `undefined` when no candidate is present.
+ */
+export function readKabmoSetting<T>(
+  keys: string | string[],
+  appSettings?: Record<string, any>,
+): T | undefined {
+  const keyList = Array.isArray(keys) ? keys : [keys];
+  const source = current(appSettings);
+  for (const key of keyList) {
+    if (source[key] !== undefined) return source[key] as T;
+  }
+  return undefined;
+}
+
+/**
+ * `defaults` layered under the settings blob only. Used to seed the
+ * settings-editor state, so unrelated top-level keys must not leak in and get
+ * written back into the blob.
+ */
+export function mergeKabmoSettings<T extends Record<string, any>>(
+  defaults: T,
+  appSettings?: Record<string, any>,
+): T {
+  current(appSettings);
+  return { ...defaults, ...settingsBlob };
+}
+
+/** Write one top-level `app_settings` key: snapshot first, then SQLite. */
+export function writeSetting(key: string, value: unknown): void {
+  snapshot = { ...current(), [key]: value };
+  sendSettings({ [key]: value });
+}
+
+/**
+ * Write a patch of Kabmo-settings keys (`theme`, `chatCompletionSound`, …). The
+ * snapshot exposes the blob's keys flat, so an edit applies to the next read
+ * without a round-trip.
+ *
+ * Only the patch travels, and the server merges it into the stored blob. The
+ * whole local blob must not be republished: this page's copy was taken when it
+ * booted, so a tab left open across an external change (a second tab, a direct
+ * API call) would overwrite the newer keys with its own stale ones on the next
+ * unrelated write — which is exactly how a theme chosen elsewhere reverted.
+ */
+export function writeKabmoSettings(patch: Record<string, any>): void {
+  settingsBlob = { ...settingsBlob, ...patch };
+  snapshot = { ...current(), ...patch };
+  sendSettings({ [SETTINGS_BLOB_KEY]: patch });
+}
+
+/**
+ * @deprecated Use `primeKabmoSettings`.
+ *
+ * The aliases exist because these four names are what the client's own modules
+ * and a plugin's `useSessionState` callers import; they resolve to the same
+ * snapshot, never to a second copy.
+ */
+export const primeChamberSettings = primeKabmoSettings;
+
+/** @deprecated Use `readKabmoSetting`. */
+export const readChamberSetting = readKabmoSetting;
+
+/** @deprecated Use `mergeKabmoSettings`. */
+export const mergeChamberSettings = mergeKabmoSettings;
+
+/** @deprecated Use `writeKabmoSettings`. */
+export const writeChamberSettings = writeKabmoSettings;
+
+/** POST a settings patch to SQLite. Fire-and-forget; failures are non-fatal. */
+function sendSettings(patch: Record<string, unknown>): void {
+  fetch('/api/settings', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(patch),
+  }).catch(() => {});
+}

package/src/shared/lib/settings/diff.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from 'bun:test';
+
+import { diffSettings } from '@/shared/lib/settings/diff';
+
+describe('diffSettings', () => {
+  test('an object patch persists only the keys it actually changed', () => {
+    const prev = { theme: 'paper', soundAlerts: true, editorFont: 'Fira Code' };
+    const next = { ...prev, theme: 'nord-dark' };
+    expect(diffSettings(prev, next, { theme: 'nord-dark' })).toEqual({ theme: 'nord-dark' });
+  });
+
+  test('a no-op patch persists nothing', () => {
+    const prev = { theme: 'paper', soundAlerts: true };
+    expect(diffSettings(prev, { ...prev }, { theme: 'paper' })).toEqual({});
+  });
+
+  test('an updater function persists every key whose value it moved', () => {
+    const prev = { keybindingSend: 'Enter', keybindingNewLine: 'Shift + Enter' };
+    const next = { keybindingSend: 'Ctrl / Cmd + Enter', keybindingNewLine: 'Enter' };
+    expect(diffSettings(prev, next, (state) => ({ ...state, ...next }))).toEqual(next);
+  });
+
+  test('an unrelated update never republishes the theme it read', () => {
+    // The regression this exists for: a tab that booted on `paper` toggling an
+    // unrelated switch in a settings modal whose snapshot predates an external
+    // theme change must not write `theme` back.
+    const prev = { theme: 'paper', chatCompletionSound: true };
+    const patch = { chatCompletionSound: false };
+    expect(diffSettings(prev, { ...prev, ...patch }, patch)).toEqual({ chatCompletionSound: false });
+  });
+});

package/src/shared/lib/settings/diff.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The subset of a settings update that should be persisted.
+ *
+ * The settings modal keeps a full `SettingsState` snapshot from the moment it
+ * opened and hands every edit to one writer. Writing the whole object back
+ * republishes values the user never touched, from a snapshot that may be older
+ * than what another writer (a second tab, an API call) has since stored — the
+ * stale copy wins purely because it was written last.
+ *
+ * A key is persisted only when the update changed it:
+ *
+ * - **Object patch** — the keys it names, but only those whose value actually
+ *   differs, so a no-op re-render does not touch the row.
+ * - **Updater function** — every key whose value differs between `prev` and
+ *   `next`; the function's own intent is not inspectable, so the diff is.
+ *
+ * Values are compared by identity, which is what `SettingsState` holds: strings,
+ * numbers and booleans. A nested object would compare by reference and be
+ * reported as changed — acceptable here, and better than dropping a real edit.
+ */
+export function diffSettings<T extends Record<string, any>>(
+  prev: T,
+  next: T,
+  update: Partial<T> | ((prev: T) => T),
+): Partial<T> {
+  const patch: Partial<T> = {};
+  const keys = typeof update === 'function' ? (Object.keys(next) as (keyof T)[]) : (Object.keys(update) as (keyof T)[]);
+  for (const key of keys) {
+    if (next[key] !== prev[key]) patch[key] = next[key];
+  }
+  return patch;
+}

package/src/shared/lib/settings/keys.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `app_settings` keys that carry Kabmo's own preferences.
+ *
+ * Two spellings exist for the settings blob, and the split is deliberate:
+ *
+ * - `kabmo_settings` is the key every writer uses now.
+ * - `omp_chamber_settings` is the key installs wrote before the rename. It is
+ *   still READ, and its keys are merged UNDER the new blob, so an install that
+ *   upgrades keeps its theme, transport, keybindings and every other preference
+ *   without a migration pass that could fail halfway. Nothing writes it any
+ *   more, so it drains as each key is rewritten.
+ *
+ * The merge order is the whole contract: the new blob wins on a shared key, so
+ * a preference changed after the upgrade is not reverted by a stale legacy row.
+ *
+ * This module has no imports on purpose — the client, the SSR shell and the
+ * server routes all resolve the same two strings through it.
+ */
+
+/** The blob every writer uses. */
+export const SETTINGS_BLOB_KEY = 'kabmo_settings';
+
+/** The pre-rename blob, read as a fallback and never written. */
+export const LEGACY_SETTINGS_BLOB_KEY = 'omp_chamber_settings';
+
+/**
+ * Read the blob from a flat `app_settings` map, with the legacy blob beneath it.
+ *
+ * Both blobs are plain objects of preference keys, so the merge is per KEY
+ * rather than per blob: an install that predates the rename has every key in
+ * the legacy row and none in the new one, and a partial upgrade can have some
+ * of each.
+ */
+export function readSettingsBlob(appSettings?: Record<string, unknown> | null): Record<string, unknown> {
+  const legacy = appSettings?.[LEGACY_SETTINGS_BLOB_KEY];
+  const current = appSettings?.[SETTINGS_BLOB_KEY];
+  return {
+    ...(isPlainRecord(legacy) ? legacy : {}),
+    ...(isPlainRecord(current) ? current : {}),
+  };
+}
+
+/** A JSON object that is not an array — the shape both blobs are written as. */
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}