@jgengine/core 0.9.0 → 0.11.0

package/dist/runtime/motionIntents.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createMotionIntents() {
     let impulses = [];
     let horizontalImpulses = [];
@@ -27,9 +28,33 @@ export function createMotionIntents() {
             y = null;
             return batch;
         },
+        snapshot() {
+            return { impulses: [...impulses], horizontalImpulses: [...horizontalImpulses], verticalVelocity, y };
+        },
+        hydrate(batch) {
+            impulses = [...batch.impulses];
+            horizontalImpulses = batch.horizontalImpulses.map(([x, z]) => [x, z]);
+            verticalVelocity = batch.verticalVelocity;
+            y = batch.y;
+        },
     };
 }
-/** Fold a batch's horizontal pushes into a controller's velocity pair — shared by the walk and voxel drivers. */
+/** Fold a batch's vertical impulses into a controller's velocity, then apply an outright `setVerticalVelocity` override — the vertical counterpart of {@link applyHorizontalImpulses}.
+ * @internal
+ */
+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.
+ * @internal
+ */
 export function applyHorizontalImpulses(velocityX, velocityZ, batch) {
     if (batch === null || batch.horizontalImpulses.length === 0)
         return [velocityX, velocityZ];

package/dist/runtime/perContext.d.ts

@@ -0,0 +1,15 @@
+import type { GameContext } from "./gameContext.js";
+/**
+ * Per-`GameContext` lazy state, keyed by context identity through a `WeakMap` so it is reclaimed when
+ * the context is — the seam a game uses instead of a module-global `Map`, which is process-global and
+ * bleeds across worlds when one host serves several `serverId`s (#632). `init` runs once per distinct
+ * context on first access; the same context always resolves to the same value. This mirrors the engine's
+ * built-in per-ctx pattern (`ctx.player.motion`, `stepPlayerMovement`).
+ *
+ * ```ts
+ * const heroRuntimes = perContext(() => new Map<string, HeroRuntime>());
+ * // per world:
+ * heroRuntimes(ctx).set(userId, runtime);
+ * ```
+ */
+export declare function perContext<T>(init: (ctx: GameContext) => T): (ctx: GameContext) => T;

package/dist/runtime/perContext.js

@@ -0,0 +1,21 @@
+/**
+ * Per-`GameContext` lazy state, keyed by context identity through a `WeakMap` so it is reclaimed when
+ * the context is — the seam a game uses instead of a module-global `Map`, which is process-global and
+ * bleeds across worlds when one host serves several `serverId`s (#632). `init` runs once per distinct
+ * context on first access; the same context always resolves to the same value. This mirrors the engine's
+ * built-in per-ctx pattern (`ctx.player.motion`, `stepPlayerMovement`).
+ *
+ * ```ts
+ * const heroRuntimes = perContext(() => new Map<string, HeroRuntime>());
+ * // per world:
+ * heroRuntimes(ctx).set(userId, runtime);
+ * ```
+ */
+export function perContext(init) {
+    const byContext = new WeakMap();
+    return (ctx) => {
+        if (!byContext.has(ctx))
+            byContext.set(ctx, init(ctx));
+        return byContext.get(ctx);
+    };
+}

package/dist/runtime/runtimeSave.d.ts

@@ -0,0 +1,79 @@
+import { type SaveBackend, type SaveStatus, type SaveTimers } from "../game/saveStore.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/**
+ * The narrow slice of a live `GameContext` a runtime save reads and writes — a
+ * `GameContext` satisfies it directly (`ctx.snapshot`/`ctx.hydrate`/`ctx.subscribe`).
+ * Depending on this instead of the full context keeps the save controller a deep,
+ * decoupled module: it captures and restores the *whole* opted-in world without
+ * knowing any subsystem.
+ */
+export interface RuntimeSaveTarget {
+    snapshot(): WorldSnapshot;
+    hydrate(snapshot: WorldSnapshot): void;
+    subscribe(listener: () => void): () => void;
+}
+/** `"autosave"` writes a fresh capture on a debounce after any world change; `"manual"` writes only on an explicit `save()`/`checkpoint()` — the save-point / quest-trigger model. */
+export type RuntimeSaveMode = "autosave" | "manual";
+/** How {@link createRuntimeSave} is wired — the live world `target`, the `backend` it persists through, and optional mode/slot/versioning/cadence knobs. */
+export interface RuntimeSaveConfig {
+    /** The live world to capture from and restore into — pass the `GameContext`. */
+    target: RuntimeSaveTarget;
+    /** Where the save lives — `localSaveBackend()` (offline) or a cloud/Convex backend; the only thing that changes between offline and cloud. */
+    backend: SaveBackend;
+    /** `"autosave"` (default) persists on world change; `"manual"` only when the game calls `save()`/`checkpoint()`. */
+    mode?: RuntimeSaveMode;
+    /** Storage namespace. Default `"runtime"`. */
+    key?: string;
+    /** Active save slot. Default `"default"`. */
+    slot?: string;
+    /** Save-format version; bump + pass {@link migrate} on a breaking world-shape change. */
+    version?: number;
+    migrate?: (data: unknown, fromVersion: number) => WorldSnapshot;
+    /** Debounce for `autosave` mode. Default `3000`. */
+    autosaveMs?: number;
+    now?: () => number;
+    timers?: SaveTimers;
+    onError?: (error: unknown) => void;
+}
+/** {@link RuntimeSaveConfig} without `target` — what a host (`createGameContext`) accepts to build `ctx.game.save` and bind it to the context itself. */
+export type RuntimeSaveOptions = Omit<RuntimeSaveConfig, "target">;
+/**
+ * Whole-world save/load bound to a live world and a pluggable backend. `save()`
+ * captures `target.snapshot()` and writes it; `load()` reads it back and
+ * `target.hydrate()`s the whole world. In `autosave` mode it also writes on a
+ * debounce after any change. Named slots, versioned migration, and offline↔cloud
+ * (backend swap) all come for free from the underlying save store.
+ */
+export interface RuntimeSave {
+    status(): SaveStatus;
+    slot(): string;
+    /** Capture the live world and persist it now (serialized against any in-flight write). */
+    save(): Promise<void>;
+    /** Semantic alias for `save()` — call it from a save point, a quest-complete or area-enter handler. */
+    checkpoint(): Promise<void>;
+    /** Load the active slot and hydrate the whole world; resolves `true` when a real save was applied, `false` for an empty slot. */
+    load(): Promise<boolean>;
+    /** Whether the active slot holds a saved world — gate a title-screen "Continue" on it. */
+    hasSave(): Promise<boolean>;
+    /** Delete the active slot's save. */
+    clear(): Promise<void>;
+    /** Switch slot and load it, hydrating the world when that slot has a save. */
+    switchSlot(slot: string): Promise<boolean>;
+    /** The slots this game has written — back a load/save menu. */
+    slots(): Promise<string[]>;
+    subscribe(listener: () => void): () => void;
+    /** Stop autosave and release the world subscription. */
+    dispose(): void;
+}
+/**
+ * Bridge a live world to a pluggable save backend: whole-state capture/restore
+ * with autosave, save points, named slots, and versioned migration — the same
+ * call for offline (localStorage) and cloud (Convex), only the `backend`
+ * differs. The game keeps control of *when* it saves (the `mode` plus explicit
+ * `checkpoint()` calls from quests/areas) and *when* it restores (`load()` on
+ * boot), so any save mechanic — continuous autosave, manual save points,
+ * checkpoint triggers — is expressible without new engine code.
+ *
+ * @capability runtime-save save/load the whole game world through a pluggable backend, autosave or save points
+ */
+export declare function createRuntimeSave(config: RuntimeSaveConfig): RuntimeSave;

package/dist/runtime/runtimeSave.js

@@ -0,0 +1,105 @@
+import { createSaveStore, } from "../game/saveStore.js";
+function defaultTimers() {
+    return {
+        set: (handler, ms) => globalThis.setTimeout(handler, ms),
+        clear: (handle) => globalThis.clearTimeout(handle),
+    };
+}
+function hasContent(snapshot) {
+    for (const _key in snapshot)
+        return true;
+    return false;
+}
+/**
+ * Bridge a live world to a pluggable save backend: whole-state capture/restore
+ * with autosave, save points, named slots, and versioned migration — the same
+ * call for offline (localStorage) and cloud (Convex), only the `backend`
+ * differs. The game keeps control of *when* it saves (the `mode` plus explicit
+ * `checkpoint()` calls from quests/areas) and *when* it restores (`load()` on
+ * boot), so any save mechanic — continuous autosave, manual save points,
+ * checkpoint triggers — is expressible without new engine code.
+ *
+ * @capability runtime-save save/load the whole game world through a pluggable backend, autosave or save points
+ */
+export function createRuntimeSave(config) {
+    const mode = config.mode ?? "autosave";
+    const autosaveMs = config.autosaveMs ?? 3000;
+    const timers = config.timers ?? defaultTimers();
+    const store = createSaveStore({
+        backend: config.backend,
+        initial: {},
+        key: config.key ?? "runtime",
+        slot: config.slot,
+        version: config.version,
+        migrate: config.migrate,
+        autosave: false,
+        now: config.now,
+        onError: config.onError,
+    });
+    let pendingTimer = null;
+    let unsubscribe = null;
+    let disposed = false;
+    let restoring = false;
+    function clearTimer() {
+        if (pendingTimer !== null) {
+            timers.clear(pendingTimer);
+            pendingTimer = null;
+        }
+    }
+    function persist() {
+        clearTimer();
+        store.set(config.target.snapshot());
+        return store.save();
+    }
+    function scheduleAutosave() {
+        if (disposed || restoring)
+            return;
+        clearTimer();
+        pendingTimer = timers.set(() => {
+            pendingTimer = null;
+            void persist();
+        }, autosaveMs);
+    }
+    if (mode === "autosave") {
+        unsubscribe = config.target.subscribe(scheduleAutosave);
+    }
+    function applyLoaded(snapshot) {
+        if (!hasContent(snapshot))
+            return false;
+        restoring = true;
+        try {
+            config.target.hydrate(snapshot);
+        }
+        finally {
+            restoring = false;
+        }
+        return true;
+    }
+    const save = () => persist();
+    return {
+        status: () => store.status(),
+        slot: () => store.slot(),
+        save,
+        checkpoint: save,
+        async load() {
+            return applyLoaded(await store.load());
+        },
+        async hasSave() {
+            return hasContent(await store.load());
+        },
+        clear: () => store.clear(),
+        async switchSlot(slot) {
+            clearTimer();
+            return applyLoaded(await store.switchSlot(slot));
+        },
+        slots: () => store.slots(),
+        subscribe: (listener) => store.subscribe(listener),
+        dispose() {
+            disposed = true;
+            clearTimer();
+            if (unsubscribe !== null)
+                unsubscribe();
+            store.dispose();
+        },
+    };
+}

package/dist/runtime/save.d.ts

@@ -3,7 +3,11 @@ export type SaveConfig = "none" | {
     auto: string;
     scope: SaveScope;
 };
+/** @internal */
 export declare function parseSaveAutoMs(auto: string): number;
+/** @internal */
 export declare function saveScopeIncludesPlayer(scope: SaveScope): boolean;
+/** @internal */
 export declare function saveScopeIncludesChunks(scope: SaveScope): boolean;
+/** @internal */
 export declare function isSaveEnabled(config: SaveConfig): config is Exclude<SaveConfig, "none">;

package/dist/runtime/save.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function parseSaveAutoMs(auto) {
     const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(auto.trim());
     if (!match) {
@@ -18,12 +19,15 @@ export function parseSaveAutoMs(auto) {
             throw new Error(`Invalid save.auto unit: ${unit}`);
     }
 }
+/** @internal */
 export function saveScopeIncludesPlayer(scope) {
     return scope === "player" || scope === "player+chunks";
 }
+/** @internal */
 export function saveScopeIncludesChunks(scope) {
     return scope === "chunks" || scope === "player+chunks";
 }
+/** @internal */
 export function isSaveEnabled(config) {
     return config !== "none";
 }

package/dist/runtime/snapshot.d.ts

@@ -69,8 +69,11 @@ export type GameRuntimeSnapshot = {
         chunks: string[];
     };
 };
+/** @internal */
 export declare function createEmptyServerRow(): RuntimeServerRow;
+/** @internal */
 export declare function createEmptyPlayerRow(userId: string): RuntimePlayerRow;
+/** @internal */
 export declare function createRuntimeSnapshot(args: {
     gameId: string;
     serverId: string;
@@ -79,9 +82,13 @@ export declare function createRuntimeSnapshot(args: {
     chunks?: Record<string, RuntimeChunkRow>;
     revision?: number;
 }): GameRuntimeSnapshot;
+/** @internal */
 export declare function markServerDirty(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot;
+/** @internal */
 export declare function markPlayerDirty(snapshot: GameRuntimeSnapshot, userId: string): GameRuntimeSnapshot;
+/** @internal */
 export declare function clearDirtyFlags(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot;
+/** @internal */
 export declare function splitProfilePlayer(player: RuntimePlayerRow): {
     persistent: RuntimePlayerRow;
     session: Record<string, unknown>;

package/dist/runtime/snapshot.js

@@ -1,4 +1,5 @@
 export const RUNTIME_SNAPSHOT_VERSION = 1;
+/** @internal */
 export function createEmptyServerRow() {
     return {
         entities: [],
@@ -7,6 +8,7 @@ export function createEmptyServerRow() {
         feeds: {},
     };
 }
+/** @internal */
 export function createEmptyPlayerRow(userId) {
     return {
         userId,
@@ -16,6 +18,7 @@ export function createEmptyPlayerRow(userId) {
         session: {},
     };
 }
+/** @internal */
 export function createRuntimeSnapshot(args) {
     return {
         version: RUNTIME_SNAPSHOT_VERSION,
@@ -32,6 +35,7 @@ export function createRuntimeSnapshot(args) {
         },
     };
 }
+/** @internal */
 export function markServerDirty(snapshot) {
     return {
         ...snapshot,
@@ -39,6 +43,7 @@ export function markServerDirty(snapshot) {
         dirty: { ...snapshot.dirty, server: true },
     };
 }
+/** @internal */
 export function markPlayerDirty(snapshot, userId) {
     if (snapshot.dirty.players.includes(userId)) {
         return markServerDirty(snapshot);
@@ -53,6 +58,7 @@ export function markPlayerDirty(snapshot, userId) {
         },
     };
 }
+/** @internal */
 export function clearDirtyFlags(snapshot) {
     return {
         ...snapshot,
@@ -63,6 +69,7 @@ export function clearDirtyFlags(snapshot) {
         },
     };
 }
+/** @internal */
 export function splitProfilePlayer(player) {
     const { session = {}, ...persistentFields } = player;
     return {

package/dist/runtime/visibility.d.ts

@@ -62,7 +62,8 @@ export interface VisibilityDecision {
  *
  * Render culling and asset streaming are intentionally separate. This class never
  * destroys entities or throttles simulation; adapters decide how to apply results.
- */
+  * @internal
+  */
 export declare class VisibilitySystem {
     #private;
     readonly settings: VisibilityDefaults;

package/dist/runtime/visibility.js

@@ -23,7 +23,8 @@ function intersectsRadius(camera, bounds, extraMargin) {
  *
  * Render culling and asset streaming are intentionally separate. This class never
  * destroys entities or throttles simulation; adapters decide how to apply results.
- */
+  * @internal
+  */
 export class VisibilitySystem {
     settings;
     #states = new Map();

package/dist/runtime/worldChannel.d.ts

@@ -0,0 +1,62 @@
+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.
+ * @internal
+ */
+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.
+ * @internal
+ */
+export declare function createWorldClientLink(ctx: Pick<GameContext, "hydrate">, send: (frame: WorldClientFrame) => void): WorldClientLink;

package/dist/runtime/worldChannel.js

@@ -0,0 +1,114 @@
+import { createWorldMirror } from "./worldMirror.js";
+import { diffSnapshots } from "./worldReplication.js";
+/** Build a {@link WorldHost} fanning one {@link HostedWorldSession} out to many cursor-tracked connections.
+ * @internal
+ */
+export function createWorldHost(session) {
+    const connections = new Set();
+    const connectionsByUser = new Map();
+    const perViewer = session.projectsViewers();
+    function connect(userId, send) {
+        let cursor = 0;
+        let released = false;
+        let viewerSnapshot = null;
+        let viewerRevision = 0;
+        function release() {
+            if (released)
+                return;
+            released = true;
+            connections.delete(connection);
+            const peers = connectionsByUser.get(userId);
+            if (peers === undefined)
+                return;
+            peers.delete(connection);
+            if (peers.size === 0) {
+                connectionsByUser.delete(userId);
+                session.leave(userId);
+            }
+        }
+        const connection = {
+            receive(frame) {
+                switch (frame.t) {
+                    case "join":
+                        session.join(userId, frame.isNew);
+                        break;
+                    case "leave":
+                        release();
+                        break;
+                    case "command":
+                        session.command(userId, frame.name, frame.input);
+                        break;
+                    case "input":
+                        session.input(userId, frame.frame);
+                        break;
+                }
+            },
+            push() {
+                if (released)
+                    return;
+                if (perViewer) {
+                    const revision = session.revision();
+                    if (viewerSnapshot !== null && revision === viewerRevision)
+                        return;
+                    const snapshot = session.snapshotFor({ userId });
+                    if (viewerSnapshot === null) {
+                        send({ t: "baseline", revision, snapshot });
+                    }
+                    else {
+                        send({ t: "diff", diff: diffSnapshots(viewerSnapshot, snapshot, revision, viewerRevision) });
+                    }
+                    viewerSnapshot = snapshot;
+                    viewerRevision = revision;
+                    return;
+                }
+                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: release,
+        };
+        connections.add(connection);
+        let peers = connectionsByUser.get(userId);
+        if (peers === undefined) {
+            peers = new Set();
+            connectionsByUser.set(userId, peers);
+        }
+        peers.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.
+ * @internal
+ */
+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,36 @@
+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;
+    /**
+     * Fold one {@link WorldDiff} onto the mirror. A diff whose `revision` doesn't advance past the mirror's own
+     * (stale or a duplicate resend) is ignored. A diff carrying `baseRevision` that doesn't match the mirror's
+     * current revision means frames were skipped in transit — the diff is ignored and {@link needsResync} flips
+     * true until the next {@link applyBaseline} instead of folding a gap onto local state. A diff without
+     * `baseRevision` (legacy producer) always applies, matching the pre-revision-checking behavior.
+     */
+    applyDiff(diff: WorldDiff): void;
+    revision(): number;
+    /** True after `applyDiff` detected a skipped revision; the caller should fetch a fresh baseline instead of more diffs. */
+    needsResync(): boolean;
+}
+/** Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`.
+ * @internal
+ */
+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.
+  * @internal
+  */
+export declare function pullWorld(session: HostedWorldSession, mirror: WorldMirror): void;

package/dist/runtime/worldMirror.js

@@ -0,0 +1,44 @@
+import { applyWorldDiff } from "./worldReplication.js";
+/** Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`.
+ * @internal
+ */
+export function createWorldMirror(ctx) {
+    let mirror = {};
+    let revision = 0;
+    let resyncNeeded = false;
+    return {
+        applyBaseline(nextRevision, snapshot) {
+            mirror = snapshot;
+            revision = nextRevision;
+            resyncNeeded = false;
+            ctx.hydrate(snapshot);
+        },
+        applyDiff(diff) {
+            if (diff.revision <= revision)
+                return;
+            if (diff.baseRevision !== undefined && diff.baseRevision !== revision) {
+                resyncNeeded = true;
+                return;
+            }
+            resyncNeeded = false;
+            mirror = applyWorldDiff(mirror, diff);
+            revision = diff.revision;
+            ctx.hydrate(mirror);
+        },
+        revision: () => revision,
+        needsResync: () => resyncNeeded,
+    };
+}
+/**
+ * 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.
+  * @internal
+  */
+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);
+}