@jgengine/core 0.9.0 → 0.10.0

package/dist/runtime/hostedWorldSession.d.ts

@@ -0,0 +1,65 @@
+import type { CommandResult } from "../commands/commandRegistry.js";
+import type { ModelAssetRef } from "../scene/assetCatalog.js";
+import type { GameContext, GameContextContent } from "./gameContext.js";
+import type { GameDefinition, LoopPlayer } from "../game/defineGame.js";
+import { type HostedGameRunner, type InputFrame } from "./hostedGameRunner.js";
+import type { WorldDiff } from "./worldReplication.js";
+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(): HostedWorldRecord | null;
+    save(record: HostedWorldRecord): void;
+}
+/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host. */
+export declare function memoryWorldStore(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";
+    revision: number;
+    snapshot: WorldSnapshot;
+} | {
+    kind: "diff";
+    diff: WorldDiff;
+};
+/** Config for {@link createHostedWorldSession}: the game, its persistence store, and the auto-save cadence. */
+export interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMultiplayer> {
+    definition: GameDefinition<TAssetRef, TMultiplayer>;
+    content: GameContextContent;
+    host?: LoopPlayer;
+    now?: () => number;
+    /** Where the authoritative snapshot persists; defaults to {@link memoryWorldStore}. */
+    store?: HostedWorldStore;
+    /** Minimum elapsed `now()` ms between auto-saves on tick. Default `0` — persist on every revision-changing tick. */
+    saveIntervalMs?: number;
+}
+/**
+ * The stateful host substrate a long-lived backend binds (ws server, browser P2P host): a live
+ * {@link HostedGameRunner} loaded from a {@link HostedWorldStore}, auto-persisted on tick, serving each client a
+ * baseline then diffs. The stateless Convex path doesn't use this — it reconstructs a runner from the same store
+ * per invocation and diffs with `diffSnapshots`. Either way the store seam and the game code are identical.
+ */
+export interface HostedWorldSession {
+    join(userId: string, isNew: boolean): void;
+    leave(userId: string): void;
+    input(userId: string, frame: InputFrame): void;
+    command(userId: string, name: string, input: unknown): CommandResult<GameContext>;
+    tick(dt: number): number;
+    /** Replication pull: `null`/`0` cursor → full baseline; a prior revision → a diff since it. */
+    sync(sinceRevision: number | null): HostedWorldSync;
+    revision(): number;
+    members(): readonly string[];
+    /** Force-persist the current world to the store. */
+    save(): void;
+    runner(): HostedGameRunner;
+}
+/** Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick. */
+export declare function createHostedWorldSession<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedWorldSessionOptions<TAssetRef, TMultiplayer>): HostedWorldSession;

package/dist/runtime/hostedWorldSession.js

@@ -0,0 +1,57 @@
+import { createHostedGameRunner } from "./hostedGameRunner.js";
+/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host. */
+export function memoryWorldStore(seed) {
+    let record = seed ?? null;
+    return {
+        load: () => record,
+        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. */
+export function createHostedWorldSession(options) {
+    const { definition, content, host, now, saveIntervalMs = 0 } = options;
+    const store = options.store ?? memoryWorldStore();
+    const loaded = store.load();
+    const runner = createHostedGameRunner({
+        definition,
+        content,
+        ...(host === undefined ? {} : { host }),
+        ...(now === undefined ? {} : { now }),
+        ...(loaded === null ? {} : { restore: loaded.snapshot }),
+    });
+    let savedRevision = loaded?.revision ?? 0;
+    let lastSaveAt = now?.() ?? 0;
+    function persist() {
+        savedRevision = runner.revision();
+        store.save({ snapshot: runner.snapshot(), revision: savedRevision });
+    }
+    return {
+        join: (userId, isNew) => runner.join(userId, isNew),
+        leave: (userId) => runner.leave(userId),
+        input: (userId, frame) => runner.input(userId, frame),
+        command: (userId, name, input) => runner.command(userId, name, input),
+        tick(dt) {
+            const revision = runner.tick(dt);
+            if (revision !== savedRevision) {
+                const at = now?.() ?? 0;
+                if (saveIntervalMs <= 0 || at - lastSaveAt >= saveIntervalMs) {
+                    lastSaveAt = at;
+                    persist();
+                }
+            }
+            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) };
+        },
+        revision: () => runner.revision(),
+        members: () => runner.members(),
+        save: persist,
+        runner: () => runner,
+    };
+}

