@crowdedkingdoms/crowdyjs 18.10.0 → 18.12.0-dev.1

package/dist/kit/realtime.d.ts

@@ -0,0 +1,72 @@
+/**
+ * What kit hubs show players near them through the realtime tier (UDP), decoded for World
+ * Stores: server-driven actors (mobs, NPCs, pets, a ball) and server events.
+ *
+ * A server-driven actor's state is {@link KitActorState} as MessagePack (`ckx_sdk::kit::wire`
+ * `ActorState`). A server event is an `eventType` from the registry in `wire.ts` with a JSON
+ * body; `ServerEventNotification.state` is that body, base64.
+ */
+import { type StateCodec } from '../stores/codec.js';
+/** A server-driven actor as a kit hub shows it. */
+export interface KitActorState {
+    /** What it is: `mob`, `npc`, `pet`, `ball`, `ghost`, or a game's own word. */
+    kind: string;
+    /** Its id within the hub that shows it. */
+    id: number;
+    /** Where it is, in chunks. */
+    x: number;
+    y: number;
+    z: number;
+    hp: number | null;
+    max_hp?: number;
+    mode?: string;
+    /** The player it belongs to (a pet, a summon). */
+    owner?: number;
+    yaw?: number;
+    name?: string;
+}
+/** Whether a decoded value is a kit actor's state. */
+export declare function isKitActorState(value: unknown): value is KitActorState;
+/** A kit actor's state from its MessagePack bytes, or null when they are not one. */
+export declare function decodeKitActorState(bytes: Uint8Array): KitActorState | null;
+/**
+ * A {@link StateCodec} for the actors kit hubs show, for `createWorldSession`'s `actors`
+ * config. A state that is not a kit actor's decodes to null (a player's, say).
+ */
+export declare const kitActorCodec: StateCodec<KitActorState | null>;
+/** A player's actor in a world with kit hubs, with the game's own state. */
+export interface KitPlayerActor<P> {
+    kind: 'player';
+    player: P;
+}
+/** A remote actor in a world with kit hubs: a player's, or a server-driven one. */
+export type KitWorldActor<P> = KitPlayerActor<P> | KitActorState;
+/** Whether a remote actor is a player's (rather than one a hub shows). */
+export declare function isKitPlayerActor<P>(actor: KitWorldActor<P>): actor is KitPlayerActor<P>;
+/**
+ * One codec for a world where players and kit hubs both show actors: a kit actor's state
+ * decodes as itself, anything else through `playerCodec` as `{ kind: 'player', player }`.
+ * A game's own player state must not be a MessagePack map with `kind`, `id`, `x` and `z`.
+ */
+export declare function withKitActors<P>(playerCodec: StateCodec<P>): StateCodec<KitWorldActor<P>>;
+/**
+ * Lane predicates for `createWorldSession`'s `actors.lanes` with {@link withKitActors}:
+ * `players`, `mobs`, `npcs`, `pets`, and `others` for any other kind a hub shows.
+ */
+export declare function kitActorLanes<P>(): Record<'players' | 'mobs' | 'npcs' | 'pets' | 'others', (a: KitWorldActor<P>) => boolean>;
+/** The event types of the kit's registry, each with the JSON codec its body takes. */
+export declare const KIT_EVENT_TYPES: readonly number[];
+/** Codecs for World Stores' `EventRouter`, one per kit event type: the bodies are JSON. */
+export declare function kitEventCodecs(): Map<number, StateCodec<Record<string, unknown>>>;
+/**
+ * A server event a kit hub sent, from its notification (`eventType` and the base64 `state`),
+ * or null when the body is not JSON.
+ */
+export declare function parseKitServerEvent(notification: {
+    eventType: number;
+    state: string;
+}): {
+    eventType: number;
+    body: Record<string, unknown>;
+} | null;
+//# sourceMappingURL=realtime.d.ts.map

