@arcadible/sdk 1.1.1 → 1.2.0

package/README.md

@@ -46,9 +46,9 @@ const progress = saved ? JSON.parse(saved) : { level: 1 };
 await arcadible.saves.write("progress", JSON.stringify(progress));
 ```
 
-A save is a name holding one string. `ready` settles once the game's saves have loaded, and never fails; from then on, `readSync` answers from memory. Every call that fails rejects (or, for `readSync`, throws) with an `ArcadibleError`, whose `code` says what to do.
+A save is a name holding one string. `ready` settles once the game's saves have loaded, and never fails; from then on, `readSync`, `listSync`, and `infoSync` answer from memory. Every call that fails rejects (or, for the sync calls, throws) with an `ArcadibleError`, whose `code` says what to do. `arcadible.saves.where` says who can read the saves back: every version of the game, only this build, or only until the page closes.
 
-Off Arcadible, such as on your dev server, the package works on its own, with the same rules and limits: saves are kept on the page's own origin, and `arcadible.build` is `null`.
+Off Arcadible, such as on your dev server, the package works on its own, with the same rules and limits: saves are kept on the page's own origin, `arcadible.saves.where` is `"build"`, and `arcadible.build` is `null`.
 
 ## Learn more
 

package/dist/bus/client.d.ts

@@ -1,4 +1,4 @@
-import { type Welcome } from "./protocol.js";
+import { type Shape, type Welcome } from "./protocol.js";
 import type { Server } from "./server.js";
 export type BusOptions = {
     client: string;
@@ -8,9 +8,13 @@ export type BusOptions = {
     requestTimeout?: number | undefined;
     standalone: () => Server;
 };
+export type RequestOptions<T> = {
+    late?: (result: T) => void;
+};
 export type Bus = {
     readonly welcomed: Promise<Welcome>;
-    request(name: string, params?: object): Promise<unknown>;
-    on(name: string, listener: (data: unknown) => void): () => void;
+    request<T>(name: string, params: object | undefined, shape: Shape<T>, options?: RequestOptions<T>): Promise<T>;
+    on<T>(name: string, shape: Shape<T>, listener: (data: T) => void): () => void;
 };
+export declare function mayHaveLanded(err: unknown): boolean;
 export declare function openBus(options: BusOptions): Bus;

package/dist/bus/client.js

@@ -1,8 +1,28 @@
 // The game's end of the bus: it says hello to the play page, and stands
 // alone when no page answers, running the page's end itself, in its own
-// page, so the rules are the same.
+// page, so the rules are the same. It takes nothing the page sends on trust:
+// every call settles, with what its request expects or a code.
 // [import]
-import { ArcadibleError, BUS_VERSION, Codes, HANDSHAKE_TIMEOUT, isHostOrigin, isMessage, isWelcome, REQUEST_TIMEOUT, } from "./protocol.js";
+import { ArcadibleError, BUS_VERSION, Codes, HANDSHAKE_TIMEOUT, isErrorBody, isHostOrigin, isMessage, isWelcome, log, REQUEST_TIMEOUT, } from "./protocol.js";
+// [declare]
+// How many calls that timed out keep waiting for a late answer; past it,
+// the oldest stop.
+const MAX_LATE = 64;
+// failures after which the page may still have done what was asked: a
+// `timeout`, or an answer the game couldn't read.
+const uncertain = new WeakSet();
+// [function]
+// Whether the page may have done what a failed call asked, so a game's
+// memory copy keeps what it showed.
+export function mayHaveLanded(err) {
+    return err instanceof ArcadibleError && uncertain.has(err);
+}
+// [function]
+function unsure(code, message) {
+    const err = new ArcadibleError(code, message);
+    uncertain.add(err);
+    return err;
+}
 // [function]
 export function openBus(options) {
     const win = options.window ?? (typeof window === "undefined" ? undefined : window);
@@ -13,6 +33,7 @@ export function openBus(options) {
     let nextId = 1;
     let handshakeTimer;
     const pending = new Map();
+    const late = new Map();
     const listeners = new Map();
     let welcome = () => undefined;
     const welcomed = new Promise((resolve) => {
@@ -23,22 +44,62 @@ export function openBus(options) {
         const message = event.data;
         if (!isMessage(message))
             return;
-        handle(message);
+        try {
+            handle(message);
+        }
+        catch (err) {
+            log("error", "a message from the play page failed.", err);
+        }
+    };
+    // [function]
+    // a call's answer: settled before anything else is read, so whatever the
+    // page sent, the call ends.
+    const settle = function (call, message) {
+        const error = message["error"];
+        if (error !== undefined) {
+            if (!isErrorBody(error)) {
+                call.reject(unsure(Codes.Unavailable, "The play page's answer was malformed."));
+                return;
+            }
+            const text = error.message;
+            call.reject(new ArcadibleError(error.code, typeof text === "string" ? text : "That failed. Try again."));
+        }
+        else if (call.shape(message["result"])) {
+            call.resolve(message["result"]);
+        }
+        else {
+            call.reject(unsure(Codes.Unavailable, "The play page's answer was malformed."));
+        }
+    };
+    // [function]
+    const answerLate = function (id, message) {
+        const call = late.get(id);
+        if (!call)
+            return;
+        late.delete(id);
+        const result = message["result"];
+        if (message["error"] === undefined && call.shape(result)) {
+            call.late(result);
+        }
     };
     // [function]
     const handle = function (message) {
         if (message.kind === "response") {
             const call = pending.get(message.id);
-            if (!call)
+            if (!call) {
+                answerLate(message.id, message);
                 return;
+            }
             pending.delete(message.id);
             clearTimeout(call.timer);
-            if ("error" in message) {
-                const { code, message: text } = message.error;
-                call.reject(new ArcadibleError(code, text));
+            try {
+                settle(call, message);
             }
-            else {
-                call.resolve(message.result);
+            catch (err) {
+                // `settle` rejects before it could throw; this only keeps a call
+                // from hanging if that ever changes.
+                call.reject(unsure(Codes.Unavailable, "The play page's answer was malformed."));
+                log("error", `${call.name}'s answer couldn't be read.`, err);
             }
         }
         else if (message.kind === "event") {
@@ -71,6 +132,9 @@ export function openBus(options) {
             return;
         state = "standalone";
         win?.removeEventListener("message", onWindowMessage);
+        if (win && win.parent !== win) {
+            log("warn", 'no play page answered within a second, so this game keeps its saves on its own origin, where only this build reads them (saves.where is "build"); reloading usually fixes it.');
+        }
         const channel = new MessageChannel();
         attach(channel.port1, options.standalone().connect(channel.port2));
     };
@@ -101,7 +165,7 @@ export function openBus(options) {
     }
     return {
         welcomed,
-        async request(name, params) {
+        async request(name, params, shape, requestOptions = {}) {
             await welcomed;
             // welcomed, so there's a channel: the play page's, or this page's own.
             const link = port;
@@ -111,22 +175,50 @@ export function openBus(options) {
             const id = nextId++;
             return new Promise((resolve, reject) => {
                 const timer = setTimeout(() => {
+                    const call = pending.get(id);
                     pending.delete(id);
-                    reject(new ArcadibleError(Codes.Timeout, `${name} timed out.`));
+                    if (call?.late) {
+                        late.set(id, { shape: call.shape, late: call.late });
+                        if (late.size > MAX_LATE) {
+                            late.delete(late.keys().next().value);
+                        }
+                    }
+                    reject(unsure(Codes.Timeout, "The play page took too long to answer. Try again."));
                 }, requestTimeout);
-                pending.set(id, { resolve, reject, timer });
+                pending.set(id, {
+                    name,
+                    resolve: resolve,
+                    reject,
+                    timer,
+                    shape,
+                    late: requestOptions.late,
+                });
                 link.postMessage({ kind: "request", id, name, params });
             });
         },
-        on(name, listener) {
+        on(name, shape, listener) {
+            // each listener on its own: one that throws, or data it can't take,
+            // doesn't stop the others.
+            const checked = function (data) {
+                if (!shape(data)) {
+                    log("warn", `ignored a malformed ${name} from the play page.`);
+                    return;
+                }
+                try {
+                    listener(data);
+                }
+                catch (err) {
+                    log("error", `a ${name} listener failed.`, err);
+                }
+            };
             let set = listeners.get(name);
             if (!set) {
                 set = new Set();
                 listeners.set(name, set);
             }
-            set.add(listener);
+            set.add(checked);
             return () => {
-                set.delete(listener);
+                set.delete(checked);
             };
         },
     };

package/dist/bus/protocol.d.ts

@@ -19,7 +19,8 @@ export type Code = (typeof Codes)[keyof typeof Codes];
 /**
  * The build that's running, from the page's own lookup: its version, from
  * `arcadible.toml` or `package.json`, and its channel (`production`,
- * `staging`, or `local` under `arc serve`). `null` standing alone.
+ * `staging`, or `local` under `arc serve`). `null` standing alone, or when
+ * the page doesn't say.
  */
 export type Build = {
     version: string;
@@ -35,6 +36,7 @@ export type Welcome = {
     v: number;
     build: Build | null;
 };
+export type Shape<T> = (value: unknown) => value is T;
 export type ErrorBody = {
     code: string;
     message: string;
@@ -66,8 +68,18 @@ export declare class ArcadibleError extends Error {
     constructor(code: Code, message: string);
     toJSON(): ErrorBody;
 }
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function isString(value: unknown): value is string;
+export declare function isNumber(value: unknown): value is number;
+export declare function isStringOrNull(value: unknown): value is string | null;
+export declare function isStringArray(value: unknown): value is string[];
+export declare function isErrorBody(value: unknown): value is {
+    code: string;
+};
+export declare function log(level: "warn" | "error", sentence: string, ...detail: unknown[]): void;
 export declare function isHello(value: unknown): value is Hello;
 export declare function isWelcome(value: unknown): value is Welcome;
+export declare function buildOf(value: unknown): Build | null;
 export declare function isMessage(value: unknown): value is Message;
 export declare function utf8Size(text: string): number;
 export declare function messageSize(value: unknown, limit?: number): number;

package/dist/bus/protocol.js

@@ -26,8 +26,10 @@ export function isHostOrigin(origin, origins) {
 // The most requests one game can have waiting on the page; past it, a
 // request fails with `busy`.
 export const MAX_IN_FLIGHT = 64;
-// One message, checked by the side that receives it: room for a whole 1 MB
-// save, and the rest of the message.
+// The largest message either side sends: room for a whole 1 MB save, or
+// every save at once (a game's are 1 MB together), and the rest of the
+// message. The page refuses a larger request, and never sends a larger
+// answer or event (DESIGN.md, section 4).
 export const MAX_MESSAGE = 1024 * 1024 + 64 * 1024;
 // [declare]
 // Every code a call can fail with. Worth retrying: `busy`, `timeout`, and
@@ -62,10 +64,38 @@ export class ArcadibleError extends Error {
     }
 }
 // [function]
-function isObject(value) {
+export function isObject(value) {
     return typeof value === "object" && value !== null;
 }
 // [function]
+export function isString(value) {
+    return typeof value === "string";
+}
+// [function]
+export function isNumber(value) {
+    return typeof value === "number";
+}
+// [function]
+export function isStringOrNull(value) {
+    return value === null || typeof value === "string";
+}
+// [function]
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every(isString);
+}
+// [function]
+// What an error is sent as: a string `code`, and a message for people.
+export function isErrorBody(value) {
+    return isObject(value) && typeof value["code"] === "string";
+}
+// [function]
+// The SDK's console line: one sentence after its name, so a developer can
+// tell it from the game's own. `warn` for a degraded state, and `error`
+// only for a bug.
+export function log(level, sentence, ...detail) {
+    console[level](`Arcadible SDK: ${sentence}`, ...detail);
+}
+// [function]
 export function isHello(value) {
     return (isObject(value) &&
         value["arcadible"] === "hello" &&
@@ -79,6 +109,17 @@ export function isWelcome(value) {
         value["v"] === BUS_VERSION);
 }
 // [function]
+// The welcome's build as a game sees it: a copy of just its version and
+// channel, so a page can't add fields games come to depend on, or `null`
+// when the page doesn't say, or says it wrong.
+export function buildOf(value) {
+    return isObject(value) &&
+        typeof value["version"] === "string" &&
+        typeof value["channel"] === "string"
+        ? { version: value["version"], channel: value["channel"] }
+        : null;
+}
+// [function]
 export function isMessage(value) {
     if (!isObject(value))
         return false;

package/dist/bus/server.js

@@ -1,13 +1,14 @@
 // The page's end of the bus: it answers a game's requests with its modules'
 // handlers, one at a time in order, and refuses what's too large, too many,
-// or unknown. `answerHellos` connects it to the play page's iframe.
+// or unknown. It never sends more than `MAX_MESSAGE` either. `answerHellos`
+// connects it to the play page's iframe.
 // [import]
-import { ArcadibleError, BUS_VERSION, Codes, isHello, isMessage, MAX_IN_FLIGHT, MAX_MESSAGE, messageSize, } from "./protocol.js";
+import { ArcadibleError, BUS_VERSION, Codes, isHello, isMessage, log, MAX_IN_FLIGHT, MAX_MESSAGE, messageSize, } from "./protocol.js";
 // [function]
 function errorBody(err) {
     if (err instanceof ArcadibleError)
         return err.toJSON();
-    console.error("arcadible: a request failed:", err);
+    log("error", "a request failed.", err);
     return {
         code: Codes.Unavailable,
         message: "That's unavailable right now. Try again.",
@@ -31,9 +32,20 @@ export function createServer(options) {
         queue = run.catch(() => undefined);
         return run;
     };
+    // nothing goes to a game that's larger than a request may be: the limits
+    // keep every answer and event within it, so one that isn't is a bug.
+    const fits = function (message, what) {
+        if (messageSize(message, MAX_MESSAGE) <= MAX_MESSAGE)
+            return true;
+        log("error", `${what} was too large to send.`);
+        return false;
+    };
     const send = function (port, name, data) {
-        if (ports.has(port))
-            port.postMessage({ kind: "event", name, data });
+        if (!ports.has(port))
+            return;
+        const message = { kind: "event", name, data };
+        if (fits(message, name))
+            port.postMessage(message);
     };
     const modules = options.modules.map((make) => make({
         broadcast(name, data) {
@@ -51,14 +63,22 @@ export function createServer(options) {
         port.postMessage({ kind: "response", id, error });
     };
     // answers each request in `entry`, which counted once toward the limit.
-    const respond = function ({ ids, port }, outcome) {
+    const respond = function ({ ids, name, port }, outcome) {
         const count = inFlight.get(port);
         if (count !== undefined)
             inFlight.set(port, count - 1);
         if (!ports.has(port))
             return;
+        const fitting = "result" in outcome && !fits(outcome, `${name}'s answer`)
+            ? {
+                error: {
+                    code: Codes.Unavailable,
+                    message: "That's unavailable right now. Try again.",
+                },
+            }
+            : outcome;
         for (const id of ids)
