@arcadible/sdk 1.2.1 → 1.3.0

package/README.md

@@ -27,34 +27,31 @@ Each build of a game on [Arcadible](https://arcadible.com) has its own origin, s
 npm install @arcadible/sdk
 ```
 
-Use the package in a game with a build step, such as a Vite project. A game without one includes the hosted script instead, which Arcadible serves from every build's own origin, as `arc serve` does locally:
-
-```html
-<script src="/arcadible/sdk/v1.js"></script>
-```
+The package is for a game with a build step, such as a Vite project. A game without one uses the [hosted script](https://developer.arcadible.com/references/arcadible-sdk#install) instead.
 
 ## Save and load
 
 ```js
 import { arcadible } from "@arcadible/sdk";
 
+// at startup: once the saves have loaded, the player's progress, or a new game.
 await arcadible.ready;
-
-const saved = arcadible.saves.readSync("progress");
+const saved = await arcadible.saves.read("progress");
 const progress = saved ? JSON.parse(saved) : { level: 1 };
 
+// at a checkpoint:
 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`, `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.
+A save is a name holding one string. `arcadible.ready` settles once the game's saves have loaded, and never fails; calls made before it wait for it, and from then on `readSync`, `listSync`, and `infoSync` answer at once from memory, for reads during play. 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, `arcadible.saves.where` is `"build"`, and `arcadible.build` is `null`.
 
 ## Learn more
 
-- [Saves](https://developer.arcadible.com/build/saves): adding the SDK, what to save, and other versions' saves.
+- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): installing it, the hosted script, `ready` and `build`, and every code.
 - [`arcadible.saves`](https://developer.arcadible.com/references/arcadible-sdk/saves): every call, what it returns, and when it fails.
-- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): `ready` and `build`, and every code.
+- [Saves](https://developer.arcadible.com/build/saves): using saves well, across versions, channels, and tabs, and where they're kept.
 - [Limits](https://developer.arcadible.com/references/limits#saves): how many saves, and how large.
 
 ## License

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.1";
+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.1";
+export const VERSION = "1.3.0";

package/package.json

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