@crowdedkingdoms/crowdyjs 18.11.0-dev.1 → 18.13.0-dev.1

package/dist/kit/modules/player.js

@@ -0,0 +1,258 @@
+import { CrowdyError } from '../../errors.js';
+import { HubState, PrivateState } from '../mirror.js';
+import { WritableKitStore } from '../store.js';
+const TOPIC = 'player';
+/** A store fed by another once it exists. */
+class Relay extends WritableKitStore {
+    constructor() {
+        super(undefined);
+    }
+    attach(source) {
+        source.subscribe((v) => this.set(v));
+        if (source.get() !== undefined)
+            this.set(source.get());
+    }
+}
+/**
+ * The caller's own `player` hub (the `player` starter), keyed by their player id: what they own
+ * and what they have done. Its stores exist from the start and fill once {@link watch} has read
+ * them; only the player reads `inventory`, `wallet` and `progress`, and each is read again when
+ * the hub says it changed. The economy is not a ledger: see the Game Kit's economy page.
+ */
+export class PlayerKit {
+    constructor(runtime, nodeType = 'player', playerKey) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.playerKey = playerKey;
+        this.profile = new Relay();
+        this.inventory = new Relay();
+        this.wallet = new Relay();
+        this.progress = new Relay();
+        this.parts = null;
+        this.rulesRead = null;
+        this.events = new Set();
+    }
+    /** The hub's key: the player's id. */
+    async key() {
+        const key = this.playerKey ?? (await this.runtime.playerId());
+        if (key === null || key === undefined) {
+            throw new CrowdyError({ message: 'the kit does not know which player it is: pass playerId to client.kit()' });
+        }
+        return key;
+    }
+    ready() {
+        this.parts ?? (this.parts = (async () => {
+            const key = await this.key();
+            const read = (method) => () => this.runtime.call(this.nodeType, key, method);
+            const source = { nodeType: this.nodeType, key, topic: TOPIC };
+            const parts = {
+                key,
+                profile: new HubState(this.runtime, this.nodeType, key, TOPIC),
+                inventory: new PrivateState(this.runtime, { ...source, what: 'inventory', read: read('inventory') }),
+                wallet: new PrivateState(this.runtime, { ...source, what: 'wallet', read: read('wallet') }),
+                progress: new PrivateState(this.runtime, { ...source, what: 'progress', read: read('progress') }),
+            };
+            this.profile.attach(parts.profile);
+            this.inventory.attach(parts.inventory);
+            this.wallet.attach(parts.wallet);
+            this.progress.attach(parts.progress);
+            parts.profile.onEvent((body) => {
+                for (const l of [...this.events])
+                    l(body);
+            });
+            return parts;
+        })().catch((e) => {
+            this.parts = null;
+            throw e;
+        }));
+        return this.parts;
+    }
+    /** Mirrors the profile and reads what only the player reads (all of it, or the parts named). */
+    async watch(...which) {
+        const parts = await this.ready();
+        const all = which.length ? which : ['profile', 'inventory', 'wallet', 'progress'];
+        await Promise.all(all.map((w) => parts[w].start()));
+    }
+    async unwatch() {
+        if (!this.parts)
+            return;
+        const parts = await this.parts;
+        await Promise.all([parts.profile.stop(), parts.inventory.stop(), parts.wallet.stop(), parts.progress.stop()]);
+    }
+    /** Levels gained and achievements unlocked, as the `player` topic announces them. */
+    onEvent(listener) {
+        this.events.add(listener);
+        return () => this.events.delete(listener);
+    }
+    /** Calls the player's hub; a change carries an action id. */
+    async call(method, args, change = true) {
+        return this.runtime.call(this.nodeType, await this.key(), method, args ?? null, change ? { action: true } : {});
+    }
+    /** Everything the hub keeps for the player. */
+    me() {
+        return this.call('me', null, false);
+    }
+    /** The game's items, recipes, loot tables, quests and achievements (read once). */
+    rules() {
+        this.rulesRead ?? (this.rulesRead = this.call('rules', null, false).catch((e) => {
+            this.rulesRead = null;
+            throw e;
+        }));
+        return this.rulesRead;
+    }
+    /** Another player's public profile. */
+    profileOf(player) {
+        return this.runtime.call(this.nodeType, String(player), 'profile');
+    }
+}
+/** The player's items: stacks in slots, and mail for what did not fit. */
+export class InventoryKit {
+    constructor(player) {
+        this.player = player;
+    }
+    get items() {
+        return this.player.inventory;
+    }
+    async watch() {
+        await this.player.watch('inventory');
+        return this.player.inventory.get();
+    }
+    /** How many of `item` the player has, as last read. */
+    count(item) {
+        return (this.player.inventory.get()?.stacks ?? []).filter((s) => s.item === item).reduce((n, s) => n + s.count, 0);
+    }
+    /** @throws {KitError} `insufficient`. */
+    discard(item, count) {
+        return this.player.call('discard', { item, count });
+    }
+    /** Moves what fits from the mail into the inventory; resolves with what moved. */
+    takeMail() {
+        return this.player.call('take_mail');
+    }
+}
+/** The player's soft currencies. */
+export class WalletKit {
+    constructor(player) {
+        this.player = player;
+    }
+    get balances() {
+        return this.player.wallet;
+    }
+    async watch() {
+        await this.player.watch('wallet');
+        return this.player.wallet.get();
+    }
+    /** The balance of `currency`, as last read. */
+    balance(currency) {
+        return this.player.wallet.get()?.balances[currency] ?? 0;
+    }
+}
+/** Experience and levels, and the public profile. */
+export class ProgressionKit {
+    constructor(player) {
+        this.player = player;
+    }
+    get progress() {
+        return this.player.progress;
+    }
+    get profile() {
+        return this.player.profile;
+    }
+    async watch() {
+        await this.player.watch('profile', 'progress');
+        return this.player.progress.get();
+    }
+    /** Another player's public profile. */
+    profileOf(player) {
+        return this.player.profileOf(player);
+    }
+    /** Called with each level the player reaches. */
+    onLevel(listener) {
+        return this.player.onEvent((e) => e.type === 'level' && listener(e.level));
+    }
+}
+/** Achievements: counts of what the player did, unlocked once. */
+export class AchievementsKit {
+    constructor(player) {
+        this.player = player;
+    }
+    async watch() {
+        await this.player.watch('profile', 'progress');
+        return this.list();
+    }
+    /** The achievements with their counts, as last read (hidden ones once unlocked). */
+    list() {
+        return this.player.progress.get()?.achievements ?? [];
+    }
+    /** Called with each achievement the player unlocks. */
+    onUnlock(listener) {
+        return this.player.onEvent((e) => e.type === 'achievement' && listener(e.achievement));
+    }
+}
+/** Quests, first-session tutorials among them. */
+export class QuestsKit {
+    constructor(player) {
+        this.player = player;
+    }
+    async watch() {
+        await this.player.watch('progress');
+        return this.list();
+    }
+    list() {
+        return this.player.progress.get()?.quests ?? [];
+    }
+    /** @throws {KitError} `conflict` (taken, done, or another first), `forbidden` (level), `not_found`. */
+    accept(quest) {
+        return this.player.call('accept', { quest });
+    }
+    /** Claims a complete quest's reward. @throws {KitError} `not_ready`, `full`. */
+    claim(quest) {
+        return this.player.call('claim', { quest });
+    }
+    /**
+     * Reports one of the counters the game lets a client report (a tutorial step).
+     * @throws {KitError} `forbidden` for a counter the game's hubs count.
+     */
+    step(counter) {
+        return this.player.call('step', { counter });
+    }
+}
+/** Crafting from the game's recipes. */
+export class CraftingKit {
+    constructor(player) {
+        this.player = player;
+    }
+    async recipes() {
+        return (await this.player.rules()).recipes;
+    }
+    /** Crafts `times` (once by default). @throws {KitError} `insufficient`, `full`, `forbidden` (level), `not_found`. */
+    craft(recipe, times) {
+        return this.player.call('craft', times === undefined ? { recipe } : { recipe, times });
+    }
+}
+/** Loot tables with pity. */
+export class LootKit {
+    constructor(player) {
+        this.player = player;
+    }
+    async tables() {
+        return (await this.player.rules()).loot;
+    }
+    /** Pays the table's cost and rolls once. @throws {KitError} `insufficient`, `full`, `not_found`. */
+    open(table) {
+        return this.player.call('open', { table });
+    }
+}
+/** Idle production that catches up on the time away. */
+export class ProductionKit {
+    constructor(player) {
+        this.player = player;
+    }
+    async view() {
+        return (await this.player.me()).production;
+    }
+    /** Moves what the producers made into the inventory, as far as it fits. */
+    collect() {
+        return this.player.call('collect');
+    }
+}

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

