@jgengine/core 0.10.0 → 0.12.0

package/dist/runtime/hostPersistence.js

@@ -11,6 +11,7 @@ function isLeaderboardIncrement(value) {
         typeof candidate.by === "number" &&
         (candidate.serverId === undefined || typeof candidate.serverId === "string"));
 }
+/** @internal */
 export function drainPendingLeaderboardIncrements(session) {
     const raw = session[LEADERBOARD_PENDING_KEY];
     if (!Array.isArray(raw) || raw.length === 0) {
@@ -21,15 +22,18 @@ export function drainPendingLeaderboardIncrements(session) {
     return { increments: raw.filter(isLeaderboardIncrement), session: rest };
 }
 export const LEADERBOARD_TOP_LIMIT = 100;
+/** @internal */
 export function clampLimit(value, fallback, max) {
     const candidate = value ?? fallback;
     if (!Number.isFinite(candidate))
         return fallback;
     return Math.min(Math.max(Math.floor(candidate), 1), max);
 }
+/** @internal */
 export function leaderboardRowKey(row) {
     return [row.gameId, row.scope, row.stat, row.serverId ?? "", row.userId].join("|");
 }
+/** @internal */
 export function applyLeaderboardRows(rows, gameId, entries, now) {
     for (const entry of entries) {
         const key = leaderboardRowKey({ ...entry, gameId });
@@ -50,6 +54,7 @@ export function applyLeaderboardRows(rows, gameId, entries, now) {
         }
     }
 }
+/** @internal */
 export function topLeaderboardRows(rows, args) {
     const limit = clampLimit(args.limit, LEADERBOARD_TOP_LIMIT, LEADERBOARD_TOP_LIMIT);
     return [...rows]
@@ -61,6 +66,7 @@ export function topLeaderboardRows(rows, args) {
         .slice(0, limit)
         .map((row) => ({ userId: row.userId, value: row.value }));
 }
+/** @internal */
 export function profileLeaderboardStats(rows, gameId, userId) {
     const profile = {};
     for (const row of rows) {
@@ -71,11 +77,13 @@ export function profileLeaderboardStats(rows, gameId, userId) {
     return profile;
 }
 export const FEED_RING_LIMIT = 20;
+/** @internal */
 export function trimFeedEntries(entries, limit = FEED_RING_LIMIT) {
     if (entries.length <= limit)
         return entries;
     return entries.slice(entries.length - limit);
 }
+/** @internal */
 export function shouldAutoSave(save, dirtyAt, lastSavedAt, now) {
     if (!isSaveEnabled(save))
         return false;
@@ -85,6 +93,7 @@ export function shouldAutoSave(save, dirtyAt, lastSavedAt, now) {
     const anchor = lastSavedAt ?? 0;
     return now - anchor >= intervalMs;
 }
+/** @internal */
 export function toServerListing(record, options = {}) {
     return {
         serverId: record.serverId,
@@ -103,12 +112,14 @@ export function toServerListing(record, options = {}) {
 }
 export const OPEN_SERVER_LISTING_LIMIT = 20;
 export const OPEN_SERVER_LISTING_MAX = 100;
+/** @internal */
 export function toOpenServerListings(listings, limit = OPEN_SERVER_LISTING_LIMIT) {
     return [...listings]
         .filter((listing) => listing.status === "running")
         .sort((a, b) => b.updatedAt - a.updatedAt)
         .slice(0, clampLimit(limit, OPEN_SERVER_LISTING_LIMIT, OPEN_SERVER_LISTING_MAX));
 }
+/** @internal */
 export function buildHydratePlayers(server, profiles) {
     const players = {};
     for (const userId of server.memberUserIds) {
@@ -129,6 +140,7 @@ export function buildHydratePlayers(server, profiles) {
     }
     return players;
 }
+/** @internal */
 export function planServerPersist(server, snapshot, save, now) {
     const drained = drainPendingLeaderboardIncrements(snapshot.server.session);
     const serverState = drained.increments.length > 0 ? { ...snapshot.server, session: drained.session } : snapshot.server;

package/dist/runtime/hostPolicy.d.ts

@@ -0,0 +1,51 @@
+import type { GameServerStatus, SessionVisibility } from "./hostPersistence.js";
+/**
+ * True when a server's `visibility` should surface in public listings / browse results.
+ * @capability host-listing-filter exclude private sessions from public browse results
+ */
+export declare function isListablePublicly(visibility: SessionVisibility | undefined): boolean;
+/**
+ * Private-server join-code gate. Existing members always pass; non-members must present a
+ * matching `joinCode` (loose-normalized via {@link normalizeJoinCode}). Callers still decide
+ * whether the server is private — this only answers the code/membership half.
+ * @capability host-join-code-gate membership-or-code gate for private hosted servers
+ */
+export declare function canJoinPrivateServer(args: {
+    isMember: boolean;
+    joinCode: string | undefined;
+    suppliedCode: string | undefined;
+}): boolean;
+/** Whether `userId` is already on the server's member roster. */
+export declare function isServerMember(memberUserIds: readonly string[], userId: string): boolean;
+/**
+ * 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(memberUserIds: readonly string[], slotsPerServer: number, userId: string): boolean;
+/**
+ * Whether a private-visibility server blocks this join (non-member without a matching code).
+ * Public / undefined visibility never blocks.
+ */
+export declare function isPrivateJoinBlocked(args: {
+    visibility: SessionVisibility | undefined;
+    memberUserIds: readonly string[];
+    userId: string;
+    joinCode: string | undefined;
+    suppliedCode: string | undefined;
+}): boolean;
+/** Roster after a successful join: unchanged when already a member, else appended. */
+export declare function withJoinedMember(memberUserIds: readonly string[], userId: string): string[];
+/** Roster after a leave: `userId` removed; order of remaining members preserved. */
+export declare function withoutMember(memberUserIds: readonly string[], userId: string): string[];
+/** Status after a leave: empty rooms reopen; non-empty rooms keep their current status. */
+export declare function statusAfterLeave(remainingMemberCount: number, currentStatus: GameServerStatus): GameServerStatus;
+/**
+ * Auto-match candidate when no `serverId` is supplied: already a member, or a public room with
+ * free capacity. Private rooms are never auto-picked (join-by-code / direct id only).
+ */
+export declare function isAutoJoinCandidate(args: {
+    memberUserIds: readonly string[];
+    slotsPerServer: number;
+    visibility: SessionVisibility | undefined;
+    userId: string;
+}): boolean;

package/dist/runtime/hostPolicy.js

@@ -0,0 +1,68 @@
+import { normalizeJoinCode } from "../multiplayer/matchmaking.js";
+/**
+ * True when a server's `visibility` should surface in public listings / browse results.
+ * @capability host-listing-filter exclude private sessions from public browse results
+ */
+export function isListablePublicly(visibility) {
+    return (visibility ?? "public") !== "private";
+}
+/**
+ * Private-server join-code gate. Existing members always pass; non-members must present a
+ * matching `joinCode` (loose-normalized via {@link normalizeJoinCode}). Callers still decide
+ * whether the server is private — this only answers the code/membership half.
+ * @capability host-join-code-gate membership-or-code gate for private hosted servers
+ */
+export function canJoinPrivateServer(args) {
+    if (args.isMember)
+        return true;
+    if (args.joinCode === undefined || args.suppliedCode === undefined)
+        return false;
+    return normalizeJoinCode(args.suppliedCode) === normalizeJoinCode(args.joinCode);
+}
+/** Whether `userId` is already on the server's member roster. */
+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);
+}
+/**
+ * Whether a private-visibility server blocks this join (non-member without a matching code).
+ * Public / undefined visibility never blocks.
+ */
+export function isPrivateJoinBlocked(args) {
+    if ((args.visibility ?? "public") !== "private")
+        return false;
+    return !canJoinPrivateServer({
+        isMember: isServerMember(args.memberUserIds, args.userId),
+        joinCode: args.joinCode,
+        suppliedCode: args.suppliedCode,
+    });
+}
+/** Roster after a successful join: unchanged when already a member, else appended. */
+export function withJoinedMember(memberUserIds, userId) {
+    return memberUserIds.includes(userId) ? [...memberUserIds] : [...memberUserIds, userId];
+}
+/** Roster after a leave: `userId` removed; order of remaining members preserved. */
+export function withoutMember(memberUserIds, userId) {
+    return memberUserIds.filter((id) => id !== userId);
+}
+/** Status after a leave: empty rooms reopen; non-empty rooms keep their current status. */
+export function statusAfterLeave(remainingMemberCount, currentStatus) {
+    return remainingMemberCount === 0 ? "open" : currentStatus;
+}
+/**
+ * Auto-match candidate when no `serverId` is supplied: already a member, or a public room with
+ * free capacity. Private rooms are never auto-picked (join-by-code / direct id only).
+ */
+export function isAutoJoinCandidate(args) {
+    if (isServerMember(args.memberUserIds, args.userId))
+        return true;
+    if (args.memberUserIds.length >= args.slotsPerServer)
+        return false;
+    return isListablePublicly(args.visibility);
+}

package/dist/runtime/hostedGameRunner.d.ts

@@ -1,10 +1,10 @@
 import type { CommandResult } from "../commands/commandRegistry.js";
 import type { GameDefinition, LoopPlayer } from "../game/defineGame.js";
 import type { ModelAssetRef } from "../scene/assetCatalog.js";
-import { type GameContext, type GameContextContent } from "./gameContext.js";
+import { type GameContext, type GameContextContent, type GameContextModels } from "./gameContext.js";
 import { type InputFrame } from "./inputSnapshot.js";
 import { type WorldDiff } from "./worldReplication.js";
-import type { WorldSnapshot } from "./worldSnapshot.js";
+import type { SnapshotViewer, WorldSnapshot } from "./worldSnapshot.js";
 export type { InputFrame };
 /** 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 declare const INPUT_COMMAND = "engine.input";
@@ -21,6 +21,8 @@ export interface HostedGameRunnerOptions<TAssetRef extends ModelAssetRef, TMulti
      * snapshot overlays the world state it seeded. Omit for a long-lived stateful host (ws) that keeps one runner.
      */
     restore?: WorldSnapshot;
+    /** Render-model lookup for collider auto-fit — pass the same lookup the shell derives from `entityModels`/`objectModels` so host and clients resolve identical hitboxes. */
+    models?: GameContextModels;
 }
 /**
  * The GameContext-loop equivalent of the pure-reducer `createGameHost`: one authoritative `createGameContext`
@@ -41,9 +43,14 @@ export interface HostedGameRunner {
     tick(dt: number): number;
     diff(sinceRevision: number): WorldDiff;
     revision(): number;
-    snapshot(): WorldSnapshot;
+    /** The full world baseline — projected to only what `viewer` may see when the context carries a replication policy, else the whole world. */
+    snapshot(viewer?: SnapshotViewer): WorldSnapshot;
+    /** True when {@link snapshot} is viewer-dependent (a replication policy projects private/AOI state); a host must then serve each viewer its own frame. */
+    projectsViewers(): boolean;
     members(): readonly string[];
     context(): GameContext;
 }
-/** Build a {@link HostedGameRunner} — one authoritative GameContext world driven server-side from the game's own loop. */
+/** Build a {@link HostedGameRunner} — one authoritative GameContext world driven server-side from the game's own loop.
+ * @internal
+ */
 export declare function createHostedGameRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedGameRunnerOptions<TAssetRef, TMultiplayer>): HostedGameRunner;

package/dist/runtime/hostedGameRunner.js

@@ -1,9 +1,13 @@
+import { syncLifecyclePhase } from "../game/gamePhase.js";
+import { advanceBehaviors } from "../scene/behaviorRuntime.js";
 import { createGameContext } from "./gameContext.js";
 import {} from "./inputSnapshot.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";
-/** Build a {@link HostedGameRunner} — one authoritative GameContext world driven server-side from the game's own loop. */
+/** Build a {@link HostedGameRunner} — one authoritative GameContext world driven server-side from the game's own loop.
+ * @internal
+ */
 export function createHostedGameRunner(options) {
     const { definition, content, host, now, restore } = options;
     const ctx = createGameContext({
@@ -11,20 +15,29 @@ export function createHostedGameRunner(options) {
         content,
         player: host ?? { userId: "host", isNew: true },
         ...(now === undefined ? {} : { now }),
+        ...(definition.replication === undefined ? {} : { replication: definition.replication }),
+        ...(options.models === undefined ? {} : { models: options.models }),
     });
     const loop = definition.loop ?? {};
-    const replicator = createWorldReplicator(() => ctx.snapshot());
+    const replicator = createWorldReplicator(() => ctx.snapshot(), {
+        worldVersion: () => ctx.replicationVersion(),
+    });
     const members = new Map();
     const inputs = new Map();
+    const inputSeq = new Map();
     loop.onInit?.(ctx);
+    syncLifecyclePhase(ctx, definition.lifecycle);
     if (restore !== undefined)
         ctx.hydrate(restore);
     return {
         join(userId, isNew) {
+            if (members.has(userId))
+                return;
             const player = { userId, isNew };
             members.set(userId, player);
             ctx.game.players?.join(userId, isNew);
             loop.onNewPlayer?.(ctx, player);
+            syncLifecyclePhase(ctx, definition.lifecycle);
         },
         resume(userId) {
             members.set(userId, { userId, isNew: false });
@@ -36,10 +49,18 @@ export function createHostedGameRunner(options) {
                 return;
             members.delete(userId);
             inputs.delete(userId);
+            inputSeq.delete(userId);
             loop.onPlayerLeave?.(ctx, player);
             ctx.game.players?.leave(userId);
         },
         input(userId, frame) {
+            const seq = frame.seq;
+            if (seq !== undefined) {
+                const lastSeq = inputSeq.get(userId);
+                if (lastSeq !== undefined && seq <= lastSeq)
+                    return;
+                inputSeq.set(userId, seq);
+            }
             inputs.set(userId, frame);
             ctx.game.players?.setInput(userId, frame);
         },
@@ -51,11 +72,14 @@ export function createHostedGameRunner(options) {
         },
         tick(dt) {
             loop.onTick?.(ctx, dt);
+            advanceBehaviors(ctx, dt);
+            syncLifecyclePhase(ctx, definition.lifecycle);
             return replicator.commit();
         },
         diff: (sinceRevision) => replicator.diff(sinceRevision),
         revision: () => replicator.revision(),
-        snapshot: () => ctx.snapshot(),
+        snapshot: (viewer) => ctx.snapshot(viewer),
+        projectsViewers: () => ctx.replicatesPerViewer(),
         members: () => Array.from(members.keys()),
         context: () => ctx,
     };

package/dist/runtime/hostedWorldSession.d.ts

@@ -1,10 +1,10 @@
 import type { CommandResult } from "../commands/commandRegistry.js";
 import type { ModelAssetRef } from "../scene/assetCatalog.js";
-import type { GameContext, GameContextContent } from "./gameContext.js";
+import type { GameContext, GameContextContent, GameContextModels } 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";
+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;
@@ -19,7 +19,9 @@ export interface HostedWorldStore {
     load(): HostedWorldRecord | null;
     save(record: HostedWorldRecord): void;
 }
-/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host. */
+/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host.
+ * @internal
+ */
 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 = {
@@ -38,8 +40,10 @@ export interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMul
     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. */
+    /** 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}. */
+    models?: GameContextModels;
 }
 /**
  * The stateful host substrate a long-lived backend binds (ws server, browser P2P host): a live
@@ -55,11 +59,17 @@ 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;
+    /** 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. */
+    projectsViewers(): boolean;
     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. */
+/** Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick.
+ * @internal
+ */
 export declare function createHostedWorldSession<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedWorldSessionOptions<TAssetRef, TMultiplayer>): HostedWorldSession;

package/dist/runtime/hostedWorldSession.js

@@ -1,5 +1,7 @@
 import { createHostedGameRunner } from "./hostedGameRunner.js";
-/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host. */
+/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host.
+ * @internal
+ */
 export function memoryWorldStore(seed) {
     let record = seed ?? null;
     return {
@@ -9,9 +11,12 @@ export function memoryWorldStore(seed) {
         },
     };
 }
-/** Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick. */
+/** Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick.
+ * @internal
+ */
 export function createHostedWorldSession(options) {
     const { definition, content, host, now, saveIntervalMs = 0 } = options;
+    const clock = now ?? Date.now;
     const store = options.store ?? memoryWorldStore();
     const loaded = store.load();
     const runner = createHostedGameRunner({
@@ -20,9 +25,10 @@ export function createHostedWorldSession(options) {
         ...(host === undefined ? {} : { host }),
         ...(now === undefined ? {} : { now }),
         ...(loaded === null ? {} : { restore: loaded.snapshot }),
+        ...(options.models === undefined ? {} : { models: options.models }),
     });
     let savedRevision = loaded?.revision ?? 0;
-    let lastSaveAt = now?.() ?? 0;
+    let lastSaveAt = clock();
     function persist() {
         savedRevision = runner.revision();
         store.save({ snapshot: runner.snapshot(), revision: savedRevision });
@@ -35,7 +41,7 @@ export function createHostedWorldSession(options) {
         tick(dt) {
             const revision = runner.tick(dt);
             if (revision !== savedRevision) {
-                const at = now?.() ?? 0;
+                const at = clock();
                 if (saveIntervalMs <= 0 || at - lastSaveAt >= saveIntervalMs) {
                     lastSaveAt = at;
                     persist();
@@ -49,6 +55,8 @@ export function createHostedWorldSession(options) {
             }
             return { kind: "diff", diff: runner.diff(sinceRevision) };
         },
+        snapshotFor: (viewer) => runner.snapshot(viewer),
+        projectsViewers: () => runner.projectsViewers(),
         revision: () => runner.revision(),
         members: () => runner.members(),
         save: persist,

package/dist/runtime/inputSnapshot.d.ts

@@ -6,14 +6,19 @@ export interface InputFrame {
     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. */
+    /** 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`. */
     publishPointer(state: PointerAxisState | null): void;
     isDown(action: string): boolean;
+    /** The held-action set for this frame — an owned, frozen array; the array {@link publish} was called with is never aliased or returned. */
     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;
+    /** True only on the frame `action` transitions from up to down (#671) — derived from the last two published held sets, so it stays replay-safe. */
+    justPressed(action: string): boolean;
+    /** True only on the frame `action` transitions from down to up (#671); mirrors {@link justPressed}. */
+    justReleased(action: string): boolean;
+    /** 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. Frozen — an owned copy of what {@link publishPointer} was called with. */
+    pointer(): Readonly<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

package/dist/runtime/inputSnapshot.js

@@ -1,19 +1,23 @@
 import { sampleAxisBindings } from "../input/axisInput.js";
 export function createInputSnapshot() {
     let heldSet = new Set();
+    let previousHeldSet = new Set();
     let heldList = [];
     let pointerState = null;
     return {
         publish(held) {
-            heldList = held;
+            previousHeldSet = heldSet;
+            heldList = Object.freeze([...held]);
             heldSet = new Set(held);
         },
         publishPointer(state) {
-            pointerState = state;
+            pointerState = state === null ? null : Object.freeze({ ...state });
         },
         isDown: (action) => heldSet.has(action),
         held: () => heldList,
         pointer: () => pointerState,
         axis: (bindings, ranges) => sampleAxisBindings(bindings, (action) => heldSet.has(action), pointerState, ranges),
+        justPressed: (action) => heldSet.has(action) && !previousHeldSet.has(action),
+        justReleased: (action) => !heldSet.has(action) && previousHeldSet.has(action),
     };
 }

package/dist/runtime/motionIntents.d.ts

@@ -21,6 +21,10 @@ export interface MotionIntents {
     setVerticalVelocity(velocityY: number): void;
     setY(y: number): void;
     takePending(): MotionIntentBatch | null;
+    /** Non-draining copy of the pending intents for a whole-world save; unlike `takePending` it leaves the queue intact. */
+    snapshot(): MotionIntentBatch;
+    /** Replace the pending intents from a {@link snapshot} payload on save load. */
+    hydrate(batch: MotionIntentBatch): void;
 }
 export interface MotionIntentBatch {
     impulses: readonly number[];
@@ -28,8 +32,13 @@ export interface MotionIntentBatch {
     verticalVelocity: number | null;
     y: number | null;
 }
+/** @internal */
 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}. */
+/** 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 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. */
+/** Fold a batch's horizontal pushes into a controller's velocity pair — shared by the walk and voxel drivers.
+ * @internal
+ */
 export declare function applyHorizontalImpulses(velocityX: number, velocityZ: number, batch: MotionIntentBatch | null): readonly [number, number];

package/dist/runtime/motionIntents.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createMotionIntents() {
     let impulses = [];
     let horizontalImpulses = [];
@@ -27,9 +28,20 @@ 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 vertical impulses into a controller's velocity, then apply an outright `setVerticalVelocity` override — the vertical counterpart of {@link applyHorizontalImpulses}. */
+/** 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;
@@ -40,7 +52,9 @@ export function applyMotionImpulses(currentVelocity, batch) {
         velocity = batch.verticalVelocity;
     return velocity;
 }
-/** Fold a batch's horizontal pushes into a controller's velocity pair — shared by the walk and voxel drivers. */
+/** 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);
+    };
+}