@hadoku/rooms-server 0.0.0-stage → 0.43.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthaeus Wolff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/emit.d.ts

@@ -0,0 +1,85 @@
+import type { Server as SocketIOServer, Socket } from 'socket.io';
+import { type SeatRole } from '@wolffm/rooms-protocol';
+import type { CoreRoomState, ClientMeta } from './state.js';
+/**
+ * Backpressure-aware emit.
+ *
+ * A socket whose write buffer is already deep cannot be helped by adding to
+ * it, so above a threshold the low-value events are dropped rather than
+ * queued. Which events those are is the HOSTING APP's call: this was extracted
+ * with `control_broadcast`, `chat_broadcast` and `time_pong` hardcoded, and
+ * shipping that list would have silently dropped a card game's state deltas as
+ * "low priority".
+ */
+export interface EmitPolicy {
+    /** Above this many buffered bytes, droppable events are dropped. */
+    thresholdBytes: number;
+    /** Never dropped, whatever the buffer depth. */
+    highPriority: ReadonlySet<string>;
+    /** Droppable, EARLIEST FIRST. An event in neither list is never dropped. */
+    lowPriorityOrder: readonly string[];
+    /** Called when an event is dropped (metrics, throttled logging). */
+    onDrop?: (info: {
+        event: string;
+        bufferedBytes: number;
+        socketId: string;
+    }) => void;
+    /** Called when the emit itself threw, after a retry. */
+    onError?: (info: {
+        event: string;
+        socketId: string;
+        err: unknown;
+    }) => void;
+}
+export declare function safeEmit(socket: Socket, event: string, payload: unknown, policy: EmitPolicy): void;
+/**
+ * Returned from an `emitPerRecipient` builder to send that recipient nothing.
+ *
+ * A sentinel rather than `null`, because `null` is a legal payload — and this
+ * codebase has already paid for that ambiguity once: `applySnapshot` has to
+ * use `!== undefined` rather than `??` precisely because `null` means "no
+ * media" there rather than "absent".
+ */
+export declare const SKIP: unique symbol;
+/**
+ * Emit to every client in a room. Returns the recipient count.
+ *
+ * Uses socket.io's own room set when the sockets have joined it, falling back
+ * to the room's client map otherwise — and cross-checks membership either way,
+ * so a socket that is in the adapter's room but not ours is not served.
+ */
+export declare function broadcastToRoom<TApp, TClient>(io: SocketIOServer, room: CoreRoomState<TApp, TClient>, event: string, payload: unknown, policy?: EmitPolicy): number;
+/**
+ * Emit a DIFFERENT payload to each recipient. Returns the number sent.
+ *
+ * The reason this exists: broadcasting one payload to the whole room is
+ * structurally wrong for anything with hidden state. A card game's opponent
+ * must not receive your hand *at all* — not receive it and decline to render
+ * it. Filtering at the client is not privacy.
+ *
+ * `build` returns the payload for that recipient, or `SKIP` to send nothing.
+ * It runs once per connected client, so keep anything expensive outside it.
+ *
+ * ## Why `TPayload` is generic and constrained
+ *
+ * This took `unknown | typeof SKIP` in 0.38.110, which **constrains nothing**:
+ * `unknown` absorbs every union member, so the whole thing collapses to plain
+ * `unknown` and the `SKIP` arm was decoration. A `build` that fell off the end
+ * and returned `undefined` type-checked cleanly. (Found by the first outside
+ * consumer reading the published `.d.ts`.)
+ *
+ * The bound is `{} | null` rather than a bare type parameter because a bare one
+ * would simply infer `TPayload = undefined` and compile again. `{}` excludes
+ * both `null` and `undefined`, so the union puts `null` back deliberately —
+ * `null` IS a legal payload here, which is the entire reason `SKIP` is a symbol.
+ */
+export declare function emitPerRecipient<TApp, TClient, TPayload extends {} | null>(io: SocketIOServer, room: CoreRoomState<TApp, TClient>, event: string, build: (client: ClientMeta<TClient>) => TPayload | typeof SKIP, policy?: EmitPolicy): number;
+/**
+ * Emit one payload to everyone holding a given seat role. Returns the count.
+ *
+ * Role is DERIVED from the seat table (`roleOf`), never stored — see
+ * rooms-protocol's seats.ts for why a stored role and the seating can
+ * disagree, and what that costs.
+ */
+export declare function emitToRole<TApp, TClient, TPayload extends {} | null>(io: SocketIOServer, room: CoreRoomState<TApp, TClient>, role: SeatRole, event: string, payload: TPayload, policy?: EmitPolicy): number;
+//# sourceMappingURL=emit.d.ts.map

package/dist/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAU,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,4EAA4E;IAC5E,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACpF,wDAAwD;IACxD,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CAC7E;AAyBD,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAmBlG;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,EAAE,OAAO,MAA6B,CAAC;AAExD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAC3C,EAAE,EAAE,cAAc,EAClB,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,EAClC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,UAAU,GAClB,MAAM,CAaR;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,SAAS,EAAE,GAAG,IAAI,EACxE,EAAE,EAAE,cAAc,EAClB,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,EAClC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,KAAK,QAAQ,GAAG,OAAO,IAAI,EAC9D,MAAM,CAAC,EAAE,UAAU,GAClB,MAAM,CAYR;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,SAAS,EAAE,GAAG,IAAI,EAClE,EAAE,EAAE,cAAc,EAClB,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,EAClC,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,QAAQ,EACjB,MAAM,CAAC,EAAE,UAAU,GAClB,MAAM,CAQR"}

package/dist/emit.js

