feat(B.1 #11): versioned settings schema with forward migration

Adds src/lib/utils/settingsMigrations.ts exposing
loadSettingsWithMigration() / saveSettingsWithVersion() around a
{version, data} envelope in localStorage["kon_settings"]. The
migration chain is indexed by destination version so adding a v2
is one MIGRATIONS[2] = (prev) => next entry away from working.

Legacy bare-object settings blobs are treated as v0 and folded into
v1 identically to before — no user-facing reset — but an unreadable
blob now surfaces a single Settings reset toast instead of silently
dropping data.

Covers Handy #602 ('settings reset on update') and unblocks the
other B.2/B.3 SettingsState additions listed in
docs/whisper-ecosystem/workstream-B.md: every subsequent field
lands behind a MIGRATIONS step, so older Kon builds stay readable.

Co-authored-by: jars <jakejars@users.noreply.github.com>

src/lib/utils/settingsMigrations.ts

@@ -0,0 +1,134 @@
+/**
+ * Forward-compatible, versioned settings migration.
+ *
+ * Historically, `localStorage["kon_settings"]` was a bare JSON object
+ * (whatever `SettingsState` looked like at write time). That shape
+ * tolerates new fields cleanly — spread over `defaults` — but does not
+ * survive:
+ *   - renaming a field, even with a trivial default mapping
+ *   - a type change on an existing field
+ *   - a settings reset the user explicitly did not ask for (Handy #602)
+ *
+ * Versioned migrations fix all three. Every schema change bumps the
+ * version constant and lands a `(from, to)` step that takes the stored
+ * raw blob (or its previous-version transform) and returns the
+ * next-version shape. `loadSettingsWithMigration` walks the chain
+ * until it reaches `CURRENT_SETTINGS_VERSION`.
+ *
+ * Covers docs/whisper-ecosystem/brief.md item #11.
+ */
+
+import { parseStoredJson } from "$lib/utils/storage";
+
+export const CURRENT_SETTINGS_VERSION = 1;
+
+/** Envelope written to localStorage. The raw blob is always kept
+ *  separately so a downgrade (user jumps to an older Kon build) can
+ *  still read v1 data even after we've bumped to v2. */
+export interface VersionedSettings<T> {
+  version: number;
+  data: T;
+}
+
+export type MigrationStep = (prev: unknown) => unknown;
+
+/**
+ * The migration chain. Add an entry per schema change.
+ *
+ * Each step is indexed by its destination version — MIGRATIONS[2] is
+ * the function that takes v1 data and returns v2 data. To add v2:
+ *
+ *   MIGRATIONS[2] = (prev) => ({ ...(prev as object), newField: 42 });
+ *
+ * Keep the steps pure — they run on load, every boot.
+ */
+export const MIGRATIONS: Record<number, MigrationStep> = {
+  // v0 -> v1: fold a raw bare-object blob (pre-versioning) into the
+  // versioned envelope. Spreading over the caller's `defaults` is the
+  // caller's job; this step just preserves whatever keys were there.
+  1: (prev) => (prev && typeof prev === "object" ? prev : {}),
+};
+
+function isVersionedEnvelope(raw: unknown): raw is VersionedSettings<unknown> {
+  return !!raw
+    && typeof raw === "object"
+    && "version" in (raw as Record<string, unknown>)
+    && "data" in (raw as Record<string, unknown>)
+    && typeof (raw as Record<string, unknown>).version === "number";
+}
+
+/**
+ * Read `localStorage[key]`, run the migration chain, and return the
+ * data blob at the current schema version. Callers then spread it
+ * over their `defaults` to produce a full `SettingsState`.
+ *
+ * Corrupt / unparseable input returns `null` — caller falls back to
+ * defaults.
+ */
+export function loadSettingsWithMigration<T>(key: string): T | null {
+  if (typeof localStorage === "undefined") return null;
+  const raw = localStorage.getItem(key);
+  if (!raw) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  let version: number;
+  let data: unknown;
+
+  if (isVersionedEnvelope(parsed)) {
+    version = parsed.version;
+    data = parsed.data;
+  } else {
+    version = 0;
+    data = parsed;
+  }
+
+  // Apply each migration step from (version + 1) up to the current
+  // schema version. A missing step between two known versions is a
+  // programming error — we warn and return null so the caller falls
+  // back to defaults instead of silently skipping.
+  for (let v = version + 1; v <= CURRENT_SETTINGS_VERSION; v++) {
+    const step = MIGRATIONS[v];
+    if (!step) {
+      console.warn(
+        `settingsMigrations: missing step to v${v} (loaded v${version}, target v${CURRENT_SETTINGS_VERSION})`,
+      );
+      return null;
+    }
+    data = step(data);
+  }
+
+  return data as T;
+}
+
+/**
+ * Serialise the current settings object into a versioned envelope and
+ * write it to localStorage. Idempotent — writing the same data twice
+ * produces the same bytes.
+ */
+export function saveSettingsWithVersion<T>(key: string, data: T): void {
+  if (typeof localStorage === "undefined") return;
+  const envelope: VersionedSettings<T> = {
+    version: CURRENT_SETTINGS_VERSION,
+    data,
+  };
+  try {
+    localStorage.setItem(key, JSON.stringify(envelope));
+  } catch {
+    // Quota exceeded / private-mode localStorage — drop the write
+    // rather than throwing into the UI. Settings are regenerated from
+    // memory on next save, or from defaults on next boot.
+  }
+}
+
+/**
+ * Back-compat shim: older call sites used `parseStoredJson` directly.
+ * When a caller hasn't migrated yet, they can keep using this for
+ * non-versioned blobs without disturbing the settings schema.
+ */
+export { parseStoredJson };