@irtio/client 0.5.1 → 0.6.0

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { AnySchema, PlainState, CollectionDesc, Delta, EntityCollection, ReadonlyCollection, RoleOf, VisibleKeys, SchemaDefs, EntityDef, DeepReadonly, InferFields, Owned, SingletonDef, ClientImplementations, ClientRpcs, SchemaRpc, ClientCallProxy } from '@irtio/schema';
+import { AnySchema, PlainState, CollectionDesc, Delta, EntityCollection, PhysicsBodyChannel, ReadonlyCollection, RoleOf, VisibleKeys, SchemaDefs, EntityDef, DeepReadonly, InferFields, Owned, SingletonDef, ClientImplementations, ClientRpcs, SchemaRpc, ClientCallProxy } from '@irtio/schema';
+import * as _irtio_protocol from '@irtio/protocol';
+import { PresenceRecord, ProfileLedger, ProfileSnapshot } from '@irtio/protocol';
+import * as MATTER from 'matter-js';
 import RAPIER from '@dimforge/rapier3d-compat';
-import { PresenceRecord } from '@irtio/protocol';
 
 /**
  * The client's state layer.
@@ -50,13 +52,16 @@ interface CorrectionOp {
     readonly snapped: boolean;
 }
 declare class ClientStore {
-    readonly ext: AnySchema;
+    /** D50: not `readonly` — a schema swap replaces it in place (`swapSchema`). */
+    ext: AnySchema;
     /** Reads the current client id — it is not known until the first `WELCOME`. */
     private readonly meOf;
     plain: PlainState;
     private tracked;
     private readonly descs;
     private readonly frozen;
+    /** 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. */
     readonly view: AnyRecord$3;
     /** Flushed-but-unjudged writes, oldest first, at most `RESIM_DEPTH` entries (D19). */
