@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 +109 -10
- package/dist/seats.d.ts.map +1 -1
- package/dist/seats.js +129 -24
- package/package.json +2 -2
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 —
|
|
255
|
-
*
|
|
256
|
-
*
|
|
257
|
-
*
|
|
258
|
-
* that wants a specific seat gone can
|
|
259
|
-
* that one SeatId and lower capacity by
|
|
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
|
-
/**
|
|
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
|
package/dist/seats.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"seats.d.ts","sourceRoot":"","sources":["../src/seats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD
|
|
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) =>
|
|
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
|
|
118
|
-
|
|
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
|
|
126
|
-
// somebody else, or a returning player would find a
|
|
127
|
-
|
|
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 —
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
* that wants a specific seat gone can
|
|
230
|
-
* that one SeatId and lower capacity by
|
|
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
|
-
/**
|
|
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.
|
|
4
|
-
"gitHead": "
|
|
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.",
|