@irtio/client 0.6.0 → 0.8.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, 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';
 
@@ -280,6 +281,23 @@ interface EngineAdapter {
     /** Factory call plus every engine-specific warning about what it returned. */
     createBody(desc: CollectionDesc, id: string, record: AnyRecord$2, warn: (key: string, message: string) => void): EngineBody | undefined;
     removeBody(body: EngineBody): void;
+    /**
+     * D71: turn a body the factory just built into a **kinematic proxy**. It keeps the collider the
+     * factory gave it, it is never moved by gravity, by contact or by any other local force, and it
+     * goes only where {@link EngineAdapter.moveKinematic} puts it. Called once, immediately after
+     * `createBody`, and never on a body the local world is simulating.
+     */
+    makeKinematic(body: EngineBody): void;
+    /**
+     * D71: put a kinematic proxy at `pose` for the next step, so that contacts see the velocity the
+     * move implies and a predicted body resting on it is carried.
+     *
+     * Called before every local step. Asking for the same pose twice moves nothing and implies no
+     * velocity — which is what "held, never extrapolated" means at the engine seam: a proxy driven
+     * through a forty-tick rebase stands still for all of it rather than running the same delta forty
+     * times.
+     */
+    moveKinematic(body: EngineBody, pose: Pose): void;
     /** One fixed-timestep step of the local world. */
     step(): void;
     /** Server record → body state, in whatever order this engine's setters require. */
@@ -302,9 +320,20 @@ interface EngineAdapter {
      */
     velocityTolerance(epsilon: number, timestepSeconds: number): number;
 }
+/**
+ * D71: where a kinematic proxy goes — the body-channel values the renderer is drawing for one
+ * instance at this instant, written into `into`. `false` when there is nothing drawn (the entity
+ * has not appeared at the render clock, or has left it).
+ *
+ * Backed by `RenderStore.drawn`, the D20 interpolation buffer: the authoritative pose at
+ * `interpDelayMs` behind arrival, **held** past the newest delta rather than extrapolated. The
+ * predictor never asks it for a time, so it can never be asked for the future.
+ */
+type DrawnReader = (desc: CollectionDesc, id: string, into: Record<string, number>) => boolean;
 /** The engine-neutral tuning knobs; both engines' option objects carry these names. */
 interface PredictorTuning {
     readonly maxPredictedBodies?: number;
+    readonly maxProxyBodies?: number;
     readonly epsilon?: number;
     readonly smoothingHalfLifeMs?: number;
     readonly smoothingSnapUnits?: number;
@@ -317,16 +346,42 @@ 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;
     /**
-     * Non-owned predicted instances currently over the cap. They render by interpolation but have
-     * no body in the local world, so predicted bodies pass through them: a non-zero value on a
-     * collection anything stands on is a gameplay bug, not a fidelity tradeoff.
+     * Non-owned predicted instances currently over `maxPredictedBodies`.
+     *
+     * Since D71 these are **proxied** rather than absent: each one still has a collider in the local
+     * world, moved to the pose the renderer draws, so a predicted body stands on it instead of
+     * falling through. What it no longer has is a simulation of its own — shove it and nothing
+     * happens locally until the server agrees. `stats.absent` is the number that means "you can fall
+     * through this"; this one means "you cannot push this".
      */
     overCap: number;
+    /** D71: kinematic proxies in the local world right now. */
+    proxies: number;
+    /**
+     * D71: non-owned instances with **no body in the local world at all** — over `maxProxyBodies`,
+     * opted out with `proxy: false`, or with no body factory on the client. Predicted bodies pass
+     * straight through these until the next correction snaps them back, so a non-zero value on a
+     * collection anything stands on is a gameplay bug rather than a fidelity tradeoff.
+     */
+    absent: number;
     /** Microseconds spent in the last rebase's re-steps. */
     lastResimMicros: number;
     /**
@@ -389,11 +444,19 @@ declare class Predictor {
     /** Seconds per step, fixed for the life of the world. */
     private timestepSeconds;
     private readonly bodies;
+    /** D71: kinematic proxies, keyed like `bodies`. The two maps are disjoint by construction. */
+    private readonly proxies;
     /** Physics-backed entity collections, in schema order. D50: not `readonly`, see `swapSchema`. */
     private collections;
     private readonly warned;
     /** Highest over-cap count warned about per collection, so growth re-warns and noise does not. */
     private readonly overCapHigh;
+    /** The same, for the proxy cap: `absent` is the count a game has to act on (D71-d). */
+    private readonly absentHigh;
+    /** D71: where a proxy goes. Wired by the session; see {@link DrawnReader}. */
+    private drawnReader;
+    /** `drawnReader`'s output buffer, reused: it is called once per proxy per frame. */
+    private readonly drawnChannels;
     /** Authority arrived since the last frame: rebase before free-running. */
     private authorityDirty;
     private accumulatorMs;
@@ -466,6 +529,11 @@ declare class Predictor {
      * `PredictedBody.desc` and re-deriving collider shapes from the new descriptors.
      */
     swapSchema(newExt: AnySchema): void;
+    /**
+     * D71: tell the predictor where its proxies go. The session calls this once, with a reader over
+     * the D20 interpolation buffer; without it a proxy holds the pose it was built at.
+     */
+    setDrawnReader(reader: DrawnReader): void;
     get epsilon(): number;
     /** `true` once the engine is loaded and the local world exists. */
     get ready(): boolean;
@@ -509,8 +577,19 @@ declare class Predictor {
      * that is the lead, not this.
      */
     noteWriteApplied(stampTick: number, appliedTick: number): void;
-    /** Does the local world currently simulate `collection[id]`? */
+    /**
+     * Does the local world currently **simulate** `collection[id]`?
+     *
+     * Deliberately still false for a proxied instance (D71). Every caller of this asks it to decide
+     * whether the local world is the better answer than authority — the render read path, the
+     * correction classifier, `room.prediction.predicts` — and for a proxy it is not: a proxy is
+     * authority, one interpolation delay old, put into the world so that other bodies can touch it.
+     * Reading it back would be a round trip through the physics engine to learn what the render
+     * buffer already said. {@link proxied} is the question about proxies.
+     */
     has(collection: string, id: string): boolean;
+    /** D71: does `collection[id]` have a kinematic proxy in the local world right now? */
+    hasProxy(collection: string, id: string): boolean;
     /**
      * Is a correction's every value within the suppression tolerance of the prediction it judges?
      * Position (and rotation) channels compare against `epsilon` directly; velocity and angular
@@ -615,24 +694,77 @@ declare class Predictor {
      */
     predictedValues(desc: CollectionDesc, id: string, fields: readonly string[], atTick?: number): AnyRecord$2 | undefined;
     /**
-     * Mirrors the local world's bodies onto the instances this client predicts: every physics
-     * instance it owns, plus non-owned instances of `predicted: true` collections up to the cap
-     * (collection order, then insertion order — the same stated iteration guarantee the server
-     * follows, so which bodies fall over the cap is deterministic).
+     * Mirrors the local world onto the instances this client can see: a **simulated** body for every
+     * physics instance it owns plus non-owned instances of `predicted: true` collections up to
+     * `maxPredictedBodies`, and a **kinematic proxy** (D71) for everything else that has a body
+     * factory and has not opted out with `proxy: false`, up to `maxProxyBodies`.
+     *
+     * Slot order is collection order then insertion order — the same iteration guarantee the server
+     * states — so which instances fall over either cap is deterministic. There is no relevance
+     * policy and no distance ordering: the ninth crate spawned is still the ninth crate, it is just
+     * now solid rather than missing.
      *
-     * Everything else — non-`predicted` collections, and `predicted` instances over the cap — gets
-     * no body and no collider here. Those instances still render (the interpolation path reads
-     * authoritative state directly), but nothing in the local world can touch them.
+     * Three transitions happen here, and each is a removal before a creation so the world never holds
+     * two colliders for one id:
+     *
+     * - **Promotion.** A proxied instance of a predicted collection finds a free slot (a predicted
+     *   body was removed, or the cap was raised). `createBody` applies the authority record, velocity
+     *   channels included, so the body carries on rather than starting from rest.
+     * - **Demotion.** A simulated instance loses its slot to an earlier-collection newcomer. That is
+     *   what this loop already did before proxies — it stopped marking the body live and the sweep
+     *   below removed it — and now it becomes a proxy at the drawn pose in the same frame. It costs
+     *   one visible pose step: the body was a lead ahead of authority and the proxy is an
+     *   interpolation delay behind it.
+     * - **Removal.** An instance the server removed, or one that left this client's area of interest
+     *   (D23), loses whichever of the two it had, the same frame.
+     *
+     * What is left over — over the proxy cap, `proxy: false`, or no factory — has no collider in the
+     * local world at all, is counted in `stats.absent`, and is the only case a predicted body still
+     * falls through.
      */
     private reconcileBodies;
+    /** Drops one simulated body and everything the loop keeps per body. Safe on a missing key. */
+    private removePredicted;
+    /** Drops one proxy. Safe on a missing key. */
+    private removeProxy;
+    /**
+     * D71: builds one kinematic proxy through the **same factory call** the simulated path uses, so
+     * the collider is the server's collider by construction rather than by a second description of
+     * it, then hands it to the adapter to be made kinematic.
+     *
+     * The authority record is applied first — a proxy appears where the server last said it was, not
+     * at the factory's origin — and the drawn pose takes over on the next `refreshProxyTargets`.
+     */
+    private createProxy;
+    /**
+     * Reads every proxy's drawn pose once per frame, and only once.
+     *
+     * Once, because a rebase re-steps the world up to `MAX_LEAD` times against a render clock that
+     * has not moved: asking again per step would return the same answer at a real cost. And once
+     * *because* of D71's rule — a proxy holds one pose for every re-step of a rebase. It cannot run
+     * ahead of the newest delta because the reader never extrapolates, and it cannot run ahead of the
+     * frame because it is only ever asked here.
+     *
+     * A proxy with nothing drawn (a delta gap, an entity not yet at the render clock) keeps the pose
+     * it had. That is the hold, and it is the difference between a crate that stays solid through a
+     * stall and a crate that slides off across the level.
+     */
+    private refreshProxyTargets;
+    /** Writes every proxy to its target pose. Runs immediately before each `adapter.step()`. */
+    private driveProxies;
     private createBody;
     /**
-     * Over-cap is not a one-time tuning notice: it means those instances are missing from the local
-     * world right now, so a predicted body walks through them. Warn on every new high-water mark
-     * per collection — a game that grows past the cap mid-session hears about it, and a count that
-     * oscillates around one level does not turn the console into a log.
+     * The two cap notices, both on a new high-water mark per collection: a game that grows past a cap
+     * mid-session hears about it, and a count that oscillates around one level does not turn the
+     * console into a log.
+     *
+     * They say different things now, and only the second is an emergency (D71). Over the *prediction*
+     * cap an instance is still solid — it has a proxy — it just is not simulated, so a shove does
+     * nothing locally until the server agrees. Over the *proxy* cap it is genuinely not there, which
+     * is the failure `bugs.md` #3 was about, and the message names both numbers so it is obvious
+     * which one to raise.
      */
-    private warnOverCap;
+    private warnCaps;
     private warnOnce;
     /**
      * The client's lead over authority, in ticks: a full round trip, rounded to the nearest tick
@@ -670,8 +802,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;
     /**
@@ -696,6 +828,11 @@ declare class Predictor {
      * local body of a collection, owned or not, run after the whole intent pass rather than
      * interleaved with it. It is what gives a non-owned predicted body its gravity on an engine
      * whose world has none of its own.
+     *
+     * Both passes walk `this.bodies`, which is why neither ever reaches a proxy (D71): a proxy is not
+     * simulated, so an intent hook or a per-step gravity force on it would be a force on a body that
+     * cannot move, applied to a pose that is going to be overwritten before the next step anyway. The
+     * isolation is structural rather than a filter, which is the version that cannot rot.
      */
     private applyIntents;
     /** Server record → body channels (the same mapping the runtime's sync uses, inverted). */
@@ -703,6 +840,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
@@ -777,6 +1034,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`). */
@@ -798,12 +1060,22 @@ interface ClientPhysics2dOptions {
      */
     readonly settle?: Readonly<Record<string, ClientIntent2dHook>>;
     /**
-     * D21 cap: how many **non-owned** predicted bodies this client simulates. Over-cap instances
-     * are **absent from the local world** — they render by interpolation, but predicted bodies
-     * pass straight through them, so anything a predicted body stands on or is blocked by has to
-     * be under the cap (warned, counted as `stats.overCap`). Default 64.
+     * D21 cap: how many **non-owned** predicted bodies this client simulates ahead. Default 64.
+     *
+     * Since D71 an over-cap instance is not gone from the local world — it gets a kinematic proxy
+     * (see `maxProxyBodies`), so a predicted body still stands on it and is still blocked by it.
+     * What it loses is being simulated: shove it and nothing happens locally until the server says
+     * it moved. Counted as `stats.overCap`.
      */
     readonly maxPredictedBodies?: number;
+    /**
+     * D71 cap: how many **kinematic proxies** this client keeps — colliders at the pose the renderer
+     * draws, for the instances it does not simulate. Default `MAX_PROXY_BODIES`. Past it, instances
+     * are **absent from the local world** and predicted bodies pass straight through them (warned,
+     * counted as `stats.absent`). See `ClientPhysicsOptions.maxProxyBodies` for why it is its own
+     * number rather than a share of the prediction cap.
+     */
+    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
@@ -885,12 +1157,28 @@ interface ClientPhysicsOptions {
      */
     readonly intents?: Readonly<Record<string, ClientIntentHook>>;
     /**
-     * D21 cap: how many **non-owned** predicted bodies this client simulates. Over-cap instances
-     * are **absent from the local world** — they render by interpolation, but predicted bodies
-     * pass straight through them, so anything a predicted body stands on or is blocked by has to
-     * be under the cap (warned, counted as `stats.overCap`). Default 64.
+     * D21 cap: how many **non-owned** predicted bodies this client simulates ahead. Default 64.
+     *
+     * Since D71 an over-cap instance is not gone from the local world — it gets a kinematic proxy
+     * (see `maxProxyBodies`), so a predicted body still stands on it and is still blocked by it.
+     * What it loses is being simulated: shove it and nothing happens locally until the server says
+     * it moved. Raise this for the bodies players push; leave it for the ones they only stand on.
+     * Counted as `stats.overCap`.
      */
     readonly maxPredictedBodies?: number;
+    /**
+     * D71 cap: how many **kinematic proxies** this client keeps — colliders at the pose the renderer
+     * draws, for the instances it does not simulate (over `maxPredictedBodies`, or in a collection
+     * that is not `predicted`). Default `MAX_PROXY_BODIES`.
+     *
+     * Its own number rather than a share of `maxPredictedBodies`, because a proxy is a different
+     * cost: a pose write and a collider in the broad phase, not a body being integrated and solved.
+     * Past this cap instances are **absent from the local world** — predicted bodies pass through
+     * them until the next correction snaps them back (warned, counted as `stats.absent`). Turn
+     * `proxy: false` on in the schema for the collections nothing collides with, so the budget goes
+     * to the ones that matter.
+     */
+    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 — steady state stays
@@ -1356,7 +1644,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 */
@@ -1369,8 +1657,18 @@ interface JoinOptions<S, Role extends string = string> {
      */
     readonly profile?: boolean;
 }
-/** `joinRelay` options: a relay room has no schema, so there is no state and no RPC. */
-interface JoinRelayOptions {
+/**
+ * `joinRelay` options. A relay room has no state and no RPC; D70 adds the one thing a schema can
+ * still describe on it — `schema` names the project's deployed schema, which lets this client
+ * bring its real hash instead of the zero hash and send typed messages.
+ */
+interface JoinRelayOptions<S extends AnySchema = AnySchema> {
+    /**
+     * D70: the schema this project deployed with `irtio deploy` and no room file. The HELLO carries
+     * its hash, the relay host checks it against what it was registered with, and `room.messages`
+     * comes from it. Omitted ⇒ the zero hash and no typed messages, exactly as before.
+     */
+    readonly schema?: S;
     readonly room?: string;
     readonly role?: string;
     readonly name?: string;
@@ -1390,6 +1688,31 @@ interface JoinRelayOptions {
 type MessageTarget = 'all' | string | {
     readonly role: string;
 };
+/**
+ * D70: `room.stats.messages` — what this socket did with peer messages.
+ *
+ * `dropped` is the one to watch. It counts typed frames this client could not read: an index its
+ * schema does not have, or a payload the codec refused. Every one of them is a peer running a
+ * schema this client does not, so a number climbing here means a stale tab, a stale deploy, or
+ * somebody probing — never a bug in the game reading it.
+ */
+interface RoomMessageStats {
+    readonly sent: number;
+    readonly received: number;
+    readonly dropped: number;
+}
+/** D70: `room.stats`. One member today; the shape exists so later counters have somewhere to go. */
+interface RoomStats {
+    readonly messages: RoomMessageStats;
+}
+/**
+ * D70: `room.messages` — one channel per shape the schema declares, `{}` when it declares none.
+ *
+ * `send` takes exactly the declared value and `on` hands back exactly the same, so a shape change
+ * is a compile error on both sides at once. Fire and forget: there is no reply, no acknowledgement
+ * and no ordering promise beyond one socket's own frames.
+ */
+type RoomMessages<S> = MessageChannels<S, MessageTarget, 'server' | string, Unsubscribe>;
 /**
  * D65: the client's view of where its bytes went, by collection and field.
  *
@@ -1415,6 +1738,44 @@ interface RoomProfile {
  * a predicted body passes through them.
  */
 declare const MAX_PREDICTED_BODIES = 64;
+/**
+ * D71: default cap on **kinematic proxies** per client — instances the local world does not
+ * simulate but does have to be able to collide with (over `MAX_PREDICTED_BODIES`, or in a
+ * collection that is not `predicted`).
+ *
+ * Its own number, measured rather than inherited from the prediction cap, because a proxy is a
+ * different cost: a pose write and a collider in the broad phase, not a body being integrated and
+ * solved. `packages/client/test/proxy-bench.test.ts` is the measurement and prints its whole table
+ * on every run.
+ *
+ * Measured 2026-09-03 on the development machine (Windows 11, node 22), 64 predicted bodies plus N
+ * proxies, all boxes in contact on a floor, median of 200 samples for a step and 20 for a
+ * forty-step rebase:
+ *
+ * | N | rapier step | rapier rebase | matter step | matter rebase |
+ * |---|---|---|---|---|
+ * | 0 | 0.0055 ms | 6.66 ms | 0.0458 ms | 2.16 ms |
+ * | 50 | 0.0146 | 7.71 | 0.0623 | 2.38 |
+ * | 100 | 0.0096 | 8.01 | 0.0659 | 2.63 |
+ * | 200 | 0.0118 | 7.22 | 0.0868 | 3.59 |
+ * | 400 | 0.0217 | 7.56 | 0.1608 | 6.32 |
+ *
+ * So a proxy costs about 0.04 microseconds a step on Rapier and 0.29 on matter — three to four
+ * orders of magnitude inside the 4 ms per step `games/dive/spike` budgets for the server's world,
+ * which means the step budget does not bind at any count worth having. What binds is the rebase,
+ * which runs on every authoritative arrival and has to fit inside a frame: at 200 both engines sit
+ * at 3.6 to 7.2 ms against a 60 Hz frame's 16.7.
+ *
+ * The same bench inside a full `pnpm test`, with the rest of the suite running in parallel workers,
+ * reads two to three times that: the step stays far inside its budget (0.023 ms rapier, 0.216 ms
+ * matter at 200) but the rebase reaches 15.6 and 12.1 ms at 200 and 22.0 and 19.2 ms at 400. That
+ * loaded reading is why 400 is not the default even though it fits on a quiet machine: a busy
+ * device is the normal case, and the rebase is the number that stretches on one.
+ *
+ * Four times the prediction cap is also the honest ratio between the two costs. Raise it with
+ * `maxProxyBodies` and watch `stats.lastResimMicros`, which is the rebase column measured live.
+ */
+declare const MAX_PROXY_BODIES = 256;
 /** Default correction-suppression epsilon, world units (see `ClientPhysicsOptions.epsilon`). */
 declare const PREDICTION_EPSILON = 0.05;
 /**
@@ -1437,6 +1798,15 @@ interface PredictionStatus {
     readonly active: boolean;
     /** Is `collection[id]` currently simulated in the local world? */
     predicts(collection: string, id: string): boolean;
+    /**
+     * D71: does `collection[id]` have a **kinematic proxy** in the local world — a collider at the
+     * pose the renderer draws, which predicted bodies collide with and never move?
+     *
+     * Never true at the same time as `predicts`: an instance is simulated locally, or proxied, or
+     * absent. `!predicts && !proxied` with the instance present is the absent case, and that is the
+     * one a predicted body falls through.
+     */
+    proxied(collection: string, id: string): boolean;
     readonly stats: PredictionStats;
 }
 /**
@@ -1498,13 +1868,24 @@ interface Room<S, Role extends string = RoleOf<S> & string> {
     requestOwnership(entity: string, id: string): Promise<boolean>;
     message(target: MessageTarget, bytes: Uint8Array): void;
     onMessage(cb: (from: 'server' | string, bytes: Uint8Array) => void): Unsubscribe;
+    /** D70: the declared message shapes. A raw `onMessage` callback never sees one of these. */
+    readonly messages: RoomMessages<S>;
+    /** 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;
     /** Sends any pending owned writes immediately instead of at the next flush window. */
     flush(): void;
     leave(): void;
 }
-/** What `joinRelay` returns: presence + the raw message channel, nothing else. */
-interface RelayRoom {
+/**
+ * What `joinRelay` returns: presence and the message channel, nothing else.
+ *
+ * D70 gives it a type parameter. `joinRelay()` with no schema is `RelayRoom<never>` and behaves
+ * exactly as it did — `messages` is `{}` — while `joinRelay({ schema })` against a project that
+ * deployed one gets the same typed channels a coded room has. There is still no state and still
+ * no RPC: a schema on a relay room describes messages, and lane K is what makes it describe more.
+ */
+interface RelayRoom<S = never> {
     readonly me: string;
     readonly id: string;
     /**
@@ -1519,6 +1900,10 @@ interface RelayRoom {
     readonly clients: readonly PresenceRecord[];
     message(target: MessageTarget, bytes: Uint8Array): void;
     onMessage(cb: (from: 'server' | string, bytes: Uint8Array) => void): Unsubscribe;
+    /** D70: the declared message shapes; `{}` for a relay join that brought no schema. */
+    readonly messages: RoomMessages<S>;
+    /** 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;
 }
@@ -1688,6 +2073,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
@@ -1805,6 +2414,25 @@ declare class RenderStore {
     attachPredictor(predictor: Predictor): void;
     /** The interpolated (or predicted, or authoritative) value of `collection[id]` right now. */
     get(desc: CollectionDesc, id: string): unknown;
+    /**
+     * M6 lane D (D71): the body-channel values the renderer is drawing for one instance right now,
+     * written into `into`. `true` when there is a pose to draw at all.
+     *
+     * This is what a kinematic proxy is moved to before every local step, and it deliberately does
+     * **not** go through `get`. `get` asks the predictor first — which would recurse, since it calls
+     * `frame()` — and for an owned or predicted instance it answers out of the local world, which is
+     * the one answer a proxy must never be given (a proxy driven by the local world is a body driving
+     * itself). So this is the D20 buffer and nothing else: the authoritative pose interpolated at
+     * `interpDelayMs` behind arrival, held at the newest delta and never extrapolated past it.
+     *
+     * Allocation-free, and only the physics channels: it runs once per proxy per frame.
+     *
+     * Two things `get` does are left out on purpose. `starved` is not counted, because that number
+     * belongs to the render path and a physics read landing in it would double it. And a buffer whose
+     * entity has aged out is not `gc`'d here, because a read that drives physics must not decide when
+     * the render path's buffers die.
+     */
+    drawn(desc: CollectionDesc, id: string, into: Record<string, number>): boolean;
     /** Is `collection[id]` visible at the render clock? */
     has(desc: CollectionDesc, id: string): boolean;
     /** The authoritative owner — ownership is fact, not a rendered value. */
@@ -1870,7 +2498,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;
@@ -1906,8 +2534,11 @@ declare class Session {
      * whatever a `SCHEMA` frame replaced it with. Read instead of `options.schema` everywhere, so a
      * swapped session announces its *current* hash when it reconnects rather than the one it was
      * born with — otherwise a resume after a swap would be refused as a mismatch.
+     *
+     * D70 made it internally readable rather than private: `buildMessages` reads the declared
+     * shapes off it when the room object is built. Still not on the public `Room` type.
      */
-    private schema;
+    schema: AnySchema | undefined;
     /** D50: how many times this session has swapped schema. Test seam and a diagnostic. */
     schemaSwaps: number;
     private readonly transport;
@@ -1969,6 +2600,24 @@ declare class Session {
      * `INTERNAL_SESSION`, the same route the D50 tests use for the session itself.
      */
     private readonly voiceListeners;
+    /**
+     * D70: typed-message listeners, by wire index, in their own map for the same structural reason
+     * `voiceListeners` is its own set: a raw `onMessage` callback must never be handed a typed
+     * frame and a typed callback must never be handed raw bytes. Splitting the registries makes
+     * that a fact about the shape of the code rather than a filter somewhere in the fan-out.
+     */
+    private readonly typedListeners;
+    /** D70: one warning per session for dropped typed messages — a flood must stay one line. */
+    private typedDropWarned;
+    /**
+     * D70: what `room.stats.messages` reads. `dropped` is the one worth watching: it counts typed
+     * frames this client could not decode, which is a peer on a schema this one does not have.
+     */
+    readonly messageCounts: {
+        sent: number;
+        received: number;
+        dropped: number;
+    };
     private cancelFlush;
     private cancelPing;
     private cancelRetry;
@@ -2073,6 +2722,18 @@ declare class Session {
     private onError;
     private onPong;
     private onMsg;
+    /**
+     * D70: decode one typed payload against the current schema and hand it to that shape's
+     * listeners.
+     *
+     * Everything a hostile peer can do here ends in the same place: a counter and a dropped frame.
+     * An index past the schema's list, a truncated payload, an oversize `str`, an over-max `list`,
+     * an unknown enum member, or a well-formed value of the wrong shape — each is caught, none
+     * throws out of the frame loop, none closes the socket, and the next frame is delivered
+     * normally. The `console.warn` fires once per session so a flood stays one line.
+     */
+    private deliverTyped;
+    private dropTypedMessage;
     private startTimers;
     /**
      * The write batcher: one window per animation frame in a browser, or per `writeIntervalMs`
@@ -2094,6 +2755,13 @@ declare class Session {
     private rejectPending;
     message(target: MessageTarget, bytes: Uint8Array): void;
     onMessage(cb: (from: 'server' | string, bytes: Uint8Array) => void): Unsubscribe;
+    /**
+     * D70: send one typed message. `payload` is already `encodeFields`'d by the caller
+     * (`buildMessages`), which is where the shape and the throw on a bad value belong.
+     */
+    typedMessage(index: number, target: MessageTarget, payload: Uint8Array): void;
+    /** D70: subscribe to one message shape by wire index. Raw listeners never see these frames. */
+    onTypedMessage(index: number, cb: (from: 'server' | string, value: Record<string, unknown>) => void): Unsubscribe;
     /**
      * D51: write one voice signaling message. Internal — reached only through `INTERNAL_SESSION`,
      * so it is not on the `Room` type and a game cannot call it.
@@ -2279,6 +2947,6 @@ declare function joinRoom<S extends AnySchema, Role extends string = RoleOf<S> &
  * channel. A separate entry rather than a schema-less `joinRoom` overload, because everything a
  * `Room` promises about state would be a lie here.
  */
-declare function joinRelay(options?: JoinRelayOptions): Promise<RelayRoom>;
+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, 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 RoomProfile, 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 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, 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 };