@datamoc/mw_games 0.1.2 → 0.2.1

package/dist/core/Loading.js

@@ -0,0 +1,102 @@
+import { Signal } from './Signal.js';
+/**
+ * Runs named, weighted asynchronous work while exposing truthful loading progress.
+ *
+ * Tasks run in order, which makes dependency ordering explicit and leaves a game free to
+ * start independent work concurrently inside one task. A task that cannot measure itself
+ * simply never calls `report`, so consumers can display an indeterminate current stage
+ * instead of inventing a percentage.
+ */
+export class LoadQueue {
+    constructor() {
+        this.changed = new Signal();
+        this.tasks = [];
+        this.progress = new Map();
+        this.status_ = 'idle';
+        this.current_ = null;
+        this.error_ = null;
+        this.cancelled = false;
+    }
+    add(task) {
+        if (!task.id)
+            throw new Error('load task needs an id');
+        if (this.tasks.some((candidate) => candidate.id === task.id))
+            throw new Error(`duplicate load task "${task.id}"`);
+        if (task.weight !== undefined && !(task.weight > 0))
+            throw new Error('load task weight must be positive');
+        if (this.status_ === 'loading')
+            throw new Error('cannot add a task while loading');
+        this.tasks.push(task);
+        this.progress.set(task.id, 0);
+        this.emit();
+        return this;
+    }
+    get snapshot() {
+        const total = this.tasks.reduce((sum, task) => sum + (task.weight ?? 1), 0);
+        const complete = this.tasks.reduce((sum, task) => sum + (task.weight ?? 1) * (this.progress.get(task.id) ?? 0), 0);
+        return { status: this.status_, completed: complete, total, current: this.current_, error: this.error_ };
+    }
+    /** starts queued work and resolves only after every task succeeds */
+    async start() {
+        if (this.status_ === 'loading')
+            throw new Error('load queue is already running');
+        this.status_ = 'loading';
+        this.cancelled = false;
+        this.error_ = null;
+        this.emit();
+        try {
+            for (const task of this.tasks) {
+                if (this.cancelled)
+                    break;
+                this.current_ = task.id;
+                this.emit();
+                const queue = this;
+                await task.run({
+                    get cancelled() {
+                        return queue.cancelled;
+                    },
+                    report: (fraction) => this.report(task.id, fraction),
+                });
+                if (!this.cancelled)
+                    this.report(task.id, 1);
+            }
+            this.current_ = null;
+            this.status_ = this.cancelled ? 'cancelled' : 'ready';
+            this.emit();
+        }
+        catch (error) {
+            this.current_ = null;
+            this.error_ = error;
+            this.status_ = 'failed';
+            this.emit();
+            throw error;
+        }
+    }
+    /** asks the current task to stop; cancellation is cooperative */
+    cancel() {
+        if (this.status_ === 'loading')
+            this.cancelled = true;
+    }
+    /** clears failure/cancellation state and task progress for a new attempt */
+    retry() {
+        if (this.status_ === 'loading')
+            throw new Error('cannot retry while loading');
+        this.status_ = 'idle';
+        this.current_ = null;
+        this.error_ = null;
+        this.cancelled = false;
+        for (const task of this.tasks)
+            this.progress.set(task.id, 0);
+        this.emit();
+    }
+    report(id, fraction) {
+        if (!Number.isFinite(fraction))
+            throw new Error('load progress must be finite');
+        this.progress.set(id, Math.max(0, Math.min(1, fraction)));
+        this.emit();
+    }
+    emit() {
+        this.changed.dispatch(this.snapshot);
+    }
+}
+//# sourceMappingURL=Loading.js.map

package/dist/core/Loading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Loading.js","sourceRoot":"","sources":["../../src/core/Loading.ts"],"names":[],"mappings":"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"}

package/dist/core/News.d.ts