@@ -0,0 +1,128 @@
+import { roleOf } from '@wolffm/rooms-protocol';
+/**
+ * An event in NEITHER list is never dropped.
+ *
+ * That default is deliberate: a new event type added by an app that forgot to
+ * classify it will be delivered, not silently discarded. The failure mode of
+ * over-delivery is a slow client; the failure mode of over-dropping is a
+ * feature that mysteriously does not work under load.
+ */
+function bufferedBytes(socket) {
+    // engine.io's write buffer. Approximate by design — the exact wire size is
+    // not knowable here, and the decision only needs an order of magnitude.
+    const engine = socket.conn;
+    const writeBuffer = engine?.writeBuffer ?? [];
+    let total = 0;
+    for (const pkt of writeBuffer) {
+        if (pkt && pkt.data != null) {
+            const str = typeof pkt.data === 'string' ? pkt.data : JSON.stringify(pkt.data);
+            total += Buffer.byteLength(str);
+        }
+    }
+    return total;
+}
+export function safeEmit(socket, event, payload, policy) {
+    try {
+        const buffered = bufferedBytes(socket);
+        if (buffered > policy.thresholdBytes && !policy.highPriority.has(event)) {
+            if (policy.lowPriorityOrder.includes(event)) {
+                policy.onDrop?.({ event, bufferedBytes: buffered, socketId: socket.id });
+                return;
+            }
+        }
+        socket.emit(event, payload);
+    }
+    catch {
+        // Buffer estimation failed (an engine.io internal changed shape). Still
+        // attempt the emit: a failed measurement must not cost delivery.
+        try {
+            socket.emit(event, payload);
+        }
+        catch (err) {
+            policy.onError?.({ event, socketId: socket.id, err });
+        }
+    }
+}
+/**
+ * Returned from an `emitPerRecipient` builder to send that recipient nothing.
+ *
+ * A sentinel rather than `null`, because `null` is a legal payload — and this
+ * codebase has already paid for that ambiguity once: `applySnapshot` has to
+ * use `!== undefined` rather than `??` precisely because `null` means "no
+ * media" there rather than "absent".
+ */
+export const SKIP = Symbol('rooms.skip');
+/**
+ * Emit to every client in a room. Returns the recipient count.
+ *
+ * Uses socket.io's own room set when the sockets have joined it, falling back
+ * to the room's client map otherwise — and cross-checks membership either way,
+ * so a socket that is in the adapter's room but not ours is not served.
+ */
+export function broadcastToRoom(io, room, event, payload, policy) {
+    let sent = 0;
+    const roomSockets = io.sockets.adapter.rooms.get(room.roomId);
+    const socketIds = roomSockets ?? room.clients.keys();
+    for (const socketId of socketIds) {
+        const socket = io.sockets.sockets.get(socketId);
+        if (socket && room.clients.has(socketId)) {
+            if (policy)
+                safeEmit(socket, event, payload, policy);
+            else
+                socket.emit(event, payload);
+            sent++;
+        }
+    }
+    return sent;
+}
+/**
+ * Emit a DIFFERENT payload to each recipient. Returns the number sent.
+ *
+ * The reason this exists: broadcasting one payload to the whole room is
+ * structurally wrong for anything with hidden state. A card game's opponent
+ * must not receive your hand *at all* — not receive it and decline to render
+ * it. Filtering at the client is not privacy.
+ *
+ * `build` returns the payload for that recipient, or `SKIP` to send nothing.
+ * It runs once per connected client, so keep anything expensive outside it.
+ *
+ * ## Why `TPayload` is generic and constrained
+ *
+ * This took `unknown | typeof SKIP` in 0.38.110, which **constrains nothing**:
+ * `unknown` absorbs every union member, so the whole thing collapses to plain
+ * `unknown` and the `SKIP` arm was decoration. A `build` that fell off the end
+ * and returned `undefined` type-checked cleanly. (Found by the first outside
+ * consumer reading the published `.d.ts`.)
+ *
+ * The bound is `{} | null` rather than a bare type parameter because a bare one
+ * would simply infer `TPayload = undefined` and compile again. `{}` excludes
+ * both `null` and `undefined`, so the union puts `null` back deliberately —
+ * `null` IS a legal payload here, which is the entire reason `SKIP` is a symbol.
+ */
+export function emitPerRecipient(io, room, event, build, policy) {
+    let sent = 0;
+    for (const [clientId, meta] of room.clients) {
+        const socket = io.sockets.sockets.get(clientId);
+        if (!socket)
+            continue;
+        const payload = build(meta);
+        if (payload === SKIP)
+            continue;
+        if (policy)
+            safeEmit(socket, event, payload, policy);
+        else
+            socket.emit(event, payload);
+        sent++;
+    }
+    return sent;
+}
+/**
+ * Emit one payload to everyone holding a given seat role. Returns the count.
+ *
+ * Role is DERIVED from the seat table (`roleOf`), never stored — see
+ * rooms-protocol's seats.ts for why a stored role and the seating can
+ * disagree, and what that costs.
+ */
+export function emitToRole(io, room, role, event, payload, policy) {
+    return emitPerRecipient(io, room, event, (client) => (roleOf(room.seats, client.participantId) === role ? payload : SKIP), policy);
+}

package/dist/gc.d.ts

