@irtio/client 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { AnySchema, PlainState, CollectionDesc, Delta, EntityCollection, PhysicsBodyChannel, ReadonlyCollection, RoleOf, VisibleKeys, SchemaDefs, EntityDef, DeepReadonly, InferFields, Owned, SingletonDef, ClientImplementations, ClientRpcs, SchemaRpc, MessageChannels, ClientCallProxy } from '@irtio/schema';
+import { AnySchema, PlainState, CollectionDesc, Delta, EntityCollection, PhysicsBodyChannel, ClientImplementations, ClientRpcs, SchemaRpc, RoleOf, VisibleKeys, SchemaDefs, EntityDef, ReadonlyCollection, DeepReadonly, InferFields, Owned, SingletonDef, ClientCallProxy, MessageChannels } from '@irtio/schema';
 import * as _irtio_protocol from '@irtio/protocol';
 import { PresenceRecord, ProfileLedger, ProfileSnapshot } from '@irtio/protocol';
+import RAPIER2D from '@dimforge/rapier2d-compat';
 import * as MATTER from 'matter-js';
 import RAPIER from '@dimforge/rapier3d-compat';
 
@@ -51,6 +52,8 @@ interface CorrectionOp {
     /** `true` when the correction outran the resim window and everything it named snapped. */
     readonly snapped: boolean;
 }
