@arcadible/sdk 1.4.1 → 1.5.0-next.0

package/README.md

@@ -35,18 +35,18 @@ The package is for a game with a build step, such as a Vite project. A game with
 ```js
 import { arcadible } from "@arcadible/sdk";
 
-await arcadible.initStart(); // first thing in your game's code
+await arcadible.initStart(); // as your code starts, before anything it awaits
 arcadible.initProgress(0.5);
 // … load, build the scene, and draw the first frame …
 await arcadible.initComplete();
 ```
 
-Call `initStart()` first thing in your game's code, report how far along you are with `initProgress()`, from 0 to 1, if you can measure it, and call `initComplete()` once your first frame is drawn. Arcadible shows your splash and the progress until then, and `initComplete()` resolves once the loading screen has faded into your game.
+Call `initStart()` as your code starts, before anything it awaits, report how far along you are with `initProgress()`, from 0 to 1, if you can measure it, and call `initComplete()` once your first frame is drawn. Arcadible shows your splash and the progress until then, and `initComplete()` resolves once the loading screen has faded into your game.
 
 ## Save and load
 
 ```js
-// once the saves have loaded
+// as your game starts, after initStart()
 const saved = await arcadible.saves.read("progress");
 const progress = saved ? JSON.parse(saved) : { level: 1 };
 
@@ -54,7 +54,7 @@ const progress = saved ? JSON.parse(saved) : { level: 1 };
 await arcadible.saves.write("progress", JSON.stringify(progress));
 ```
 
