@arcadible/sdk 1.2.2 → 1.3.0

package/dist/bus/client.d.ts

@@ -10,11 +10,13 @@ export type BusOptions = {
 };
 export type RequestOptions<T> = {
     late?: (result: T) => void;
+    timeout?: number;
 };
 export type Bus = {
     readonly welcomed: Promise<Welcome>;
     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;
+    emit(name: string, data?: unknown): void;
 };
 export declare function mayHaveLanded(err: unknown): boolean;
 export declare function openBus(options: BusOptions): Bus;

package/dist/bus/client.js

@@ -184,7 +184,7 @@ export function openBus(options) {
                         }
                     }
                     reject(unsure(Codes.Timeout, "The play page took too long to answer. Try again."));
-                }, requestTimeout);
+                }, requestOptions.timeout ?? requestTimeout);
                 pending.set(id, {
                     name,
                     resolve: resolve,
@@ -196,6 +196,11 @@ export function openBus(options) {
                 link.postMessage({ kind: "request", id, name, params });
             });
         },
+        emit(name, data) {
+            void welcomed.then(() => {
+                port?.postMessage({ kind: "event", name, data });
+            });
+        },
         on(name, shape, listener) {
             // each listener on its own: one that throws, or data it can't take,
             // doesn't stop the others.

package/dist/bus/server.d.ts

@@ -1,15 +1,17 @@
-import { type Build, type Welcome } from "./protocol.js";
+import { type Build, type Hello, type Welcome } from "./protocol.js";
 export type Params = Record<string, unknown>;
 export type Handler = {
     run(params: Params): Promise<unknown>;
     key?(params: Params): string;
     coalesce?: boolean;
+    parallel?: boolean;
 };
 export type ModuleContext = {
     broadcast(name: string, data: unknown): void;
 };
 export type Module = {
     handlers: Record<string, Handler>;
+    events?: Record<string, (data: unknown) => void>;
     open?(send: (name: string, data: unknown) => void): Promise<void>;
     close?(): void;
 };
@@ -23,11 +25,12 @@ export type Server = {
     close(): void;
 };
 export declare function createServer(options: ServerOptions): Server;
-export declare function answerHellos({ frame, origin, server, window: win, }: {
+export declare function answerHellos({ frame, origin, server, window: win, onHello, }: {
     frame: HTMLIFrameElement;
     origin: string;
     server: Server;
     window: Window;
+    onHello?: ((hello: Hello) => void) | undefined;
 }): {
     close(): void;
 };

package/dist/bus/server.js

@@ -54,10 +54,14 @@ export function createServer(options) {
         },
     }));
     const handlers = new Map();