package/dist/runtime/inputSnapshot.d.ts

@@ -1,4 +1,10 @@
 import type { PointerAxisState } from "../input/pointerAxis.js";
+import { type AxisBinding, type AxisRange } from "../input/axisInput.js";
+/** One client's input for a tick — the semantic held-action set plus pointer state, the serializable, over-the-wire counterpart of {@link InputSnapshot} the host stores per connected player. */
+export interface InputFrame {
+    held: readonly string[];
+    pointer: PointerAxisState | null;
+}
 export interface InputSnapshot {
     /** Replaces the held-action set for this frame. 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;
@@ -8,5 +14,12 @@ export interface InputSnapshot {
     held(): readonly string[];
     /** Pointer position over the play surface, `[-1, 1]` per axis with `+y` down, published by the shell each frame; `null` until the first pointer move. */
     pointer(): PointerAxisState | null;
+    /**
+     * Instantaneous analog axis sample against the held-action set and current pointer (#533.7) — bind
+     * throttle/steer/handbrake (or any axes) to *action names*, not raw key codes, since the held set is
+     * semantic actions. Feed the result into an `AxisChannel` for smoothing; unlisted ranges default to
+     * bipolar `[-1, 1]`, so pass `{ min: 0, max: 1 }` for one-directional pedals.
+     */
+    axis<TAxes extends string>(bindings: Record<TAxes, AxisBinding>, ranges?: Partial<Record<TAxes, AxisRange>>): Record<TAxes, number>;
 }
 export declare function createInputSnapshot(): InputSnapshot;

package/dist/runtime/inputSnapshot.js

@@ -1,3 +1,4 @@
+import { sampleAxisBindings } from "../input/axisInput.js";
 export function createInputSnapshot() {
     let heldSet = new Set();
     let heldList = [];
@@ -13,5 +14,6 @@ export function createInputSnapshot() {
         isDown: (action) => heldSet.has(action),
         held: () => heldList,
         pointer: () => pointerState,
+        axis: (bindings, ranges) => sampleAxisBindings(bindings, (action) => heldSet.has(action), pointerState, ranges),
     };
 }

package/dist/runtime/motionIntents.d.ts

@@ -29,5 +29,7 @@ export interface MotionIntentBatch {
     y: number | null;
 }
 export declare function createMotionIntents(): MotionIntents;
+/** Fold a batch's vertical impulses into a controller's velocity, then apply an outright `setVerticalVelocity` override — the vertical counterpart of {@link applyHorizontalImpulses}. */
+export declare function applyMotionImpulses(currentVelocity: number, batch: MotionIntentBatch | null): number;
 /** Fold a batch's horizontal pushes into a controller's velocity pair — shared by the walk and voxel drivers. */
 export declare function applyHorizontalImpulses(velocityX: number, velocityZ: number, batch: MotionIntentBatch | null): readonly [number, number];

package/dist/runtime/motionIntents.js

@@ -29,6 +29,17 @@ export function createMotionIntents() {
         },
     };
 }