@@ -70,9 +75,24 @@ declare class ClientStore {
      * walks the window tick by tick starts from here, not from the newest local value.
      */
     private readonly baselineIntents;
-    constructor(ext: AnySchema, 
+    constructor(
+    /** D50: not `readonly` — a schema swap replaces it in place (`swapSchema`). */
+    ext: AnySchema, 
     /** Reads the current client id — it is not known until the first `WELCOME`. */
     meOf: () => string);
+    /**
+     * D50: rebuild every schema-derived handle in this store against `newExt`, keeping the objects
+     * user code holds. `view` keeps its identity (contractual, and pinned by test), and so does each
+     * collection facade behind it, because a game may well have hoisted `room.state.players` into a
+     * local.
+     *
+     * State itself is *not* carried across: `plain` is re-created empty under the new schema. That
+     * is not a loss, because a swap only ever happens immediately before the resync WELCOME that
+     * `rejoinAll` sends, and `loadSnapshot` re-seeds everything from it. Carrying the old records
+     * forward would be actively wrong — `normalizeRecord` rejects field names the old schema did
+     * not have, and a record built under the old descriptor is missing the new fields entirely.
+     */
+    swapSchema(newExt: AnySchema): void;
     loadSnapshot(bytes: Uint8Array): void;
     /**
      * Captures the field values of every pending owned write, keyed by collection then id then
@@ -87,7 +107,17 @@ declare class ClientStore {
      * whatever the resync snapshot happened to carry for that field.
      */
     applyPendingWrites(pending: Map<string, Map<string, AnyRecord$3>>): void;
-    private buildView;
+    /**
+     * Defines one accessor per collection on `view`. Called once at construction and again on every
+     * schema swap, always against the SAME object, so `room.state`'s identity never changes.
+     *
+     * A collection that survives the swap keeps its facade and is retargeted at the new descriptor;
+     * a collection the new schema adds gets a fresh one; a collection that disappears has its
+     * accessor deleted. Only the first two can happen on an additive swap, but a `delete` is one
+     * line and a stale accessor reading a collection that no longer exists would throw from inside
+     * a getter, which is a miserable thing to debug.
+     */
+    private buildViewInto;
     /** The writable tracked proxy when this client owns `id`, otherwise a frozen one. */
     instance(desc: CollectionDesc, id: string): unknown;
     private freeze;
@@ -171,29 +201,30 @@ declare class ClientStore {
 }
 
 /**
- * Client-side physics prediction (D22 part 2, D21): a local Rapier world that simulates this
- * client's own bodies — and any `predicted: true` collection's bodies — ahead of the server.
+ * The engine-neutral half of client-side physics prediction (D22 part 2, D21, D57): the loop, the
+ * render clock, the pose ring, the error smoothing, the cap, and the rebase replay. Everything an
+ * engine actually does sits behind {@link EngineAdapter}, and there is exactly one implementation
+ * of the loop for every engine irtio blesses.
  *
  * ## The contract
  *
- * The world is built from the **shared world-builder** the game passes to
- * `joinRoom({ physics })`: the same `setup` (static geometry), `bodies` (shape factories) and
- * `intents` (intent → force, per step) functions the room's config uses, imported by both sides
- * from one module (`irtio/world.ts` by convention — a convention, not a mechanism). The builder
- * must be pure over synced inputs: no `Math.random()`, no clock, seed/level params read from
- * synced state — or the two worlds are not the same world.
+ * The world is built from the **shared world-builder** the game passes to `joinRoom`: the same
+ * `setup` (static geometry), `bodies` (shape factories) and `intents` (intent → force, per step)
+ * functions the room's config uses, imported by both sides from one module (`irtio/world.ts` by
+ * convention — a convention, not a mechanism). The builder must be pure over synced inputs: no
+ * `Math.random()`, no clock, seed/level params read from synced state — or the two worlds are not
+ * the same world.
  *
  * ## The loop
  *
- * The local world **free-runs** on a fixed-timestep accumulator driven by render reads: each
- * step applies the owner's current intent values through the `intents` hook, then steps. When
+ * The local world **free-runs** on a fixed-timestep accumulator driven by render reads: each step
+ * applies the owner's current intent values through the `intents` hook, then steps. When
  * authoritative body state arrives (a `CORRECT` for an owned body, a `DELTA` for a non-owned
  * predicted one), every predicted body is **rebased** to the server's values and the world
  * re-steps the client's lead — one step per tick of estimated one-way latency, replaying the
- * buffered unjudged intent frames oldest-first (the write buffer holds exactly the server's
- * input frames — only intents are writable on a physics entity). The lead is bounded by the
- * shared resimulation depth (20, D19): beyond it the body snaps to authority and the snap is
- * counted.
+ * buffered unjudged intent frames oldest-first (the write buffer holds exactly the server's input
+ * frames — only intents are writable on a physics entity). The lead is bounded by the shared
+ * resimulation depth (20, D19): beyond it the body snaps to authority and the snap is counted.
  *
  * ## What the renderer sees
  *
@@ -214,94 +245,68 @@ declare class ClientStore {
  * snapped back by the next correction. That is the documented constraint: predict both
  * (`predicted: true`, within the cap) or interpolate both.
  *
- * The engine itself is loaded lazily via dynamic `import()`, so a game with no physics option —
- * or a bundler that code-splits — pays nothing for it.
+ * The engines themselves are loaded lazily, by an adapter module behind a dynamic `import()` from
+ * `session.ts`, so a game with no physics option — or one that predicts with the other engine —
+ * pays nothing for the one it does not use.
  */
 
 type AnyRecord$2 = Record<string, unknown>;
-type ClientRapierModule = typeof RAPIER;
-type ClientRapierWorld = RAPIER.World;
-type ClientRapierBody = RAPIER.RigidBody;
-interface ClientVector3 {
-    readonly x: number;
-    readonly y: number;
-    readonly z: number;
-}
-/** What a client-side body factory returns — the same shape the room config's factories use. */
-interface ClientBodySpec {
-    readonly body: RAPIER.RigidBodyDesc;
-    readonly colliders?: readonly RAPIER.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.
+ * One engine's body, opaque to this file. Created, read, stepped and removed only through the
+ * adapter — the core stores the handle and hands it straight back.
  */
-type ClientBodyFactory = {
-    factory(rapier: ClientRapierModule, instance: AnyRecord$2, id: string): ClientBodySpec;
-}['factory'];
-type ClientIntentHook = {
-    hook(body: ClientRapierBody, instance: AnyRecord$2, rapier: ClientRapierModule, world: ClientRapierWorld): void;
-}['hook'];
+type EngineBody = object;
+/** The schema's channel mapping for one collection, as `applyRecord` wants it. */
+type BodyChannels = readonly (readonly [PhysicsBodyChannel, string])[];
 /**
- * `joinRoom({ physics })` — the client half of the shared world-builder contract. Every function
- * here should be the very export the room config imports, so "same code both sides" stays
- * literally true.
+ * Everything an engine does, and nothing else. One adapter per blessed engine
+ * (`physics.ts` for Rapier, `physics2d.ts` for matter-js); the adapter owns its module handle,
+ * its world, and the game's engine-shaped options (`gravity`, `setup`, `bodies`, `intents`), so
+ * no engine type reaches this file.
  */
-interface ClientPhysicsOptions {
-    /** Must equal the room config's gravity (put it in the shared module). */
-    readonly gravity: ClientVector3;
-    /** 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: ClientRapierWorld, rapier: ClientRapierModule) => void;
-    /** Shape factories for the collections this client predicts (the room's `physics.bodies`). */
-    readonly bodies?: Readonly<Record<string, ClientBodyFactory>>;
-    /**
-     * 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, 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.
-     */
+interface EngineAdapter {
+    /** The module specifier, for the "failed to load" line. */
+    readonly engineName: string;
+    /** The `joinRoom` option these hooks came from (`physics`, `physics2d`), for warnings. */
+    readonly optionName: string;
+    /** The game's explicit timestep in seconds, when it set one. */
+    readonly timestep: number | undefined;
+    /** Loads the engine, builds the local world and runs `setup`. Rejects if the load fails. */
+    start(timestepSeconds: number): Promise<void>;
+    /** Drops the world. The core clears its own bookkeeping. */
+    free(): void;
+    /** Did the game pass a body factory for this collection? */
+    hasFactory(collection: string): boolean;
+    /** 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;
+    /** One fixed-timestep step of the local world. */
+    step(): void;
+    /** Server record → body state, in whatever order this engine's setters require. */
+    applyRecord(body: EngineBody, channels: BodyChannels, record: AnyRecord$2): void;
+    /** Body state → a 3D pose. A planar engine fills `z = 0` and a quaternion about Z. */
+    readPose(body: EngineBody, into: Pose): void;
+    /** The game's intent hook for an owned body, before one step. A no-op when it declared none. */
+    applyIntent(collection: string, body: EngineBody, instance: AnyRecord$2): void;
+    /**
+     * A per-step force applied to **every** local body of a collection, owned or not, after the
+     * intent pass. Present only on engines whose worlds do not apply gravity themselves: a matter2d
+     * room applies gravity per body from its own hooks, so a non-owned predicted crate would hang
+     * in the air through the whole lead without it. Rapier has no equivalent, and must not gain one.
+     */
+    settle?(collection: string, body: EngineBody, instance: AnyRecord$2): void;
+    /**
+     * The tolerance a velocity channel is compared against, given the position tolerance and the
+     * timestep. Rapier's velocities are per second (`epsilon / dt`); matter's are per step, and one
+     * step of a velocity error of `epsilon` is `epsilon` of position, so its answer is `epsilon`.
+     */
+    velocityTolerance(epsilon: number, timestepSeconds: number): number;
+}
+/** The engine-neutral tuning knobs; both engines' option objects carry these names. */
+interface PredictorTuning {
     readonly maxPredictedBodies?: 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
-     * quiet. Positions compare against `epsilon` world units directly; velocity channels compare
-     * against `epsilon / timestep` (a velocity disagreement matters by what it moves in one tick —
-     * an input frame landing one tick late on the server is invisible, not a storm). Default 0.05.
-     */
     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.
-     *
-     * A rebase can move a body that has already been drawn — because the server disagreed, or
-     * because a newly-flushed intent changed what the last few ticks should have been. Handing
-     * that straight to the renderer is a step, and a step in the middle of steady motion is what
-     * a player calls a yank. Instead the jump is taken out of the drawn pose and put into a
-     * per-body offset that decays: the character keeps moving smoothly and arrives at the truth a
-     * moment later.
-     *
-     * This smooths the **error**, not the motion. A rate limiter on the drawn position — the
-     * obvious version, and the one a game writes for itself — cannot tell a correction from the
-     * character running, so it lags real movement too. Nothing here touches motion the simulation
-     * actually produced.
-     */
     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.
-     *
-     * This is the teleport case: a respawn, an area change, a resync. Easing across one of those
-     * draws the body sliding through the level, which is worse than the step it avoids. It is the
-     * one number here that depends on how big a world unit is in your game.
-     */
     readonly smoothingSnapUnits?: number;
 }
 /** Counters for the report and `room.prediction.stats`. */
@@ -339,20 +344,53 @@ interface PredictionStats {
      * applied tick judges a stamped write.
      */
     stampGap: number;
+    /**
+     * The same gap before the `[0, RESIM_DEPTH]` clamp, smoothed the same way (bugs.md #47). A
+     * negative reading is a stamp that *trails* the server's application: the lead under-estimated
+     * the transit and the clamp is hiding it from `stampGap`. Diagnostic; the replay never reads it.
+     */
+    stampGapRaw: number;
+    /** The stamp the newest judged `WRITE` carried, and the server tick it was applied at. */
+    lastStampTick: number;
+    lastAppliedTick: number;
 }
-declare class PhysicsPredictor {
+/**
+ * One body's transform, as plain mutable objects: the ring below is overwritten every tick and
+ * must not allocate to do it.
+ */
+interface Pose {
+    readonly t: Vec;
+    readonly r: Quat;
+    readonly v: Vec;
+    readonly w: Vec;
+}
+type Vec = {
+    x: number;
+    y: number;
+    z: number;
+};
+type Quat = {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+};
+declare class Predictor {
     private readonly store;
-    private readonly options;
+    private readonly adapter;
+    private readonly tuning;
     private readonly meOf;
     private readonly rttOf;
     private readonly tickIntervalOf;
     private readonly log;
     readonly stats: PredictionStats;
-    private rapier;
-    private world;
+    /** True once the adapter's world exists. The `world !== undefined` of the one-engine version. */
+    private worldReady;
+    /** Seconds per step, fixed for the life of the world. */
+    private timestepSeconds;
     private readonly bodies;
-    /** Physics-backed entity collections, in schema order. */
-    private readonly collections;
+    /** 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;
@@ -379,6 +417,8 @@ declare class PhysicsPredictor {
     private renderTick;
     /** Scratch for one interpolated pose. `read()` is synchronous, so one is enough. */
     private readonly scratch;
+    /** Scratch for a direct body reading, so it never races `scratch`'s interpolated one. */
+    private readonly live;
     /** Scratch quaternions, so the per-body per-frame offset maths allocates nothing. */
     private readonly qa;
     private readonly qb;
@@ -397,11 +437,35 @@ declare class PhysicsPredictor {
     private gapMeasured;
     /** The newest stamp already folded into `stampGap`, so a repeated echo is not re-weighted. */
     private gapSampledThrough;
+    /** The lead the last rebase re-stepped, so a change in it can be folded into `stampGap`. */
+    private lastLead;
     private readonly predictedTicks;
     private readonly history;
-    /** History kept per body — comfortably past the resim depth. */
+    /**
+     * History kept per body: a correction for tick T is judged against the prediction recorded for
+     * T, and T is `lead` ticks behind the head when it arrives, so this has to clear `MAX_LEAD`
+     * with room for delivery jitter.
+     */
     private static readonly HISTORY_TICKS;
-    constructor(ext: AnySchema, store: ClientStore, options: ClientPhysicsOptions, meOf: () => string, rttOf: () => number, tickIntervalOf: () => number, log?: (message: string) => void);
+    constructor(ext: AnySchema, store: ClientStore, adapter: EngineAdapter, tuning: PredictorTuning, meOf: () => string, rttOf: () => number, tickIntervalOf: () => number, log?: (message: string) => void);
+    /**
+     * D50: re-derive the predicted-collection list from a rebuilt schema.
+     *
+     * This is deliberately shallow, and it is safe to be shallow because of the scope rule the
+     * supervisor enforces: **any change touching a physics collection classifies breaking**
+     * (`packages/supervisor/src/schema-swap.ts`), so a swap that reaches this method is guaranteed
+     * to leave every physics collection structurally identical. What changes is descriptor
+     * *identity*, not content, and this brings the predictor's references back in line with the
+     * store's rather than leaving two equal-but-distinct descriptor trees in play.
+     *
+     * The live bodies are dropped instead of retargeted, for the same reason the render buffers
+     * are: `reset()` follows immediately, the resync WELCOME re-seeds authority, and a body carried
+     * across a schema boundary is exactly the kind of thing that would look fine and be wrong.
+     *
+     * When the physics scope rule is lifted, this is where the real work goes: rebuilding each
+     * `PredictedBody.desc` and re-deriving collider shapes from the new descriptors.
+     */
+    swapSchema(newExt: AnySchema): void;
     get epsilon(): number;
     /** `true` once the engine is loaded and the local world exists. */
     get ready(): boolean;
@@ -437,6 +501,12 @@ declare class PhysicsPredictor {
      * write. Clamped into `[0, RESIM_DEPTH]`: a stamp taken before this client had any physics
      * authority is on the session's bare write counter rather than the server's tick stream, and
      * differencing the two clocks is meaningless — 0 is the old behaviour and the honest default.
+     *
+     * The floor is also load-bearing in a way that is not obvious, and `bugs.md` #45 is the
+     * measurement: a stamp can *trail* the server's application, when the lead over-estimates the
+     * transit, and correcting for that by letting the gap go negative delays every write's replay by
+     * the same amount. It buys an accurate stop and pays for it with a late start. The lever for
+     * that is the lead, not this.
      */
     noteWriteApplied(stampTick: number, appliedTick: number): void;
     /** Does the local world currently simulate `collection[id]`? */
@@ -444,8 +514,8 @@ declare class PhysicsPredictor {
     /**
      * 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
-     * channels against `epsilon / timestep`, because a velocity disagreement matters by what it
-     * moves in one tick.
+     * channels against the adapter's per-engine velocity tolerance, because a velocity
+     * disagreement matters by what it moves in one tick.
      */
     withinEpsilon(desc: CollectionDesc, fields: readonly string[], patch: AnyRecord$2, predicted: AnyRecord$2): boolean;
     /** Is `collection` one this client would predict at all (owned always; non-owned per D21)? */
@@ -565,43 +635,32 @@ declare class PhysicsPredictor {
     private warnOverCap;
     private warnOnce;
     /**
-     * The client's lead over authority, in ticks: the one-way transit the authority in hand has
-     * already spent in flight, rounded to the nearest tick. Nothing more.
-     *
-     * Every tick of lead beyond that transit is a tick of motion the client draws on the
-     * assumption that the input it is holding will still be held when the server gets there. On a
-     * release that assumption is wrong by construction, and the invented travel is handed back as
-     * a backwards yank — bug 1's "keeps moving after key up and then snaps back". It was
-     * `ceil(owd) + 1`, which on a fast link is two whole ticks of margin over a transit of nearly
-     * zero. Measured on the arena fixture at no injected latency (release overshoot of a 6 u/s
-     * held-input character, `physics-predict.test.ts`):
-     *
-     * | lead | drawn overshoot past the server's stop | worst backwards step |
-     * | --- | --- | --- |
-     * | `ceil(owd) + 1` (was) | 0.585 u | -0.585 u |
-     * | `max(1, round(owd))` (is) | 0.293 u | -0.292 u |
-     * | `round(owd)`, floor 0 | 0.0008 u | -0.0008 u |
+     * The client's lead over authority, in ticks: a full round trip, rounded to the nearest tick
+     * (bugs.md #47, Candidate A).
      *
-     * One tick of running is 0.3 u there: the overshoot is the lead, in ticks, and nothing else.
-     * On a link with no transit to cover, every tick of lead is a tick of guessing that the key is
-     * still held.
+     * The authority in hand left the server one one-way transit ago, so the server is at
+     * `authority + owd` right now, and an input flushed now reaches it another one-way transit
+     * later: the first tick it can take effect at is `authority + rtt`. The head has to be there
+     * for two reasons. The stamp is `head + 1`, and a stamp that names the tick the server will
+     * actually apply the write at is what lets the replay put a release where the server put it;
+     * with the head at half a round trip (server-now) the stamp trailed the application by
+     * `owd - 1` ticks, `stampGap`'s floor at zero discarded the sign, and every release was
+     * replayed a one-way transit late: the local body stopped, then followed authority forward for
+     * the rest of the round trip. And the intent the local body is simulating under is the intent
+     * the server will be simulating under at the same tick, which is the whole point of predicting.
      *
-     * The floor of 1 is not margin, it is the smallest lead that is still prediction. At 0 the
-     * rebase takes no steps: the local world is pinned to the authority it just received, which is
-     * already a tick old, so the client responds to its own input only when the next `CORRECT`
-     * arrives and every moving body reads as mispredicted by one tick of motion. Measured: the
-     * bot suites' correction-storm invariant fires immediately (21 corrections/s per bot against a
-     * threshold of 5 in `packages/cli/test/simulate-physics.test.ts`). One tick of speculation is
-     * the price of predicting at all; two was the bug.
+     * The price is the distance between the drawn body and the authority it is anchored to, which
+     * is the size of every misprediction the client has not been told about yet: a full round trip
+     * of motion instead of half. dive's lag budget states that distance against the round trip the
+     * test measures.
      *
-     * Erring low is also the cheap direction — a lead shorter than the transit means authority
-     * arrives slightly *ahead* of the prediction, and a correction that pulls the character the way
-     * it is already going is the one nobody can see.
-     *
-     * Measured earlier the same day (dive e2e): a *full*-round-trip lead was worse again
-     * (-1.4 to -1.8 u worst backwards step vs -0.6 at half), which is the same finding from the
-     * other end. `stats.stampGap` is the running check on all of this — it reports how far ahead
-     * of the server's application the stamps still land, and it should sit at 0.
+     * Erring high is still the expensive direction, and the rounding is to nearest for that reason:
+     * a lead longer than the real round trip is a tick of motion the client draws on the assumption
+     * that the input it is holding will still be held when the server gets there, and on a release
+     * that assumption is wrong by construction (bug 1's "keeps moving after key up and then snaps
+     * back"). `stats.stampGap` is the running check: it reports how far ahead of the server's
+     * application the stamps land, and `stampGapRaw` the same before the clamp. Both should sit
+     * between 0 and 1.
      */
     private leadTicks;
     private timestepMs;
@@ -611,8 +670,8 @@ declare class PhysicsPredictor {
      * 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 the shared resim depth: an outrun lead
-     * snaps to authority and counts (`stats.snaps`).
+     * judged write) before the first of them. Bounded by `MAX_LEAD`: an outrun lead snaps to
+     * authority and counts (`stats.snaps`).
      */
     private rebase;
     /**
@@ -632,6 +691,11 @@ declare class PhysicsPredictor {
      * tick this step predicts (during a rebase — see `rebase`'s replay walk), else the instance's
      * current values (free-run: plain state carries the newest local intent writes, which is
      * correct there because free-run steps are the ticks *after* every buffered write).
+     *
+     * Then, on an engine that declares one, the `settle` pass: a per-step force over **every**
+     * 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.
      */
     private applyIntents;
     /** Server record → body channels (the same mapping the runtime's sync uses, inverted). */
@@ -639,6 +703,447 @@ declare class PhysicsPredictor {
     private isF32;
 }
 
+/**
+ * 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
+ * where a matter.js type is touched.
+ *
+ * The loop is `predictor.ts`, shared byte for byte with the Rapier path. This file is the seam
+ * list, and it mirrors `packages/runtime/src/core/matter.ts` — the room's own matter world — the
+ * way `physics.ts` mirrors the Rapier runtime. Three things in it are load-bearing and none of
+ * them are visible from the loop:
+ *
+ * **The units are matter.js's, not translated.** `gravity` goes into `engine.gravity` verbatim
+ * (matter's own y is *down*), and a velocity is neither per second nor, strictly, per step:
+ * `Body.updateVelocities` normalises `body.velocity` against `Body._baseDelta`, a sixtieth of a
+ * second, whatever the engine's step is, and `Body.setVelocity` reads the same units back. The
+ * wire carries what the runtime writes, so the client reads and writes them unchanged, and
+ * `velocityTolerance` divides by `dt / baseDelta` rather than by `dt`. In a 60 Hz room those are
+ * the same thing and the tolerance is plain `epsilon`.
+ *
+ * **A rebase has to leave the body integrating from where it was put.** matter is a Verlet
+ * integrator: the next step's motion is `position - positionPrev`, so writing a position without
+ * moving `positionPrev` with it makes the whole jump this step's velocity. `Body.setPosition`
+ * shifts `positionPrev` by the same delta and `Body.setVelocity` re-derives it from the current
+ * position, which is why this uses the setters and follows `applyRecordToBody`'s order rather
+ * than assigning fields.
+ *
+ * **The timestep never varies.** `Body.update` scales a body's carried velocity by the ratio of
+ * consecutive deltas, so a constant delta makes that ratio 1. The same constant the room uses is
+ * the only safe one, which is why the predictor fixes it at start.
+ *
+ * ## `settle`
+ *
+ * A matter2d room applies gravity per body, from its own hooks, because `engine.gravity` is often
+ * zero (different bodies fall at different rates). An owned body gets that through `intents`. A
+ * non-owned predicted one — a crate the player stands on — has no intent hook and would hang in
+ * the air for the whole prediction lead, so `settle` runs the same per-step force over every local
+ * body of a collection, owned or not, after the intent pass. Rapier has no equivalent because
+ * engine gravity does that job there.
+ */
+
+type ClientMatterModule = typeof MATTER;
+type ClientMatterEngine = MATTER.Engine;
+type ClientMatterBody = MATTER.Body;
+type ClientMatterConstraint = MATTER.Constraint;
+interface ClientVector2 {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * What a client-side matter2d body factory returns — the same shape the room config's factories
+ * use. matter.js has no separate collider concept: a body *is* its geometry.
+ */
+interface ClientBody2dSpec {
+    readonly body: ClientMatterBody;
+    /** Added to the local world with the body, and removed with it. */
+    readonly constraints?: readonly ClientMatterConstraint[];
+}
+/**
+ * Method-syntax members check bivariantly, so a builder's factory or hook written against its own
+ * instance type (`(body, player: Player) => …`) is accepted — the values really passed are the
+ * schema's records for that collection.
+ */
+type ClientBody2dFactory = {
+    factory(matter: ClientMatterModule, instance: AnyRecord$2, id: string): ClientBody2dSpec;
+}['factory'];
+type ClientIntent2dHook = {
+    hook(body: ClientMatterBody, instance: AnyRecord$2, matter: ClientMatterModule, engine: ClientMatterEngine, timestep: number): void;
+}['hook'];
+/**
+ * `joinRoom({ physics2d })` — the client half of the shared world-builder contract for a matter2d
+ * room. A sibling of `physics`, not a variant inside it: passing both is an error at join, and the
+ * wire carries no engine name, so passing the *wrong* one is a game bug the client cannot detect.
+ * Every function here should be the very export the room config imports.
+ */
+interface ClientPhysics2dOptions {
+    /** 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`). */
+    readonly timestep?: number;
+    /** The shared static-geometry builder (the room's `physics.setup`). */
+    readonly setup?: (engine: ClientMatterEngine, matter: ClientMatterModule) => void;
+    /** Shape factories for the collections this client predicts (the room's `physics.bodies`). */
+    readonly bodies?: Readonly<Record<string, ClientBody2dFactory>>;
+    /**
+     * 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, ClientIntent2dHook>>;
+    /**
+     * A per-step force over **every** local body of a collection, owned or not, run after the whole
+     * intent pass. This is where a matter2d room's per-body gravity goes for the bodies nobody
+     * steers: without it a predicted crate stands still in mid-air for the length of the lead and
+     * is snapped back by every correction.
+     */
+    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.
+     */
+    readonly maxPredictedBodies?: 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 compare against what one step of the error
+     * would actually move the body by, which on a 60 Hz room is also `epsilon` (matter stores a
+     * velocity per sixtieth of a second, not per second). Default 0.05.
+     */
+    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 Rapier half of client-side physics prediction (D22 part 2, D21): `joinRoom({ physics })`'s
+ * option type, the lazy `@dimforge/rapier3d-compat` load, and the adapter that is the only place
+ * in the client where a Rapier type is touched.
+ *
+ * The loop itself — the free-run accumulator, the rebase replay, the pose ring, the render clock,
+ * the error smoothing and the D21 cap — lives in `predictor.ts` and knows about no engine at all.
+ * Read that file's header for what the predictor does and why; this one is the seam list:
+ * `loadEngine`, world construction and `setup`, the body factory and its warnings, `world.step()`,
+ * the record→body and body→pose mappings, the intent hook call, and the per-second velocity
+ * tolerance. `physics2d.ts` is the same list written against matter-js.
+ *
+ * The engine is loaded lazily via dynamic `import()`, so a game with no physics option — or one
+ * that predicts with matter2d — pays nothing for it.
+ */
+
+type ClientRapierModule = typeof RAPIER;
+type ClientRapierWorld = RAPIER.World;
+type ClientRapierBody = RAPIER.RigidBody;
+interface ClientVector3 {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/** What a client-side body factory returns — the same shape the room config's factories use. */
+interface ClientBodySpec {
+    readonly body: RAPIER.RigidBodyDesc;
+    readonly colliders?: readonly RAPIER.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 ClientBodyFactory = {
+    factory(rapier: ClientRapierModule, instance: AnyRecord$2, id: string): ClientBodySpec;
+}['factory'];
+type ClientIntentHook = {
+    hook(body: ClientRapierBody, instance: AnyRecord$2, rapier: ClientRapierModule, world: ClientRapierWorld): void;
+}['hook'];
+/**
+ * `joinRoom({ physics })` — the client half of the shared world-builder contract. Every function
+ * here should be the very export the room config imports, so "same code both sides" stays
+ * literally true.
+ */
+interface ClientPhysicsOptions {
+    /** Must equal the room config's gravity (put it in the shared module). */
+    readonly gravity: ClientVector3;
+    /** 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: ClientRapierWorld, rapier: ClientRapierModule) => void;
+    /** Shape factories for the collections this client predicts (the room's `physics.bodies`). */
+    readonly bodies?: Readonly<Record<string, ClientBodyFactory>>;
+    /**
+     * 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, 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.
+     */
+    readonly maxPredictedBodies?: 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
+     * quiet. Positions compare against `epsilon` world units directly; velocity channels compare
+     * against `epsilon / timestep` (a velocity disagreement matters by what it moves in one tick —
+     * an input frame landing one tick late on the server is invisible, not a storm). Default 0.05.
+     */
+    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.
+     *
+     * A rebase can move a body that has already been drawn — because the server disagreed, or
+     * because a newly-flushed intent changed what the last few ticks should have been. Handing
+     * that straight to the renderer is a step, and a step in the middle of steady motion is what
+     * a player calls a yank. Instead the jump is taken out of the drawn pose and put into a
+     * per-body offset that decays: the character keeps moving smoothly and arrives at the truth a
+     * moment later.
+     *
+     * This smooths the **error**, not the motion. A rate limiter on the drawn position — the
+     * obvious version, and the one a game writes for itself — cannot tell a correction from the
+     * character running, so it lags real movement too. Nothing here touches motion the simulation
+     * actually produced.
+     */
+    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.
+     *
+     * This is the teleport case: a respawn, an area change, a resync. Easing across one of those
+     * draws the body sliding through the level, which is worse than the step it avoids. It is the
+     * one number here that depends on how big a world unit is in your game.
+     */
+    readonly smoothingSnapUnits?: number;
+}
+
+/**
+ * D53 client side: the anonymous persistent identity, and the assertion exchange that keeps it
+ * out of the game.
+ *
+ * ## The one rule this module exists to enforce
+ *
+ * **The identity token never goes to a room socket.** It is stored in `localStorage`, sent to the
+ * control plane over HTTPS, and traded there for a short-lived, project-bound assertion. That
+ * assertion is the only thing that reaches the game.
+ *
+ * The reason matters more than the mechanism. Room code runs inside the game's own tenant, and a
+ * game you did not write is code you cannot vouch for — so anything the socket carries has to be
+ * worthless to a hostile game. An assertion is: it names one project (so it cannot be replayed
+ * against another game), it expires in minutes, and its subject is a per-project pseudonym, so
+ * two games holding assertions for the same person cannot tell that they do.
+ *
+ * ## What a game has to do
+ *
+ * ```ts
+ * const room = await joinRoom(schema, { identity: true });
+ * ```
+ *
+ * That is all. `joinRoom` mints an identity on first run, keeps it, exchanges it for an assertion
+ * before every HELLO — every reconnect included, because an assertion that outlives its exchange
+ * would be refused with `E_TOKEN_EXPIRED` — and `ctx.playerId` in room code is the stable
+ * `irt:<subject>` for that project.
+ *
+ * ## Storage, and what D61 changed about it
+ *
+ * `localStorage`, under ONE key per origin: `irtio.account`.
+ *
+ * It used to be one key per project (`irtio.identity.<project>`), so two games on one origin were
+ * two players. That was right while a credential WAS the player, and wrong the moment an account
+ * sat above it: the credential identifies a device, the account identifies the person, and what
+ * keeps two games from correlating a player is the per-project pseudonymous subject, which is
+ * derived at the control plane and owes nothing to how many keys a browser holds. Splitting the
+ * credential per project bought no privacy and cost the player an account per game.
+ *
+ * A value left under the old key is ADOPTED on first run and the old key is removed. A migrated
+ * identity is already an account (the migration backfilled one per identity with the identity's
+ * own id), so adopting it is a rename of a storage key and the player keeps every board position
+ * they had.
+ *
+ * The honest limits are unchanged and they are why linking exists: a player clearing site data is
+ * a new player, a private window is a new player, and a different browser is a different player
+ * until they link it. `linkCode()` and `redeemLinkCode()` are how a second device stops being a
+ * second player.
+ *
+ * Every storage access is wrapped: `localStorage` throws outright in some embedded contexts, and
+ * an identity that cannot be stored should degrade to an ordinary key join rather than take the
+ * game down.
+ */
+/** The `localStorage` key: one credential per origin, whatever the project (D61). */
+declare const ACCOUNT_STORAGE_KEY = "irtio.account";
+/**
+ * The pre-D61 per-project key, kept only so a returning player's credential can be adopted once
+ * and then removed. Nothing writes this any more.
+ */
+declare function identityStorageKey(project: string): string;
+interface IdentityOptions {
+    /** The project key. Defaults to the schema's, exactly as `joinRoom` resolves it. */
+    readonly project: string;
+    /**
+     * The control plane's HTTPS origin. Defaults to `https://irt.io` — the apex where the control
+     * API lives (D-single-origin). A local `irtio dev` has no control plane at all, so a game
+     * testing identities against one must pass this.
+     */
+    readonly controlUrl?: string | undefined;
+    /** Injected in tests; `fetch` otherwise. */
+    readonly fetch?: typeof fetch | undefined;
+    /**
+     * Where the identity token is kept. Defaults to `localStorage`. A game with its own storage
+     * (a native shell, an extension) can supply one; a game that passes `null` keeps the identity
+     * only for the life of the page.
+     */
+    readonly storage?: IdentityStorage | null | undefined;
+}
+interface IdentityStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** The default control origin: the apex that serves both the site and the control API. */
+declare const DEFAULT_CONTROL_URL = "https://irt.io";
+declare class IdentityError extends Error {
+    readonly code: string;
+    readonly name = "IdentityError";
+    /**
+     * How long the control plane asked us to wait, in milliseconds, when it said so. Only ever set
+     * on `E_IDENTITY_RATE_LIMITED`: a rate limit is a wait, not an outage, and a game that cannot
+     * tell the two apart drops to its offline path forever over a sixty-second backoff (bug #36).
+     */
+    readonly retryAfterMs?: number | undefined;
+    constructor(code: string, message: string, retryAfterMs?: number | undefined);
+}
+/** The distinct code a 429 from the control plane produces. */
+declare const E_IDENTITY_RATE_LIMITED = "E_IDENTITY_RATE_LIMITED";
+/**
+ * The longest `ensure()` will sit and wait before retrying a mint. Past this the wait is longer
+ * than any game's patience, so the caller gets the named error with `retryAfterMs` attached and
+ * decides for itself — sleeping for minutes inside a join is worse than saying why.
+ */
+declare const MAX_IDENTITY_RETRY_WAIT_MS = 60000;
+/**
+ * A player's identity for one project, and the assertion provider `joinRoom` hands the session.
+ *
+ * One instance per project per page. It caches the current assertion and re-exchanges when it is
+ * close to expiring, so a reconnect storm does not become an exchange storm.
+ */
+declare class Identity {
+    private readonly project;
+    private readonly controlUrl;
+    private readonly fetchImpl;
+    private readonly storage;
+    private token;
+    private accountId;
+    private cached;
+    private inFlight;
+    constructor(options: IdentityOptions);
+    /**
+     * Reads the stored credential, adopting a pre-D61 per-project one if that is all there is.
+     *
+     * Adoption is a rename and nothing more: migration 020 gave every pre-D61 identity an account
+     * whose id is the identity's own id, so the credential that was this player on this project is
+     * already this player's account credential everywhere. Moving it to the origin-wide key is what
+     * makes the same person on the same browser one player across the games on that origin.
+     *
+     * The old key is removed after a successful adoption. If the write fails (a storage that reads
+     * but will not write), the old value is used anyway and adoption is retried next time, which is
+     * the same degrade-quietly rule the rest of this module follows.
+     */
+    private load;
+    /** The stored identity token, or `undefined` before the first mint. Never sent to a room. */
+    get stored(): string | undefined;
+    /** The player id the room will see, once an assertion has been fetched. */
+    get playerId(): string | undefined;
+    /**
+     * Mints an identity if this browser has none, and returns the token.
+     *
+     * A mint refused with 429 is retried ONCE, after the window the control plane named, as long as
+     * that window is short enough to wait out (`MAX_IDENTITY_RETRY_WAIT_MS`). Everything else — and
+     * a second refusal — throws, and a rate limit throws `E_IDENTITY_RATE_LIMITED` with
+     * `retryAfterMs` rather than the unreachable-control-plane code, so a game can tell "wait" from
+     * "gone" (bug #36).
+     */
+    ensure(): Promise<string>;
+    private mint;
+    /**
+     * A currently-valid assertion for this project, exchanging one if the cached one is gone or
+     * within thirty seconds of expiry.
+     *
+     * The margin is what keeps a long reconnect from presenting a token that expires mid-handshake.
+     * Concurrent callers share one exchange, so a burst of reconnects is one HTTP request.
+     */
+    assertion(now?: number): Promise<string>;
+    private exchange;
+    /** Drops the stored identity. The next `ensure()` mints a new player. */
+    forget(): void;
+    /**
+     * Asks the control plane for a link code to read out on another device.
+     *
+     * The code is short and typable because a person carries it between two screens. Show it, do
+     * not store it, and let it expire: a code left on a screen for the ten minutes it lives is the
+     * one thing about this that a player controls.
+     */
+    linkCode(): Promise<{
+        code: string;
+        expiresInMs: number;
+    }>;
+    /**
+     * Redeems a code read off another device, and **replaces** this browser's credential with a new
+     * one on that code's account.
+     *
+     * Two things happen in that order and both matter. The new credential is stored first, so a
+     * failure between the two leaves the player linked rather than credential-less. Then whatever
+     * this browser used to be is retired on the account it is leaving.
+     *
+     * **That retirement deletes the old account when this was its only device**, rather than
+     * revoking the credential and walking away. Revoking the last device leaves an account nothing
+     * can ever authenticate as, whose board rows and saved games are then unreachable by the player
+     * and undeletable by anyone. An account with other devices only loses this one.
+     *
+     * So this call can destroy the progress held on THIS browser. Warn the player first; the docs
+     * page has wording for it. The retirement is best-effort: if it fails the link still stands,
+     * because failing a link that already worked is the worse direction.
+     */
+    redeemLinkCode(code: string): Promise<{
+        account: string;
+    }>;
+    /** The devices on this account: ids and timestamps, plus which one this browser is. */
+    devices(): Promise<{
+        account: string;
+        self: string;
+        devices: {
+            id: string;
+            createdAt: string;
+            lastSeen: string;
+        }[];
+    }>;
+    /**
+     * Revokes one device on this account. Revoking the device this browser IS leaves this instance
+     * holding a credential the control plane no longer knows, so it forgets it: the next `ensure()`
+     * mints a fresh player rather than looping on a refused exchange.
+     */
+    revokeDevice(deviceId: string): Promise<void>;
+    /**
+     * Deletes this account and everything keyed on it, in every project it played, and forgets the
+     * credential. There is no undo and the control plane does not keep a copy.
+     */
+    deleteAccount(): Promise<void>;
+    /** The account id, once anything has told us what it is. Opaque; never parse it. */
+    get account(): string | undefined;
+    /** One authenticated account-route call: credential in the header, project in the query. */
+    private accountFetch;
+    private post;
+}
+
 /**
  * A client-side entity collection: the read API of `@irtio/schema`'s `ReadonlyCollection`, plus
  * index sugar so `state.players[room.me]` reads the same as `state.players.get(room.me)`.
@@ -722,6 +1227,16 @@ interface RoomEvents {
     status: Status;
     error: RoomError;
     correct: Correction;
+    /**
+     * Fires whenever the built-in presence collection changes (someone joins or leaves, or a
+     * presence field updates), carrying the same array `room.clients` returns.
+     */
+    clients: readonly PresenceRecord[];
+    /**
+     * Fires after each `PONG` updates the smoothed round-trip time, about every `PING_INTERVAL_MS`
+     * (2s), carrying the same value `room.rtt` returns.
+     */
+    rtt: number;
 }
 type Unsubscribe = () => void;
 /**
@@ -797,12 +1312,32 @@ interface JoinOptions<S, Role extends string = string> {
      * back a fresh token when the old one nears expiry. Omitted ⇒ the key-only join, unchanged.
      */
     readonly token?: string | (() => string | Promise<string>);
+    /**
+     * D53: join under an irtio anonymous persistent identity. `true` mints one on this browser's
+     * first run, stores it, and exchanges it for a short-lived project-bound assertion before
+     * every HELLO; an `Identity` instance is used as-is, so several joins can share one.
+     *
+     * `ctx.playerId` in room code becomes a stable `irt:<subject>` that survives reconnection,
+     * hibernation and closing the tab — which is what a leaderboard keys on.
+     *
+     * The identity token itself never reaches the room. What rides the socket is the assertion:
+     * bound to this one project, valid for minutes, and carrying a per-project pseudonym rather
+     * than a platform id, so the game learns nothing about the player anywhere else. That is a
+     * deliberate property and not an accident of the implementation — see `identity.ts`.
+     *
+     * Mutually exclusive with `token`: a join asserts one identity, and a client offering two
+     * would be asking the server to pick.
+     */
+    readonly identity?: boolean | Identity;
+    /** D53: the control plane origin the identity exchange talks to. Defaults to https://irt.io;
+     *  a local `irtio dev` has no control plane, so testing identities locally needs this. */
+    readonly controlUrl?: string;
     readonly onStatus?: (status: Status) => void;
     /** Hard cap on the owned-write flush window, in ms. Default 50. */
     readonly writeIntervalMs?: number;
     /**
      * How far behind arrival `room.render` draws non-owned entities, in ms (D20). Default:
-     * `2 × tickIntervalMs` (the room's tick interval, learned from `WELCOME`), floored at 50 ms.
+     * `2000 / tickRate` (twice the room's tick interval, learned from `WELCOME`), floored at 50 ms.
      */
     readonly interpDelayMs?: number;
     /**
@@ -814,12 +1349,25 @@ interface JoinOptions<S, Role extends string = string> {
      * code-splits keeps Rapier out of the critical path entirely.
      */
     readonly physics?: ClientPhysicsOptions;
+    /**
+     * D57: the same contract for a matter2d room — `setup`, `bodies`, `intents`, plus `settle`,
+     * the per-step pass over every local body of a collection that gives a crate nobody owns its
+     * gravity. A sibling of `physics` rather than a variant inside it, because the two engines
+     * 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;
     /** @internal */
     readonly transport?: Transport;
     /** @internal */
     readonly scheduler?: Scheduler;
     /** @internal */
     readonly onFrame?: FrameHook;
+    /**
+     * D65: keep a bandwidth ledger for this session, readable as `room.profile`. Off by default and
+     * free when off. A development and diagnostics surface, not something to ship enabled.
+     */
+    readonly profile?: boolean;
 }
 /** `joinRelay` options: a relay room has no schema, so there is no state and no RPC. */
 interface JoinRelayOptions {
@@ -842,6 +1390,20 @@ interface JoinRelayOptions {
 type MessageTarget = 'all' | string | {
     readonly role: string;
 };
+/**
+ * D65: the client's view of where its bytes went, by collection and field.
+ *
+ * A client cannot tell area-of-interest churn from a real spawn — after the encode the two are
+ * the same bytes, and only the server knows which ops it synthesised. So every add and remove in
+ * a `spatial-grid` collection lands under `churn` here, and surfaces that show it say
+ * `enter/leave (incl. spawns)` rather than pretending otherwise.
+ */
+interface RoomProfile {
+    /** Cumulative bytes since the socket opened, by row. */
+    total(): _irtio_protocol.ProfileSnapshot;
+    /** Bytes per second over a rolling window of about a second. */
+    perSecond(): _irtio_protocol.ProfileSnapshot;
+}
 /**
  * Default D21 cap on non-owned predicted bodies per client.
  *
@@ -897,6 +1459,11 @@ interface Room<S, Role extends string = RoleOf<S> & string> {
     readonly link: string;
     /** The last server tick this client saw. */
     readonly tick: number;
+    /**
+     * The room's configured client cap (`WELCOME`), or `0` when unknown (a relay-only server
+     * predating this field).
+     */
+    readonly maxClients: number;
     readonly status: Status;
     /** Round-trip time in ms from the last `PING`/`PONG`, or 0 before the first one. */
     readonly rtt: number;
@@ -920,6 +1487,12 @@ interface Room<S, Role extends string = RoleOf<S> & string> {
      * counters the bot runtime and the demos report.
      */
     readonly prediction?: PredictionStatus;
+    /**
+     * D65: this session's bandwidth ledger, present only when the join passed `profile: true`.
+     * `total()` is cumulative since the socket opened; `perSecond()` is a rolling window of about a
+     * second, advanced on the session's own clock each time it is read.
+     */
+    readonly profile?: RoomProfile;
     readonly call: RoomCallProxy<S>;
     /** Convenience alias for `room.call.requestOwnership`. */
     requestOwnership(entity: string, id: string): Promise<boolean>;
@@ -934,6 +1507,11 @@ interface Room<S, Role extends string = RoleOf<S> & string> {
 interface RelayRoom {
     readonly me: string;
     readonly id: string;
+    /**
+     * The room's configured client cap (`WELCOME`), or `0` when unknown (a relay-only server
+     * predating this field).
+     */
+    readonly maxClients: number;
     readonly link: string;
     readonly status: Status;
     /** Round-trip time in ms from the last `PING`/`PONG`, or 0 before the first one. */
@@ -987,6 +1565,130 @@ declare function roomIdFrom(roomOrLink: string): string;
  */
 declare function linkForUrl(wsUrl: string, roomId: string): string;
 
+/**
+ * D52 client side: `matchRoom` — quick-match, then join.
+ *
+ * This is sugar over two things the SDK already does: one HTTP POST to the control plane, and
+ * `joinRoom({ room })` with the code it answers. Nothing about the join differs from a friend
+ * sharing a link, which is the property the whole design is built on — the room neither knows nor
+ * cares that a matchmaker filled it.
+ *
+ * The wait is a long poll, so the request simply takes as long as the queue takes. A queue that
+ * never fills answers "no match" at the deadline and `matchRoom` throws `E_NO_MATCH` rather than
+ * silently dropping the player somewhere: a matchmaker that quietly degrades is one nobody can
+ * debug, and a game that wants to show "still looking…" needs to be told.
+ */
+
+declare class MatchError extends Error {
+    readonly code: string;
+    readonly name = "MatchError";
+    constructor(code: string, message: string);
+}
+interface MatchOptions {
+    /** The queue to join. Omitted uses the project's `default` queue (party of two). */
+    readonly queue?: string;
+    /**
+     * D63-g: a party code from `createParty`, so this player queues with their friends.
+     *
+     * Every member sends the same code with their own call. Nobody sends anybody else's identity:
+     * a device credential is a secret that never leaves the browser that minted it, so a party is
+     * a code you read out rather than a list you assemble.
+     *
+     * The queue fills only when the whole party is waiting, and the members land on consecutive
+     * seats. A party bigger than the queue is refused with `E_PARTY_TOO_BIG` at the first call.
+     */
+    readonly party?: string;
+    /**
+     * How long to wait before giving up, in milliseconds. The control plane caps this at two
+     * minutes and applies its own default (30 s) when omitted.
+     */
+    readonly timeoutMs?: number;
+    /** The control plane origin. Defaults to `https://irt.io`. */
+    readonly controlUrl?: string;
+    /** Injected in tests. */
+    readonly fetch?: typeof fetch;
+}
+/** What the queue answered. `seat` is a 0-based index into the party in arrival order. */
+interface MatchTicket {
+    readonly room: string;
+    readonly queue: string;
+    /**
+     * 0-based position in the party, in arrival order — **or `-1` for a backfill answer**, where
+     * arrival order among a running room's players is not something the matchmaker knows.
+     *
+     * A game that uses `seat` as an index has to handle the `-1`. It is a value that cannot be
+     * mistaken for a position, rather than an absent field, precisely so that a game which forgets
+     * gets an obviously wrong answer instead of a plausible one.
+     */
+    readonly seat: number;
+    readonly size: number;
+    /**
+     * True when this is a seat in a room that is already running rather than a fresh code.
+     *
+     * The room may fill before you get there — the matchmaker is working from an occupancy reading a
+     * few seconds old — so a join off a backfill ticket can be refused with `E_ROOM_FULL`.
+     * `matchRoom` handles that for you by queueing again, once.
+     */
+    readonly backfill: boolean;
+}
+/**
+ * Queues for a game and resolves with the room code when the party fills.
+ *
+ * The identity, when one is supplied, is what gives the queue its one-ticket-per-player rule: a
+ * player cannot fill a queue with themselves. Without one the queue falls back to limiting by
+ * address, which is weaker (two players behind one NAT share a bucket) and is the honest reason
+ * to adopt identities before shipping a quick-match button.
+ */
+declare function findMatch(project: string, options?: MatchOptions & {
+    readonly identity?: string;
+}): Promise<MatchTicket>;
+/** What `createParty` answers with. */
+interface PartyTicket {
+    /** The code every member sends with their own `matchRoom` call. Readable out loud. */
+    readonly party: string;
+    /** How long the code stays good for. Ten minutes today. */
+    readonly expiresInMs: number;
+}
+/**
+ * Mints a party code so a group can queue together (D63-g).
+ *
+ * ```ts
+ * const { party } = await createParty(schema.project, { size: 2 });
+ * // read `party` out to your friend, then both of you:
+ * const room = await matchRoom(schema, { queue: '2v2', party });
+ * ```
+ *
+ * A code rather than a list of members, and the reason is worth knowing: an identity is a secret
+ * that never leaves the browser that minted it, so there is no way for one player to hold
+ * another's, and a ticket that claimed to speak for several players would be forgeable. Nobody
+ * proves anything about anybody here — the matcher simply groups the tickets that carry the same
+ * code — and the worst a guessed code can do is put a stranger in your game, which is what
+ * quick-match does anyway.
+ *
+ * The code expires after `expiresInMs`. Expiry stops new members joining the party; members who
+ * are already queued keep their tickets.
+ */
+declare function createParty(project: string, options: {
+    readonly size: number;
+} & Pick<MatchOptions, 'controlUrl' | 'fetch'>): Promise<PartyTicket>;
+/**
+ * Quick-match, then join: the one call a quick-play button needs.
+ *
+ * ```ts
+ * const room = await matchRoom(schema);            // two strangers, one room, no code
+ * const room = await matchRoom(schema, { queue: '1v1', identity: true });
+ * ```
+ *
+ * With `identity: true` the player is minted an anonymous persistent identity (once, ever, stored
+ * in `localStorage`), the queue enforces one ticket per identity, and the room sees a stable
+ * `ctx.playerId` — which is what a leaderboard needs to key on.
+ */
+declare function matchRoom<S extends AnySchema, Role extends string = RoleOf<S> & string>(schema: S, options?: MatchOptions & JoinOptions<S, Role> & {
+    role?: RoleOf<S> & string;
+} & {
+    readonly identity?: boolean;
+}): Promise<Room<S, Role>>;
+
 /**
  * The default `Scheduler`. In a browser the write batcher aligns to `requestAnimationFrame` (one
  * `WRITE` per rendered frame, which is what a game loop produces); everywhere else — and as a
@@ -1024,32 +1726,83 @@ declare const webSocketTransport: Transport;
 
 type AnyRecord$1 = Record<string, unknown>;
 declare class RenderStore {
-    private readonly ext;
+    /** D50: not `readonly` — a schema swap replaces it in place (`swapSchema`). */
+    private ext;
     private readonly store;
     private readonly meOf;
     private readonly now;
     private readonly delayMs;
+    /** The room's tick interval from `WELCOME`; 0 means unknown (pre-week-8 server). */
+    private readonly intervalMs;
     /** collection → id → buffered keyframes. Only interpolating entity collections have entries. */
     private readonly buffers;
     private readonly descs;
+    /** Live collection facades by name, so a D50 swap can retarget rather than replace them. */
+    private readonly facades;
     /** The object handed out as `room.render`; identity survives a resync. */
     readonly view: AnyRecord$1;
     /** Render reads that ran past the newest delta and held it (buffer starvation, D20). */
     starved: number;
     /** D22 part 2: set when the session predicts physics bodies; render reads consult it first. */
     private predictor;
-    constructor(ext: AnySchema, store: ClientStore, meOf: () => string, now: () => number, delayMs: () => number);
+    /**
+     * The offset between the server's tick clock and this client's `now()`: a frame for tick `n`
+     * is stamped `base + n × intervalMs`. Undefined until the first delta of a connection.
+     */
+    private base;
+    /** `now()` at the last `base` move; bounds how far the upward drift correction may go. */
+    private baseAt;
+    constructor(
+    /** D50: not `readonly` — a schema swap replaces it in place (`swapSchema`). */
+    ext: AnySchema, store: ClientStore, meOf: () => string, now: () => number, delayMs: () => number, 
+    /** The room's tick interval from `WELCOME`; 0 means unknown (pre-week-8 server). */
+    intervalMs: () => number);
+    /**
+     * D50: rebuild against `newExt`, keeping `view`'s identity and every collection facade behind
+     * it, exactly as `ClientStore.swapSchema` does.
+     *
+     * Every interpolation buffer is dropped. A keyframe is a plain record whose fields were laid
+     * out by the old descriptor, and `lerpRecord` walks `desc.fields` — interpolating an old
+     * keyframe against a new one under the new field list is precisely the silent misread this
+     * whole part exists to avoid. `seedSnapshot`, called moments later off the resync WELCOME,
+     * re-seeds one keyframe per entity, which is the same state the buffers would have started
+     * from on a reconnect.
+     */
+    swapSchema(newExt: AnySchema): void;
     /**
      * Seeds one keyframe per existing entity from a `WELCOME` snapshot, backdated by the delay so
      * the world is visible immediately (the join snapshot is the render baseline, not a change to
      * ease towards).
      */
     seedSnapshot(): void;
-    /** Buffers every entity a `DELTA` touched, stamped with its arrival time. Call after apply. */
+    /**
+     * Maps `tick` onto the client clock, or returns `undefined` when the tick interval is unknown
+     * and the caller must fall back to arrival stamping.
+     *
+     * The offset is the minimum of `now() − tick × intervalMs` over the connection: the least
+     * delayed delta seen so far is the best evidence of where the server's tick clock sits, and
+     * every later delta is that plus its own queueing delay. So a better sample is taken
+     * immediately, a worse one only bleeds in at drift speed, and a discontinuity larger than the
+     * render window (hibernation wake, a backgrounded tab's clock jump, a tick stall) is a new
+     * clock rather than a late frame and snaps.
+     */
+    private stampFor;
+    private snapMs;
+    /**
+     * Buffers every entity a `DELTA` touched, stamped on the server's tick clock so delivery
+     * burstiness cannot modulate the drawn velocity. Call after apply.
+     */
     recordDelta(delta: Delta): void;
+    /**
+     * Appends one keyframe, keeping `frames` strictly ascending in `t` — `prune` and the lerp both
+     * depend on it. Two constraints meet here: the hybrid spatial encode sends two DELTA frames for
+     * a single tick, whose tick-derived stamps are equal, so the second one replaces rather than
+     * appends; and an offset that just snapped backwards must not stamp behind what is buffered.
+     */
+    private pushFrame;
     private bufferFor;
     private renderTime;
-    attachPredictor(predictor: PhysicsPredictor): void;
+    attachPredictor(predictor: Predictor): void;
     /** The interpolated (or predicted, or authoritative) value of `collection[id]` right now. */
     get(desc: CollectionDesc, id: string): unknown;
     /** Is `collection[id]` visible at the render clock? */
@@ -1061,7 +1814,8 @@ declare class RenderStore {
     /** Drops frames the render clock has passed, keeping the newest one at-or-before `renderT`. */
     private prune;
     private gc;
-    private buildView;
+    /** See `ClientStore.buildViewInto`: same contract, same reasons, one object reused forever. */
+    private buildViewInto;
 }
 
 /**
@@ -1098,35 +1852,64 @@ interface SessionOptions {
      * resume that outlives its token would otherwise be refused with `E_TOKEN_EXPIRED`.
      */
     readonly token?: string | (() => string | Promise<string>) | undefined;
+    /**
+     * D53: a provider for the platform identity assertion this session presents at HELLO.
+     *
+     * Always a function, never a string, and that is the point: an assertion lives for minutes
+     * and a session lives for as long as the player plays, so a reconnect an hour in has to be
+     * able to fetch a fresh one. A fixed string would be a session that dies at its first long
+     * disconnect with `E_TOKEN_EXPIRED`.
+     */
+    readonly assertion?: (() => string | Promise<string>) | undefined;
     readonly role?: string | undefined;
     readonly name?: string | undefined;
     readonly rpc?: Readonly<Record<string, ClientImpl>> | undefined;
     readonly writeIntervalMs?: number | undefined;
-    /** Render delay for `room.render` (D20). Default `max(50, 2 × tickIntervalMs)`. */
+    /** Render delay for `room.render` (D20). Default `max(50, 2000 / tickRate)`. */
     readonly interpDelayMs?: number | undefined;
     /** 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 transport?: Transport | undefined;
     readonly scheduler?: Scheduler | undefined;
     readonly onFrame?: FrameHook | undefined;
+    /** D65: keep a bandwidth ledger for this session. */
+    readonly profile?: boolean | undefined;
     readonly onStatus?: ((status: Status) => void) | undefined;
     /** `true` in a browser with no explicit `room` option: `?room=` gets written back. */
     readonly publishLocation: boolean;
 }
 declare class Session {
     private readonly options;
-    readonly ext: AnySchema;
+    /**
+     * D50: not `readonly`. `swapSchema` replaces it when an additive deploy hands this session a
+     * new descriptor mid-flight. Everything that decodes a frame reads it through `this`, so the
+     * single assignment below is what actually moves the session onto the new schema.
+     */
+    ext: AnySchema;
     readonly store: ClientStore;
     readonly render: RenderStore;
-    /** `true` when the join passed `physics` and the schema has body-backed collections. */
+    /** `true` when the join passed an engine option and the schema has body-backed collections. */
     readonly predictionRequested: boolean;
     /**
-     * Present once `./physics.js` has loaded (dynamic import — the predictor code, like the
-     * engine, costs a non-physics game zero bytes). Reads fall back to interpolation until then.
+     * Present once the engine's adapter module has loaded — `./physics.js` for `physics`,
+     * `./physics2d.js` for `physics2d`, each behind a dynamic import, so the predictor code and its
+     * engine cost a non-physics game (or the other engine's game) zero bytes. Reads fall back to
+     * interpolation until then.
+     */
+    predictor: Predictor | undefined;
+    /** The schema the `CALL`/`REPLY` rpc id space indexes into. D50: swappable, see `swapSchema`. */
+    private rpcSchema;
+    /**
+     * The BUILDER schema this session is currently on: `options.schema` at construction, then
+     * 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.
      */
-    predictor: PhysicsPredictor | undefined;
-    /** The schema the `CALL`/`REPLY` rpc id space indexes into. */
-    private readonly rpcSchema;
+    private schema;
+    /** D50: how many times this session has swapped schema. Test seam and a diagnostic. */
+    schemaSwaps: number;
     private readonly transport;
     private readonly scheduler;
     private readonly writeIntervalMs;
@@ -1144,7 +1927,10 @@ declare class Session {
      */
     writeTick: number;
     /** The room's tick interval from `WELCOME`, or 0 when unknown (relay / pre-week-8 server). */
+    /** Milliseconds per tick, derived from the rate in `WELCOME`. 0 when the room has no tick. */
     tickIntervalMs: number;
+    /** The room's client cap from `WELCOME`, or 0 when unknown (relay / pre-this-field server). */
+    maxClients: number;
     rtt: number;
     status: Status;
     private socket;
@@ -1169,6 +1955,20 @@ declare class Session {
     private readonly pending;
     private readonly listeners;
     private readonly messageListeners;
+    /**
+     * D51: voice signaling listeners, kept in their own set rather than sharing `messageListeners`.
+     *
+     * The isolation clause has a client half as well as a server half. The supervisor guarantees that
+     * a room handler never observes `{ kind: 'voice' }`; this set is what guarantees the same for a
+     * *game*, which holds the other end of the same socket and whose `room.onMessage` would otherwise
+     * receive every transport parameter and DTLS fingerprint in the call. Splitting the sets makes
+     * the property structural — there is no `!== 'voice'` filter to forget somewhere in the fan-out,
+     * and no ordering between two callbacks to get wrong.
+     *
+     * Nothing on the public `Room` type can reach this set. `joinVoice` gets at it through
+     * `INTERNAL_SESSION`, the same route the D50 tests use for the session itself.
+     */
+    private readonly voiceListeners;
     private cancelFlush;
     private cancelPing;
     private cancelRetry;
@@ -1191,10 +1991,78 @@ declare class Session {
     private fatal;
     private onSocketClosed;
     private stopTimers;
+    /**
+     * D65: the session's bandwidth ledger, present only when the join asked for one. A second
+     * consumer of the same seam `onFrame` uses (the bots' observer is the first), so the two
+     * compose rather than compete.
+     */
+    readonly ledger: ProfileLedger | undefined;
+    /** D65: the rolling window `room.profile.perSecond()` reads, advanced on the session clock. */
+    private profileWindow;
+    /**
+     * D65: bytes per second over a rolling window of about a second, measured on the scheduler's
+     * clock rather than `Date.now()` so a test with a fake clock gets a deterministic answer.
+     *
+     * The window advances only when somebody reads it: a reader at 1 Hz (the overlay) gets a
+     * one-second window, and a reader that never calls costs nothing. A read sooner than a second
+     * after the last one is extrapolated from the partial window rather than returning zeros.
+     */
+    profilePerSecond(): ProfileSnapshot;
     private send;
     private onFrame;
     /** A frame we could not decode or apply. Reported, never fatal: the stream may recover. */
     private localError;
+    /**
+     * D50: a `SCHEMA` frame landed. The server sends one during an additive `migrate` deploy, after
+     * the old worker has stopped sending and before the resync WELCOME, so this session can stay
+     * open across a deploy instead of being closed with `E_SCHEMA_MISMATCH`.
+     *
+     * A decode failure here is reported as a non-fatal error and the swap is abandoned. That leaves
+     * the session on the old schema with a resync WELCOME about to arrive under the new one, which
+     * it will fail to decode — noisy, but noisy is the correct failure: the alternative is decoding
+     * it anyway under the wrong descriptor, and a misdecode is silent.
+     */
+    private onSchema;
+    /**
+     * The one entry point for a mid-session schema change. Internal: not part of the public client
+     * API this release, and not called from anywhere but `onSchema`.
+     *
+     * **What is rebuilt.** Every schema-derived handle in the client, top down:
+     *
+     *  - `schema` / `ext` / `rpcSchema` here, which is what every `decodeDelta`, `encodeDelta`,
+     *    `decodeSnapshot` and rpc-id lookup reads through;
+     *  - `descsByName`, the correction path's collection index, invalidated so it re-derives;
+     *  - `ClientStore`: `ext`, its descriptor map, `plain`, `tracked`, and the per-collection
+     *    facades behind `room.state` — retargeted, not replaced;
+     *  - `RenderStore`: the same, plus every interpolation buffer;
+     *  - `PhysicsPredictor`, when one exists: its predicted-collection list and its live bodies.
+     *
+     * **What is dropped, and why** (part 4 plan §1.3). Everything below is state that was laid out
+     * by the old descriptors and has no correct reading under the new ones. The resync WELCOME
+     * arriving immediately after re-establishes all of it, which is what makes dropping cheap:
+     *
+     *  - the authoritative state (`plain`) and its tracked proxy tree — re-seeded by `loadSnapshot`;
+     *  - flushed-but-unjudged writes, the evicted-tick watermark and the baseline intents — a
+     *    resync already discards these (see `ClientStore.loadSnapshot`), and their field names are
+     *    indexed against descriptors that no longer exist;
+     *  - every render interpolation keyframe — `lerpRecord` walks `desc.fields`, so mixing a
+     *    pre-swap keyframe with a post-swap one is a silent misread. `seedSnapshot` re-seeds from
+     *    the WELCOME;
+     *  - every predicted body and its pose ring — `PhysicsPredictor.reset()`'s existing job.
+     *
+     * **What is deliberately NOT dropped: in-flight calls** (§1.2, the default rule). A `PendingCall`
+     * captured its `returns` descriptor at the moment it was issued, and the REPLY it is waiting for
+     * was produced by a room that had those params in hand. So a call issued before the swap keeps
+     * decoding its reply under the schema it was issued with, and resolves normally afterwards. This
+     * costs nothing to implement — the descriptor is already captured per call rather than looked up
+     * at reply time — and it is the honest semantics: the call did happen, under the old contract.
+     *
+     * The narrow case this leaves is a REPLY whose *shape* changed additively between the two
+     * schemas. Decoding it under the old `returns` reads the fields the caller asked for and stops,
+     * which is exactly what an appended field means. A breaking change to an RPC never reaches here:
+     * it classifies breaking and the session is closed instead.
+     */
+    private swapSchema;
     private onWelcome;
     private onDelta;
     private onCorrect;
@@ -1226,6 +2094,18 @@ declare class Session {
     private rejectPending;
     message(target: MessageTarget, bytes: Uint8Array): void;
     onMessage(cb: (from: 'server' | string, bytes: Uint8Array) => 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.
+     *
+     * This deliberately does NOT go through `message()`. `MessageTarget` has no voice member on
+     * purpose (that is the third of the three isolation mechanisms), and widening it so that this
+     * method could share the mapping would delete the mechanism to save four lines. Building the
+     * `MsgTarget` here keeps `{ kind: 'voice' }` unrepresentable from anywhere a game can reach.
+     */
+    sendVoice(bytes: Uint8Array): void;
+    /** D51: subscribe to voice signaling replies. Internal, for the same reason as `sendVoice`. */
+    onVoice(cb: (bytes: Uint8Array) => void): Unsubscribe;
     get clients(): readonly PresenceRecord[];
     get link(): string;
     on<K extends keyof RoomEvents>(event: K, cb: (value: RoomEvents[K]) => void): Unsubscribe;
@@ -1233,6 +2113,138 @@ declare class Session {
     private setStatus;
 }
 
+/**
+ * D51: `joinVoice` — the client half of on-box voice.
+ *
+ * ## Why a free function and not `room.voice`
+ *
+ * `joinVoice(room)` mirrors `joinRoom(schema)`: a free function you call when you want the thing,
+ * rather than a property that exists on every `Room` whether or not the game has voice. Three
+ * reasons, in order of how much they matter.
+ *
+ * 1. **It keeps `mediasoup-client` off the join path.** The device library and its RTP capability
+ *    machinery are loaded by the first `joinVoice` call, dynamically. A game that never calls it
+ *    never pays for it, in bundle size or in startup work.
+ * 2. **Voice is per-participant, not per-room.** A room can be joined by a spectator, an NPC or a
+ *    headless bot, none of which have a microphone; making voice a room property would suggest a
+ *    lifetime it does not have. The handle returned here is the lifetime.
+ * 3. **It keeps the isolation clause structural.** Everything voice needs from the session —
+ *    `sendVoice`, `onVoice` — lives behind `INTERNAL_SESSION` and is absent from the public `Room`
+ *    type. Hanging voice off `Room` would have meant putting at least one of them within a game's
+ *    reach.
+ *
+ * ## Positional audio is not in this release
+ *
+ * The `positional` option is accepted and *ignored*. It is declared here rather than omitted so
+ * that a game which already passes it keeps compiling and keeps working (with flat audio) rather
+ * than failing to build, and so that turning it on later is an implementation change rather than an
+ * API change. Passing `true` logs one warning and does nothing spatial: no panner, no listener
+ * orientation, no distance model. See `mute` below for the one thing that *is* signalled.
+ *
+ * ## The handshake
+ *
+ * Fixed by the SFU's `dispatch`, and worth stating because the ordering is not obvious:
+ *
+ *   join    -> joined     (both transports' parameters, the router's capabilities, current peers)
+ *   connect -> connected  (per transport, fired lazily by mediasoup's own 'connect' event)
+ *   produce -> produced   (our microphone; the SFU then tells peers via `peer-joined`)
+ *   consume -> consumed   (per remote producer; the consumer starts PAUSED)
+ *   resume                (no reply — the SFU acknowledges by letting packets flow)
+ *
+ * Consumers starting paused is mediasoup's documented sequence and the reason `resume` is a
+ * separate message: the track is attached to its `<audio>` element before the first RTP packet
+ * arrives, rather than racing it.
+ *
+ * Replies carry no request id, because the SFU's protocol has none. Correlation is therefore by
+ * shape: `connected` by `transportId`, `consumed` by `producerId`, `joined` and `produced` by
+ * being the only one outstanding. An `error` has nothing to correlate on at all, so it rejects
+ * every outstanding waiter — which is what makes `E_VOICE_UNAVAILABLE` (a tenant with no SFU
+ * configured, which is every box until O16 answers) come back as a rejected `joinVoice` rather
+ * than a promise that hangs forever.
+ */
+
+/**
+ * What is known about one other participant: what *they* did to their microphone, and what *you*
+ * did to their playback on this machine. The two are deliberately separate fields rather than one
+ * "silent" flag, because a UI that conflated them would tell a player they had muted somebody when
+ * in fact that person had stopped talking.
+ */
+interface VoicePeerState {
+    /** The peer's own microphone mute, as last reported by the SFU. Not local. */
+    readonly muted: boolean;
+    /** This machine's local silencing of that peer. Never signalled, never seen by anyone else. */
+    readonly mutedLocally: boolean;
+    /** This machine's local playback volume for that peer, 0..1. */
+    readonly volume: number;
+}
+interface VoiceHandle {
+    /**
+     * Mute or unmute the microphone. Signalled to the SFU rather than only stopped locally: the SFU
+     * pauses the producer, which is what actually stops the bytes leaving the box, and an SFU that
+     * merely saw a silent stream could not tell a muted participant from a quiet room.
+     */
+    mute(muted: boolean): void;
+    readonly muted: boolean;
+    /** The other participants currently in this room's voice call, by room client id. */
+    readonly peers: readonly string[];
+    /**
+     * Local playback volume for one peer, 0..1 (clamped). Purely local: nothing is signalled, the
+     * peer is not told, and every other participant hears them unchanged. Remembered for the life of
+     * the handle, so setting it for a peer whose track has not arrived yet still takes effect when
+     * it does.
+     */
+    setPeerVolume(peerId: string, volume: number): void;
+    /**
+     * Locally silence one peer. Distinct from the `peer-muted` event, which reports that peer's own
+     * microphone: this one is yours, it is not signalled, and the two are reported separately by
+     * `peerState`.
+     */
+    mutePeer(peerId: string, muted: boolean): void;
+    /** The current state of one peer, or `undefined` if nobody by that id is in the call. */
+    peerState(peerId: string): VoicePeerState | undefined;
+    leave(): Promise<void>;
+    on(event: 'peer-joined' | 'peer-left' | 'peer-muted' | 'peers-changed' | 'error', cb: (v: never) => void): () => void;
+}
+interface VoiceOptions {
+    /**
+     * **Not implemented in this release.** Accepted so that calling code compiles and runs, ignored
+     * at runtime; passing `true` logs one warning and produces ordinary flat audio. Kept in the type
+     * so that shipping it later is not a breaking change.
+     */
+    readonly positional?: boolean;
+}
+/**
+ * The seam `@irtio/voice-ui` reads to draw a speaking indicator, and the only thing about a voice
+ * call that is not on the public `VoiceHandle`.
+ *
+ * It is a *registered* symbol rather than a module-local one (unlike `INTERNAL_SESSION`, which
+ * never leaves this package) because the reader is a different package: two copies of
+ * `@irtio/client` in one bundle would otherwise mint two different symbols and the panel would
+ * silently find nothing. Registered means "internal by convention, reachable across a package
+ * boundary", which is exactly the contract here.
+ *
+ * It is not public API. The shape may change in any release; `@irtio/voice-ui` treats every field
+ * as optional and degrades to no indicator when it is absent.
+ */
+declare const INTERNAL_VOICE_TRACKS: unique symbol;
+/** What lives behind {@link INTERNAL_VOICE_TRACKS}. */
+interface VoiceTrackAccess {
+    /** The remote track being played for one peer, if one has been attached. */
+    peerTrack(peerId: string): MediaStreamTrack | undefined;
+    /** This client's own microphone track, for a self speaking indicator. */
+    micTrack(): MediaStreamTrack | undefined;
+}
+/**
+ * Joins the voice call for a room this client is already in.
+ *
+ * Requires a microphone permission (the browser prompts) and a tenant with an SFU configured; a
+ * tenant without one rejects with `E_VOICE_UNAVAILABLE` rather than hanging.
+ *
+ * `options.positional` is accepted and ignored — positional audio is not in this release. See the
+ * module doc.
+ */
+declare function joinVoice<S extends AnySchema, R extends string>(room: Room<S, R>, options?: VoiceOptions): Promise<VoiceHandle>;
+
 /**
  * `@irtio/client` — the browser/Node SDK.
  *
@@ -1269,4 +2281,4 @@ declare function joinRoom<S extends AnySchema, Role extends string = RoleOf<S> &
  */
 declare function joinRelay(options?: JoinRelayOptions): Promise<RelayRoom>;
 
-export { CALL_TIMEOUT_MS, type ClientBodySpec, type ClientCollection, type ClientPhysicsOptions, type ClientRapierBody, type ClientRapierModule, type ClientRapierWorld, type ClientState, ClientStore, type ClientVector3, type Correction, DEFAULT_REGION, DEFAULT_WRITE_INTERVAL_MS, DEV_PORT, E_CONNECT_FAILED, type FrameHook, type JoinOptions, type JoinRelayOptions, MAX_PREDICTED_BODIES, type MessageTarget, PING_INTERVAL_MS, PREDICTION_EPSILON, type PredictionStats, type PredictionStatus, REGION_RE, RESIM_DEPTH, type RelayRoom, type Room, type RoomCallProxy, type RoomError, type RoomEvents, SMOOTHING_HALF_LIFE_MS, SMOOTHING_SNAP_UNITS, type Scheduler, Session, type Status, type Transport, type TransportSocket, type Unsubscribe, defaultScheduler, joinRelay, joinRoom, linkForUrl, resolveUrl, roomIdFrom, webSocketTransport };
+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 };