+    const events = new Map();
     for (const module of modules) {
         for (const [name, handler] of Object.entries(module.handlers)) {
             handlers.set(name, handler);
         }
+        for (const [name, listener] of Object.entries(module.events ?? {})) {
+            events.set(name, listener);
+        }
     }
     const refuse = function (port, id, error) {
         port.postMessage({ kind: "response", id, error });
@@ -110,6 +114,12 @@ export function createServer(options) {
         }
         inFlight.set(port, (inFlight.get(port) ?? 0) + 1);
         const entry = { name, port, params, ids: [id] };
+        if (handler.parallel) {
+            Promise.resolve()
+                .then(() => handler.run(entry.params))
+                .then((result) => respond(entry, { result }), (err) => respond(entry, { error: errorBody(err) }));
+            return;
+        }
         if (key !== null)
             waiting.set(key, entry);
         enqueue(() => {
@@ -118,8 +128,29 @@ export function createServer(options) {
             return handler.run(entry.params);
         }).then((result) => respond(entry, { result }), (err) => respond(entry, { error: errorBody(err) }));
     };
+    // an event from the game: unknown ones, and ones too large, are dropped,
+    // since nothing waits on them.
+    const hear = function (name, data) {
+        const listener = events.get(name);
+        if (!listener)
+            return;
+        if (messageSize(data, MAX_MESSAGE) > MAX_MESSAGE)
+            return;
+        try {
+            listener(data);
+        }
+        catch (err) {
+            log("error", `the game's ${name} failed.`, err);
+        }
+    };
     const receive = function (port, data) {
-        if (!isMessage(data) || data.kind !== "request")
+        if (!isMessage(data))
+            return;
+        if (data.kind === "event") {
+            hear(data.name, data.data);
+            return;
+        }
+        if (data.kind !== "request")
             return;
         if (messageSize(data, MAX_MESSAGE) > MAX_MESSAGE) {
             refuse(port, data.id, {
@@ -170,7 +201,7 @@ export function createServer(options) {
 // iframe, at its build's exact origin, with a welcome and a private
 // channel. A new page load in the frame says hello again, and replaces the
 // channel. Call it before inserting the iframe, so no hello is missed.
-export function answerHellos({ frame, origin, server, window: win, }) {
+export function answerHellos({ frame, origin, server, window: win, onHello, }) {
     let current = null;
     const onMessage = function (event) {
         const target = frame.contentWindow;
@@ -180,6 +211,12 @@ export function answerHellos({ frame, origin, server, window: win, }) {
             !isHello(event.data)) {
             return;
         }
+        try {
+            onHello?.(event.data);
+        }
+        catch (err) {
+            log("error", "the page's hello listener failed.", err);
+        }
         const channel = new MessageChannel();
         const welcome = server.connect(channel.port1);
         if (current)

package/dist/client.d.ts

@@ -23,6 +23,23 @@ export interface Arcadible {
     readonly build: Build | null | undefined;
     /** Saves that carry over between the game's versions. */
     readonly saves: Saves;
+    /**
+     * Begins the game's initialization: call it first, before anything you
+     * await, and Arcadible shows the game's loading screen until `initEnd()`.
+     * It resolves as `ready` does, once the SDK and the saves are ready.
+     */
+    initBegin(): Promise<Ready>;
+    /**
+     * How far along the initialization is, from 0 to 1, measured however the
+     * game likes. Optional; a lower value than the last is ignored.
+     */
+    initProgress(fraction: number): void;
+    /**
+     * Ends the initialization, once the game's first frame is drawn:
+     * Arcadible takes its loading screen down, and this resolves once the
+     * game is visible.
+     */
+    initEnd(): Promise<void>;
 }
 export type ClientOptions = {
     window?: Window;

package/dist/client.js

@@ -4,6 +4,7 @@
 // [import]
 import { openBus } from "./bus/client.js";
 import { buildOf, REQUEST_TIMEOUT } from "./bus/protocol.js";
+import { createLifecycle } from "./lifecycle/client.js";
 import { indexedDBBackend } from "./saves/backend/indexeddb.js";
 import { createSaves } from "./saves/client.js";
 import { serve } from "./host.js";
@@ -20,9 +21,10 @@ const STANDALONE = {
 // [function]
 export function createClient(options = {}) {
     const backend = options.backend ?? (() => indexedDBBackend());
+    const win = options.window ?? (typeof window === "undefined" ? undefined : window);
     const bus = openBus({
         client: VERSION,
-        window: options.window,
+        window: win,
         origins: options.origins,
         handshakeTimeout: options.handshakeTimeout,
         requestTimeout: options.requestTimeout,
@@ -37,6 +39,7 @@ export function createClient(options = {}) {
         settled = { build: buildOf(welcome.build) };
         return settled;
     });
+    const lifecycle = createLifecycle(bus, win);
     return {
         version: VERSION,
         ready,
@@ -44,5 +47,15 @@ export function createClient(options = {}) {
             return settled ? settled.build : undefined;
         },
         saves,
+        initBegin() {
+            lifecycle.begin();
+            return ready;
+        },
+        initProgress(fraction) {
+            lifecycle.progress(fraction);
+        },
+        initEnd() {
+            return lifecycle.end();
+        },
     };
 }

package/dist/host.d.ts

@@ -1,4 +1,6 @@
+import type { Hello } from "./bus/protocol.js";
 import { type Server } from "./bus/server.js";
+import { type LifecycleHost } from "./lifecycle/server.js";
 import type { Backend } from "./saves/backend/types.js";
 import type { Where } from "./saves/rules.js";
 export type ServeOptions = {
@@ -8,11 +10,13 @@ export type ServeOptions = {
     backend: Backend;
     where?: Where;
     now?: () => Date;
+    lifecycle?: LifecycleHost;
 };
 type HostOptions = ServeOptions & {
     frame: HTMLIFrameElement;
     origin: string;
     window?: Window;
+    onHello?: (hello: Hello) => void;
 };
 export declare function serve(options: ServeOptions): Server;
 export declare function createHost(options: HostOptions): {

package/dist/host.js

@@ -1,7 +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]
 import { answerHellos, createServer } from "./bus/server.js";
+import { lifecycleServer } from "./lifecycle/server.js";
 import { savesServer } from "./saves/server.js";
 // [function]
 // Answers the bus for one game in one channel, on any number of ports.
@@ -17,6 +17,7 @@ export function serve(options) {
                 version,
                 where: options.where ?? "game",
             }),
+            ...(options.lifecycle ? [lifecycleServer(options.lifecycle)] : []),
         ],
     });
 }
@@ -30,6 +31,7 @@ export function createHost(options) {
         origin: options.origin,
         server: serve(options),
         window: options.window ?? window,
+        onHello: options.onHello,
     });
 }
 export { indexedDBBackend } from "./saves/backend/indexeddb.js";

package/dist/lifecycle/client.d.ts

@@ -0,0 +1,7 @@
+import type { Bus } from "../bus/client.js";
+export type Lifecycle = {
+    begin(): void;
+    progress(fraction: unknown): void;
+    end(): Promise<void>;
+};
+export declare function createLifecycle(bus: Bus, win: Window | undefined): Lifecycle;

package/dist/lifecycle/client.js

@@ -0,0 +1,88 @@
+// The game's side of its initialization: `initBegin`, `initProgress`, and
+// `initEnd` on `arcadible` (DESIGN.md, section 7, Initialization). The page
+// keeps its loading screen only for a game that began before its own `load`,
+// which this side reports, once, as it happens, so the page decides without
+// a timer. Calls after that do nothing, and the console says why once.
+import { isObject, log } from "../bus/protocol.js";
+import { END_TIMEOUT, fractionOf, Names } from "./rules.js";
+// [function]
+export function createLifecycle(bus, win) {
+    // began before the game's `load`: the loading screen is the page's to
+    // keep. `false` once `load` passed without a begin.
+    let begun = null;
+    let loaded = false;
+    let last = -1;
+    let ended = null;
+    let warnedLate = false;
+    let warnedValue = false;
+    const framed = Boolean(win && win.parent !== win);
+    const late = function (call) {
+        if (warnedLate || !framed)
+            return;
+        warnedLate = true;
+        log("warn", `${call} came after the page loaded, so Arcadible's loading screen was already down. Call initBegin() first, before anything you await.`);
+    };
+    const onLoad = function () {
+        if (loaded)
+            return;
+        loaded = true;
+        if (begun === null)
+            begun = false;
+        bus.emit(Names.Loaded, { begun });
+    };
+    const begin = function (call) {
+        if (begun !== null) {
+            if (!begun)
+                late(call);
+            return;
+        }
+        if (loaded) {
+            begun = false;
+            late(call);
+            return;
+        }
+        begun = true;
+        bus.emit(Names.Begin);
+    };
+    // [start]
+    // the game's own `load` is the frame's on the page: a game that began by
+    // then keeps the loading screen. A script that runs after it (added by
+    // code, late) reports at once.
+    if (win && typeof win.addEventListener === "function") {
+        if (win.document?.readyState === "complete")
+            onLoad();
+        else
+            win.addEventListener("load", onLoad, { once: true });
+    }
+    return {
+        begin() {
+            begin("initBegin");
+        },
+        progress(fraction) {
+            const value = fractionOf(fraction);
+            if (value === null) {
+                if (!warnedValue) {
+                    warnedValue = true;
+                    log("warn", "initProgress takes a number from 0 to 1.");
+                }
+                return;
+            }
+            begin("initProgress");
+            if (!begun || ended || value <= last)
+                return;
+            last = value;
+            bus.emit(Names.Progress, { fraction: value });
+        },
+        end() {
+            if (ended)
+                return ended;
+            begin("initEnd");
+            // a page without a loading screen, an older one, or none standing
+            // alone, answers `unsupported`: the game is visible already.
+            ended = begun
+                ? bus.request(Names.End, {}, isObject, { timeout: END_TIMEOUT }).then(() => undefined, () => undefined)
+                : Promise.resolve();
+            return ended;
+        },
+    };
+}

package/dist/lifecycle/rules.d.ts

@@ -0,0 +1,10 @@
+export declare const Names: {
+    readonly Begin: "lifecycle.initBegin";
+    readonly Progress: "lifecycle.initProgress";
+    readonly Loaded: "lifecycle.loaded";
+    readonly End: "lifecycle.initEnd";
+};
+export declare const INIT_SINCE = "1.3.0";
+export declare const END_TIMEOUT = 60000;
+export declare function reportsInit(client: unknown): boolean;
+export declare function fractionOf(value: unknown): number | null;

package/dist/lifecycle/rules.js

@@ -0,0 +1,53 @@
+// The game's initialization on the bus, shared by both ends: the messages'
+// names, and the first SDK that sends them (DESIGN.md, section 7,
+// Initialization). On the bus they're `lifecycle`'s; games call them on
+// `arcadible` itself.
+// [declare]
+export const Names = {
+    // the game began its initialization: an event.
+    Begin: "lifecycle.initBegin",
+    // how far along it is, `{ fraction }`, from 0 to 1: an event.
+    Progress: "lifecycle.initProgress",
+    // the game's own `load`, `{ begun }`: whether it began before it. An
+    // event, sent once, so the page decides without a timer.
+    Loaded: "lifecycle.loaded",
+    // its first frame is drawn: a request, answered once the game is visible.
+    End: "lifecycle.initEnd",
+};
+// The first SDK that sends them. An older one can't, so the page takes its
+// loading screen down at `load`, without waiting to hear.
+export const INIT_SINCE = "1.3.0";
+// How long `initEnd()` waits for the page to say the game is visible: past
+// the loading screen's minimum and fade, and a device held the wrong way
+// for a while. Past it, the game goes on as if visible.
+export const END_TIMEOUT = 60_000;
+// [function]
+// a version's numbers, `1.3.0-beta.1` as [1, 3, 0], or null.
+function numbers(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/u.exec(version);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+// [function]
+// Whether an SDK, by the version in its hello, can report its
+// initialization: `INIT_SINCE` or later. Anything unreadable can't.
+export function reportsInit(client) {
+    if (typeof client !== "string")
+        return false;
+    const have = numbers(client);
+    const since = numbers(INIT_SINCE);
+    if (!have)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (have[i] !== since[i])
+            return have[i] > since[i];
+    }
+    return true;
+}
+// [function]
+// a fraction as the page takes it: a finite number, clamped to 0 to 1, or
+// null.
+export function fractionOf(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    return Math.min(1, Math.max(0, value));
+}

package/dist/lifecycle/server.d.ts

@@ -0,0 +1,8 @@
+import type { Module } from "../bus/server.js";
+export type LifecycleHost = {
+    begin(): void;
+    progress(fraction: number): void;
+    loaded(begun: boolean): void;
+    end(): Promise<void>;
+};
+export declare function lifecycleServer(host: LifecycleHost): () => Module;

package/dist/lifecycle/server.js

@@ -0,0 +1,32 @@
+// The page's side of the game's initialization: it passes what the game
+// reports to the page's loading screen, and answers `initEnd` once the page
+// says the game is visible. A page without a loading screen leaves it out,
+// so `initEnd` gets `unsupported`, which a game takes as visible at once.
+// [import]
+import { isObject } from "../bus/protocol.js";
+import { fractionOf, Names } from "./rules.js";
+// [function]
+export function lifecycleServer(host) {
+    return () => ({
+        handlers: {
+            [Names.End]: {
+                parallel: true,
+                run: async () => {
+                    await host.end();
+                    return {};
+                },
+            },
+        },
+        events: {
+            [Names.Begin]: () => host.begin(),
+            [Names.Progress]: (data) => {
+                const fraction = isObject(data) ? fractionOf(data["fraction"]) : null;
+                if (fraction !== null)
+                    host.progress(fraction);
+            },
+            [Names.Loaded]: (data) => {
+                host.loaded(isObject(data) && data["begun"] === true);
+            },
+        },
+    });
+}

package/dist/saves/rules.d.ts

@@ -47,7 +47,6 @@ export declare function checkWrite(saves: ReadonlyMap<string, {
 }>, 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

@@ -65,7 +65,7 @@ export function isSaveInfoOrNull(value) {
             typeof value["savedAt"] === "string"));
 }
 // [function]
-export function isSave(value) {
+function isSave(value) {
     return (isObject(value) &&
         checkName(value["name"]) === null &&
         typeof value["data"] === "string" &&

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.2.2";
+export declare const VERSION = "1.3.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.2.2";
+export const VERSION = "1.3.0";

package/package.json

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