@jgengine/core 0.10.0 → 0.11.0

package/dist/runtime/gameRuntime.d.ts

@@ -43,4 +43,5 @@ export type GameRuntime = {
     joinPlayer: (snapshot: GameRuntimeSnapshot, userId: string, isNew: boolean) => GameRuntimeSnapshot;
     toProfileRow: (snapshot: GameRuntimeSnapshot, userId: string) => RuntimeProfileRow | null;
 };
+/** @internal */
 export declare function createGameRuntime(definition: GameRuntimeDefinition): GameRuntime;

package/dist/runtime/gameRuntime.js

@@ -1,5 +1,6 @@
 import { runCommand } from "./commandRunner.js";
 import { createEmptyPlayerRow, createRuntimeSnapshot, } from "./snapshot.js";
+/** @internal */
 export function createGameRuntime(definition) {
     const loop = definition.loop;
     let initialized = false;

package/dist/runtime/headlessRunner.d.ts

@@ -0,0 +1,60 @@
+import type { GameDefinition, GameLoop } from "../game/defineGame.js";
+import type { PointerAxisState } from "../input/pointerAxis.js";
+import type { ModelAssetRef } from "../scene/assetCatalog.js";
+import { type GameContext, type GameContextContent } from "./gameContext.js";
+import type { InputSnapshot } from "./inputSnapshot.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. */
+    held?: readonly string[];
+    /** Replaces the normalized pointer state; omit to leave the last pointer unchanged (pass `null` to clear it). */
+    pointer?: PointerAxisState | null;
+}
+export interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> {
+    definition: GameDefinition<TAssetRef, TMultiplayer>;
+    /** Catalog resolvers (`entityById`/`objectById`) the context uses; defaults to an empty catalog. */
+    content?: GameContextContent;
+    /** Lifecycle hooks — `onInit`/`onNewPlayer` fire at construction, `onTick` on every {@link HeadlessRunner.step}. The shell keeps this separate from `definition` (presentation wraps it); a headless caller passes it directly. */
+    loop?: GameLoop<GameContext>;
+    /** The single local player; defaults to `{ userId: "player", isNew: true }`. */
+    player?: {
+        userId: string;
+        isNew: boolean;
+    };
+    /** Wall-clock source for the sim clock — inject a deterministic counter for reproducible runs. */
+    now?: () => number;
+    /** Per-step real-dt clamp in seconds, matching the shell's frame cap so one long stall can't fast-forward the sim. Default `0.05`. */
+    maxStepSeconds?: number;
+    /**
+     * Drive the built-in keyboard player-movement controller from the held-action set each step, exactly as the shell's
+     * FrameDriver does for pose-driven games. Off by default — cartridge/tick-driven games move their own entities inside
+     * `onTick` and don't need it.
+     */
+    playerMovement?: boolean;
+    /** Yaw heading (radians) fed to the movement controller when `playerMovement` is on; the shell supplies its camera yaw. */
+    heading?: number;
+}
+/**
+ * A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init
+ * hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole
+ * play path (time, input, `onTick`, behaviour nav, optional player movement) runs from `core` primitives alone, so a
+ * non-React host (a server tick, a test, a CLI replay) can play a real game and read its world snapshot. The shell's
+ * FrameDriver is one such driver bolted to `useFrame`; this is the same step distilled out of the render tree.
+ *
+ * @capability headless-runner play a real game loop with no renderer — tick, feed input, read the world snapshot
+ */
+export interface HeadlessRunner {
+    /** The live game context — read `ctx.scene.entity.list()`, `ctx.game.store`, `ctx.subscribe`/`ctx.version()` for the world snapshot. */
+    readonly ctx: GameContext;
+    /** The per-frame input the loop reads; the same object exposed as `ctx.input`. */
+    readonly input: InputSnapshot;
+    readonly userId: string;
+    /**
+     * Advance the simulation one step. Publishes `input` (if given), advances the sim clock by the clamped real dt,
+     * runs optional player movement, then `loop.onTick` and behaviour nav. Returns the scaled game dt `onTick` saw.
+     */
+    step(dtSeconds: number, input?: HeadlessInput): number;
+    /** Publish input without advancing — for pre-seeding the held set before the first {@link step}. */
+    publishInput(input: HeadlessInput): void;
+}
+export declare function createHeadlessRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HeadlessRunnerOptions<TAssetRef, TMultiplayer>): HeadlessRunner;

package/dist/runtime/headlessRunner.js

