@crowdedkingdoms/crowdyjs 18.10.0 → 18.12.0-dev.1

package/dist/kit/modules/territory.d.ts

@@ -0,0 +1,92 @@
+import { HubState } from '../mirror.js';
+import type { KitRuntime } from '../runtime.js';
+export interface TerritoryPoint {
+    id: string;
+    owner: string | null;
+    /** The faction pressing a capture, and how far it is, 0 to 1. */
+    capturing: string | null;
+    progress: number;
+    /** Members on the point at the last scan, by faction. */
+    present: Record<string, number>;
+}
+/** What the `territory` topic carries. */
+export interface TerritoryView {
+    phase: 'open' | 'won';
+    points: TerritoryPoint[];
+    scores: Record<string, number>;
+    /** Members by faction. */
+    members: Record<string, number>;
+    winner: string | null;
+}
+export interface ZoneContender {
+    player: number;
+    hp: number;
+    /** Outside the circle at the last scan. */
+    outside: boolean;
+    /** 1 for the winner; set as each player is eliminated. */
+    place: number | null;
+}
+/** What the `zone` topic carries. */
+export interface ZoneView {
+    phase: 'lobby' | 'running' | 'finished';
+    /** The circle's centre, in chunks. */
+    center: [number, number];
+    radius: number;
+    /** The phase under way, and the radius it shrinks to. */
+    stage: number | null;
+    next_radius: number | null;
+    players: ZoneContender[];
+    alive: number;
+    winner: number | null;
+}
+/** Control points and shrinking circles (the `territory` starter, types `territory` and `zone`). */
+export declare class TerritoryKit {
+    private readonly runtime;
+    private readonly territoryType;
+    private readonly zoneType;
+    private readonly maps;
+    private readonly zones;
+    constructor(runtime: KitRuntime, territoryType?: string, zoneType?: string);
+    /** The war on map `key`. */
+    map(key: string): TerritoryMap;
+    /** The circle of match `key`. */
+    zone(key: string): ZoneMatch;
+}
+/**
+ * One war over a map's control points: a faction captures a point by having more members standing
+ * on it than any other (the hub reads where players are; a client never says it is on a point),
+ * a capture decays when nobody presses it, each point held pays its faction, and the first to the
+ * winning score wins. `view.onEvent` hears `captured`, `income` and `won`.
+ */
+export declare class TerritoryMap {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    readonly view: HubState<TerritoryView>;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    watch(): Promise<TerritoryView>;
+    unwatch(): Promise<void>;
+    /** Joins a faction, once: a player keeps theirs. @throws {KitError} `conflict`, `bad_request`, `full`. */
+    join(faction: string): Promise<boolean>;
+    /** A new war. Developers only. */
+    reset(): Promise<boolean>;
+}
+/**
+ * One match's circle: it holds, then shrinks, phase by phase, and wears down every player outside
+ * it (the hub reads where players are) until one is left. `view.onEvent` hears `warning`,
+ * `shrinking`, `settled`, `final`, `eliminated` and `won`.
+ */
+export declare class ZoneMatch {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    readonly view: HubState<ZoneView>;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    watch(): Promise<ZoneView>;
+    unwatch(): Promise<void>;
+    /** @throws {KitError} `started`, `full`. */
+    join(): Promise<boolean>;
+    /** The first to join, or a developer. @throws {KitError} `forbidden`, `not_ready`, `started`. */
+    start(): Promise<boolean>;
+}
+//# sourceMappingURL=territory.d.ts.map

package/dist/kit/modules/territory.d.ts.map

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

package/dist/kit/modules/territory.js

