@jgengine/core 0.9.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

@@ -0,0 +1,54 @@
+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 InputFrame } from "./inputSnapshot.js";
+import { type WorldDiff } from "./worldReplication.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";
+/** Config for {@link createHostedGameRunner}: the game definition, its content lookup, and an optional host identity. */
+export interface HostedGameRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> {
+    definition: GameDefinition<TAssetRef, TMultiplayer>;
+    content: GameContextContent;
+    /** The world's own authoritative identity (`ctx.player` server-side); real players join as members. */
+    host?: LoopPlayer;
+    now?: () => number;
+    /**
+     * Rehydrate a persisted world instead of booting a fresh one — for stateless hosts (Convex) that reconstruct
+     * the runner each invocation. `onInit` still runs (so commands and systems it registers exist), then this
+     * snapshot overlays the world state it seeded. Omit for a long-lived stateful host (ws) that keeps one runner.
+     */
+    restore?: WorldSnapshot;
+}
+/**
+ * The GameContext-loop equivalent of the pure-reducer `createGameHost`: one authoritative `createGameContext`
+ * per world, driven server-side. `onInit` runs once at construction; `onNewPlayer`/`onPlayerLeave` fire per
+ * join/leave; `tick` advances `onTick` then commits a revision. Clients pull a full {@link WorldSnapshot}
+ * baseline once, then per-tick {@link WorldDiff}s from their last revision. Games ship only normal GameContext
+ * code — the runner adds no per-game surface.
+ */
+export interface HostedGameRunner {
+    join(userId: string, isNew: boolean): void;
+    /** Re-attach an already-joined member on a reconstructed runner — restores membership and `ctx.game.players` without re-firing `onNewPlayer`. Stateless hosts call it once per persisted member after `restore`. */
+    resume(userId: string): void;
+    leave(userId: string): void;
+    /** Record a client's latest input frame — stashed for {@link heldInput} and mirrored onto `ctx.game.players` so the movement seam reads each player's intent in `onTick`. */
+    input(userId: string, frame: InputFrame): void;
+    heldInput(userId: string): InputFrame | null;
+    command(userId: string, name: string, input: unknown): CommandResult<GameContext>;
+    tick(dt: number): number;
+    diff(sinceRevision: number): WorldDiff;
+    revision(): number;
+    /** 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.
+ * @internal
+ */
+export declare function createHostedGameRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedGameRunnerOptions<TAssetRef, TMultiplayer>): HostedGameRunner;

package/dist/runtime/hostedGameRunner.js

@@ -0,0 +1,85 @@
+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.
+ * @internal
+ */
+export function createHostedGameRunner(options) {
+    const { definition, content, host, now, restore } = options;
+    const ctx = createGameContext({
+        definition,
+        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(), {
+        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 });
+            ctx.game.players?.join(userId, false);
+        },
+        leave(userId) {
+            const player = members.get(userId);
+            if (player === undefined)
+                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);
+        },
+        heldInput(userId) {
+            return inputs.get(userId) ?? null;
+        },
+        command(userId, name, input) {
+            return ctx.game.commands.runAs(userId, name, input);
+        },
+        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: (viewer) => ctx.snapshot(viewer),
+        projectsViewers: () => ctx.replicatesPerViewer(),
+        members: () => Array.from(members.keys()),
+        context: () => ctx,
+    };
+}

package/dist/runtime/hostedWorldSession.d.ts

@@ -0,0 +1,73 @@
+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 { SnapshotViewer, WorldSnapshot } from "./worldSnapshot.js";
+/** One hosted world's persisted authoritative state — the unit a {@link HostedWorldStore} loads and saves. */
+export interface HostedWorldRecord {
+    snapshot: WorldSnapshot;
+    revision: number;
+}
+/**
+ * Narrow persistence seam for a hosted world — the {@link HostedWorldRecord} counterpart of `HostPersistence`.
+ * Backends implement it (memory/file/sql/convex); the session never names one. A stateful host loads once and
+ * saves on a cadence; a stateless host reconstructs from `load()` each invocation.
+ */
+export interface HostedWorldStore {
+    load(): HostedWorldRecord | null;
+    save(record: HostedWorldRecord): void;
+}
+/** 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 = {
+    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 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;
+}
+/**
+ * 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;
+    /** 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.
+ * @internal
+ */
+export declare function createHostedWorldSession<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedWorldSessionOptions<TAssetRef, TMultiplayer>): HostedWorldSession;

package/dist/runtime/hostedWorldSession.js

@@ -0,0 +1,64 @@
+import { createHostedGameRunner } from "./hostedGameRunner.js";
+/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host.
+ * @internal
+ */
+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.
+ * @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({
+        definition,
+        content,
+        ...(host === undefined ? {} : { host }),
+        ...(now === undefined ? {} : { now }),
+        ...(loaded === null ? {} : { restore: loaded.snapshot }),
+    });
+    let savedRevision = loaded?.revision ?? 0;
+    let lastSaveAt = clock();
+    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 = clock();
+                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) };
+        },
+        snapshotFor: (viewer) => runner.snapshot(viewer),
+        projectsViewers: () => runner.projectsViewers(),
+        revision: () => runner.revision(),
+        members: () => runner.members(),
+        save: persist,
+        runner: () => runner,
+    };
+}

package/dist/runtime/inputSnapshot.d.ts

@@ -1,12 +1,30 @@
 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. */
+    /** 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
+     * 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,17 +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,6 +32,13 @@ export interface MotionIntentBatch {
     verticalVelocity: number | null;
     y: number | null;
 }
+/** @internal */
 export declare function createMotionIntents(): MotionIntents;
-/** 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 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.
+ * @internal
+ */
 export declare function applyHorizontalImpulses(velocityX: number, velocityZ: number, batch: MotionIntentBatch | null): readonly [number, number];