@irtio/client 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,15 +1,434 @@
-import { ReadonlyCollection, RoleOf, VisibleKeys, SchemaDefs, EntityDef, DeepReadonly, InferFields, Owned, SingletonDef, ClientImplementations, ClientRpcs, SchemaRpc, ClientCallProxy, AnySchema, PlainState, CollectionDesc, Delta } from '@irtio/schema';
+import { AnySchema, PlainState, CollectionDesc, Delta, EntityCollection, ReadonlyCollection, RoleOf, VisibleKeys, SchemaDefs, EntityDef, DeepReadonly, InferFields, Owned, SingletonDef, ClientImplementations, ClientRpcs, SchemaRpc, ClientCallProxy } from '@irtio/schema';
+import RAPIER from '@dimforge/rapier3d-compat';
 import { PresenceRecord } from '@irtio/protocol';
 
 /**
- * `@irtio/client`'s public contract: the `Room` surface `joinRoom` returns, its options, the
- * client-side state types, and the two injectable seams (`Transport`, `Scheduler`).
+ * The client's state layer.
+ *
+ * One plain `PlainState` (decoded from the join snapshot, advanced by every `DELTA`) with two
+ * views over it:
+ *
+ * - **owned instances** → the `track()` proxy for that record, so a write normalizes exactly like
+ *   the server would (f32 quantized, ranges and string sizes enforced by a throw) and marks a
+ *   dirty set the flush window turns into one `WRITE`;
+ * - **everything else** → `frozenProxy`, which ignores writes and warns once with the ownership
+ *   hint.
+ *
+ * Which one you get is decided per `get()`, so an ownership change needs no bookkeeping — but the
+ * object identity is not stable across it, which is why `state.x.get(id)` must be re-read after a
+ * grab (documented in the README).
  *
- * Nothing here imports a runtime dependency: the package speaks the wire with `@irtio/protocol`
- * and `@irtio/schema` only, and reaches for the global `WebSocket` that Node 22 and every
- * browser already have.
+ * The server-wins rule lives here too: a `DELTA`'s update ops are dropped field-wise for
+ * instances this client owns (adds, removes and owner changes still apply), while a `CORRECT`
+ * applies in full and clears the matching local dirty marks.
  */
 