@@ -0,0 +1,46 @@
+import { type SaveStorage } from './Save.ts';
+/**
+ * Fetches a game's own news/announcements feed - the inbound counterpart to
+ * `FeedbackClient`, following the same injectable-transport shape (a game's own HTTPS
+ * endpoint, no backend shipped or assumed) rather than a second pattern.
+ */
+export interface NewsItem {
+    id: string;
+    title: string;
+    body: string;
+    publishedAt?: number;
+}
+export interface NewsOptions {
+    endpoint: string;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+export declare class NewsClient {
+    private readonly endpoint;
+    private readonly timeoutMs;
+    private readonly fetchFn;
+    constructor(options: NewsOptions);
+    /**
+     * Fetches and validates the feed; a malformed item throws rather than reaching a game as
+     * trusted data. The response is read as text and run through `sanitizeInboundText`
+     * (a size cap, no embedded control characters) before `JSON.parse` ever sees it, ahead of
+     * `normalizeItem`'s own per-field shape check below.
+     */
+    fetchItems(): Promise<NewsItem[]>;
+}
+export interface NewsSeenOptions {
+    namespace: string;
+    storage?: SaveStorage;
+}
+/** which news items a player has already dismissed, so a returning player is not shown the same announcement forever */
+export declare class NewsSeenTracker {
+    private readonly storage;
+    private readonly key;
+    constructor(options: NewsSeenOptions);
+    private readSeen;
+    isSeen(id: string): boolean;
+    markSeen(id: string): void;
+    /** `items` filtered down to whichever have not been marked seen yet */
+    unseen(items: readonly NewsItem[]): NewsItem[];
+}
+//# sourceMappingURL=News.d.ts.map

package/dist/core/News.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"News.d.ts","sourceRoot":"","sources":["../../src/core/News.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7D;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAChC;AAED,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD,YAAY,OAAO,EAAE,WAAW,EAO/B;IAED;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAYtC;CACD;AAgBD,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wHAAwH;AACxH,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,YAAY,OAAO,EAAE,eAAe,EAGnC;IAED,OAAO,CAAC,QAAQ;IAKhB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1B;IAED,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAIzB;IAED,uEAAuE;IACvE,MAAM,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAG7C;CACD"}

package/dist/core/News.js

@@ -0,0 +1,79 @@
+import { defaultStorage } from './Save.js';
+import { sanitizeInboundText } from './Sanitize.js';
+export class NewsClient {
+    constructor(options) {
+        if (!options.endpoint)
+            throw new Error('news endpoint is required');
+        this.endpoint = options.endpoint;
+        this.timeoutMs = options.timeoutMs ?? 10000;
+        if (!(this.timeoutMs > 0))
+            throw new Error('news timeout must be positive');
+        this.fetchFn = options.fetch ?? globalThis.fetch;
+        if (!this.fetchFn)
+            throw new Error('fetch is unavailable; provide NewsOptions.fetch');
+    }
+    /**
+     * Fetches and validates the feed; a malformed item throws rather than reaching a game as
+     * trusted data. The response is read as text and run through `sanitizeInboundText`
+     * (a size cap, no embedded control characters) before `JSON.parse` ever sees it, ahead of
+     * `normalizeItem`'s own per-field shape check below.
+     */
+    async fetchItems() {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetchFn(this.endpoint, { signal: controller.signal });
+            if (!response.ok)
+                throw new Error(`news request failed with HTTP ${response.status}`);
+            const data = JSON.parse(sanitizeInboundText(await response.text()));
+            if (!Array.isArray(data))
+                throw new Error('news response was not an array');
+            return data.map((raw, index) => normalizeItem(raw, index));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function normalizeItem(raw, index) {
+    if (typeof raw !== 'object' || raw === null)
+        throw new Error(`news item ${index} was not an object`);
+    const item = raw;
+    if (typeof item.id !== 'string' || !item.id)
+        throw new Error(`news item ${index} is missing a string id`);
+    if (typeof item.title !== 'string')
+        throw new Error(`news item ${index} is missing a string title`);
+    if (typeof item.body !== 'string')
+        throw new Error(`news item ${index} is missing a string body`);
+    return {
+        id: item.id,
+        title: item.title,
+        body: item.body,
+        publishedAt: typeof item.publishedAt === 'number' ? item.publishedAt : undefined,
+    };
+}
+/** which news items a player has already dismissed, so a returning player is not shown the same announcement forever */
+export class NewsSeenTracker {
+    constructor(options) {
+        this.storage = options.storage ?? defaultStorage();
+        this.key = `mwg-news-seen:${options.namespace}`;
+    }
+    readSeen() {
+        const raw = this.storage.read(this.key);
+        return new Set(raw ? JSON.parse(raw) : []);
+    }
+    isSeen(id) {
+        return this.readSeen().has(id);
+    }
+    markSeen(id) {
+        const seen = this.readSeen();
+        seen.add(id);
+        this.storage.write(this.key, JSON.stringify([...seen]));
+    }
+    /** `items` filtered down to whichever have not been marked seen yet */
+    unseen(items) {
+        const seen = this.readSeen();
+        return items.filter((item) => !seen.has(item.id));
+    }
+}
+//# sourceMappingURL=News.js.map

package/dist/core/News.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"News.js","sourceRoot":"","sources":["../../src/core/News.ts"],"names":[],"mappings":"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"}

package/dist/core/PlayerInput.d.ts

@@ -0,0 +1,38 @@
+import type { Action } from './Input.ts';
+export interface PlayerInputOptions {
+    /** this player's own gamepad, when they have one; omit for a keyboard-only player */
+    padIndex?: number;
+}
+/**
+ * A player-scoped view over `mwg/core`'s `Input` module for same-screen local multiplayer.
+ *
+ * `Input` has no concept of a player: `Action` is a bare string, and its `bindings`/`held`/
+ * `onAction` all live at module scope. Binding the same action name to two pads directly -
+ * `Input.bindButton('confirm', 0, [0])` and `Input.bindButton('confirm', 1, [0])` - does not
+ * give two independent "confirm"s; both bindings land in the very same action's key set, so
+ * either pad pressing it fires the one shared `onAction`, with no way to tell which pad did.
+ *
+ * This does not change `Input` itself - it is a thin, purely additive naming convention:
+ * every action a `PlayerInput` binds or queries is transparently prefixed with this
+ * player's own `id`, so two players' "confirm" become two distinct actions
+ * (`"p1:confirm"`, `"p2:confirm"`) that never collide. A single-player game using `Input`'s
+ * bare action names directly is entirely unaffected.
+ */
+export declare class PlayerInput {
+    readonly id: string;
+    readonly padIndex?: number;
+    constructor(id: string, options?: PlayerInputOptions);
+    private scoped;
+    /** binds this player's own action to keyboard keys, independent of any other player's binding for the same action name */
+    bind(action: Action, keys: readonly string[]): void;
+    /** binds this player's own action to a button on their own `padIndex` */
+    bindButton(action: Action, buttons: readonly number[]): void;
+    /** binds this player's own action to an axis direction on their own `padIndex` */
+    bindAxis(action: Action, axis: number, direction: 1 | -1): void;
+    isDown(action: Action): boolean;
+    justPressed(action: Action): boolean;
+    justReleased(action: Action): boolean;
+    /** every key/pad binding for this player's own action, in the same shape `Input.exportBindings` uses */
+    keysFor(action: Action): string[];
+}
+//# sourceMappingURL=PlayerInput.d.ts.map

package/dist/core/PlayerInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayerInput.d.ts","sourceRoot":"","sources":["../../src/core/PlayerInput.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,WAAW,kBAAkB;IAClC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAW;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,YAAY,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,EAIvD;IAED,OAAO,CAAC,MAAM;IAId,0HAA0H;IAC1H,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAElD;IAED,yEAAyE;IACzE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAG3D;IAED,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAG9D;IAED,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE9B;IAED,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnC;IAED,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEpC;IAED,wGAAwG;IACxG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAEhC;CACD"}

package/dist/core/PlayerInput.js

@@ -0,0 +1,57 @@
+import * as Input from './Input.js';
+/**
+ * A player-scoped view over `mwg/core`'s `Input` module for same-screen local multiplayer.
+ *
+ * `Input` has no concept of a player: `Action` is a bare string, and its `bindings`/`held`/
+ * `onAction` all live at module scope. Binding the same action name to two pads directly -
+ * `Input.bindButton('confirm', 0, [0])` and `Input.bindButton('confirm', 1, [0])` - does not
+ * give two independent "confirm"s; both bindings land in the very same action's key set, so
+ * either pad pressing it fires the one shared `onAction`, with no way to tell which pad did.
+ *
+ * This does not change `Input` itself - it is a thin, purely additive naming convention:
+ * every action a `PlayerInput` binds or queries is transparently prefixed with this
+ * player's own `id`, so two players' "confirm" become two distinct actions
+ * (`"p1:confirm"`, `"p2:confirm"`) that never collide. A single-player game using `Input`'s
+ * bare action names directly is entirely unaffected.
+ */
+export class PlayerInput {
+    constructor(id, options = {}) {
+        if (!id)
+            throw new Error('a player needs a non-empty id');
+        this.id = id;
+        this.padIndex = options.padIndex;
+    }
+    scoped(action) {
+        return `${this.id}:${action}`;
+    }
+    /** binds this player's own action to keyboard keys, independent of any other player's binding for the same action name */
+    bind(action, keys) {
+        Input.bind(this.scoped(action), keys);
+    }
+    /** binds this player's own action to a button on their own `padIndex` */
+    bindButton(action, buttons) {
+        if (this.padIndex === undefined)
+            throw new Error(`player "${this.id}" has no padIndex to bind a gamepad button to`);
+        Input.bindButton(this.scoped(action), this.padIndex, buttons);
+    }
+    /** binds this player's own action to an axis direction on their own `padIndex` */
+    bindAxis(action, axis, direction) {
+        if (this.padIndex === undefined)
+            throw new Error(`player "${this.id}" has no padIndex to bind a gamepad axis to`);
+        Input.bindAxis(this.scoped(action), this.padIndex, axis, direction);
+    }
+    isDown(action) {
+        return Input.isDown(this.scoped(action));
+    }
+    justPressed(action) {
+        return Input.justPressed(this.scoped(action));
+    }
+    justReleased(action) {
+        return Input.justReleased(this.scoped(action));
+    }
+    /** every key/pad binding for this player's own action, in the same shape `Input.exportBindings` uses */
+    keysFor(action) {
+        return Input.keysFor(this.scoped(action));
+    }
+}
+//# sourceMappingURL=PlayerInput.js.map

package/dist/core/PlayerInput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayerInput.js","sourceRoot":"","sources":["../../src/core/PlayerInput.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AAQpC;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,WAAW;IAIvB,YAAY,EAAU,EAAE,OAAO,GAAuB,EAAE;QACvD,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QAC1D,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,CAAC;IAEO,MAAM,CAAC,MAAc;QAC5B,OAAO,GAAG,IAAI,CAAC,EAAE,IAAI,MAAM,EAAE,CAAC;IAC/B,CAAC;IAED,0HAA0H;IAC1H,IAAI,CAAC,MAAc,EAAE,IAAuB;QAC3C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC;IAED,yEAAyE;IACzE,UAAU,CAAC,MAAc,EAAE,OAA0B;QACpD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,CAAC,EAAE,+CAA+C,CAAC,CAAC;QACpH,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC/D,CAAC;IAED,kFAAkF;IAClF,QAAQ,CAAC,MAAc,EAAE,IAAY,EAAE,SAAiB;QACvD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,CAAC,EAAE,6CAA6C,CAAC,CAAC;QAClH,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,CAAC,MAAc;QACpB,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,WAAW,CAAC,MAAc;QACzB,OAAO,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,YAAY,CAAC,MAAc;QAC1B,OAAO,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,wGAAwG;IACxG,OAAO,CAAC,MAAc;QACrB,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3C,CAAC;CACD"}

package/dist/core/RunHistory.d.ts

@@ -0,0 +1,43 @@
+import { type SaveStorage } from './Save.ts';
+/**
+ * A personal, local record of completed runs - what `core.Session` (launch count) and
+ * `core.Achievements` (derived unlocks, no per-run record) don't keep, and distinct from
+ * `SaveSystem.list()`, which enumerates *continuable* slots, not runs already over.
+ *
+ * `mwg` stays agnostic about what a run's own report actually contains, the same way
+ * `SaveSystem` stays agnostic about what "the save" contains: a game supplies its own
+ * `summary` shape (score, cause of death, floor reached, whatever it considers a run's own
+ * stats) and this only ever stores, lists, and sorts it.
+ */
+export interface RunHistoryEntry<T> {
+    id: string;
+    endedAt: number;
+    summary: T;
+}
+export interface RunHistoryOptions {
+    /** namespaces the stored history, so two games sharing an origin never collide */
+    namespace: string;
+    storage?: SaveStorage;
+    /** oldest runs are dropped once this many are stored; omit for unlimited */
+    limit?: number;
+}
+export declare class RunHistory<T> {
+    private readonly storage;
+    private readonly limit?;
+    private readonly key;
+    constructor(options: RunHistoryOptions);
+    private readAll;
+    /** appends a completed run's summary, oldest first; drops the oldest entry once `limit` is exceeded */
+    record(summary: T): RunHistoryEntry<T>;
+    /** every recorded run, oldest first */
+    all(): readonly RunHistoryEntry<T>[];
+    /**
+     * Every recorded run sorted by a field of its own summary - explicitly a local, personal
+     * ranking over this player's own history, not a networked leaderboard comparing players
+     * against each other, which `mwg` does not attempt here.
+     */
+    ranked(by: (summary: T) => number, order?: 'asc' | 'desc'): readonly RunHistoryEntry<T>[];
+    /** drops every recorded run */
+    clear(): void;
+}
+//# sourceMappingURL=RunHistory.d.ts.map

package/dist/core/RunHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunHistory.d.ts","sourceRoot":"","sources":["../../src/core/RunHistory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,CAAC,CAAC;CACX;AAED,MAAM,WAAW,iBAAiB;IACjC,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,UAAU,CAAC,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,YAAY,OAAO,EAAE,iBAAiB,EAIrC;IAED,OAAO,CAAC,OAAO;IAKf,uGAAuG;IACvG,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAOrC;IAED,uCAAuC;IACvC,GAAG,IAAI,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,CAEnC;IAED;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,MAAM,EAAE,KAAK,GAAE,KAAK,GAAG,MAAe,GAAG,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,CAIhG;IAED,+BAA+B;IAC/B,KAAK,IAAI,IAAI,CAEZ;CACD"}

package/dist/core/RunHistory.js

@@ -0,0 +1,41 @@
+import { defaultStorage } from './Save.js';
+export class RunHistory {
+    constructor(options) {
+        this.storage = options.storage ?? defaultStorage();
+        this.limit = options.limit;
+        this.key = `mwg-runs:${options.namespace}`;
+    }
+    readAll() {
+        const raw = this.storage.read(this.key);
+        return raw ? JSON.parse(raw) : [];
+    }
+    /** appends a completed run's summary, oldest first; drops the oldest entry once `limit` is exceeded */
+    record(summary) {
+        const entries = this.readAll();
+        const entry = { id: `${Date.now()}-${entries.length}`, endedAt: Date.now(), summary };
+        entries.push(entry);
+        if (this.limit !== undefined && entries.length > this.limit)
+            entries.splice(0, entries.length - this.limit);
+        this.storage.write(this.key, JSON.stringify(entries));
+        return entry;
+    }
+    /** every recorded run, oldest first */
+    all() {
+        return this.readAll();
+    }
+    /**
+     * Every recorded run sorted by a field of its own summary - explicitly a local, personal
+     * ranking over this player's own history, not a networked leaderboard comparing players
+     * against each other, which `mwg` does not attempt here.
+     */
+    ranked(by, order = 'desc') {
+        const entries = this.readAll();
+        const sign = order === 'desc' ? -1 : 1;
+        return entries.sort((a, b) => sign * (by(a.summary) - by(b.summary)));
+    }
+    /** drops every recorded run */
+    clear() {
+        this.storage.remove(this.key);
+    }
+}
+//# sourceMappingURL=RunHistory.js.map

package/dist/core/RunHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunHistory.js","sourceRoot":"","sources":["../../src/core/RunHistory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAoB,MAAM,WAAW,CAAC;AA0B7D,MAAM,OAAO,UAAU;IAKtB,YAAY,OAA0B;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,cAAc,EAAE,CAAC;QACnD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,GAAG,GAAG,YAAY,OAAO,CAAC,SAAS,EAAE,CAAC;IAC5C,CAAC;IAEO,OAAO;QACd,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxC,OAAO,GAAG,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAA0B,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,CAAC;IAED,uGAAuG;IACvG,MAAM,CAAC,OAAU;QAChB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAuB,EAAE,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,CAAC;QAC1G,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK;YAAE,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5G,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QACtD,OAAO,KAAK,CAAC;IACd,CAAC;IAED,uCAAuC;IACvC,GAAG;QACF,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,EAA0B,EAAE,KAAK,GAAmB,MAAM;QAChE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACvE,CAAC;IAED,+BAA+B;IAC/B,KAAK;QACJ,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;CACD"}

package/dist/core/Sanitize.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Cheap, structural checks over inbound data - a save imported from another device or
+ * server (`SaveSystem.importSlot`), a news feed response (`NewsClient`), an external save
+ * format (`rpg.decodeMarshal`) - run before any of it is parsed or handed to a game as
+ * trusted state. Deliberately narrow: a size cap and a control-character check catch a
+ * truncated, corrupted, or hostile payload cheaply, ahead of and distinct from validating
+ * that a parsed value's own fields have the shape a game actually expects (`validateSchema`,
+ * below), which is a separate, deeper pass over already-parsed data.
+ */
+export interface SizeLimitOptions {
+    /** bytes; defaults to 10 MB */
+    maxBytes?: number;
+}
+/** throws once `data`'s size (UTF-8 byte length for a string, byte length for a buffer) exceeds the cap */
+export declare function checkSize(data: string | Uint8Array, options?: SizeLimitOptions): void;
+/**
+ * Throws on an embedded NUL byte or a control character outside ordinary whitespace
+ * (tab, newline, carriage return) - the kind of byte a well-formed save or news response
+ * never legitimately contains, and a cheap tell that a payload was truncated, corrupted, or
+ * deliberately malformed before it ever reaches `JSON.parse`.
+ */
+export declare function checkNoControlCharacters(text: string): void;
+/** `checkSize` then `checkNoControlCharacters` - the minimum bar before any inbound text is parsed */
+export declare function sanitizeInboundText(text: string, options?: SizeLimitOptions): string;
+/**
+ * A small schema for validating an already-parsed value's shape - deliberately not a full
+ * JSON Schema implementation, only what `SaveSystem`/`NewsClient`-shaped data actually needs:
+ * primitives, arrays, and objects, with `__proto__`/`constructor`/`prototype` keys always
+ * rejected regardless of what a schema itself asks for, since no legitimate save or feed
+ * payload ever needs to set one and a parsed JSON object having one is exactly the
+ * prototype-pollution shape this exists to catch.
+ */
+export type Schema = {
+    type: 'string';
+    optional?: boolean;
+} | {
+    type: 'number';
+    optional?: boolean;
+    min?: number;
+    max?: number;
+} | {
+    type: 'boolean';
+    optional?: boolean;
+} | {
+    type: 'object';
+    optional?: boolean;
+    fields: Record<string, Schema>;
+} | {
+    type: 'array';
+    optional?: boolean;
+    items: Schema;
+    maxLength?: number;
+};
+/** throws with a path-qualified message at the first field that does not match `schema` */
+export declare function validateSchema(value: unknown, schema: Schema, path?: string): void;
+//# sourceMappingURL=Sanitize.d.ts.map

package/dist/core/Sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sanitize.d.ts","sourceRoot":"","sources":["../../src/core/Sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,gBAAgB;IAChC,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,2GAA2G;AAC3G,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,GAAE,gBAAqB,GAAG,IAAI,CAIzF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQ3D;AAED,sGAAsG;AACtG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAIxF;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GACf;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAI5E,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,SAAM,GAAG,IAAI,CAoC/E"}

package/dist/core/Sanitize.js

@@ -0,0 +1,87 @@
+/**
+ * Cheap, structural checks over inbound data - a save imported from another device or
+ * server (`SaveSystem.importSlot`), a news feed response (`NewsClient`), an external save
+ * format (`rpg.decodeMarshal`) - run before any of it is parsed or handed to a game as
+ * trusted state. Deliberately narrow: a size cap and a control-character check catch a
+ * truncated, corrupted, or hostile payload cheaply, ahead of and distinct from validating
+ * that a parsed value's own fields have the shape a game actually expects (`validateSchema`,
+ * below), which is a separate, deeper pass over already-parsed data.
+ */
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+/** throws once `data`'s size (UTF-8 byte length for a string, byte length for a buffer) exceeds the cap */
+export function checkSize(data, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const size = typeof data === 'string' ? new TextEncoder().encode(data).length : data.length;
+    if (size > maxBytes)
+        throw new Error(`inbound data exceeds the ${maxBytes}-byte limit (${size} bytes)`);
+}
+/**
+ * Throws on an embedded NUL byte or a control character outside ordinary whitespace
+ * (tab, newline, carriage return) - the kind of byte a well-formed save or news response
+ * never legitimately contains, and a cheap tell that a payload was truncated, corrupted, or
+ * deliberately malformed before it ever reaches `JSON.parse`.
+ */
+export function checkNoControlCharacters(text) {
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code === 0x09 || code === 0x0a || code === 0x0d)
+            continue; //tab, LF, CR
+        if (code <= 0x1f || code === 0x7f) {
+            throw new Error(`inbound data contains a control character (0x${code.toString(16).padStart(2, '0')}) at index ${i}`);
+        }
+    }
+}
+/** `checkSize` then `checkNoControlCharacters` - the minimum bar before any inbound text is parsed */
+export function sanitizeInboundText(text, options = {}) {
+    checkSize(text, options);
+    checkNoControlCharacters(text);
+    return text;
+}
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/** throws with a path-qualified message at the first field that does not match `schema` */
+export function validateSchema(value, schema, path = '$') {
+    if (value === undefined) {
+        if (schema.optional)
+            return;
+        throw new Error(`${path} is required`);
+    }
+    switch (schema.type) {
+        case 'string':
+            if (typeof value !== 'string')
+                throw new Error(`${path} must be a string`);
+            return;
+        case 'number':
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                throw new Error(`${path} must be a finite number`);
+            if (schema.min !== undefined && value < schema.min)
+                throw new Error(`${path} must be >= ${schema.min}`);
+            if (schema.max !== undefined && value > schema.max)
+                throw new Error(`${path} must be <= ${schema.max}`);
+            return;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                throw new Error(`${path} must be a boolean`);
+            return;
+        case 'array':
+            if (!Array.isArray(value))
+                throw new Error(`${path} must be an array`);
+            if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+                throw new Error(`${path} exceeds its maximum length of ${schema.maxLength}`);
+            }
+            value.forEach((item, index) => validateSchema(item, schema.items, `${path}[${index}]`));
+            return;
+        case 'object': {
+            if (typeof value !== 'object' || value === null || Array.isArray(value))
+                throw new Error(`${path} must be an object`);
+            for (const key of Object.keys(value)) {
+                if (FORBIDDEN_KEYS.has(key))
+                    throw new Error(`${path} contains a forbidden key "${key}"`);
+            }
+            for (const [key, fieldSchema] of Object.entries(schema.fields)) {
+                validateSchema(value[key], fieldSchema, `${path}.${key}`);
+            }
+            return;
+        }
+    }
+}
+//# sourceMappingURL=Sanitize.js.map

package/dist/core/Sanitize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sanitize.js","sourceRoot":"","sources":["../../src/core/Sanitize.ts"],"names":[],"mappings":"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"}