-            port.postMessage({ kind: "response", id, ...outcome });
+            port.postMessage({ kind: "response", id, ...fitting });
     };
     const answer = function (port, request) {
         const { id, name } = request;

package/dist/client.d.ts

@@ -8,13 +8,17 @@ export type Ready = {
 export interface Arcadible {
     /** The SDK's own version. */
     readonly version: string;
-    /** Settles once the game's saves have loaded, and never fails. */
+    /**
+     * Settles once the game's saves have loaded, or after 10 seconds if they
+     * haven't, and never fails. It resolves with `build`; each module's own
+     * facts are on the module, such as `saves.where`.
+     */
     readonly ready: Promise<Ready>;
     /**
      * The build that's running, its version and channel, once `ready` has
      * settled: compare a save's `info().version` with it, so as not to
-     * overwrite a save from a newer version. `null` standing alone, off
-     * Arcadible, and `undefined` before.
+     * overwrite a save from a newer version. `null` when nobody says, such as
+     * standing alone, and `undefined` before.
      */
     readonly build: Build | null | undefined;
     /** Saves that carry over between the game's versions. */

package/dist/client.js

@@ -3,14 +3,20 @@
 // same rules in its own page, when no page answers.
 // [import]
 import { openBus } from "./bus/client.js";
-import { REQUEST_TIMEOUT } from "./bus/protocol.js";
+import { buildOf, REQUEST_TIMEOUT } from "./bus/protocol.js";
 import { indexedDBBackend } from "./saves/backend/indexeddb.js";
 import { createSaves } from "./saves/client.js";
 import { serve } from "./host.js";
 import { VERSION } from "./version.js";
-// The scope a game standing alone keeps its saves under, on its own origin.
-// Standing alone there's no version to stamp: saves say `null`.
-const STANDALONE = { game: "standalone", channel: "local", version: null };
+// The scope a game standing alone keeps its saves under, on its own origin,
+// where only this build reads them. Standing alone there's no version to
+// stamp: saves say `null`.
+const STANDALONE = {
+    game: "standalone",
+    channel: "local",
+    version: null,
+    where: "build",
+};
 // [function]
 export function createClient(options = {}) {
     const backend = options.backend ?? (() => indexedDBBackend());
@@ -28,7 +34,7 @@ export function createClient(options = {}) {
     let settled = null;
     // ready once welcomed, and each module's first messages have arrived.
     const ready = Promise.all([bus.welcomed, opened]).then(([welcome]) => {
-        settled = { build: welcome.build ?? null };
+        settled = { build: buildOf(welcome.build) };
         return settled;
     });
     return {

package/dist/host.d.ts

@@ -1,10 +1,12 @@
 import { type Server } from "./bus/server.js";
 import type { Backend } from "./saves/backend/types.js";
+import type { Where } from "./saves/rules.js";
 export type ServeOptions = {
     game: string;
     channel: string;
     version: string | null;
     backend: Backend;
+    where?: Where;
     now?: () => Date;
 };
 type HostOptions = ServeOptions & {

package/dist/host.js

@@ -15,6 +15,7 @@ export function serve(options) {
                 now: options.now ?? (() => new Date()),
                 scope: { game, channel },
                 version,
+                where: options.where ?? "game",
             }),
         ],
     });

package/dist/saves/backend/indexeddb.d.ts

@@ -3,7 +3,6 @@ export type IndexedDBOptions = {
     factory?: IDBFactory | null;
     player?: string;
     persist?: boolean;
-    openTimeout?: number;
 };
 export declare function indexedDBBackend(options?: IndexedDBOptions): Backend & {
     close(): void;

package/dist/saves/backend/indexeddb.js

@@ -1,4 +1,5 @@
 // [import]
+import { ArcadibleError, Codes, log } from "../../bus/protocol.js";
 import { listenersByKey } from "./listeners.js";
 import { memoryBackend } from "./memory.js";
 // [declare]
@@ -12,9 +13,6 @@ const CHANNEL = "arcadible-saves";
 // every save is a guest's for One; a signed-in player's sit beside them
 // later, under their own id, with no migration.
 const GUEST = "guest";
-// how long opening may take before saves are kept in memory instead: some
-// browsers can leave an open hanging.
-const OPEN_TIMEOUT = 5000;
 // [function]
 function settle(request) {
     return new Promise((resolve, reject) => {
@@ -31,9 +29,10 @@ function finish(tx) {
     });
 }
 // [function]
-function open(factory, timeout) {
+// Opens the database, however long it takes: a slow open is waited for,
+// since the saves are late, not gone (the game's calls wait, or time out).
+function open(factory) {
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error("Opening IndexedDB timed out.")), timeout);
         const request = factory.open(DB_NAME, DB_VERSION);
         request.onupgradeneeded = () => {
             const db = request.result;
@@ -45,14 +44,8 @@ function open(factory, timeout) {
             saves.createIndex(BY_SCOPE, ["player", "game", "channel"]);
             db.createObjectStore(GAMES, { keyPath: ["player", "game", "channel"] });
         };
-        request.onsuccess = () => {
-            clearTimeout(timer);
-            resolve(request.result);
-        };
-        request.onerror = () => {
-            clearTimeout(timer);
-            reject(request.error);
-        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
     });
 }
 // [function]
@@ -69,8 +62,11 @@ function isClosed(err) {
 }
 // [function]
 // Saves kept in IndexedDB: the play page's, which every game shares, and a
-// game standing alone on its own origin. Where IndexedDB won't open, such as
-// some `file://` pages, they're kept in memory, and `status()` says so.
+// game standing alone on its own origin. Where there's no IndexedDB, or it
+// refuses to open (a browser blocking site data, some `file://` pages),
+// they're kept in memory, and `status()` says so. Once it has opened, it
+// never switches: a lost connection fails calls with `unavailable` until it
+// opens again, rather than show an empty copy.
 export function indexedDBBackend(options = {}) {
     const factory = options.factory === undefined
         ? (globalThis.indexedDB ?? null)
@@ -78,35 +74,64 @@ export function indexedDBBackend(options = {}) {
     const player = options.player ?? GUEST;
     const fallback = memoryBackend();
     const listeners = listenersByKey();
-    let status = "local";
+    // memory only when the first open fails; never once it has opened.
+    let status = "device";
+    let opened = false;
+    let current = null;
+    let opening = null;
     let asked = false;
     const keyOf = (scope) => `${player}\u0000${scope.game}\u0000${scope.channel}`;
     const rangeOf = (scope) => IDBKeyRange.only([player, scope.game, scope.channel]);
+    const lost = function (db) {
+        if (current === db)
+            current = null;
+    };
     const connect = async function () {
         try {
             if (!factory)
                 throw new Error("IndexedDB isn't available here.");
-            const db = await open(factory, options.openTimeout ?? OPEN_TIMEOUT);
+            const db = await open(factory);
             // a newer version of this page wants to upgrade: step aside.
-            db.onversionchange = () => db.close();
+            db.onversionchange = () => {
+                db.close();
+                lost(db);
+            };
+            // the browser closed it under us (Safari can).
+            db.onclose = () => lost(db);
             if (options.persist && !asked) {
                 asked = true;
                 globalThis.navigator?.storage?.persist?.().catch(() => false);
             }
+            opened = true;
+            current = db;
             return db;
         }
         catch (err) {
-            console.warn("arcadible: saves are kept in memory only:", err);
-            status = "ephemeral";
+            if (opened) {
+                log("warn", "the saves' storage couldn't be opened again.", err);
+                throw new ArcadibleError(Codes.Unavailable, "Saves can't be reached right now. Try again.");
+            }
+            log("warn", "this browser won't keep saves here, so they're kept in memory until the page closes.", err);
+            status = "memory";
             return null;
         }
+        finally {
+            opening = null;
+        }
+    };
+    // the database, opening it once however many ask; null in memory.
+    const database = function () {
+        if (status === "memory")
+            return Promise.resolve(null);
+        if (current)
+            return Promise.resolve(current);
+        opening ??= connect();
+        return opening;
     };
-    let opening = connect();
     // runs `op` on the database, opening it again once if it was closed, or
     // on the memory fallback when there's none.
     const run = async function (op, otherwise) {
-        const current = opening;
-        const db = await current;
+        const db = await database();
         if (!db)
             return otherwise();
         try {
@@ -115,13 +140,12 @@ export function indexedDBBackend(options = {}) {
         catch (err) {
             if (!isClosed(err))
                 throw err;
-            // once, however many operations found it closed.
-            if (opening === current)
-                opening = connect();
-            const again = await opening;
+            lost(db);
+            const again = await database();
             return again ? op(again) : otherwise();
         }
     };
+    database().catch(() => undefined);
     const broadcast = typeof BroadcastChannel === "undefined"
         ? null
         : new BroadcastChannel(CHANNEL);
@@ -218,7 +242,8 @@ export function indexedDBBackend(options = {}) {
         },
         close() {
             broadcast?.close();
-            opening.then((db) => db?.close()).catch(() => undefined);
+            current?.close();
+            opening?.then((db) => db?.close()).catch(() => undefined);
         },
     };
 }

package/dist/saves/backend/listeners.js

@@ -1,4 +1,5 @@
 // [import]
+import { log } from "../../bus/protocol.js";
 // [function]
 // Each game's subscribers, by key, for a backend to tell of changes. Each
 // gets its own copy, so one can't change what the next one sees, and one
@@ -25,7 +26,7 @@ export function listenersByKey() {
                     listener(structuredClone(change), source);
                 }
                 catch (err) {
-                    console.error("arcadible: a change's listener failed:", err);
+                    log("error", "a change's listener failed.", err);
                 }
             }
         },

package/dist/saves/backend/memory.d.ts

@@ -1,7 +1,7 @@
-import type { SaveStatus } from "../rules.js";
+import type { BackendStatus } from "../rules.js";
 import type { Backend, Scope } from "./types.js";
 export declare function memoryBackend({ status, }?: {
-    status?: SaveStatus;
+    status?: BackendStatus;
 }): Backend & {
     used(scope: Scope): string | undefined;
 };

package/dist/saves/backend/memory.js

@@ -7,8 +7,9 @@ function keyOf(scope) {
 // [function]
 // Saves kept in memory, for tests, and wherever IndexedDB
 // won't open. Hosts sharing one act like tabs sharing a device. Its saves
-// last as long as the page, so it says `ephemeral`.
-export function memoryBackend({ status = "ephemeral", } = {}) {
+// last as long as the page, so it says `memory`; tests pretend it's a
+// device's with `device`.
+export function memoryBackend({ status = "memory", } = {}) {
     const games = new Map();
     const listeners = listenersByKey();
     const gameOf = function (scope) {

package/dist/saves/backend/types.d.ts

@@ -1,4 +1,4 @@
-import type { SaveStatus } from "../rules.js";
+import type { BackendStatus } from "../rules.js";
 export type Scope = {
     game: string;
     channel: string;
@@ -18,7 +18,7 @@ export type Change = {
     revision: number;
 };
 export interface Backend {
-    status(): SaveStatus;
+    status(): BackendStatus;
     list(scope: Scope): Promise<SaveRecord[]>;
     get(scope: Scope, name: string): Promise<SaveRecord | null>;
     change(scope: Scope, name: string, decide: (saves: SaveRecord[]) => NewRecord | null, source: string): Promise<Change | null>;

package/dist/saves/client.d.ts

@@ -1,5 +1,5 @@
-import type { Bus } from "../bus/client.js";
-import { type SaveInfo } from "./rules.js";
+import { type Bus } from "../bus/client.js";
+import { type SaveInfo, type Where } from "./rules.js";
 /** `arcadible.saves`: each save is a name holding one string. */
 export interface Saves {
     /** Keeps `data` as the save `name`, replacing what it held. */
@@ -14,6 +14,17 @@ export interface Saves {
     remove(name: string): Promise<void>;
     /** After `ready`, the save's string from memory; before it, throws `not_ready`. */
     readSync(name: string): string | null;
+    /** After `ready`, the names of the game's saves from memory, sorted. */
+    listSync(): string[];
+    /** After `ready`, the save's version and time from memory, or `null`. */
+    infoSync(name: string): SaveInfo | null;
+    /**
+     * Who can read the saves back, once `ready` has settled: `"game"` (every
+     * version of the game), `"build"` (only this build), or `"memory"` (only
+     * until the page closes). `undefined` until it's known. Other values may
+     * be added: treat one you don't know as `"game"`.
+     */
+    readonly where: Where | undefined;
 }
 export declare function createSaves(bus: Bus, { timeout }: {
     timeout: number;

package/dist/saves/client.js

@@ -1,11 +1,12 @@
 // Saves, the game's side: `arcadible.saves`, and its memory copy of the
 // game's saves, so reads after `ready` answer at once.
-import { ArcadibleError, Codes, utf8Size } from "../bus/protocol.js";
-import { checkName, checkWrite, } from "./rules.js";
+// [import]
+import { mayHaveLanded } from "../bus/client.js";
+import { ArcadibleError, buildOf, Codes, isStringArray, isStringOrNull, log, utf8Size, } from "../bus/protocol.js";
+import { checkName, checkWrite, isRevisionOrNull, isSaveInfoOrNull, isSaveMeta, isSavesChange, isSavesLoad, } from "./rules.js";
 // [function]
-// a call that failed this way may still have been kept by the page.
-function mayHaveLanded(err) {
-    return err instanceof ArcadibleError && err.code === Codes.Timeout;
+function isAnything(_value) {
+    return true;
 }
 // [function]
 function infoOf(meta) {
@@ -20,6 +21,7 @@ export function createSaves(bus, { timeout }) {
     let settled = false;
     // whether the memory copy holds the game's saves.
     let loaded = false;
+    let where;
     let version = null;
     const mirror = new Map();
     // the newest revision seen of each save, removals included.
@@ -57,6 +59,14 @@ export function createSaves(bus, { timeout }) {
         kept(name, revision, save);
     };
     // [function]
+    // the answer to a write or remove that timed out, once it comes: the
+    // page did keep it, so the memory copy takes it, unless a newer write of
+    // the save is waiting, whose answer will be newer still.
+    const landed = function (name, revision, save) {
+        if (!writing.has(name))
+            kept(name, revision, save);
+    };
+    // [function]
     const restore = function (name, previous) {
         if (previous)
             mirror.set(name, previous);
@@ -77,138 +87,160 @@ export function createSaves(bus, { timeout }) {
         }
     };
     // [function]
-    const request = async function (name, params) {
-        await opened;
-        return bus.request(name, params);
+    // runs `call` once `ready` has settled: at once when it has, so a write
+    // changes the memory copy in the same tick, and a `readSync` right after
+    // it sees the save.
+    const whenOpened = function (call) {
+        return settled ? call() : opened.then(call);
+    };
+    // [function]
+    const send = function (name, data) {
+        // before the saves have loaded, only the name and document can be
+        // checked here; the page checks the rest once they have.
+        const optimistic = loaded;
+        const refused = checkWrite(optimistic ? mirror : new Map(), name, data);
+        if (refused)
+            return Promise.reject(refused);
+        // the memory copy changes at once, so the next read sees it; the
+        // promise settles once the page has kept it.
+        const previous = mirror.get(name);
+        const ticket = ++writes;
+        writing.set(name, ticket);
+        if (optimistic) {
+            mirror.set(name, {
+                name,
+                data,
+                info: {
+                    version,
+                    savedAt: new Date().toISOString(),
+                    size: utf8Size(data),
+                    revision: previous?.info.revision ?? 0,
+                },
+            });
+        }
+        const save = (meta) => ({ name, data, info: meta });
+        return bus
+            .request("saves.write", { name, data }, isSaveMeta, {
+            late: (meta) => landed(name, meta.revision, save(meta)),
+        })
+            .then((meta) => {
+            if (writing.get(name) === ticket) {
+                writing.delete(name);
+                kept(name, meta.revision, save(meta));
+            }
+            return infoOf(meta);
+        }, (err) => {
+            if (writing.get(name) === ticket)
+                writing.delete(name);
+            // one the page refused is rolled back, unless something newer
+            // replaced it meanwhile; one it may have kept stays.
+            if (optimistic &&
+                !mayHaveLanded(err) &&
+                mirror.get(name)?.data === data) {
+                restore(name, previous);
+            }
+            throw err;
+        });
+    };
+    // [function]
+    const erase = function (name) {
+        const optimistic = loaded;
+        const previous = mirror.get(name);
+        if (optimistic)
+            mirror.delete(name);
+        return bus
+            .request("saves.remove", { name }, isRevisionOrNull, {
+            late: (revision) => {
+                if (revision !== null)
+                    landed(name, revision, null);
+            },
+        })
+            .then((revision) => {
+            if (revision !== null)
+                kept(name, revision, null);
+        }, (err) => {
+            if (optimistic && !mayHaveLanded(err) && !mirror.has(name)) {
+                restore(name, previous);
+            }
+            throw err;
+        });
     };
     // [start]
     let timer;
-    bus.on("saves.load", (data) => {
+    // the load is checked here, not by the bus, so even a malformed one
+    // settles `ready` at once: the saves didn't load, and the sync reads say so.
+    bus.on("saves.load", isAnything, (load) => {
         if (loaded)
             return;
         clearTimeout(timer);
-        const load = data;
-        try {
-            if (!load?.error && Array.isArray(load?.items)) {
-                for (const save of load.items) {
-                    mirror.set(save.name, save);
-                    revisions.set(save.name, save.info.revision);
-                }
-                loaded = true;
-                for (const change of early.splice(0))
-                    apply(change);
-            }
+        if (!isSavesLoad(load)) {
+            log("warn", "the play page sent saves the game couldn't read.");
+            open();
+            return;
         }
-        finally {
-            // even a malformed load settles `ready`.
+        if (load.error) {
             open();
+            return;
         }
+        for (const save of load.items) {
+            mirror.set(save.name, save);
+            revisions.set(save.name, save.info.revision);
+        }
+        loaded = true;
+        where = typeof load.where === "string" ? load.where : undefined;
+        for (const change of early.splice(0))
+            apply(change);
+        open();
     });
-    bus.on("saves.change", (data) => {
+    bus.on("saves.change", isSavesChange, (change) => {
         // one that comes before the saves is kept until they do.
         if (loaded)
-            apply(data);
+            apply(change);
         else
-            early.push(data);
+            early.push(change);
     });
     bus.welcomed.then((welcome) => {
-        version = welcome.build?.version ?? null;
+        version = buildOf(welcome.build)?.version ?? null;
         // the memory copy doesn't pretend to be empty while the saves are late:
         // a game that took that for "no save yet" could start over, and
         // overwrite the player's progress once they arrived.
         if (!settled) {
             timer = setTimeout(() => {
-                console.warn("arcadible: the game's saves haven't arrived yet.");
+                if (!loaded) {
+                    log("warn", "the game's saves haven't arrived yet, so the sync reads throw unavailable until they do.");
+                }
                 open();
             }, timeout);
         }
     });
     const saves = {
-        async write(name, data) {
-            await opened;
-            // before the saves have loaded, only the name and document can be
-            // checked here; the page checks the rest once they have.
-            const optimistic = loaded;
-            const refused = checkWrite(optimistic ? mirror : new Map(), name, data);
-            if (refused)
-                throw refused;
-            // the memory copy changes at once, so the next read sees it; the
-            // promise settles once the page has kept it.
-            const previous = mirror.get(name);
-            const ticket = ++writes;
-            writing.set(name, ticket);
-            if (optimistic) {
-                mirror.set(name, {
-                    name,
-                    data,
-                    info: {
-                        version,
-                        savedAt: new Date().toISOString(),
-                        size: utf8Size(data),
-                        revision: previous?.info.revision ?? 0,
-                    },
-                });
-            }
-            try {
-                const meta = (await bus.request("saves.write", {
-                    name,
-                    data,
-                }));
-                if (writing.get(name) === ticket) {
-                    writing.delete(name);
-                    kept(name, meta.revision, { name, data, info: meta });
-                }
-                return infoOf(meta);
-            }
-            catch (err) {
-                if (writing.get(name) === ticket)
-                    writing.delete(name);
-                // one the page refused is rolled back, unless something newer
-                // replaced it meanwhile.
-                if (optimistic &&
-                    !mayHaveLanded(err) &&
-                    mirror.get(name)?.data === data) {
-                    restore(name, previous);
-                }
-                throw err;
-            }
+        write(name, data) {
+            return whenOpened(() => send(name, data));
         },
         async read(name) {
             const refused = checkName(name);
             if (refused)
                 throw refused;
-            return (await request("saves.read", { name }));
+            await opened;
+            return bus.request("saves.read", { name }, isStringOrNull);
         },
         async list() {
-            return (await request("saves.list"));
+            await opened;
+            return bus.request("saves.list", undefined, isStringArray);
         },
         async info(name) {
             const refused = checkName(name);
             if (refused)
                 throw refused;
-            const meta = (await request("saves.info", { name }));
+            await opened;
+            const meta = await bus.request("saves.info", { name }, isSaveInfoOrNull);
             return meta ? infoOf(meta) : null;
         },
         async remove(name) {
             const refused = checkName(name);
             if (refused)
                 throw refused;
-            await opened;
-            const optimistic = loaded;
-            const previous = mirror.get(name);
-            if (optimistic)
-                mirror.delete(name);
-            try {
-                const revision = (await bus.request("saves.remove", { name }));
-                if (revision !== null)
-                    kept(name, revision, null);
-            }
-            catch (err) {
-                if (optimistic && !mayHaveLanded(err) && !mirror.has(name)) {
-                    restore(name, previous);
-                }
-                throw err;
-            }
+            return whenOpened(() => erase(name));
         },
         readSync(name) {
             assertLoaded();
@@ -217,6 +249,21 @@ export function createSaves(bus, { timeout }) {
                 throw refused;
             return mirror.get(name)?.data ?? null;
         },
+        listSync() {
+            assertLoaded();
+            return [...mirror.keys()].sort();
+        },
+        infoSync(name) {
+            assertLoaded();
+            const refused = checkName(name);
+            if (refused)
+                throw refused;
+            const save = mirror.get(name);
+            return save ? infoOf(save.info) : null;
+        },
+        get where() {
+            return where;
+        },
     };
     return { saves, opened };
 }

package/dist/saves/rules.d.ts

@@ -1,7 +1,14 @@
 import { ArcadibleError } from "../bus/protocol.js";
 export declare const MAX_SAVES = 32;
 export declare const MAX_TOTAL: number;
-export type SaveStatus = "local" | "ephemeral";
+/**
+ * Who can read the saves back: every version of the game (`"game"`), only
+ * this build (`"build"`), or only until the page closes (`"memory"`). Other
+ * values may be added, such as `"account"`: a game treats one it doesn't
+ * know as `"game"`.
+ */
+export type Where = "game" | "build" | "memory" | (string & {});
+export type BackendStatus = "device" | "memory";
 /** What a game is told of a save. */
 export type SaveInfo = {
     /**
@@ -22,7 +29,7 @@ export type Save = {
     info: SaveMeta;
 };
 export type SavesLoad = {
-    status: SaveStatus;
+    where?: Where;
     items: Save[];
     error?: {
         code: string;
@@ -38,3 +45,9 @@ export declare function checkName(name: unknown): ArcadibleError | null;
 export declare function checkWrite(saves: ReadonlyMap<string, {
     info: SaveMeta;
 }>, name: unknown, data: unknown): ArcadibleError | null;
+export declare function isSaveMeta(value: unknown): value is SaveMeta;
+export declare function isSaveInfoOrNull(value: unknown): value is SaveInfo | null;
+export declare function isSave(value: unknown): value is Save;
+export declare function isSavesLoad(value: unknown): value is SavesLoad;
+export declare function isSavesChange(value: unknown): value is SavesChange;
+export declare function isRevisionOrNull(value: unknown): value is number | null;

package/dist/saves/rules.js

@@ -1,7 +1,7 @@
 // Saves' rules, shared by the game's side and the page's so they can't drift
 // apart: the shapes, the limits, and their checks (DESIGN.md, section 6).
 // [import]
-import { ArcadibleError, Codes, utf8Size } from "../bus/protocol.js";
+import { ArcadibleError, Codes, isNumber, isObject, isStringOrNull, utf8Size, } from "../bus/protocol.js";
 // [declare]
 // Saves' limits, the same everywhere (DESIGN.md, section 6, Limits).
 export const MAX_SAVES = 32;
@@ -47,3 +47,48 @@ export function checkWrite(saves, name, data) {
     }
     return null;
 }
+// [function]
+// What the page sends of a save, checked for only what a game relies on
+// (DESIGN.md, The host is never trusted): extra fields pass.
+export function isSaveMeta(value) {
+    return (isObject(value) &&
+        isStringOrNull(value["version"]) &&
+        typeof value["savedAt"] === "string" &&
+        isNumber(value["size"]) &&
+        isNumber(value["revision"]));
+}
+// [function]
+export function isSaveInfoOrNull(value) {
+    return (value === null ||
+        (isObject(value) &&
+            isStringOrNull(value["version"]) &&
+            typeof value["savedAt"] === "string"));
+}
+// [function]
+export function isSave(value) {
+    return (isObject(value) &&
+        checkName(value["name"]) === null &&
+        typeof value["data"] === "string" &&
+        isSaveMeta(value["info"]));
+}
+// [function]
+// A load the memory copy can take whole: every save readable, or none.
+export function isSavesLoad(value) {
+    return (isObject(value) &&
+        Array.isArray(value["items"]) &&
+        (value["error"] !== undefined || value["items"].every(isSave)));
+}
+// [function]
+export function isSavesChange(value) {
+    if (!isObject(value) ||
+        checkName(value["name"]) !== null ||
+        !isNumber(value["revision"])) {
+        return false;
+    }
+    const save = value["save"];
+    return save === null || (isSave(save) && save.name === value["name"]);
+}
+// [function]
+export function isRevisionOrNull(value) {
+    return value === null || isNumber(value);
+}

package/dist/saves/server.d.ts

@@ -1,8 +1,10 @@
 import type { Module, ModuleContext } from "../bus/server.js";
 import type { Backend, Scope } from "./backend/types.js";
+import { type Where } from "./rules.js";
 type SavesServerOptions = {
     scope: Scope;
     version: string | null;
+    where: Where;
     backend: Backend;
     now: () => Date;
 };

package/dist/saves/server.js

@@ -1,8 +1,9 @@
 // Saves, the page's side: it answers a game's saves requests from its
 // backend, enforces the limits, and stamps each save with the game's
-// version. Its first message on each channel is the game's saves.
+// version. Its first message on each channel is the game's saves, and who
+// can read them back.
 // [import]
-import { ArcadibleError, Codes, utf8Size } from "../bus/protocol.js";
+import { ArcadibleError, Codes, log, utf8Size } from "../bus/protocol.js";
 import { checkName, checkWrite, } from "./rules.js";
 // [function]
 function toSave(record) {
@@ -38,7 +39,7 @@ function storageError(err) {
 }
 // [function]
 export function savesServer(options) {
-    const { backend, now, scope, version } = options;
+    const { backend, now, scope, version, where } = options;
     const source = sourceId();
     // a write, checked against the game's saves in the same step as it's kept.
     const write = async function (params) {
@@ -67,10 +68,13 @@ export function savesServer(options) {
         const [list] = await Promise.all([
             backend.list(scope),
             backend.touch(scope, now().toISOString()).catch((err) => {
-                console.warn("arcadible: the saves' last use couldn't be kept:", err);
+                log("warn", "the saves' last use couldn't be kept.", err);
             }),
         ]);
-        return { status: backend.status(), items: list.map(toSave) };
+        return {
+            where: backend.status() === "memory" ? "memory" : where,
+            items: list.map(toSave),
+        };
     };
     return (context) => {
         // another tab (later, another device) changed a save: tell the game,
@@ -103,7 +107,13 @@ export function savesServer(options) {
                 "saves.remove": {
                     key: saveKey,
                     run: async (params) => {
-                        const change = await backend.change(scope, nameOf(params), () => null, source);
+                        // a removal writes too (the game's change counter), so a full
+                        // device refuses it the same way.
+                        const change = await backend
+                            .change(scope, nameOf(params), () => null, source)
+                            .catch((err) => {
+                            throw storageError(err);
+                        });
                         return change?.revision ?? null;
                     },
                 },
@@ -113,15 +123,11 @@ export function savesServer(options) {
                     send("saves.load", await load());
                 }
                 catch (err) {
-                    console.error("arcadible: the game's saves couldn't load:", err);
+                    log("warn", "the game's saves couldn't load.", err);
                     const error = err instanceof ArcadibleError
                         ? err.toJSON()
                         : { code: Codes.Unavailable, message: "Saves couldn't load." };
-                    send("saves.load", {
-                        status: "ephemeral",
-                        items: [],
-                        error,
-                    });
+                    send("saves.load", { items: [], error });
                 }
             },
             close: unsubscribe,

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.1.1";
+export declare const VERSION = "1.2.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // The client's version, sent in its hello and shown as `arcadible.version`,
 // for bug reports. It matches package.json (test/unit/protocol.test.ts).
-export const VERSION = "1.1.1";
+export const VERSION = "1.2.0";

package/package.json

@@ -43,5 +43,5 @@
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.1.1"
+  "version": "1.2.0"
 }