@hadoku/rooms-protocol 0.0.0-stage → 0.43.16

package/dist/resync.js

@@ -0,0 +1,110 @@
+/**
+ * Reconnect and resync — the CONTRACT, not the transport.
+ *
+ * A client that drops and returns has three problems, and they are separable:
+ * did it miss anything (sequence), is it even talking to the same room
+ * incarnation (epoch), and does the server still agree about who it is
+ * (identity). The rules for all three live here, pure and dependency-free, so
+ * both ends agree on them and either end can test them without a socket.
+ *
+ * **The implementations deliberately stay where they are.** Watchparty's socket
+ * lifecycle is in `apps/ui/src/lib/socket.ts` and is not extracted; a second
+ * consumer whose client is a cross-origin iframe relaying over `postMessage`
+ * has a different transport entirely. What both need to agree on is the RULES,
+ * which is this file.
+ *
+ * ## What watchparty actually stamps today — read this before binding
+ *
+ * `CoreRoomState.lastEventSeq` is incremented **only for playback control
+ * events** (`ws/control.ts`), and it reaches clients in the `snapshot` and
+ * `control_ack` payloads. Chat, presence, health and game envelopes carry no
+ * sequence at all. So `classifySeq` is a rule this package *guarantees*, not a
+ * behaviour watchparty currently exercises end to end — an app that wants gap
+ * detection stamps `SeqCursor` on its own envelopes and runs the classifier.
+ *
+ * That distinction was stated wrongly once (an earlier version of the
+ * extraction reply claimed "every envelope carries seq"), so it is spelled out
+ * here rather than left to be inferred.
+ */
+/**
+ * Classify an incoming event against the last one applied.
+ *
+ * `last === null` means nothing has been applied yet, which is 'ok' rather than
+ * a gap: a client joining mid-stream has missed everything by definition, and
+ * its snapshot — not a resync request — is what establishes the baseline.
+ *
+ * **Sequence numbers are NEVER compared across epochs.** A restarted server
+ * counting from 1 while the client holds 500 would otherwise read as a flood
+ * of duplicates and the client would sit there discarding live events forever.
+ * The epoch check therefore comes first, before any arithmetic.
+ */
+export function classifySeq(last, incoming) {
+    if (last === null)
+        return 'ok';
+    if (incoming.epoch !== last.epoch)
+        return 'epoch-change';
+    if (incoming.seq === last.seq + 1)
+        return 'ok';
+    if (incoming.seq <= last.seq)
+        return 'duplicate';
+    return 'gap';
+}
+/** How many events a gap skipped. 0 when the verdict is not 'gap'. */
+export function missedCount(last, incoming) {
+    if (last === null || incoming.epoch !== last.epoch)
+        return 0;
+    return Math.max(0, incoming.seq - last.seq - 1);
+}
+/**
+ * Does this verdict require the client to ask the server for state?
+ *
+ * A helper rather than a comparison at each call site, because the answer is
+ * NOT "anything that isn't ok": a duplicate must not trigger a resync. Under
+ * any retransmit, duplicates arrive in bursts, and resyncing on each one turns
+ * a harmless replay into a request storm against the server that is already
+ * struggling enough to be retransmitting.
+ */
+export function needsResync(verdict) {
+    return verdict === 'gap' || verdict === 'epoch-change';
+}
+/**
+ * Should the client re-assert its local identity to the server?
+ *
+ * On each snapshot a client compares its own name/avatar against the server's
+ * roster entry FOR ITSELF and emits an identity update only for the fields that
+ * actually disagree, so later snapshots are no-ops.
+ *
+ * **Read `serverEntry` from the ROSTER, not from the snapshot.** Watchparty's
+ * snapshot carries seven fields and has never included a roster; a caller that
+ * looked itself up there got `undefined` permanently, both guards collapsed to
+ * local state alone, and every client with a saved identity re-emitted on
+ * every snapshot — including the room-wide ones. That bug survived a long time
+ * because broken and correct agree on the FIRST snapshot after join and
+ * diverge only afterwards.
+ *
+ * `serverEntry === undefined` still means "assert": that is the genuine
+ * first-snapshot case, where the client cannot know the server's view.
+ *
+ * Known quirk, preserved deliberately: an empty server name does not trigger a
+ * name assert, because an empty string is not a default name under any sane
+ * `isDefaultName`. Widening that is a separate decision with a different blast
+ * radius.
+ *
+ * @param isDefaultName recognises an auto-assigned name; a local name that is
+ *                      still a default is not worth asserting.
+ * @returns the fields to emit, or null when nothing differs.
+ */
+export function resolveIdentityReassert(local, serverEntry, isDefaultName) {
+    const wantsName = !!local.name &&
+        !isDefaultName(local.name) &&
+        (!serverEntry || isDefaultName(serverEntry.name || ''));
+    const wantsAvatar = !!local.avatarId && (!serverEntry || serverEntry.avatarId !== local.avatarId);
+    if (!wantsName && !wantsAvatar)
+        return null;
+    const out = {};
+    if (wantsName)
+        out.name = local.name;
+    if (wantsAvatar)
+        out.avatarId = local.avatarId;
+    return out;
+}