@@ -0,0 +1,84 @@
+import { HubState } from '../mirror.js';
+/** Control points and shrinking circles (the `territory` starter, types `territory` and `zone`). */
+export class TerritoryKit {
+    constructor(runtime, territoryType = 'territory', zoneType = 'zone') {
+        this.runtime = runtime;
+        this.territoryType = territoryType;
+        this.zoneType = zoneType;
+        this.maps = new Map();
+        this.zones = new Map();
+    }
+    /** The war on map `key`. */
+    map(key) {
+        let m = this.maps.get(key);
+        if (!m) {
+            m = new TerritoryMap(this.runtime, this.territoryType, key);
+            this.maps.set(key, m);
+        }
+        return m;
+    }
+    /** The circle of match `key`. */
+    zone(key) {
+        let z = this.zones.get(key);
+        if (!z) {
+            z = new ZoneMatch(this.runtime, this.zoneType, key);
+            this.zones.set(key, z);
+        }
+        return z;
+    }
+}
+/**
+ * One war over a map's control points: a faction captures a point by having more members standing
+ * on it than any other (the hub reads where players are; a client never says it is on a point),
+ * a capture decays when nobody presses it, each point held pays its faction, and the first to the
+ * winning score wins. `view.onEvent` hears `captured`, `income` and `won`.
+ */
+export class TerritoryMap {
+    constructor(runtime, nodeType, key) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.key = key;
+        this.view = new HubState(runtime, nodeType, key, 'territory');
+    }
+    watch() {
+        return this.view.start();
+    }
+    unwatch() {
+        return this.view.stop();
+    }
+    /** Joins a faction, once: a player keeps theirs. @throws {KitError} `conflict`, `bad_request`, `full`. */
+    join(faction) {
+        return this.runtime.call(this.nodeType, this.key, 'join', { faction }, { action: true });
+    }
+    /** A new war. Developers only. */
+    reset() {
+        return this.runtime.call(this.nodeType, this.key, 'reset', null, { action: true });
+    }
+}
+/**
+ * One match's circle: it holds, then shrinks, phase by phase, and wears down every player outside
+ * it (the hub reads where players are) until one is left. `view.onEvent` hears `warning`,
+ * `shrinking`, `settled`, `final`, `eliminated` and `won`.
+ */
+export class ZoneMatch {
+    constructor(runtime, nodeType, key) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.key = key;
+        this.view = new HubState(runtime, nodeType, key, 'zone');
+    }
+    watch() {
+        return this.view.start();
+    }
+    unwatch() {
+        return this.view.stop();
+    }
+    /** @throws {KitError} `started`, `full`. */
+    join() {
+        return this.runtime.call(this.nodeType, this.key, 'join', null, { action: true });
+    }
+    /** The first to join, or a developer. @throws {KitError} `forbidden`, `not_ready`, `started`. */
+    start() {
+        return this.runtime.call(this.nodeType, this.key, 'start', null, { action: true });
+    }
+}

package/dist/kit/modules/world.d.ts

