@hadoku/rooms-protocol 0.45.98 → 0.45.99

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/seats.d.ts CHANGED
@@ -64,6 +64,30 @@ import type { ParticipantId } from './participantId.js';
64
64
  * renders them as `{}`. This table is plain JSON-safe data so that a pluggable
65
65
  * snapshot/restore is a matter of writing it out, not of teaching a serializer
66
66
  * about five container types. Keep it that way.
67
+ *
68
+ * ## Closed seats (2026-11-16, hadoku-cardtable's draft pods)
69
+ *
70
+ * A seat the LEADER closed: it still EXISTS (it counts toward
71
+ * `table.seats.length` and so toward capacity's shape — a UI drawing the
72
+ * table still needs a slot for it), but nobody — human or bot — may sit in
73
+ * it, below an open seat or between two of them. Magic's draft pods close a
74
+ * specific seat (shrinking the draft by one) while every other seat,
75
+ * including a higher one, stays open; `SeatTable.capacity` alone cannot say
76
+ * that, which is the gap this closes.
77
+ *
78
+ * `seatParticipant`, `padWithBots` and the single-seat `seatBot` all skip a
79
+ * closed seat, exactly as they skip one past `capacity`. `closeSeat` itself
80
+ * refuses an OCCUPIED seat rather than evicting — same shape as
81
+ * `unseatParticipant`/`removeFromSeat` already being the caller's job when an
82
+ * occupant must go first. A closed seat holds no reservation (closing one
83
+ * clears it) and keeps no occupant, so "closed" and "occupied" are mutually
84
+ * exclusive by construction — nothing downstream has to check both.
85
+ *
86
+ * `setSeatCapacity`'s shrink is unaffected: it slices away seats past the new
87
+ * capacity (closed or not) and a closed seat, having no occupant, is never
88
+ * among the participants it reports displaced — "lowering capacity never
89
+ * evicts into a closed seat" holds because a closed seat is never a
90
+ * destination for anyone, displaced or not.
67
91
  */
68
92
  /** Index into `SeatTable.seats`. Stable across a reconnect. */
69
93
  export type SeatId = number;
@@ -78,8 +102,23 @@ export type SeatOccupant = {
78
102
  };
79
103
  export interface Seat {
80
104
  id: SeatId;
81
- /** null = empty and claimable. */
105
+ /** null = empty and claimable (unless `closed`). */
82
106
  occupant: SeatOccupant | null;
107
+ /**
108
+ * The leader closed this seat: present for the table's shape, claimable by
109
+ * nobody. Absent or false on a seat nobody has closed — see this module's
110
+ * header, "Closed seats". A closed seat's `occupant` is always null; the
111
+ * two are mutually exclusive by construction (`closeSeat` refuses an
112
+ * occupied seat rather than evicting).
113
+ *
114
+ * OPTIONAL, not required, even though every seat this module creates sets
115
+ * it explicitly: a seat literal built before 2026-11-16 (a fixture, a
116
+ * stored record predating this field) has no `closed` key at all, and
117
+ * every read here treats that exactly like `false` — making the field
118
+ * required would turn every such literal into a type error for a property
119
+ * that was never wrong, only older.
120
+ */
121
+ closed?: boolean;
83
122
  }
84
123
  /** A seat held for one participant until `expiresAt` (epoch ms). */