package/dist/seats.d.ts

@@ -0,0 +1,269 @@
+import type { ParticipantId } from './participantId.js';
+/**
+ * Seating — who is in the game, in what ORDER, and who is merely watching.
+ *
+ * ## SeatId IS the ordering
+ *
+ * A `SeatId` is an index into `seats`, not a sort key. Seat order is
+ * load-bearing, not cosmetic: in bomberman it selects a spawn point, and in a
+ * draft the pack passes left, then right, then left again. So the table stores
+ * position directly rather than deriving it from anything that can be
+ * reordered.
+ *
+ * What it replaces in watchparty: `buildPlayerRoster` walked `room.clients`
+ * and handed out `playerId` in **Map insertion order of socket ids**. That map
+ * is keyed by socket id, so a player who reconnected was deleted and re-inserted
+ * at the END — silently moving them to the last slot and shifting everyone
+ * after them. Mid-session, one person's refresh reshuffled the table's spawn
+ * points.
+ *
+ * ## Sticky by default, RESERVED when the app asks
+ *
+ * Two different needs pull in opposite directions, and there are two mechanisms
+ * because one is not enough:
+ *
+ *   - **Sticky** (always on). On leave the seat is released but the
+ *     participant -> seat assignment is REMEMBERED, so a returning participant
+ *     reclaims their old place when it is still free instead of being appended.
+ *     A departed viewer never holds a slot others are waiting for.
+ *   - **Reserved** (opt-in, `reservationTtlMs`). The seat is additionally held
+ *     AGAINST OTHER PEOPLE for a bounded window, so a reconnect cannot lose it
+ *     to whoever happened to be waiting.
+ *
+ * Sticky alone is right for a watch party, where an empty slot should go to
+ * whoever wants it. It is not enough for a long game: on a bounded table a
+ * network blip, a suspended laptop or a backgrounded tab frees the seat with no
+ * overlap at all, and that is exactly when it gets taken.
+ *
+ * A reservation also survives the case nothing else can. When a server
+ * restarts, every socket drops at once — so any scheme based on "is a transport
+ * still attached" is empty for every seat simultaneously and cannot help. A
+ * reservation is data, so it can be persisted and restored with the table.
+ *
+ * Both need an identity that outlives the transport, which is why
+ * `ParticipantId` had to land first — with socket ids there is nothing to
+ * remember or reserve. See `participantId.ts`.
+ *
+ * ## A reservation blocks other HUMANS, not bots
+ *
+ * The seat of an absent player can be filled by a bot and reclaimed on their
+ * return — which is what a pod of eight wants when one person's train goes into
+ * a tunnel. `padWithBots` therefore ignores reservations and `seatParticipant`
+ * honours them, and a returning human evicts the bot sitting in their seat.
+ *
+ * ## Roles are DERIVED, never stored
+ *
+ * `roleOf` reads the table. A stored role could disagree with the seating —
+ * a "player" with no seat, or a seated "spectator" — and every consumer would
+ * then have to guess which half to trust. There is one source of truth.
+ *
+ * ## Plain arrays and records, deliberately — NOT Map/Set
+ *
+ * Every other collection on `RoomState` is a `Map` or a `Set`, which is the
+ * reason room state cannot be snapshotted or restored today: `JSON.stringify`
+ * renders them as `{}`. This table is plain JSON-safe data so that a pluggable
+ * snapshot/restore is a matter of writing it out, not of teaching a serializer
+ * about five container types. Keep it that way.
+ */
+/** Index into `SeatTable.seats`. Stable across a reconnect. */
+export type SeatId = number;
+/** Derived from seating — see this module's header. */
+export type SeatRole = 'player' | 'spectator';
+export type SeatOccupant = {
+    kind: 'human';
+    participantId: ParticipantId;
+} | {
+    kind: 'bot';
+    botId: string;
+};
+export interface Seat {
+    id: SeatId;
+    /** null = empty and claimable. */
+    occupant: SeatOccupant | null;
+}
+/** A seat held for one participant until `expiresAt` (epoch ms). */
+export interface SeatReservation {
+    participantId: ParticipantId;
+    expiresAt: number;
+}
+export interface SeatTable {
+    /**
+     * Maximum seats, or `null` for unbounded.
+     *
+     * `null` is watchparty's normal state: a room watching video has no slot
+     * limit and everyone present is a participant, so every joiner is seated in
+     * arrival order and there are no spectators. Bomberman sets a real capacity
+     * when a game is selected; a draft pod sets one at creation.
+     */
+    capacity: number | null;
+    /** Index === SeatId. Length grows to capacity (or with arrivals when unbounded). */
+    seats: Seat[];
+    /**
+     * participantId -> the seat they last held. Outlives their departure so a
+     * reconnect reclaims the same place. Never consulted when that seat is
+     * occupied by someone else.
+     */
+    remembered: Record<ParticipantId, SeatId>;
+    /**
+     * seatId -> who it is being held for, and until when. Keyed by seat because
+     * a seat has at most one reservation while a participant could otherwise
+     * appear to hold several.
+     *
+     * Expiry is LAZY — checked when the seat is considered, never swept by a
+     * timer. Timers do not compose (they stack into cascading delays) and they
+     * mask state bugs by silently fixing them on the next tick.
+     */
+    reservations: Record<SeatId, SeatReservation>;
+    /**
+     * How long `unseatParticipant(..., { hold: true })` holds a seat, in ms.
+     *
+     * **0 disables reservations entirely**, which is the default and is exactly
+     * the pre-reservation behaviour — so a host that wants sticky-only gets it by
+     * doing nothing. Per TABLE rather than a module constant because the right
+     * value is a product decision that genuinely differs: a watch party wants a
+     * departed viewer's slot back promptly, a 45-minute draft would rather hold a
+     * seat for minutes than break the pod for everyone else.
+     */
+    reservationTtlMs: number;
+}
+export interface SeatTableOptions {
+    /** See `SeatTable.reservationTtlMs`. 0 (the default) disables reservations. */
+    reservationTtlMs?: number;
+}
+export declare function createSeatTable(capacity?: number | null, opts?: SeatTableOptions): SeatTable;
+/** The seat this participant currently occupies, or null. */
+export declare function seatOf(table: SeatTable, participantId: ParticipantId): SeatId | null;
+/** Occupant of a seat, or null when empty or out of range. */
+export declare function occupantOf(table: SeatTable, id: SeatId): SeatOccupant | null;
+/**
+ * The live reservation on a seat, or null when there is none or it has expired.
+ *
+ * Expired entries are deleted as they are found — lazy expiry, so the table
+ * self-cleans through normal use without a timer.
+ */
+export declare function reservationFor(table: SeatTable, id: SeatId, now?: number): SeatReservation | null;
+/** The seat currently held for this participant, if any. */
+export declare function reservedSeatOf(table: SeatTable, participantId: ParticipantId, now?: number): SeatId | null;
+/** Drop a seat's reservation, whoever it is for. */
+export declare function clearReservation(table: SeatTable, id: SeatId): void;
+/**
+ * May this participant take this seat?
+ *
+ * False only when someone ELSE holds a live reservation on it. A participant is
+ * never blocked by their own reservation — that is the point of one.
+ */
+export declare function seatClaimableBy(table: SeatTable, id: SeatId, participantId: ParticipantId, now?: number): boolean;
+/**
+ * Seat a participant, preferring the seat they last held.
+ *
+ * Returns their SeatId, or null when the table is full of PEOPLE — in which
+ * case the caller treats them as a spectator. Idempotent: already-seated
+ * returns the seat they are in, so a duplicate join cannot take two.
+ *
+ * ## A human outranks a bot
+ *
+ * A bot holding a seat never turns a real player away — it is evicted and the
+ * human takes the seat. Without that, `padWithBots` filling the table locks
+ * every later arrival out permanently: padding clears and re-fills the same
+ * lowest free seat, so the seat a human needs is re-taken the instant it frees.
+ * Callers CAN avoid it by clamping the bot count to capacity-minus-humans (what
+ * `handleGameSetBots` does), but a table that depends on every caller getting
+ * that right will eventually meet one that doesn't.
+ *
+ * Eviction is a last resort, after a genuinely free seat and after growing the
+ * table — bots only move when there is no other way to seat a person. The one
+ * exception is the remembered seat: seat stability is the whole point, so
+ * reclaiming it displaces a bot rather than sending its owner elsewhere.
+ */
+export declare function seatParticipant(table: SeatTable, participantId: ParticipantId, now?: number): SeatId | null;
+export interface ReleaseOptions {
+    /**
+     * Also HOLD the seat against other people for `ttlMs`.
+     *
+     * A per-call flag rather than table policy because the same table wants both
+     * answers: a viewer saying "I'm leaving" should free the slot at once, while
+     * a player dropping off a pod should not cost the other seven their game.
+     * The caller knows which of those just happened; the table cannot.
+     *
+     * Defaults to true, which is a no-op unless the table has a
+     * `reservationTtlMs` — so a host that never opted in sees no change.
+     */
+    hold?: boolean;
+    /** Override the table's `reservationTtlMs` for this release. */
+    ttlMs?: number;
+    now?: number;
+}
+/**
+ * Release a participant's seat, remembering it for their return.
+ *
+ * Returns the vacated SeatId, or null if they held none.
+ */
+export declare function unseatParticipant(table: SeatTable, participantId: ParticipantId, opts?: ReleaseOptions): SeatId | null;
+/** Forget a participant entirely, so they get a fresh seat next time. */
+export declare function forgetParticipant(table: SeatTable, participantId: ParticipantId): void;
+/**
+ * Role of a participant. `'player'` iff they hold a seat.
+ *
+ * With an unbounded table every participant is a player, which is watchparty's
+ * behaviour today — it has no spectator concept, and inventing one here with
+ * nothing to render it would be a subsystem with no consumer.
+ */
+export declare function roleOf(table: SeatTable, participantId: ParticipantId): SeatRole;
+/** Seats holding a human, in seat order. */
+export declare function humanSeats(table: SeatTable): Array<{
+    id: SeatId;
+    participantId: ParticipantId;
+}>;
+/** Every occupied seat, humans and bots, in seat order. */
+export declare function occupiedSeats(table: SeatTable): Array<{
+    id: SeatId;
+    occupant: SeatOccupant;
+}>;
+/**
+ * Change capacity, releasing any human seated beyond the new limit.
+ *
+ * Returns the participants displaced — the caller decides what that means
+ * (they become spectators; a game in progress may prefer not to shrink at all).
+ * Their seat stays remembered, so growing the table again restores them.
+ */
+export declare function setSeatCapacity(table: SeatTable, capacity: number | null): ParticipantId[];
+/**
+ * Fill up to `count` free seats with bots, after the humans.
+ *
+ * Existing bots are cleared first so the count is a target rather than an
+ * increment — the leader's control sets "how many bots", not "add this many".
+ * Bot ids are positional (`bot:<n>` by seat) so a re-pad is deterministic.
+ */
+export declare function padWithBots(table: SeatTable, count: number): SeatId[];
+/** Free seats available to a new human right now. */
+export declare function freeSeatCount(table: SeatTable): number;
+/**
+ * The table as a RENDERER should see it: one row per seat up to capacity,
+ * empty ones included.
+ *
+ * `SeatTable.seats` grows with arrivals rather than being pre-allocated, which
+ * is right for the table — `seatParticipant` creates the next seat on demand
+ * and `freeSeatCount` compensates with `capacity - seats.length`. It is the
+ * wrong shape for a UI: rendering `table.seats` verbatim draws a four-player
+ * room with two players in it as a TWO-seat table, which reads as "full" or
+ * as broken. (Found by hadoku_site's `templates/game` from a screenshot, not
+ * from a test — nothing about the data is inconsistent, so nothing failed.)
+ *
+ * Here rather than in each consumer because every bounded-table UI needs the
+ * same loop, and a hand-rolled `Array.from({length: capacity})` is one
+ * `seats.length > capacity` away from silently DROPPING an occupied seat from
+ * the view — a player who vanishes from the table while still seated and still
+ * playing. `setSeatCapacity` truncates, so that state is unreachable today;
+ * this keeps it unreachable from the render side too, rather than relying on
+ * every consumer having read that function.
+ *
+ * Unbounded (`capacity === null`) is a pass-through: there is no number to pad
+ * to, and inventing one would draw empty seats nobody may sit in. Rows are
+ * fresh objects, like every other derived view here, so a renderer cannot
+ * mutate the table through one.
+ */
+export declare function seatRows(table: SeatTable): Array<{
+    id: SeatId;
+    occupant: SeatOccupant | null;
+}>;
+//# sourceMappingURL=seats.d.ts.map