-A save is a name holding one string. Read your saves once as your game starts, keep the state in your game, and write at checkpoints. Every call returns a promise, and one that fails rejects 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.
+Saves are for what your game remembers between sessions, such as progress, settings, and preferences, not a general key/value store: up to 32 saves, 1 MB together, each named as you choose. A save is a name holding one string. Read your saves once as your game starts, keep the state in your game, and write at checkpoints. Every call returns a promise, and one that fails rejects 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 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`.
 

package/dist/client.d.ts

@@ -24,8 +24,8 @@ export interface Arcadible {
     /** Saves that carry over between the game's versions. */
     readonly saves: Saves;
     /**
-     * Starts the game's initialization: call it first, before anything you
-     * await, and Arcadible shows the game's loading screen until
+     * Starts the game's initialization: call it as your code starts, before
+     * anything it awaits, and Arcadible shows the game's loading screen until
      * `initComplete()`.
      * It resolves as `ready` does, once the SDK and the saves are ready.
      */
@@ -41,6 +41,20 @@ export interface Arcadible {
      * game is visible.
      */
     initComplete(): Promise<void>;
+    /**
+     * Arcadible needs the game to pause: stop, go quiet, and save, drawing
+     * nothing over its last frame. It isn't told why. The page waits on the
+     * listener's promise, for a moment, only before it closes or reloads the
+     * game. Subscribing while paused gets the pause just after `on` returns.
+     * Returns a function that unsubscribes.
+     */
+    on(name: "pause", listener: () => void | Promise<void>): () => void;
+    /**
+     * Nothing holds the game any more: carry on, or, for a game that needs a
+     * moment, show its own "Ready?" first. Returns a function that
+     * unsubscribes.
+     */
+    on(name: "resume", listener: () => void): () => void;
 }
 export type ClientOptions = {
     window?: Window;

package/dist/client.js

@@ -5,6 +5,7 @@
 import { openBus } from "./bus/client.js";
 import { buildOf, REQUEST_TIMEOUT } from "./bus/protocol.js";
 import { createLifecycle } from "./lifecycle/client.js";
+import { createPause } from "./lifecycle/pause.js";
 import { indexedDBBackend } from "./saves/backend/indexeddb.js";
 import { createSaves } from "./saves/client.js";
 import { serve } from "./host.js";
@@ -40,6 +41,7 @@ export function createClient(options = {}) {
         return settled;
     });
     const lifecycle = createLifecycle(bus, win);
+    const pause = createPause(bus);
     return {
         version: VERSION,
         ready,
@@ -57,5 +59,8 @@ export function createClient(options = {}) {
         initComplete() {
             return lifecycle.complete();
         },
+        on(name, listener) {
+            return pause.on(name, listener);
+        },
     };
 }

package/dist/host.d.ts

@@ -1,5 +1,6 @@
 import type { Hello } from "./bus/protocol.js";
 import { type Server } from "./bus/server.js";
+import { type Holds } from "./lifecycle/holds.js";
 import { type LifecycleHost } from "./lifecycle/server.js";
 import type { Backend } from "./saves/backend/types.js";
 import type { Where } from "./saves/rules.js";
@@ -11,17 +12,22 @@ export type ServeOptions = {
     where?: Where;
     now?: () => Date;
     lifecycle?: LifecycleHost;
+    holds?: Holds;
 };
-type HostOptions = ServeOptions & {
+export type Host = {
+    close(): void;
+    hold(): () => void;
+    leave(timeout?: number): Promise<void>;
+};
+type HostOptions = Omit<ServeOptions, "holds"> & {
     frame: HTMLIFrameElement;
     origin: string;
     window?: Window;
     onHello?: (hello: Hello) => void;
 };
 export declare function serve(options: ServeOptions): Server;
-export declare function createHost(options: HostOptions): {
-    close(): void;
-};
+export declare function createHost(options: HostOptions): Host;
 export type { Server } from "./bus/server.js";
+export { createHolds, type Holds } from "./lifecycle/holds.js";
 export { indexedDBBackend } from "./saves/backend/indexeddb.js";
 export { memoryBackend } from "./saves/backend/memory.js";

package/dist/host.js

@@ -1,6 +1,7 @@
 // The page's side of the bus. The play page uses `createHost`;
 // a game standing alone runs `serve` in its own page.
 import { answerHellos, createServer } from "./bus/server.js";
+import { createHolds } from "./lifecycle/holds.js";
 import { lifecycleServer } from "./lifecycle/server.js";
 import { savesServer } from "./saves/server.js";
 // [function]
@@ -10,6 +11,8 @@ export function serve(options) {
     return createServer({
         build: version === null ? null : { version, channel },
         modules: [
+            // first, so the game knows whether it's held by `ready`.
+            ...(options.holds ? [options.holds.module] : []),
             savesServer({
                 backend,
                 now: options.now ?? (() => new Date()),
@@ -24,15 +27,41 @@ export function serve(options) {
 // [function]
 // The play page's host: it answers its iframe's hello with a welcome and a
 // private channel. Call it before inserting the iframe, so no hello is
-// missed.
+// missed. It holds the game while the page is hidden; `hold` holds it for
+// the page's own reasons (its menu), and `leave` before the page closes or
+// reloads it.
 export function createHost(options) {
-    return answerHellos({
+    const win = options.window ?? window;
+    const holds = createHolds();
+    const answering = answerHellos({
         frame: options.frame,
         origin: options.origin,
-        server: serve(options),
-        window: options.window ?? window,
+        server: serve({ ...options, holds }),
+        window: win,
         onHello: options.onHello,
     });
+    const doc = win.document;
+    let hidden = null;
+    const visibility = function () {
+        if (doc.visibilityState === "hidden")
+            hidden ??= holds.hold();
+        else if (hidden) {
+            hidden();
+            hidden = null;
+        }
+    };
+    doc?.addEventListener("visibilitychange", visibility);
+    if (doc)
+        visibility();
+    return {
+        close() {
+            doc?.removeEventListener("visibilitychange", visibility);
+            answering.close();
+        },
+        hold: () => holds.hold(),
+        leave: (timeout) => holds.leave(timeout),
+    };
 }
+export { createHolds } from "./lifecycle/holds.js";
 export { indexedDBBackend } from "./saves/backend/indexeddb.js";
 export { memoryBackend } from "./saves/backend/memory.js";

package/dist/lifecycle/holds.d.ts

@@ -0,0 +1,7 @@
+import type { Module, ModuleContext } from "../bus/server.js";
+export type Holds = {
+    hold(): () => void;
+    leave(timeout?: number): Promise<void>;
+    module(context: ModuleContext): Module;
+};
+export declare function createHolds(): Holds;

package/dist/lifecycle/holds.js

@@ -0,0 +1,81 @@
+// The page's side of pause and resume: what holds the game (the page
+// hidden, Arcadible's menu, an ad, closing), as one state the game hears,
+// never why. The game gets one pause as the first hold comes, and one
+// resume once the last is let go, however many overlap. Before closing or
+// reloading the game, the page waits a moment for a game that listens to
+// save; a game that doesn't is closed at once.
+// [import]
+import { isObject } from "../bus/protocol.js";
+import { LEAVE_TIMEOUT, Names } from "./rules.js";
+// [function]
+export function createHolds() {
+    const holding = new Set();
+    let n = 0;
+    let listening = false;
+    // the last pause the game said it settled.
+    let settled = 0;
+    const waiters = new Set();
+    let context = null;
+    const state = () => ({ held: holding.size > 0, n });
+    const tell = () => context?.broadcast(Names.Held, state());
+    const hold = function () {
+        const token = Symbol("hold");
+        if (holding.size === 0)
+            n++;
+        holding.add(token);
+        if (holding.size === 1)
+            tell();
+        return () => {
+            if (!holding.delete(token))
+                return;
+            if (holding.size === 0)
+                tell();
+        };
+    };
+    return {
+        hold,
+        leave(timeout = LEAVE_TIMEOUT) {
+            hold();
+            if (!listening || settled >= n)
+                return Promise.resolve();
+            return new Promise((resolve) => {
+                const done = () => {
+                    clearTimeout(timer);
+                    waiters.delete(done);
+                    resolve();
+                };
+                const timer = setTimeout(done, timeout);
+                waiters.add(done);
+            });
+        },
+        module(ctx) {
+            context = ctx;
+            return {
+                handlers: {},
+                events: {
+                    [Names.Listening]: () => {
+                        listening = true;
+                    },
+                    [Names.Paused]: (data) => {
+                        const value = isObject(data) ? data["n"] : undefined;
+                        if (typeof value !== "number" || value > n)
+                            return;
+                        settled = Math.max(settled, value);
+                        if (settled < n)
+                            return;
+                        for (const done of [...waiters])
+                            done();
+                    },
+                },
+                // the state now, first on each channel, so the game knows it by
+                // `ready`. A new channel is a new page load in the frame, which
+                // says again whether it listens.
+                async open(send) {
+                    listening = false;
+                    settled = 0;
+                    send(Names.Held, state());
+                },
+            };
+        },
+    };
+}

package/dist/lifecycle/pause.d.ts

@@ -0,0 +1,7 @@
+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;
+};
+export declare function createPause(bus: Bus): Pause;

package/dist/lifecycle/pause.js

@@ -0,0 +1,106 @@
+// The game's side of pause and resume: `arcadible.on("pause")` and
+// `arcadible.on("resume")`. The page says whether it holds the game, never
+// 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 { 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) &&
+        typeof value["held"] === "boolean" &&
+        typeof value["n"] === "number");
+}
+// [function]
+export function createPause(bus) {
+    let held = false;
+    let n = 0;
+    let told = false;
+    // 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)
+            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") {
+                    log("error", "a pause listener failed.", result.reason);
+                }
+            }
+            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);
+        else if (!held && was) {
+            if (heard)
+                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);
+            if (!told) {
+                told = true;
+                bus.emit(Names.Listening);
+            }
+            // subscribing while held: the pause just after `on` returns, if it
+            // still holds and the listener is still there.
+            if (held) {
+                const count = n;
+                queueMicrotask(() => {
+                    if (held && n === count && pauses.has(fn))
+                        pause([fn], count);
+                });
+            }
+            return () => {
+                pauses.delete(fn);
+            };
+        },
+    };
+}

package/dist/lifecycle/rules.d.ts

@@ -3,7 +3,11 @@ export declare const Names: {
     readonly Progress: "lifecycle.initProgress";
     readonly Loaded: "lifecycle.loaded";
     readonly Complete: "lifecycle.initComplete";
+    readonly Held: "lifecycle.held";
+    readonly Listening: "lifecycle.listening";
+    readonly Paused: "lifecycle.paused";
 };
+export declare const LEAVE_TIMEOUT = 1000;
 export declare const INIT_SINCE = "1.4.0";
 export declare const COMPLETE_TIMEOUT = 60000;
 export declare function reportsInit(client: unknown): boolean;

package/dist/lifecycle/rules.js

@@ -12,7 +12,21 @@ export const Names = {
     Loaded: "lifecycle.loaded",
     // its first frame is drawn: a request, answered once the game is visible.
     Complete: "lifecycle.initComplete",
+    // whether the page holds the game, `{ held, n }`: an event, sent as the
+    // module opens and on every change, `n` counting the pauses. The game
+    // runs its pause listeners as it's held, and its resume listeners as
+    // it's let go.
+    Held: "lifecycle.held",
+    // the game listens for pause: an event, sent once, so the page knows to
+    // wait for it before closing.
+    Listening: "lifecycle.listening",
+    // the game's pause listeners have settled, `{ n }`, for pause `n`: an
+    // event, which the page waits on only as it closes.
+    Paused: "lifecycle.paused",
 };
+// How long the page waits for a game's pause listeners before it closes or
+// reloads it: long enough to save, short enough not to keep anyone waiting.
+export const LEAVE_TIMEOUT = 1000;
 // The first SDK that sends them. An older one doesn't, so the page takes its
 // loading screen down at `load`, without waiting to hear.
 export const INIT_SINCE = "1.4.0";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.4.1";
+export declare const VERSION = "1.5.0-next.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.4.1";
+export const VERSION = "1.5.0-next.0";

package/package.json

@@ -43,5 +43,5 @@
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.4.1"
+  "version": "1.5.0-next.0"
 }