@@ -0,0 +1,23 @@
+import type { CoreRoomState } from './state.js';
+/**
+ * Reaping idle and empty rooms.
+ *
+ * `evaluateRoom` is pure so the policy can be tested without a registry.
+ */
+export interface GCEvalResult {
+    idle: boolean;
+    empty: boolean;
+    shouldDestroy: boolean;
+}
+export interface GCTimings {
+    /** Threshold to consider a room idle. */
+    idleMs: number;
+    /** Grace period after the last client leaves. */
+    emptyGraceMs: number;
+}
+export declare function evaluateRoom<TApp, TClient>(room: CoreRoomState<TApp, TClient>, timings: GCTimings, now?: number): GCEvalResult;
+/** Rooms that should be destroyed now. */
+export declare function collectGC<TApp, TClient>(rooms: Array<CoreRoomState<TApp, TClient>>, timings: GCTimings, now?: number): {
+    destroy: Array<CoreRoomState<TApp, TClient>>;
+};
+//# sourceMappingURL=gc.d.ts.map

package/dist/gc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gc.d.ts","sourceRoot":"","sources":["../src/gc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;GAIG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EACxC,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,EAClC,OAAO,EAAE,SAAS,EAClB,GAAG,GAAE,MAAmB,GACvB,YAAY,CAWd;AAED,0CAA0C;AAC1C,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,EACrC,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,EAC1C,OAAO,EAAE,SAAS,EAClB,GAAG,GAAE,MAAmB,GACvB;IAAE,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,CAMlD"}

package/dist/gc.js

@@ -0,0 +1,22 @@
+export function evaluateRoom(room, timings, now = Date.now()) {
+    const idle = (now - room.updatedAt) >= timings.idleMs;
+    const empty = room.clients.size === 0;
+    let shouldDestroy = false;
+    if (empty) {
+        // `updatedAt` stands in for "last emptied". Coarse but conservative: any
+        // activity at all pushes the destroy decision out.
+        const emptyDuration = now - room.updatedAt;
+        if (emptyDuration >= timings.emptyGraceMs)
+            shouldDestroy = true;
+    }
+    return { idle, empty, shouldDestroy };
+}
+/** Rooms that should be destroyed now. */
+export function collectGC(rooms, timings, now = Date.now()) {
+    const destroy = [];
+    for (const r of rooms) {
+        if (evaluateRoom(r, timings, now).shouldDestroy)
+            destroy.push(r);
+    }
+    return { destroy };
+}

package/dist/identity.d.ts

@@ -0,0 +1,45 @@
+import { type ParticipantId, type ParticipantIdTier } from '@wolffm/rooms-protocol';
+export interface DeriveParticipantInput {
+    /**
+     * The platform account id — the key registry's `userId`, resolved
+     * SERVER-SIDE from the caller's credential through whoami. The `account`
+     * tier's preferred material, because it survives key rotation. Never take
+     * it from a client payload or from the `X-User-Id` header a request that
+     * bypassed the edge could set.
+     */
+    accountId?: string | null;
+    /**
+     * DEPRECATED account material — the raw `X-User-Key` credential. Used only
+     * when no `accountId` is given. An id derived from it changes whenever the
+     * key rotates, so a consumer still passing it should resolve the userId and
+     * pass that instead.
+     */
+    friendKey?: string | null;
+    /**
+     * A stable-but-unproven browser id. CLIENT-ASSERTED, so `device` is NOT an
+     * authorization boundary — gate power on `isAuthenticatedTier`, never on
+     * `isDurableParticipantId`.
+     */
+    deviceId?: string | null;
+    /** Fallback for a connection nobody can name. Dies with the transport. */
+    socketId: string;
+}
+export interface DerivedParticipant {
+    id: ParticipantId;
+    tier: ParticipantIdTier;
+}
+export type ParticipantIdDeriver = (input: DeriveParticipantInput) => DerivedParticipant;
+/**
+ * Bind a derivation to one app's domain.
+ *
+ * A FACTORY rather than a `(input, domain)` function so the domain is chosen
+ * once, at module scope, and no call site can mint a second identity space for
+ * the same person by passing a different string. The highest available tier
+ * wins: an account id (or, deprecated, a friend key) beats a device id beats
+ * the socket id; an account id beats a friend key. Account material present
+ * alongside a device id ignores the device id entirely —
+ * preferring the client-controlled input while authenticated is the one
+ * combination that lets somebody hold two identities at once.
+ */
+export declare function createParticipantIdDeriver(domain: string): ParticipantIdDeriver;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,iBAAiB,EAKvB,MAAM,wBAAwB,CAAC;AA6ChC,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,aAAa,CAAC;IAClB,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,sBAAsB,KAAK,kBAAkB,CAAC;AASzF;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAwB/E"}