package/dist/seats.d.ts.map

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

package/dist/seats.js

@@ -0,0 +1,276 @@
+export function createSeatTable(capacity = null, opts = {}) {
+    return {
+        capacity,
+        seats: [],
+        remembered: {},
+        reservations: {},
+        reservationTtlMs: opts.reservationTtlMs ?? 0,
+    };
+}
+function isHuman(o, participantId) {
+    return o?.kind === 'human' && o.participantId === participantId;
+}
+/** The seat this participant currently occupies, or null. */
+export function seatOf(table, participantId) {
+    const seat = table.seats.find((s) => isHuman(s.occupant, participantId));
+    return seat ? seat.id : null;
+}
+/** Occupant of a seat, or null when empty or out of range. */
+export function occupantOf(table, id) {
+    return table.seats[id]?.occupant ?? null;
+}
+/** Whether another seat could still be created or claimed. */
+function hasRoom(table) {
+    return table.capacity === null || table.seats.length < table.capacity
+        || table.seats.some((s) => s.occupant === null);
+}
+/** Grow the array to cover `id`, filling any hole with empty seats. */
+function ensureSeat(table, id) {
+    while (table.seats.length <= id) {
+        table.seats.push({ id: table.seats.length, occupant: null });
+    }
+    return table.seats[id];
+}
+// ── Reservations ────────────────────────────────────────────────────────────
+/**
+ * The live reservation on a seat, or null when there is none or it has expired.
+ *
+ * Expired entries are deleted as they are found — lazy expiry, so the table
+ * self-cleans through normal use without a timer.
+ */
+export function reservationFor(table, id, now = Date.now()) {
+    const held = table.reservations[id];
+    if (!held)
+        return null;
+    if (held.expiresAt <= now) {
+        delete table.reservations[id];
+        return null;
+    }
+    return held;
+}
+/** The seat currently held for this participant, if any. */
+export function reservedSeatOf(table, participantId, now = Date.now()) {
+    for (const seat of table.seats) {
+        const held = reservationFor(table, seat.id, now);
+        if (held?.participantId === participantId)
+            return seat.id;
+    }
+    return null;
+}
+/** Drop a seat's reservation, whoever it is for. */
+export function clearReservation(table, id) {
+    delete table.reservations[id];
+}
+/**
+ * May this participant take this seat?
+ *
+ * False only when someone ELSE holds a live reservation on it. A participant is
+ * never blocked by their own reservation — that is the point of one.
+ */
+export function seatClaimableBy(table, id, participantId, now = Date.now()) {
+    const held = reservationFor(table, id, now);
+    return held === null || held.participantId === participantId;
+}
+/**
+ * Seat a participant, preferring the seat they last held.
+ *
+ * Returns their SeatId, or null when the table is full of PEOPLE — in which
+ * case the caller treats them as a spectator. Idempotent: already-seated
+ * returns the seat they are in, so a duplicate join cannot take two.
+ *
+ * ## A human outranks a bot
+ *
+ * A bot holding a seat never turns a real player away — it is evicted and the
+ * human takes the seat. Without that, `padWithBots` filling the table locks
+ * every later arrival out permanently: padding clears and re-fills the same
+ * lowest free seat, so the seat a human needs is re-taken the instant it frees.
+ * Callers CAN avoid it by clamping the bot count to capacity-minus-humans (what
+ * `handleGameSetBots` does), but a table that depends on every caller getting
+ * that right will eventually meet one that doesn't.
+ *
+ * Eviction is a last resort, after a genuinely free seat and after growing the
+ * table — bots only move when there is no other way to seat a person. The one
+ * exception is the remembered seat: seat stability is the whole point, so
+ * reclaiming it displaces a bot rather than sending its owner elsewhere.
+ */
+export function seatParticipant(table, participantId, now = Date.now()) {
+    const existing = seatOf(table, participantId);
+    if (existing !== null)
+        return existing;
+    const claim = (seat) => {
+        seat.occupant = { kind: 'human', participantId };
+        table.remembered[participantId] = seat.id;
+        // Taking the seat consumes any hold on it — theirs, by the rule above.
+        clearReservation(table, seat.id);
+        return seat.id;
+    };
+    const open = (seat) => (seat.occupant === null || seat.occupant.kind === 'bot')
+        && seatClaimableBy(table, seat.id, participantId, now);
+    // 1. The remembered seat, if it is within capacity and not held by a person.
+    const remembered = table.remembered[participantId];
+    if (remembered !== undefined && (table.capacity === null || remembered < table.capacity)) {
+        const seat = ensureSeat(table, remembered);
+        if (open(seat))
+            return claim(seat);
+    }
+    // 2. The lowest free seat — deterministic, so two servers replaying the same
+    //    join order land on the same table. Skips seats held for someone else.
+    const free = table.seats.find((s) => s.occupant === null && seatClaimableBy(table, s.id, participantId, now));
+    if (free)
+        return claim(free);
+    // 3. A new seat, while capacity allows one.
+    if (table.capacity === null || table.seats.length < table.capacity) {
+        return claim(ensureSeat(table, table.seats.length));
+    }
+    // 4. Last resort: take the lowest bot's seat — again, not one being held for
+    //    somebody else, or a returning player would find a stranger in it.
+    const bot = table.seats.find((s) => s.occupant?.kind === 'bot' && seatClaimableBy(table, s.id, participantId, now));
+    if (bot)
+        return claim(bot);
+    return null;
+}
+/**
+ * Release a participant's seat, remembering it for their return.
+ *
+ * Returns the vacated SeatId, or null if they held none.
+ */
+export function unseatParticipant(table, participantId, opts = {}) {
+    const id = seatOf(table, participantId);
+    if (id === null)
+        return null;
+    const now = opts.now ?? Date.now();
+    table.seats[id].occupant = null;
+    table.remembered[participantId] = id; // sticky — see header
+    const ttl = opts.ttlMs ?? table.reservationTtlMs;
+    if ((opts.hold ?? true) && ttl > 0) {
+        table.reservations[id] = { participantId, expiresAt: now + ttl };
+    }
+    // No `else clearReservation(id)`. It looks prudent and is unreachable: this
+    // function is the ONLY writer of a reservation and it empties the seat in the
+    // same breath, so a held seat is always vacant — and a vacant seat is not one
+    // anybody is being unseated from. `claim()` consumes the hold on the way back
+    // in. A mutation test proved the branch dead (removing it failed nothing).
+    return id;
+}
+/** Forget a participant entirely, so they get a fresh seat next time. */
+export function forgetParticipant(table, participantId) {
+    unseatParticipant(table, participantId, { hold: false });
+    delete table.remembered[participantId];
+    const held = reservedSeatOf(table, participantId);
+    if (held !== null)
+        clearReservation(table, held);
+}
+/**
+ * Role of a participant. `'player'` iff they hold a seat.
+ *
+ * With an unbounded table every participant is a player, which is watchparty's
+ * behaviour today — it has no spectator concept, and inventing one here with
+ * nothing to render it would be a subsystem with no consumer.
+ */
+export function roleOf(table, participantId) {
+    return seatOf(table, participantId) === null ? 'spectator' : 'player';
+}
+/** Seats holding a human, in seat order. */
+export function humanSeats(table) {
+    const out = [];
+    for (const s of table.seats) {
+        if (s.occupant?.kind === 'human')
+            out.push({ id: s.id, participantId: s.occupant.participantId });
+    }
+    return out;
+}
+/** Every occupied seat, humans and bots, in seat order. */
+export function occupiedSeats(table) {
+    const out = [];
+    for (const s of table.seats) {
+        if (s.occupant !== null)
+            out.push({ id: s.id, occupant: s.occupant });
+    }
+    return out;
+}
+/**
+ * Change capacity, releasing any human seated beyond the new limit.
+ *
+ * Returns the participants displaced — the caller decides what that means
+ * (they become spectators; a game in progress may prefer not to shrink at all).
+ * Their seat stays remembered, so growing the table again restores them.
+ */
+export function setSeatCapacity(table, capacity) {
+    table.capacity = capacity;
+    if (capacity === null)
+        return [];
+    const displaced = [];
+    for (const seat of table.seats.slice(capacity)) {
+        if (seat.occupant?.kind === 'human')
+            displaced.push(seat.occupant.participantId);
+        seat.occupant = null;
+        // A reservation on a seat that no longer exists can never be honoured and
+        // would keep `reservedSeatOf` pointing off the end of the table.
+        clearReservation(table, seat.id);
+    }
+    table.seats.length = Math.min(table.seats.length, capacity);
+    return displaced;
+}
+/**
+ * Fill up to `count` free seats with bots, after the humans.
+ *
+ * Existing bots are cleared first so the count is a target rather than an
+ * increment — the leader's control sets "how many bots", not "add this many".
+ * Bot ids are positional (`bot:<n>` by seat) so a re-pad is deterministic.
+ */
+export function padWithBots(table, count) {
+    for (const seat of table.seats) {
+        if (seat.occupant?.kind === 'bot')
+            seat.occupant = null;
+    }
+    const filled = [];
+    let remaining = Math.max(0, count);
+    while (remaining > 0 && hasRoom(table)) {
+        const free = table.seats.find((s) => s.occupant === null);
+        const seat = free ?? ensureSeat(table, table.seats.length);
+        seat.occupant = { kind: 'bot', botId: `bot:${seat.id}` };
+        filled.push(seat.id);
+        remaining -= 1;
+    }
+    return filled;
+}
+/** Free seats available to a new human right now. */
+export function freeSeatCount(table) {
+    const empty = table.seats.filter((s) => s.occupant === null).length;
+    if (table.capacity === null)
+        return empty + 1; // one can always be created
+    return empty + Math.max(0, table.capacity - table.seats.length);
+}
+/**
+ * The table as a RENDERER should see it: one row per seat up to capacity,
+ * empty ones included.
+ *
+ * `SeatTable.seats` grows with arrivals rather than being pre-allocated, which
+ * is right for the table — `seatParticipant` creates the next seat on demand
+ * and `freeSeatCount` compensates with `capacity - seats.length`. It is the
+ * wrong shape for a UI: rendering `table.seats` verbatim draws a four-player
+ * room with two players in it as a TWO-seat table, which reads as "full" or
+ * as broken. (Found by hadoku_site's `templates/game` from a screenshot, not
+ * from a test — nothing about the data is inconsistent, so nothing failed.)
+ *
+ * Here rather than in each consumer because every bounded-table UI needs the
+ * same loop, and a hand-rolled `Array.from({length: capacity})` is one
+ * `seats.length > capacity` away from silently DROPPING an occupied seat from
+ * the view — a player who vanishes from the table while still seated and still
+ * playing. `setSeatCapacity` truncates, so that state is unreachable today;
+ * this keeps it unreachable from the render side too, rather than relying on
+ * every consumer having read that function.
+ *
+ * Unbounded (`capacity === null`) is a pass-through: there is no number to pad
+ * to, and inventing one would draw empty seats nobody may sit in. Rows are
+ * fresh objects, like every other derived view here, so a renderer cannot
+ * mutate the table through one.
+ */
+export function seatRows(table) {
+    const rows = table.seats.map((s) => ({ id: s.id, occupant: s.occupant }));
+    if (table.capacity === null)
+        return rows;
+    for (let id = rows.length; id < table.capacity; id++)
+        rows.push({ id, occupant: null });
+    return rows;
+}