@jgengine/core 0.18.0 → 0.18.1

package/dist/runtime/headlessRunner.js

@@ -1,6 +1,7 @@
 import { resolvePlayerMovementTuning, stepPlayerMovement, } from "../movement/playerMovement.js";
 import { advanceBehaviors } from "../scene/behaviorRuntime.js";
 import { createGameContext } from "./gameContext.js";
+import { createContextSimSnapshot } from "./simSnapshot.js";
 export function createHeadlessRunner(options) {
     const { definition, loop } = options;
     const content = options.content ?? {};
@@ -15,8 +16,13 @@ export function createHeadlessRunner(options) {
     });
     loop?.onInit?.(ctx);
     loop?.onNewPlayer?.(ctx);
+    const simSnapshot = createContextSimSnapshot(ctx);
     const tuning = options.playerMovement === true
-        ? resolvePlayerMovementTuning({ physics: definition.physics, world: definition.world })
+        ? resolvePlayerMovementTuning({
+            physics: definition.physics,
+            world: definition.world,
+            movement: options.movement,
+        })
         : null;
     function publishInput(input) {
         if (input.held !== undefined)
@@ -47,13 +53,25 @@ export function createHeadlessRunner(options) {
             if (input !== undefined)
                 publishInput(input);
             const dt = Math.min(dtSeconds, maxStep);
-            const gameDt = ctx.time.advance(dt);
-            if (tuning !== null) {
-                stepPlayerMovement(ctx, player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer() }, dt, tuning, options.heading);
-            }
-            loop?.onTick?.(ctx, gameDt);
-            advanceBehaviors(ctx, gameDt);
-            return gameDt;
+            let total = 0;
+            ctx.sim.advance(dt, (stepDt) => {
+                const gameDt = ctx.time.advance(stepDt);
+                total += gameDt;
+                ctx.sim.runStages("beforeMovement", stepDt);
+                if (tuning !== null) {
+                    stepPlayerMovement(ctx, player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer() }, stepDt, tuning, options.heading, options.pitch);
+                }
+                ctx.sim.runStages("afterMovement", stepDt);
+                loop?.onTick?.(ctx, gameDt);
+                advanceBehaviors(ctx, gameDt);
+                ctx.sim.runStages("afterTick", stepDt);
+            });
+            return total;
+        },
+        snapshot: () => simSnapshot.capture(),
+        restore(snapshot) {
+            simSnapshot.restore(snapshot);
         },
+        tick: () => ctx.sim.tick(),
     };
 }

package/dist/runtime/hostPolicy.d.ts

@@ -1,6 +1,6 @@
 import type { GameServerStatus, SessionVisibility } from "./hostPersistence.js";
 /**
- * Hard ceiling on `slotsPerServer` for a single hosted server row.
+ * Room-topology ceiling on `slotsPerServer`; shared membership uses indexed rows instead.
  *
  * A hosted server keeps its whole roster, every member's session state, and the world row in one
  * backing document. On Convex that document caps at 1 MiB with at most 1024 entries in an object, and
@@ -10,7 +10,7 @@ import type { GameServerStatus, SessionVisibility } from "./hostPersistence.js";
  */
 export declare const JG_MAX_MEMBERS_PER_SERVER = 256;
 /** Whether a `slotsPerServer` value is a capacity a single hosted server row can actually hold. */