@@ -0,0 +1,131 @@
+import { HubState } from '../mirror.js';
+import type { KitRuntime } from '../runtime.js';
+export interface RaceGate {
+    x: number;
+    z: number;
+    radius: number;
+}
+export interface RaceRacer {
+    player: number;
+    x: number;
+    z: number;
+    lap: number;
+    /** The gate the racer must pass next. */
+    next_gate: number;
+    best_lap_ms: number | null;
+    place: number | null;
+    total_ms: number | null;
+    did_not_finish: boolean;
+}
+/** What the `race` topic carries. */
+export interface RaceView {
+    phase: 'lobby' | 'countdown' | 'racing' | 'finished';
+    course_id: string;
+    gates: RaceGate[];
+    laps: number;
+    /** When the race starts (Unix ms), once counting down. */
+    go_at: number | null;
+    /** When the rest's time is up, once the winner is in. */
+    closes_at: number | null;
+    racers: RaceRacer[];
+}
+/** The winner's run: `[ms from the start, x, y, z, yaw]` frames to race against. */
+export interface RaceGhost {
+    player: number;
+    total_ms: number;
+    frames: Array<[number, number, number, number, number]>;
+}
+export interface BallPlayer {
+    player: number;
+    team: 'red' | 'blue';
+    x: number;
+    z: number;
+}
+export interface BallState {
+    x: number;
+    z: number;
+    vx: number;
+    vz: number;
+    holder: number | null;
+    held_since: number;
+    last_touch: number | null;
+}
+/** What the `ball` topic carries. */
+export interface BallView {
+    phase: 'lobby' | 'playing' | 'finished';
+    width: number;
+    depth: number;
+    goal_width: number;
+    ball: BallState;
+    players: BallPlayer[];
+    /** Red's, then blue's. */
+    score: [number, number];
+    ends_at: number | null;
+    winner: 'red' | 'blue' | null;
+}
+/** Races and ball games (the `racing` starter, types `race` and `ball`). */
+export declare class RacingKit {
+    private readonly runtime;
+    private readonly raceType;
+    private readonly ballType;
+    private readonly races;
+    private readonly matches;
+    constructor(runtime: KitRuntime, raceType?: string, ballType?: string);
+    /** The race with key `key`. */
+    race(key: string): Race;
+    /** The ball game with key `key`. */
+    ball(key: string): BallMatch;
+}
+/**
+ * One race: a course of gates passed in order, a countdown, laps and splits, places in finishing
+ * order, and a ghost of the winner's run. A client reports where its racer is ({@link pos}, a few
+ * times a second) and the hub times the positions its movement warden kept. `view.onEvent` hears
+ * `go`, `timing` (with its `stage`: `started`, `checkpoint`, `lap`, `finished`), `violation` and
+ * `finished`.
+ */
+export declare class Race {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    readonly view: HubState<RaceView>;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    watch(): Promise<RaceView>;
+    unwatch(): Promise<void>;
+    /** @throws {KitError} `started`, `full`. */
+    join(): Promise<boolean>;
+    leave(): Promise<boolean>;
+    /** Starts the countdown (the first to join, or a developer). @throws {KitError} `forbidden`, `started`. */
+    start(): Promise<boolean>;
+    /** Reports where the racer is; resolves with the position the hub kept. */
+    pos(x: number, z: number): Promise<[number, number]>;
+    /** The winner's run, once there is one. */
+    ghost(): Promise<RaceGhost | null>;
+}
+/**
+ * One ball game: two teams, a ball the hub moves (passes, shots, friction, the side walls),
+ * possession (claim a loose ball near it, or take it from an opponent whose protection is over), a
+ * goal in each end wall. `view.onEvent` hears `claimed`, `passed`, `shot`, `goal`, `violation` and
+ * `finished`.
+ */
+export declare class BallMatch {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    readonly view: HubState<BallView>;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    watch(): Promise<BallView>;
+    unwatch(): Promise<void>;
+    /** @throws {KitError} `bad_request` (red or blue), `full`, `started`. */
+    join(team: 'red' | 'blue'): Promise<boolean>;
+    /** @throws {KitError} `forbidden`, `not_ready` (each team needs a player), `started`. */
+    start(): Promise<boolean>;
+    /** Reports where the player is; resolves with the position the hub kept. */
+    pos(x: number, z: number): Promise<[number, number]>;
+    /** Claims the ball. @throws {KitError} `out_of_reach`, `cooldown` (too soon, or its holder's protection), `conflict` (a teammate has it). */
+    claim(): Promise<boolean>;
+    /** Passes to a teammate. @throws {KitError} `conflict` (not the holder), `bad_request` (not a teammate). */
+    pass(to: number | string): Promise<boolean>;
+    /** Shoots toward `(x, z)`. @throws {KitError} `conflict` (not the holder). */
+    shoot(x: number, z: number): Promise<boolean>;
+}
+//# sourceMappingURL=racing.d.ts.map

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

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

