@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/save/slots.d.ts

@@ -0,0 +1,56 @@
+import type { Host } from '../host/types.js';
+import type { Migrations } from './migrate.js';
+import type { Schema } from './schema.js';
+import type { StorageLike } from './storage.js';
+import { type SaveStore, type SlotMeta } from './store.js';
+export interface SlotInfo {
+    /** 1-based slot number. */
+    slot: number;
+    label: string;
+    /** `savedAt` of the data in storage (ms). */
+    savedAt: number;
+    /** Version of the data in storage (before any migration `open` would run). */
+    version: number;
+    playMs?: number;
+    thumbnail?: string;
+    /** Length of the stored JSON text (UTF-16 code units). */
+    size: number;
+}
+export interface SlotManagerOptions<T> {
+    game: string;
+    version: number;
+    migrations?: Migrations;
+    defaults: () => T;
+    schema: Schema<T> | ((value: unknown) => value is T);
+    /** Number of slots, `1..slots`. Default 3. */
+    slots?: number;
+    host?: Pick<Host, 'storage'>;
+    storage?: StorageLike | null;
+    /** Fills `label`, `playMs` and `thumbnail` for the sidecar on every flush. */
+    meta?: (data: T) => SlotMeta;
+    /** Passed to each store. Default 250. */
+    debounceMs?: number;
+    autoFlush?: boolean;
+    now?: () => number;
+}
+export interface SlotManager<T> {
+    /** Number of slots. */
+    readonly slots: number;
+    /** Slots that hold data, in slot order, from the sidecars; no save data is parsed. */
+    list(): SlotInfo[];
+    /** The store for slot `n`; the same instance while it stays open. Throws outside `1..slots`. */
+    open(slot: number): SaveStore<T>;
+    /** Copies data and sidecar from one slot to another, flushing `from` first. False if `from` is empty. */
+    copy(from: number, to: number): boolean;
+    /** Removes data, sidecar and backup. An open store for the slot is reset to defaults. */
+    remove(slot: number): void;
+    /**
+     * Changes the label in the sidecar (writing one if the slot predates sidecars) and keeps it
+     * through later flushes of an open store unless `meta` returns its own label. False if empty.
+     */
+    rename(slot: number, label: string): boolean;
+    /** The slot with the latest `savedAt`, or null. */
+    mostRecent(): SlotInfo | null;
+}
+export declare function slotName(slot: number): string;
+export declare function createSlotManager<T>(opts: SlotManagerOptions<T>): SlotManager<T>;

package/dist/save/slots.js