-export declare function validateSlotsPerServer(slotsPerServer: number): {
+export declare function validateSlotsPerServer(slotsPerServer: number, topology?: "rooms" | "shared"): {
     ok: true;
 } | {
     ok: false;
@@ -75,6 +75,7 @@ export declare function isServerMember(memberUserIds: readonly string[], userId:
  * True when the server has no free slots for a non-member. Existing members never count as
  * "full" so rejoin/leave cycles keep working.
  */
+export declare function isServerFull(memberCount: number, slotsPerServer: number, isMember: boolean): boolean;
 export declare function isServerFull(memberUserIds: readonly string[], slotsPerServer: number, userId: string): boolean;
 /**
  * Whether a private-visibility server blocks this join (non-member without a matching code).

package/dist/runtime/hostPolicy.js

@@ -1,6 +1,6 @@
 import { normalizeJoinCode } from "../multiplayer/matchmaking.js";
 /**
- * Hard ceiling on `slotsPerServer` for a single hosted server row.
+ * Room-topology ceiling on `slotsPerServer`; shared membership uses indexed rows instead.
  *
  * A hosted server keeps its whole roster, every member's session state, and the world row in one
  * backing document. On Convex that document caps at 1 MiB with at most 1024 entries in an object, and
@@ -10,11 +10,11 @@ import { normalizeJoinCode } from "../multiplayer/matchmaking.js";
  */
 export const JG_MAX_MEMBERS_PER_SERVER = 256;
 /** Whether a `slotsPerServer` value is a capacity a single hosted server row can actually hold. */
-export function validateSlotsPerServer(slotsPerServer) {
-    if (!Number.isInteger(slotsPerServer) || slotsPerServer < 1) {
+export function validateSlotsPerServer(slotsPerServer, topology = "rooms") {
+    if (!Number.isSafeInteger(slotsPerServer) || slotsPerServer < 1) {
         return { ok: false, reason: `slotsPerServer must be a positive integer, got ${slotsPerServer}` };
     }
-    if (slotsPerServer > JG_MAX_MEMBERS_PER_SERVER) {
+    if (topology !== "shared" && slotsPerServer > JG_MAX_MEMBERS_PER_SERVER) {
         return {
             ok: false,
             reason: `slotsPerServer ${slotsPerServer} exceeds JG_MAX_MEMBERS_PER_SERVER (${JG_MAX_MEMBERS_PER_SERVER}). ` +
@@ -76,12 +76,10 @@ export function canJoinPrivateServer(args) {
 export function isServerMember(memberUserIds, userId) {
     return memberUserIds.includes(userId);
 }
-/**
- * True when the server has no free slots for a non-member. Existing members never count as
- * "full" so rejoin/leave cycles keep working.
- */
-export function isServerFull(memberUserIds, slotsPerServer, userId) {
-    return memberUserIds.length >= slotsPerServer && !memberUserIds.includes(userId);
+export function isServerFull(members, slotsPerServer, member) {
+    const count = typeof members === "number" ? members : members.length;
+    const isMember = typeof member === "boolean" ? member : typeof members !== "number" && members.includes(member);
+    return count >= slotsPerServer && !isMember;
 }
 /**
  * Whether a private-visibility server blocks this join (non-member without a matching code).

package/dist/runtime/hostedGameRunner.js

@@ -2,6 +2,9 @@ import { syncLifecyclePhase } from "../game/gamePhase.js";
 import { advanceBehaviors } from "../scene/behaviorRuntime.js";
 import { createGameContext } from "./gameContext.js";
 import {} from "./inputSnapshot.js";
+import { serverStep } from "../movement/serverStep.js";
+import { resolvePlayerMovementTuning } from "../movement/playerMovement.js";
+import { createInputRecorder } from "./inputRecorder.js";
 import { createWorldReplicator } from "./worldReplication.js";
 /** Reserved command name the authoritative host intercepts on the existing `runCommand` transport to route a client's {@link InputFrame} to `session.input`, so per-tick input needs no separate wire. */
 export const INPUT_COMMAND = "engine.input";
@@ -24,7 +27,10 @@ export function createHostedGameRunner(options) {
     });
     const members = new Map();
     const inputs = new Map();
+    const latestInputs = new Map();
+    const movementTuning = resolvePlayerMovementTuning({ world: definition.world, physics: definition.physics });
     const inputSeq = new Map();
+    let hostTick = 0;
     loop.onInit?.(ctx);
     syncLifecyclePhase(ctx, definition.lifecycle);
     if (restore !== undefined)
@@ -49,6 +55,7 @@ export function createHostedGameRunner(options) {
                 return;
             members.delete(userId);
             inputs.delete(userId);
+            latestInputs.delete(userId);
             inputSeq.delete(userId);
             loop.onPlayerLeave?.(ctx, player);
             ctx.game.players?.leave(userId);
@@ -61,24 +68,45 @@ export function createHostedGameRunner(options) {
                     return;
                 inputSeq.set(userId, seq);
             }
-            inputs.set(userId, frame);
-            ctx.game.players?.setInput(userId, frame);
+            let recorder = inputs.get(userId);
+            if (recorder === undefined) {
+                recorder = createInputRecorder();
+                inputs.set(userId, recorder);
+            }
+            recorder.record(frame.tick ?? ctx.sim.tick() + 1, frame);
+            latestInputs.set(userId, frame);
         },
         heldInput(userId) {
-            return inputs.get(userId) ?? null;
+            return latestInputs.get(userId) ?? null;
         },
         command(userId, name, input) {
             return ctx.game.commands.runAs(userId, name, input);
         },
         tick(dt) {
-            loop.onTick?.(ctx, dt);
-            advanceBehaviors(ctx, dt);
+            hostTick += 1;
+            ctx.sim.advance(dt, (stepDt, tick) => {
+                for (const [userId, recorder] of inputs) {
+                    const frame = recorder.frameAt(tick);
+                    if (frame !== null)
+                        ctx.game.players?.setInput(userId, frame);
+                }
+                ctx.sim.runStages("beforeMovement", stepDt);
+                for (const userId of members.keys()) {
+                    const frame = inputs.get(userId)?.frameAt(tick) ?? null;
+                    if (frame !== null)
+                        serverStep(ctx, userId, frame, stepDt, movementTuning);
+                }
+                ctx.sim.runStages("afterMovement", stepDt);
+                loop.onTick?.(ctx, stepDt);
+                advanceBehaviors(ctx, stepDt);
+                ctx.sim.runStages("afterTick", stepDt);
+            });
             syncLifecyclePhase(ctx, definition.lifecycle);
             return replicator.commit();
         },
         diff: (sinceRevision) => replicator.diff(sinceRevision),
         revision: () => replicator.revision(),
-        snapshot: (viewer) => ctx.snapshot(viewer),
+        snapshot: (viewer) => ctx.snapshot(viewer === undefined ? undefined : { ...viewer, tick: hostTick }),
         projectsViewers: () => ctx.replicatesPerViewer(),
         members: () => Array.from(members.keys()),
         context: () => ctx,

package/dist/runtime/hostedWorldSession.d.ts

@@ -5,24 +5,14 @@ import type { GameDefinition, LoopPlayer } from "../game/defineGame.js";
 import { type HostedGameRunner, type InputFrame } from "./hostedGameRunner.js";
 import type { WorldDiff } from "./worldReplication.js";
 import type { SnapshotViewer, WorldSnapshot } from "./worldSnapshot.js";
-/** One hosted world's persisted authoritative state — the unit a {@link HostedWorldStore} loads and saves. */
-export interface HostedWorldRecord {
-    snapshot: WorldSnapshot;
-    revision: number;
-}
-/**
- * Narrow persistence seam for a hosted world — the {@link HostedWorldRecord} counterpart of `HostPersistence`.
- * Backends implement it (memory/file/sql/convex); the session never names one. A stateful host loads once and
- * saves on a cadence; a stateless host reconstructs from `load()` each invocation.
- */
-export interface HostedWorldStore {
-    load(): HostedWorldRecord | null;
-    save(record: HostedWorldRecord): void;
-}
+import type { HostedWorldRecord, HostedWorldStore, SyncHostedWorldStore } from "./hostedWorldStore.js";
+export type { HostedWorldRecord, HostedWorldStore, SyncHostedWorldStore } from "./hostedWorldStore.js";
 /** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host.
  * @internal
  */
-export declare function memoryWorldStore(seed?: HostedWorldRecord): HostedWorldStore;
+export declare function memoryWorldStore(seed?: HostedWorldRecord): SyncHostedWorldStore;
+/** Async in-process store for callers exercising the production persistence contract. */
+export declare function asyncMemoryWorldStore(seed?: HostedWorldRecord): HostedWorldStore;
 /** A client replication pull: a full baseline (first sync / fell behind) or a diff since the client's cursor. */
 export type HostedWorldSync = {
     kind: "baseline";
@@ -39,7 +29,7 @@ export interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMul
     host?: LoopPlayer;
     now?: () => number;
     /** Where the authoritative snapshot persists; defaults to {@link memoryWorldStore}. */
-    store?: HostedWorldStore;
+    store?: SyncHostedWorldStore;
     /** Minimum elapsed ms between auto-saves on tick, measured against `now` (defaults to `Date.now` when omitted). Default `0` — persist on every revision-changing tick. */
     saveIntervalMs?: number;
     /** Render-model lookup for collider auto-fit, forwarded to the runner — see {@link HostedGameRunnerOptions.models}. */
@@ -59,6 +49,8 @@ export interface HostedWorldSession {
     tick(dt: number): number;
     /** Replication pull: `null`/`0` cursor → full baseline; a prior revision → a diff since it. */
     sync(sinceRevision: number | null): HostedWorldSync;
+    /** Alias used by host transports when pulling the next baseline or diff for a subscriber. */
+    pull(sinceRevision: number | null): HostedWorldSync;
     /** The full world baseline projected for one viewer (private/AOI). Identity when no replication policy is set. */
     snapshotFor(viewer: SnapshotViewer): WorldSnapshot;
     /** True when {@link snapshotFor} is viewer-dependent — a host must serve each connection its own projected frame instead of a shared diff. */
@@ -73,3 +65,7 @@ export interface HostedWorldSession {
  * @internal
  */
 export declare function createHostedWorldSession<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedWorldSessionOptions<TAssetRef, TMultiplayer>): HostedWorldSession;
+/** Build a hosted session from an asynchronous persistence backend. */
+export declare function createHostedWorldSessionAsync<TAssetRef extends ModelAssetRef, TMultiplayer>(options: Omit<HostedWorldSessionOptions<TAssetRef, TMultiplayer>, "store"> & {
+    store: HostedWorldStore;
+}): Promise<HostedWorldSession>;

package/dist/runtime/hostedWorldSession.js

@@ -11,6 +11,14 @@ export function memoryWorldStore(seed) {
         },
     };
 }
+/** Async in-process store for callers exercising the production persistence contract. */
+export function asyncMemoryWorldStore(seed) {
+    let record = seed ?? null;
+    return {
+        async load() { return record; },
+        async save(next) { record = { snapshot: next.snapshot, revision: next.revision }; },
+    };
+}
 /** Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick.
  * @internal
  */
@@ -33,6 +41,12 @@ export function createHostedWorldSession(options) {
         savedRevision = runner.revision();
         store.save({ snapshot: runner.snapshot(), revision: savedRevision });
     }
+    const pull = (sinceRevision) => {
+        if (sinceRevision === null || sinceRevision <= 0) {
+            return { kind: "baseline", revision: runner.revision(), snapshot: runner.snapshot() };
+        }
+        return { kind: "diff", diff: runner.diff(sinceRevision) };
+    };
     return {
         join: (userId, isNew) => runner.join(userId, isNew),
         leave: (userId) => runner.leave(userId),
@@ -49,12 +63,8 @@ export function createHostedWorldSession(options) {
             }
             return revision;
         },
-        sync(sinceRevision) {
-            if (sinceRevision === null || sinceRevision <= 0) {
-                return { kind: "baseline", revision: runner.revision(), snapshot: runner.snapshot() };
-            }
-            return { kind: "diff", diff: runner.diff(sinceRevision) };
-        },
+        pull,
+        sync: pull,
         snapshotFor: (viewer) => runner.snapshot(viewer),
         projectsViewers: () => runner.projectsViewers(),
         revision: () => runner.revision(),
@@ -63,3 +73,16 @@ export function createHostedWorldSession(options) {
         runner: () => runner,
     };
 }
+/** Build a hosted session from an asynchronous persistence backend. */
+export async function createHostedWorldSessionAsync(options) {
+    const { store, ...sessionOptions } = options;
+    const loaded = await store.load();
+    const session = createHostedWorldSession({
+        ...sessionOptions,
+        store: {
+            load: () => loaded,
+            save: (record) => { void store.save(record); },
+        },
+    });
+    return session;
+}

package/dist/runtime/hostedWorldStore.d.ts

@@ -0,0 +1,20 @@
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/** One hosted world's persisted authoritative state — the unit a {@link HostedWorldStore} loads and saves. */
+export interface HostedWorldRecord {
+    snapshot: WorldSnapshot;
+    revision: number;
+}
+/**
+ * Narrow persistence seam for a hosted world — the {@link HostedWorldRecord} counterpart of `HostPersistence`.
+ * Backends implement it (memory/file/sql/convex); the session never names one. A stateful host loads once and
+ * saves on a cadence; a stateless host reconstructs from `load()` each invocation.
+ */
+export interface HostedWorldStore {
+    load(): Promise<HostedWorldRecord | null>;
+    save(record: HostedWorldRecord): Promise<void>;
+}
+/** Synchronous store adapter retained for deterministic in-process tests. */
+export interface SyncHostedWorldStore {
+    load(): HostedWorldRecord | null;
+    save(record: HostedWorldRecord): void;
+}

package/dist/runtime/hostedWorldStore.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/inputRecorder.d.ts

@@ -0,0 +1,30 @@
+import type { InputFrame } from "./inputSnapshot.js";
+/** An input frame and the first tick it applies to. */
+export interface RecordedInput {
+    tick: number;
+    frame: InputFrame;
+}
+/** Serializable recorder contents, sorted by tick. */
+export interface InputRecorderState {
+    frames: RecordedInput[];
+}
+/** Tick-indexed input log: record per tick, look up the frame in force at any tick. */
+export interface InputRecorder {
+    /** Store the frame in force from `tick` onward. Recording the same tick twice replaces the earlier frame. */
+    record(tick: number, frame: InputFrame): void;
+    /** The frame in force at `tick`: the latest recorded frame whose tick is at most `tick`, or `null` before the first. */
+    frameAt(tick: number): InputFrame | null;
+    frames(): readonly RecordedInput[];
+    /** Highest recorded tick, or `-1` when empty. */
+    lastTick(): number;
+    clear(): void;
+    snapshot(): InputRecorderState;
+    restore(state: InputRecorderState): void;
+}
+/**
+ * Tick-indexed input log for deterministic replay: record what each tick saw, then feed {@link frameAt} back
+ * into a runner stepping from a matching {@link createSimSnapshotRegistry} snapshot.
+ *
+ * @capability input-recorder tick-indexed input log for replay, rollback, and regression tests
+ */
+export declare function createInputRecorder(): InputRecorder;

package/dist/runtime/inputRecorder.js

@@ -0,0 +1,59 @@
+function cloneFrame(frame) {
+    return {
+        held: [...frame.held],
+        pointer: frame.pointer === null ? null : { ...frame.pointer },
+        ...(frame.analog === undefined ? {} : { analog: frame.analog === null ? null : { ...frame.analog } }),
+        ...(frame.tick === undefined ? {} : { tick: frame.tick }),
+    };
+}
+/**
+ * Tick-indexed input log for deterministic replay: record what each tick saw, then feed {@link frameAt} back
+ * into a runner stepping from a matching {@link createSimSnapshotRegistry} snapshot.
+ *
+ * @capability input-recorder tick-indexed input log for replay, rollback, and regression tests
+ */
+export function createInputRecorder() {
+    let frames = [];
+    function indexAtOrBefore(tick) {
+        let lo = 0;
+        let hi = frames.length - 1;
+        let found = -1;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            if (frames[mid].tick <= tick) {
+                found = mid;
+                lo = mid + 1;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        return found;
+    }
+    return {
+        record(tick, frame) {
+            const entry = { tick, frame: cloneFrame(frame) };
+            const index = indexAtOrBefore(tick);
+            if (index >= 0 && frames[index].tick === tick) {
+                frames[index] = entry;
+                return;
+            }
+            frames.splice(index + 1, 0, entry);
+        },
+        frameAt(tick) {
+            const index = indexAtOrBefore(tick);
+            return index < 0 ? null : frames[index].frame;
+        },
+        frames: () => frames,
+        lastTick: () => (frames.length === 0 ? -1 : frames[frames.length - 1].tick),
+        clear() {
+            frames = [];
+        },
+        snapshot: () => ({ frames: frames.map((entry) => ({ tick: entry.tick, frame: cloneFrame(entry.frame) })) }),
+        restore(state) {
+            frames = state.frames
+                .map((entry) => ({ tick: entry.tick, frame: cloneFrame(entry.frame) }))
+                .sort((a, b) => a.tick - b.tick);
+        },
+    };
+}

package/dist/runtime/inputSnapshot.d.ts

@@ -6,8 +6,16 @@ export interface InputFrame {
     pointer: PointerAxisState | null;
     /** Analog per-action magnitudes (0..1) for actions driven by a continuous source (virtual joystick, gamepad stick); absent/null means every held action is fully pressed. */
     analog?: Readonly<Record<string, number>> | null;
+    /** Simulation tick (`ctx.sim.tick()`) the frame was captured for; hosts and replay align inputs on it. Absent from senders that predate the fixed-step loop. */
+    tick?: number;
 }
 export interface InputSnapshot {
+    /** Trigger controller vibration for a local user's gamepad when supported. */
+    rumble(userId: string, options: {
+        strong: number;
+        weak: number;
+        ms: number;
+    }): Promise<boolean>;
     /** Replaces the held-action set for this frame, rolling the previous held set forward for edge detection (#671). Called by the shell before `onTick` each frame; does not bump `ctx.version()` or notify `ctx.subscribe` listeners — per-frame publishes would storm subscribers. */
     publish(held: readonly string[]): void;
     /** Replaces the normalized pointer-position state for this frame (#293). Same no-notify contract as `publish`. */

package/dist/runtime/inputSnapshot.js

@@ -12,6 +12,7 @@ export function createInputSnapshot() {
         return heldSet.has(action) ? 1 : 0;
     };
     return {
+        rumble: async () => false,
         publish(held) {
             previousHeldSet = heldSet;
             heldList = Object.freeze([...held]);

package/dist/runtime/poseInterpolation.d.ts

@@ -0,0 +1,36 @@
+import type { EntityStore } from "../scene/entityStore.js";
+/** A render pose sampled between two simulation steps: `[x, y, z, rotationY]`. */
+export type RenderPose = [x: number, y: number, z: number, rotationY: number];
+/** Serializable previous-step poses keyed by entity id. */
+export interface PoseHistoryState {
+    previous: Record<string, RenderPose>;
+}
+/** Previous-step pose buffer: capture at each fixed step, sample between steps for rendering. */
+export interface PoseHistory {
+    /** Capture every entity's current pose as the "previous" step. Call once at the start of each fixed step. */
+    beginStep(entities: EntityStore): void;
+    /**
+     * Write the pose `alpha` of the way from the previous step to the live pose into `out`. Returns `false` (and
+     * leaves `out` untouched) when the entity is unknown; an entity with no history or one that jumped farther
+     * than `snapDistance` gets its live pose.
+     */
+    sample(entities: EntityStore, id: string, alpha: number, out: RenderPose): boolean;
+    /** Forget an entity's previous pose so its next frame renders live (respawn, teleport). */
+    snap(id: string): void;
+    retune(options: {
+        snapDistance?: number;
+    }): void;
+    snapshot(): PoseHistoryState;
+    restore(state: PoseHistoryState): void;
+}
+/** Shortest-arc interpolation between two yaw angles. */
+export declare function lerpAngle(from: number, to: number, t: number): number;
+/**
+ * Previous-step pose buffer for render interpolation under a fixed-step loop. Reuses one 4-slot array per
+ * entity so a step over N entities allocates only for entities seen for the first time.
+ *
+ * @capability pose-interpolation render entity poses between fixed simulation steps without stutter
+ */
+export declare function createPoseHistory(options?: {
+    snapDistance?: number;
+}): PoseHistory;

package/dist/runtime/poseInterpolation.js

@@ -0,0 +1,91 @@
+const TWO_PI = Math.PI * 2;
+/** Shortest-arc interpolation between two yaw angles. */
+export function lerpAngle(from, to, t) {
+    let delta = (to - from) % TWO_PI;
+    if (delta > Math.PI)
+        delta -= TWO_PI;
+    else if (delta < -Math.PI)
+        delta += TWO_PI;
+    return from + delta * t;
+}
+/**
+ * Previous-step pose buffer for render interpolation under a fixed-step loop. Reuses one 4-slot array per
+ * entity so a step over N entities allocates only for entities seen for the first time.
+ *
+ * @capability pose-interpolation render entity poses between fixed simulation steps without stutter
+ */
+export function createPoseHistory(options) {
+    let snapDistance = options?.snapDistance ?? 8;
+    const previous = new Map();
+    const seen = new Set();
+    return {
+        beginStep(entities) {
+            seen.clear();
+            for (const entity of entities.list()) {
+                seen.add(entity.id);
+                let slot = previous.get(entity.id);
+                if (slot === undefined) {
+                    slot = [0, 0, 0, 0];
+                    previous.set(entity.id, slot);
+                }
+                slot[0] = entity.position[0];
+                slot[1] = entity.position[1];
+                slot[2] = entity.position[2];
+                slot[3] = entity.rotationY;
+            }
+            if (previous.size !== seen.size) {
+                for (const id of previous.keys()) {
+                    if (!seen.has(id))
+                        previous.delete(id);
+                }
+            }
+        },
+        sample(entities, id, alpha, out) {
+            const live = entities.get(id);
+            if (live === null)
+                return false;
+            const prev = previous.get(id);
+            const t = alpha < 0 ? 0 : alpha > 1 ? 1 : alpha;
+            if (prev === undefined || t >= 1) {
+                out[0] = live.position[0];
+                out[1] = live.position[1];
+                out[2] = live.position[2];
+                out[3] = live.rotationY;
+                return true;
+            }
+            const dx = live.position[0] - prev[0];
+            const dy = live.position[1] - prev[1];
+            const dz = live.position[2] - prev[2];
+            if (dx * dx + dy * dy + dz * dz > snapDistance * snapDistance) {
+                out[0] = live.position[0];
+                out[1] = live.position[1];
+                out[2] = live.position[2];
+                out[3] = live.rotationY;
+                return true;
+            }
+            out[0] = prev[0] + dx * t;
+            out[1] = prev[1] + dy * t;
+            out[2] = prev[2] + dz * t;
+            out[3] = lerpAngle(prev[3], live.rotationY, t);
+            return true;
+        },
+        snap(id) {
+            previous.delete(id);
+        },
+        retune(next) {
+            if (next.snapDistance !== undefined)
+                snapDistance = next.snapDistance;
+        },
+        snapshot() {
+            const copy = {};
+            for (const [id, pose] of previous)
+                copy[id] = [pose[0], pose[1], pose[2], pose[3]];
+            return { previous: copy };
+        },
+        restore(state) {
+            previous.clear();
+            for (const [id, pose] of Object.entries(state.previous))
+                previous.set(id, [pose[0], pose[1], pose[2], pose[3]]);
+        },
+    };
+}

package/dist/runtime/prediction.d.ts

@@ -0,0 +1,45 @@
+import type { InputFrame } from "./inputSnapshot.js";
+/** Deterministic state transition used to advance one predicted input frame. */
+export type PredictionStep<S> = (state: S, input: InputFrame, dt: number) => S;
+/** One input, tick, and resulting state retained for authoritative replay. */
+export type PredictionRecord<S> = {
+    tick: number;
+    input: InputFrame;
+    state: S;
+    dt: number;
+};
+/** Serializable prediction state containing the confirmation baseline and pending input history. */
+export type PredictionSnapshot<S> = {
+    confirmedTick: number;
+    confirmed: S;
+    predicted: S;
+    records: PredictionRecord<S>[];
+};
+/** Stateful prediction handle supporting recording, reconciliation, inspection, and restoration. */
+export type PredictionBuffer<S> = {
+    record(input: InputFrame, dt?: number, observedState?: S): S;
+    reconcile(tick: number, authoritative: S): {
+        error: number;
+        replayed: number;
+        snapped: boolean;
+        state: S;
+    };
+    state(): S;
+    snapshot(): PredictionSnapshot<S>;
+    restore(next: PredictionSnapshot<S>): void;
+};
+/**
+ * Keeps local input predictions ahead of the last server confirmation. Reconciliation replaces the
+ * confirmed state and deterministically replays unconfirmed inputs through the supplied step function.
+ * `maxTicks` bounds retained work and memory; dropped inputs are folded into the confirmed baseline.
+ * @capability client-side input prediction with replay reconciliation
+ */
+export declare function createPredictionBuffer<S>(config: {
+    initial: S;
+    step: PredictionStep<S>;
+    maxTicks: number;
+    startTick?: number;
+    dt?: number;
+    /** Error above which a caller should snap its rendered pose to the reconciled result. */
+    snapThreshold?: number;
+}): PredictionBuffer<S>;