+type AnyRecord$3 = Record<string, unknown>;
+/**
+ * Resimulation depth cap (D19): how many flushed-but-unjudged `WRITE`s the client retains for
+ * replay after a `CORRECT`. A correction older than the retained window snaps everything it
+ * corrects and counts it (`snapped`); buffer memory is bounded by the same window.
+ */
+declare const RESIM_DEPTH = 20;
+/** One correction op, as the `'correct'` event sees it. */
+interface CorrectionOp {
+    readonly collection: string;
+    readonly id: string;
+    readonly fields: readonly string[];
+    readonly patch: AnyRecord$3;
+    /** The local (predicted) values of `fields` right before the snap — what `patch` overrode. */
+    readonly previous: AnyRecord$3;
+    readonly tick: number;
+    /**
+     * The client write tick the server judged (D19), absent against a pre-week-8 server. Local
+     * writes newer than it were re-applied on top of the correction.
+     */
+    readonly clientTick?: number;
+    /** How many pending local writes were re-applied over this correction's values. */
+    readonly replayed: number;
+    /** `true` when the correction outran the resim window and everything it named snapped. */
+    readonly snapped: boolean;
+}
+declare class ClientStore {
+    readonly 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;
+    /** 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). */
+    private readonly pendingWrites;
+    /** The newest write tick evicted from `pendingWrites` — corrections older than it must snap. */
+    private evictedThroughTick;
+    /**
+     * The newest fields to leave `pendingWrites` per instance — judged into a correction, or
+     * evicted past the resim depth. This is the intent in force at the *start* of a resim window:
+     * the server holds a write's values until the next `WRITE` replaces them, so a replay that
+     * walks the window tick by tick starts from here, not from the newest local value.
+     */
+    private readonly baselineIntents;
+    constructor(ext: AnySchema, 
+    /** Reads the current client id — it is not known until the first `WELCOME`. */
+    meOf: () => string);
+    loadSnapshot(bytes: Uint8Array): void;
+    /**
+     * Captures the field values of every pending owned write, keyed by collection then id then
+     * field name — call this **before** `loadSnapshot` on a resync, or the edit is gone once the
+     * old `plain` it lives in is replaced. Paired with `applyPendingWrites`.
+     */
+    capturePendingWrites(): Map<string, Map<string, AnyRecord$3>>;
+    /**
+     * Writes a `capturePendingWrites` snapshot into the freshly loaded `plain` (still the raw
+     * decoded values — no validation, they were already validated at the time of the original
+     * local write) and marks every owned field dirty so the next flush resends the real edit, not
+     * whatever the resync snapshot happened to carry for that field.
+     */
+    applyPendingWrites(pending: Map<string, Map<string, AnyRecord$3>>): void;
+    private buildView;
+    /** The writable tracked proxy when this client owns `id`, otherwise a frozen one. */
+    instance(desc: CollectionDesc, id: string): unknown;
+    private freeze;
+    private entityHint;
+    private singletonHint;
+    /**
+     * Applies a server `DELTA`. Update ops for instances this client owns are dropped field-wise
+     * (server wins only through `CORRECT`); adds, removes and owner changes always apply.
+     */
+    applyServerDelta(delta: Delta): void;
+    /**
+     * The flushed-write half of the §7.2 in-flight own-write fix: an `add` op for an instance this
+     * client owns replaces the whole record, so any write already *flushed* (dirty set consumed —
+     * `preserveLocalWrites` cannot see it) but not yet judged would be reverted by the echo.
+     * Re-apply the retained pending writes in flush order; the server's eventual `CORRECT` (if the
+     * write is clamped) still wins through the snap+replay path.
+     */
+    private replayOverAddEchoes;
+    private withoutOwnedUpdates;
+    /**
+     * An `add` for an instance this client will own, with its unflushed local field values folded
+     * back in. Returns `op` unchanged when there is nothing to preserve.
+     */
+    private preserveLocalWrites;
+    /**
+     * Applies a `CORRECT`: snap the named fields to the server's values, then re-apply every local
+     * write newer than the judged `clientTick` in order (D19 snap + replay) — flushed writes from
+     * the retained buffer first, the still-unflushed in-window edit last (it is the newest, and its
+     * dirty mark survives so the next flush re-sends the *local* value, not the server's).
+     *
+     * Without a `clientTick` (a pre-week-8 server) — or when the correction outran the
+     * `RESIM_DEPTH` window (`snapped`) — the pre-D19 semantics apply: the correction wins in full
+     * and the local dirty marks it supersedes are cleared.
+     */
+    applyCorrection(delta: Delta, clientTick?: number): CorrectionOp[];
+    private desc;
+    /** The raw plain collection — authoritative values plus local writes (`track()` writes through). */
+    plainCollection(name: string): EntityCollection;
+    /**
+     * The flushed-but-unjudged write patches for one instance, oldest first, each keyed by the
+     * tick its `WRITE` was stamped with — for a physics entity these are exactly its
+     * unacknowledged intent frames (only intents are writable). The predictor's rebase walks its
+     * resim window tick by tick and applies the newest patch stamped at or before each tick
+     * (D22 part 2), starting from `baselineIntent` for the ticks before the first of them.
+     */
+    pendingWritePatches(collection: string, id: string): readonly {
+        tick: number;
+        patch: AnyRecord$3;
+    }[];
+    /**
+     * The intent in force for one instance at the start of the resim window: the newest fields
+     * that have left the pending buffer (judged into a correction's values, or evicted past the
+     * resim depth). `undefined` until the instance's first write leaves the buffer.
+     */
+    baselineIntent(collection: string, id: string): AnyRecord$3 | undefined;
+    /** Folds a write that left the pending buffer into the per-instance baseline, newest wins. */
+    private noteBaseline;
+    /** Cheap check for the flush loop: has anything been written locally since the last flush? */
+    get hasLocalWrites(): boolean;
+    /**
+     * The `WRITE` payload for everything dirty, or `undefined` when nothing qualifies. Consumes the
+     * dirty set either way (a write to an instance that has since been removed or handed away is
+     * dropped, not retried forever).
+     */
+    takeWrite(tick: number): Uint8Array | undefined;
+    /**
+     * Captures the field values a flushed `WRITE` carried, keyed by its write tick, so a later
+     * `CORRECT` can re-apply exactly the writes the server had not judged yet (D19 snap + replay).
+     * Bounded to `RESIM_DEPTH` entries; eviction is remembered so an outrun correction snaps.
+     */
+    private retainPendingWrite;
+    /** Re-applies one retained write's fields for `collection[id]` onto the plain state. */
+    private replayWrite;
+    /**
+     * Re-marks every field of every instance this client owns, so a resync `WELCOME` (wake or
+     * worker restart) does not silently drop writes that were in flight.
+     */
+    remarkOwned(): void;
+    /** Only update ops, only instances that still exist and are still mine, never the owner bit. */
+    private ownedDirty;
+}
+
+/**
+ * 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 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 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
+ * 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.
+ *
+ * ## What is deliberately absent
+ *
+ * Non-predicted dynamic bodies do not exist in the local world, and neither do `predicted: true`
+ * instances that fall over `maxPredictedBodies`. A predicted body that collides with either on
+ * the server mispredicts here — it had nothing to collide with, so it passes through and is
+ * 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.
+ */
+
+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.
+ */
+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;
+}
+/** Counters for the report and `room.prediction.stats`. */
+interface PredictionStats {
+    /** Steps taken free-running ahead of authority. */
+    freeSteps: number;
+    /** Steps taken re-simulating after a rebase. */
+    resimSteps: number;
+    /** Rebase passes (one per authoritative arrival batch). */
+    rebases: number;
+    /** Rebases whose lead outran the resim depth: the body snapped to authority. */
+    snaps: number;
+    /** Corrections whose values matched the local prediction within epsilon. */
+    suppressed: number;
+    /**
+     * Non-owned predicted instances currently over the cap. They render by interpolation but have
+     * no body in the local world, so predicted bodies pass through them: a non-zero value on a
+     * collection anything stands on is a gameplay bug, not a fidelity tradeoff.
+     */
+    overCap: number;
+    /** Microseconds spent in the last rebase's re-steps. */
+    lastResimMicros: number;
+}
+declare class PhysicsPredictor {
+    private readonly store;
+    private readonly options;
+    private readonly meOf;
+    private readonly rttOf;
+    private readonly tickIntervalOf;
+    private readonly log;
+    readonly stats: PredictionStats;
+    private rapier;
+    private world;
+    private readonly bodies;
+    /** Physics-backed entity collections, in schema order. */
+    private readonly collections;
+    private readonly warned;
+    /** Highest over-cap count warned about per collection, so growth re-warns and noise does not. */
+    private readonly overCapHigh;
+    /** Authority arrived since the last frame: rebase before free-running. */
+    private authorityDirty;
+    private accumulatorMs;
+    private lastNow;
+    private lastFrameNow;
+    private failed;
+    /**
+     * Per owned body: the server tick its authoritative record is *from* (the tick of the last
+     * `CORRECT` that touched it), and the per-tick prediction history — after every local step,
+     * the body's channels are recorded under the tick that step predicted. A correction for tick T
+     * is then judged against the client's prediction **for tick T**, not against the current head
+     * of the simulation (which legitimately leads authority by the whole latency — comparing
+     * against it would report the lead as misprediction).
+     */
+    private readonly authorityTicks;
+    private readonly predictedTicks;
+    private readonly history;
+    /** History kept per body — comfortably past the resim depth. */
+    private static readonly HISTORY_TICKS;
+    constructor(ext: AnySchema, store: ClientStore, options: ClientPhysicsOptions, meOf: () => string, rttOf: () => number, tickIntervalOf: () => number, log?: (message: string) => void);
+    get epsilon(): number;
+    /** `true` once the engine is loaded and the local world exists. */
+    get ready(): boolean;
+    /**
+     * Kicks off the async engine load. Idempotent. Until it resolves, every read falls back to
+     * interpolation/authority — joining is never blocked on 2.9 MB of WASM.
+     */
+    start(): Promise<void>;
+    free(): void;
+    /** A resync (`WELCOME`) replaced the authority wholesale: rebase everything, drop banked time. */
+    reset(): void;
+    /** Authoritative body state arrived (`DELTA` on a non-owned body, `CORRECT` on an owned one). */
+    noteAuthority(): void;
+    /** The session tells us which server tick one body's authoritative record is from. */
+    noteAuthorityTick(collection: string, id: string, tick: number): void;
+    /** Does the local world currently simulate `collection[id]`? */
+    has(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
+     * channels against `epsilon / timestep`, 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)? */
+    predictsCollection(name: string): boolean;
+    /**
+     * Advances the local world to `now`. Driven by render reads (one pass per timestamp), so a
+     * draw loop — or a bot's render sampling — is the clock; there is no timer.
+     */
+    frame(now: number): void;
+    /**
+     * The predicted record for `collection[id]`: the authoritative record (which already carries
+     * local intent writes — `track()` writes through to plain state) with the body-mapped channels
+     * replaced by the local world's values, `Math.fround`ed for f32 fields so what the draw loop
+     * reads is what the wire would carry.
+     */
+    read(desc: CollectionDesc, id: string, base: AnyRecord$2): AnyRecord$2;
+    /**
+     * The local world's current values for `fields` of one body — what a correction is judged
+     * against (`previous` on the `correct` event, and the epsilon-suppression comparison).
+     */
+    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).
+     *
+     * 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.
+     */
+    private reconcileBodies;
+    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.
+     */
+    private warnOverCap;
+    private warnOnce;
+    /**
+     * The client's lead over authority, in ticks: one-way latency plus one tick of margin.
+     * Measured (dive e2e, 2026-08-27): a full-round-trip lead was tried for the tick-aligned
+     * replay and made release transitions *worse* (-1.4 to -1.8 u worst backwards step vs -0.6 at
+     * half), because the extra lead grows the standing overshoot a rest-settling body has to give
+     * back. Half the trip plus margin is where the stamp clock and the correction stream meet.
+     */
+    private leadTicks;
+    private timestepMs;
+    /**
+     * Rebase + re-step: snap every predicted body to the authoritative record (server values —
+     * `DELTA` for non-owned bodies, `CORRECT` for owned ones; body fields are never client-
+     * 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`).
+     */
+    private rebase;
+    /**
+     * The tick a `WRITE` flushed right now should be stamped with: one past the newest predicted
+     * head across owned bodies — the first tick the new intent can affect. That puts the stamp on
+     * the same clock as `authorityTicks` and the resim window (the server's tick stream), which is
+     * what lets the rebase walk pending writes by tick instead of by array index. `undefined`
+     * until the engine runs or while nothing is owned; the session falls back to its counter.
+     */
+    stampTick(): number | undefined;
+    /** After every step: advance each owned body's prediction clock and remember its channels. */
+    private recordStep;
+    private freeRun;
+    /**
+     * Applies intents for every owned predicted body before one step: the intent in force at the
+     * 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).
+     */
+    private applyIntents;
+    /** Server record → body channels (the same mapping the runtime's sync uses, inverted). */
+    private applyRecord;
+    private isF32;
+}
+
 /**
  * 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)`.
@@ -56,6 +475,11 @@ interface Correction {
     readonly fields: readonly string[];
     /** The server's values for those fields (already applied to `room.state`). */
     readonly patch: Readonly<Record<string, unknown>>;
