@arcadible/sdk 1.5.2 → 1.5.3-next.6

package/README.md

@@ -15,18 +15,14 @@
   <a href="https://developer.arcadible.com/build/initialization">Initialization</a> ·
   <a href="https://developer.arcadible.com/build/saves">Saves</a> ·
   <a href="https://developer.arcadible.com/build/pausing">Pausing</a> ·
+  <a href="https://developer.arcadible.com/build/players">Players</a> ·
   <a href="https://arcadible.com">Arcadible</a> ·
   <a href="https://studio.arcadible.com">Studio</a>
 </p>
 
 <br>
 
-The Arcadible SDK is optional: a game runs on [Arcadible](https://arcadible.com) without it. With it, a game gets these from the play page around it:
-
-- **[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.
-- **[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.
-- **[Pausing](https://developer.arcadible.com/build/pausing):** Arcadible tells the game when to stop, go quiet, and save, and when to carry on.
-- **[`system` and `context`](https://developer.arcadible.com/references/arcadible-sdk#system):** the store's language, and when this run launched.
+The Arcadible SDK is optional: it's how your game works with [Arcadible](https://arcadible.com), such as [showing a loading screen](https://developer.arcadible.com/build/initialization), [keeping saves across versions](https://developer.arcadible.com/build/saves), and [knowing who's playing](https://developer.arcadible.com/build/players). Everything it does, and every call, is in the [Arcadible SDK reference](https://developer.arcadible.com/references/arcadible-sdk).
 
 ## Install
 
@@ -42,8 +38,9 @@ The package is for a game with a build step, such as a Vite project. A game with
 import { arcadible } from "@arcadible/sdk";
 
 await arcadible.initStart(); // as your code starts, before anything it awaits
+// … load your files …
 arcadible.initProgress(0.5);
-// … load, build the scene, and draw the first frame …
+// … build the scene, and draw the first frame …
 await arcadible.initComplete();
 ```
 
@@ -83,7 +80,8 @@ Arcadible pauses your game when the page is hidden, when it covers your game, an
 - [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.
 - [Pausing](https://developer.arcadible.com/build/pausing): what a pause asks of your game, and resuming.
-- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): including it, every call, the saves' included, `system` and `context`, and every code.
+- [Players](https://developer.arcadible.com/build/players): who's playing, a guest or logged in, their name and picture.
+- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): including it, every call (saves and players have pages of their own), `system` and `context`, and every code.
 - [Limits](https://developer.arcadible.com/references/limits#saves): how many saves, and how large.
 
 ## License

package/dist/bus/protocol.d.ts

@@ -6,6 +6,8 @@ export declare const MAX_IN_FLIGHT = 64;
 export declare const MAX_MESSAGE: number;
 export declare const Codes: {
     readonly Busy: "busy";
+    readonly Conflict: "conflict";
+    readonly Denied: "denied";
     readonly Full: "full";
     readonly Invalid: "invalid";
     readonly NotReady: "not_ready";

package/dist/bus/protocol.js

@@ -33,11 +33,17 @@ export const MAX_IN_FLIGHT = 64;
 export const MAX_MESSAGE = 1024 * 1024 + 64 * 1024;
 // [declare]
 // Every code a call can fail with. Worth retrying: `busy`, `timeout`, and
-// `unavailable`. Not: `full` (the device has no room; the player must free
-// some), `invalid`, `too_large`, and `too_many`. More may come: a game
+// `unavailable`, and `conflict` once the value is read again. Not: `full`
+// (no room, on the device or in a player's values; something must be
+// freed), `denied`, `invalid`, `too_large`, and `too_many`. More may come: a game
 // treats a code it doesn't know as `unavailable`.
 export const Codes = {
     Busy: "busy",
+    // a value was written since the revision a write named: read it again.
+    Conflict: "conflict",
+    // Arcadible doesn't allow the call: a game reads the developer's and the
+    // game's values, and reads and writes its own player's, who's logged in.
+    Denied: "denied",
     Full: "full",
     Invalid: "invalid",
     // only `readSync`, `listSync`, and `infoSync` throw it, before `ready`.

package/dist/client.d.ts

@@ -2,8 +2,11 @@ import { type Build } from "./bus/protocol.js";
 import { type Context } from "./context/client.js";
 import { type System } from "./system/client.js";
 import { type Players } from "./players/client.js";
+import { type Functions } from "./runner/client.js";
 import type { Backend } from "./saves/backend/types.js";
 import { type Saves } from "./saves/client.js";
+import { type Tickets } from "./tickets/client.js";
+import { type Values } from "./values/client.js";
 export type Ready = {
     build: Build | null;
 };
@@ -47,6 +50,25 @@ export interface Arcadible {
      * `undefined` before.
      */
     readonly players: Players;
+    /**
+     * The game's function, its server code that Arcadible runs: `url`, where
+     * it is, fixed for the run, and `fetch(path, init)`, a request to it
+     * that carries the game's ticket.
+     */
+    readonly functions: Functions;
+    /**
+     * Tickets for the game's own servers: `get(server)`, proof of the game,
+     * the build, and the player, which a server checks.
+     */
+    readonly tickets: Tickets;
+    /**
+     * The game's data kept on Arcadible, JSON under a key: what its developer
+     * published (`"developer"`) and what the game shares (`"game"`), to read,
+     * and the player's own (`players.primary`), to read and write, wherever
+     * they play. `read`, `write`, `list`, and `remove`, each taking a key or
+     * a list of keys; `scope(scope)` for the same with the scope named once.
+     */
+    readonly values: Values;
     /**
      * Starts the game's initialization: call it as your code starts, before
      * anything it awaits, and Arcadible shows the game's loading screen until
@@ -86,5 +108,6 @@ export type ClientOptions = {
     handshakeTimeout?: number;
     requestTimeout?: number;
     backend?: () => Backend;
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
 };
 export declare function createClient(options?: ClientOptions): Arcadible;

package/dist/client.js

@@ -9,8 +9,11 @@ import { createPause } from "./lifecycle/pause.js";
 import { createContextClient } from "./context/client.js";
 import { createSystemClient } from "./system/client.js";
 import { createPlayersClient } from "./players/client.js";
+import { createFunctionsClient } from "./runner/client.js";
 import { indexedDBBackend } from "./saves/backend/indexeddb.js";
 import { createSaves } from "./saves/client.js";
+import { createTicketsClient } from "./tickets/client.js";
+import { createValuesClient } from "./values/client.js";
 import { serve } from "./host.js";
 import { VERSION } from "./version.js";
 // The scope a game standing alone keeps its saves under, on its own origin,
@@ -42,10 +45,18 @@ export function createClient(options = {}) {
     const system = createSystemClient(bus);
     const context = createContextClient(bus);
     const players = createPlayersClient(bus);
+    const tickets = createTicketsClient(bus);
+    const values = createValuesClient(bus);
+    const functions = createFunctionsClient(bus, {
+        fetch: options.fetch ?? ((url, init) => fetch(url, init)),
+        // set below: a request made before `ready` waits on it.
+        ready: () => ready,
+        tickets: tickets.tickets,
+    });
     const lifecycle = createLifecycle(bus, win);
     const pause = createPause(bus);
     // the ones `ready` waits on, or tells: lifecycle and pause do neither.
-    const parts = [saves, system, context, players];
+    const parts = [saves, system, context, players, functions];
     let settled = null;
     // ready once welcomed, and each module's first messages have arrived;
     // then each is told, so its facts are known, or null.
@@ -72,6 +83,9 @@ export function createClient(options = {}) {
             return context.value;
         },
         players: players.players,
+        functions: functions.functions,
+        tickets: tickets.tickets,
+        values: values.values,
         initStart() {
             lifecycle.start();
             return ready;

package/dist/host.d.ts

@@ -7,8 +7,11 @@ import { type System } from "./system/server.js";
 import { type LifecycleHost } from "./lifecycle/server.js";
 import { type SignedIn } from "./players/host.js";
 import { type PlayersHost } from "./players/server.js";
+import type { RunnerState } from "./runner/rules.js";
 import type { Backend } from "./saves/backend/types.js";
 import type { Where } from "./saves/rules.js";
+import { type TicketsHost } from "./tickets/server.js";
+import { type ValuesHost } from "./values/server.js";
 export type ServeOptions = {
     game: string;
     channel: string;
@@ -21,6 +24,9 @@ export type ServeOptions = {
     system?: System;
     context?: ContextState;
     players?: PlayersHost;
+    runner?: RunnerState;
+    tickets?: TicketsHost;
+    values?: ValuesHost;
 };
 export type Host = {
     close(): void;
@@ -31,6 +37,7 @@ export type Host = {
 type HostOptions = Omit<ServeOptions, "holds" | "system" | "context" | "players"> & {
     player?: SignedIn | null;
     fetch?: (url: string) => Promise<Response>;
+    logIn?: (() => Promise<void>) | undefined;
     language?: string;
     launchedAt?: string;
     frame: HTMLIFrameElement;

package/dist/host.js

@@ -11,7 +11,10 @@ import { createSystem } from "./system/server.js";
 import { lifecycleServer } from "./lifecycle/server.js";
 import { playersHost } from "./players/host.js";
 import { playersServer } from "./players/server.js";
+import { runnerServer } from "./runner/server.js";
 import { savesServer } from "./saves/server.js";
+import { ticketsServer } from "./tickets/server.js";
+import { valuesServer } from "./values/server.js";
 // [function]
 // Answers the bus for one game in one channel, on any number of ports.
 export function serve(options) {
@@ -25,6 +28,7 @@ export function serve(options) {
             ...(options.system ? [options.system.module] : []),
             ...(options.context ? [contextServer(options.context)] : []),
             ...(options.players ? [playersServer(options.players)] : []),
+            ...(options.runner ? [runnerServer(options.runner)] : []),
             savesServer({
                 backend,
                 now: options.now ?? (() => new Date()),
@@ -32,6 +36,8 @@ export function serve(options) {
                 version,
                 where: options.where ?? "game",
             }),
+            ...(options.tickets ? [ticketsServer(options.tickets)] : []),
+            ...(options.values ? [valuesServer(options.values)] : []),
             ...(options.lifecycle ? [lifecycleServer(options.lifecycle)] : []),
         ],
     });
@@ -74,6 +80,7 @@ export function createHost(options) {
                         backend: options.backend,
                         fetch: options.fetch ?? ((url) => win.fetch(url)),
                         game: options.game,
+                        logIn: options.logIn,
                         player: options.player,
                     }),
                 }),

package/dist/index.d.ts

@@ -7,5 +7,8 @@ export type { Saves } from "./saves/client.js";
 export type { System } from "./system/client.js";
 export type { Context } from "./context/client.js";
 export type { Players } from "./players/client.js";
-export type { Player } from "./players/rules.js";
+export type { Player, PlayerId } from "./players/rules.js";
+export type { Functions } from "./runner/client.js";
+export type { Tickets } from "./tickets/client.js";
+export type { Entry, Item, Listed, ListOptions, ReadableValues, Scope, ScopedValues, Value, Values, Written, } from "./values/client.js";
 export type { SaveInfo } from "./saves/rules.js";

package/dist/players/client.d.ts

@@ -1,5 +1,5 @@
 import type { Bus } from "../bus/client.js";
-import { type Player } from "./rules.js";
+import { type Player, type PlayerId } from "./rules.js";
 /** Who's playing. */
 export interface Players {
     /**
@@ -11,11 +11,21 @@ export interface Players {
     readonly primary: Player | null | undefined;
     /**
      * Each player's picture, 256 × 256, as WebP, in the order given: a Blob,
-     * or `null` for a player with none (a guest always). Takes players or
-     * their ids, up to 50. Rejects with `unavailable` when the pictures can't
-     * be reached, as offline.
+     * or `null` for a player with none (a guest always), and for a missing
+     * player, such as `primary` off Arcadible. Takes players or their ids, up
+     * to 50. Rejects with `unavailable` when the pictures can't be reached, as
+     * offline.
      */
-    pictures(players: readonly (Player | string)[]): Promise<(Blob | null)[]>;
+    pictures(players: readonly (Player | PlayerId | null | undefined)[]): Promise<(Blob | null)[]>;
+    /**
+     * Has Arcadible offer a guest a log-in, in a small notice of its own over
+     * the game: call it when a player asks to log in, or reaches something
+     * that needs an account. Resolves once the offer is up, or at once for a
+     * player who's logged in already; it never says whether they took it,
+     * since logging in ends the run, and the next one starts as them. Rejects
+     * with `unavailable` where no log-in can be offered, as off Arcadible.
+     */
+    logIn(): Promise<void>;
 }
 export type PlayersClient = {
     players: Players;

package/dist/players/client.js

@@ -1,7 +1,7 @@
 // The game's side of `players`: `arcadible.players`, who's playing. Its
 // `primary` is a fact, fixed for the run: `undefined` before `ready`, and
 // `null` where no page says (standing alone, or an older page). Pictures
-// are asked for when a game draws them.
+// are asked for when a game draws them, and a log-in is the page's to offer.
 import { ArcadibleError, Codes, isObject, log } from "../bus/protocol.js";
 import { fact } from "../facts.js";
 import { isId, isPicture, MAX_PICTURES, Names, PICTURES_PER_REQUEST, stateOf, } from "./rules.js";
@@ -11,7 +11,8 @@ function isAnswer(length) {
     return (value) => Array.isArray(value) && value.length === length;
 }
 // [function]
-// the ids a game asked for, checked before anything is sent.
+// the ids a game asked for, checked before anything is sent: `null` for a
+// missing player, such as `primary` off Arcadible, which has no picture.
 function idsOf(players) {
     if (!Array.isArray(players)) {
         throw new ArcadibleError(Codes.Invalid, "players.pictures takes an array of players, or of their ids.");
@@ -20,6 +21,8 @@ function idsOf(players) {
         throw new ArcadibleError(Codes.TooMany, `players.pictures takes up to ${MAX_PICTURES} players at once, not ${players.length}.`);
     }
     return players.map((entry, index) => {
+        if (entry === null || entry === undefined)
+            return null;
         const id = isObject(entry) ? entry["id"] : entry;
         if (!isId(id)) {
             throw new ArcadibleError(Codes.Invalid, `players.pictures takes players, or their ids: entry ${index} is neither.`);
@@ -64,12 +67,33 @@ export function createPlayersClient(bus) {
         },
         async pictures(list) {
             const ids = idsOf(list);
+            // only the players there are: a missing one is no picture, and isn't
+            // asked for.
+            const wanted = ids.filter((id) => id !== null);
             // a few at a time, so every answer fits a message.
-            const pictures = [];
-            for (let at = 0; at < ids.length; at += PICTURES_PER_REQUEST) {
-                pictures.push(...(await ask(ids.slice(at, at + PICTURES_PER_REQUEST))));
+            const found = [];
+            for (let at = 0; at < wanted.length; at += PICTURES_PER_REQUEST) {
+                found.push(...(await ask(wanted.slice(at, at + PICTURES_PER_REQUEST))));
+            }
+            let next = 0;
+            return ids.map((id) => (id === null ? null : (found[next++] ?? null)));
+        },
+        async logIn() {
+            // logged in already: there's nothing to offer.
+            if (primary.value && !primary.value.guest)
+                return;
+            try {
+                await bus.request(Names.LogIn, {}, isObject);
+            }
+            catch (err) {
+                // no page to ask (standing alone), one from before log-ins, or one
+                // that didn't answer in time: no log-in is offered now.
+                if (err instanceof ArcadibleError &&
+                    (err.code === Codes.Unsupported || err.code === Codes.Timeout)) {
+                    throw new ArcadibleError(Codes.Unavailable, "A log-in can't be offered here.");
+                }
+                throw err;
             }
-            return pictures;
         },
     };
     return { players, settle: () => primary.settle() };

package/dist/players/host.d.ts

@@ -10,5 +10,6 @@ export type PlayersHostOptions = {
     backend: Backend;
     game: string;
     fetch: (url: string) => Promise<Response>;
+    logIn?: (() => Promise<void>) | undefined;
 };
 export declare function playersHost(options: PlayersHostOptions): PlayersHost;

package/dist/players/host.js

@@ -1,7 +1,7 @@
 // Who a play page's game runs for: the player signed in, from the page's
 // own lookup, or the device's guest in this game.
 // [import]
-import { log } from "../bus/protocol.js";
+import { ArcadibleError, Codes, log } from "../bus/protocol.js";
 import { isId } from "./rules.js";
 // [function]
 // Only the primary's picture is found, fetched from its address when a
@@ -46,5 +46,14 @@ export function playersHost(options) {
             });
             return picture;
         },
+        async logIn() {
+            // signed in already: nothing to offer.
+            if (signedIn)
+                return;
+            if (!options.logIn) {
+                throw new ArcadibleError(Codes.Unavailable, "A log-in can't be offered here.");
+            }
+            await options.logIn();
+        },
     };
 }

package/dist/players/rules.d.ts

@@ -1,12 +1,15 @@
 export declare const Names: {
     readonly State: "players.state";
     readonly Pictures: "players.pictures";
+    readonly LogIn: "players.logIn";
 };
+/** A player's id in this game: a UUID, in lowercase. */
+export type PlayerId = string;
 /** A player, as a game sees one. */
 export interface Player {
     /** This player in this game: a UUID, the same every run, different in every game. */
-    readonly id: string;
-    /** Signed out: playing on this device, with no account. */
+    readonly id: PlayerId;
+    /** Logged out: playing on this device, with no account. */
     readonly guest: boolean;
     /** The profile's name, as players see it; null for a guest, or with none. */
     readonly name: string | null;
@@ -19,7 +22,7 @@ export declare const PICTURES_PER_REQUEST = 10;
 export declare const MAX_PICTURE: number;
 export declare const PICTURE_TYPE = "image/webp";
 /** Whether a value is a player's id: a UUID, in lowercase. */
-export declare function isId(value: unknown): value is string;
+export declare function isId(value: unknown): value is PlayerId;
 /**
  * A new id, for a guest: a random UUID. `crypto.randomUUID` isn't on
  * plain-http pages, as a development play page is, so it's built from

package/dist/players/rules.js

@@ -1,5 +1,5 @@
 // `players` on the bus, shared by both ends: who's playing, fixed for the
-// run, and their pictures, on demand.
+// run, their pictures, on demand, and a log-in, offered to a guest.
 // [import]
 import { isObject } from "../bus/protocol.js";
 // [declare]
@@ -8,6 +8,9 @@ export const Names = {
     State: "players.state",
     // pictures, a request with `{ ids }`, answered with a Blob or null each.
     Pictures: "players.pictures",
+    // a log-in, offered to a guest by the page: a request with nothing,
+    // answered once the offer is up.
+    LogIn: "players.logIn",
 };
 // The most pictures one call asks for.
 export const MAX_PICTURES = 50;

package/dist/players/server.d.ts

@@ -3,5 +3,6 @@ import { type Player } from "./rules.js";
 export type PlayersHost = {
     primary(): Promise<Player>;
     picture(id: string): Promise<Blob | null>;
+    logIn?(): Promise<void>;
 };
 export declare function playersServer(host: PlayersHost): () => Module;

package/dist/players/server.js

@@ -1,5 +1,6 @@
 // The page's side of `players`: who's playing, sent once as the game
-// connects, and their pictures, fetched when a game asks. It never changes
+// connects, their pictures, fetched when a game asks, and a log-in, which
+// the page offers a guest when a game asks. Who's playing never changes
 // during the run: the page ends the run when the player does.
 // [import]
 import { ArcadibleError, Codes, log } from "../bus/protocol.js";
@@ -36,8 +37,25 @@ export function playersServer(host) {
             return null;
         });
     };
+    const logIn = async function () {
+        try {
+            if (!host.logIn)
+                throw new Error("The page offers no log-in.");
+            await host.logIn();
+        }
+        catch (err) {
+            // whatever the page's reason, the game is told one thing.
+            if (!(err instanceof ArcadibleError)) {
+                log("warn", "a log-in couldn't be offered.", err);
+            }
+            throw new ArcadibleError(Codes.Unavailable, "A log-in can't be offered here.");
+        }
+        return {};
+    };
     return () => ({
         handlers: {
+            // beside the queue: it waits on the page, not on storage.
+            [Names.LogIn]: { run: logIn, parallel: true },
             // beside the queue: it waits on the network, not on storage.
             [Names.Pictures]: { run: pictures, parallel: true },
         },

package/dist/runner/client.d.ts

@@ -0,0 +1,34 @@
+import type { Bus } from "../bus/client.js";
+import type { Tickets } from "../tickets/client.js";
+/** The game's function: its server code, which Arcadible runs. */
+export interface Functions {
+    /**
+     * Its address, for a request of the game's own making: `${url}/score`,
+     * with a ticket for it (`tickets.get(url)`). Set by the time `ready`
+     * settles; `null` for a game with no function, or where no page says,
+     * such as standing alone, and `undefined` before.
+     */
+    readonly url: string | null | undefined;
+    /**
+     * A request to the game's function, as `fetch` makes one: `path` from
+     * its root, such as `"/score"`, and `init` as `fetch` takes it. It
+     * carries a ticket, which says the game, the build, and the player, so
+     * the function knows who's asking; the page keeps the ticket while it's
+     * good, and gets another when it isn't. Resolves with the function's
+     * `Response`, whatever its status. Rejects with `invalid` (a path that
+     * isn't one), `unavailable` (no function here, or no ticket right now),
+     * or `busy` (too many tickets), and as `fetch` does when the network
+     * fails.
+     */
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+}
+export type FunctionsClient = {
+    functions: Functions;
+    settle(): void;
+};
+export type FunctionsOptions = {
+    fetch: (url: string, init: RequestInit) => Promise<Response>;
+    ready: () => Promise<unknown>;
+    tickets: Tickets;
+};
+export declare function createFunctionsClient(bus: Bus, options: FunctionsOptions): FunctionsClient;

package/dist/runner/client.js

@@ -0,0 +1,45 @@
+// The game's side of `functions`: `arcadible.functions`, the game's
+// function (its runner, inside Arcadible), the server code Arcadible runs
+// for it. `url` is where it is, fixed for the run: `undefined` before
+// `ready`, and `null` where no page says (standing alone, an older page, or
+// a game with no function). `fetch` calls it, with the ticket that proves
+// who's asking.
+import { ArcadibleError, Codes } from "../bus/protocol.js";
+import { fact } from "../facts.js";
+import { Names, runnerOf } from "./rules.js";
+// [function]
+export function createFunctionsClient(bus, options) {
+    const where = fact(bus, Names.State, {
+        fixed: true,
+        parse(data) {
+            const runner = runnerOf(data);
+            return runner ? Object.freeze({ url: runner.url }) : null;
+        },
+    });
+    const functions = {
+        get url() {
+            const value = where.value;
+            return value ? value.url : value;
+        },
+        async fetch(path, init = {}) {
+            if (typeof path !== "string" || !path.startsWith("/")) {
+                throw new ArcadibleError(Codes.Invalid, 'functions.fetch takes a path from the function\'s root, such as "/score".');
+            }
+            await options.ready();
+            const url = where.value?.url;
+            if (!url) {
+                throw new ArcadibleError(Codes.Unavailable, "This game has no function here.");
+            }
+            const ticket = await options.tickets.get(url);
+            const headers = new Headers(init.headers);
+            headers.set("Authorization", `Bearer ${ticket}`);
+            return options.fetch(`${url}${path}`, { ...init, headers });
+        },
+    };
+    return {
+        functions,
+        settle() {
+            where.settle();
+        },
+    };
+}

package/dist/runner/rules.d.ts

@@ -0,0 +1,12 @@
+export declare const Names: {
+    readonly State: "runner.state";
+};
+export type RunnerState = {
+    url: string;
+};
+/**
+ * The runner as the game keeps it: its address, a web address with no
+ * trailing slash, so `${url}/score` reads as it's written. Null for
+ * anything else.
+ */
+export declare function runnerOf(value: unknown): RunnerState | null;

package/dist/runner/rules.js

@@ -0,0 +1,36 @@
+// `runner` on the bus, shared by both ends: where the game's runner is (its
+// function, as a game knows it), fixed for the run.
+// [import]
+import { isObject } from "../bus/protocol.js";
+// [declare]
+export const Names = {
+    // the runner, `{ url }`: an event, sent once, as the module opens.
+    State: "runner.state",
+};
+// The longest address kept.
+const MAX_URL = 2048;
+// [function]
+/**
+ * The runner as the game keeps it: its address, a web address with no
+ * trailing slash, so `${url}/score` reads as it's written. Null for
+ * anything else.
+ */
+export function runnerOf(value) {
+    if (!isObject(value))
+        return null;
+    const url = value["url"];
+    if (typeof url !== "string" || url.length > MAX_URL)
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+        return null;
+    if (parsed.search !== "" || parsed.hash !== "")
+        return null;
+    return { url: `${parsed.origin}${parsed.pathname.replace(/\/+$/u, "")}` };
+}

package/dist/runner/server.d.ts

@@ -0,0 +1,3 @@
+import type { Module } from "../bus/server.js";
+import { type RunnerState } from "./rules.js";
+export declare function runnerServer(runner: RunnerState): () => Module;

package/dist/runner/server.js

@@ -0,0 +1,20 @@
+// The page's side of `runner`: where the game's runner is, sent once as the
+// game connects. It never changes during the run.
+// [import]
+import { log } from "../bus/protocol.js";
+import { Names, runnerOf } from "./rules.js";
+// [function]
+export function runnerServer(runner) {
+    const state = runnerOf(runner);
+    if (!state) {
+        log("error", `the runner's address isn't one: ${JSON.stringify(runner)}.`);
+    }
+    return () => ({
+        handlers: {},
+        // first on each channel, so the game has it by `ready`.
+        async open(send) {
+            if (state)
+                send(Names.State, state);
+        },
+    });
+}

package/dist/tickets/client.d.ts

@@ -0,0 +1,20 @@
+import type { Bus } from "../bus/client.js";
+/** Tickets for the game's own servers. */
+export interface Tickets {
+    /**
+     * A ticket for one of the game's servers: proof, signed by Arcadible, of
+     * the game, the build, and the player (no one, for a guest), good for a
+     * few minutes. Takes the server's address, any URL of it, which
+     * the game declared in `arcadible.toml` (`[client] server_origins`). Send it
+     * once, as the game connects: an `Authorization` header, or a WebSocket's
+     * first message, never in a URL. Call it each time one is needed; the
+     * page keeps it while it's good. Rejects with `invalid` (not an address,
+     * or not one of the game's servers), `busy` (too many), or `unavailable`
+     * (offline, or off Arcadible; worth trying again).
+     */
+    get(server: string): Promise<string>;
+}
+export type TicketsClient = {
+    tickets: Tickets;
+};
+export declare function createTicketsClient(bus: Bus): TicketsClient;