@@ -0,0 +1,44 @@
+import { resolvePlayerMovementTuning, stepPlayerMovement, } from "../movement/playerMovement.js";
+import { advanceBehaviors } from "../scene/behaviorRuntime.js";
+import { createGameContext } from "./gameContext.js";
+export function createHeadlessRunner(options) {
+    const { definition, loop } = options;
+    const content = options.content ?? {};
+    const player = options.player ?? { userId: "player", isNew: true };
+    const maxStep = options.maxStepSeconds ?? 0.05;
+    const ctx = createGameContext({
+        definition,
+        content,
+        player,
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    loop?.onInit?.(ctx);
+    loop?.onNewPlayer?.(ctx);
+    const tuning = options.playerMovement === true
+        ? resolvePlayerMovementTuning({ physics: definition.physics, world: definition.world })
+        : null;
+    function publishInput(input) {
+        if (input.held !== undefined)
+            ctx.input.publish(input.held);
+        if (input.pointer !== undefined)
+            ctx.input.publishPointer(input.pointer);
+    }
+    return {
+        ctx,
+        input: ctx.input,
+        userId: player.userId,
+        publishInput,
+        step(dtSeconds, input) {
+            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;
+        },
+    };
+}

package/dist/runtime/hostPersistence.d.ts

@@ -58,11 +58,13 @@ export type LeaderboardEntry = {
     value: number;
 };
 export declare const LEADERBOARD_PENDING_KEY = "leaderboardPending";
+/** @internal */
 export declare function drainPendingLeaderboardIncrements(session: Record<string, unknown>): {
     increments: LeaderboardIncrement[];
     session: Record<string, unknown>;
 };
 export declare const LEADERBOARD_TOP_LIMIT = 100;
+/** @internal */
 export declare function clampLimit(value: number | undefined, fallback: number, max: number): number;
 export type LeaderboardRow = {
     gameId: string;
@@ -73,8 +75,11 @@ export type LeaderboardRow = {
     value: number;
     updatedAt: number;
 };
+/** @internal */
 export declare function leaderboardRowKey(row: Omit<LeaderboardRow, "value" | "updatedAt">): string;
+/** @internal */
 export declare function applyLeaderboardRows(rows: Map<string, LeaderboardRow>, gameId: string, entries: LeaderboardIncrement[], now: number): void;
+/** @internal */
 export declare function topLeaderboardRows(rows: Iterable<LeaderboardRow>, args: {
     gameId: string;
     stat: string;
@@ -82,9 +87,12 @@ export declare function topLeaderboardRows(rows: Iterable<LeaderboardRow>, args:
     serverId?: string;
     limit?: number;
 }): LeaderboardEntry[];
+/** @internal */
 export declare function profileLeaderboardStats(rows: Iterable<LeaderboardRow>, gameId: string, userId: string): Record<string, number>;
 export declare const FEED_RING_LIMIT = 20;
+/** @internal */
 export declare function trimFeedEntries<T>(entries: T[], limit?: number): T[];
+/** @internal */
 export declare function shouldAutoSave(save: SaveConfig, dirtyAt: number | undefined, lastSavedAt: number | undefined, now: number): boolean;
 export type ServerListing = {
     serverId: string;
@@ -101,9 +109,11 @@ export type ServerListing = {
 export type ToServerListingOptions = {
     includeJoinCode?: boolean;
 };
+/** @internal */
 export declare function toServerListing(record: GameServerRecord, options?: ToServerListingOptions): ServerListing;
 export declare const OPEN_SERVER_LISTING_LIMIT = 20;
 export declare const OPEN_SERVER_LISTING_MAX = 100;
+/** @internal */
 export declare function toOpenServerListings(listings: Iterable<ServerListing>, limit?: number): ServerListing[];
 export type HostPersistence = {
     savePlan?: (plan: ServerPersistPlan) => Promise<void>;
@@ -141,6 +151,7 @@ export type HostPersistence = {
         userId: string;
     }) => Promise<Record<string, number>>;
 };
+/** @internal */
 export declare function buildHydratePlayers(server: GameServerRecord, profiles: Record<string, PlayerProfileRecord | null>): Record<string, RuntimePlayerRow>;
 export type ServerPersistPlan = {
     server: GameServerRecord;
@@ -149,4 +160,5 @@ export type ServerPersistPlan = {
     deletedChunks: string[];
     leaderboard: LeaderboardIncrement[];
 };
+/** @internal */
 export declare function planServerPersist(server: GameServerRecord, snapshot: GameRuntimeSnapshot, save: SaveConfig, now: number): ServerPersistPlan;

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/hostedGameRunner.d.ts

@@ -4,7 +4,7 @@ import type { ModelAssetRef } from "../scene/assetCatalog.js";
 import { type GameContext, type GameContextContent } 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";
@@ -41,9 +41,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,28 @@ export function createHostedGameRunner(options) {
         content,
         player: host ?? { userId: "host", isNew: true },
         ...(now === undefined ? {} : { now }),
+        ...(definition.replication === undefined ? {} : { replication: definition.replication }),
     });
     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 +48,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 +71,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

@@ -4,7 +4,7 @@ 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";
+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,7 +40,7 @@ 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;
 }
 /**
@@ -55,11 +57,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({
@@ -22,7 +27,7 @@ export function createHostedWorldSession(options) {
         ...(loaded === null ? {} : { restore: loaded.snapshot }),
     });
     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 +40,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 +54,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);
+    };
+}