package/dist/identity.js

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { formatParticipantId, isUsableAccountId, resolveParticipantTier, PARTICIPANT_ID_DIGEST_LENGTH, } from '@wolffm/rooms-protocol';
+/**
+ * Participant identity — the DERIVATION half.
+ *
+ * `@wolffm/rooms-protocol` owns the FORMAT (the prefixes, the tier gates, the
+ * digest length) and stops there, because it is zero-dependency and isomorphic:
+ * hashing needs a synchronous primitive, `node:crypto` is absent in a browser
+ * bundle, and Web Crypto's digest is async. This package is server-only, so the
+ * hash lives here.
+ *
+ * It lives here rather than in each app because it had already been written
+ * twice — watchparty's `rooms/participantId.ts` and hadoku_site's
+ * `templates/game` `identity.ts` — with two different separation schemes for
+ * one security property. The second copy is where the property quietly stops
+ * holding.
+ *
+ * ## The DOMAIN is the app's, and it is required
+ *
+ * Ids minted under one domain agree only with ids minted under that domain, so
+ * two hadoku apps hashing the same friend key produce unrelated participants.
+ * That is deliberate: a room in one app must not be able to assert a person's
+ * identity in another, and an app that leaks its ids does not leak everyone
+ * else's. VERSION the string (`hadoku.<app>.participant.v1`) so changing the
+ * scheme is a visible re-identification rather than a silent one.
+ *
+ * ## Per-TIER separation is enforced here, not by the caller
+ *
+ * The tier is hashed in alongside the domain. Without it, a client that learned
+ * any friend key could present it as its DEVICE id and land on that
+ * authenticated participant's identity — collapsing the tier distinction the
+ * whole scheme rests on, silently. An earlier version left this to the caller
+ * by asking for two domain strings; a caller that passed the same string twice
+ * got a working system with the property removed, and nothing said so.
+ *
+ * ## What comes out is safe to log, ship and show
+ *
+ * The friend key IS the credential and never leaves this module. The body of an
+ * `fk:`/`dev:` id is a truncated SHA-256 of it, which cannot be reversed — see
+ * `participantHandle` in rooms-protocol for the part you may show a room.
+ */
+/** Separator: U+001F cannot appear in a header value, so fields cannot run together. */
+const SEP = '\u001f';
+function digest(domain, tier, material) {
+    return createHash('sha256')
+        .update(`${domain}${SEP}${tier}${SEP}${material}`, 'utf8')
+        .digest('hex')
+        .slice(0, PARTICIPANT_ID_DIGEST_LENGTH);
+}
+/**
+ * Bind a derivation to one app's domain.
+ *
+ * A FACTORY rather than a `(input, domain)` function so the domain is chosen
+ * once, at module scope, and no call site can mint a second identity space for
+ * the same person by passing a different string. The highest available tier
+ * wins: an account id (or, deprecated, a friend key) beats a device id beats
+ * the socket id; an account id beats a friend key. Account material present
+ * alongside a device id ignores the device id entirely —
+ * preferring the client-controlled input while authenticated is the one
+ * combination that lets somebody hold two identities at once.
+ */
+export function createParticipantIdDeriver(domain) {
+    if (!domain)
+        throw new Error('participant id domain is required');
+    return (input) => {
+        const tier = resolveParticipantTier(input);
+        switch (tier) {
+            case 'account':
+                // The material is LABELLED so a userId and a credential can never
+                // digest to the same body, whatever their values.
+                return {
+                    id: formatParticipantId(tier, isUsableAccountId(input.accountId)
+                        ? digest(domain, tier, `uid${SEP}${input.accountId}`)
+                        : digest(domain, tier, input.friendKey)),
+                    tier,
+                };
+            case 'device':
+                return { id: formatParticipantId(tier, digest(domain, tier, input.deviceId)), tier };
+            case 'ephemeral':
+                // NOT hashed: a socket id is already a public, server-minted, opaque
+                // handle every client in the room sees, and it dies with the transport.
+                // Hashing it would cost a round of guessing for nothing and make logs
+                // harder to correlate with engine.io's own.
+                return { id: formatParticipantId(tier, input.socketId), tier };
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @wolffm/rooms-server — room mechanics for a socket.io server.
+ *
+ * Room lifecycle and membership, stable participant identity, seating, avatar
+ * claims, name persistence across reconnect, backpressure-aware emit, per-key
+ * rate limiting, and idle/empty reaping.
+ *
+ * Carries no hosting-app vocabulary and no opinion about what a room is FOR —
+ * that lives in `CoreRoomState<TApp>`'s `app`. Three things a hosting app
+ * supplies rather than inherits: the avatar pool (`claimAvatar`), the emit
+ * priority classes (`EmitPolicy`), and its own logging/metrics via the policy
+ * callbacks. Each was hardcoded in the code this was extracted from, and each
+ * would have been a wrong answer for the second consumer.
+ */
+export * from './state.js';
+export * from './identity.js';
+export * from './emit.js';
+export * from './gc.js';
+export * from './rateLimiter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @wolffm/rooms-server — room mechanics for a socket.io server.
+ *
+ * Room lifecycle and membership, stable participant identity, seating, avatar
+ * claims, name persistence across reconnect, backpressure-aware emit, per-key
+ * rate limiting, and idle/empty reaping.
+ *
+ * Carries no hosting-app vocabulary and no opinion about what a room is FOR —
+ * that lives in `CoreRoomState<TApp>`'s `app`. Three things a hosting app
+ * supplies rather than inherits: the avatar pool (`claimAvatar`), the emit
+ * priority classes (`EmitPolicy`), and its own logging/metrics via the policy
+ * callbacks. Each was hardcoded in the code this was extracted from, and each
+ * would have been a wrong answer for the second consumer.
+ */
+export * from './state.js';
+export * from './identity.js';
+export * from './emit.js';
+export * from './gc.js';
+export * from './rateLimiter.js';
+// NOT `export * from '@wolffm/rooms-protocol'`. Re-exporting it would give
+// every symbol two import paths, and the first thing that drifts is which one
+// a file happens to use. Consumers depend on both packages explicitly.

package/dist/rateLimiter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Token-bucket rate limiting, per key.
+ *
+ * The limits themselves are NOT here — a hosting app picks its own capacities
+ * and windows (watchparty has four: control, seek, chat, game). This module is
+ * only the mechanism.
+ */
+export interface RateLimitConfig {
+    capacity: number;
+    refillAmount: number;
+    refillIntervalMs: number;
+}
+export declare class MultiRateLimiter<K = string> {
+    private cfg;
+    private buckets;
+    constructor(cfg: RateLimitConfig);
+    /** Remove this limiter from the sweep registry (call on socket disconnect). */
+    deregister(): void;
+    allow(key: K, tokens?: number, now?: number): boolean;
+    remaining(key: K): number;
+    /** Remove buckets not accessed within maxAgeMs. */
+    prune(maxAgeMs: number, now?: number): number;
+}
+/** Prune stale buckets from every live MultiRateLimiter. */
+export declare function pruneAllLimiters(maxAgeMs: number): number;
+//# sourceMappingURL=rateLimiter.d.ts.map

package/dist/rateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.d.ts","sourceRoot":"","sources":["../src/rateLimiter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAkDD,qBAAa,gBAAgB,CAAC,CAAC,GAAG,MAAM;IAE1B,OAAO,CAAC,GAAG;IADvB,OAAO,CAAC,OAAO,CAAgC;gBAC3B,GAAG,EAAE,eAAe;IAIxC,+EAA+E;IAC/E,UAAU,IAAI,IAAI;IAKlB,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,GAAE,MAAU,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO;IAWpE,SAAS,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM;IAMzB,mDAAmD;IACnD,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM;CAU1D;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOzD"}

package/dist/rateLimiter.js

@@ -0,0 +1,95 @@
+/**
+ * Token-bucket rate limiting, per key.
+ *
+ * The limits themselves are NOT here — a hosting app picks its own capacities
+ * and windows (watchparty has four: control, seek, chat, game). This module is
+ * only the mechanism.
+ */
+class TokenBucket {
+    config;
+    state;
+    constructor(config, now = Date.now()) {
+        this.config = config;
+        this.state = { tokens: config.capacity, lastRefill: now };
+    }
+    tryRemove(tokens = 1, now = Date.now()) {
+        this.refill(now);
+        if (this.state.tokens >= tokens) {
+            this.state.tokens -= tokens;
+            return true;
+        }
+        return false;
+    }
+    refill(now) {
+        const { refillIntervalMs, refillAmount, capacity } = this.config;
+        if (now <= this.state.lastRefill)
+            return;
+        const elapsed = now - this.state.lastRefill;
+        if (elapsed < refillIntervalMs)
+            return;
+        const intervals = Math.floor(elapsed / refillIntervalMs);
+        if (intervals <= 0)
+            return;
+        this.state.tokens = Math.min(capacity, this.state.tokens + intervals * refillAmount);
+        this.state.lastRefill += intervals * refillIntervalMs;
+    }
+    get remaining() {
+        this.refill(Date.now());
+        return this.state.tokens;
+    }
+}
+// Registry of live limiters, so a periodic sweep can prune every one's stale
+// buckets without the caller tracking them. `deregister()` on disconnect is
+// what keeps this from being a leak.
+const allLimiters = [];
+export class MultiRateLimiter {
+    cfg;
+    buckets = new Map();
+    constructor(cfg) {
+        this.cfg = cfg;
+        allLimiters.push(this);
+    }
+    /** Remove this limiter from the sweep registry (call on socket disconnect). */
+    deregister() {
+        const idx = allLimiters.indexOf(this);
+        if (idx !== -1)
+            allLimiters.splice(idx, 1);
+    }
+    allow(key, tokens = 1, now = Date.now()) {
+        let entry = this.buckets.get(key);
+        if (!entry) {
+            entry = { key, bucket: new TokenBucket(this.cfg, now), lastAccessed: now };
+            this.buckets.set(key, entry);
+        }
+        else {
+            entry.lastAccessed = now;
+        }
+        return entry.bucket.tryRemove(tokens, now);
+    }
+    remaining(key) {
+        const entry = this.buckets.get(key);
+        if (!entry)
+            return this.cfg.capacity;
+        return entry.bucket.remaining;
+    }
+    /** Remove buckets not accessed within maxAgeMs. */
+    prune(maxAgeMs, now = Date.now()) {
+        let pruned = 0;
+        for (const [key, entry] of this.buckets) {
+            if (now - entry.lastAccessed >= maxAgeMs) {
+                this.buckets.delete(key);
+                pruned++;
+            }
+        }
+        return pruned;
+    }
+}
+/** Prune stale buckets from every live MultiRateLimiter. */
+export function pruneAllLimiters(maxAgeMs) {
+    const now = Date.now();
+    let total = 0;
+    for (const limiter of allLimiters) {
+        total += limiter.prune(maxAgeMs, now);
+    }
+    return total;
+}

package/dist/state.d.ts

@@ -0,0 +1,186 @@
+import { type ParticipantId, type ParticipantIdTier, type SeatTable } from '@wolffm/rooms-protocol';
+/** Builds the seat table for one room. See `RoomRegistry`'s constructor. */
+export type SeatTableFactory = () => SeatTable;
+/**
+ * Room state and membership, generic over the hosting app's own state.
+ *
+ * Everything here is true of ANY room. Anything specific to what the room is
+ * FOR belongs in `TApp` — see `CoreRoomState.app`.
+ */
+export interface ClientMeta<TClient = unknown> {
+    /** Ephemeral per-connection id. In practice the socket id. */
+    clientId: string;
+    socketId: string;
+    /**
+     * Stable identity of the PERSON, surviving reconnect. Unlike `clientId` this
+     * is durable at the account and device tiers — see rooms-protocol's
+     * participantId.ts for the tier contract, and why `device` is not an
+     * authorization boundary.
+     */
+    participantId: ParticipantId;
+    joinedAt: number;
+    /** Presence heartbeat timestamp (ms). */
+    lastSeen: number;
+    name?: string;
+    /**
+     * Chosen avatar, from a pool the HOSTING APP supplies (`claimAvatar`). The
+     * pool is not a room concept — watchparty's is a list of character sprites,
+     * and baking that vocabulary in here is exactly what this package must not do.
+     */
+    avatarId?: string;
+    /**
+     * Authenticated credential for this connection, when there is one. Server-
+     * internal: it IS the auth material, so it must never reach a payload.
+     */
+    friendKey?: string;
+    /**
+     * The platform account id (registry `userId`) this connection resolved to,
+     * when it resolved to one. The identity anything DURABLE about this person
+     * keys on — stats, ballots, ownership — because unlike `friendKey` it
+     * survives key rotation. Server-resolved; never taken from a payload.
+     */
+    accountId?: string;
+    /**
+     * The hosting app's own per-client data, the same split as
+     * `CoreRoomState.app`. Watchparty keeps its key type, room key and health
+     * telemetry here; a card game would keep whatever it needs.
+     *
+     * Generic rather than `unknown` so an app reads its own fields without a
+     * cast, and rather than absent so the package never grows a field like
+     * `keyType: 'viewer' | 'leader'` — which is app vocabulary wearing a
+     * room-shaped name.
+     */
+    app: TClient;
+}
+export interface CoreRoomState<TApp, TClient = unknown> {
+    roomId: string;
+    /** Provided at join (auth). Not broadcast. */
+    roomKey: string;
+    /** The room's authority, by clientId, or null. */
+    leaderId: string | null;
+    /** Monotonic sequence for outbound events. */
+    lastEventSeq: number;
+    createdAt: number;
+    updatedAt: number;
+    /** clientId -> meta. Keyed by the EPHEMERAL id; see `clientByParticipant`. */
+    clients: Map<string, ClientMeta<TClient>>;
+    /** Avatars currently claimed by connected clients. */
+    usedAvatars: Set<string>;
+    /**
+     * ParticipantId -> custom name. Durable tiers survive a reconnect; the
+     * ephemeral tier does not, and is dropped on leave.
+     */
+    clientNames: Map<ParticipantId, string>;
+    /** Who is in the room and in what ORDER — see rooms-protocol's seats.ts. */
+    seats: SeatTable;
+    /** The hosting app's own state. */
+    app: TApp;
+}
+/**
+ * A set of rooms.
+ *
+ * A CLASS rather than the module-level `const rooms = new Map()` this was
+ * extracted from. In an application a module singleton is merely implicit; in a
+ * library it means two consumers in one process silently share a room table.
+ * A hosting app that wants one registry holds one instance — same behaviour,
+ * stated rather than assumed.
+ */
+export declare class RoomRegistry<TApp, TClient = unknown> {
+    private createApp;
+    private createSeats;
+    private rooms;
+    private onDelete;
+    /**
+     * @param createApp      the room's own app state, per room.
+     * @param createSeats    the room's seat table, per room. Defaults to
+     *   unbounded with no reservations, which is right for a room with no slot
+     *   limit (watching video) and wrong for almost any game.
+     *
+     * A FACTORY, not a table: one `SeatTable` shared across rooms would seat
+     * every player in every room. And a parameter rather than a hardcoded
+     * `createSeatTable(null)`, because capacity and seat-hold are product
+     * decisions this package has no business making — hardcoding them made the
+     * first consumer reach in and overwrite `room.seats` immediately after
+     * `seed`, which is two owners of one field and the shape of a race the day
+     * something else reads it in between.
+     */
+    constructor(createApp: (now: number) => TApp, createSeats?: SeatTableFactory);
+    /**
+     * Create a room deterministically. Returns the existing one if present.
+     *
+     * `createSeats` overrides the registry's default for THIS room — a pod size
+     * that varies per room is a normal thing for a game to want, and it must be
+     * settable at creation rather than patched afterwards.
+     */
+    seed(roomId: string, roomKey: string, createSeats?: SeatTableFactory): CoreRoomState<TApp, TClient>;
+    get(roomId: string): CoreRoomState<TApp, TClient> | undefined;
+    findByKey(roomKey: string): CoreRoomState<TApp, TClient> | undefined;
+    all(): Array<CoreRoomState<TApp, TClient>>;
+    get size(): number;
+    /** Register a callback for room deletion (cleanup of app-side caches). */
+    onRoomDelete(cb: (roomId: string) => void): void;
+    delete(roomId: string): void;
+}
+export declare function joinRoom<TApp, TClient>(room: CoreRoomState<TApp, TClient>, clientId: string, socketId: string, participantId: ParticipantId, createClientApp: () => TClient): ClientMeta<TClient>;
+/**
+ * Remove ONE CONNECTION from a room.
+ *
+ * A connection, not a person — and the difference is the whole of the ordering
+ * below. `clients` is keyed by the ephemeral client id, so one participant can
+ * hold several entries at once: a second tab, or a stale socket whose close
+ * lands AFTER its replacement has already joined. Both are routine.
+ *
+ * **The seat is given up only when this was the person's LAST connection**, and
+ * the delete therefore happens FIRST so that question can be asked honestly.
+ * Unseating unconditionally takes the seat from a player who is sitting right
+ * there on a live connection — and on a reconnect race it does so *after* the
+ * new connection re-seated them, so the repair is invisible to the code that
+ * caused it. The first consumer to build a game on this package found it and
+ * wrapped every call in a guard that re-seats the participant afterwards; that
+ * guard belongs here, once, not in each consumer.
+ *
+ * The avatar is released on every close regardless, because it is claimed per
+ * CONNECTION (`ClientMeta.avatarId`), not per participant.
+ */
+export declare function leaveRoom<TApp, TClient>(room: CoreRoomState<TApp, TClient>, clientId: string): void;
+/**
+ * The live client for a participant, or undefined when not connected.
+ *
+ * `clients` is keyed by the ephemeral id, so this is the reverse lookup from
+ * the stable identity a seat holds back to the current connection. Linear,
+ * which is fine at room scale and keeps a second index from drifting.
+ */
+export declare function clientByParticipant<TApp, TClient>(room: CoreRoomState<TApp, TClient>, participantId: ParticipantId): ClientMeta<TClient> | undefined;
+/** Claim an avatar. False when it is not in the pool, or already taken. */
+export declare function claimAvatar<TApp, TClient>(room: CoreRoomState<TApp, TClient>, avatarId: string, pool: readonly string[]): boolean;
+/** Release an avatar back to the pool. Idempotent. */
+export declare function releaseAvatar<TApp, TClient>(room: CoreRoomState<TApp, TClient>, avatarId: string | undefined): void;
+/** Unclaimed avatars, in pool order. */
+export declare function availableAvatars<TApp, TClient>(room: CoreRoomState<TApp, TClient>, pool: readonly string[]): string[];
+/** Claimed avatars, in pool order. */
+export declare function usedAvatars<TApp, TClient>(room: CoreRoomState<TApp, TClient>, pool: readonly string[]): string[];
+export type IdentitySource = 'client-sent' | 'restored' | 'none';
+export interface IdentityResolution {
+    /** The name to apply, if any. */
+    name?: string;
+    /** How `name` was determined (or 'none' if the caller assigns a default). */
+    source: IdentitySource;
+    /** Durability of the identity it was persisted under. Callers log this. */
+    tier: ParticipantIdTier | null;
+}
+/**
+ * Resolve (and persist) a client's name on join. A pure decision over the
+ * room's name store, so it is testable without a live socket. Priority:
+ *   1. A client-sent name is authoritative — apply and persist it.
+ *   2. Otherwise restore whatever this participant was called last time.
+ *   3. Otherwise 'none' (the caller assigns a default).
+ *
+ * Callers MUST log the returned resolution, so a restore that silently did NOT
+ * happen can never read as a success.
+ */
+export declare function resolveJoinName<TApp, TClient>(room: CoreRoomState<TApp, TClient>, participantId: ParticipantId, sentName: string | undefined): IdentityResolution;
+/** Store a custom name against a participant identity. */
+export declare function setClientName<TApp, TClient>(room: CoreRoomState<TApp, TClient>, participantId: ParticipantId, name: string): void;
+/** A participant's stored custom name, if any. */
+export declare function getClientName<TApp, TClient>(room: CoreRoomState<TApp, TClient>, participantId: ParticipantId): string | undefined;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

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

package/dist/state.js

@@ -0,0 +1,221 @@
+import { participantIdTier, isDurableParticipantId, createSeatTable, seatParticipant, unseatParticipant, } from '@wolffm/rooms-protocol';
+/**
+ * A set of rooms.
+ *
+ * A CLASS rather than the module-level `const rooms = new Map()` this was
+ * extracted from. In an application a module singleton is merely implicit; in a
+ * library it means two consumers in one process silently share a room table.
+ * A hosting app that wants one registry holds one instance — same behaviour,
+ * stated rather than assumed.
+ */
+export class RoomRegistry {
+    createApp;
+    createSeats;
+    rooms = new Map();
+    onDelete = [];
+    /**
+     * @param createApp      the room's own app state, per room.
+     * @param createSeats    the room's seat table, per room. Defaults to
+     *   unbounded with no reservations, which is right for a room with no slot
+     *   limit (watching video) and wrong for almost any game.
+     *
+     * A FACTORY, not a table: one `SeatTable` shared across rooms would seat
+     * every player in every room. And a parameter rather than a hardcoded
+     * `createSeatTable(null)`, because capacity and seat-hold are product
+     * decisions this package has no business making — hardcoding them made the
+     * first consumer reach in and overwrite `room.seats` immediately after
+     * `seed`, which is two owners of one field and the shape of a race the day
+     * something else reads it in between.
+     */
+    constructor(createApp, createSeats = () => createSeatTable(null)) {
+        this.createApp = createApp;
+        this.createSeats = createSeats;
+    }
+    /**
+     * Create a room deterministically. Returns the existing one if present.
+     *
+     * `createSeats` overrides the registry's default for THIS room — a pod size
+     * that varies per room is a normal thing for a game to want, and it must be
+     * settable at creation rather than patched afterwards.
+     */
+    seed(roomId, roomKey, createSeats = this.createSeats) {
+        const existing = this.rooms.get(roomId);
+        if (existing)
+            return existing;
+        const now = Date.now();
+        const state = {
+            roomId,
+            roomKey,
+            leaderId: null,
+            lastEventSeq: 0,
+            createdAt: now,
+            updatedAt: now,
+            clients: new Map(),
+            usedAvatars: new Set(),
+            clientNames: new Map(),
+            seats: createSeats(),
+            app: this.createApp(now),
+        };
+        this.rooms.set(roomId, state);
+        return state;
+    }
+    get(roomId) {
+        return this.rooms.get(roomId);
+    }
+    findByKey(roomKey) {
+        for (const r of this.rooms.values()) {
+            if (r.roomKey === roomKey)
+                return r;
+        }
+        return undefined;
+    }
+    all() {
+        return Array.from(this.rooms.values());
+    }
+    get size() {
+        return this.rooms.size;
+    }
+    /** Register a callback for room deletion (cleanup of app-side caches). */
+    onRoomDelete(cb) {
+        this.onDelete.push(cb);
+    }
+    delete(roomId) {
+        for (const cb of this.onDelete)
+            cb(roomId);
+        this.rooms.delete(roomId);
+    }
+}
+// ── Membership ──────────────────────────────────────────────────────────────
+export function joinRoom(room, clientId, socketId, participantId, createClientApp) {
+    const meta = {
+        clientId,
+        socketId,
+        participantId,
+        joinedAt: Date.now(),
+        lastSeen: Date.now(),
+        app: createClientApp(),
+    };
+    room.clients.set(clientId, meta);
+    // Seat them, reclaiming the seat this participant last held. Returns null
+    // only when a bounded table is full of people, in which case they are a
+    // spectator — `roleOf` reads the table rather than a stored flag.
+    seatParticipant(room.seats, participantId);
+    room.updatedAt = Date.now();
+    return meta;
+}
+/**
+ * Remove ONE CONNECTION from a room.
+ *
+ * A connection, not a person — and the difference is the whole of the ordering
+ * below. `clients` is keyed by the ephemeral client id, so one participant can
+ * hold several entries at once: a second tab, or a stale socket whose close
+ * lands AFTER its replacement has already joined. Both are routine.
+ *
+ * **The seat is given up only when this was the person's LAST connection**, and
+ * the delete therefore happens FIRST so that question can be asked honestly.
+ * Unseating unconditionally takes the seat from a player who is sitting right
+ * there on a live connection — and on a reconnect race it does so *after* the
+ * new connection re-seated them, so the repair is invisible to the code that
+ * caused it. The first consumer to build a game on this package found it and
+ * wrapped every call in a guard that re-seats the participant afterwards; that
+ * guard belongs here, once, not in each consumer.
+ *
+ * The avatar is released on every close regardless, because it is claimed per
+ * CONNECTION (`ClientMeta.avatarId`), not per participant.
+ */
+export function leaveRoom(room, clientId) {
+    const meta = room.clients.get(clientId);
+    room.clients.delete(clientId);
+    if (meta) {
+        // Guarantee the avatar returns to the pool on EVERY leave path, not just
+        // the disconnect handler. Idempotent, so a caller that already released is
+        // harmless.
+        releaseAvatar(room, meta.avatarId);
+        // Drop the name only for an EPHEMERAL identity — that id is the socket id,
+        // so it can never be matched again after reconnect, and keeping it would
+        // leak one entry per connection for the life of the room. A DURABLE
+        // identity keeps its name so a reconnect restores it.
+        if (!isDurableParticipantId(meta.participantId)) {
+            room.clientNames.delete(meta.participantId);
+        }
+        // Release the seat but REMEMBER it, so a reconnect reclaims the same place
+        // instead of being appended after everyone who stayed — and only once
+        // nothing else is carrying this identity. See the header.
+        if (clientByParticipant(room, meta.participantId) === undefined) {
+            unseatParticipant(room.seats, meta.participantId);
+        }
+    }
+    room.updatedAt = Date.now();
+}
+/**
+ * The live client for a participant, or undefined when not connected.
+ *
+ * `clients` is keyed by the ephemeral id, so this is the reverse lookup from
+ * the stable identity a seat holds back to the current connection. Linear,
+ * which is fine at room scale and keeps a second index from drifting.
+ */
+export function clientByParticipant(room, participantId) {
+    for (const meta of room.clients.values()) {
+        if (meta.participantId === participantId)
+            return meta;
+    }
+    return undefined;
+}
+// ── Avatars ─────────────────────────────────────────────────────────────────
+//
+// The POOL is the hosting app's, passed in at each call. That is deliberate:
+// an avatar list is app content (watchparty's is a set of character sprites),
+// and a package that owned it would be asserting what rooms look like.
+/** Claim an avatar. False when it is not in the pool, or already taken. */
+export function claimAvatar(room, avatarId, pool) {
+    if (!pool.includes(avatarId))
+        return false;
+    if (room.usedAvatars.has(avatarId))
+        return false;
+    room.usedAvatars.add(avatarId);
+    return true;
+}
+/** Release an avatar back to the pool. Idempotent. */
+export function releaseAvatar(room, avatarId) {
+    if (!avatarId)
+        return;
+    room.usedAvatars.delete(avatarId);
+}
+/** Unclaimed avatars, in pool order. */
+export function availableAvatars(room, pool) {
+    return pool.filter((a) => !room.usedAvatars.has(a));
+}
+/** Claimed avatars, in pool order. */
+export function usedAvatars(room, pool) {
+    return pool.filter((a) => room.usedAvatars.has(a));
+}
+/**
+ * Resolve (and persist) a client's name on join. A pure decision over the
+ * room's name store, so it is testable without a live socket. Priority:
+ *   1. A client-sent name is authoritative — apply and persist it.
+ *   2. Otherwise restore whatever this participant was called last time.
+ *   3. Otherwise 'none' (the caller assigns a default).
+ *
+ * Callers MUST log the returned resolution, so a restore that silently did NOT
+ * happen can never read as a success.
+ */
+export function resolveJoinName(room, participantId, sentName) {
+    const tier = participantIdTier(participantId);
+    if (sentName) {
+        room.clientNames.set(participantId, sentName);
+        return { name: sentName, source: 'client-sent', tier };
+    }
+    const restored = room.clientNames.get(participantId);
+    if (restored !== undefined) {
+        return { name: restored, source: 'restored', tier };
+    }
+    return { source: 'none', tier };
+}
+/** Store a custom name against a participant identity. */
+export function setClientName(room, participantId, name) {
+    room.clientNames.set(participantId, name);
+}
+/** A participant's stored custom name, if any. */
+export function getClientName(room, participantId) {
+    return room.clientNames.get(participantId);
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@hadoku/rooms-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.43.15",
+  "type": "module",
+  "license": "MIT",
+  "description": "Room lifecycle, membership, seating, identity and backpressure-aware emit for a socket.io server.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WolffM/hadoku-watchparty.git",
+    "directory": "packages/rooms-server"
+  },
+  "dependencies": {
+    "@wolffm/rooms-protocol": "npm:@hadoku/rooms-protocol@0.43.15"
+  },
+  "peerDependencies": {
+    "socket.io": "^4.8.3"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.