+/** Fold a batch's vertical impulses into a controller's velocity, then apply an outright `setVerticalVelocity` override — the vertical counterpart of {@link applyHorizontalImpulses}. */
+export function applyMotionImpulses(currentVelocity, batch) {
+    if (batch === null)
+        return currentVelocity;
+    let velocity = currentVelocity;
+    for (const impulse of batch.impulses)
+        velocity += impulse;
+    if (batch.verticalVelocity !== null)
+        velocity = batch.verticalVelocity;
+    return velocity;
+}
 /** Fold a batch's horizontal pushes into a controller's velocity pair — shared by the walk and voxel drivers. */
 export function applyHorizontalImpulses(velocityX, velocityZ, batch) {
     if (batch === null || batch.horizontalImpulses.length === 0)

package/dist/runtime/worldChannel.d.ts

@@ -0,0 +1,58 @@
+import type { GameContext } from "./gameContext.js";
+import type { InputFrame } from "./hostedGameRunner.js";
+import type { HostedWorldSession } from "./hostedWorldSession.js";
+import type { WorldDiff } from "./worldReplication.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/** Host→client frame: the full baseline a joiner needs, then per-tick diffs. What a transport marshals downstream. */
+export type WorldServerFrame = {
+    t: "baseline";
+    revision: number;
+    snapshot: WorldSnapshot;
+} | {
+    t: "diff";
+    diff: WorldDiff;
+};
+/** Client→host frame: a player's session verbs. What a transport marshals upstream. */
+export type WorldClientFrame = {
+    t: "join";
+    isNew: boolean;
+} | {
+    t: "leave";
+} | {
+    t: "command";
+    name: string;
+    input: unknown;
+} | {
+    t: "input";
+    frame: InputFrame;
+};
+/** One client's link on the host side: routes its upstream frames into the shared session, pushes it sync frames. */
+export interface WorldHostConnection {
+    receive(frame: WorldClientFrame): void;
+    push(): void;
+    close(): void;
+}
+/**
+ * The transport-agnostic host: fans one {@link HostedWorldSession} out to many connections, each tracking its own
+ * revision cursor so a joiner gets a baseline and everyone else gets diffs. A ws server, a Convex function, or an
+ * in-process loopback all drive the same shape — decode a frame → `connection.receive`; after `session.tick` →
+ * `broadcast`. No wire format is assumed; frames are plain data a transport serializes however it likes.
+ */
+export interface WorldHost {
+    connect(userId: string, send: (frame: WorldServerFrame) => void): WorldHostConnection;
+    broadcast(): void;
+    session(): HostedWorldSession;
+}
+/** Build a {@link WorldHost} fanning one {@link HostedWorldSession} out to many cursor-tracked connections. */
+export declare function createWorldHost(session: HostedWorldSession): WorldHost;
+/** The client end of a {@link WorldHost} connection: applies server frames to a local `ctx`, sends session verbs upstream. */
+export interface WorldClientLink {
+    receive(frame: WorldServerFrame): void;
+    join(isNew: boolean): void;
+    leave(): void;
+    command(name: string, input: unknown): void;
+    input(frame: InputFrame): void;
+    revision(): number;
+}
+/** Build a {@link WorldClientLink} — the client end that mirrors host frames into `ctx` and sends session verbs upstream. */
+export declare function createWorldClientLink(ctx: Pick<GameContext, "hydrate">, send: (frame: WorldClientFrame) => void): WorldClientLink;

package/dist/runtime/worldChannel.js

@@ -0,0 +1,69 @@
+import { createWorldMirror } from "./worldMirror.js";
+/** Build a {@link WorldHost} fanning one {@link HostedWorldSession} out to many cursor-tracked connections. */
+export function createWorldHost(session) {
+    const connections = new Set();
+    function connect(userId, send) {
+        let cursor = 0;
+        const connection = {
+            receive(frame) {
+                switch (frame.t) {
+                    case "join":
+                        session.join(userId, frame.isNew);
+                        break;
+                    case "leave":
+                        session.leave(userId);
+                        break;
+                    case "command":
+                        session.command(userId, frame.name, frame.input);
+                        break;
+                    case "input":
+                        session.input(userId, frame.frame);
+                        break;
+                }
+            },
+            push() {
+                if (cursor !== 0 && cursor === session.revision())
+                    return;
+                const sync = session.sync(cursor === 0 ? null : cursor);
+                if (sync.kind === "baseline") {
+                    cursor = sync.revision;
+                    send({ t: "baseline", revision: sync.revision, snapshot: sync.snapshot });
+                }
+                else {
+                    cursor = sync.diff.revision;
+                    send({ t: "diff", diff: sync.diff });
+                }
+            },
+            close() {
+                connections.delete(connection);
+            },
+        };
+        connections.add(connection);
+        return connection;
+    }
+    return {
+        connect,
+        broadcast() {
+            for (const connection of connections)
+                connection.push();
+        },
+        session: () => session,
+    };
+}
+/** Build a {@link WorldClientLink} — the client end that mirrors host frames into `ctx` and sends session verbs upstream. */
+export function createWorldClientLink(ctx, send) {
+    const mirror = createWorldMirror(ctx);
+    return {
+        receive(frame) {
+            if (frame.t === "baseline")
+                mirror.applyBaseline(frame.revision, frame.snapshot);
+            else
+                mirror.applyDiff(frame.diff);
+        },
+        join: (isNew) => send({ t: "join", isNew }),
+        leave: () => send({ t: "leave" }),
+        command: (name, input) => send({ t: "command", name, input }),
+        input: (frame) => send({ t: "input", frame }),
+        revision: () => mirror.revision(),
+    };
+}

package/dist/runtime/worldMirror.d.ts

@@ -0,0 +1,24 @@
+import type { GameContext } from "./gameContext.js";
+import type { HostedWorldSession } from "./hostedWorldSession.js";
+import { type WorldDiff } from "./worldReplication.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/**
+ * The client end of host-authoritative replication: folds a host's baseline + {@link WorldDiff} stream onto a
+ * local {@link GameContext}. It keeps the last full {@link WorldSnapshot}, advances it with each diff, and pushes
+ * the result through `ctx.hydrate` — so the client mirrors exactly the subsystems its own game opted into and
+ * silently ignores host modules it lacks. This is the inverse of a {@link HostedWorldSession}; the transport in
+ * between (loopback, ws, Convex) is irrelevant.
+ */
+export interface WorldMirror {
+    applyBaseline(revision: number, snapshot: WorldSnapshot): void;
+    applyDiff(diff: WorldDiff): void;
+    revision(): number;
+}
+/** Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`. */
+export declare function createWorldMirror(ctx: Pick<GameContext, "hydrate">): WorldMirror;
+/**
+ * Pull one replication step from a co-located {@link HostedWorldSession} into a {@link WorldMirror} — the
+ * no-network local path (host and client in one process). A fresh mirror pulls a baseline; thereafter it pulls
+ * a diff since its own revision. The same `sync(sinceRevision)` call is what a networked transport marshals.
+ */
+export declare function pullWorld(session: HostedWorldSession, mirror: WorldMirror): void;

package/dist/runtime/worldMirror.js

@@ -0,0 +1,31 @@
+import { applyWorldDiff } from "./worldReplication.js";
+/** Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`. */
+export function createWorldMirror(ctx) {
+    let mirror = {};
+    let revision = 0;
+    return {
+        applyBaseline(nextRevision, snapshot) {
+            mirror = snapshot;
+            revision = nextRevision;
+            ctx.hydrate(snapshot);
+        },
+        applyDiff(diff) {
+            mirror = applyWorldDiff(mirror, diff);
+            revision = diff.revision;
+            ctx.hydrate(mirror);
+        },
+        revision: () => revision,
+    };
+}
+/**
+ * Pull one replication step from a co-located {@link HostedWorldSession} into a {@link WorldMirror} — the
+ * no-network local path (host and client in one process). A fresh mirror pulls a baseline; thereafter it pulls
+ * a diff since its own revision. The same `sync(sinceRevision)` call is what a networked transport marshals.
+ */
+export function pullWorld(session, mirror) {
+    const sync = session.sync(mirror.revision() === 0 ? null : mirror.revision());
+    if (sync.kind === "baseline")
+        mirror.applyBaseline(sync.revision, sync.snapshot);
+    else
+        mirror.applyDiff(sync.diff);
+}

package/dist/runtime/worldReplication.d.ts

@@ -0,0 +1,46 @@
+import type { SceneEntity } from "../scene/entityStore.js";
+import type { StatValueMap } from "../scene/entityStats.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/**
+ * A revision-stamped delta over a {@link WorldSnapshot}. The host sends one per tick to each client, carrying
+ * only what changed since that client's last acknowledged revision — entity/stat/store deltas plus whole
+ * snapshots of any other opted-in module (feed, leaderboard, chat, …) that changed. Fold it onto a prior
+ * baseline with {@link applyWorldDiff}.
+ */
+export interface WorldDiff {
+    revision: number;
+    entities: readonly SceneEntity[];
+    removedEntities: readonly string[];
+    stats: Record<string, StatValueMap>;
+    removedStats: readonly string[];
+    store: readonly (readonly [string, unknown])[];
+    removedStore: readonly string[];
+    /** Changed whole-module snapshots keyed by module name — everything a client can't reconstruct from deltas. */
+    modules: WorldSnapshot;
+}
+/**
+ * Turns successive full {@link WorldSnapshot}s into per-client {@link WorldDiff}s. Each `commit()` re-reads the
+ * world, stamps every item that changed with the new revision, and remembers removals; `diff(sinceRevision)`
+ * then replays exactly the items stamped after that revision. Everything the tracker holds is JSON — the same
+ * shape that rides the wire — so a diff is inherently serializable. Change-detection is a full re-serialize per
+ * commit; dirty-hint acceleration is a later optimization behind the same seam.
+ */
+export declare function createWorldReplicator(takeSnapshot: () => WorldSnapshot): {
+    commit: () => number;
+    diff: (sinceRevision: number) => WorldDiff;
+    revision: () => number;
+};
+/** The stateful diff tracker returned by {@link createWorldReplicator}: `commit()`, `diff(sinceRevision)`, `revision()`. */
+export type WorldReplicator = ReturnType<typeof createWorldReplicator>;
+/**
+ * Diff two full {@link WorldSnapshot}s directly, stamping the result at `revision` — the stateless counterpart of
+ * {@link createWorldReplicator} for hosts that persist snapshots rather than keep a live tracker (Convex reconstructs
+ * per invocation). `applyWorldDiff(prev, diffSnapshots(prev, next, r))` reproduces `next`.
+ */
+export declare function diffSnapshots(prev: WorldSnapshot, next: WorldSnapshot, revision: number): WorldDiff;
+/**
+ * Fold a {@link WorldDiff} onto a prior {@link WorldSnapshot} baseline, returning the next full snapshot — the
+ * client-side inverse of {@link createWorldReplicator}. Pure data in, pure data out: upserts changed entities,
+ * stats and store keys, drops the removed ones, and replaces changed module snapshots wholesale.
+ */
+export declare function applyWorldDiff(baseline: WorldSnapshot, diff: WorldDiff): WorldSnapshot;

package/dist/runtime/worldReplication.js

@@ -0,0 +1,185 @@
+const CORE_KEYS = new Set(["entities", "stats", "store"]);
+/**
+ * Turns successive full {@link WorldSnapshot}s into per-client {@link WorldDiff}s. Each `commit()` re-reads the
+ * world, stamps every item that changed with the new revision, and remembers removals; `diff(sinceRevision)`
+ * then replays exactly the items stamped after that revision. Everything the tracker holds is JSON — the same
+ * shape that rides the wire — so a diff is inherently serializable. Change-detection is a full re-serialize per
+ * commit; dirty-hint acceleration is a later optimization behind the same seam.
+ */
+export function createWorldReplicator(takeSnapshot) {
+    let revision = 0;
+    const entities = new Map();
+    const removedEntities = new Map();
+    const stats = new Map();
+    const removedStats = new Map();
+    const store = new Map();
+    const removedStore = new Map();
+    const modules = new Map();
+    function diffMap(live, tracked, removed, nextRevision) {
+        let changed = false;
+        for (const [key, json] of live) {
+            const prev = tracked.get(key);
+            if (prev === undefined || prev.json !== json) {
+                tracked.set(key, { json, revision: nextRevision });
+                removed.delete(key);
+                changed = true;
+            }
+        }
+        for (const key of tracked.keys()) {
+            if (!live.has(key)) {
+                tracked.delete(key);
+                removed.set(key, nextRevision);
+                changed = true;
+            }
+        }
+        return changed;
+    }
+    function commit() {
+        const snapshot = takeSnapshot();
+        const nextRevision = revision + 1;
+        const liveEntities = new Map();
+        for (const entity of (snapshot["entities"] ?? [])) {
+            liveEntities.set(entity.id, JSON.stringify(entity));
+        }
+        const liveStats = new Map();
+        for (const [id, value] of Object.entries((snapshot["stats"] ?? {}))) {
+            liveStats.set(id, JSON.stringify(value));
+        }
+        const liveStore = new Map();
+        for (const [key, value] of (snapshot["store"] ?? [])) {
+            liveStore.set(key, JSON.stringify(value ?? null));
+        }
+        const liveModules = new Map();
+        for (const [key, value] of Object.entries(snapshot)) {
+            if (CORE_KEYS.has(key))
+                continue;
+            liveModules.set(key, JSON.stringify(value ?? null));
+        }
+        let changed = diffMap(liveEntities, entities, removedEntities, nextRevision);
+        changed = diffMap(liveStats, stats, removedStats, nextRevision) || changed;
+        changed = diffMap(liveStore, store, removedStore, nextRevision) || changed;
+        changed = diffMap(liveModules, modules, new Map(), nextRevision) || changed;
+        if (changed)
+            revision = nextRevision;
+        return revision;
+    }
+    function diff(sinceRevision) {
+        const changedEntities = [];
+        for (const [, tracked] of entities) {
+            if (tracked.revision > sinceRevision)
+                changedEntities.push(JSON.parse(tracked.json));
+        }
+        const changedStats = {};
+        for (const [id, tracked] of stats) {
+            if (tracked.revision > sinceRevision)
+                changedStats[id] = JSON.parse(tracked.json);
+        }
+        const changedStore = [];
+        for (const [key, tracked] of store) {
+            if (tracked.revision > sinceRevision)
+                changedStore.push([key, JSON.parse(tracked.json)]);
+        }
+        const changedModules = {};
+        for (const [key, tracked] of modules) {
+            if (tracked.revision > sinceRevision)
+                changedModules[key] = JSON.parse(tracked.json);
+        }
+        return {
+            revision,
+            entities: changedEntities,
+            removedEntities: keysAfter(removedEntities, sinceRevision),
+            stats: changedStats,
+            removedStats: keysAfter(removedStats, sinceRevision),
+            store: changedStore,
+            removedStore: keysAfter(removedStore, sinceRevision),
+            modules: changedModules,
+        };
+    }
+    return { commit, diff, revision: () => revision };
+}
+function keysAfter(map, sinceRevision) {
+    const out = [];
+    for (const [key, revision] of map) {
+        if (revision > sinceRevision)
+            out.push(key);
+    }
+    return out;
+}
+/**
+ * Diff two full {@link WorldSnapshot}s directly, stamping the result at `revision` — the stateless counterpart of
+ * {@link createWorldReplicator} for hosts that persist snapshots rather than keep a live tracker (Convex reconstructs
+ * per invocation). `applyWorldDiff(prev, diffSnapshots(prev, next, r))` reproduces `next`.
+ */
+export function diffSnapshots(prev, next, revision) {
+    const prevEntities = new Map();
+    for (const entity of (prev["entities"] ?? [])) {
+        prevEntities.set(entity.id, JSON.stringify(entity));
+    }
+    const entities = [];
+    const nextEntityIds = new Set();
+    for (const entity of (next["entities"] ?? [])) {
+        nextEntityIds.add(entity.id);
+        const json = JSON.stringify(entity);
+        if (prevEntities.get(entity.id) !== json)
+            entities.push(JSON.parse(json));
+    }
+    const removedEntities = [...prevEntities.keys()].filter((id) => !nextEntityIds.has(id));
+    const prevStats = (prev["stats"] ?? {});
+    const nextStats = (next["stats"] ?? {});
+    const stats = {};
+    for (const [id, value] of Object.entries(nextStats)) {
+        const json = JSON.stringify(value);
+        if (JSON.stringify(prevStats[id]) !== json)
+            stats[id] = JSON.parse(json);
+    }
+    const removedStats = Object.keys(prevStats).filter((id) => !(id in nextStats));
+    const prevStore = new Map((prev["store"] ?? []));
+    const nextStore = new Map((next["store"] ?? []));
+    const store = [];
+    for (const [key, value] of nextStore) {
+        const json = JSON.stringify(value ?? null);
+        if (JSON.stringify(prevStore.get(key) ?? null) !== json)
+            store.push([key, JSON.parse(json)]);
+    }
+    const removedStore = [...prevStore.keys()].filter((key) => !nextStore.has(key));
+    const modules = {};
+    for (const [key, value] of Object.entries(next)) {
+        if (CORE_KEYS.has(key))
+            continue;
+        const json = JSON.stringify(value ?? null);
+        if (JSON.stringify(prev[key] ?? null) !== json)
+            modules[key] = JSON.parse(json);
+    }
+    return { revision, entities, removedEntities, stats, removedStats, store, removedStore, modules };
+}
+/**
+ * Fold a {@link WorldDiff} onto a prior {@link WorldSnapshot} baseline, returning the next full snapshot — the
+ * client-side inverse of {@link createWorldReplicator}. Pure data in, pure data out: upserts changed entities,
+ * stats and store keys, drops the removed ones, and replaces changed module snapshots wholesale.
+ */
+export function applyWorldDiff(baseline, diff) {
+    const next = { ...baseline };
+    const entityById = new Map();
+    for (const entity of (baseline["entities"] ?? []))
+        entityById.set(entity.id, entity);
+    for (const entity of diff.entities)
+        entityById.set(entity.id, entity);
+    for (const id of diff.removedEntities)
+        entityById.delete(id);
+    next["entities"] = Array.from(entityById.values());
+    const statsById = { ...(baseline["stats"] ?? {}) };
+    for (const [id, value] of Object.entries(diff.stats))
+        statsById[id] = value;
+    for (const id of diff.removedStats)
+        delete statsById[id];
+    next["stats"] = statsById;
+    const storeByKey = new Map((baseline["store"] ?? []));
+    for (const [key, value] of diff.store)
+        storeByKey.set(key, value);
+    for (const key of diff.removedStore)
+        storeByKey.delete(key);
+    next["store"] = Array.from(storeByKey.entries());
+    for (const [key, value] of Object.entries(diff.modules))
+        next[key] = value;
+    return next;
+}

package/dist/runtime/worldSnapshot.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The replication seam for host-authoritative shared worlds: the opt-in feature manifest *is* the
+ * replication schema. Each live subsystem a game opts into registers a {@link SnapshotModule} keyed
+ * by name; the host serializes exactly the registered set into a {@link WorldSnapshot} and a client
+ * hydrates the same keys back. Adding a replicated subsystem is a registration, never a new branch.
+ */
+export interface SnapshotModule<T = unknown> {
+    readonly key: string;
+    snapshot(): T;
+    hydrate(data: T): void;
+}
+/** Full world baseline keyed by {@link SnapshotModule.key} — one entry per opted-in subsystem. */
+export type WorldSnapshot = Record<string, unknown>;
+/** Serialize every registered module into one keyed baseline — the host→client full-world send. */
+export declare function composeWorldSnapshot(modules: readonly SnapshotModule[]): WorldSnapshot;
+/** Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched. */
+export declare function applyWorldSnapshot(modules: readonly SnapshotModule[], snapshot: WorldSnapshot): void;

package/dist/runtime/worldSnapshot.js

@@ -0,0 +1,15 @@
+/** Serialize every registered module into one keyed baseline — the host→client full-world send. */
+export function composeWorldSnapshot(modules) {
+    const snapshot = {};
+    for (const module of modules)
+        snapshot[module.key] = module.snapshot();
+    return snapshot;
+}
+/** Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched. */
+export function applyWorldSnapshot(modules, snapshot) {
+    for (const module of modules) {
+        if (Object.prototype.hasOwnProperty.call(snapshot, module.key)) {
+            module.hydrate(snapshot[module.key]);
+        }
+    }
+}

package/dist/scene/assetCatalog.d.ts

@@ -1,3 +1,4 @@
+/** Measured horizontal footprint, footprint center, and lowest Y of a model in model space. */
 export interface ModelDims {
     footprint: {
         w: number;

package/dist/scene/colliders.d.ts

@@ -33,8 +33,14 @@ export interface ResolvedCollider {
 }
 export declare const DEFAULT_ENTITY_HIT_RADIUS = 0.5;
 export declare const DEFAULT_OBJECT_HALF_EXTENTS: EntityPosition;
+/** Matches the shell's fallback actor capsule (~0.7m wide, feet at y=0 to head at ~1.8m). */
+export declare const DEFAULT_ENTITY_BODY_HALF_EXTENTS: EntityPosition;
+/** Entity-local center of the default body hitbox (half its height above the feet). */
+export declare const DEFAULT_ENTITY_BODY_OFFSET: EntityPosition;
 export declare function defaultEntityColliders(): EntityColliderSet;
 export declare function defaultObjectColliders(halfExtents?: EntityPosition): EntityColliderSet;
+/** Blocking physical body derived from an object's rendered scale: a grounded box spanning the visual (base at y=0, matching the shell's fallback mesh). */
+export declare function scaledObjectColliders(scale: readonly [number, number, number]): EntityColliderSet;
 export declare function resolveColliders(set: EntityColliderSet | null | undefined): ResolvedCollider[];
 export declare function worldOffset(local: EntityPosition | undefined, position: EntityPosition, rotationY: number): EntityPosition;
 export declare function colliderWorldCenter(collider: ResolvedCollider, position: EntityPosition, rotationY: number): EntityPosition;