@arcadible/sdk 1.4.2 → 1.5.0-next.0

package/dist/client.d.ts

@@ -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.2";
+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.2";
+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.2"
+  "version": "1.5.0-next.0"
 }