+/** A row appeared (`onAdd`) or disappeared (`onRemove`) in one entity collection. */
+type EntityCallback = (id: string, row: unknown) => void;
 declare class ClientStore {
     /** D50: not `readonly` — a schema swap replaces it in place (`swapSchema`). */
     ext: AnySchema;
@@ -60,6 +63,13 @@ declare class ClientStore {
     private tracked;
     private readonly descs;
     private readonly frozen;
+    /**
+     * Per-collection add/remove subscribers (`room.onAdd` / `room.onRemove`). Kept here rather than
+     * in the session because this is the only place that sees a frame's ops against the state the
+     * frame is about to change: a removed row's last values exist for exactly as long as it takes
+     * `applyDelta` to run.
+     */
+    private readonly entityListeners;
     /** Live collection facades by name, so a D50 swap can retarget rather than replace them. */
     private readonly facades;
     /** The object handed out as `room.state`; identity survives a resync. */
@@ -123,6 +133,28 @@ declare class ClientStore {
     private freeze;
     private entityHint;
     private singletonHint;
+    private listenersFor;
+    /**
+     * Subscribes to rows appearing in one entity collection. Rows that are **already present** are
+     * announced synchronously as the subscription is made — the join snapshot has usually landed
+     * before user code runs, and a listener that had to reconcile the initial set by hand would
+     * make the event useless for exactly the case (a spawn effect) it exists for.
+     */
+    onEntityAdd(name: string, cb: EntityCallback): () => void;
+    /** Subscribes to rows disappearing from one entity collection (never fires for past removals). */
+    onEntityRemove(name: string, cb: EntityCallback): () => void;
+    private emitAdd;
+    private emitRemove;
+    /**
+     * The adds and removes a delta is about to make, captured against the state as it stands now:
+     * a remove's last values are only readable before `applyDelta` drops the row.
+     */
+    private captureOps;
+    private flushOps;
+    /** Fires adds and removes for the difference a wholesale snapshot load made. */
+    private emitSnapshotDiff;
+    /** The rows every subscribed collection holds right now, for the snapshot diff. */
+    private captureRows;
     /**
      * Applies a server `DELTA`. Update ops for instances this client owns are dropped field-wise
      * (server wins only through `CORRECT`); adds, removes and owner changes always apply.
@@ -345,8 +377,21 @@ interface PredictionStats {
     resimSteps: number;
     /** Rebase passes (one per authoritative arrival batch). */
     rebases: number;
-    /** Rebases whose lead outran the resim depth: the body snapped to authority. */
+    /**
+     * Rebases that rendered every body at authority. Since bugs.md #71 an outrun lead clamps
+     * instead of snapping (`leadClamped`), so nothing increments this today; the field stays
+     * because a zero here is a fence several suites hold, and a future hard-snap path would count
+     * here again.
+     */
     snaps: number;
+    /**
+     * Rebases whose lead outran `MAX_LEAD` and were re-stepped that many ticks instead (bugs.md
+     * #71). The local character still answers input; the anchor sits closer to authority than the
+     * round trip wants, so releases overshoot by the difference. A value that climbs and keeps
+     * climbing means the measured rtt is past the cap's horizon (667 ms at 60 Hz) — degraded
+     * prediction, where a snap would have been none.
+     */
+    leadClamped: number;
     /** Corrections whose values matched the local prediction within epsilon. */
     suppressed: number;
     /**
@@ -788,8 +833,8 @@ declare class Predictor {
      * written, so plain state holds exactly what the server said), then re-step the world by the
      * client's lead, applying to each re-stepped tick the intent that was in force *at that tick*:
      * the newest buffered unjudged write stamped at or before it, or the baseline (the newest
-     * judged write) before the first of them. Bounded by `MAX_LEAD`: an outrun lead snaps to
-     * authority and counts (`stats.snaps`).
+     * judged write) before the first of them. Bounded by `MAX_LEAD`: an outrun lead re-steps that
+     * many and counts (`stats.leadClamped`, bugs.md #71).
      */
     private rebase;
     /**
@@ -826,6 +871,126 @@ declare class Predictor {
     private isF32;
 }
 
+/**
+ * The rapier2d half of client-side physics prediction: `joinRoom({ physics2d: { engine:
+ * 'rapier2d', … } })`'s option type, the lazy `@dimforge/rapier2d-compat` load, and the adapter
+ * that is the only place in the client where a rapier2d type is touched.
+ *
+ * The loop is `predictor.ts`, shared byte for byte with the other two engines. This file is the
+ * seam list, and it is transcribed from `physics.ts` — the Rapier one — rather than from
+ * `physics2d.ts`, for the same reason `core/rapier2d.ts` is transcribed from `core/physics.ts`:
+ *
+ * - **The world applies gravity**, so there is no `settle` hook here and there must not be one.
+ *   `EngineAdapter.settle` exists for matter2d, whose engine gravity is usually zero and whose
+ *   rooms apply it per body; a rapier2d world that gained one would fall twice as fast on the
+ *   client and be corrected every tick.
+ * - **Velocities are per second**, so `velocityTolerance` is `epsilon / dt`, the 3D answer, not
+ *   matter's per-step one.
+ * - **The step is `world.step()`** against a `world.timestep` fixed once at start.
+ *
+ * What it takes from the 2D side is only the plane: `{ x, y }` gravity, a scalar rotation and a
+ * scalar spin, mapped onto the thirteen 3D pose numbers through `@irtio/schema`'s `channelOf2d` /
+ * `applyChannel2d` / `angleFrom2d`. That mapping is written once, in the schema package, and this
+ * file reads it rather than restating it — a second copy is a way for the two sides to disagree
+ * by a sign.
+ *
+ * There is no planar-lock warning here (bug 6's friction trap needs a third axis to lock, and this
+ * engine has none), and the engine is loaded lazily, so a game predicting with matter2d or rapier3d
+ * never pulls the 2D WASM in.
+ */
+
+type ClientRapier2dModule = typeof RAPIER2D;
+type ClientRapier2dWorld = RAPIER2D.World;
+type ClientRapier2dBody = RAPIER2D.RigidBody;
+interface ClientVector2d {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * What a client-side rapier2d body factory returns — the same shape the room config's factories
+ * use (`Rapier2dBodySpec` in `@irtio/server`). Rapier bodies *have* colliders rather than being
+ * their geometry, which is the one structural difference from the matter2d spec.
+ */
+interface ClientRapier2dBodySpec {
+    readonly body: RAPIER2D.RigidBodyDesc;
+    readonly colliders?: readonly RAPIER2D.ColliderDesc[];
+}
+/**
+ * Method-syntax members check bivariantly, so a builder's factory or intent hook written against
+ * its own instance type (`(body, ball: Ball) => …`) is accepted — the values really passed are
+ * the schema's records for that collection.
+ */
+type ClientRapier2dBodyFactory = {
+    factory(rapier: ClientRapier2dModule, instance: AnyRecord$2, id: string): ClientRapier2dBodySpec;
+}['factory'];
+/**
+ * The client's half of `Rapier2dIntentHook`. Same five parameters in the same order as the server
+ * type, so one hook exported from a shared world module typechecks against both sides without a
+ * cast.
+ */
+type ClientRapier2dIntentHook = {
+    hook(body: ClientRapier2dBody, instance: AnyRecord$2, rapier: ClientRapier2dModule, world: ClientRapier2dWorld, timestep: number): void;
+}['hook'];
+/**
+ * `joinRoom({ physics2d: { engine: 'rapier2d', … } })` — the client half of the shared
+ * world-builder contract for a rapier2d room.
+ *
+ * It rides inside the `physics2d` option rather than beside it because it is the same *option*:
+ * a planar world, a planar gravity, one 2D engine. `engine` is the discriminant, and it is
+ * required here and optional (defaulting to `'matter2d'`) on the matter2d member, so every
+ * matter2d room written before this engine existed still compiles unchanged.
+ *
+ * There is no `settle`. See the module docblock.
+ */
+interface ClientRapier2dOptions {
+    /** The discriminant. Required: `physics2d` without one is a matter2d world. */
+    readonly engine: 'rapier2d';
+    /** Must equal the room config's gravity. Rapier's convention is y-up; nothing flips it. */
+    readonly gravity: ClientVector2d;
+    /** Seconds per step. Defaults to the room's tick interval (from `WELCOME`). */
+    readonly timestep?: number;
+    /** The shared static-geometry builder (the room's `physics.setup`). */
+    readonly setup?: (world: ClientRapier2dWorld, rapier: ClientRapier2dModule) => void;
+    /** Shape factories for the collections this client predicts (the room's `physics.bodies`). */
+    readonly bodies?: Readonly<Record<string, ClientRapier2dBodyFactory>>;
+    /**
+     * Intent → force, applied before every predicted step for bodies this client owns — the same
+     * function the room's `tick()` calls per instance, shared so both simulations agree.
+     */
+    readonly intents?: Readonly<Record<string, ClientRapier2dIntentHook>>;
+    /**
+     * D21 cap: how many **non-owned** predicted bodies this client simulates ahead. Default 64.
+     * Over-cap instances get a kinematic proxy instead (see `maxProxyBodies`), so a predicted body
+     * still stands on them. Counted as `stats.overCap`.
+     */
+    readonly maxPredictedBodies?: number;
+    /**
+     * D71 cap: how many **kinematic proxies** this client keeps. Default `MAX_PROXY_BODIES`. Past
+     * it, instances are absent from the local world and predicted bodies pass through them (warned,
+     * counted as `stats.absent`). See `ClientPhysicsOptions.maxProxyBodies` for why it is its own
+     * number.
+     */
+    readonly maxProxyBodies?: number;
+    /**
+     * A body-field correction whose every value is within this tolerance of the local prediction is
+     * *suppressed*: authority still applies, but it is not a misprediction. Positions compare
+     * against `epsilon` world units; velocity channels against `epsilon / timestep`, because a
+     * rapier2d velocity is per second. Default 0.05, which is sized for a metre-scale world.
+     */
+    readonly epsilon?: number;
+    /**
+     * How fast the drawn position eases back onto the simulation after a re-simulation moved it, as
+     * a half-life in milliseconds. `0` turns the smoothing off. Default 70. See
+     * `ClientPhysicsOptions.smoothingHalfLifeMs` for why this smooths the error and not the motion.
+     */
+    readonly smoothingHalfLifeMs?: number;
+    /**
+     * How far the drawn position may be held from the simulation while an offset eases away, in
+     * world units. Past it the offset is dropped and the body appears where it is. Default 4.
+     */
+    readonly smoothingSnapUnits?: number;
+}
+
 /**
  * The matter2d half of client-side physics prediction (D45, D57): `joinRoom({ physics2d })`'s
  * option type, the lazy `matter-js` load, and the adapter that is the only place in the client
@@ -900,6 +1065,11 @@ type ClientIntent2dHook = {
  * Every function here should be the very export the room config imports.
  */
 interface ClientPhysics2dOptions {
+    /**
+     * The `physics2d` discriminant. Optional and defaulting to `'matter2d'`, so every matter2d
+     * client written before rapier2d existed keeps compiling and keeps predicting with matter.
+     */
+    readonly engine?: 'matter2d';
     /** Must equal the room config's gravity, in matter's own convention (y is down). */
     readonly gravity: ClientVector2;
     /** Seconds per step. Defaults to the room's tick interval (from `WELCOME`). */
@@ -1314,6 +1484,12 @@ type ClientState<S, Role extends string = RoleOf<S> & string> = {
         serverOwned: true;
     } ? ClientCollection<DeepReadonly<InferFields<F>>> : ClientCollection<Owned<InferFields<F>>> : SchemaDefs<S>[K] extends SingletonDef<infer F, any> ? DeepReadonly<InferFields<F>> : never;
 };
+/** The entity-collection names visible to `Role` — the keys `room.onAdd`/`room.onRemove` take. */
+type EntityKeys<S, Role extends string = RoleOf<S> & string> = {
+    [K in keyof ClientState<S, Role>]: ClientState<S, Role>[K] extends ReadonlyCollection<any> ? K : never;
+}[keyof ClientState<S, Role>];
+/** The row type of one entity collection, as `room.state` hands it out. */
+type RowOf<S, Role extends string, K extends keyof ClientState<S, Role>> = ClientState<S, Role>[K] extends ReadonlyCollection<infer T> ? T : never;
 /** `connecting` → `starting`? → `connected` ⇄ `reconnecting` → `closed`. */
 type Status = 'connecting' | 'starting' | 'connected' | 'reconnecting' | 'closed';
 /**
@@ -1505,7 +1681,7 @@ interface JoinOptions<S, Role extends string = string> {
      * take different functions; passing both is an error at join. The wire carries no engine
      * name, so passing the one that does not match the room is a game bug the client cannot see.
      */
-    readonly physics2d?: ClientPhysics2dOptions;
+    readonly physics2d?: ClientPhysics2dOptions | ClientRapier2dOptions;
     /** @internal */
     readonly transport?: Transport;
     /** @internal */
@@ -1734,9 +1910,29 @@ interface Room<S, Role extends string = RoleOf<S> & string> {
     /** D70: this socket's message counters, including typed frames it could not read. */
     readonly stats: RoomStats;
     on<K extends keyof RoomEvents>(event: K, cb: (value: RoomEvents[K]) => void): Unsubscribe;
+    /**
+     * Fires when a row appears in one entity collection — a server-owned spawn, another client's
+     * entity, a resync that brought a row this client had not seen.
+     *
+     * Rows that are **already present** when you subscribe are announced synchronously, inside the
+     * `onAdd` call itself: the join snapshot has landed by the time `joinRoom` resolves, so a
+     * listener registered right after the join sees the whole initial set and then every later
+     * arrival, with no separate pass over `room.state`.
+     */
+    onAdd<K extends EntityKeys<S, Role>>(collection: K, cb: (id: string, row: RowOf<S, Role, K>) => void): Unsubscribe;
+    /**
+     * Fires when a row disappears from one entity collection, carrying its **last values** — the
+     * row itself is the death event, so a corpse stain or a score tick needs no parallel RPC. The
+     * row handed to the callback is read-only and is not in `room.state` any more.
+     */
+    onRemove<K extends EntityKeys<S, Role>>(collection: K, cb: (id: string, lastRow: RowOf<S, Role, K>) => void): Unsubscribe;
     /** Sends any pending owned writes immediately instead of at the next flush window. */
     flush(): void;
-    leave(): void;
+    /**
+     * Leaves for good. The returned promise resolves once the socket has closed (immediately if it
+     * was already closed), so a script can `await room.leave()` before exiting.
+     */
+    leave(): Promise<void>;
 }
 /**
  * What `joinRelay` returns: presence and the message channel, nothing else.
@@ -1766,7 +1962,8 @@ interface RelayRoom<S = never> {
     /** D70: this socket's message counters, including typed frames it could not read. */
     readonly stats: RoomStats;
     on<K extends keyof RoomEvents>(event: K, cb: (value: RoomEvents[K]) => void): Unsubscribe;
-    leave(): void;
+    /** Leaves for good; resolves once the socket has closed (immediately if it already had). */
+    leave(): Promise<void>;
 }
 
 /**
@@ -1934,6 +2131,230 @@ declare function matchRoom<S extends AnySchema, Role extends string = RoleOf<S>
 } & {
     readonly identity?: boolean;
 }): Promise<Room<S, Role>>;
+/** What a `mode: "public"` answer carries. */
+interface PublicTicket {
+    readonly room: string;
+    readonly queue: string;
+    /** How many players the queue this lobby belongs to seats. */
+    readonly size: number;
+    /** True when this caller minted the room rather than joining one somebody else was waiting in. */
+    readonly created: boolean;
+}
+/**
+ * Asks the control plane for a public room of `queue`: the oldest open one, or a fresh code.
+ *
+ * The lower half of {@link joinPublic}, exported because the element's chooser is driven by events
+ * rather than by a call, and an app that wires its own **Join a game** button may want the code
+ * without the join.
+ *
+ * `exclude` names a room this caller already failed to join, so the second answer is a different
+ * one. See `joinPublic` for when that happens.
+ */
+declare function findPublic(project: string, options?: Pick<MatchOptions, 'queue' | 'controlUrl' | 'fetch'> & {
+    readonly identity?: string;
+    readonly exclude?: string;
+}): Promise<PublicTicket>;
+/**
+ * Join a game: land in the next open public lobby, or open one and wait in it.
+ *
+ * ```ts
+ * const room = await joinPublic(schema);              // the default queue
+ * const room = await joinPublic(schema, { queue: '4p', identity: true });
+ * ```
+ *
+ * This is the other shape of matchmaking and it is deliberately not `matchRoom`. `matchRoom`
+ * holds a long poll until a whole party is there and answers `E_NO_MATCH` if one never is;
+ * `joinPublic` resolves on the first round trip and puts the player in a room that says "1/4
+ * players". Waiting in a lobby you can see is a different experience from waiting on a spinner,
+ * and it is the one a **Join a game** button should give.
+ *
+ * Nothing about the join differs from a friend sharing a link — the room neither knows nor cares
+ * that the registry sent you — which is the property every part of this feature is built on.
+ *
+ * **The one retry.** The registry answers from an occupancy reading a few seconds old, so the room
+ * may have filled on the way there. That is refused with `E_ROOM_FULL`, and the honest recovery is
+ * to ask once more, naming the room that did not work so the second answer cannot be the same one.
+ * Once, and never a loop: a retry that kept going would turn a busy game into a client that
+ * hammers control, and a second failure means something a third attempt will not fix.
+ */
+declare function joinPublic<S extends AnySchema, Role extends string = RoleOf<S> & string>(schema: S, options?: Pick<MatchOptions, 'queue' | 'controlUrl' | 'fetch'> & JoinOptions<S, Role> & {
+    role?: RoleOf<S> & string;
+} & {
+    readonly identity?: boolean;
+}): Promise<Room<S, Role>>;
+
+/**
+ * D75 (M6 lane H): the client's half of the lobby, and the glue that wires `<irt-lobby>` up.
+ *
+ * Two exports and a clean division between them.
+ *
+ * `lobbyOf(room)` is the **view**: it reads the lobby fragment out of ordinary room state and
+ * answers the structural shape `@irtio/lobby`'s `AttachableRoom.lobby` asks for. It is a reader
+ * plus one owner write (the ready flag), and it holds nothing the room does not already say.
+ *
+ * `attachLobby(element, schema, options)` is the **glue**: it listens for the panel's two chooser
+ * events, makes the calls the panel deliberately cannot make itself, and attaches the room it gets
+ * back. Sugar, not capability — the same rule `matchRoom` is held to. An app that wants to answer
+ * the events itself keeps every part of this and needs none of it.
+ *
+ * ## Why the view polls
+ *
+ * `room.on(...)` has no "state changed" event: the client SDK publishes `status`, `clients`, `rtt`,
+ * `error` and `correct`, and lobby state is ordinary entity state that arrives in a `DELTA` like
+ * everything else. So `on('change')` samples — on every `clients` event, and on a cheap timer in
+ * between — and fires only when a small signature actually differs.
+ *
+ * That is a real cost and it is written here rather than hidden: one shallow string build per
+ * sample, over at most `maxClients` records, for as long as somebody is watching. It is the honest
+ * price of the element importing nothing from this package. A `state` event on `Room` would replace
+ * the timer with a subscription and is recorded as a debt in the lane report rather than smuggled
+ * into this lane's protocol-free budget.
+ */
+
+/**
+ * The two collection names the lobby fragment declares.
+ *
+ * Literals here rather than an import from `@irtio/server`, which is where they are defined. The
+ * client SDK ships to browsers and depends on `@irtio/schema` and `@irtio/protocol` alone; taking
+ * a dependency on the room-file API to read two strings would put the whole of it in every game's
+ * bundle. This is the same fence `@irtio/server`'s own `MAX_AWAKE_MAX` sits behind, and it is
+ * pinned the same way: `test/lobby-view.test.ts` imports both and asserts the pairs equal, from a
+ * package that legitimately depends on both, so a rename is a failing test rather than a lobby
+ * that silently never appears.
+ */
+declare const LOBBY_STATE = "irtLobby";
+declare const LOBBY_MEMBERS = "irtLobbyMembers";
+/** How often the view samples for a change between `clients` events. */
+declare const LOBBY_POLL_MS = 120;
+/** One row of the lobby roster, in join order. */
+interface LobbyPlayer {
+    readonly clientId: string;
+    readonly ready: boolean;
+    readonly connected: boolean;
+    /** True for the row belonging to the client holding this view. */
+    readonly me: boolean;
+}
+/** What `lobbyOf` answers: `@irtio/lobby`'s structural `lobby` member, with names. */
+interface LobbyView {
+    readonly phase: 'lobby' | 'started';
+    readonly players: readonly LobbyPlayer[];
+    readonly public: boolean;
+    readonly readyUi: boolean;
+    /** How many the room starts at under `'when-full'`, or 0 when the room has not said. */
+    readonly capacity: number;
+    ready(value: boolean): void;
+    setPublic?(value: boolean): void;
+    on(event: 'change', cb: () => void): () => void;
+}
+interface StateLike {
+    [collection: string]: unknown;
+}
+interface RoomLike {
+    readonly me: string;
+    readonly state: StateLike;
+    readonly clients: readonly {
+        clientId: string;
+        connected: boolean;
+    }[];
+    on(event: 'clients', cb: (clients: readonly {
+        clientId: string;
+        connected: boolean;
+    }[]) => void): () => void;
+    flush(): void;
+}
+/**
+ * Does this room carry a lobby?
+ *
+ * A schema that did not spread `lobbyCollections` has neither collection, and the honest answer for
+ * such a room is that it has no lobby rather than an empty one — `<irt-lobby>` renders no lobby UI
+ * at all in that case, which is what keeps every existing consumer unchanged.
+ */
+declare function hasLobby(room: unknown): boolean;
+/**
+ * Reads a joined room's lobby.
+ *
+ * ```ts
+ * const room = await joinPublic(schema);
+ * lobby.attach(room, { lobby: lobbyOf(room) });
+ * ```
+ *
+ * `setPublic` is present only when the caller supplies one, and that is a consequence of there
+ * being no built-in RPC for it. The platform never takes a public toggle from a client — that
+ * would be a protocol change — so the room's own game code owns the door. A game that wants the
+ * panel's toggle to work declares its own RPC and passes it here:
+ *
+ * ```ts
+ * lobbyOf(room, { setPublic: (value) => void room.call.setPublic({ value }) })
+ * ```
+ *
+ * Without one, the panel renders the room's public state and no toggle, which is the truthful
+ * rendering of a room whose code has not offered the control.
+ */
+declare function lobbyOf(room: unknown, options?: {
+    readonly setPublic?: (value: boolean) => void;
+}): LobbyView | undefined;
+/** What the panel's `quickmatch` event carries. */
+interface QuickMatchDetail {
+    readonly queue?: string;
+}
+/** The element surface `attachLobby` needs. Structural, so a test can pass a stand-in. */
+interface LobbyElementLike {
+    addEventListener(type: string, cb: (event: Event) => void): void;
+    removeEventListener(type: string, cb: (event: Event) => void): void;
+    setAttribute(name: string, value: string): void;
+    removeAttribute(name: string): void;
+    attach(room: unknown): () => void;
+}
+/**
+ * The room, as `<irt-lobby>`'s structural `AttachableRoom` wants it: everything the panel already
+ * read, plus the optional `lobby` member the design's §6 adds.
+ *
+ * A wrapper of getters rather than a spread, because a `Room`'s fields are accessors on a class:
+ * `{ ...room }` would freeze `status`, `id` and `clients` at the moment of the copy, and the panel
+ * re-reads all three on every render precisely so a reconnect that changes the code is picked up.
+ * Mutating the room to hang a `lobby` on it was the other option and is worse — the SDK's own
+ * object would then carry a field its type does not declare.
+ */
+declare function attachable(room: RoomLike & {
+    id: string;
+    link: string;
+    status: string;
+    maxClients?: number;
+    rtt?: number;
+}, view: LobbyView | undefined): unknown;
+interface AttachLobbyOptions<S extends AnySchema, Role extends string> {
+    /** Passed through to `joinRoom` / `joinPublic`. */
+    readonly join?: JoinOptions<S, Role> & {
+        role?: RoleOf<S> & string;
+    };
+    /** Passed through to the control-plane call. */
+    readonly match?: Pick<MatchOptions, 'controlUrl' | 'fetch'> & {
+        readonly identity?: boolean;
+    };
+    /** The room's own public-toggle RPC, if it has one. See `lobbyOf`. */
+    readonly setPublic?: (room: Room<S, Role>, value: boolean) => void;
+    /** Called with the room once it is joined, so game code can start drawing. */
+    readonly onRoom?: (room: Room<S, Role>) => void;
+    /** Called when a join fails. Default: the panel's status goes back to idle and the error is
+     *  rethrown on the microtask queue so it reaches `window.onerror` rather than vanishing. */
+    readonly onError?: (err: unknown) => void;
+}
+/**
+ * Wires `<irt-lobby>`'s chooser to the two calls it deliberately cannot make itself.
+ *
+ * ```ts
+ * attachLobby(document.querySelector('irt-lobby')!, schema, { onRoom: (room) => start(room) });
+ * ```
+ *
+ * The panel emits and this answers: `private` becomes an ordinary `joinRoom` with no code (which
+ * creates one), `quickmatch` becomes `joinPublic`. Both then `attach` the room, exactly as an app
+ * doing it by hand would. Returns an unsubscribe.
+ *
+ * `@irtio/lobby` imports nothing from this package and never will — that is what lets a React or
+ * Svelte app drive the panel with attributes and no SDK. This function is the other side of that
+ * rule rather than an exception to it: the dependency points this way.
+ */
+declare function attachLobby<S extends AnySchema, Role extends string = RoleOf<S> & string>(element: LobbyElementLike, schema: S, options?: AttachLobbyOptions<S, Role>): () => void;
 
 /**
  * The default `Scheduler`. In a browser the write batcher aligns to `requestAnimationFrame` (one
@@ -2135,7 +2556,7 @@ interface SessionOptions {
     /** The shared world-builder half the client predicts with (D22 part 2). */
     readonly physics?: ClientPhysicsOptions | undefined;
     /** The same, for a matter2d room (D57). Never both; `joinRoom` refuses that. */
-    readonly physics2d?: ClientPhysics2dOptions | undefined;
+    readonly physics2d?: ClientPhysics2dOptions | ClientRapier2dOptions | undefined;
     readonly transport?: Transport | undefined;
     readonly scheduler?: Scheduler | undefined;
     readonly onFrame?: FrameHook | undefined;
@@ -2272,8 +2693,15 @@ declare class Session {
     private connect;
     private transportFailed;
     private sendHello;
-    /** Leaves for good: no reconnect, pending calls reject, the socket closes. */
-    leave(): void;
+    /**
+     * Leaves for good: no reconnect, pending calls reject, the socket closes.
+     *
+     * The promise resolves when the socket reports its close (or immediately when there was
+     * nothing open), so `await room.leave()` is a real wait rather than a guessed timeout. A
+     * transport that never reports one is bounded by `LEAVE_CLOSE_TIMEOUT_MS` so the caller cannot
+     * hang on it.
+     */
+    leave(): Promise<void>;
     private fatal;
     private onSocketClosed;
     private stopTimers;
@@ -2586,4 +3014,4 @@ declare function joinRoom<S extends AnySchema, Role extends string = RoleOf<S> &
  */
 declare function joinRelay<S extends AnySchema = never>(options?: JoinRelayOptions<S extends AnySchema ? S : AnySchema>): Promise<RelayRoom<S>>;
 
-export { ACCOUNT_STORAGE_KEY, CALL_TIMEOUT_MS, type ClientBody2dFactory, type ClientBody2dSpec, type ClientBodySpec, type ClientCollection, type ClientIntent2dHook, type ClientMatterBody, type ClientMatterConstraint, type ClientMatterEngine, type ClientMatterModule, type ClientPhysics2dOptions, type ClientPhysicsOptions, type ClientRapierBody, type ClientRapierModule, type ClientRapierWorld, type ClientState, ClientStore, type ClientVector2, type ClientVector3, type Correction, DEFAULT_CONTROL_URL, DEFAULT_REGION, DEFAULT_WRITE_INTERVAL_MS, DEV_PORT, E_CONNECT_FAILED, E_IDENTITY_RATE_LIMITED, type FrameHook, INTERNAL_VOICE_TRACKS, Identity, IdentityError, type IdentityOptions, type IdentityStorage, type JoinOptions, type JoinRelayOptions, MAX_IDENTITY_RETRY_WAIT_MS, MAX_PREDICTED_BODIES, MAX_PROXY_BODIES, MatchError, type MatchOptions, type MatchTicket, type MessageTarget, PING_INTERVAL_MS, PREDICTION_EPSILON, type PartyTicket, type PredictionStats, type PredictionStatus, REGION_RE, RESIM_DEPTH, type RelayRoom, type Room, type RoomCallProxy, type RoomError, type RoomEvents, type RoomMessageStats, type RoomMessages, type RoomProfile, type RoomStats, SMOOTHING_HALF_LIFE_MS, SMOOTHING_SNAP_UNITS, type Scheduler, Session, type Status, type Transport, type TransportSocket, type Unsubscribe, type VoiceHandle, type VoiceOptions, type VoicePeerState, type VoiceTrackAccess, createParty, defaultScheduler, findMatch, identityStorageKey, joinRelay, joinRoom, joinVoice, linkForUrl, matchRoom, resolveUrl, roomIdFrom, webSocketTransport };
+export { ACCOUNT_STORAGE_KEY, type AttachLobbyOptions, CALL_TIMEOUT_MS, type ClientBody2dFactory, type ClientBody2dSpec, type ClientBodySpec, type ClientCollection, type ClientIntent2dHook, type ClientMatterBody, type ClientMatterConstraint, type ClientMatterEngine, type ClientMatterModule, type ClientPhysics2dOptions, type ClientPhysicsOptions, type ClientRapier2dBody, type ClientRapier2dBodyFactory, type ClientRapier2dBodySpec, type ClientRapier2dIntentHook, type ClientRapier2dModule, type ClientRapier2dOptions, type ClientRapier2dWorld, type ClientRapierBody, type ClientRapierModule, type ClientRapierWorld, type ClientState, ClientStore, type ClientVector2, type ClientVector2d, type ClientVector3, type Correction, DEFAULT_CONTROL_URL, DEFAULT_REGION, DEFAULT_WRITE_INTERVAL_MS, DEV_PORT, E_CONNECT_FAILED, E_IDENTITY_RATE_LIMITED, type EntityKeys, type FrameHook, INTERNAL_VOICE_TRACKS, Identity, IdentityError, type IdentityOptions, type IdentityStorage, type JoinOptions, type JoinRelayOptions, LOBBY_MEMBERS, LOBBY_POLL_MS, LOBBY_STATE, type LobbyPlayer, type LobbyView, MAX_IDENTITY_RETRY_WAIT_MS, MAX_PREDICTED_BODIES, MAX_PROXY_BODIES, MatchError, type MatchOptions, type MatchTicket, type MessageTarget, PING_INTERVAL_MS, PREDICTION_EPSILON, type PartyTicket, type PredictionStats, type PredictionStatus, type PublicTicket, type QuickMatchDetail, REGION_RE, RESIM_DEPTH, type RelayRoom, type Room, type RoomCallProxy, type RoomError, type RoomEvents, type RoomMessageStats, type RoomMessages, type RoomProfile, type RoomStats, type RowOf, SMOOTHING_HALF_LIFE_MS, SMOOTHING_SNAP_UNITS, type Scheduler, Session, type Status, type Transport, type TransportSocket, type Unsubscribe, type VoiceHandle, type VoiceOptions, type VoicePeerState, type VoiceTrackAccess, attachLobby, attachable, createParty, defaultScheduler, findMatch, findPublic, hasLobby, identityStorageKey, joinPublic, joinRelay, joinRoom, joinVoice, linkForUrl, lobbyOf, matchRoom, resolveUrl, roomIdFrom, webSocketTransport };