+    /**
+     * The local (predicted) values of `fields` right before the snap. Misprediction magnitude is
+     * the numeric distance between `previous` and `patch`, per field.
+     */
+    readonly previous: Readonly<Record<string, unknown>>;
     readonly tick: number;
     /**
      * The client write tick the server judged (D19, week 8): every local write through it is
@@ -70,6 +494,19 @@ interface Correction {
      * writes) — everything it named snapped to the server's values, nothing was replayed.
      */
     readonly snapped: boolean;
+    /**
+     * D22: every corrected field is a simulation-owned body field this client does **not**
+     * predict — not a disagreement, just server-authoritative body state reaching its owner (once
+     * per tick, by design). When the client predicts the body, this is `false` and the correction
+     * is a real misprediction: `previous` holds the local world's predicted values.
+     */
+    readonly simulation: boolean;
+    /**
+     * D22 part 2: a predicted body's correction whose every value matched the local prediction
+     * within the epsilon — authority applied, but there was nothing to disagree about. Suppressed
+     * corrections keep a healthy predicted body's steady state quiet.
+     */
+    readonly suppressed: boolean;
 }
 interface RoomEvents {
     status: Status;
@@ -134,9 +571,30 @@ interface JoinOptions<S, Role extends string = string> {
      * (which is what `irtio dev` uses when there is no `irtio.json`).
      */
     readonly key?: string;
+    /**
+     * Week 13 (D27): a JWT asserting who this player is, minted by your server with the project's
+     * signing secret. `ctx.playerId` becomes the token's `sub`, and a `role` claim overrides
+     * `role` here. A function is called before every HELLO — reconnects included — so it can hand
+     * back a fresh token when the old one nears expiry. Omitted ⇒ the key-only join, unchanged.
+     */
+    readonly token?: string | (() => string | Promise<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.
+     */
+    readonly interpDelayMs?: number;
+    /**
+     * D22 part 2: the client half of the shared world-builder contract — the same `setup`,
+     * `bodies` and `intents` functions the room's `physics` config imports (by convention from
+     * `irtio/world.ts`), plus `gravity`. With it, this client simulates its own bodies (and any
+     * `predicted: true` collection's, capped) ahead in a local world; without it, body-backed
+     * entities interpolate like everything else. The engine loads lazily — a bundler that
+     * code-splits keeps Rapier out of the critical path entirely.
+     */
+    readonly physics?: ClientPhysicsOptions;
     /** @internal */
     readonly transport?: Transport;
     /** @internal */
@@ -163,6 +621,27 @@ interface JoinRelayOptions {
 type MessageTarget = 'all' | string | {
     readonly role: string;
 };
+/**
+ * Default D21 cap on non-owned predicted bodies per client.
+ *
+ * Sized against measurement, not caution: 41 dynamic bodies stacked in contact step in 0.005 to
+ * 0.007 ms (`games/dive/spike`, 2026-08-26), and a rebase re-steps the local world once per lead
+ * tick per authoritative tick — about 0.5 ms per second of wall clock at 30Hz with a 3-tick lead.
+ * Body count is not what makes prediction expensive, and the cost of a cap set too low is not
+ * saved CPU: over-cap instances are **absent from the local world** (see `reconcileBodies`), so
+ * a predicted body passes through them.
+ */
+declare const MAX_PREDICTED_BODIES = 64;
+/** Default correction-suppression epsilon, world units (see `ClientPhysicsOptions.epsilon`). */
+declare const PREDICTION_EPSILON = 0.05;
+/** `room.prediction` (D22 part 2). */
+interface PredictionStatus {
+    /** The engine is loaded and the local world exists. */
+    readonly active: boolean;
+    /** Is `collection[id]` currently simulated in the local world? */
+    predicts(collection: string, id: string): boolean;
+    readonly stats: PredictionStats;
+}
 /**
  * `room.call.<rpc>(params)` — every server RPC the builder declared, plus the one built-in.
  * `requestOwnership` takes the entity/id pair positionally and unwraps `{ granted }`.
@@ -184,8 +663,23 @@ interface Room<S, Role extends string = RoleOf<S> & string> {
     /** Round-trip time in ms from the last `PING`/`PONG`, or 0 before the first one. */
     readonly rtt: number;
     readonly state: ClientState<S, Role>;
+    /**
+     * The render read path (D20): same shapes as `room.state`, but non-owned entities are
+     * interpolated at `now − interpDelayMs` (numeric fields lerp, everything else steps) while
+     * owned entities return the predicted local values. A draw loop opts in by one substitution —
+     * `room.state.players` → `room.render.players`. Tests and game logic keep reading
+     * `room.state`, which stays authoritative.
+     */
+    readonly render: ClientState<S, Role>;
     /** Built-in presence, ordered by join. */
     readonly clients: readonly PresenceRecord[];
+    /**
+     * Physics-prediction status, present when the join passed `physics` and the schema has
+     * body-backed collections (D22 part 2). `active` flips true once the engine loads; `predicts`
+     * says whether one instance currently reads from the local world; `stats` carries the
+     * counters the bot runtime and the demos report.
+     */
+    readonly prediction?: PredictionStatus;
     readonly call: RoomCallProxy<S>;
     /** Convenience alias for `room.call.requestOwnership`. */
     requestOwnership(entity: string, id: string): Promise<boolean>;
@@ -260,141 +754,58 @@ declare function defaultScheduler(): Scheduler;
 declare const webSocketTransport: Transport;
 
 /**
- * The client's state layer.
- *
- * One plain `PlainState` (decoded from the join snapshot, advanced by every `DELTA`) with two
- * views over it:
+ * The interpolated render read path (D20, week 8): `room.render.<collection>` mirrors
+ * `room.state`'s shapes, but non-owned entities are rendered at `now − interpDelayMs`, lerping
+ * numeric fields between the two bracketing DELTAs and stepping everything else (strings, bools,
+ * enums, refs, lists). Owned entities return the predicted (local) values — the same object
+ * `room.state` hands out — so one read path serves the whole draw loop.
  *
- * - **owned instances** → the `track()` proxy for that record, so a write normalizes exactly like
- *   the server would (f32 quantized, ranges and string sizes enforced by a throw) and marks a
- *   dirty set the flush window turns into one `WRITE`;
- * - **everything else** → `frozenProxy`, which ignores writes and warns once with the ownership
- *   hint.
- *
- * Which one you get is decided per `get()`, so an ownership change needs no bookkeeping — but the
- * object identity is not stable across it, which is why `state.x.get(id)` must be re-read after a
- * grab (documented in the README).
- *
- * The server-wins rule lives here too: a `DELTA`'s update ops are dropped field-wise for
- * instances this client owns (adds, removes and owner changes still apply), while a `CORRECT`
- * applies in full and clears the matching local dirty marks.
+ * `room.state` stays authoritative and untouched: tests, bots and existing code see exactly what
+ * they saw before. Entities appear and disappear at the buffered time; past the newest delta the
+ * value holds (no extrapolation) and the starvation is counted. A collection declared
+ * `interpolate: false` (and every singleton) reads straight through to the authoritative view.
  */
 
 type AnyRecord$1 = Record<string, unknown>;
-/**
- * Resimulation depth cap (D19): how many flushed-but-unjudged `WRITE`s the client retains for
- * replay after a `CORRECT`. A correction older than the retained window snaps everything it
- * corrects and counts it (`snapped`); buffer memory is bounded by the same window.
- */
-declare const RESIM_DEPTH = 20;
-/** One correction op, as the `'correct'` event sees it. */
-interface CorrectionOp {
-    readonly collection: string;
-    readonly id: string;
-    readonly fields: readonly string[];
-    readonly patch: AnyRecord$1;
-    readonly tick: number;
-    /**
-     * The client write tick the server judged (D19), absent against a pre-week-8 server. Local
-     * writes newer than it were re-applied on top of the correction.
-     */
-    readonly clientTick?: number;
-    /** How many pending local writes were re-applied over this correction's values. */
-    readonly replayed: number;
-    /** `true` when the correction outran the resim window and everything it named snapped. */
-    readonly snapped: boolean;
-}
-declare class ClientStore {
-    readonly ext: AnySchema;
-    /** Reads the current client id — it is not known until the first `WELCOME`. */
+declare class RenderStore {
+    private readonly ext;
+    private readonly store;
     private readonly meOf;
-    plain: PlainState;
-    private tracked;
+    private readonly now;
+    private readonly delayMs;
+    /** collection → id → buffered keyframes. Only interpolating entity collections have entries. */
+    private readonly buffers;
     private readonly descs;
-    private readonly frozen;
-    /** The object handed out as `room.state`; identity survives a resync. */
+    /** The object handed out as `room.render`; identity survives a resync. */
     readonly view: AnyRecord$1;
-    /** Flushed-but-unjudged writes, oldest first, at most `RESIM_DEPTH` entries (D19). */
-    private readonly pendingWrites;
-    /** The newest write tick evicted from `pendingWrites` — corrections older than it must snap. */
-    private evictedThroughTick;
-    constructor(ext: AnySchema, 
-    /** Reads the current client id — it is not known until the first `WELCOME`. */
-    meOf: () => string);
-    loadSnapshot(bytes: Uint8Array): void;
-    /**
-     * Captures the field values of every pending owned write, keyed by collection then id then
-     * field name — call this **before** `loadSnapshot` on a resync, or the edit is gone once the
-     * old `plain` it lives in is replaced. Paired with `applyPendingWrites`.
-     */
-    capturePendingWrites(): Map<string, Map<string, 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);
     /**
-     * Writes a `capturePendingWrites` snapshot into the freshly loaded `plain` (still the raw
-     * decoded values — no validation, they were already validated at the time of the original
-     * local write) and marks every owned field dirty so the next flush resends the real edit, not
-     * whatever the resync snapshot happened to carry for that field.
+     * 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).
      */
-    applyPendingWrites(pending: Map<string, Map<string, AnyRecord$1>>): void;
+    seedSnapshot(): void;
+    /** Buffers every entity a `DELTA` touched, stamped with its arrival time. Call after apply. */
+    recordDelta(delta: Delta): void;
+    private bufferFor;
+    private renderTime;
+    attachPredictor(predictor: PhysicsPredictor): 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? */
+    has(desc: CollectionDesc, id: string): boolean;
+    /** The authoritative owner — ownership is fact, not a rendered value. */
+    ownerOf(desc: CollectionDesc, id: string): string | undefined;
+    /** Ids visible at the render clock: owned (predicted) plus buffered-and-appeared. */
+    ids(desc: CollectionDesc): IterableIterator<string>;
+    /** Drops frames the render clock has passed, keeping the newest one at-or-before `renderT`. */
+    private prune;
+    private gc;
     private buildView;
-    /** The writable tracked proxy when this client owns `id`, otherwise a frozen one. */
-    instance(desc: CollectionDesc, id: string): unknown;
-    private freeze;
-    private entityHint;
-    private singletonHint;
-    /**
-     * Applies a server `DELTA`. Update ops for instances this client owns are dropped field-wise
-     * (server wins only through `CORRECT`); adds, removes and owner changes always apply.
-     */
-    applyServerDelta(delta: Delta): void;
-    /**
-     * The flushed-write half of the §7.2 in-flight own-write fix: an `add` op for an instance this
-     * client owns replaces the whole record, so any write already *flushed* (dirty set consumed —
-     * `preserveLocalWrites` cannot see it) but not yet judged would be reverted by the echo.
-     * Re-apply the retained pending writes in flush order; the server's eventual `CORRECT` (if the
-     * write is clamped) still wins through the snap+replay path.
-     */
-    private replayOverAddEchoes;
-    private withoutOwnedUpdates;
-    /**
-     * An `add` for an instance this client will own, with its unflushed local field values folded
-     * back in. Returns `op` unchanged when there is nothing to preserve.
-     */
-    private preserveLocalWrites;
-    /**
-     * Applies a `CORRECT`: snap the named fields to the server's values, then re-apply every local
-     * write newer than the judged `clientTick` in order (D19 snap + replay) — flushed writes from
-     * the retained buffer first, the still-unflushed in-window edit last (it is the newest, and its
-     * dirty mark survives so the next flush re-sends the *local* value, not the server's).
-     *
-     * Without a `clientTick` (a pre-week-8 server) — or when the correction outran the
-     * `RESIM_DEPTH` window (`snapped`) — the pre-D19 semantics apply: the correction wins in full
-     * and the local dirty marks it supersedes are cleared.
-     */
-    applyCorrection(delta: Delta, clientTick?: number): CorrectionOp[];
-    private desc;
-    /** Cheap check for the flush loop: has anything been written locally since the last flush? */
-    get hasLocalWrites(): boolean;
-    /**
-     * The `WRITE` payload for everything dirty, or `undefined` when nothing qualifies. Consumes the
-     * dirty set either way (a write to an instance that has since been removed or handed away is
-     * dropped, not retried forever).
-     */
-    takeWrite(tick: number): Uint8Array | undefined;
-    /**
-     * Captures the field values a flushed `WRITE` carried, keyed by its write tick, so a later
-     * `CORRECT` can re-apply exactly the writes the server had not judged yet (D19 snap + replay).
-     * Bounded to `RESIM_DEPTH` entries; eviction is remembered so an outrun correction snaps.
-     */
-    private retainPendingWrite;
-    /** Re-applies one retained write's fields for `collection[id]` onto the plain state. */
-    private replayWrite;
-    /**
-     * Re-marks every field of every instance this client owns, so a resync `WELCOME` (wake or
-     * worker restart) does not silently drop writes that were in flight.
-     */
-    remarkOwned(): void;
-    /** Only update ops, only instances that still exist and are still mine, never the owner bit. */
-    private ownedDirty;
 }
 
 /**
@@ -419,10 +830,21 @@ interface SessionOptions {
     readonly url: string;
     readonly roomId: string;
     readonly key: string;
+    /**
+     * Week 13 (D27): a JWT asserting who this player is, minted by YOUR server with the project's
+     * signing secret (`irtio keys jwt-secret`). A function is called before every HELLO — every
+     * reconnect included — so a fresh token can be supplied when the old one nears its `exp`; a
+     * resume that outlives its token would otherwise be refused with `E_TOKEN_EXPIRED`.
+     */
+    readonly token?: string | (() => 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)`. */
+    readonly interpDelayMs?: number | undefined;
+    /** The shared world-builder half the client predicts with (D22 part 2). */
+    readonly physics?: ClientPhysicsOptions | undefined;
     readonly transport?: Transport | undefined;
     readonly scheduler?: Scheduler | undefined;
     readonly onFrame?: FrameHook | undefined;
@@ -434,6 +856,14 @@ declare class Session {
     private readonly options;
     readonly ext: AnySchema;
     readonly store: ClientStore;
+    readonly render: RenderStore;
+    /** `true` when the join passed `physics` 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.
+     */
+    predictor: PhysicsPredictor | undefined;
     /** The schema the `CALL`/`REPLY` rpc id space indexes into. */
     private readonly rpcSchema;
     private readonly transport;
@@ -445,9 +875,11 @@ declare class Session {
     roomId: string;
     tick: number;
     /**
-     * The client-local write counter (D19): +1 per flushed `WRITE`, stamped in its delta header.
+     * The stamp of the newest flushed `WRITE`, carried in its delta header (D19). With physics
+     * prediction live this is the predictor's head tick + 1 — the server's tick clock, which is
+     * what lets the rebase replay pending writes by tick — and otherwise a bare counter.
      * Monotonic for the life of the session, across reconnects — the server's `lastClientTick`
-     * for this client survives the grace window too.
+     * for this client survives the grace window too, and only ever moves forward.
      */
     writeTick: number;
     /** The room's tick interval from `WELCOME`, or 0 when unknown (relay / pre-week-8 server). */
@@ -455,6 +887,19 @@ declare class Session {
     rtt: number;
     status: Status;
     private socket;
+    /**
+     * Whether `socket` has actually opened. `TransportSocket` deliberately has no `readyState` —
+     * `@irtio/testing` injects an in-process pair — so the session tracks it from `onopen`.
+     *
+     * Needed because a reconnecting session holds a socket that exists and is *not* sendable:
+     * `onSocketClosed` clears `socket` but keeps `joined` true (that is what makes resume work), and
+     * `connect()` then assigns a fresh socket that is still CONNECTING. Every send guard here used to
+     * test `this.socket` for presence alone, so the ping timer and the write flush would both reach a
+     * connecting socket and throw `InvalidStateError: Sent before connected.` out of a timer callback,
+     * where nothing catches it. Found on staging under 40+ bots, where joins are slow enough for the
+     * window to be wide; it never opens against a local dev server.
+     */
+    private socketOpen;
     private resumeToken;
     private joined;
     private left;
@@ -470,6 +915,11 @@ declare class Session {
     private settleJoin;
     private failJoin;
     constructor(options: SessionOptions);
+    /**
+     * The `room.render` delay (D20): the explicit option, else twice the room's tick interval
+     * (from `WELCOME`), floored at 50 ms — also the fallback when the interval is unknown.
+     */
+    get interpDelayMs(): number;
     /** Connects and resolves on the first `WELCOME`; a fatal `ERROR` before it rejects. */
     start(): Promise<Session>;
     private connect;
@@ -487,6 +937,10 @@ declare class Session {
     private onWelcome;
     private onDelta;
     private onCorrect;
+    private descsByName;
+    private descOfCollection;
+    /** Pre-rebase predicted values per corrected instance, keyed `collection id`. */
+    private capturePredicted;
     private onError;
     private onPong;
     private onMsg;
@@ -497,6 +951,7 @@ declare class Session {
      * inside a window leaves as a single `WRITE`.
      */
     private armFlush;
+    private sendPing;
     private armPing;
     /** Sends every pending owned write now. */
     flush(): void;
@@ -553,4 +1008,4 @@ declare function joinRoom<S extends AnySchema, Role extends string = RoleOf<S> &
  */
 declare function joinRelay(options?: JoinRelayOptions): Promise<RelayRoom>;
 
-export { CALL_TIMEOUT_MS, type ClientCollection, type ClientState, ClientStore, type Correction, DEFAULT_REGION, DEFAULT_WRITE_INTERVAL_MS, DEV_PORT, E_CONNECT_FAILED, type FrameHook, type JoinOptions, type JoinRelayOptions, type MessageTarget, PING_INTERVAL_MS, RESIM_DEPTH, type RelayRoom, type Room, type RoomCallProxy, type RoomError, type RoomEvents, type Scheduler, Session, type Status, type Transport, type TransportSocket, type Unsubscribe, defaultScheduler, joinRelay, joinRoom, linkForUrl, resolveUrl, roomIdFrom, webSocketTransport };
+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, RESIM_DEPTH, type RelayRoom, type Room, type RoomCallProxy, type RoomError, type RoomEvents, type Scheduler, Session, type Status, type Transport, type TransportSocket, type Unsubscribe, defaultScheduler, joinRelay, joinRoom, linkForUrl, resolveUrl, roomIdFrom, webSocketTransport };