@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/save/codec.js

@@ -0,0 +1,169 @@
+/**
+ * Save envelope, the typed-array JSON codec and the export/import string codec.
+ *
+ * Stored value: JSON `{ "v": <version>, "t": <savedAt ms>, "d": <data> }`.
+ * Export string: `TC1.<game>.<checksum>.<base64url(envelope JSON)>`. The checksum
+ * (FNV-1a, hex) catches truncated copy-paste; it is not tamper protection.
+ *
+ * Typed arrays inside the data are stored as `{ "$b": <base64url bytes>, "$t"?: <kind> }`
+ * (`$t` omitted for `Uint8Array`) by `saveReplacer` and turned back by `saveReviver`, so a
+ * tilemap or a voxel chunk never goes through a JSON number array. Bytes are in platform byte
+ * order (little-endian everywhere WebGPU runs). A plain object of the player's data that has
+ * its own `$b` key is escaped as `$$b` (one more `$` per level) and unescaped on load.
+ */
+export function isEnvelope(x) {
+    if (typeof x !== 'object' || x === null)
+        return false;
+    const e = x;
+    return typeof e.v === 'number' && Number.isInteger(e.v) && typeof e.t === 'number' && 'd' in e;
+}
+/** 32-bit FNV-1a over UTF-16 code units, as 8 hex chars. */
+export function fnv1a(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+// ---- base64url over bytes ----
+const CHUNK = 0x2000;
+function bytesToBase64Url(bytes) {
+    let bin = '';
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        bin += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64UrlToBytes(b64) {
+    const std = b64.replace(/-/g, '+').replace(/_/g, '/');
+    const bin = atob(std + '='.repeat((4 - (std.length % 4)) % 4));
+    const out = new Uint8Array(new ArrayBuffer(bin.length));
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function toBase64Url(text) {
+    return bytesToBase64Url(new TextEncoder().encode(text));
+}
+function fromBase64Url(b64) {
+    return new TextDecoder('utf-8', { fatal: true }).decode(base64UrlToBytes(b64));
+}
+/** Typed-array kind → constructor. Internal: `schema.ts` and the tests import it from here. */
+export const TYPED_KIND_CTORS = {
+    u8: Uint8Array,
+    u16: Uint16Array,
+    u32: Uint32Array,
+    i8: Int8Array,
+    i16: Int16Array,
+    i32: Int32Array,
+    f32: Float32Array,
+    f64: Float64Array,
+};
+const KIND_OF = new Map(Object.keys(TYPED_KIND_CTORS).map((k) => [TYPED_KIND_CTORS[k], k]));
+/** The tag kind for `value` if it is one of the eight supported typed arrays, else null. */
+export function typedKindOf(value) {
+    if (!ArrayBuffer.isView(value))
+        return null;
+    return KIND_OF.get(value.constructor) ?? null;
+}
+const ESCAPED_KEY = /^\$+b$/;
+function isPlainObject(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * `JSON.stringify` replacer: typed arrays become `{ $b, $t? }`; a plain object with a key
+ * matching `/^\$+b$/` gets that key prefixed with one more `$`.
+ */
+export function saveReplacer(_key, value) {
+    const kind = typedKindOf(value);
+    if (kind !== null) {
+        const view = value;
+        const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+        const b = bytesToBase64Url(bytes);
+        return kind === 'u8' ? { $b: b } : { $b: b, $t: kind };
+    }
+    if (isPlainObject(value)) {
+        const keys = Object.keys(value);
+        if (keys.some((k) => ESCAPED_KEY.test(k))) {
+            const out = {};
+            for (const k of keys)
+                out[ESCAPED_KEY.test(k) ? `$${k}` : k] = value[k];
+            return out;
+        }
+    }
+    return value;
+}
+function isTag(v) {
+    if (typeof v.$b !== 'string')
+        return false;
+    const keys = Object.keys(v);
+    if (keys.length === 1)
+        return true;
+    return keys.length === 2 && typeof v.$t === 'string' && v.$t in TYPED_KIND_CTORS;
+}
+/** `JSON.parse` reviver undoing `saveReplacer`. Bad tags (damaged base64) are left as objects. */
+export function saveReviver(_key, value) {
+    if (!isPlainObject(value))
+        return value;
+    if (isTag(value)) {
+        let bytes;
+        try {
+            bytes = base64UrlToBytes(value.$b);
+        }
+        catch {
+            return value;
+        }
+        const kind = value.$t ?? 'u8';
+        const Ctor = TYPED_KIND_CTORS[kind];
+        if (bytes.byteLength % Ctor.BYTES_PER_ELEMENT !== 0)
+            return value;
+        if (kind === 'u8')
+            return bytes;
+        return new Ctor(bytes.buffer, 0, bytes.byteLength / Ctor.BYTES_PER_ELEMENT);
+    }
+    const keys = Object.keys(value);
+    if (keys.some((k) => k.length > 2 && ESCAPED_KEY.test(k))) {
+        const out = {};
+        for (const k of keys)
+            out[k.length > 2 && ESCAPED_KEY.test(k) ? k.slice(1) : k] = value[k];
+        return out;
+    }
+    return value;
+}
+// ---- export string ----
+const PREFIX = 'TC1';
+export function encodeExport(game, env) {
+    const json = JSON.stringify(env, saveReplacer);
+    return `${PREFIX}.${game}.${fnv1a(json)}.${toBase64Url(json)}`;
+}
+export function decodeExport(game, text) {
+    const parts = text.trim().split('.');
+    if (parts.length !== 4 || parts[0] !== PREFIX)
+        return { ok: false, error: 'not a save string' };
+    const [, g, sum, body] = parts;
+    if (g !== game)
+        return { ok: false, error: `save belongs to "${g}", not "${game}"` };
+    let json;
+    try {
+        json = fromBase64Url(body);
+    }
+    catch {
+        return { ok: false, error: 'save string is damaged (bad encoding)' };
+    }
+    if (fnv1a(json) !== sum)
+        return { ok: false, error: 'save string is damaged (checksum)' };
+    let parsed;
+    try {
+        parsed = JSON.parse(json, saveReviver);
+    }
+    catch {
+        return { ok: false, error: 'save string is damaged (bad JSON)' };
+    }
+    if (!isEnvelope(parsed))
+        return { ok: false, error: 'save string has no version envelope' };
+    return { ok: true, envelope: parsed };
+}

package/dist/save/index.d.ts

@@ -0,0 +1,8 @@
+export { decodeExport, encodeExport, fnv1a, saveReplacer, saveReviver, type TypedArrayOf, type TypedKind, typedKindOf, } from './codec.js';
+export { createJournal, type Journal, type JournalOptions } from './journal.js';
+export { assertMigrationChain, type Migration, MigrationError, type Migrations, runMigrations, } from './migrate.js';
+export { type Infer, type NumberOptions, type Schema, s } from './schema.js';
+export { type BindTarget, createSettingsStore, type SettingsStore, type SettingsStoreOptions, } from './settings.js';
+export { createSlotManager, type SlotInfo, type SlotManager, type SlotManagerOptions, slotName, } from './slots.js';
+export { isQuotaError, MemoryStorage, probeStorage, type StorageLike } from './storage.js';
+export { createSaveStore, type ImportResult, type LoadResult, listSlots, type SaveStatus, type SaveStore, type SaveStoreOptions, type SlotMeta, type StoredMeta, saveKey, } from './store.js';

package/dist/save/index.js

@@ -0,0 +1,8 @@
+export { decodeExport, encodeExport, fnv1a, saveReplacer, saveReviver, typedKindOf, } from './codec.js';
+export { createJournal } from './journal.js';
+export { assertMigrationChain, MigrationError, runMigrations, } from './migrate.js';
+export { s } from './schema.js';
+export { createSettingsStore, } from './settings.js';
+export { createSlotManager, slotName, } from './slots.js';
+export { isQuotaError, MemoryStorage, probeStorage } from './storage.js';
+export { createSaveStore, listSlots, saveKey, } from './store.js';

package/dist/save/journal.d.ts

@@ -0,0 +1,24 @@
+import type { SaveStore } from './store.js';
+export interface JournalOptions {
+    /** Most undo steps kept. Default 50. */
+    limit?: number;
+}
+export interface Journal {
+    /** Snapshot the current data. Identical to the last snapshot: no-op. Clears redo. */
+    push(label?: string): void;
+    /** Restore the previous snapshot (the current data becomes the redo step). False when none. */
+    undo(): boolean;
+    /** Restore the next snapshot after an undo. False when none. */
+    redo(): boolean;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    /** Undo steps available. */
+    readonly length: number;
+    /** The label of the step `undo` would restore, if `push` gave one. */
+    readonly undoLabel: string | undefined;
+    /** The label of the step `redo` would restore. */
+    readonly redoLabel: string | undefined;
+    /** Drop every snapshot. */
+    clear(): void;
+}
+export declare function createJournal<T>(store: SaveStore<T>, opts?: JournalOptions): Journal;

package/dist/save/journal.js

@@ -0,0 +1,102 @@
+/**
+ * An undo journal over a save store: snapshots of the store's validated data, restored through
+ * `store.set`. Call `push()` before a change (a checkpoint) or after one (a commit); both work.
+ */
+import { saveReplacer } from './codec.js';
+export function createJournal(store, opts = {}) {
+    const limit = opts.limit ?? 50;
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new Error('journal limit must be ≥ 1');
+    const past = [];
+    const future = [];
+    // The JSON text of the current data, cached by identity (`set` replaces the reference).
+    let cachedRef;
+    let cachedText = '';
+    const currentText = () => {
+        const d = store.get();
+        if (d !== cachedRef) {
+            cachedRef = d;
+            cachedText = JSON.stringify(d, saveReplacer);
+        }
+        return cachedText;
+    };
+    const snapshot = (label) => {
+        const text = currentText();
+        const snap = { data: structuredClone(store.get()), text };
+        if (label !== undefined)
+            snap.label = label;
+        return snap;
+    };
+    const top = (stack) => stack[stack.length - 1];
+    /** Steps in `stack` not equal to the current data (the top may be a commit of it). */
+    const steps = (stack) => stack.length - (stack.length && top(stack).text === currentText() ? 1 : 0);
+    const trim = () => {
+        while (past.length > limit)
+            past.shift();
+    };
+    /** Move from one stack to the other, with the current data as the return step. */
+    const step = (from, to) => {
+        const cur = snapshot();
+        while (from.length && top(from).text === cur.text) {
+            // A commit of the current data: carry its label to the return step.
+            cur.label = from.pop().label;
+        }
+        const target = from.pop();
+        if (!target)
+            return false;
+        const toTop = top(to);
+        if (toTop && toTop.text === cur.text)
+            toTop.label ??= cur.label;
+        else
+            to.push(cur);
+        store.set(structuredClone(target.data));
+        return true;
+    };
+    return {
+        push(label) {
+            const snap = snapshot(label);
+            future.length = 0;
+            const last = top(past);
+            if (last && last.text === snap.text) {
+                if (label !== undefined)
+                    last.label = label;
+                return;
+            }
+            past.push(snap);
+            trim();
+        },
+        undo: () => step(past, future),
+        redo() {
+            const ok = step(future, past);
+            trim();
+            return ok;
+        },
+        get canUndo() {
+            return steps(past) > 0;
+        },
+        get canRedo() {
+            return steps(future) > 0;
+        },
+        get length() {
+            return steps(past);
+        },
+        get undoLabel() {
+            const t = currentText();
+            for (let i = past.length - 1; i >= 0; i--)
+                if (past[i].text !== t)
+                    return past[i].label;
+            return undefined;
+        },
+        get redoLabel() {
+            const t = currentText();
+            for (let i = future.length - 1; i >= 0; i--)
+                if (future[i].text !== t)
+                    return future[i].label;
+            return undefined;
+        },
+        clear() {
+            past.length = 0;
+            future.length = 0;
+        },
+    };
+}

package/dist/save/migrate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Migrations chain. `migrations[n]` upgrades data from version `n` to `n + 1`.
+ * Versions are positive integers; the first shipped version is 1.
+ */
+export type Migration = (data: any) => unknown;
+export type Migrations = Readonly<Record<number, Migration>>;
+export declare class MigrationError extends Error {
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    constructor(message: string, fromVersion: number, toVersion: number);
+}
+/** Throws `MigrationError` if a step is missing, the data is from the future, or a step throws. */
+export declare function runMigrations(data: unknown, fromVersion: number, toVersion: number, migrations: Migrations): unknown;
+/** Throws if the chain `1 → version` has gaps. Call once at startup or in a test. */
+export declare function assertMigrationChain(version: number, migrations: Migrations): void;

package/dist/save/migrate.js

@@ -0,0 +1,37 @@
+export class MigrationError extends Error {
+    fromVersion;
+    toVersion;
+    constructor(message, fromVersion, toVersion) {
+        super(message);
+        this.fromVersion = fromVersion;
+        this.toVersion = toVersion;
+        this.name = 'MigrationError';
+    }
+}
+/** Throws `MigrationError` if a step is missing, the data is from the future, or a step throws. */
+export function runMigrations(data, fromVersion, toVersion, migrations) {
+    if (!Number.isInteger(fromVersion) || fromVersion < 1)
+        throw new MigrationError(`invalid save version ${fromVersion}`, fromVersion, toVersion);
+    if (fromVersion > toVersion)
+        throw new MigrationError(`save version ${fromVersion} is newer than this build (${toVersion})`, fromVersion, toVersion);
+    let current = data;
+    for (let v = fromVersion; v < toVersion; v++) {
+        const step = migrations[v];
+        if (!step)
+            throw new MigrationError(`no migration from v${v} to v${v + 1}`, v, toVersion);
+        try {
+            current = step(current);
+        }
+        catch (err) {
+            throw new MigrationError(`migration v${v} → v${v + 1} failed: ${err instanceof Error ? err.message : String(err)}`, v, toVersion);
+        }
+    }
+    return current;
+}
+/** Throws if the chain `1 → version` has gaps. Call once at startup or in a test. */
+export function assertMigrationChain(version, migrations) {
+    for (let v = 1; v < version; v++) {
+        if (typeof migrations[v] !== 'function')
+            throw new MigrationError(`migration chain gap: v${v} → v${v + 1}`, v, version);
+    }
+}

package/dist/save/schema.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A tiny runtime schema guard for save data. Not a general validation library:
+ * just enough to reject corrupt or hand-edited saves before the game sees them.
+ *
+ * ```ts
+ * const Settings = s.object({ volume: s.number({ min: 0, max: 1 }), name: s.optional(s.string()) });
+ * type Settings = Infer<typeof Settings>;
+ * Settings.validate(json); // null when valid, else "$.volume: expected number ≤ 1"
+ * ```
+ */
+import { type TypedArrayOf, type TypedKind } from './codec.js';
+export interface Schema<T> {
+    /** Returns `null` if `value` matches, else a message naming the first failing path. */
+    validate(value: unknown, path?: string): string | null;
+    /** Type guard form of `validate`. */
+    is(value: unknown): value is T;
+    /** Phantom field carrying the inferred type. Never set at runtime. */
+    readonly _type?: T;
+}
+export type Infer<S> = S extends Schema<infer T> ? T : never;
+/** `s.number(opts)`: an inclusive range and an integer check. */
+export interface NumberOptions {
+    min?: number;
+    max?: number;
+    int?: boolean;
+}
+/** Optional-key marker used by `s.object`. */
+declare const OPTIONAL: unique symbol;
+type OptionalSchema<T> = Schema<T | undefined> & {
+    [OPTIONAL]: true;
+};
+type Shape = Record<string, Schema<unknown>>;
+type OptionalKeys<S extends Shape> = {
+    [K in keyof S]: S[K] extends {
+        [OPTIONAL]: true;
+    } ? K : never;
+}[keyof S];
+type ObjectOf<S extends Shape> = {
+    [K in Exclude<keyof S, OptionalKeys<S>>]: Infer<S[K]>;
+} & {
+    [K in OptionalKeys<S>]?: Infer<S[K]>;
+};
+export declare const s: {
+    unknown(): Schema<unknown>;
+    boolean(): Schema<boolean>;
+    string(opts?: {
+        maxLength?: number;
+    }): Schema<string>;
+    number(opts?: NumberOptions): Schema<number>;
+    literal<const L extends string | number | boolean | null>(...values: L[]): Schema<L>;
+    array<T>(item: Schema<T>, opts?: {
+        maxLength?: number;
+    }): Schema<T[]>;
+    /** String-keyed map with uniform values. */
+    record<T>(value: Schema<T>): Schema<Record<string, T>>;
+    /** Fixed-shape object. Extra keys are allowed (forward compatibility) unless `strict`. */
+    object<S extends Shape>(shape: S, opts?: {
+        strict?: boolean;
+    }): Schema<ObjectOf<S>>;
+    optional<T>(inner: Schema<T>): OptionalSchema<T>;
+    nullable<T>(inner: Schema<T>): Schema<T | null>;
+    /** A `Uint8Array` (stored as base64url, not a number array). */
+    bytes(opts?: {
+        maxLength?: number;
+    }): Schema<Uint8Array>;
+    /** One of the eight typed arrays by kind, e.g. `s.typed('f32')` for a `Float32Array`. */
+    typed<K extends TypedKind>(kind: K, opts?: {
+        maxLength?: number;
+    }): Schema<TypedArrayOf<K>>;
+    union<T extends Schema<unknown>[]>(...options: T): Schema<Infer<T[number]>>;
+};
+export {};

package/dist/save/schema.js

@@ -0,0 +1,154 @@
+/**
+ * A tiny runtime schema guard for save data. Not a general validation library:
+ * just enough to reject corrupt or hand-edited saves before the game sees them.
+ *
+ * ```ts
+ * const Settings = s.object({ volume: s.number({ min: 0, max: 1 }), name: s.optional(s.string()) });
+ * type Settings = Infer<typeof Settings>;
+ * Settings.validate(json); // null when valid, else "$.volume: expected number ≤ 1"
+ * ```
+ */
+import { TYPED_KIND_CTORS } from './codec.js';
+function make(validate) {
+    return {
+        validate: (value, path = '$') => validate(value, path),
+        is: (value) => validate(value, '$') === null,
+    };
+}
+function typeName(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    if (ArrayBuffer.isView(v))
+        return v.constructor.name;
+    return typeof v;
+}
+/** Optional-key marker used by `s.object`. */
+const OPTIONAL = Symbol('optional');
+export const s = {
+    unknown() {
+        return make(() => null);
+    },
+    boolean() {
+        return make((v, p) => typeof v === 'boolean' ? null : `${p}: expected boolean, got ${typeName(v)}`);
+    },
+    string(opts = {}) {
+        return make((v, p) => {
+            if (typeof v !== 'string')
+                return `${p}: expected string, got ${typeName(v)}`;
+            if (opts.maxLength !== undefined && v.length > opts.maxLength)
+                return `${p}: string longer than ${opts.maxLength}`;
+            return null;
+        });
+    },
+    number(opts = {}) {
+        return make((v, p) => {
+            if (typeof v !== 'number' || !Number.isFinite(v))
+                return `${p}: expected finite number, got ${typeName(v)}`;
+            if (opts.int && !Number.isInteger(v))
+                return `${p}: expected integer`;
+            if (opts.min !== undefined && v < opts.min)
+                return `${p}: expected number ≥ ${opts.min}`;
+            if (opts.max !== undefined && v > opts.max)
+                return `${p}: expected number ≤ ${opts.max}`;
+            return null;
+        });
+    },
+    literal(...values) {
+        return make((v, p) => values.includes(v) ? null : `${p}: expected one of ${JSON.stringify(values)}`);
+    },
+    array(item, opts = {}) {
+        return make((v, p) => {
+            if (!Array.isArray(v))
+                return `${p}: expected array, got ${typeName(v)}`;
+            if (opts.maxLength !== undefined && v.length > opts.maxLength)
+                return `${p}: array longer than ${opts.maxLength}`;
+            for (let i = 0; i < v.length; i++) {
+                const err = item.validate(v[i], `${p}[${i}]`);
+                if (err)
+                    return err;
+            }
+            return null;
+        });
+    },
+    /** String-keyed map with uniform values. */
+    record(value) {
+        return make((v, p) => {
+            if (typeof v !== 'object' || v === null || Array.isArray(v))
+                return `${p}: expected object, got ${typeName(v)}`;
+            for (const [k, val] of Object.entries(v)) {
+                const err = value.validate(val, `${p}.${k}`);
+                if (err)
+                    return err;
+            }
+            return null;
+        });
+    },
+    /** Fixed-shape object. Extra keys are allowed (forward compatibility) unless `strict`. */
+    object(shape, opts = {}) {
+        return make((v, p) => {
+            if (typeof v !== 'object' || v === null || Array.isArray(v))
+                return `${p}: expected object, got ${typeName(v)}`;
+            const obj = v;
+            for (const [k, schema] of Object.entries(shape)) {
+                const optional = OPTIONAL in schema;
+                if (!(k in obj) || obj[k] === undefined) {
+                    if (optional)
+                        continue;
+                    return `${p}.${k}: missing`;
+                }
+                const err = schema.validate(obj[k], `${p}.${k}`);
+                if (err)
+                    return err;
+            }
+            if (opts.strict) {
+                for (const k of Object.keys(obj))
+                    if (!(k in shape))
+                        return `${p}.${k}: unexpected key`;
+            }
+            return null;
+        });
+    },
+    optional(inner) {
+        const base = make((v, p) => (v === undefined ? null : inner.validate(v, p)));
+        return Object.assign(base, { [OPTIONAL]: true });
+    },
+    nullable(inner) {
+        return make((v, p) => (v === null ? null : inner.validate(v, p)));
+    },
+    /** A `Uint8Array` (stored as base64url, not a number array). */
+    bytes(opts = {}) {
+        return make((v, p) => {
+            if (!(v instanceof Uint8Array))
+                return `${p}: expected Uint8Array, got ${typeName(v)}`;
+            if (opts.maxLength !== undefined && v.length > opts.maxLength)
+                return `${p}: bytes longer than ${opts.maxLength}`;
+            return null;
+        });
+    },
+    /** One of the eight typed arrays by kind, e.g. `s.typed('f32')` for a `Float32Array`. */
+    typed(kind, opts = {}) {
+        const Ctor = TYPED_KIND_CTORS[kind];
+        return make((v, p) => {
+            if (!(v instanceof Ctor))
+                return `${p}: expected ${Ctor.name}, got ${typeName(v)}`;
+            const len = v.byteLength / Ctor.BYTES_PER_ELEMENT;
+            if (opts.maxLength !== undefined && len > opts.maxLength)
+                return `${p}: typed array longer than ${opts.maxLength}`;
+            return null;
+        });
+    },
+    union(...options) {
+        return make((v, p) => {
+            const errors = [];
+            for (const o of options) {
+                const err = o.validate(v, p);
+                if (err === null)
+                    return null;
+                errors.push(err);
+            }
+            return errors.join(' | ') || `${p}: no union options`;
+        });
+    },
+};

package/dist/save/settings.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A settings store: `createSaveStore` in the `settings` slot, written synchronously, kept apart
+ * from progress, with `bind` for wiring menu controls.
+ */
+import { type SaveStore, type SaveStoreOptions } from './store.js';
+export interface SettingsStoreOptions<T> extends Omit<SaveStoreOptions<T>, 'slot' | 'debounceMs' | 'version' | 'meta'> {
+    /** Default `settings`. */
+    slot?: string;
+    /** Default 1. */
+    version?: number;
+}
+/** A control `bind` can drive: an `<input>`, `<select>`, or any `{ value }` object (tests). */
+export type BindTarget = HTMLInputElement | HTMLSelectElement | {
+    value: string;
+    checked?: boolean;
+    type?: string;
+    addEventListener?: (type: string, fn: () => void) => void;
+    removeEventListener?: (type: string, fn: () => void) => void;
+};
+export interface SettingsStore<T> extends SaveStore<T> {
+    /**
+     * Sets the control from `get()[key]`, writes the control's value to the store on `input` and
+     * `change` (coerced to the key's current type: number, boolean or string; a checkbox uses
+     * `checked`), and updates the control when the store changes elsewhere. Returns unbind.
+     */
+    bind<K extends keyof T & string>(input: BindTarget, key: K): () => void;
+}
+export declare function createSettingsStore<T>(opts: SettingsStoreOptions<T>): SettingsStore<T>;

package/dist/save/settings.js

@@ -0,0 +1,59 @@
+/**
+ * A settings store: `createSaveStore` in the `settings` slot, written synchronously, kept apart
+ * from progress, with `bind` for wiring menu controls.
+ */
+import { createSaveStore } from './store.js';
+export function createSettingsStore(opts) {
+    const store = createSaveStore({
+        ...opts,
+        slot: opts.slot ?? 'settings',
+        version: opts.version ?? 1,
+        debounceMs: 0,
+    });
+    const bind = (input, key) => {
+        const checkbox = input.type === 'checkbox';
+        const read = () => {
+            const current = store.get()[key];
+            if (typeof current === 'boolean')
+                return checkbox ? !!input.checked : input.value === 'true';
+            if (typeof current === 'number') {
+                const n = Number(input.value);
+                return Number.isFinite(n) ? n : current;
+            }
+            return input.value;
+        };
+        const show = () => {
+            const v = store.get()[key];
+            if (checkbox)
+                input.checked = !!v;
+            else
+                input.value = String(v);
+        };
+        let writing = false;
+        const onInput = () => {
+            const next = read();
+            if (Object.is(next, store.get()[key]))
+                return;
+            writing = true;
+            const ok = store.update((d) => {
+                d[key] = next;
+            });
+            writing = false;
+            if (!ok)
+                show();
+        };
+        show();
+        input.addEventListener?.('input', onInput);
+        input.addEventListener?.('change', onInput);
+        const unsubscribe = store.subscribe(() => {
+            if (!writing)
+                show();
+        });
+        return () => {
+            input.removeEventListener?.('input', onInput);
+            input.removeEventListener?.('change', onInput);
+            unsubscribe();
+        };
+    };
+    return Object.assign(store, { bind });
+}