@arcadible/sdk 1.3.1 → 1.4.1

package/README.md

@@ -35,13 +35,13 @@ 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.initBegin(); // first thing in your game's code
+await arcadible.initStart(); // first thing in your game's code
 arcadible.initProgress(0.5);
 // … load, build the scene, and draw the first frame …
-await arcadible.initEnd();
+await arcadible.initComplete();
 ```
 
-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.
+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.
 
 ## Save and load
 
@@ -54,9 +54,9 @@ const progress = saved ? JSON.parse(saved) : { level: 1 };
 await arcadible.saves.write("progress", JSON.stringify(progress));
 ```
 
-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.
+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 `initEnd()` resolves at once, saves are kept in the game's own browser storage, `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 `initComplete()` 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
 

package/dist/bus/protocol.js

@@ -1,6 +1,6 @@
 // The bus's rules, shared by both ends so they can't drift apart: the
 // handshake, the message shapes, the error codes, and the limits on what
-// crosses it (DESIGN.md, section 4). It knows nothing of any module.
+// crosses it. It knows nothing of any module.
 // [declare]
 // The bus's own version: the handshake and the message shapes. New modules,
 // names, and fields are additions within it.
@@ -15,9 +15,9 @@ export const REQUEST_TIMEOUT = 10_000;
 // included, whatever framed it. Who may frame a build is decided outside the
 // game, where it can change: on Arcadible by each build's `frame-ancestors`,
 // which the browser enforces before the game runs, and elsewhere by whoever
