@arcadible/sdk 1.2.2 → 1.3.1

package/README.md

@@ -7,11 +7,12 @@
 <h1 align="center">Arcadible SDK</h1>
 
 <p align="center">
-  Saves that carry over from one version of your game to the next.
+  Arcadible's loading screen for your game, and saves that carry over from one version to the next.
 </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://arcadible.com">Arcadible</a> ·
   <a href="https://studio.arcadible.com">Studio</a>
@@ -19,7 +20,7 @@
 
 <br>
 
-Each build of a game on [Arcadible](https://arcadible.com) has its own origin, so its browser storage starts empty with every update. Saves made through the Arcadible SDK are kept by the play page instead, on the player's device, so they carry over. The SDK is optional, and saves are all it does.
+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.
 
 ## Install
 
@@ -29,29 +30,39 @@ npm install @arcadible/sdk
 
 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
+## Initialization
 
 ```js
 import { arcadible } from "@arcadible/sdk";
 
-// at startup: once the saves have loaded, the player's progress, or a new game.
-await arcadible.ready;
+await arcadible.initBegin(); // first thing in your game's code
+arcadible.initProgress(0.5);
+// … load, build the scene, and draw the first frame …
+await arcadible.initEnd();
+```
+
+Call `initBegin()` 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 `initEnd()` once your first frame is drawn. Arcadible shows your splash and the progress until then, and `initEnd()` resolves once the loading screen has faded into your game.
+
+## Save and load
+
+```js
+// once the saves have loaded
 const saved = await arcadible.saves.read("progress");
 const progress = saved ? JSON.parse(saved) : { level: 1 };
 
-// at a checkpoint:
+// at a checkpoint
 await arcadible.saves.write("progress", JSON.stringify(progress));
 ```
 
-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.
+A save is a name holding one string. Once `initBegin()` has resolved, `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`.
+Off Arcadible, such as on your dev server, the package still works, with the same rules and limits: there's no loading screen, so `initEnd()` resolves at once, saves are kept in the game's own browser storage, `arcadible.saves.where` is `"build"`, and `arcadible.build` is `null`.
 
 ## Learn more
 
-- [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.
+- [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.
 - [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() as your code starts, before anything you await or schedule for later.`);
+    };
+    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.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.2.2";
+export const VERSION = "1.3.1";

package/package.json

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