@@ -0,0 +1,69 @@
+import { CollectionMirror, HubState } from '../mirror.js';
+import type { KitRuntime } from '../runtime.js';
+/** What the `world` topic carries: the world's conditions now. */
+export interface WorldConditions {
+    /** 0 at midnight, 0.5 at noon. */
+    time_of_day: number;
+    night: boolean;
+    /** `clear`, `rain`, `storm` or `fog` in the starter. */
+    weather: string;
+    /** The active liveops events' modifiers; where events overlap they multiply. */
+    modifiers: Record<string, number>;
+}
+/** A resource node, as `state` lists it. */
+export interface WorldResourceNode {
+    id: number;
+    amount: number;
+    /** When it grows back (Unix ms), while it is empty. */
+    regrow_at: number | null;
+}
+/** A liveops event: between `start_ms` and `end_ms` its modifiers apply. */
+export interface WorldLiveopsEvent {
+    name: string;
+    start_ms: number;
+    end_ms: number;
+    modifiers?: Record<string, number>;
+}
+/** What the world hub's `state` answers. */
+export interface WorldView {
+    conditions: WorldConditions;
+    /** Game time since the world began, advanced only while it runs. */
+    clock_ms: number;
+    nodes: WorldResourceNode[];
+    events: WorldLiveopsEvent[];
+    /** Players in the app. */
+    online: number;
+}
+/** Where the world hub is: the root hub, `world` with an empty key, in the starter pack. */
+export interface WorldKitOptions {
+    nodeType?: string;
+    key?: string;
+}
+/**
+ * The root world hub (the `world-tick` starter): its clock, weather and liveops modifiers as a
+ * mirrored {@link conditions} topic, its resource nodes as a mirrored {@link nodes} collection,
+ * harvesting, and for developers the liveops schedule. The root hub takes 50 calls a second for
+ * the whole app, so read it from the mirrors (`conditions.start()`), not by polling `state`.
+ */
+export declare class WorldKit {
+    private readonly runtime;
+    /** The `world` topic: conditions now. `start()` it to keep it current. */
+    readonly conditions: HubState<WorldConditions>;
+    /** The `nodes` topic: each resource node's `amount` and `regrow_at`, by node id. */
+    readonly nodes: CollectionMirror;
+    private readonly nodeType;
+    private readonly key;
+    constructor(runtime: KitRuntime, options?: WorldKitOptions);
+    /** Everything the world shows: conditions, clock, nodes, events, players online. */
+    state(): Promise<WorldView>;
+    /**
+     * Takes one from resource node `node`; resolves with what it holds now.
+     * @throws {KitError} `cooldown`, `empty` (it grows back), `not_found`.
+     */
+    harvest(node: number): Promise<number>;
+    /** Schedules (or replaces) a liveops event. Developers only (a developer kit). */
+    schedule(event: WorldLiveopsEvent): Promise<boolean>;
+    /** Cancels a liveops event; resolves with whether there was one. Developers only. */
+    cancel(name: string): Promise<boolean>;
+}
+//# sourceMappingURL=world.d.ts.map

package/dist/kit/modules/world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../../src/kit/modules/world.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,eAAe,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,4FAA4F;AAC5F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,qBAAa,QAAQ;IASjB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAC/C,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAGV,OAAO,EAAE,UAAU,EACpC,OAAO,GAAE,eAAoB;IAQ/B,oFAAoF;IACpF,KAAK,IAAI,OAAO,CAAC,SAAS,CAAC;IAI3B;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAItC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpD,qFAAqF;IACrF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGvC"}

package/dist/kit/modules/world.js

@@ -0,0 +1,35 @@
+import { CollectionMirror, HubState } from '../mirror.js';
+/**
+ * The root world hub (the `world-tick` starter): its clock, weather and liveops modifiers as a
+ * mirrored {@link conditions} topic, its resource nodes as a mirrored {@link nodes} collection,
+ * harvesting, and for developers the liveops schedule. The root hub takes 50 calls a second for
+ * the whole app, so read it from the mirrors (`conditions.start()`), not by polling `state`.
+ */
+export class WorldKit {
+    constructor(runtime, options = {}) {
+        this.runtime = runtime;
+        this.nodeType = options.nodeType ?? 'world';
+        this.key = options.key ?? '';
+        this.conditions = new HubState(runtime, this.nodeType, this.key, 'world');
+        this.nodes = new CollectionMirror(runtime, this.nodeType, this.key, 'nodes');
+    }
+    /** Everything the world shows: conditions, clock, nodes, events, players online. */
+    state() {
+        return this.runtime.call(this.nodeType, this.key, 'state');
+    }
+    /**
+     * Takes one from resource node `node`; resolves with what it holds now.
+     * @throws {KitError} `cooldown`, `empty` (it grows back), `not_found`.
+     */
+    harvest(node) {
+        return this.runtime.call(this.nodeType, this.key, 'harvest', { node }, { action: true });
+    }
+    /** Schedules (or replaces) a liveops event. Developers only (a developer kit). */
+    schedule(event) {
+        return this.runtime.call(this.nodeType, this.key, 'schedule', event, { action: true });
+    }
+    /** Cancels a liveops event; resolves with whether there was one. Developers only. */
+    cancel(name) {
+        return this.runtime.call(this.nodeType, this.key, 'cancel', { name }, { action: true });
+    }
+}

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;
+}