package/dist/kit/modules/racing.js

@@ -0,0 +1,113 @@
+import { HubState } from '../mirror.js';
+/** Races and ball games (the `racing` starter, types `race` and `ball`). */
+export class RacingKit {
+    constructor(runtime, raceType = 'race', ballType = 'ball') {
+        this.runtime = runtime;
+        this.raceType = raceType;
+        this.ballType = ballType;
+        this.races = new Map();
+        this.matches = new Map();
+    }
+    /** The race with key `key`. */
+    race(key) {
+        let r = this.races.get(key);
+        if (!r) {
+            r = new Race(this.runtime, this.raceType, key);
+            this.races.set(key, r);
+        }
+        return r;
+    }
+    /** The ball game with key `key`. */
+    ball(key) {
+        let m = this.matches.get(key);
+        if (!m) {
+            m = new BallMatch(this.runtime, this.ballType, key);
+            this.matches.set(key, m);
+        }
+        return m;
+    }
+}
+/**
+ * One race: a course of gates passed in order, a countdown, laps and splits, places in finishing
+ * order, and a ghost of the winner's run. A client reports where its racer is ({@link pos}, a few
+ * times a second) and the hub times the positions its movement warden kept. `view.onEvent` hears
+ * `go`, `timing` (with its `stage`: `started`, `checkpoint`, `lap`, `finished`), `violation` and
+ * `finished`.
+ */
+export class Race {
+    constructor(runtime, nodeType, key) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.key = key;
+        this.view = new HubState(runtime, nodeType, key, 'race');
+    }
+    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 });
+    }
+    leave() {
+        return this.runtime.call(this.nodeType, this.key, 'leave', null, { action: true });
+    }
+    /** Starts the countdown (the first to join, or a developer). @throws {KitError} `forbidden`, `started`. */
+    start() {
+        return this.runtime.call(this.nodeType, this.key, 'start', null, { action: true });
+    }
+    /** Reports where the racer is; resolves with the position the hub kept. */
+    pos(x, z) {
+        return this.runtime.call(this.nodeType, this.key, 'pos', { x, z });
+    }
+    /** The winner's run, once there is one. */
+    ghost() {
+        return this.runtime.call(this.nodeType, this.key, 'ghost');
+    }
+}
+/**
+ * One ball game: two teams, a ball the hub moves (passes, shots, friction, the side walls),
+ * possession (claim a loose ball near it, or take it from an opponent whose protection is over), a
+ * goal in each end wall. `view.onEvent` hears `claimed`, `passed`, `shot`, `goal`, `violation` and
+ * `finished`.
+ */
+export class BallMatch {
+    constructor(runtime, nodeType, key) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.key = key;
+        this.view = new HubState(runtime, nodeType, key, 'ball');
+    }
+    watch() {
+        return this.view.start();
+    }
+    unwatch() {
+        return this.view.stop();
+    }
+    /** @throws {KitError} `bad_request` (red or blue), `full`, `started`. */
+    join(team) {
+        return this.runtime.call(this.nodeType, this.key, 'join', { team }, { action: true });
+    }
+    /** @throws {KitError} `forbidden`, `not_ready` (each team needs a player), `started`. */
+    start() {
+        return this.runtime.call(this.nodeType, this.key, 'start', null, { action: true });
+    }
+    /** Reports where the player is; resolves with the position the hub kept. */
+    pos(x, z) {
+        return this.runtime.call(this.nodeType, this.key, 'pos', { x, z });
+    }
+    /** Claims the ball. @throws {KitError} `out_of_reach`, `cooldown` (too soon, or its holder's protection), `conflict` (a teammate has it). */
+    claim() {
+        return this.runtime.call(this.nodeType, this.key, 'claim', null, { action: true });
+    }
+    /** Passes to a teammate. @throws {KitError} `conflict` (not the holder), `bad_request` (not a teammate). */
+    pass(to) {
+        return this.runtime.call(this.nodeType, this.key, 'pass', { to: Number(to) }, { action: true });
+    }
+    /** Shoots toward `(x, z)`. @throws {KitError} `conflict` (not the holder). */
+    shoot(x, z) {
+        return this.runtime.call(this.nodeType, this.key, 'shoot', { x, z }, { action: true });
+    }
+}

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

