@irtio/client 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,15 +1,644 @@
-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:
  *
- * 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.
+ * - **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.
  */
 
+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 the renderer sees
+ *
+ * Not the head. The head moves once per server tick — and only when an arrival rebases the world
+ * onto it — while a display asks two to four times as often, so handing back the head draws a
+ * character running at a steady nine units a second as standing still for half the frames and
+ * moving at twenty for the rest. `read()` therefore keeps a short ring of recent poses per body
+ * and draws between the two either side of a render clock that runs on wall time, steered to sit
+ * about a tick behind the head. Correctness is unaffected: `room.state`, the per-tick history a
+ * correction is judged against, and `predictedValues` all still see the head. See bug 7 in
+ * `docs/bugs.md` for the measurement.
+ *
+ * ## 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;
+    /**
+     * 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`. */
+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;
+    /**
+     * The largest render-error offset currently being eased away, in world units — how far the
+     * furthest-off predicted body is being drawn from where the simulation puts it, so that a
+     * re-simulation did not arrive as a step (`smoothingHalfLifeMs`). It rises on a correction and
+     * falls back towards zero; what is unhealthy is a value that *stays* up, which means the
+     * client is being corrected as fast as it can absorb it.
+     */
+    smoothing: number;
+    /**
+     * Ticks between the stamp a `WRITE` carries and the server tick it was applied at, smoothed
+     * (bug 1). The client stamps on its predicted clock, which leads authority, so this is how far
+     * *early* a naive replay would put every pending intent. 0 until a server that reports the
+     * applied tick judges a stamped write.
+     */
+    stampGap: 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;
+    /**
+     * The local world's head, on the server's tick timeline: the authoritative tick the last
+     * rebase started from plus the lead it re-stepped, then one per free-run step.
+     */
+    private headTick;
+    /** The newest server tick any authority has been seen for. `headTick`'s base. */
+    private authorityTick;
+    /** The newest tick a pose has been stored for. `-1` until the first capture. */
+    private curTick;
+    /**
+     * Where the renderer is, as a fractional tick. Advanced by wall time every frame and steered
+     * to sit about a tick behind `curTick`; `read()` draws between the stored poses either side
+     * of it.
+     */
+    private renderTick;
+    /** Scratch for one interpolated pose. `read()` is synchronous, so one is enough. */
+    private readonly scratch;
+    /** Scratch quaternions, so the per-body per-frame offset maths allocates nothing. */
+    private readonly qa;
+    private readonly qb;
+    private readonly qc;
+    /**
+     * 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;
+    /** Smoothed stamp-minus-applied gap; see `noteWriteApplied`. */
+    private stampGap;
+    private gapMeasured;
+    /** The newest stamp already folded into `stampGap`, so a repeated echo is not re-weighted. */
+    private gapSampledThrough;
+    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).
+     *
+     * `tick` is the server tick it carried, and it is the base of the predictor's own head clock —
+     * which the renderer's interpolation is paced against. It has to be the *world's* clock rather
+     * than any one body's: a client with nothing of its own to own still draws a world full of
+     * predicted bodies.
+     */
+    noteAuthority(tick?: number): void;
+    /** The session tells us which server tick one body's authoritative record is from. */
+    noteAuthorityTick(collection: string, id: string, tick: number): void;
+    /**
+     * A `CORRECT` reported both halves of a judged write: the stamp the client put on it and the
+     * server tick it was actually applied at (bug 1). The gap between them is the systematic error
+     * in the rebase's replay, and it is not zero even on a loopback: the stamp is the predictor's
+     * *head* (authority + lead), while the server applies on arrival, at a tick barely past the
+     * authority the client is replaying from. Replaying at the stamp therefore held the previous
+     * intent for `gap` ticks the server had already simulated under the new one — the overshoot on
+     * every key release, sized `gap x speed`.
+     *
+     * Smoothed, because it rides on delivery jitter and the measurement is one sample per judged
+     * 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.
+     */
+    noteWriteApplied(stampTick: number, appliedTick: 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 head moved: store every predicted body's pose under the tick it now holds.
+     *
+     * A tick can be simulated more than once — a `DELTA` and a `CORRECT` both arrive for the same
+     * tick and each rebases — so the slot is simply rewritten with the better answer. It can also
+     * move backwards, when a free-run step is discarded by the rebase behind it; `curTick` does
+     * not follow it down, because moving the newest label backwards would drag the segment the
+     * renderer is crossing backwards with it.
+     */
+    private capturePoses;
+    /**
+     * Advance the render clock by one frame of wall time, steering it towards a target distance
+     * behind the head rather than clamping it there.
+     *
+     * `renderTick` and `curTick` agree on rate — one tick per tick period — but not on phase, and
+     * the phase error is delivery jitter: authority arrives when the network hands it over, not
+     * every 33 ms however steady the server is. Left alone the two would wander apart, so the
+     * clock is steered, by rate rather than by position. What the network did to a packet is not
+     * something the player's character should be seen doing.
+     */
+    private advanceRenderClock;
+    /**
+     * Keep the render clock inside the span there are poses for.
+     *
+     * Both ends are real. At `curTick` there is nothing further to draw towards, so a late arrival
+     * holds the pose rather than extrapolating motion the next tick would have to take back — the
+     * same trade that sized the prediction lead (bug 1). At the far end the ring has recycled the
+     * slot and the pose is genuinely gone. Between them the clock floats, and the rate trim above
+     * is what keeps it from spending its time against either stop.
+     */
+    private holdRenderTick;
+    /** `smoothingHalfLifeMs`, or 0 when the game turned the smoothing off. */
+    private halfLifeMs;
+    /** Remember where every body is being drawn, before this frame re-simulates anything. */
+    private snapshotDrawn;
+    /**
+     * Take whatever the re-simulation moved the drawn pose by and put it in the offset instead.
+     *
+     * This is the whole of correction smoothing, and it is smoothing the *error*: the difference
+     * measured here is between two answers to the same question — where is this body at the render
+     * clock — asked either side of a rebase. Motion the simulation produced is not in it, because
+     * the render clock advanced before the snapshot. So real movement is never slowed, which is
+     * the thing a rate limiter on the drawn position cannot promise: it sees a position that moved
+     * and has no way to know whether the body ran or was corrected.
+     *
+     * It absorbs more than server disagreement. A newly flushed intent changes what the last few
+     * ticks should have been, and the replay hands that over as a jump the same way; so does the
+     * render clock being pulled back inside the poses it has. All of it is the same defect from
+     * the player's side — the character was drawn somewhere it now turns out it was not — and all
+     * of it eases away here.
+     */
+    private absorbJump;
+    /**
+     * Ease every offset towards zero. Exponential, so the rate is proportional to the error and
+     * there is no world-scale speed to pick: a correction worth a tenth of a unit is worked off
+     * gently and one worth a whole unit is not left hanging around for a second.
+     */
+    private decayOffsets;
+    private clearOffset;
+    /**
+     * The pose to draw one body at: the stored poses either side of the render clock, blended.
+     * Falls back to the body's live transform when the ring cannot bracket it — before the first
+     * capture, and for a body that appeared this frame.
+     */
+    private rawPose;
+    /** `rawPose` with the render-error offset applied — what the draw loop actually gets. */
+    private renderPose;
+    /**
+     * 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.
+     *
+     * Drawn *between* two simulated ticks, not at the head. The local world steps at the room's
+     * tick rate, and only when authority arrives to rebase it; a display runs at two to four times
+     * that and asks on every frame. Handing back the head means the answer changes on some frames
+     * and not others, so a character running at a steady nine units a second is drawn standing
+     * still for half of them and moving at twenty for the rest. It is the player's own character
+     * answering their own key, and it reads as the game hitching.
+     *
+     * This is a *render* read. `room.state` and every correctness path — `predictedValues`, the
+     * per-tick history a correction is judged against — still see the head exactly as before.
+     */
+    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: 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 |
+     *
+     * 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 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.
+     *
+     * 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.
+     */
+    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;
+    /** Returns the number of steps taken, so the caller knows whether the head moved. */
+    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 +685,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 +704,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 +781,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 +831,41 @@ 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;
+/**
+ * Default half-life for render-error smoothing, milliseconds (see
+ * `ClientPhysicsOptions.smoothingHalfLifeMs`). About two ticks at 30Hz: long enough that a
+ * correction is a settle rather than a step, short enough that the drawn position is back on the
+ * simulation within a fifth of a second.
+ */
+declare const SMOOTHING_HALF_LIFE_MS = 70;
+/**
+ * Default distance past which a render-error offset is dropped rather than eased away, world
+ * units (see `ClientPhysicsOptions.smoothingSnapUnits`). A respawn, an area change or a session
+ * resync moves a body somewhere else entirely, and sliding into it is worse than arriving.
+ * Four units is a guess at world scale and the one number here a game may need to change.
+ */
+declare const SMOOTHING_SNAP_UNITS = 4;
+/** `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 }`.
@@ -176,7 +879,10 @@ interface Room<S, Role extends string = RoleOf<S> & string> {
     readonly me: string;
     /** The room code (from `WELCOME`). */
     readonly id: string;
-    /** Shareable URL carrying `?room=<id>`. */
+    /**
+     * Shareable URL carrying `?room=<id>`, with per-client params (`role`) stripped so it is safe
+     * to hand to somebody else. The address bar keeps them.
+     */
     readonly link: string;
     /** The last server tick this client saw. */
     readonly tick: number;
@@ -184,8 +890,25 @@ 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
+     * predicted bodies are drawn between the two most recent ticks of the local physics world.
+     * Either way the value advances with the frame clock rather than with arrivals or with the
+     * tick rate. 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 +983,60 @@ 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:
- *
- * - **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.
+ * 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). Predicted bodies — owned or `predicted: true` — come from the local
+ * physics world instead, drawn between the two most recent simulated ticks rather than at the
+ * simulation head, so they too advance with the frame clock and not with whatever rate their
+ * source happens to update at (`physics.ts`, `read`). One read path serves the whole draw loop.
  *
- * 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;
 }
 
 /**
@@ -409,8 +1051,13 @@ type AnyRecord = Record<string, unknown>;
 type ClientImpl = (params: AnyRecord) => unknown;
 /** Default hard cap on the owned-write flush window. */
 declare const DEFAULT_WRITE_INTERVAL_MS = 50;
-/** How often the client pings for `room.rtt`. */
-declare const PING_INTERVAL_MS = 10000;
+/**
+ * How often the client pings for `room.rtt`. Two seconds rather than ten (bug 4): the prediction
+ * lead is re-derived from `rtt` on every rebase, so the interval is not just how fresh a
+ * diagnostic number is — it is how long one measurement gets to size the client's simulation.
+ * A PING is a 4-byte payload; five of them a minute is not the reason a room costs anything.
+ */
+declare const PING_INTERVAL_MS = 2000;
 /** How long an outbound RPC waits for its `REPLY` before rejecting. */
 declare const CALL_TIMEOUT_MS = 10000;
 interface SessionOptions {
@@ -419,10 +1066,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 +1092,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 +1111,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 +1123,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 +1151,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 +1173,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 +1187,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 +1244,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, 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 };