@irtio/client 0.6.0 → 0.7.0

package/dist/index.d.ts

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