-// serves it. So the host is never trusted with anything of value (DESIGN.md,
-// section 4). Only `null` is refused: a `file://` page or a sandboxed frame,
-// which can't be told apart.
+// serves it. So the host is never trusted with anything of value. Only
+// `null` is refused: a `file://` page or a sandboxed frame, which can't be
+// told apart.
 export function isHostOrigin(origin, origins) {
     return origins
         ? origins.includes(origin)
@@ -29,7 +29,7 @@ export const MAX_IN_FLIGHT = 64;
 // The largest message either side sends: room for a whole 1 MB save, or
 // every save at once (a game's are 1 MB together), and the rest of the
 // message. The page refuses a larger request, and never sends a larger
-// answer or event (DESIGN.md, section 4).
+// answer or event.
 export const MAX_MESSAGE = 1024 * 1024 + 64 * 1024;
 // [declare]
 // Every code a call can fail with. Worth retrying: `busy`, `timeout`, and
@@ -40,6 +40,7 @@ export const Codes = {
     Busy: "busy",
     Full: "full",
     Invalid: "invalid",
+    // only `readSync`, `listSync`, and `infoSync` throw it, before `ready`.
     NotReady: "not_ready",
     Timeout: "timeout",
     TooLarge: "too_large",

package/dist/client.d.ts

@@ -24,22 +24,23 @@ export interface Arcadible {
     /** 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()`.
+     * Starts the game's initialization: call it first, before anything you
+     * await, and Arcadible shows the game's loading screen until
+     * `initComplete()`.
      * It resolves as `ready` does, once the SDK and the saves are ready.
      */
-    initBegin(): Promise<Ready>;
+    initStart(): 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:
+     * Completes 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>;
+    initComplete(): Promise<void>;
 }
 export type ClientOptions = {
     window?: Window;

package/dist/client.js

@@ -47,15 +47,15 @@ export function createClient(options = {}) {
             return settled ? settled.build : undefined;
         },
         saves,
-        initBegin() {
-            lifecycle.begin();
+        initStart() {
+            lifecycle.start();
             return ready;
         },
         initProgress(fraction) {
             lifecycle.progress(fraction);
         },
-        initEnd() {
-            return lifecycle.end();
+        initComplete() {
+            return lifecycle.complete();
         },
     };
 }

package/dist/lifecycle/client.d.ts

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

package/dist/lifecycle/client.js

@@ -1,18 +1,18 @@
-// 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.
+// The game's side of its initialization: `initStart`, `initProgress`, and
+// `initComplete` on `arcadible`. The page keeps its loading screen only for
+// a game that started 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";
+import { COMPLETE_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;
+    // started before the game's `load`: the loading screen is the page's to
+    // keep. `false` once `load` passed without a start.
+    let started = null;
     let loaded = false;
     let last = -1;
-    let ended = null;
+    let completed = null;
     let warnedLate = false;
     let warnedValue = false;
     const framed = Boolean(win && win.parent !== win);
@@ -20,33 +20,33 @@ export function createLifecycle(bus, win) {
         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.`);
+        log("warn", `${call} came after the page loaded, so Arcadible's loading screen was already down. Call initStart() 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 });
+        if (started === null)
+            started = false;
+        bus.emit(Names.Loaded, { started });
     };
-    const begin = function (call) {
-        if (begun !== null) {
-            if (!begun)
+    const start = function (call) {
+        if (started !== null) {
+            if (!started)
                 late(call);
             return;
         }
         if (loaded) {
-            begun = false;
+            started = false;
             late(call);
             return;
         }
-        begun = true;
-        bus.emit(Names.Begin);
+        started = true;
+        bus.emit(Names.Start);
     };
     // [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
+    // the game's own `load` is the frame's on the page: a game that started
+    // 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")
@@ -55,8 +55,8 @@ export function createLifecycle(bus, win) {
             win.addEventListener("load", onLoad, { once: true });
     }
     return {
-        begin() {
-            begin("initBegin");
+        start() {
+            start("initStart");
         },
         progress(fraction) {
             const value = fractionOf(fraction);
@@ -67,22 +67,26 @@ export function createLifecycle(bus, win) {
                 }
                 return;
             }
-            begin("initProgress");
-            if (!begun || ended || value <= last)
+            start("initProgress");
+            if (!started || completed || value <= last)
                 return;
             last = value;
             bus.emit(Names.Progress, { fraction: value });
         },
-        end() {
-            if (ended)
-                return ended;
-            begin("initEnd");
+        complete() {
+            if (completed)
+                return completed;
+            start("initComplete");
             // 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)
+            completed = started
+                ? bus
+                    .request(Names.Complete, {}, isObject, {
+                    timeout: COMPLETE_TIMEOUT,
+                })
+                    .then(() => undefined, () => undefined)
                 : Promise.resolve();
-            return ended;
+            return completed;
         },
     };
 }

package/dist/lifecycle/rules.d.ts

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

package/dist/lifecycle/rules.js

@@ -1,28 +1,27 @@
 // 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.
+// names, and the first SDK that sends them. 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",
+    // the game started its initialization: an event.
+    Start: "lifecycle.initStart",
     // 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
+    // the game's own `load`, `{ started }`: whether it started 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",
+    Complete: "lifecycle.initComplete",
 };
-// The first SDK that sends them. An older one can't, so the page takes its
+// 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.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;
+export const INIT_SINCE = "1.4.0";
+// How long `initComplete()` 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 COMPLETE_TIMEOUT = 60_000;
 // [function]
-// a version's numbers, `1.3.0-beta.1` as [1, 3, 0], or null.
+// a version's numbers, `1.4.0-beta.1` as [1, 4, 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;

package/dist/lifecycle/server.d.ts

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

package/dist/lifecycle/server.js

@@ -1,7 +1,8 @@
 // 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.
+// reports to the page's loading screen, and answers `initComplete` once the
+// page says the game is visible. A page without a loading screen leaves it
+// out, so `initComplete` gets `unsupported`, which a game takes as visible
+// at once.
 // [import]
 import { isObject } from "../bus/protocol.js";
 import { fractionOf, Names } from "./rules.js";
@@ -9,23 +10,23 @@ import { fractionOf, Names } from "./rules.js";
 export function lifecycleServer(host) {
     return () => ({
         handlers: {
-            [Names.End]: {
+            [Names.Complete]: {
                 parallel: true,
                 run: async () => {
-                    await host.end();
+                    await host.complete();
                     return {};
                 },
             },
         },
         events: {
-            [Names.Begin]: () => host.begin(),
+            [Names.Start]: () => host.start(),
             [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);
+                host.loaded(isObject(data) && data["started"] === true);
             },
         },
     });

package/dist/saves/client.d.ts

@@ -12,17 +12,28 @@ export interface Saves {
     info(name: string): Promise<SaveInfo | null>;
     /** Removes the save, if there is one. */
     remove(name: string): Promise<void>;
-    /** After `ready`, the save's string from memory; before it, throws `not_ready`. */
+    /**
+     * The save's string from memory, once `ready` has settled; before it,
+     * throws `not_ready`. Prefer `await read(name)`: read once as the game
+     * starts, and keep the state in the game.
+     */
     readSync(name: string): string | null;
-    /** After `ready`, the names of the game's saves from memory, sorted. */
+    /**
+     * The names of the game's saves from memory, sorted, once `ready` has
+     * settled. Prefer `await list()`.
+     */
     listSync(): string[];
-    /** After `ready`, the save's version and time from memory, or `null`. */
+    /**
+     * Which version wrote the save, and when, from memory, once `ready` has
+     * settled. Prefer `await info(name)`.
+     */
     infoSync(name: string): SaveInfo | null;
     /**
-     * Who can read the saves back, once `ready` has settled: `"game"` (every
-     * version of the game), `"build"` (only this build), or `"memory"` (only
-     * until the page closes). `undefined` until it's known. Other values may
-     * be added: treat one you don't know as `"game"`.
+     * Who can read the saves back, once `initStart()` or `ready` has
+     * settled: `"game"` (every version of the game), `"build"` (only this
+     * build), or `"memory"` (only until the page closes). `undefined` until
+     * it's known. Other values may be added: treat one you don't know as
+     * `"game"`.
      */
     readonly where: Where | undefined;
 }

package/dist/saves/rules.js

@@ -1,9 +1,9 @@
 // Saves' rules, shared by the game's side and the page's so they can't drift
-// apart: the shapes, the limits, and their checks (DESIGN.md, section 6).
+// apart: the shapes, the limits, and their checks.
 // [import]
 import { ArcadibleError, Codes, isNumber, isObject, isStringOrNull, utf8Size, } from "../bus/protocol.js";
 // [declare]
-// Saves' limits, the same everywhere (DESIGN.md, section 6, Limits).
+// Saves' limits, the same everywhere.
 export const MAX_SAVES = 32;
 // Every save's document together, in UTF-8 bytes.
 export const MAX_TOTAL = 1024 * 1024;
@@ -48,8 +48,8 @@ export function checkWrite(saves, name, data) {
     return null;
 }
 // [function]
-// What the page sends of a save, checked for only what a game relies on
-// (DESIGN.md, The host is never trusted): extra fields pass.
+// What the page sends of a save, checked for only what a game relies on,
+// since the host is never trusted: extra fields pass.
 export function isSaveMeta(value) {
     return (isObject(value) &&
         isStringOrNull(value["version"]) &&

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.3.1";
+export declare const VERSION = "1.4.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.3.1";
+export const VERSION = "1.4.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "author": "Offst, Inc.",
-  "description": "The Arcadible SDK: saves that carry over between a game's versions on Arcadible.",
+  "description": "The Arcadible SDK: Arcadible's loading screen for a game's initialization, and saves that carry over between its versions.",
   "devDependencies": {
     "@playwright/test": "1.63.0",
     "@types/node": "^25.0.3",
@@ -43,5 +43,5 @@
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.3.1"
+  "version": "1.4.1"
 }