@arcadible/sdk 1.5.0-next.4 → 1.5.1

package/README.md

@@ -7,20 +7,26 @@
 <h1 align="center">Arcadible SDK</h1>
 
 <p align="center">
-  Arcadible's loading screen for your game, and saves that carry over from one version to the next.
+  How your game works with Arcadible.
 </p>
 
 <p align="center">
   <a href="https://developer.arcadible.com/references/arcadible-sdk">Docs</a> ·
   <a href="https://developer.arcadible.com/build/initialization">Initialization</a> ·
   <a href="https://developer.arcadible.com/build/saves">Saves</a> ·
+  <a href="https://developer.arcadible.com/build/pausing">Pausing</a> ·
   <a href="https://arcadible.com">Arcadible</a> ·
   <a href="https://studio.arcadible.com">Studio</a>
 </p>
 
 <br>
 
-The Arcadible SDK is optional: a game runs on [Arcadible](https://arcadible.com) without it. With it, a game gets two things from the play page around it: its [initialization](https://developer.arcadible.com/build/initialization), bracketed, so Arcadible's loading screen shows the game's splash and progress until its first frame is drawn, and [saves](https://developer.arcadible.com/build/saves), kept by the play page, so the player's progress carries over from one version to the next.
+The Arcadible SDK is optional: a game runs on [Arcadible](https://arcadible.com) without it. With it, a game gets these from the play page around it:
+
+- **[Initialization](https://developer.arcadible.com/build/initialization),** bracketed, so Arcadible's loading screen shows the game's splash and progress until its first frame is drawn.
+- **[Saves](https://developer.arcadible.com/build/saves),** kept by the play page, so the player's progress carries over from one version to the next.
+- **[Pausing](https://developer.arcadible.com/build/pausing):** Arcadible tells the game when to stop, go quiet, and save, and when to carry on.
+- **[`system` and `context`](https://developer.arcadible.com/references/arcadible-sdk#system):** the store's language, and when this run launched.
 
 ## Install
 
@@ -58,11 +64,26 @@ Saves are for what your game remembers between sessions, such as progress, setti
 
 Off Arcadible, such as on your dev server, the package still works, with the same rules and limits: there's no loading screen, so `initComplete()` resolves at once, saves are kept in the game's own browser storage, `arcadible.saves.where` is `"build"`, and `arcadible.build` is `null`.
 
+## Pause and resume
+
+```js
+arcadible.on("pause", async () => {
+  // … stop your game loop and timers, and silence your audio …
+  await arcadible.saves.write("progress", JSON.stringify(progress));
+});
+arcadible.on("resume", () => {
+  // … start your game loop and timers again, and your audio …
+});
+```
+
+Arcadible pauses your game when the page is hidden, when it covers your game, and before it closes or reloads it, when it waits a moment for your save. Stop, go quiet, and save, drawing nothing over your game; on `resume`, carry on, or show a "Ready?" first in an action game.
+
 ## Learn more
 
 - [Initialization](https://developer.arcadible.com/build/initialization): where each call goes, progress, and what comes after.
 - [Saves](https://developer.arcadible.com/build/saves): using saves well, across versions, channels, and tabs, and where they're kept.
-- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): including it, every call, the saves' included, and every code.
+- [Pausing](https://developer.arcadible.com/build/pausing): what a pause asks of your game, and resuming.
+- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): including it, every call, the saves' included, `system` and `context`, and every code.
 - [Limits](https://developer.arcadible.com/references/limits#saves): how many saves, and how large.
 
 ## License

package/dist/client.js

@@ -33,28 +33,36 @@ export function createClient(options = {}) {
         requestTimeout: options.requestTimeout,
         standalone: () => serve({ ...STANDALONE, backend: backend() }),
     });
-    const { saves, opened } = createSaves(bus, {
+    // each module's game side, made on the bus as the client starts, before
+    // anything arrives.
+    const saves = createSaves(bus, {
         timeout: options.requestTimeout ?? REQUEST_TIMEOUT,
     });
-    let settled = null;
     const system = createSystemClient(bus);
     const context = createContextClient(bus);
-    // ready once welcomed, and each module's first messages have arrived.
-    const ready = Promise.all([bus.welcomed, opened]).then(([welcome]) => {
-        system.settle();
-        context.settle();
+    const lifecycle = createLifecycle(bus, win);
+    const pause = createPause(bus);
+    // the ones `ready` waits on, or tells: lifecycle and pause do neither.
+    const parts = [saves, system, context];
+    let settled = null;
+    // ready once welcomed, and each module's first messages have arrived;
+    // then each is told, so its facts are known, or null.
+    const ready = Promise.all([
+        bus.welcomed,
+        ...parts.map((part) => part.opened),
+    ]).then(([welcome]) => {
+        for (const part of parts)
+            part.settle?.();
         settled = { build: buildOf(welcome.build) };
         return settled;
     });
-    const lifecycle = createLifecycle(bus, win);
-    const pause = createPause(bus);
     return {
         version: VERSION,
         ready,
         get build() {
             return settled ? settled.build : undefined;
         },
-        saves,
+        saves: saves.saves,
         get system() {
             return system.value;
         },

package/dist/context/client.d.ts

@@ -1,4 +1,5 @@
 import type { Bus } from "../bus/client.js";
+import { type Fact } from "../facts.js";
 /** How this run started, fixed for the run. */
 export interface Context {
     readonly launch: {
@@ -6,7 +7,4 @@ export interface Context {
         readonly at: string;
     };
 }
-export declare function createContextClient(bus: Bus): {
-    settle(): void;
-    readonly value: Context | null | undefined;
-};
+export declare function createContextClient(bus: Bus): Fact<Context>;

package/dist/context/client.js

@@ -1,31 +1,17 @@
 // The game's side of `context`: `arcadible.context`, how this run started,
 // fixed for the run. `undefined` before `ready`, and `null` where no page
 // says (standing alone, or an older page).
-import { isObject, log } from "../bus/protocol.js";
+import { fact } from "../facts.js";
 import { contextOf, Names } from "./rules.js";
 // [function]
 export function createContextClient(bus) {
-    let context = null;
-    let settled = false;
-    bus.on(Names.State, isObject, (data) => {
-        // fixed for the run: the first one stands, and none comes after `ready`.
-        if (context || settled)
-            return;
-        const next = contextOf(data);
-        if (!next) {
-            log("warn", "ignored a malformed context from the play page.");
-            return;
-        }
-        context = Object.freeze({ launch: Object.freeze({ ...next.launch }) });
-    });
-    return {
-        settle() {
-            settled = true;
-        },
-        get value() {
-            if (!settled)
-                return undefined;
-            return context;
+    return fact(bus, Names.State, {
+        fixed: true,
+        parse(data) {
+            const context = contextOf(data);
+            return context
+                ? Object.freeze({ launch: Object.freeze({ ...context.launch }) })
+                : null;
         },
-    };
+    });
 }

package/dist/facts.d.ts

@@ -0,0 +1,11 @@
+import type { Bus } from "./bus/client.js";
+export type Fact<T> = {
+    settle(): void;
+    readonly value: T | null | undefined;
+};
+export type FactOptions<T> = {
+    parse(value: unknown): T | null;
+    fixed?: boolean;
+    changed?(before: T, next: T): void;
+};
+export declare function fact<T>(bus: Bus, name: string, options: FactOptions<T>): Fact<T>;

package/dist/facts.js

@@ -0,0 +1,33 @@
+// A fact the page sends as its module opens, such as `system`'s state or
+// `context`: `undefined` before `ready`, the fact from then on, or `null`
+// where no page sent one (standing alone, or an older page). Only what
+// `parse` keeps is kept, so the host is trusted with nothing; a fixed fact
+// takes its first and nothing after `ready`, and a changing one tells
+// `changed` what came after it.
+import { isObject, log } from "./bus/protocol.js";
+// [function]
+export function fact(bus, name, options) {
+    let value = null;
+    let settled = false;
+    bus.on(name, isObject, (data) => {
+        if (options.fixed && (value !== null || settled))
+            return;
+        const next = options.parse(data);
+        if (next === null) {
+            log("warn", `ignored a malformed ${name} from the play page.`);
+            return;
+        }
+        const before = value;
+        value = next;
+        if (before !== null && settled)
+            options.changed?.(before, next);
+    });
+    return {
+        settle() {
+            settled = true;
+        },
+        get value() {
+            return settled ? value : undefined;
+        },
+    };
+}

package/dist/lifecycle/pause.d.ts

@@ -1,7 +1,5 @@
 import type { Bus } from "../bus/client.js";
-export type PauseListener = () => void | Promise<void>;
-export type ResumeListener = () => void;
 export type Pause = {
-    on(name: string, listener: unknown): () => void;
+    on(name: unknown, listener: unknown): () => void;
 };
 export declare function createPause(bus: Bus): Pause;

package/dist/lifecycle/pause.js

@@ -3,11 +3,9 @@
 // why; this side keeps that from the moment it connects, so a game that
 // subscribes while held still gets its pause, and tells the page once its
 // pause listeners have settled, which the page waits on only as it closes.
-import { ArcadibleError, Codes, isObject, log } from "../bus/protocol.js";
+import { isObject, log } from "../bus/protocol.js";
+import { listeners } from "../listeners.js";
 import { Names } from "./rules.js";
-// the events a game can listen for on `arcadible`: a closed list, so a typo
-// throws rather than never firing.
-const EVENTS = ["pause", "resume"];
 // [function]
 function isHeld(value) {
     return (isObject(value) &&
@@ -22,21 +20,14 @@ export function createPause(bus) {
     // whether the game heard this hold's pause: a resume goes only to a game
     // that did, so it never resumes from a pause it wasn't told of.
     let heard = false;
-    const pauses = new Set();
-    const resumes = new Set();
-    // runs pause listeners, each on its own, and tells the page once they've
-    // all settled, for pause `count`.
-    const pause = function (listeners, count) {
-        if (listeners.length > 0)
+    // the events a game can listen for on `arcadible`.
+    const on = listeners("arcadible", ["pause", "resume"]);
+    // runs pause listeners, and tells the page once they've all settled, for
+    // pause `count`.
+    const pause = function (run, count) {
+        const runs = run().map((result) => Promise.resolve(result));
+        if (runs.length > 0)
             heard = true;
-        const runs = listeners.map((listener) => {
-            try {
-                return Promise.resolve(listener());
-            }
-            catch (err) {
-                return Promise.reject(err);
-            }
-        });
         void Promise.allSettled(runs).then((results) => {
             for (const result of results) {
                 if (result.status === "rejected") {
@@ -46,45 +37,23 @@ export function createPause(bus) {
             bus.emit(Names.Paused, { n: count });
         });
     };
-    const resume = function () {
-        for (const listener of [...resumes]) {
-            try {
-                listener();
-            }
-            catch (err) {
-                log("error", "a resume listener failed.", err);
-            }
-        }
-    };
     bus.on(Names.Held, isHeld, (data) => {
         const was = held;
         held = data.held;
         n = data.n;
         if (held && !was)
-            pause([...pauses], n);
+            pause(() => on.call("pause"), n);
         else if (!held && was) {
             if (heard)
-                resume();
+                on.call("resume");
             heard = false;
         }
     });
     return {
         on(name, listener) {
-            if (!EVENTS.includes(name)) {
-                throw new ArcadibleError(Codes.Invalid, `arcadible.on takes "pause" or "resume", not ${JSON.stringify(name)}.`);
-            }
-            if (typeof listener !== "function") {
-                throw new ArcadibleError(Codes.Invalid, `arcadible.on("${name}") takes a function.`);
-            }
-            if (name === "resume") {
-                const fn = listener;
-                resumes.add(fn);
-                return () => {
-                    resumes.delete(fn);
-                };
-            }
-            const fn = listener;
-            pauses.add(fn);
+            const off = on.add(name, listener);
+            if (name !== "pause")
+                return off;
             if (!told) {
                 told = true;
                 bus.emit(Names.Listening);
@@ -94,13 +63,20 @@ export function createPause(bus) {
             if (held) {
                 const count = n;
                 queueMicrotask(() => {
-                    if (held && n === count && pauses.has(fn))
-                        pause([fn], count);
+                    if (held && n === count && on.has("pause", listener)) {
+                        pause(() => {
+                            try {
+                                return [listener()];
+                            }
+                            catch (err) {
+                                log("error", "a pause listener failed.", err);
+                                return [undefined];
+                            }
+                        }, count);
+                    }
                 });
             }
-            return () => {
-                pauses.delete(fn);
-            };
+            return off;
         },
     };
 }

package/dist/listeners.d.ts

@@ -0,0 +1,13 @@
+type Listener = (...args: never[]) => unknown;
+export type Listeners<N extends string> = {
+    add(name: unknown, listener: unknown): () => void;
+    of(name: N): Listener[];
+    has(name: N, listener: unknown): boolean;
+    call(name: N, ...args: unknown[]): unknown[];
+};
+/**
+ * The listeners for `names` on the object a game calls as `where`
+ * (`"arcadible"`, `"arcadible.system"`).
+ */
+export declare function listeners<N extends string>(where: string, names: readonly N[]): Listeners<N>;
+export {};

package/dist/listeners.js

@@ -0,0 +1,48 @@
+// The listeners behind every `on` a game calls (`arcadible.on`,
+// `arcadible.system.on`): a closed list of names, so a typo throws rather
+// than never firing; a listener that must be a function; the function that
+// unsubscribes; and each listener run on its own, so one that throws stops
+// none of the others. One shape for each, with the same messages.
+// [import]
+import { ArcadibleError, Codes, log } from "./bus/protocol.js";
+// [function]
+/**
+ * The listeners for `names` on the object a game calls as `where`
+ * (`"arcadible"`, `"arcadible.system"`).
+ */
+export function listeners(where, names) {
+    const sets = new Map(names.map((name) => [name, new Set()]));
+    const list = names.map((name) => JSON.stringify(name)).join(" or ");
+    const of = (name) => [...(sets.get(name) ?? [])];
+    return {
+        add(name, listener) {
+            const set = sets.get(name);
+            if (!set) {
+                throw new ArcadibleError(Codes.Invalid, `${where}.on takes ${list}, not ${JSON.stringify(name)}.`);
+            }
+            if (typeof listener !== "function") {
+                throw new ArcadibleError(Codes.Invalid, `${where}.on(${JSON.stringify(name)}) takes a function.`);
+            }
+            const fn = listener;
+            set.add(fn);
+            return () => {
+                set.delete(fn);
+            };
+        },
+        of,
+        has(name, listener) {
+            return sets.get(name)?.has(listener) ?? false;
+        },
+        call(name, ...args) {
+            return of(name).map((fn) => {
+                try {
+                    return fn(...args);
+                }
+                catch (err) {
+                    log("error", `a ${name} listener failed.`, err);
+                    return undefined;
+                }
+            });
+        },
+    };
+}

package/dist/system/client.d.ts

@@ -1,4 +1,5 @@
 import type { Bus } from "../bus/client.js";
+import { type Fact } from "../facts.js";
 /** Arcadible's state for the player, which changes while the game runs. */
 export interface System {
     /**
@@ -14,7 +15,4 @@ export interface System {
      */
     on(name: "change", listener: (system: System, changed: readonly string[]) => void): () => void;
 }
-export declare function createSystemClient(bus: Bus): {
-    settle(): void;
-    readonly value: System | null | undefined;
-};
+export declare function createSystemClient(bus: Bus): Fact<System>;

package/dist/system/client.js

@@ -2,61 +2,36 @@
 // player, read at any time, with one `change` event naming what changed.
 // `undefined` before `ready`, and `null` where no page says (standing
 // alone, or an older page).
-import { ArcadibleError, Codes, isObject, log } from "../bus/protocol.js";
+import { fact } from "../facts.js";
+import { listeners } from "../listeners.js";
 import { Names, stateOf } from "./rules.js";
 // [function]
 export function createSystemClient(bus) {
-    let state = null;
-    let settled = false;
-    const listeners = new Set();
+    // the events a game can listen for on `arcadible.system`.
+    const on = listeners("arcadible.system", ["change"]);
+    const kept = fact(bus, Names.State, {
+        parse: stateOf,
+        changed(before, next) {
+            const changed = Object.keys(next).filter((key) => next[key] !== before[key]);
+            if (changed.length > 0)
+                on.call("change", system, changed);
+        },
+    });
+    // one object for the run: what a game holds, and what `change` passes,
+    // reads the state as it is now.
     const system = {
         get language() {
-            return state.language;
-        },
-        on(name, listener) {
-            if (name !== "change") {
-                throw new ArcadibleError(Codes.Invalid, `arcadible.system.on takes "change", not ${JSON.stringify(name)}.`);
-            }
-            if (typeof listener !== "function") {
-                throw new ArcadibleError(Codes.Invalid, 'arcadible.system.on("change") takes a function.');
-            }
-            const fn = listener;
-            listeners.add(fn);
-            return () => {
-                listeners.delete(fn);
-            };
+            return kept.value.language;
         },
+        on: (name, listener) => on.add(name, listener),
     };
-    bus.on(Names.State, isObject, (data) => {
-        const next = stateOf(data);
-        if (!next) {
-            log("warn", "ignored a malformed system state from the play page.");
-            return;
-        }
-        const before = state;
-        state = next;
-        if (!before || !settled)
-            return;
-        const changed = Object.keys(next).filter((key) => next[key] !== before[key]);
-        if (changed.length === 0)
-            return;
-        for (const listener of [...listeners]) {
-            try {
-                listener(system, changed);
-            }
-            catch (err) {
-                log("error", "a system change listener failed.", err);
-            }
-        }
-    });
     return {
-        settle() {
-            settled = true;
-        },
+        settle: () => kept.settle(),
         get value() {
-            if (!settled)
+            const value = kept.value;
+            if (value === undefined)
                 return undefined;
-            return state ? system : null;
+            return value === null ? null : system;
         },
     };
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.5.0-next.4";
+export declare const VERSION = "1.5.1";

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.5.0-next.4";
+export const VERSION = "1.5.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "author": "Offst, Inc.",
-  "description": "The Arcadible SDK: Arcadible's loading screen for a game's initialization, and saves that carry over between its versions.",
+  "description": "The Arcadible SDK: how your game works with Arcadible.",
   "devDependencies": {
     "@playwright/test": "1.63.0",
     "@types/node": "^25.0.3",
@@ -43,5 +43,5 @@
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.5.0-next.4"
+  "version": "1.5.1"
 }