@@ -0,0 +1,76 @@
+import { HubState, PrivateState } from '../mirror.js';
+import type { KitRuntime } from '../runtime.js';
+/** The last thing done at a table. */
+export interface CardPlayed {
+    player: number;
+    card: string | null;
+    /** `play`, `draw` or `pass`. */
+    action: string;
+}
+/** What the `table` topic carries: the public table, never a hand. */
+export interface CardTableView {
+    phase: 'lobby' | 'playing' | 'finished';
+    players: number[];
+    host: number | null;
+    /** Cards in each player's hand, by player id (the keys are the ids as text). */
+    hand_counts: Record<string, number>;
+    top: string | null;
+    /** The suit in play (an eight names one). */
+    suit: string | null;
+    draw_count: number;
+    turn: number | null;
+    turn_ends: number | null;
+    last: CardPlayed | null;
+    winner: number | null;
+    scores: Record<string, number>;
+}
+/** The caller's hand, as `hand` answers it. */
+export interface CardHand {
+    cards: string[];
+    /** The cards the rule lets them play now. */
+    playable: string[];
+    /** Whether they drew this turn (and may pass). */
+    drawn: boolean;
+}
+/** Card tables (the `deck` starter): {@link table} by key. */
+export declare class TablesKit {
+    private readonly runtime;
+    private readonly nodeType;
+    private readonly tables;
+    constructor(runtime: KitRuntime, nodeType?: string);
+    table(key: string): CardTable;
+}
+/**
+ * One table with true hidden information: the deck and every hand live in the hub, and a player
+ * reads only their own hand ({@link hand}, read again whenever the hub's `changed` message names
+ * them). The starter's game is crazy eights.
+ */
+export declare class CardTable {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    /** The `table` topic: the public table. */
+    readonly table: HubState<CardTableView>;
+    /** The caller's hand: never on the topic. */
+    readonly hand: PrivateState<CardHand>;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    /** Mirrors the table and the caller's hand. */
+    watch(): Promise<CardTableView>;
+    unwatch(): Promise<void>;
+    /** @throws {KitError} `started`, `full`. */
+    join(): Promise<boolean>;
+    leave(): Promise<boolean>;
+    /** Deals (the host, from two players). @throws {KitError} `forbidden`, `too_few_players`, `started`. */
+    start(): Promise<boolean>;
+    /**
+     * Plays a card from the caller's hand; an eight names `suit` (`S`, `H`, `D` or `C`).
+     * @throws {KitError} `not_your_turn`, `not_found` (not in the hand), `not_playable` (the rule),
+     *   `bad_request` (an eight without a suit).
+     */
+    play(card: string, suit?: string): Promise<boolean>;
+    /** Draws a card (once a turn). @throws {KitError} `not_your_turn`, `conflict`, `empty`. */
+    draw(): Promise<boolean>;
+    /** Passes, after drawing. @throws {KitError} `conflict` (draw first). */
+    pass(): Promise<boolean>;
+}
+//# sourceMappingURL=tables.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../src/kit/modules/tables.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;IACxC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,+CAA+C;AAC/C,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kDAAkD;IAClD,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,8DAA8D;AAC9D,qBAAa,SAAS;IAIlB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;gBAGpC,OAAO,EAAE,UAAU,EACnB,QAAQ,SAAS;IAGpC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS;CAQ9B;AAED;;;;GAIG;AACH,qBAAa,SAAS;IAOlB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM;IARtB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IACxC,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;gBAGnB,OAAO,EAAE,UAAU,EAC3B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM;IAYtB,+CAA+C;IACzC,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC;IAK/B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,4CAA4C;IAC5C,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAIxB,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAIzB,wGAAwG;IACxG,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAIzB;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKnD,2FAA2F;IAC3F,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAIxB,yEAAyE;IACzE,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;CAGzB"}