85
124
  export interface SeatReservation {
@@ -135,6 +174,37 @@ export declare function createSeatTable(capacity?: number | null, opts?: SeatTab
135
174
  export declare function seatOf(table: SeatTable, participantId: ParticipantId): SeatId | null;
136
175
  /** Occupant of a seat, or null when empty or out of range. */
137
176
  export declare function occupantOf(table: SeatTable, id: SeatId): SeatOccupant | null;
177
+ /** Is this seat closed? False (not an error) for a seat that does not exist. */
178
+ export declare function isClosed(table: SeatTable, id: SeatId): boolean;
179
+ /**
180
+ * Close an EMPTY seat so nobody may claim it — present for the table's
181
+ * shape, claimable by nobody. Refuses (returns false) an occupied seat:
182
+ * closing never evicts, same division of labour as every other op here —
183
+ * the caller empties a seat first (`unseatParticipant`/`removeFromSeat`/
184
+ * `unseatBot`) if that is what it wants.
185
+ *
186
+ * MATERIALIZES the seat if it is within capacity but nobody has reached it
187
+ * yet (same as `seatParticipant`'s remembered-seat step) — cardtable's pods
188
+ * close a seat index before anyone has sat anywhere near it, so requiring a
189
+ * prior arrival just to have something to close would make this unusable
190
+ * for its own reason for existing. Refuses (returns false, never grows) a
191
+ * seat AT OR PAST a bounded `capacity`: there is no such seat to close.
192
+ *
193
+ * Idempotent: already closed is a no-op success. Drops any reservation on
194
+ * the seat — a closed seat holds nothing for anybody (see this module's
195
+ * header).
196
+ */
197
+ export declare function closeSeat(table: SeatTable, id: SeatId): boolean;
198
+ /**
199
+ * Reopen a closed seat so it may be claimed again — `seatParticipant`,
200
+ * `padWithBots` and `seatBot` all see it the instant it reopens, same as any
201
+ * other seat becoming free. No-op true for a seat that is not closed, or
202
+ * that does not exist yet (vacuously not closed either way; this never
203
+ * grows the table — there is nothing to materialize, only a fact to leave
204
+ * unchanged). False only for an id that could never be a seat: negative, or
205
+ * at/past a bounded `capacity`.
206
+ */
207
+ export declare function openSeat(table: SeatTable, id: SeatId): boolean;
138
208
  /**
139
209
  * The live reservation on a seat, or null when there is none or it has expired.
140
210
  *
@@ -251,17 +321,20 @@ export declare function occupiedSeats(table: SeatTable): Array<{
251
321
  * (`slice(capacity)`): the array can never hold more than `capacity` entries
252
322
  * afterward, so nobody above the new line survives, and nobody below it is
253
323
  * ever touched. A caller-chosen seat to sacrifice instead is deliberately not
254
- * offered — this table has no concept of a specific seat that is "closed"
255
- * while a higher one stays open (that would mean `seats.length` no longer
256
- * bounding `capacity`, breaking `hasRoom` and `freeSeatCount`), and inventing
257
- * one would be a second notion of "capacity" alongside this number. A caller
258
- * that wants a specific seat gone can `unseatParticipant`/`removeFromSeat`
259
- * that one SeatId and lower capacity by one separately — two calls, not a
260
- * hidden extra state.
324
+ * offered here — that is `closeSeat` (added 2026-11-16 for a bounded seat
325
+ * that stays below an open one), a DIFFERENT shape of shrink: this one
326
+ * removes the seat from the table entirely (shortening `seats`), `closeSeat`
327
+ * keeps it in place and merely closes it (`seats.length` unchanged). A
328
+ * caller that wants a specific seat gone rather than closed can still
329
+ * `unseatParticipant`/`removeFromSeat` that one SeatId and lower capacity by
330
+ * one separately — two calls, not a hidden extra state. A closed seat
331
+ * sliced away here is simply removed like any other (never evicted — it
332
+ * holds no occupant by construction) and never appears in `displaced`.
261
333
  */
262
334
  export declare function setSeatCapacity(table: SeatTable, capacity: number | null): ParticipantId[];
263
335
  /**
264
- * Fill up to `count` free seats with bots, after the humans.
336
+ * Fill up to `count` free seats with bots, after the humans. Never a closed
337
+ * seat — same as `seatParticipant`, closed means nobody, bot or human.
265
338
  *
266
339
  * Existing bots are cleared first so the count is a target rather than an
267
340
  * increment — the leader's control sets "how many bots", not "add this many".
@@ -284,9 +357,28 @@ export declare function padWithBots(table: SeatTable, count: number): SeatId[];
284
357
  * only to leave that memory behind.
285
358
  *
286
359
  * Returns the SeatId, or null if the participant held no seat to replace.
360
+ * `seatBot`, below, is the sibling for an EMPTY seat (`padWithBots`'
361
+ * single-seat form, keyed by seat rather than by participant).
287
362
  */
288
363
  export declare function replaceWithBot(table: SeatTable, participantId: ParticipantId): SeatId | null;
289
- /** Free seats available to a new human right now. */
364
+ /**
365
+ * Put a bot in ONE specific empty, open seat — the leader toggling a single
366
+ * seat, as distinct from `padWithBots`' whole-table target count. Refuses a
367
+ * closed seat or a seat already holding a HUMAN (returns null —
368
+ * `replaceWithBot` is the op that evicts one). MATERIALIZES the seat if it
369
+ * is within capacity but unreached, same as `closeSeat`; refuses (never
370
+ * grows) a seat at or past a bounded `capacity`. Already a bot there is a
371
+ * no-op success, same id back. Ignores reservations, same as `padWithBots` —
372
+ * a reservation blocks another human, never a bot.
373
+ */
374
+ export declare function seatBot(table: SeatTable, id: SeatId): SeatId | null;
375
+ /**
376
+ * Take the bot out of a seat, opening it. Null (no-op) on a seat holding no
377
+ * bot — empty, closed, or a human's — same contract as `unseatParticipant`
378
+ * answering null for a seat a participant does not hold.
379
+ */
380
+ export declare function unseatBot(table: SeatTable, id: SeatId): SeatId | null;
381
+ /** Free seats available to a new human right now. A closed seat is never free. */
290
382
  export declare function freeSeatCount(table: SeatTable): number;
291
383
  /**
292
384
  * The table as a RENDERER should see it: one row per seat up to capacity,
@@ -312,9 +404,16 @@ export declare function freeSeatCount(table: SeatTable): number;
312
404
  * to, and inventing one would draw empty seats nobody may sit in. Rows are
313
405
  * fresh objects, like every other derived view here, so a renderer cannot
314
406
  * mutate the table through one.
407
+ *
408
+ * Carries `closed` because a renderer needs it: a closed seat still takes a
409
+ * slot in the table's shape (this is exactly the view where that matters —
410
+ * `table.seats` verbatim would draw it the same as any other seat) but must
411
+ * be drawn as unclaimable, never as empty. Padded rows past `seats.length`
412
+ * are never closed — nobody has closed a seat that does not exist yet.
315
413
  */
316
414
  export declare function seatRows(table: SeatTable): Array<{
317
415
  id: SeatId;
318
416
  occupant: SeatOccupant | null;
417
+ closed: boolean;
319
418
  }>;
320
419
  //# sourceMappingURL=seats.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"seats.d.ts","sourceRoot":"","sources":["../src/seats.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"seats.d.ts","sourceRoot":"","sources":["../src/seats.ts"],"names":[],"mappings":"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"}
package/dist/seats.js CHANGED
@@ -19,18 +19,73 @@ export function seatOf(table, participantId) {
19
19
  export function occupantOf(table, id) {
20
20
  return table.seats[id]?.occupant ?? null;
21
21
  }
22
- /** Whether another seat could still be created or claimed. */
22
+ /** Whether another seat could still be created or claimed (a closed seat is neither). */
23
23
  function hasRoom(table) {
24
24
  return table.capacity === null || table.seats.length < table.capacity
25
- || table.seats.some((s) => s.occupant === null);
25
+ || table.seats.some((s) => s.occupant === null && !s.closed);
26
26
  }
27
- /** Grow the array to cover `id`, filling any hole with empty seats. */
27
+ /** Grow the array to cover `id`, filling any hole with empty (never closed) seats. */
28
28
  function ensureSeat(table, id) {
29
29
  while (table.seats.length <= id) {
30
- table.seats.push({ id: table.seats.length, occupant: null });
30
+ table.seats.push({ id: table.seats.length, occupant: null, closed: false });
31
31
  }
32
32
  return table.seats[id];
33
33
  }
34
+ /** The seat at `id`, or undefined when it does not exist. Never grows the table — see `ensureSeat` for that. */
35
+ function seatAt(table, id) {
36
+ return table.seats[id];
37
+ }
38
+ /** Is this seat closed? False (not an error) for a seat that does not exist. */
39
+ export function isClosed(table, id) {
40
+ return seatAt(table, id)?.closed ?? false;
41
+ }
42
+ /**
43
+ * Close an EMPTY seat so nobody may claim it — present for the table's
44
+ * shape, claimable by nobody. Refuses (returns false) an occupied seat:
45
+ * closing never evicts, same division of labour as every other op here —
46
+ * the caller empties a seat first (`unseatParticipant`/`removeFromSeat`/
47
+ * `unseatBot`) if that is what it wants.
48
+ *
49
+ * MATERIALIZES the seat if it is within capacity but nobody has reached it
50
+ * yet (same as `seatParticipant`'s remembered-seat step) — cardtable's pods
51
+ * close a seat index before anyone has sat anywhere near it, so requiring a
52
+ * prior arrival just to have something to close would make this unusable
53
+ * for its own reason for existing. Refuses (returns false, never grows) a
54
+ * seat AT OR PAST a bounded `capacity`: there is no such seat to close.
55
+ *
56
+ * Idempotent: already closed is a no-op success. Drops any reservation on
57
+ * the seat — a closed seat holds nothing for anybody (see this module's
58
+ * header).
59
+ */
60
+ export function closeSeat(table, id) {
61
+ if (id < 0 || (table.capacity !== null && id >= table.capacity))
62
+ return false;
63
+ const seat = ensureSeat(table, id);
64
+ if (seat.closed)
65
+ return true;
66
+ if (seat.occupant !== null)
67
+ return false;
68
+ seat.closed = true;
69
+ clearReservation(table, id);
70
+ return true;
71
+ }
72
+ /**
73
+ * Reopen a closed seat so it may be claimed again — `seatParticipant`,
74
+ * `padWithBots` and `seatBot` all see it the instant it reopens, same as any
75
+ * other seat becoming free. No-op true for a seat that is not closed, or
76
+ * that does not exist yet (vacuously not closed either way; this never
77
+ * grows the table — there is nothing to materialize, only a fact to leave
78
+ * unchanged). False only for an id that could never be a seat: negative, or
79
+ * at/past a bounded `capacity`.
80
+ */
81
+ export function openSeat(table, id) {
82
+ if (id < 0 || (table.capacity !== null && id >= table.capacity))
83
+ return false;
84
+ const seat = seatAt(table, id);
85
+ if (seat !== undefined)
86
+ seat.closed = false;
87
+ return true;
88
+ }
34
89
  // ── Reservations ────────────────────────────────────────────────────────────
35
90
  /**
36
91
  * The live reservation on a seat, or null when there is none or it has expired.
@@ -104,7 +159,8 @@ export function seatParticipant(table, participantId, now = Date.now()) {
104
159
  clearReservation(table, seat.id);
105
160
  return seat.id;
106
161
  };
107
- const open = (seat) => (seat.occupant === null || seat.occupant.kind === 'bot')
162
+ const open = (seat) => !seat.closed
163
+ && (seat.occupant === null || seat.occupant.kind === 'bot')
108
164
  && seatClaimableBy(table, seat.id, participantId, now);
109
165
  // 1. The remembered seat, if it is within capacity and not held by a person.
110
166
  const remembered = table.remembered[participantId];
@@ -114,17 +170,20 @@ export function seatParticipant(table, participantId, now = Date.now()) {
114
170
  return claim(seat);
115
171
  }
116
172
  // 2. The lowest free seat — deterministic, so two servers replaying the same
117
- // join order land on the same table. Skips seats held for someone else.
118
- const free = table.seats.find((s) => s.occupant === null && seatClaimableBy(table, s.id, participantId, now));
173
+ // join order land on the same table. Skips closed seats and ones held for
174
+ // someone else.
175
+ const free = table.seats.find((s) => !s.closed && s.occupant === null && seatClaimableBy(table, s.id, participantId, now));
119
176
  if (free)
120
177
  return claim(free);
121
- // 3. A new seat, while capacity allows one.
178
+ // 3. A new seat, while capacity allows one. Never closed — nobody has closed
179
+ // a seat that did not exist a moment ago.
122
180
  if (table.capacity === null || table.seats.length < table.capacity) {
123
181
  return claim(ensureSeat(table, table.seats.length));
124
182
  }
125
- // 4. Last resort: take the lowest bot's seat — again, not one being held for
126
- // somebody else, or a returning player would find a stranger in it.
127
- const bot = table.seats.find((s) => s.occupant?.kind === 'bot' && seatClaimableBy(table, s.id, participantId, now));
183
+ // 4. Last resort: take the lowest bot's seat — again, not a closed one or
184
+ // one being held for somebody else, or a returning player would find a
185
+ // stranger in it.
186
+ const bot = table.seats.find((s) => !s.closed && s.occupant?.kind === 'bot' && seatClaimableBy(table, s.id, participantId, now));
128
187
  if (bot)
129
188
  return claim(bot);
130
189
  return null;
@@ -222,13 +281,15 @@ export function occupiedSeats(table) {
222
281
  * (`slice(capacity)`): the array can never hold more than `capacity` entries
223
282
  * afterward, so nobody above the new line survives, and nobody below it is
224
283
  * ever touched. A caller-chosen seat to sacrifice instead is deliberately not
225
- * offered — this table has no concept of a specific seat that is "closed"
226
- * while a higher one stays open (that would mean `seats.length` no longer
227
- * bounding `capacity`, breaking `hasRoom` and `freeSeatCount`), and inventing
228
- * one would be a second notion of "capacity" alongside this number. A caller
229
- * that wants a specific seat gone can `unseatParticipant`/`removeFromSeat`
230
- * that one SeatId and lower capacity by one separately — two calls, not a
231
- * hidden extra state.
284
+ * offered here — that is `closeSeat` (added 2026-11-16 for a bounded seat
285
+ * that stays below an open one), a DIFFERENT shape of shrink: this one
286
+ * removes the seat from the table entirely (shortening `seats`), `closeSeat`
287
+ * keeps it in place and merely closes it (`seats.length` unchanged). A
288
+ * caller that wants a specific seat gone rather than closed can still
289
+ * `unseatParticipant`/`removeFromSeat` that one SeatId and lower capacity by
290
+ * one separately — two calls, not a hidden extra state. A closed seat
291
+ * sliced away here is simply removed like any other (never evicted — it
292
+ * holds no occupant by construction) and never appears in `displaced`.
232
293
  */
233
294
  export function setSeatCapacity(table, capacity) {
234
295
  table.capacity = capacity;
@@ -246,7 +307,8 @@ export function setSeatCapacity(table, capacity) {
246
307
  return displaced;
247
308
  }
248
309
  /**
249
- * Fill up to `count` free seats with bots, after the humans.
310
+ * Fill up to `count` free seats with bots, after the humans. Never a closed
311
+ * seat — same as `seatParticipant`, closed means nobody, bot or human.
250
312
  *
251
313
  * Existing bots are cleared first so the count is a target rather than an
252
314
  * increment — the leader's control sets "how many bots", not "add this many".
@@ -260,7 +322,7 @@ export function padWithBots(table, count) {
260
322
  const filled = [];
261
323
  let remaining = Math.max(0, count);
262
324
  while (remaining > 0 && hasRoom(table)) {
263
- const free = table.seats.find((s) => s.occupant === null);
325
+ const free = table.seats.find((s) => s.occupant === null && !s.closed);
264
326
  const seat = free ?? ensureSeat(table, table.seats.length);
265
327
  seat.occupant = { kind: 'bot', botId: `bot:${seat.id}` };
266
328
  filled.push(seat.id);
@@ -284,6 +346,8 @@ export function padWithBots(table, count) {
284
346
  * only to leave that memory behind.
285
347
  *
286
348
  * Returns the SeatId, or null if the participant held no seat to replace.
349
+ * `seatBot`, below, is the sibling for an EMPTY seat (`padWithBots`'
350
+ * single-seat form, keyed by seat rather than by participant).
287
351
  */
288
352
  export function replaceWithBot(table, participantId) {
289
353
  const id = seatOf(table, participantId);
@@ -293,9 +357,44 @@ export function replaceWithBot(table, participantId) {
293
357
  table.seats[id].occupant = { kind: 'bot', botId: `bot:${id}` };
294
358
  return id;
295
359
  }
296
- /** Free seats available to a new human right now. */
360
+ /**
361
+ * Put a bot in ONE specific empty, open seat — the leader toggling a single
362
+ * seat, as distinct from `padWithBots`' whole-table target count. Refuses a
363
+ * closed seat or a seat already holding a HUMAN (returns null —
364
+ * `replaceWithBot` is the op that evicts one). MATERIALIZES the seat if it
365
+ * is within capacity but unreached, same as `closeSeat`; refuses (never
366
+ * grows) a seat at or past a bounded `capacity`. Already a bot there is a
367
+ * no-op success, same id back. Ignores reservations, same as `padWithBots` —
368
+ * a reservation blocks another human, never a bot.
369
+ */
370
+ export function seatBot(table, id) {
371
+ if (id < 0 || (table.capacity !== null && id >= table.capacity))
372
+ return null;
373
+ const seat = ensureSeat(table, id);
374
+ if (seat.closed)
375
+ return null;
376
+ if (seat.occupant?.kind === 'bot')
377
+ return id;
378
+ if (seat.occupant !== null)
379
+ return null;
380
+ seat.occupant = { kind: 'bot', botId: `bot:${id}` };
381
+ return id;
382
+ }
383
+ /**
384
+ * Take the bot out of a seat, opening it. Null (no-op) on a seat holding no
385
+ * bot — empty, closed, or a human's — same contract as `unseatParticipant`
386
+ * answering null for a seat a participant does not hold.
387
+ */
388
+ export function unseatBot(table, id) {
389
+ const seat = table.seats[id];
390
+ if (seat === undefined || seat.occupant?.kind !== 'bot')
391
+ return null;
392
+ seat.occupant = null;
393
+ return id;
394
+ }
395
+ /** Free seats available to a new human right now. A closed seat is never free. */
297
396
  export function freeSeatCount(table) {
298
- const empty = table.seats.filter((s) => s.occupant === null).length;
397
+ const empty = table.seats.filter((s) => s.occupant === null && !s.closed).length;
299
398
  if (table.capacity === null)
300
399
  return empty + 1; // one can always be created
301
400
  return empty + Math.max(0, table.capacity - table.seats.length);
@@ -324,12 +423,18 @@ export function freeSeatCount(table) {
324
423
  * to, and inventing one would draw empty seats nobody may sit in. Rows are
325
424
  * fresh objects, like every other derived view here, so a renderer cannot
326
425
  * mutate the table through one.
426
+ *
427
+ * Carries `closed` because a renderer needs it: a closed seat still takes a
428
+ * slot in the table's shape (this is exactly the view where that matters —
429
+ * `table.seats` verbatim would draw it the same as any other seat) but must
430
+ * be drawn as unclaimable, never as empty. Padded rows past `seats.length`
431
+ * are never closed — nobody has closed a seat that does not exist yet.
327
432
  */
328
433
  export function seatRows(table) {
329
- const rows = table.seats.map((s) => ({ id: s.id, occupant: s.occupant }));
434
+ const rows = table.seats.map((s) => ({ id: s.id, occupant: s.occupant, closed: s.closed ?? false }));
330
435
  if (table.capacity === null)
331
436
  return rows;
332
437
  for (let id = rows.length; id < table.capacity; id++)
333
- rows.push({ id, occupant: null });
438
+ rows.push({ id, occupant: null, closed: false });
334
439
  return rows;
335
440
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@hadoku/rooms-protocol",
3
- "version": "0.45.98",
4
- "gitHead": "1a103a0407fdc339669849a4b43a9b68f9319662",
3
+ "version": "0.45.99",
4
+ "gitHead": "5075e839dd6ee20cc08dd4294d823772b384370c",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "description": "Room, identity and seating protocol — the wire contract shared by rooms-server and rooms-client.",