@jgengine/core 0.10.0 → 0.11.0

package/dist/game/saveStore.d.ts

@@ -0,0 +1,111 @@
+import { type KeyValueStorage } from "./keyValueStore.js";
+/**
+ * The one async storage seam a save store persists through. Every backend
+ * satisfies this same three-method shape — the browser's `localStorage`
+ * (offline), an in-memory map (tests/SSR), or a database/Convex/HTTP endpoint
+ * (cloud) — so a game switches offline saves for cloud saves by swapping the
+ * backend and changing nothing else. Keys are opaque namespaced strings; values
+ * are already-serialized strings, so a backend never needs to know the save
+ * shape.
+ */
+export interface SaveBackend {
+    read(key: string): Promise<string | null>;
+    write(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/**
+ * A {@link SaveBackend} over a synchronous {@link KeyValueStorage} — the
+ * browser's `localStorage` by default (offline, on-device saves), a test stub,
+ * or `null` for memory-only. Storage errors (quota exceeded, private mode, no
+ * DOM) degrade to no-ops, so a save never throws into a game tick.
+ *
+ * @capability local-save persist a game to on-device localStorage (offline)
+ */
+export declare function localSaveBackend(storage?: KeyValueStorage | null): SaveBackend;
+/** A memory-only {@link SaveBackend} — saves survive a reload only within the same session. For tests, SSR, or a "no persistence" mode that still exercises the same save code path. */
+export declare function memorySaveBackend(): SaveBackend;
+/** Adopt any async `read`/`write`/`remove` trio as a {@link SaveBackend} — the seam for cloud saves backed by a database, an HTTP endpoint, or Convex (see `@jgengine/convex/convexSaveBackend`). Reads/writes may reject; the save store surfaces the failure as `"error"` status instead of throwing. */
+export declare function remoteSaveBackend(backend: SaveBackend): SaveBackend;
+/** Lifecycle of the last save/load — drive a "Saving…"/"Saved" indicator or a loading gate off it. `"error"` means the backend rejected a read or write. */
+export type SaveStatus = "idle" | "loading" | "saving" | "saved" | "error";
+/** Autosave cadence: debounce writes `debounceMs` after the last edit, but never wait longer than `maxWaitMs` while edits keep coming (`0` removes the ceiling). `autosave: true` uses `{ debounceMs: 1000, maxWaitMs: 15000 }`. */
+export interface SaveAutoConfig {
+    debounceMs?: number;
+    maxWaitMs?: number;
+}
+/** The timer seam autosave schedules through — defaults to the ambient `setTimeout`/`clearTimeout`; inject fakes in tests. */
+export interface SaveTimers {
+    set(handler: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+/** The versioned envelope written to the backend — `version` lets a later game build detect and {@link SaveStoreConfig.migrate | migrate} an older payload. */
+export interface SaveEnvelope<T> {
+    version: number;
+    savedAt: number;
+    value: T;
+}
+/** How a {@link createSaveStore} is wired — the backend it persists through, the initial value, and optional slot/versioning/autosave/serialization knobs. */
+export interface SaveStoreConfig<T> {
+    /** Where saves live — {@link localSaveBackend}, {@link memorySaveBackend}, or a {@link remoteSaveBackend}. */
+    backend: SaveBackend;
+    /** The value a fresh save starts from (nothing stored yet, or after `clear`). */
+    initial: T;
+    /** Storage namespace, joined with the slot into the backend key. Default `"save"`. */
+    key?: string;
+    /** Active save slot — pass distinct slots for multiple parallel saves. Default `"default"`. */
+    slot?: string;
+    /** Current save-format version. Default `1`. Bump it on a breaking shape change and pass {@link migrate}. */
+    version?: number;
+    /** Upgrade an older payload to the current shape. Receives the stored value and the version it was written at (`0` for a pre-versioned/raw payload). */
+    migrate?: (data: unknown, fromVersion: number) => T;
+    /** Autosave on every `set`/`patch`. `false` (default) saves only on an explicit `save()`. */
+    autosave?: boolean | SaveAutoConfig;
+    serialize?: (envelope: SaveEnvelope<T>) => string;
+    deserialize?: (raw: string) => unknown;
+    /** Injectable clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Injectable timers for autosave. Default ambient `setTimeout`/`clearTimeout`. */
+    timers?: SaveTimers;
+    /** Notified on any backend read/write failure — status is already `"error"` when it runs. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * A pluggable-backend game save with autosave, named slots, and versioned
+ * migration. `value()`/`patch()` hold the live state; `load()` hydrates it from
+ * the backend; `save()` (or autosave) writes it back. Backend failures surface
+ * as `"error"` status and through `onError` — a save never throws into a tick.
+ */
+export interface SaveStore<T> {
+    value(): T;
+    status(): SaveStatus;
+    slot(): string;
+    /** Monotonic change counter — bumps on any value or status change; drive `useSyncExternalStore` off it. */
+    revision(): number;
+    /** Hydrate the active slot from the backend into `value()`; corrupt payloads fall back to `initial`. */
+    load(): Promise<T>;
+    /** Replace the value and mark it dirty (schedules autosave). */
+    set(value: T): void;
+    /** Read-modify-write the value and mark it dirty; returns the next value. */
+    patch(mutate: (previous: T) => T): T;
+    /** Flush the current value to the backend now (serialized against in-flight saves). */
+    save(): Promise<void>;
+    /** Delete the active slot and reset `value()` to `initial`. */
+    clear(): Promise<void>;
+    /** Flush any dirty state, switch to `slot`, and load it. */
+    switchSlot(slot: string): Promise<T>;
+    /** The slots this store has written (for a load/save menu). */
+    slots(): Promise<string[]>;
+    subscribe(listener: () => void): () => void;
+    /** Stop autosave timers and drop listeners. */
+    dispose(): void;
+}
+/**
+ * Create a {@link SaveStore}. Same call for offline and cloud — only the
+ * `backend` differs (localStorage, memory, or an async DB/Convex endpoint). Turn
+ * on `autosave` and every `set`/`patch` persists on a debounce; leave it off and
+ * call `save()` at checkpoints. Bump `version` + pass `migrate` when the save
+ * shape changes so old players keep their progress.
+ *
+ * @capability game-save save/load game state with a pluggable backend, autosave, slots, and migration
+ */
+export declare function createSaveStore<T>(config: SaveStoreConfig<T>): SaveStore<T>;

package/dist/game/saveStore.js

@@ -0,0 +1,312 @@
+import { defaultKeyValueStorage } from "./keyValueStore.js";
+function readSafe(storage, key) {
+    if (storage === null)
+        return null;
+    try {
+        return storage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A {@link SaveBackend} over a synchronous {@link KeyValueStorage} — the
+ * browser's `localStorage` by default (offline, on-device saves), a test stub,
+ * or `null` for memory-only. Storage errors (quota exceeded, private mode, no
+ * DOM) degrade to no-ops, so a save never throws into a game tick.
+ *
+ * @capability local-save persist a game to on-device localStorage (offline)
+ */
+export function localSaveBackend(storage) {
+    const store = storage === undefined ? defaultKeyValueStorage() : storage;
+    return {
+        read: (key) => Promise.resolve(readSafe(store, key)),
+        write: (key, value) => {
+            if (store !== null) {
+                try {
+                    store.setItem(key, value);
+                }
+                catch {
+                    // storage rejected the write; the store keeps the value in memory
+                }
+            }
+            return Promise.resolve();
+        },
+        remove: (key) => {
+            if (store !== null) {
+                try {
+                    store.removeItem(key);
+                }
+                catch {
+                    // ignore removal failure
+                }
+            }
+            return Promise.resolve();
+        },
+    };
+}
+/** A memory-only {@link SaveBackend} — saves survive a reload only within the same session. For tests, SSR, or a "no persistence" mode that still exercises the same save code path. */
+export function memorySaveBackend() {
+    const map = new Map();
+    return {
+        read: (key) => Promise.resolve(map.get(key) ?? null),
+        write: (key, value) => {
+            map.set(key, value);
+            return Promise.resolve();
+        },
+        remove: (key) => {
+            map.delete(key);
+            return Promise.resolve();
+        },
+    };
+}
+/** Adopt any async `read`/`write`/`remove` trio as a {@link SaveBackend} — the seam for cloud saves backed by a database, an HTTP endpoint, or Convex (see `@jgengine/convex/convexSaveBackend`). Reads/writes may reject; the save store surfaces the failure as `"error"` status instead of throwing. */
+export function remoteSaveBackend(backend) {
+    return backend;
+}
+function defaultTimers() {
+    return {
+        set: (handler, ms) => globalThis.setTimeout(handler, ms),
+        clear: (handle) => globalThis.clearTimeout(handle),
+    };
+}
+function normalizeAuto(config) {
+    if (config === undefined || config === false)
+        return null;
+    if (config === true)
+        return { debounceMs: 1000, maxWaitMs: 15000 };
+    return { debounceMs: config.debounceMs ?? 1000, maxWaitMs: config.maxWaitMs ?? 15000 };
+}
+function isEnvelope(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.version === "number" &&
+        "value" in value);
+}
+/**
+ * Create a {@link SaveStore}. Same call for offline and cloud — only the
+ * `backend` differs (localStorage, memory, or an async DB/Convex endpoint). Turn
+ * on `autosave` and every `set`/`patch` persists on a debounce; leave it off and
+ * call `save()` at checkpoints. Bump `version` + pass `migrate` when the save
+ * shape changes so old players keep their progress.
+ *
+ * @capability game-save save/load game state with a pluggable backend, autosave, slots, and migration
+ */
+export function createSaveStore(config) {
+    const namespace = config.key ?? "save";
+    const formatVersion = config.version ?? 1;
+    const initial = config.initial;
+    const backend = config.backend;
+    const clock = config.now ?? (() => Date.now());
+    const timers = config.timers ?? defaultTimers();
+    const auto = normalizeAuto(config.autosave);
+    const serialize = config.serialize ?? ((envelope) => JSON.stringify(envelope));
+    const deserialize = config.deserialize ?? ((raw) => JSON.parse(raw));
+    const onError = config.onError;
+    let currentSlot = config.slot ?? "default";
+    let current = initial;
+    let status = "idle";
+    let revision = 0;
+    let dirty = false;
+    let firstDirtyAt = null;
+    let pendingTimer = null;
+    let saveChain = Promise.resolve();
+    let disposed = false;
+    const listeners = new Set();
+    function emit() {
+        revision += 1;
+        for (const listener of listeners)
+            listener();
+    }
+    function setStatus(next) {
+        if (status === next)
+            return;
+        status = next;
+        emit();
+    }
+    function reportError(error) {
+        onError?.(error);
+    }
+    const dataKey = (slot) => `${namespace}:${slot}`;
+    const indexKey = () => `${namespace}:__slots__`;
+    function decode(raw) {
+        const parsed = deserialize(raw);
+        if (isEnvelope(parsed)) {
+            if (parsed.version === formatVersion)
+                return parsed.value;
+            if (config.migrate)
+                return config.migrate(parsed.value, parsed.version);
+            return parsed.value;
+        }
+        if (config.migrate)
+            return config.migrate(parsed, 0);
+        return parsed;
+    }
+    async function readSlots() {
+        try {
+            const raw = await backend.read(indexKey());
+            if (raw === null)
+                return [];
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed.filter((entry) => typeof entry === "string") : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async function rememberSlot(slot) {
+        try {
+            const list = await readSlots();
+            if (list.includes(slot))
+                return;
+            await backend.write(indexKey(), JSON.stringify([...list, slot]));
+        }
+        catch (error) {
+            reportError(error);
+        }
+    }
+    async function forgetSlot(slot) {
+        try {
+            const list = await readSlots();
+            if (!list.includes(slot))
+                return;
+            await backend.write(indexKey(), JSON.stringify(list.filter((entry) => entry !== slot)));
+        }
+        catch (error) {
+            reportError(error);
+        }
+    }
+    function clearTimer() {
+        if (pendingTimer !== null) {
+            timers.clear(pendingTimer);
+            pendingTimer = null;
+        }
+    }
+    function markDirty() {
+        dirty = true;
+        if (auto === null)
+            return;
+        const now = clock();
+        if (firstDirtyAt === null)
+            firstDirtyAt = now;
+        if (auto.maxWaitMs > 0 && now - firstDirtyAt >= auto.maxWaitMs) {
+            clearTimer();
+            void save();
+            return;
+        }
+        clearTimer();
+        pendingTimer = timers.set(() => {
+            pendingTimer = null;
+            void save();
+        }, auto.debounceMs);
+    }
+    async function flush() {
+        if (disposed)
+            return;
+        clearTimer();
+        const slot = currentSlot;
+        const value = current;
+        setStatus("saving");
+        try {
+            const envelope = { version: formatVersion, savedAt: clock(), value };
+            await backend.write(dataKey(slot), serialize(envelope));
+            await rememberSlot(slot);
+            if (current === value) {
+                dirty = false;
+                firstDirtyAt = null;
+            }
+            setStatus("saved");
+        }
+        catch (error) {
+            setStatus("error");
+            reportError(error);
+        }
+    }
+    function save() {
+        const run = saveChain.then(() => flush());
+        saveChain = run.catch(() => undefined);
+        return run;
+    }
+    async function load() {
+        setStatus("loading");
+        try {
+            const raw = await backend.read(dataKey(currentSlot));
+            let value;
+            try {
+                value = raw === null ? initial : decode(raw);
+            }
+            catch {
+                value = initial;
+            }
+            current = value;
+            dirty = false;
+            firstDirtyAt = null;
+            setStatus("idle");
+            emit();
+            void rememberSlot(currentSlot);
+            return current;
+        }
+        catch (error) {
+            setStatus("error");
+            reportError(error);
+            return current;
+        }
+    }
+    return {
+        value: () => current,
+        status: () => status,
+        slot: () => currentSlot,
+        revision: () => revision,
+        load,
+        set(value) {
+            current = value;
+            emit();
+            markDirty();
+        },
+        patch(mutate) {
+            current = mutate(current);
+            emit();
+            markDirty();
+            return current;
+        },
+        save,
+        async clear() {
+            clearTimer();
+            const slot = currentSlot;
+            setStatus("saving");
+            try {
+                await backend.remove(dataKey(slot));
+                await forgetSlot(slot);
+                current = initial;
+                dirty = false;
+                firstDirtyAt = null;
+                setStatus("idle");
+                emit();
+            }
+            catch (error) {
+                setStatus("error");
+                reportError(error);
+            }
+        },
+        async switchSlot(slot) {
+            if (dirty)
+                await save();
+            clearTimer();
+            currentSlot = slot;
+            current = initial;
+            dirty = false;
+            firstDirtyAt = null;
+            return load();
+        },
+        slots: readSlots,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        dispose() {
+            disposed = true;
+            clearTimer();
+            listeners.clear();
+        },
+    };
+}

package/dist/game/snapshotHistory.d.ts

@@ -0,0 +1,67 @@
+/** Bounded past/future snapshot stacks — a serializable undo/redo record for any state `T`. */
+export interface HistoryStacks<T> {
+    /** Prior states, oldest first; the last entry is the step an undo restores. */
+    readonly past: readonly T[];
+    /** Undone states awaiting redo, oldest first; the last entry is the step a redo restores. */
+    readonly future: readonly T[];
+}
+/** The snapshot an undo/redo restores plus the advanced stacks. */
+export interface HistoryStep<T> {
+    /** State to apply as the new present. */
+    snapshot: T;
+    /** Stacks after the step. */
+    stacks: HistoryStacks<T>;
+}
+/** Empty history stacks for state `T`.
+ * @internal
+ */
+export declare function emptyHistory<T>(): HistoryStacks<T>;
+/** True when there is a prior state to undo to.
+ * @internal
+ */
+export declare function canUndo<T>(stacks: HistoryStacks<T>): boolean;
+/** True when there is an undone state to redo.
+ * @internal
+ */
+export declare function canRedo<T>(stacks: HistoryStacks<T>): boolean;
+/**
+ * Record `present` as the newest undo step and clear the redo future (a fresh action forks history).
+ * The oldest past entries beyond `limit` are dropped so the stack stays bounded for save/transport.
+  * @internal
+  */
+export declare function recordSnapshot<T>(stacks: HistoryStacks<T>, present: T, limit?: number): HistoryStacks<T>;
+/**
+ * Step back: pop the newest past snapshot to apply as the new present, and push the given `present`
+ * onto the future for a later redo. Returns `null` when there is nothing to undo.
+  * @internal
+  */
+export declare function undoSnapshot<T>(stacks: HistoryStacks<T>, present: T): HistoryStep<T> | null;
+/**
+ * Step forward: pop the newest future snapshot to apply as the new present, and push the given
+ * `present` back onto the past. Returns `null` when there is nothing to redo.
+  * @internal
+  */
+export declare function redoSnapshot<T>(stacks: HistoryStacks<T>, present: T): HistoryStep<T> | null;
+/** Stateful undo/redo handle over {@link HistoryStacks}, holding the stacks in a closure. */
+export interface SnapshotHistory<T> {
+    /** Record `present` as a new undo step and clear the redo future. */
+    record(present: T): void;
+    /** Undo, returning the restored snapshot or `null` if there is nothing to undo. */
+    undo(present: T): T | null;
+    /** Redo, returning the restored snapshot or `null` if there is nothing to redo. */
+    redo(present: T): T | null;
+    /** True when an undo is available. */
+    canUndo(): boolean;
+    /** True when a redo is available. */
+    canRedo(): boolean;
+    /** Drop all history. */
+    clear(): void;
+    /** Current immutable stacks (for serialization). */
+    stacks(): HistoryStacks<T>;
+}
+/**
+ * Stateful undo/redo handle wrapping the pure snapshot functions. Call `record(state)` before each
+ * mutation; `undo`/`redo` return the state to apply. `limit` bounds the past stack.
+  * @internal
+  */
+export declare function createSnapshotHistory<T>(limit?: number): SnapshotHistory<T>;

package/dist/game/snapshotHistory.js

@@ -0,0 +1,95 @@
+/** Empty history stacks for state `T`.
+ * @internal
+ */
+export function emptyHistory() {
+    return { past: [], future: [] };
+}
+/** True when there is a prior state to undo to.
+ * @internal
+ */
+export function canUndo(stacks) {
+    return stacks.past.length > 0;
+}
+/** True when there is an undone state to redo.
+ * @internal
+ */
+export function canRedo(stacks) {
+    return stacks.future.length > 0;
+}
+/**
+ * Record `present` as the newest undo step and clear the redo future (a fresh action forks history).
+ * The oldest past entries beyond `limit` are dropped so the stack stays bounded for save/transport.
+  * @internal
+  */
+export function recordSnapshot(stacks, present, limit = 100) {
+    const past = [...stacks.past, present];
+    const trimmed = limit > 0 && past.length > limit ? past.slice(past.length - limit) : past;
+    return { past: trimmed, future: [] };
+}
+/**
+ * Step back: pop the newest past snapshot to apply as the new present, and push the given `present`
+ * onto the future for a later redo. Returns `null` when there is nothing to undo.
+  * @internal
+  */
+export function undoSnapshot(stacks, present) {
+    if (stacks.past.length === 0)
+        return null;
+    const snapshot = stacks.past[stacks.past.length - 1];
+    return {
+        snapshot,
+        stacks: { past: stacks.past.slice(0, -1), future: [...stacks.future, present] },
+    };
+}
+/**
+ * Step forward: pop the newest future snapshot to apply as the new present, and push the given
+ * `present` back onto the past. Returns `null` when there is nothing to redo.
+  * @internal
+  */
+export function redoSnapshot(stacks, present) {
+    if (stacks.future.length === 0)
+        return null;
+    const snapshot = stacks.future[stacks.future.length - 1];
+    return {
+        snapshot,
+        stacks: { past: [...stacks.past, present], future: stacks.future.slice(0, -1) },
+    };
+}
+/**
+ * Stateful undo/redo handle wrapping the pure snapshot functions. Call `record(state)` before each
+ * mutation; `undo`/`redo` return the state to apply. `limit` bounds the past stack.
+  * @internal
+  */
+export function createSnapshotHistory(limit = 100) {
+    let stacks = emptyHistory();
+    return {
+        record(present) {
+            stacks = recordSnapshot(stacks, present, limit);
+        },
+        undo(present) {
+            const step = undoSnapshot(stacks, present);
+            if (step === null)
+                return null;
+            stacks = step.stacks;
+            return step.snapshot;
+        },
+        redo(present) {
+            const step = redoSnapshot(stacks, present);
+            if (step === null)
+                return null;
+            stacks = step.stacks;
+            return step.snapshot;
+        },
+        canUndo() {
+            return canUndo(stacks);
+        },
+        canRedo() {
+            return canRedo(stacks);
+        },
+        clear() {
+            stacks = emptyHistory();
+        },
+        stacks() {
+            return stacks;
+        },
+    };
+}

package/dist/game/social.d.ts

@@ -135,6 +135,36 @@ export interface WorldInvites {
     decline(userId: string, inviteId: string): void;
     listFor(userId: string): WorldInvite[];
 }
+/** One party's replicated membership — id, current leader, and ordered member ids. */
+export interface SocialPartySnapshot {
+    id: string;
+    leader: string;
+    members: string[];
+}
+/**
+ * Full friends/party/world-invite state as one serializable baseline — the host→client replication
+ * payload behind the `social` snapshot module. Presence and emotes are derived from live deps, not stored.
+ */
+export interface SocialSnapshot {
+    friendships: Record<string, string[]>;
+    blocked: Record<string, string[]>;
+    friendRequests: Record<string, {
+        from: string;
+        to: string;
+    }>;
+    requestCounter: number;
+    partyConfig: PartyConfig | null;
+    parties: SocialPartySnapshot[];
+    partyInvites: Record<string, {
+        from: string;
+        to: string;
+        createdAt: number;
+    }>;
+    partyCounter: number;
+    inviteCounter: number;
+    worldInvites: WorldInvite[];
+    worldInviteCounter: number;
+}
 export interface Social {
     friends: Friends;
     party: Party;
@@ -143,5 +173,12 @@ export interface Social {
     };
     emotes: Emotes;
     worldInvites: WorldInvites;
-}
+    snapshot(): SocialSnapshot;
+    hydrate(data: SocialSnapshot): void;
+}
+/**
+ * Emotes and lightweight social interactions between nearby players.
+ *
+ * @capability social-emotes emotes and social interactions between nearby players
+ */
 export declare function createSocial(deps: SocialDeps): Social;