@crowdedkingdoms/crowdyjs 18.10.0 → 18.11.0-dev.1

package/dist/kit/protocol.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The game kit protocol: what kit hubs (ck-exec's starter packs, built on `ckx_sdk::kit`)
+ * send the kit's clients, read without I/O.
+ *
+ * A kit hub's topics carry **kit messages**: MessagePack maps with the hub's data and four
+ * reserved fields beside it: `v` (the protocol version, {@link KIT_PROTOCOL}), `epoch` (the
+ * publishing instance's epoch, which changes whenever it is placed again: a move, a restart or
+ * a crash), `seq` (one more than the topic's last message) and `kind`:
+ *
+ * - `snapshot`: the topic's whole public state; it replaces what the client holds.
+ * - `delta`: one change to a collection (`id`, then `type_name` and `props`, or `removed`),
+ *   applied in `seq` order. A gap in `seq`, or another `epoch`, means a resync.
+ * - `changed`: something private changed for the players in `who` (`what` names it); they read
+ *   it back with a call the hub answers for its caller alone. Topics have no access control,
+ *   so kit hubs never publish anything private.
+ * - `event`: something that happened, with nothing to keep.
+ *
+ * Every kit hub answers `snapshot { topic }` with a `snapshot` message whose `seq` is the
+ * topic's last. A call that changes something may carry an `action_id`; the hub answers a call
+ * sent again with the first answer. A refusal's message is `kit:<code>: <text>`.
+ */
+import { CrowdyExecError } from '../domains/exec.js';
+/** The protocol version kit messages carry in `v`. */
+export declare const KIT_PROTOCOL = 1;
+/** The method every kit hub answers with a topic's snapshot. */
+export declare const KIT_SNAPSHOT_METHOD = "snapshot";
+/** The longest `action_id` a hub takes, in bytes. */
+export declare const KIT_ACTION_ID_MAX = 64;
+export type KitMessageKind = 'snapshot' | 'delta' | 'changed' | 'event';
+/** The reserved fields of a kit message. */
+export interface KitHeader {
+    v: number;
+    epoch: number;
+    seq: number;
+    kind: KitMessageKind;
+}
+/** The body of a `changed` message. */
+export interface KitChanged {
+    /** The players who should read again (player ids). */
+    who: number[];
+    /** What changed for them, as the hub's endpoints name it. */
+    what: string;
+}
+/** One member of a collection, as a `delta` or a collection snapshot carries it. */
+export interface KitContainer {
+    id: number;
+    type_name: string;
+    /** Its public properties, all of them: a delta replaces what the client held. */
+    props: Record<string, unknown>;
+}
+/** A collection delta's body. */
+export interface KitDelta {
+    id: number;
+    type_name?: string;
+    props?: Record<string, unknown>;
+    removed?: boolean;
+}
+/** Whether `value` is a kit message: a map with the four reserved fields. */
+export declare function isKitMessage(value: unknown): value is KitHeader & Record<string, unknown>;
+/**
+ * A kit message split into its header and its body (every other field), or null when
+ * `value` is not one.
+ */
+export declare function splitKitMessage<T = Record<string, unknown>>(value: unknown): {
+    header: KitHeader;
+    body: T;
+} | null;
+/** The code and text of a kit refusal's message, or null for any other message. */
+export declare function parseKitRefusal(message: string): {
+    code: string;
+    text: string;
+} | null;
+/** The refusal codes kit hubs share; a hub may add its own (lowercase, digits, `_`). */
+export declare const KIT_CODES: {
+    readonly BAD_REQUEST: "bad_request";
+    readonly NOT_FOUND: "not_found";
+    readonly FORBIDDEN: "forbidden";
+    readonly CONFLICT: "conflict";
+    readonly FULL: "full";
+    readonly LIMIT: "limit";
+    readonly COOLDOWN: "cooldown";
+    readonly NOT_YOUR_TURN: "not_your_turn";
+    readonly NOT_MEMBER: "not_member";
+    readonly STARTED: "started";
+    readonly FINISHED: "finished";
+    readonly NOT_READY: "not_ready";
+    readonly RESERVED: "reserved";
+    readonly EMPTY: "empty";
+    readonly OUT_OF_REACH: "out_of_reach";
+    readonly EXPIRED: "expired";
+    readonly INSUFFICIENT: "insufficient";
+    readonly ALREADY_DONE: "already_done";
+};
+/**
+ * A kit hub refused the call (`AppError` with a `kit:<code>:` message): `code` is what to
+ * branch on, `text` what to show. It is a {@link CrowdyExecError} with status `AppError`, so
+ * code that handles exec errors handles it.
+ */
+export declare class KitError extends CrowdyExecError {
+    readonly code: string;
+    readonly text: string;
+    constructor(code: string, text: string, cause?: unknown);
+    /** `error` as a {@link KitError} when it is a coded refusal; otherwise `error` itself. */
+    static from(error: unknown): unknown;
+}
+/** The refusal code of `error`, when it is a kit refusal. */
+export declare function kitErrorCode(error: unknown): string | null;
+/** A fresh `action_id`: unique per attempt, the same for every resend of that attempt. */
+export declare function newActionId(): string;
+/**
+ * `args` with `action_id` beside them: a plain object gains the field, `undefined` or `null`
+ * becomes `{ action_id }`. Anything else (an array, a number) cannot carry one and is
+ * returned as it is.
+ */
+export declare function withActionId(args: unknown, actionId: string): unknown;
+/**
+ * The centre chunk of the shard holding chunk `(x, z)`: shards are `size` by `size` chunks,
+ * keyed by their centre. The same function as `ckx_sdk::kit::shard`, so a client finds the
+ * hub for where it stands without asking. `x` and `z` are chunk coordinates (integers).
+ */
+export declare function shardCentre(x: number, z: number, size: number): [number, number];
+/** The key of the shard holding chunk `(x, z)`: `"<x>,<z>"` of its centre. */
+export declare function shardKey(x: number, z: number, size: number): string;
+/** The centre chunk a shard key names, or null when it is not `"<x>,<z>"`. */
+export declare function parseShardKey(key: string): [number, number] | null;
+/** The keys of the shards within `radius` shards of the one holding `(x, z)`, its own first. */
+export declare function shardKeysAround(x: number, z: number, size: number, radius: number): string[];
+//# sourceMappingURL=protocol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/kit/protocol.ts"],"names":[],"mappings":"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"}

package/dist/kit/protocol.js

@@ -0,0 +1,171 @@
+/**
+ * The game kit protocol: what kit hubs (ck-exec's starter packs, built on `ckx_sdk::kit`)
+ * send the kit's clients, read without I/O.
+ *
+ * A kit hub's topics carry **kit messages**: MessagePack maps with the hub's data and four
+ * reserved fields beside it: `v` (the protocol version, {@link KIT_PROTOCOL}), `epoch` (the
+ * publishing instance's epoch, which changes whenever it is placed again: a move, a restart or
+ * a crash), `seq` (one more than the topic's last message) and `kind`:
+ *
+ * - `snapshot`: the topic's whole public state; it replaces what the client holds.
+ * - `delta`: one change to a collection (`id`, then `type_name` and `props`, or `removed`),
+ *   applied in `seq` order. A gap in `seq`, or another `epoch`, means a resync.
+ * - `changed`: something private changed for the players in `who` (`what` names it); they read
+ *   it back with a call the hub answers for its caller alone. Topics have no access control,
+ *   so kit hubs never publish anything private.
+ * - `event`: something that happened, with nothing to keep.
+ *
+ * Every kit hub answers `snapshot { topic }` with a `snapshot` message whose `seq` is the
+ * topic's last. A call that changes something may carry an `action_id`; the hub answers a call
+ * sent again with the first answer. A refusal's message is `kit:<code>: <text>`.
+ */
+import { CrowdyExecError } from '../domains/exec.js';
+/** The protocol version kit messages carry in `v`. */
+export const KIT_PROTOCOL = 1;
+/** The method every kit hub answers with a topic's snapshot. */
+export const KIT_SNAPSHOT_METHOD = 'snapshot';
+/** The longest `action_id` a hub takes, in bytes. */
+export const KIT_ACTION_ID_MAX = 64;
+const KINDS = new Set(['snapshot', 'delta', 'changed', 'event']);
+const RESERVED = ['v', 'epoch', 'seq', 'kind'];
+/** Whether `value` is a kit message: a map with the four reserved fields. */
+export function isKitMessage(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const v = value;
+    return (typeof v.v === 'number' &&
+        typeof v.epoch === 'number' &&
+        typeof v.seq === 'number' &&
+        typeof v.kind === 'string' &&
+        KINDS.has(v.kind));
+}
+/**
+ * A kit message split into its header and its body (every other field), or null when
+ * `value` is not one.
+ */
+export function splitKitMessage(value) {
+    if (!isKitMessage(value))
+        return null;
+    const body = { ...value };
+    for (const k of RESERVED)
+        delete body[k];
+    return {
+        header: { v: value.v, epoch: value.epoch, seq: value.seq, kind: value.kind },
+        body: body,
+    };
+}
+// ---- refusals ----
+const CODED = /^kit:([a-z0-9_]{1,64}): ([\s\S]*)$/;
+/** The code and text of a kit refusal's message, or null for any other message. */
+export function parseKitRefusal(message) {
+    const m = CODED.exec(message);
+    return m ? { code: m[1], text: m[2] } : null;
+}
+/** The refusal codes kit hubs share; a hub may add its own (lowercase, digits, `_`). */
+export const KIT_CODES = {
+    BAD_REQUEST: 'bad_request',
+    NOT_FOUND: 'not_found',
+    FORBIDDEN: 'forbidden',
+    CONFLICT: 'conflict',
+    FULL: 'full',
+    LIMIT: 'limit',
+    COOLDOWN: 'cooldown',
+    NOT_YOUR_TURN: 'not_your_turn',
+    NOT_MEMBER: 'not_member',
+    STARTED: 'started',
+    FINISHED: 'finished',
+    NOT_READY: 'not_ready',
+    RESERVED: 'reserved',
+    EMPTY: 'empty',
+    OUT_OF_REACH: 'out_of_reach',
+    EXPIRED: 'expired',
+    INSUFFICIENT: 'insufficient',
+    ALREADY_DONE: 'already_done',
+};
+/**
+ * A kit hub refused the call (`AppError` with a `kit:<code>:` message): `code` is what to
+ * branch on, `text` what to show. It is a {@link CrowdyExecError} with status `AppError`, so
+ * code that handles exec errors handles it.
+ */
+export class KitError extends CrowdyExecError {
+    constructor(code, text, cause) {
+        super('AppError', `kit:${code}: ${text}`, cause);
+        this.name = 'KitError';
+        this.code = code;
+        this.text = text;
+    }
+    /** `error` as a {@link KitError} when it is a coded refusal; otherwise `error` itself. */
+    static from(error) {
+        if (error instanceof KitError)
+            return error;
+        if (error instanceof CrowdyExecError && error.status === 'AppError') {
+            // A CrowdyExecError's message leads with its status.
+            const prefix = `${error.status}: `;
+            const raw = error.message.startsWith(prefix) ? error.message.slice(prefix.length) : error.message;
+            const coded = parseKitRefusal(raw);
+            if (coded)
+                return new KitError(coded.code, coded.text, error);
+        }
+        return error;
+    }
+}
+/** The refusal code of `error`, when it is a kit refusal. */
+export function kitErrorCode(error) {
+    const e = KitError.from(error);
+    return e instanceof KitError ? e.code : null;
+}
+// ---- action ids ----
+/** A fresh `action_id`: unique per attempt, the same for every resend of that attempt. */
+export function newActionId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return `a-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+ * `args` with `action_id` beside them: a plain object gains the field, `undefined` or `null`
+ * becomes `{ action_id }`. Anything else (an array, a number) cannot carry one and is
+ * returned as it is.
+ */
+export function withActionId(args, actionId) {
+    if (args === undefined || args === null)
+        return { action_id: actionId };
+    if (typeof args === 'object' && !Array.isArray(args) && !(args instanceof Uint8Array)) {
+        return { ...args, action_id: actionId };
+    }
+    return args;
+}
+// ---- shard keys ----
+/**
+ * The centre chunk of the shard holding chunk `(x, z)`: shards are `size` by `size` chunks,
+ * keyed by their centre. The same function as `ckx_sdk::kit::shard`, so a client finds the
+ * hub for where it stands without asking. `x` and `z` are chunk coordinates (integers).
+ */
+export function shardCentre(x, z, size) {
+    const s = Math.max(1, Math.trunc(size));
+    const half = Math.floor(s / 2);
+    return [Math.floor(Math.trunc(x) / s) * s + half, Math.floor(Math.trunc(z) / s) * s + half];
+}
+/** The key of the shard holding chunk `(x, z)`: `"<x>,<z>"` of its centre. */
+export function shardKey(x, z, size) {
+    const [cx, cz] = shardCentre(x, z, size);
+    return `${cx},${cz}`;
+}
+/** The centre chunk a shard key names, or null when it is not `"<x>,<z>"`. */
+export function parseShardKey(key) {
+    const m = /^\s*(-?\d+)\s*,\s*(-?\d+)\s*$/.exec(key);
+    return m ? [Number(m[1]), Number(m[2])] : null;
+}
+/** The keys of the shards within `radius` shards of the one holding `(x, z)`, its own first. */
+export function shardKeysAround(x, z, size, radius) {
+    const s = Math.max(1, Math.trunc(size));
+    const [cx, cz] = shardCentre(x, z, s);
+    const keys = [`${cx},${cz}`];
+    for (let dz = -radius; dz <= radius; dz++) {
+        for (let dx = -radius; dx <= radius; dx++) {
+            if (dx !== 0 || dz !== 0)
+                keys.push(`${cx + dx * s},${cz + dz * s}`);
+        }
+    }
+    return keys;
+}

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"}