package/dist/kit/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../src/kit/realtime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAkBhE,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,sDAAsD;AACtD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAItE;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,GAAG,IAAI,CAQ3E;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,UAAU,CAAC,aAAa,GAAG,IAAI,CAG1D,CAAC;AAEF,4EAA4E;AAC5E,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,CAAC,CAAC;CACX;AAED,mFAAmF;AACnF,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC;AAEjE,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,cAAc,CAAC,CAAC,CAAC,CAEvF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAQzF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,KAAK,MAAM,CAAC,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAS5H;AAED,sFAAsF;AACtF,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAc5C,CAAC;AAEF,2FAA2F;AAC3F,wBAAgB,cAAc,IAAI,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAGjF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,CAS9D"}

package/dist/kit/realtime.js

@@ -0,0 +1,108 @@
+/**
+ * What kit hubs show players near them through the realtime tier (UDP), decoded for World
+ * Stores: server-driven actors (mobs, NPCs, pets, a ball) and server events.
+ *
+ * A server-driven actor's state is {@link KitActorState} as MessagePack (`ckx_sdk::kit::wire`
+ * `ActorState`). A server event is an `eventType` from the registry in `wire.ts` with a JSON
+ * body; `ServerEventNotification.state` is that body, base64.
+ */
+import { decode, encode } from '@msgpack/msgpack';
+import { jsonCodec } from '../stores/codec.js';
+import { decodeBase64, encodeBase64 } from '../utils.js';
+import { EVENT_ABILITY, EVENT_CONTACT_DAMAGE, EVENT_CONTROL_POINT, EVENT_EMOTE, EVENT_ENCOUNTER, EVENT_MOVEMENT_VIOLATION, EVENT_POSSESSION, EVENT_PROPOSAL, EVENT_RACE_TIMING, EVENT_SCORE, EVENT_TURN, EVENT_WEATHER, EVENT_ZONE_CHANGE, } from './wire.js';
+/** Whether a decoded value is a kit actor's state. */
+export function isKitActorState(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const v = value;
+    return typeof v.kind === 'string' && typeof v.id === 'number' && typeof v.x === 'number' && typeof v.z === 'number';
+}
+/** A kit actor's state from its MessagePack bytes, or null when they are not one. */
+export function decodeKitActorState(bytes) {
+    try {
+        const v = decode(bytes);
+        if (!isKitActorState(v))
+            return null;
+        return { ...v, y: typeof v.y === 'number' ? v.y : 0, hp: typeof v.hp === 'number' ? v.hp : null };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A {@link StateCodec} for the actors kit hubs show, for `createWorldSession`'s `actors`
+ * config. A state that is not a kit actor's decodes to null (a player's, say).
+ */
+export const kitActorCodec = {
+    encode: (state) => encodeBase64(state ? encode(state) : new Uint8Array()),
+    decode: (data) => (data ? decodeKitActorState(decodeBase64(data)) : null),
+};
+/** Whether a remote actor is a player's (rather than one a hub shows). */
+export function isKitPlayerActor(actor) {
+    return actor.kind === 'player' && 'player' in actor;
+}
+/**
+ * One codec for a world where players and kit hubs both show actors: a kit actor's state
+ * decodes as itself, anything else through `playerCodec` as `{ kind: 'player', player }`.
+ * A game's own player state must not be a MessagePack map with `kind`, `id`, `x` and `z`.
+ */
+export function withKitActors(playerCodec) {
+    return {
+        encode: (actor) => (isKitPlayerActor(actor) ? playerCodec.encode(actor.player) : kitActorCodec.encode(actor)),
+        decode: (data) => {
+            const kit = data ? decodeKitActorState(decodeBase64(data)) : null;
+            return kit ?? { kind: 'player', player: playerCodec.decode(data) };
+        },
+    };
+}
+/**
+ * Lane predicates for `createWorldSession`'s `actors.lanes` with {@link withKitActors}:
+ * `players`, `mobs`, `npcs`, `pets`, and `others` for any other kind a hub shows.
+ */
+export function kitActorLanes() {
+    const known = new Set(['player', 'mob', 'npc', 'pet']);
+    return {
+        players: (a) => a.kind === 'player',
+        mobs: (a) => a.kind === 'mob',
+        npcs: (a) => a.kind === 'npc',
+        pets: (a) => a.kind === 'pet',
+        others: (a) => !known.has(a.kind),
+    };
+}
+/** The event types of the kit's registry, each with the JSON codec its body takes. */
+export const KIT_EVENT_TYPES = [
+    EVENT_CONTACT_DAMAGE,
+    EVENT_WEATHER,
+    EVENT_TURN,
+    EVENT_SCORE,
+    EVENT_PROPOSAL,
+    EVENT_ABILITY,
+    EVENT_MOVEMENT_VIOLATION,
+    EVENT_CONTROL_POINT,
+    EVENT_RACE_TIMING,
+    EVENT_ZONE_CHANGE,
+    EVENT_ENCOUNTER,
+    EVENT_POSSESSION,
+    EVENT_EMOTE,
+];
+/** Codecs for World Stores' `EventRouter`, one per kit event type: the bodies are JSON. */
+export function kitEventCodecs() {
+    const codec = jsonCodec();
+    return new Map(KIT_EVENT_TYPES.map((t) => [t, codec]));
+}
+/**
+ * A server event a kit hub sent, from its notification (`eventType` and the base64 `state`),
+ * or null when the body is not JSON.
+ */
+export function parseKitServerEvent(notification) {
+    try {
+        const text = new TextDecoder().decode(decodeBase64(notification.state));
+        const body = text ? JSON.parse(text) : {};
+        if (!body || typeof body !== 'object' || Array.isArray(body))
+            return null;
+        return { eventType: notification.eventType, body: body };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/kit/runtime.d.ts

@@ -0,0 +1,90 @@
+import { type ExecAPI, type ExecConnectOptions, type ExecConnection, type ExecPushHandler } from '../domains/exec.js';
+/** Subscriptions one connection holds at most (the gateway refuses the next). */
+export declare const KIT_SUBSCRIPTIONS_MAX = 256;
+/** How a {@link KitRuntime} reaches the app's hubs. */
+export interface KitRuntimeOptions {
+    /** Use this connection rather than opening one. The kit does not close it. */
+    connection?: ExecConnection;
+    /** How the kit opens its connection: affinity (`nodeType`, `key`), timeouts, a WebSocket. */
+    connect?: ExecConnectOptions;
+    /**
+     * Connect as one of the app's developers (`exec.connectAsDeveloper`, the org's
+     * `manage_compute`, an identity session rather than an app token): what admin endpoints
+     * (`configure`, `schedule`, ...) need.
+     */
+    developer?: boolean;
+    /**
+     * Calls, subscriptions and unsubscriptions the kit sends in one window at most. The gateway
+     * takes 120 per 10 s from a player and refuses the rest `Busy`; the default, 100, keeps the
+     * kit under it with room for the game's own calls.
+     */
+    callBudget?: number;
+    /** The budget's window, in milliseconds. Default 10 000. */
+    budgetWindowMs?: number;
+    /**
+     * Times a call is sent again when it did not run (`Busy`, `RateLimited`), or, when it
+     * carries an action id, after an unknown outcome (`DeadlineExceeded`, `Unavailable`,
+     * `Moved`). Default 2.
+     */
+    retries?: number;
+    /** The player's id, to match `changed` messages; asked of `users.me` when absent. */
+    playerId?: string | number;
+}
+/** Per call: the action id, and the reply timeout. */
+export interface KitCallOptions {
+    /**
+     * Send an `action_id` so a resend is answered once: `true` for a fresh one, or the id to
+     * use (for a deliberate retry of an earlier attempt).
+     */
+    action?: boolean | string;
+    /** How long to wait for the reply, in milliseconds (the connection's default otherwise). */
+    timeoutMs?: number;
+}
+/**
+ * The kit's way to the app's hubs: one {@link ExecConnection} shared by every kit module,
+ * opened when first needed. It paces what it sends to a budget below the gateway's limit,
+ * sends a call again when that is safe (it did not run, or it carries an action id the hub
+ * answers once), counts subscriptions under the gateway's cap, and turns a hub's coded
+ * refusal into a {@link KitError}.
+ */
+export declare class KitRuntime {
+    readonly appId: string;
+    private readonly exec;
+    private readonly options;
+    private readonly whoAmI?;
+    private conn;
+    private connecting;
+    private ended;
+    private readonly budget;
+    private readonly retries;
+    private readonly subs;
+    private readonly reconnectListeners;
+    private readonly endedListeners;
+    private me;
+    constructor(appId: string, exec: ExecAPI | undefined, options?: KitRuntimeOptions, whoAmI?: (() => Promise<string | null>) | undefined);
+    /** The connection, opened on first use. */
+    connection(): Promise<ExecConnection>;
+    private open;
+    /** The player's id, from the options or `users.me`; null when neither knows it. */
+    playerId(): Promise<string | null>;
+    /**
+     * Calls a hub's endpoint, `args` as MessagePack, and returns the decoded reply.
+     * @throws {KitError} for a hub's coded refusal; {@link CrowdyExecError} for the platform's.
+     */
+    call<T = unknown>(nodeType: string, key: string, method: string, args?: unknown, options?: KitCallOptions): Promise<T>;
+    /**
+     * Receives what a hub publishes on `topic`. Returns the function that stops this handler
+     * (and the subscription with the last one).
+     * @throws {KitError} `limit` past {@link KIT_SUBSCRIPTIONS_MAX} subscriptions.
+     */
+    subscribe<T = unknown>(nodeType: string, key: string, topic: string, onPush: ExecPushHandler<T>): Promise<() => Promise<void>>;
+    /** How many distinct topics the kit subscribes to. */
+    get subscriptions(): number;
+    /** Called with the new host after the connection reconnects; kit mirrors resync then. */
+    onReconnect(listener: (host: string) => void): () => void;
+    /** Called once when the player's access ended (close code 4403); nothing reconnects. */
+    onAccessEnded(listener: (reason: string) => void): () => void;
+    /** Closes the connection the kit opened (not one it was given). */
+    close(): void;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/kit/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/kit/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAG5B,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,6FAA6F;IAC7F,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA8CD;;;;;;GAMG;AACH,qBAAa,UAAU;IAYnB,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAd1B,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,UAAU,CAAwC;IAC1D,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqC;IACxE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuC;IACtE,OAAO,CAAC,EAAE,CAAuC;gBAGtC,KAAK,EAAE,MAAM,EACL,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,OAAO,GAAE,iBAAsB,EAC/B,MAAM,CAAC,GAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,aAAA;IAMxD,2CAA2C;IACrC,UAAU,IAAI,OAAO,CAAC,cAAc,CAAC;YAY7B,IAAI;IAmBlB,mFAAmF;IAC7E,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAQxC;;;OAGG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC;IA2Bb;;;;OAIG;IACG,SAAS,CAAC,CAAC,GAAG,OAAO,EACzB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IA2B/B,sDAAsD;IACtD,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,yFAAyF;IACzF,WAAW,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAKzD,wFAAwF;IACxF,aAAa,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAK7D,mEAAmE;IACnE,KAAK,IAAI,IAAI;CAMd"}

package/dist/kit/runtime.js

@@ -0,0 +1,194 @@
+import { CrowdyExecError, } from '../domains/exec.js';
+import { KitError, newActionId, withActionId } from './protocol.js';
+/** Subscriptions one connection holds at most (the gateway refuses the next). */
+export const KIT_SUBSCRIPTIONS_MAX = 256;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A token bucket: `capacity` tokens a window, refilled continuously. */
+class Budget {
+    constructor(capacity, windowMs) {
+        this.capacity = capacity;
+        this.windowMs = windowMs;
+        this.last = Date.now();
+        this.blockedUntil = 0;
+        this.tokens = capacity;
+    }
+    refill() {
+        const now = Date.now();
+        this.tokens = Math.min(this.capacity, this.tokens + ((now - this.last) * this.capacity) / this.windowMs);
+        this.last = now;
+    }
+    async take() {
+        for (;;) {
+            const wait = this.blockedUntil - Date.now();
+            if (wait > 0) {
+                await sleep(wait);
+                continue;
+            }
+            this.refill();
+            if (this.tokens >= 1) {
+                this.tokens -= 1;
+                return;
+            }
+            await sleep(Math.ceil(((1 - this.tokens) * this.windowMs) / this.capacity));
+        }
+    }
+    /** The gateway said to wait: nothing is sent until `ms` from now. */
+    hold(ms) {
+        this.blockedUntil = Math.max(this.blockedUntil, Date.now() + ms);
+        this.tokens = 0;
+    }
+}
+/**
+ * The kit's way to the app's hubs: one {@link ExecConnection} shared by every kit module,
+ * opened when first needed. It paces what it sends to a budget below the gateway's limit,
+ * sends a call again when that is safe (it did not run, or it carries an action id the hub
+ * answers once), counts subscriptions under the gateway's cap, and turns a hub's coded
+ * refusal into a {@link KitError}.
+ */
+export class KitRuntime {
+    constructor(appId, exec, options = {}, whoAmI) {
+        this.appId = appId;
+        this.exec = exec;
+        this.options = options;
+        this.whoAmI = whoAmI;
+        this.conn = null;
+        this.connecting = null;
+        this.ended = null;
+        this.subs = new Map();
+        this.reconnectListeners = new Set();
+        this.endedListeners = new Set();
+        this.me = null;
+        this.budget = new Budget(Math.max(1, options.callBudget ?? 100), Math.max(1, options.budgetWindowMs ?? 10000));
+        this.retries = Math.max(0, options.retries ?? 2);
+    }
+    /** The connection, opened on first use. */
+    async connection() {
+        if (this.ended !== null)
+            throw new CrowdyExecError('Denied', `access ended: ${this.ended}`);
+        if (this.conn)
+            return this.conn;
+        if (!this.connecting) {
+            this.connecting = this.open().catch((e) => {
+                this.connecting = null;
+                throw e;
+            });
+        }
+        return this.connecting;
+    }
+    async open() {
+        let c = this.options.connection;
+        if (!c) {
+            if (!this.exec)
+                throw new CrowdyExecError('Unavailable', 'the kit has no exec client to connect with');
+            c = this.options.developer
+                ? await this.exec.connectAsDeveloper(this.appId, this.options.connect)
+                : await this.exec.connect(this.appId, this.options.connect);
+        }
+        c.onReconnect((host) => {
+            for (const l of [...this.reconnectListeners])
+                l(host);
+        });
+        c.onAccessEnded((reason) => {
+            this.ended = reason;
+            for (const l of [...this.endedListeners])
+                l(reason);
+        });
+        this.conn = c;
+        return c;
+    }
+    /** The player's id, from the options or `users.me`; null when neither knows it. */
+    async playerId() {
+        if (this.options.playerId !== undefined)
+            return String(this.options.playerId);
+        if (!this.me) {
+            this.me = this.whoAmI ? this.whoAmI().catch(() => null) : Promise.resolve(null);
+        }
+        return this.me;
+    }
+    /**
+     * Calls a hub's endpoint, `args` as MessagePack, and returns the decoded reply.
+     * @throws {KitError} for a hub's coded refusal; {@link CrowdyExecError} for the platform's.
+     */
+    async call(nodeType, key, method, args, options = {}) {
+        const actionId = options.action === true ? newActionId() : typeof options.action === 'string' ? options.action : undefined;
+        const sent = actionId ? withActionId(args, actionId) : args;
+        for (let attempt = 0;; attempt++) {
+            await this.budget.take();
+            const conn = await this.connection();
+            try {
+                return await conn.call(nodeType, key, method, sent, { timeoutMs: options.timeoutMs });
+            }
+            catch (e) {
+                const err = KitError.from(e);
+                if (attempt < this.retries && err instanceof CrowdyExecError && !(err instanceof KitError)) {
+                    if (err.status === 'Busy' && err.rateLimited) {
+                        this.budget.hold(err.retryAfterMs ?? 1000);
+                        continue;
+                    }
+                    const didNotRun = err.status === 'Busy' || err.status === 'RateLimited';
+                    const unknown = err.status === 'DeadlineExceeded' || err.status === 'Unavailable' || err.status === 'Moved';
+                    if (didNotRun || (actionId && unknown)) {
+                        await sleep(Math.min(2000, 200 * 2 ** attempt) * (0.5 + Math.random() / 2));
+                        continue;
+                    }
+                }
+                throw err;
+            }
+        }
+    }
+    /**
+     * Receives what a hub publishes on `topic`. Returns the function that stops this handler
+     * (and the subscription with the last one).
+     * @throws {KitError} `limit` past {@link KIT_SUBSCRIPTIONS_MAX} subscriptions.
+     */
+    async subscribe(nodeType, key, topic, onPush) {
+        const k = `${nodeType}\u0000${key}\u0000${topic}`;
+        const held = this.subs.get(k) ?? 0;
+        if (held === 0) {
+            if (this.subs.size >= KIT_SUBSCRIPTIONS_MAX) {
+                throw new KitError('limit', `a connection holds at most ${KIT_SUBSCRIPTIONS_MAX} subscriptions`);
+            }
+            await this.budget.take();
+        }
+        const conn = await this.connection();
+        const stop = await conn.subscribe(nodeType, key, topic, onPush);
+        this.subs.set(k, (this.subs.get(k) ?? 0) + 1);
+        let stopped = false;
+        return async () => {
+            if (stopped)
+                return;
+            stopped = true;
+            const left = (this.subs.get(k) ?? 1) - 1;
+            if (left > 0) {
+                this.subs.set(k, left);
+            }
+            else {
+                this.subs.delete(k);
+                await this.budget.take();
+            }
+            await stop();
+        };
+    }
+    /** How many distinct topics the kit subscribes to. */
+    get subscriptions() {
+        return this.subs.size;
+    }
+    /** Called with the new host after the connection reconnects; kit mirrors resync then. */
+    onReconnect(listener) {
+        this.reconnectListeners.add(listener);
+        return () => this.reconnectListeners.delete(listener);
+    }
+    /** Called once when the player's access ended (close code 4403); nothing reconnects. */
+    onAccessEnded(listener) {
+        this.endedListeners.add(listener);
+        return () => this.endedListeners.delete(listener);
+    }
+    /** Closes the connection the kit opened (not one it was given). */
+    close() {
+        if (this.conn && !this.options.connection)
+            this.conn.close();
+        this.conn = null;
+        this.connecting = null;
+        this.subs.clear();
+    }
+}

package/dist/kit/store.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The kit's observable value: `get` the current value, `subscribe` to hear each new one. The
+ * shape React's `useSyncExternalStore(store.subscribe, store.get)` takes, and that any other
+ * framework wraps in a line.
+ */
+export interface KitStore<T> {
+    get(): T;
+    /** Calls `listener` with every new value; returns the function that stops it. */
+    subscribe(listener: (value: T) => void): () => void;
+}
+/** A {@link KitStore} its owner sets. */
+export declare class WritableKitStore<T> implements KitStore<T> {
+    private value;
+    private readonly listeners;
+    constructor(initial: T);
+    get(): T;
+    subscribe(listener: (value: T) => void): () => void;
+    set(value: T): void;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/kit/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/kit/store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,GAAG,IAAI,CAAC,CAAC;IACT,iFAAiF;IACjF,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACrD;AAED,yCAAyC;AACzC,qBAAa,gBAAgB,CAAC,CAAC,CAAE,YAAW,QAAQ,CAAC,CAAC,CAAC;IACrD,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;gBAE/C,OAAO,EAAE,CAAC;IAItB,GAAG,IAAI,CAAC;IAIR,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAKnD,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;CAUpB"}

package/dist/kit/store.js

@@ -0,0 +1,25 @@
+/** A {@link KitStore} its owner sets. */
+export class WritableKitStore {
+    constructor(initial) {
+        this.listeners = new Set();
+        this.value = initial;
+    }
+    get() {
+        return this.value;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    set(value) {
+        this.value = value;
+        for (const l of [...this.listeners]) {
+            try {
+                l(value);
+            }
+            catch {
+                /* a listener's exception is its own */
+            }
+        }
+    }
+}

package/dist/kit/topology.d.ts

@@ -0,0 +1,69 @@
+import type { ExecAPI, ExecBuild, ExecManifestType, ExecNodeTypeInput, ExecStarterPack } from '../domains/exec.js';
+/** The crates one build takes at most (the game API's `execBuild`). */
+export declare const KIT_BUILD_MAX_CRATES = 16;
+/** The node API scopes a manifest may declare (ck-exec `bounds::NODE_API_SCOPES`). */
+export declare const KIT_NODE_API_SCOPES: readonly string[];
+/** A manifest as the kit composes it: the root hub and each node type. */
+export interface KitManifest {
+    root: string;
+    types: Record<string, ExecNodeTypeInput | ExecManifestType>;
+}
+/** What {@link KitTopology.plan} composes: a manifest, and the starter crates it builds. */
+export interface KitTopologyPlan {
+    root: string;
+    types: Record<string, ExecNodeTypeInput>;
+    /** The starter crates the types name, each built once. */
+    crates: string[];
+}
+/** Changes to a planned type: a seed, limits, replicas, scopes, `client`, ... */
+export interface KitPlanOptions {
+    overrides?: Record<string, Partial<ExecNodeTypeInput>>;
+}
+/** How {@link KitTopology.deploy} waits for its build. */
+export interface KitDeployOptions {
+    /** Default 10 minutes. */
+    timeoutMs?: number;
+    /** Called with the build once it is done. */
+    onBuild?: (build: ExecBuild) => void;
+}
+/**
+ * What the execution manager would refuse in `manifest`, in its words (ck-exec
+ * `Manifest::problems`, less the digests, which the build fills in): the root is a hub
+ * without a parent, every other type has a defined parent, `calls` name defined types or `*`,
+ * replicas are for spokes, scopes are known. Empty when it deploys.
+ */
+export declare function kitManifestProblems(manifest: KitManifest): string[];
+/**
+ * An app's tree of kit hubs, composed from the starter packs (`exec.starters`): pick the node
+ * types a game uses, and {@link plan} adds the hubs they hang under and the ones they call,
+ * checks the tree, and {@link deploy} builds the crates on the platform and deploys them.
+ * For the app's developers (the org's `manage_compute`), from an identity session.
+ */
+export declare class KitTopology {
+    private readonly appId;
+    private readonly exec;
+    private packed;
+    constructor(appId: string, exec: ExecAPI | undefined);
+    private api;
+    /** The starter packs this tier's toolchain carries (fetched once). */
+    pack(): Promise<ExecStarterPack>;
+    /** The node types the packs offer. */
+    types(): Promise<string[]>;
+    /**
+     * A manifest with the types in `select`, the types they hang under up to the root, and the
+     * types they call (by name, not `*`), from the packs' manifest.
+     * @throws {CrowdyError} for a type the packs do not have, a tree the manager would refuse,
+     *   or more crates than one build takes.
+     */
+    plan(select: readonly string[], options?: KitPlanOptions): Promise<KitTopologyPlan>;
+    /**
+     * Builds the plan's crates on the platform, waits, and deploys the manifest with the build.
+     * Resolves with the deployed version and the build id.
+     * @throws {CrowdyError} when the build fails (its log in the message).
+     */
+    deploy(plan: KitTopologyPlan, options?: KitDeployOptions): Promise<{
+        version: number;
+        buildId: string;
+    }>;
+}
+//# sourceMappingURL=topology.d.ts.map

package/dist/kit/topology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../../src/kit/topology.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EAET,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAE5B,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAUhD,CAAC;AAEF,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,CAAC,CAAC;CAC7D;AAED,4FAA4F;AAC5F,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACzC,0DAA0D;IAC1D,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;CACxD;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACtC;AAID;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,EAAE,CA0BnE;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IAIpB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJvB,OAAO,CAAC,MAAM,CAAyC;gBAGpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,OAAO,GAAG,SAAS;IAG5C,OAAO,CAAC,GAAG;IAKX,sEAAsE;IACtE,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC;IAYhC,sCAAsC;IAChC,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIhC;;;;;OAKG;IACG,IAAI,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IA8B7F;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAiBnH"}