package/dist/kit/modules/tables.js

@@ -0,0 +1,73 @@
+import { HubState, PrivateState } from '../mirror.js';
+/** Card tables (the `deck` starter): {@link table} by key. */
+export class TablesKit {
+    constructor(runtime, nodeType = 'deck') {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.tables = new Map();
+    }
+    table(key) {
+        let t = this.tables.get(key);
+        if (!t) {
+            t = new CardTable(this.runtime, this.nodeType, key);
+            this.tables.set(key, t);
+        }
+        return t;
+    }
+}
+/**
+ * One table with true hidden information: the deck and every hand live in the hub, and a player
+ * reads only their own hand ({@link hand}, read again whenever the hub's `changed` message names
+ * them). The starter's game is crazy eights.
+ */
+export class CardTable {
+    constructor(runtime, nodeType, key) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.key = key;
+        this.table = new HubState(runtime, nodeType, key, 'table');
+        this.hand = new PrivateState(runtime, {
+            nodeType,
+            key,
+            topic: 'table',
+            what: 'hand',
+            read: () => runtime.call(nodeType, key, 'hand'),
+        });
+    }
+    /** Mirrors the table and the caller's hand. */
+    async watch() {
+        const [view] = await Promise.all([this.table.start(), this.hand.start()]);
+        return view;
+    }
+    async unwatch() {
+        await Promise.all([this.table.stop(), this.hand.stop()]);
+    }
+    /** @throws {KitError} `started`, `full`. */
+    join() {
+        return this.runtime.call(this.nodeType, this.key, 'join', null, { action: true });
+    }
+    leave() {
+        return this.runtime.call(this.nodeType, this.key, 'leave', null, { action: true });
+    }
+    /** Deals (the host, from two players). @throws {KitError} `forbidden`, `too_few_players`, `started`. */
+    start() {
+        return this.runtime.call(this.nodeType, this.key, 'start', null, { action: true });
+    }
+    /**
+     * Plays a card from the caller's hand; an eight names `suit` (`S`, `H`, `D` or `C`).
+     * @throws {KitError} `not_your_turn`, `not_found` (not in the hand), `not_playable` (the rule),
+     *   `bad_request` (an eight without a suit).
+     */
+    play(card, suit) {
+        const args = suit === undefined ? { card } : { card, suit };
+        return this.runtime.call(this.nodeType, this.key, 'play', args, { action: true });
+    }
+    /** Draws a card (once a turn). @throws {KitError} `not_your_turn`, `conflict`, `empty`. */
+    draw() {
+        return this.runtime.call(this.nodeType, this.key, 'draw', null, { action: true });
+    }
+    /** Passes, after drawing. @throws {KitError} `conflict` (draw first). */
+    pass() {
+        return this.runtime.call(this.nodeType, this.key, 'pass', null, { action: true });
+    }
+}