@@ -0,0 +1,200 @@
+/**
+ * Numbered save slots with a metadata sidecar, for a load/save menu.
+ *
+ * Slot `n` (1-based) is the store `thunderclap:<game>:slot<n>`; its sidecar `<key>:meta`
+ * (`StoredMeta`) is written in the same flush as the data, so `list()` reads only sidecars and
+ * never parses save data. Slots saved before the sidecar existed are listed from the data key's
+ * `v` and `t`.
+ */
+import { defaultHost } from '../host/default.js';
+import { isEnvelope } from './codec.js';
+import { createSaveStore, saveKey } from './store.js';
+export function slotName(slot) {
+    return `slot${slot}`;
+}
+function readMeta(storage, key) {
+    const raw = storage.getItem(`${key}:meta`);
+    if (raw !== null) {
+        try {
+            const m = JSON.parse(raw);
+            if (typeof m === 'object' &&
+                m !== null &&
+                typeof m.v === 'number' &&
+                typeof m.t === 'number' &&
+                typeof m.size === 'number')
+                return m;
+        }
+        catch {
+            // Fall through to the data key.
+        }
+    }
+    const data = storage.getItem(key);
+    if (data === null)
+        return null;
+    try {
+        const env = JSON.parse(data);
+        if (!isEnvelope(env))
+            return null;
+        return { v: env.v, t: env.t, size: data.length };
+    }
+    catch {
+        return null;
+    }
+}
+export function createSlotManager(opts) {
+    const count = opts.slots ?? 3;
+    if (!Number.isInteger(count) || count < 1)
+        throw new Error('slots must be an integer ≥ 1');
+    const userMeta = opts.meta ?? (() => ({}));
+    /** Labels set by `rename`, so an open store's next flush keeps them. */
+    const labels = new Map();
+    const metaFor = (slot) => (data) => {
+        const m = userMeta(data);
+        const label = labels.get(slot);
+        return label !== undefined && m.label === undefined ? { ...m, label } : m;
+    };
+    const source = opts.storage === undefined ? (opts.host ?? defaultHost()).storage : null;
+    const storageNow = () => (source ? source.open() : (opts.storage ?? null));
+    const open = new Map();
+    const check = (slot) => {
+        if (!Number.isInteger(slot) || slot < 1 || slot > count)
+            throw new RangeError(`slot ${slot} is outside 1..${count}`);
+        return saveKey(opts.game, slotName(slot));
+    };
+    const info = (storage, slot) => {
+        let m;
+        try {
+            m = readMeta(storage, check(slot));
+        }
+        catch {
+            return null;
+        }
+        if (!m)
+            return null;
+        const out = {
+            slot,
+            label: m.label ?? `Slot ${slot}`,
+            savedAt: m.t,
+            version: m.v,
+            size: m.size,
+        };
+        if (m.playMs !== undefined)
+            out.playMs = m.playMs;
+        if (m.thumbnail !== undefined)
+            out.thumbnail = m.thumbnail;
+        return out;
+    };
+    const list = () => {
+        const storage = storageNow();
+        if (!storage)
+            return [];
+        const out = [];
+        for (let n = 1; n <= count; n++) {
+            const i = info(storage, n);
+            if (i)
+                out.push(i);
+        }
+        return out;
+    };
+    return {
+        slots: count,
+        list,
+        open(slot) {
+            const key = check(slot);
+            let store = open.get(slot);
+            if (store)
+                return store;
+            store = createSaveStore({
+                game: opts.game,
+                slot: slotName(slot),
+                version: opts.version,
+                migrations: opts.migrations,
+                defaults: opts.defaults,
+                schema: opts.schema,
+                debounceMs: opts.debounceMs,
+                host: opts.host,
+                storage: opts.storage,
+                autoFlush: opts.autoFlush,
+                now: opts.now,
+                meta: metaFor(slot),
+            });
+            if (store.key !== key)
+                throw new Error('slot key mismatch');
+            open.set(slot, store);
+            return store;
+        },
+        copy(from, to) {
+            const fromKey = check(from);
+            const toKey = check(to);
+            if (from === to)
+                return false;
+            open.get(from)?.flush();
+            const storage = storageNow();
+            if (!storage)
+                return false;
+            try {
+                const data = storage.getItem(fromKey);
+                if (data === null)
+                    return false;
+                const target = open.get(to);
+                if (target) {
+                    target.dispose();
+                    open.delete(to);
+                }
+                storage.setItem(toKey, data);
+                labels.delete(to);
+                const m = storage.getItem(`${fromKey}:meta`);
+                if (m !== null)
+                    storage.setItem(`${toKey}:meta`, m);
+                else
+                    storage.removeItem(`${toKey}:meta`);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        remove(slot) {
+            const key = check(slot);
+            const store = open.get(slot);
+            if (store)
+                store.clear();
+            labels.delete(slot);
+            const storage = storageNow();
+            if (!storage)
+                return;
+            try {
+                storage.removeItem(key);
+                storage.removeItem(`${key}:meta`);
+                storage.removeItem(`${key}:backup`);
+            }
+            catch {
+                // Nothing to do: the slot is unreadable anyway.
+            }
+        },
+        rename(slot, label) {
+            const key = check(slot);
+            const storage = storageNow();
+            if (!storage)
+                return false;
+            try {
+                const m = readMeta(storage, key);
+                if (!m)
+                    return false;
+                storage.setItem(`${key}:meta`, JSON.stringify({ ...m, label }));
+                labels.set(slot, label);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        mostRecent() {
+            let best = null;
+            for (const i of list())
+                if (!best || i.savedAt > best.savedAt)
+                    best = i;
+            return best;
+        },
+    };
+}

package/dist/save/storage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Storage backends. Web storage can be missing, throw on access (sandboxed or
+ * cross-origin iframes with third-party storage blocked), throw on write (quota,
+ * Safari private mode), or be silently partitioned. Everything here is defensive.
+ * The real backend comes from the host (`Host.storage`, engine/host); the web host
+ * probes `localStorage` with `probeStorage`.
+ */
+/** The subset of the Web Storage API the save module uses. */
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    readonly length: number;
+    key(index: number): string | null;
+}
+/** In-memory `StorageLike`. Used as the fallback and in tests. */
+export declare class MemoryStorage implements StorageLike {
+    private readonly map;
+    get length(): number;
+    key(index: number): string | null;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * Returns the storage `get` yields if it works, or `null` if it is unavailable,
+ * throws, or cannot round-trip a value. Never throws.
+ *
+ * @param get how to obtain the storage. Merely reading `window.localStorage`
+ *   throws a SecurityError in some iframes, so the getter itself is guarded.
+ */
+export declare function probeStorage(get: () => StorageLike | undefined | null): StorageLike | null;
+/** True if `err` looks like a storage quota error across browsers. */
+export declare function isQuotaError(err: unknown): boolean;

package/dist/save/storage.js

@@ -0,0 +1,62 @@
+/**
+ * Storage backends. Web storage can be missing, throw on access (sandboxed or
+ * cross-origin iframes with third-party storage blocked), throw on write (quota,
+ * Safari private mode), or be silently partitioned. Everything here is defensive.
+ * The real backend comes from the host (`Host.storage`, engine/host); the web host
+ * probes `localStorage` with `probeStorage`.
+ */
+/** In-memory `StorageLike`. Used as the fallback and in tests. */
+export class MemoryStorage {
+    map = new Map();
+    get length() {
+        return this.map.size;
+    }
+    key(index) {
+        return [...this.map.keys()][index] ?? null;
+    }
+    getItem(key) {
+        return this.map.get(key) ?? null;
+    }
+    setItem(key, value) {
+        this.map.set(key, String(value));
+    }
+    removeItem(key) {
+        this.map.delete(key);
+    }
+    clear() {
+        this.map.clear();
+    }
+}
+const PROBE_KEY = 'thunderclap:__probe__';
+/**
+ * Returns the storage `get` yields if it works, or `null` if it is unavailable,
+ * throws, or cannot round-trip a value. Never throws.
+ *
+ * @param get how to obtain the storage. Merely reading `window.localStorage`
+ *   throws a SecurityError in some iframes, so the getter itself is guarded.
+ */
+export function probeStorage(get) {
+    try {
+        const storage = get();
+        if (!storage)
+            return null;
+        const token = String(Date.now());
+        storage.setItem(PROBE_KEY, token);
+        const ok = storage.getItem(PROBE_KEY) === token;
+        storage.removeItem(PROBE_KEY);
+        return ok ? storage : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True if `err` looks like a storage quota error across browsers. */
+export function isQuotaError(err) {
+    if (!(err instanceof Error) && !(typeof err === 'object' && err !== null))
+        return false;
+    const e = err;
+    return (e.name === 'QuotaExceededError' ||
+        e.name === 'NS_ERROR_DOM_QUOTA_REACHED' ||
+        e.code === 22 ||
+        e.code === 1014);
+}

package/dist/save/store.d.ts

@@ -0,0 +1,114 @@
+import type { Host } from '../host/types.js';
+import { type Migrations } from './migrate.js';
+import type { Schema } from './schema.js';
+import { type StorageLike } from './storage.js';
+/** What a slot menu shows without loading the slot; filled by `SaveStoreOptions.meta`. */
+export interface SlotMeta {
+    /** Shown in the slot list. Default `Slot <n>` in a slot manager. */
+    label?: string;
+    /** Play time in ms. */
+    playMs?: number;
+    /** A small image for the menu (a data URL or a game-defined id). Keep it short: it is stored. */
+    thumbnail?: string;
+}
+/** The sidecar at `<key>:meta`, written in the same flush as the data. */
+export interface StoredMeta extends SlotMeta {
+    v: number;
+    t: number;
+    /** Length of the stored JSON text (UTF-16 code units, what web storage quotas count). */
+    size: number;
+}
+/** `thunderclap:<game>:<slot>` */
+export declare function saveKey(game: string, slot: string): string;
+/** Slot names that currently have data for `game` (excludes backups). */
+export declare function listSlots(game: string, storage?: StorageLike | null): string[];
+/**
+ * How the initial load went:
+ * - `fresh`: nothing stored; defaults used.
+ * - `loaded`: stored data at the current version.
+ * - `migrated`: stored data upgraded from an older version (written back on next flush).
+ * - `recovered`: stored data was unreadable (corrupt, invalid, newer build, failed migration);
+ *   the raw value was copied to `<key>:backup` and defaults were used. See `status.error`.
+ */
+export type LoadResult = 'fresh' | 'loaded' | 'migrated' | 'recovered';
+export interface SaveStatus {
+    /** True when the last read/write reached real storage. False means memory only: warn the player. */
+    persistent: boolean;
+    loadResult: LoadResult;
+    /** Most recent problem (load, write or import), or null. */
+    error: string | null;
+    /** True while a debounced write is pending. */
+    dirty: boolean;
+}
+export interface SaveStoreOptions<T> {
+    /** Game id, e.g. `my-game`. Letters, digits, `-`, `_`. */
+    game: string;
+    /** Slot name. Default `main`. */
+    slot?: string;
+    /** Current data version (integer ≥ 1). */
+    version: number;
+    /** `migrations[n]` upgrades data from v`n` to v`n+1`. Must cover 1 → version. */
+    migrations?: Migrations;
+    /** Fresh data for a new player. Called whenever defaults are needed. */
+    defaults: () => T;
+    /** Runtime shape check applied after migration, on `set`, and on import. */
+    schema: Schema<T> | ((value: unknown) => value is T);
+    /** Debounce for writes, ms. Default 250. `0` writes synchronously on every `set`. */
+    debounceMs?: number;
+    /**
+     * Where the storage comes from: `host.storage.open()`, re-tried on each write while it is
+     * unavailable. Default: `defaultHost()` (the web host's `localStorage`).
+     */
+    host?: Pick<Host, 'storage'>;
+    /**
+     * A fixed backing storage instead of the host's. Pass `null` to force memory only.
+     * Tests pass a `MemoryStorage` or a throwing stub.
+     */
+    storage?: StorageLike | null;
+    /** Flush on `pagehide` / hidden `visibilitychange`. Default true when `window` exists. */
+    autoFlush?: boolean;
+    /** Clock for `savedAt`. Default `Date.now`. */
+    now?: () => number;
+    /**
+     * When set, every flush also writes `<key>:meta` (`StoredMeta`: version, time, size and what
+     * this returns) so a slot menu can list slots without loading them. A failed meta write is
+     * not an error for the data. Slot managers set it; plain stores leave it out.
+     */
+    meta?: (data: T) => SlotMeta;
+}
+export type ImportResult = {
+    ok: true;
+    migrated: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+export interface SaveStore<T> {
+    readonly key: string;
+    /** Shorthand for `status.persistent`. */
+    readonly persistent: boolean;
+    readonly status: Readonly<SaveStatus>;
+    /** Timestamp of the data currently held (ms), or 0 if never saved. */
+    readonly savedAt: number;
+    /** Current data. Treat as read-only; change it via `set` or `update`. */
+    get(): T;
+    /** Replace the data and schedule a write. Returns false (and records `error`) if it fails the schema. */
+    set(data: T): boolean;
+    /** Mutate a structured clone of the data (or return a replacement), validate, schedule a write. */
+    update(fn: (draft: T) => T | undefined): boolean;
+    /** Write now if dirty. Returns `status.persistent`. */
+    flush(): boolean;
+    /** Replace with defaults and write. */
+    reset(): void;
+    /** Remove the stored value (and backup); in-memory data becomes defaults. */
+    clear(): void;
+    /** Portable string for the player to copy. Includes pending changes. */
+    exportString(): string;
+    /** Validate, migrate and adopt a string from `exportString`. Writes immediately on success. */
+    importString(text: string): ImportResult;
+    /** Called after every status or data change. Returns an unsubscribe function. */
+    subscribe(fn: (status: Readonly<SaveStatus>) => void): () => void;
+    /** Flush and remove listeners. */
+    dispose(): void;
+}
+export declare function createSaveStore<T>(opts: SaveStoreOptions<T>): SaveStore<T>;