@jgengine/core 0.17.0 → 0.18.1

package/dist/runtime/gameRuntime.js

@@ -1,4 +1,4 @@
-import { runCommand } from "./commandRunner.js";
+import { resolveCommandScope, runCommand } from "./commandRunner.js";
 import { createEmptyPlayerRow, createRuntimeSnapshot, } from "./snapshot.js";
 /** @internal */
 export function createGameRuntime(definition) {
@@ -6,6 +6,7 @@ export function createGameRuntime(definition) {
     let initialized = false;
     return {
         gameId: definition.gameId,
+        topology: definition.topology,
         save: definition.save,
         hasTick: loop?.onTick !== undefined,
         hydrate(input) {
@@ -23,6 +24,7 @@ export function createGameRuntime(definition) {
                     get snapshot() {
                         return current;
                     },
+                    nowMs: input.nowMs ?? Date.now(),
                     setSnapshot(next) {
                         current = next;
                     },
@@ -30,10 +32,18 @@ export function createGameRuntime(definition) {
             }
             return current;
         },
-        runCommand(snapshot, actorUserId, commandName, input) {
-            return runCommand(snapshot, definition.commands, commandName, input, actorUserId);
+        runCommand(snapshot, actorUserId, commandName, input, nowMs) {
+            return runCommand(snapshot, definition.commands, commandName, input, actorUserId, nowMs ?? Date.now());
         },
-        tick(snapshot, dtSeconds) {
+        commandScope(commandName, input, actorUserId) {
+            return resolveCommandScope(definition.commands, commandName, input, actorUserId);
+        },
+        joinScope(userId, isNew) {
+            if (!loop?.onNewPlayer)
+                return { players: [userId], chunkKeys: [] };
+            return loop.joinScope?.(userId, isNew);
+        },
+        tick(snapshot, dtSeconds, nowMs) {
             if (!loop?.onTick)
                 return snapshot;
             let current = snapshot;
@@ -44,6 +54,7 @@ export function createGameRuntime(definition) {
                 get playerIds() {
                     return Object.keys(current.players);
                 },
+                nowMs: nowMs ?? Date.now(),
                 setSnapshot(next) {
                     current = next;
                 },
@@ -51,7 +62,7 @@ export function createGameRuntime(definition) {
             loop.onTick(ctx, dtSeconds);
             return current;
         },
-        joinPlayer(snapshot, userId, isNew) {
+        joinPlayer(snapshot, userId, isNew, nowMs) {
             const players = { ...snapshot.players };
             if (!players[userId]) {
                 players[userId] = createEmptyPlayerRow(userId);
@@ -76,6 +87,7 @@ export function createGameRuntime(definition) {
                     return next;
                 },
                 player: { userId, isNew },
+                nowMs: nowMs ?? Date.now(),
                 setSnapshot(updated) {
                     next = updated;
                 },
@@ -96,3 +108,12 @@ export function createGameRuntime(definition) {
         },
     };
 }
+/** Seed a fresh player through the same onNewPlayer hook as joining, without hydrating or modifying a world. */
+export function initialPlayerState(runtime, userId, nowMs = Date.now()) {
+    const snapshot = createRuntimeSnapshot({ gameId: runtime.gameId, serverId: "" });
+    const initialized = runtime.joinPlayer(snapshot, userId, true, nowMs);
+    const player = initialized.players[userId];
+    if (!player)
+        throw new Error(`onNewPlayer removed player "${userId}"`);
+    return structuredClone(player);
+}

package/dist/runtime/headlessRunner.d.ts

@@ -3,6 +3,7 @@ import type { PointerAxisState } from "../input/pointerAxis.js";
 import type { ModelAssetRef } from "../scene/assetCatalog.js";
 import { type GameContext, type GameContextContent, type GameContextModels } from "./gameContext.js";
 import type { InputSnapshot } from "./inputSnapshot.js";
+import { type SimSnapshot } from "./simSnapshot.js";
 /** One step's worth of player intent handed to {@link HeadlessRunner.step} — the held-action set and pointer state the shell would otherwise publish from the browser each frame. */
 export interface HeadlessInput {
     /** Replaces the held-action set for this step; edge detection (`justPressed`/`justReleased`) rolls the previous set forward. Omit to keep the last published set. */
@@ -31,8 +32,12 @@ export interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultipl
      * `onTick` and don't need it.
      */
     playerMovement?: boolean;
+    /** Movement tuning — when `playerMovement` is on, the shell resolves from `definition.world`/`physics`; pass a direct config to test flight or other movement overrides headlessly. */
+    movement?: import("../game/playableGame.js").PlayerMovementConfig;
     /** Yaw heading (radians) fed to the movement controller when `playerMovement` is on; the shell supplies its camera yaw. */
     heading?: number;
+    /** Pitch (radians) fed alongside yaw for 6DOF spectator flight when `alignWithLook` is set. */
+    pitch?: number;
     /** Render-model lookup for collider auto-fit — pass what the shell would derive from `entityModels`/`objectModels` so headless raycasts hit the same boxes as play. */
     models?: GameContextModels;
 }
@@ -71,5 +76,10 @@ export interface HeadlessRunner {
     publishInput(input: HeadlessInput): void;
     /** Drive the game's own UI commands / intents headlessly — the same registry `ctx.game.commands` and the shell's command sink dispatch into. No renderer, no pointer simulation: dispatch an intent, then read reactive state off `ctx`. */
     readonly ui: HeadlessCommandInterface;
+    /** Capture the whole simulation (world, clock, loop, rng cursor) for {@link restore}; with a fixed `simulation.hz` and recorded input, replaying from it reproduces the run exactly. */
+    snapshot(): SimSnapshot;
+    restore(snapshot: SimSnapshot): void;
+    /** Current simulation tick (`ctx.sim.tick()`). */
+    tick(): number;
 }
 export declare function createHeadlessRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HeadlessRunnerOptions<TAssetRef, TMultiplayer>): HeadlessRunner;

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;