@jgengine/core 0.18.1 → 0.21.0

package/dist/runtime/hostedGameRunner.js

@@ -24,29 +24,142 @@ export function createHostedGameRunner(options) {
     const loop = definition.loop ?? {};
     const replicator = createWorldReplicator(() => ctx.snapshot(), {
         worldVersion: () => ctx.replicationVersion(),
+        initialRevision: options.revision ?? 0,
     });
     const members = new Map();
     const inputs = new Map();
     const latestInputs = new Map();
-    const movementTuning = resolvePlayerMovementTuning({ world: definition.world, physics: definition.physics });
+    const movementTuning = { ...resolvePlayerMovementTuning({ world: definition.world, physics: definition.physics }), authoritativeStep: true };
     const inputSeq = new Map();
+    const inputPressSeq = new Map();
+    const departed = new Map();
+    const maxDepartedUsers = options.inputRetention?.maxDepartedUsers ?? 256;
+    const departedTtlMs = options.inputRetention?.departedTtlMs ?? 300_000;
+    const inputNowMs = options.inputRetention?.nowMs ?? Date.now;
+    if (!Number.isInteger(maxDepartedUsers) || maxDepartedUsers < 0 || !Number.isFinite(departedTtlMs) || departedTtlMs < 0) {
+        throw new RangeError("inputRetention requires a nonnegative integer user limit and finite nonnegative TTL");
+    }
+    let retentionTime = -Infinity;
+    const retentionNow = () => {
+        const time = inputNowMs();
+        if (!Number.isFinite(time))
+            throw new RangeError("inputRetention.nowMs must return finite milliseconds");
+        return retentionTime = Math.max(retentionTime, time);
+    };
+    const expireDeparted = () => {
+        const time = retentionNow();
+        // Monotone leave times keep insertion order equal to expiry order, even if
+        // the wall clock reverses. Live ingress inspects only the first tombstone.
+        while (departed.size > 0) {
+            const [userId, expiresAt] = departed.entries().next().value;
+            if (expiresAt > time && departed.size <= maxDepartedUsers)
+                break;
+            departed.delete(userId);
+            inputSeq.delete(userId);
+            inputPressSeq.delete(userId);
+        }
+    };
+    const compactRecorder = (recorder, tick) => {
+        const continuous = recorder.frameAt(tick);
+        const frames = recorder.frames().filter(entry => entry.tick > tick);
+        if (continuous !== null) {
+            const { presses: _consumed, ...held } = continuous;
+            frames.unshift({ tick, frame: held });
+        }
+        recorder.restore({ frames });
+    };
     let hostTick = 0;
+    const inputModule = {
+        key: "hostInput",
+        snapshot() {
+            const tick = ctx.sim.tick();
+            const saved = [];
+            for (const userId of members.keys()) {
+                const recorder = inputs.get(userId);
+                const latest = latestInputs.get(userId);
+                if (recorder === undefined || latest === undefined)
+                    continue;
+                const continuous = recorder.frameAt(tick);
+                // Keep continuous intent and unconsumed future ticks, never elapsed history.
+                // Live input coalesces onto the next tick; explicit replay may stage future ticks.
+                const frames = recorder.frames().filter(entry => entry.tick > tick);
+                if (continuous !== null) {
+                    const { presses: _consumed, ...held } = continuous;
+                    frames.unshift({ tick, frame: held });
+                }
+                const seq = inputSeq.get(userId);
+                const pressSeq = inputPressSeq.get(userId);
+                saved.push({ userId, latest, recorder: { frames }, ...(seq === undefined ? {} : { seq }), ...(pressSeq === undefined ? {} : { pressSeq }) });
+            }
+            return saved;
+        },
+        hydrate(saved) {
+            inputs.clear();
+            latestInputs.clear();
+            inputSeq.clear();
+            inputPressSeq.clear();
+            departed.clear();
+            for (const input of saved) {
+                const recorder = createInputRecorder();
+                recorder.restore(input.recorder);
+                inputs.set(input.userId, recorder);
+                latestInputs.set(input.userId, input.latest);
+                if (input.seq !== undefined)
+                    inputSeq.set(input.userId, input.seq);
+                if (input.pressSeq !== undefined)
+                    inputPressSeq.set(input.userId, input.pressSeq);
+            }
+        },
+        decode(raw) {
+            const frame = (value) => {
+                if (value === null || typeof value !== "object" || !("held" in value) || !Array.isArray(value.held) || !value.held.every(action => typeof action === "string"))
+                    return false;
+                if (!("pointer" in value))
+                    return false;
+                const pointer = value.pointer;
+                if (pointer !== null && (typeof pointer !== "object" || !("x" in pointer) || !("y" in pointer) || !("active" in pointer) || !Number.isFinite(pointer.x) || !Number.isFinite(pointer.y) || typeof pointer.active !== "boolean"))
+                    return false;
+                if ("tick" in value && value.tick !== undefined && !Number.isFinite(value.tick))
+                    return false;
+                if ("presses" in value && value.presses !== undefined && (!Array.isArray(value.presses) || !value.presses.every(press => press !== null && typeof press === "object" && typeof press.action === "string" && Number.isFinite(press.seq))))
+                    return false;
+                if ("analog" in value && value.analog !== undefined && value.analog !== null && (typeof value.analog !== "object" || Array.isArray(value.analog) || !Object.values(value.analog).every(Number.isFinite)))
+                    return false;
+                return true;
+            };
+            if (!Array.isArray(raw) || !raw.every(input => input !== null && typeof input === "object" && typeof input.userId === "string" &&
+                (input.seq === undefined || Number.isFinite(input.seq)) && (input.pressSeq === undefined || Number.isFinite(input.pressSeq)) && frame(input.latest) &&
+                input.recorder !== null && typeof input.recorder === "object" && Array.isArray(input.recorder.frames) &&
+                input.recorder.frames.every((entry) => entry !== null && typeof entry === "object" && Number.isFinite(entry.tick) && frame(entry.frame))))
+                return null;
+            if (new Set(raw.map(input => input.userId)).size !== raw.length)
+                return null;
+            return raw;
+        },
+    };
+    ctx.game.registerSave?.(inputModule);
     loop.onInit?.(ctx);
     syncLifecyclePhase(ctx, definition.lifecycle);
     if (restore !== undefined)
-        ctx.hydrate(restore);
+        ctx.restore(restore);
     return {
         join(userId, isNew) {
+            expireDeparted();
             if (members.has(userId))
                 return;
+            departed.delete(userId);
             const player = { userId, isNew };
             members.set(userId, player);
+            ctx.player.possession.own(userId, userId);
             ctx.game.players?.join(userId, isNew);
             loop.onNewPlayer?.(ctx, player);
             syncLifecyclePhase(ctx, definition.lifecycle);
         },
         resume(userId) {
+            expireDeparted();
+            departed.delete(userId);
             members.set(userId, { userId, isNew: false });
+            ctx.player.possession.own(userId, userId);
             ctx.game.players?.join(userId, false);
         },
         leave(userId) {
@@ -56,12 +169,22 @@ export function createHostedGameRunner(options) {
             members.delete(userId);
             inputs.delete(userId);
             latestInputs.delete(userId);
-            inputSeq.delete(userId);
+            // Retain only bounded, recent admission marks; departed ingress is ignored.
+            if (inputSeq.has(userId) || inputPressSeq.has(userId)) {
+                departed.delete(userId);
+                departed.set(userId, retentionNow() + departedTtlMs);
+            }
+            expireDeparted();
             loop.onPlayerLeave?.(ctx, player);
             ctx.game.players?.leave(userId);
         },
         input(userId, frame) {
+            expireDeparted();
+            if (!members.has(userId))
+                return;
             const seq = frame.seq;
+            if ((seq !== undefined && !Number.isFinite(seq)) || (frame.tick !== undefined && !Number.isFinite(frame.tick)))
+                return;
             if (seq !== undefined) {
                 const lastSeq = inputSeq.get(userId);
                 if (lastSeq !== undefined && seq <= lastSeq)
@@ -73,8 +196,26 @@ export function createHostedGameRunner(options) {
                 recorder = createInputRecorder();
                 inputs.set(userId, recorder);
             }
-            recorder.record(frame.tick ?? ctx.sim.tick() + 1, frame);
-            latestInputs.set(userId, frame);
+            let admitted = frame;
+            if (frame.presses !== undefined) {
+                let lastPress = inputPressSeq.get(userId) ?? -Infinity;
+                const presses = [...frame.presses].sort((a, b) => a.seq - b.seq).filter(press => {
+                    if (!Number.isFinite(press.seq) || press.seq <= lastPress)
+                        return false;
+                    lastPress = press.seq;
+                    return true;
+                });
+                if (presses.length > 0)
+                    inputPressSeq.set(userId, lastPress);
+                admitted = { ...frame, presses };
+            }
+            recorder.record(frame.tick ?? ctx.sim.tick() + 1, admitted);
+            compactRecorder(recorder, ctx.sim.tick());
+            latestInputs.set(userId, admitted);
+        },
+        inputStats() {
+            expireDeparted();
+            return { members: members.size, recorders: inputs.size, recordedFrames: [...inputs.values()].reduce((count, recorder) => count + recorder.frames().length, 0), latestInputs: latestInputs.size, wireSequences: inputSeq.size, pressSequences: inputPressSeq.size, departedUsers: departed.size };
         },
         heldInput(userId) {
             return latestInputs.get(userId) ?? null;
@@ -83,8 +224,9 @@ export function createHostedGameRunner(options) {
             return ctx.game.commands.runAs(userId, name, input);
         },
         tick(dt) {
+            expireDeparted();
             hostTick += 1;
-            ctx.sim.advance(dt, (stepDt, tick) => {
+            ctx.sim.advance(dt, (stepDt, tick, gameDt) => {
                 for (const [userId, recorder] of inputs) {
                     const frame = recorder.frameAt(tick);
                     if (frame !== null)
@@ -93,13 +235,15 @@ export function createHostedGameRunner(options) {
                 ctx.sim.runStages("beforeMovement", stepDt);
                 for (const userId of members.keys()) {
                     const frame = inputs.get(userId)?.frameAt(tick) ?? null;
-                    if (frame !== null)
-                        serverStep(ctx, userId, frame, stepDt, movementTuning);
+                    if (frame !== null && gameDt > 0)
+                        serverStep(ctx, userId, frame, gameDt, movementTuning);
                 }
                 ctx.sim.runStages("afterMovement", stepDt);
-                loop.onTick?.(ctx, stepDt);
-                advanceBehaviors(ctx, stepDt);
+                loop.onTick?.(ctx, gameDt);
+                advanceBehaviors(ctx, gameDt);
                 ctx.sim.runStages("afterTick", stepDt);
+                for (const recorder of inputs.values())
+                    compactRecorder(recorder, tick);
             });
             syncLifecyclePhase(ctx, definition.lifecycle);
             return replicator.commit();
@@ -107,6 +251,8 @@ export function createHostedGameRunner(options) {
         diff: (sinceRevision) => replicator.diff(sinceRevision),
         revision: () => replicator.revision(),
         snapshot: (viewer) => ctx.snapshot(viewer === undefined ? undefined : { ...viewer, tick: hostTick }),
+        state: ctx.state,
+        commit: () => replicator.commit(),
         projectsViewers: () => ctx.replicatesPerViewer(),
         members: () => Array.from(members.keys()),
         context: () => ctx,

package/dist/runtime/hostedWorldSession.d.ts

@@ -7,7 +7,12 @@ import type { WorldDiff } from "./worldReplication.js";
 import type { SnapshotViewer, WorldSnapshot } from "./worldSnapshot.js";
 import type { HostedWorldRecord, HostedWorldStore, SyncHostedWorldStore } from "./hostedWorldStore.js";
 export type { HostedWorldRecord, HostedWorldStore, SyncHostedWorldStore } from "./hostedWorldStore.js";
-/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host.
+/** @internal Decode the retry envelope shared by authoritative hosts. */
+export declare function unwrapOpEnvelope(input: unknown): {
+    opId: string;
+    input: unknown;
+} | null;
+/** Detached in-process {@link SyncHostedWorldStore} for tests, local play, and the browser-tab P2P host.
  * @internal
  */
 export declare function memoryWorldStore(seed?: HostedWorldRecord): SyncHostedWorldStore;
@@ -30,8 +35,10 @@ export interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMul
     now?: () => number;
     /** Where the authoritative snapshot persists; defaults to {@link memoryWorldStore}. */
     store?: SyncHostedWorldStore;
-    /** 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. */
+    /** Minimum elapsed ms between automatic saves, measured against `now` (default `Date.now`). Default `0`; private clock/simulation changes also count. A pending write defers automatic capture until a later tick. */
     saveIntervalMs?: number;
+    /** Retained retry receipts per player. Default `64`; retries after eviction are new operations. */
+    operationHistoryLimit?: number;
     /** Render-model lookup for collider auto-fit, forwarded to the runner — see {@link HostedGameRunnerOptions.models}. */
     models?: GameContextModels;
 }
@@ -43,11 +50,14 @@ export interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMul
  */
 export interface HostedWorldSession {
     join(userId: string, isNew: boolean): void;
+    /** Whether this identity has joined before, including across leave/restart. */
+    hasPlayer(userId: string): boolean;
     leave(userId: string): void;
     input(userId: string, frame: InputFrame): void;
-    command(userId: string, name: string, input: unknown): CommandResult<GameContext>;
+    /** Optional stable operation id deduplicates retries across reconnect/restart; the receipt persists atomically with state. */
+    command(userId: string, name: string, input: unknown, operationId?: string): CommandResult<GameContext>;
     tick(dt: number): number;
-    /** Replication pull: `null`/`0` cursor → full baseline; a prior revision → a diff since it. */
+    /** Replication pull: a fresh, pre-restart or future cursor receives a baseline; an in-session revision receives a diff. */
     sync(sinceRevision: number | null): HostedWorldSync;
     /** Alias used by host transports when pulling the next baseline or diff for a subscriber. */
     pull(sinceRevision: number | null): HostedWorldSync;
@@ -58,7 +68,9 @@ export interface HostedWorldSession {
     revision(): number;
     members(): readonly string[];
     /** Force-persist the current world to the store. */
-    save(): void;
+    save(): void | Promise<void>;
+    /** Most recent automatic save failure; cleared by a successful write. Explicit `save()` also rejects. */
+    persistenceError(): unknown | null;
     runner(): HostedGameRunner;
 }
 /** Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick.

package/dist/runtime/hostedWorldSession.js

@@ -1,22 +1,34 @@
 import { createHostedGameRunner } from "./hostedGameRunner.js";
-/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host.
+import { applyWorldSnapshot } from "./worldSnapshot.js";
+/** @internal Decode the retry envelope shared by authoritative hosts. */
+export function unwrapOpEnvelope(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return null;
+    const record = input;
+    const opId = record["__jgWsOpId"];
+    if (typeof opId !== "string")
+        return null;
+    const { __jgWsOpId: _opId, ...rest } = record;
+    return { opId, input: rest };
+}
+/** Detached in-process {@link SyncHostedWorldStore} for tests, local play, and the browser-tab P2P host.
  * @internal
  */
 export function memoryWorldStore(seed) {
-    let record = seed ?? null;
+    let record = seed === undefined ? null : structuredClone(seed);
     return {
-        load: () => record,
+        load: () => record === null ? null : structuredClone(record),
         save(next) {
-            record = { snapshot: next.snapshot, revision: next.revision };
+            record = structuredClone(next);
         },
     };
 }
 /** Async in-process store for callers exercising the production persistence contract. */
 export function asyncMemoryWorldStore(seed) {
-    let record = seed ?? null;
+    let record = seed === undefined ? null : structuredClone(seed);
     return {
-        async load() { return record; },
-        async save(next) { record = { snapshot: next.snapshot, revision: next.revision }; },
+        async load() { return record === null ? null : structuredClone(record); },
+        async save(next) { record = structuredClone(next); },
     };
 }
 /** Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick.
@@ -33,32 +45,157 @@ export function createHostedWorldSession(options) {
         ...(host === undefined ? {} : { host }),
         ...(now === undefined ? {} : { now }),
         ...(loaded === null ? {} : { restore: loaded.snapshot }),
+        revision: loaded?.revision ?? 0,
         ...(options.models === undefined ? {} : { models: options.models }),
     });
+    const knownPlayers = new Set();
+    const operations = new Map();
+    const configuredHistory = options.operationHistoryLimit ?? 64;
+    const historyLimit = Number.isFinite(configuredHistory) ? Math.max(1, Math.floor(configuredHistory)) : 64;
+    const sessionModule = {
+        key: "hostSession",
+        snapshot: () => ({ players: [...knownPlayers], operations: [...operations] }),
+        hydrate(state) {
+            knownPlayers.clear();
+            for (const userId of state.players)
+                knownPlayers.add(userId);
+            operations.clear();
+            for (const [userId, receipts] of state.operations)
+                operations.set(userId, receipts.slice(-historyLimit));
+        },
+        decode(raw) {
+            if (raw === null || typeof raw !== "object" || !("players" in raw) || !("operations" in raw))
+                return null;
+            if (!Array.isArray(raw.players) || !raw.players.every((id) => typeof id === "string") || !Array.isArray(raw.operations))
+                return null;
+            for (const entry of raw.operations) {
+                if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string" || !Array.isArray(entry[1]))
+                    return null;
+                for (const receipt of entry[1]) {
+                    if (receipt === null || typeof receipt !== "object" || typeof receipt.id !== "string" ||
+                        typeof receipt.command !== "string" || typeof receipt.input !== "string" ||
+                        !["applied", "rejected", "unknown-command"].includes(receipt.outcome) ||
+                        (receipt.outcome === "rejected" && typeof receipt.reason !== "string"))
+                        return null;
+                }
+            }
+            return raw;
+        },
+    };
+    runner.context().game.registerSave?.(sessionModule);
+    if (loaded !== null) {
+        if (Object.hasOwn(loaded.snapshot, "hostSession") && sessionModule.decode(loaded.snapshot["hostSession"]) === null) {
+            throw new Error("Invalid hosted player/retry state; save left untouched");
+        }
+        applyWorldSnapshot([sessionModule], loaded.snapshot);
+    }
     let savedRevision = loaded?.revision ?? 0;
+    let savedVersion = runner.context().version();
+    let savedSimTick = runner.context().sim.tick();
     let lastSaveAt = clock();
+    let writing = null;
+    let saveFailure = null;
     function persist() {
-        savedRevision = runner.revision();
-        store.save({ snapshot: runner.snapshot(), revision: savedRevision });
+        const record = { snapshot: runner.state(), revision: runner.revision() };
+        const version = runner.context().version();
+        const simTick = runner.context().sim.tick();
+        const success = () => {
+            savedRevision = record.revision;
+            savedVersion = version;
+            savedSimTick = simTick;
+            saveFailure = null;
+        };
+        const write = () => store.save(record);
+        let pending;
+        try {
+            pending = writing === null ? write() : writing.catch(() => { }).then(write);
+        }
+        catch (error) {
+            saveFailure = error;
+            throw error;
+        }
+        if (pending === undefined) {
+            success();
+            return;
+        }
+        const completion = pending.then(success, (error) => {
+            saveFailure = error;
+            throw error;
+        });
+        writing = completion;
+        void completion.catch(() => { }).finally(() => {
+            if (writing === completion)
+                writing = null;
+        });
+        return completion;
     }
     const pull = (sinceRevision) => {
-        if (sinceRevision === null || sinceRevision <= 0) {
+        if (sinceRevision === null || sinceRevision <= (loaded?.revision ?? 0) || sinceRevision > runner.revision()) {
             return { kind: "baseline", revision: runner.revision(), snapshot: runner.snapshot() };
         }
         return { kind: "diff", diff: runner.diff(sinceRevision) };
     };
     return {
-        join: (userId, isNew) => runner.join(userId, isNew),
-        leave: (userId) => runner.leave(userId),
+        join(userId, isNew) {
+            runner.join(userId, knownPlayers.has(userId) ? false : isNew);
+            knownPlayers.add(userId);
+            runner.context().touch();
+            runner.commit();
+        },
+        hasPlayer: (userId) => knownPlayers.has(userId),
+        leave(userId) {
+            runner.leave(userId);
+            runner.commit();
+        },
         input: (userId, frame) => runner.input(userId, frame),
-        command: (userId, name, input) => runner.command(userId, name, input),
+        command(userId, name, input, operationId) {
+            const envelope = unwrapOpEnvelope(input);
+            if (envelope !== null) {
+                operationId ??= envelope.opId;
+                input = envelope.input;
+            }
+            const receipts = operations.get(userId) ?? [];
+            const inputJson = JSON.stringify(input) ?? "null";
+            const receipt = operationId === undefined ? undefined : receipts.find((entry) => entry.id === operationId);
+            if (receipt !== undefined) {
+                if (receipt.command !== name || receipt.input !== inputJson)
+                    return { status: "rejected", reason: "operation-conflict" };
+                if (receipt.outcome === "applied")
+                    return { status: "applied", state: runner.context() };
+                if (receipt.outcome === "rejected")
+                    return { status: "rejected", reason: receipt.reason };
+                return { status: "unknown-command" };
+            }
+            const before = runner.state();
+            let result;
+            try {
+                result = runner.command(userId, name, input);
+            }
+            catch (error) {
+                runner.context().restore(before);
+                throw error;
+            }
+            if (result.status !== "applied")
+                runner.context().restore(before);
+            if (operationId !== undefined) {
+                receipts.push({ id: operationId, command: name, input: inputJson, outcome: result.status,
+                    ...(result.status === "rejected" ? { reason: result.reason } : {}) });
+                operations.set(userId, receipts.slice(-historyLimit));
+                runner.context().touch();
+            }
+            runner.commit();
+            return result;
+        },
         tick(dt) {
             const revision = runner.tick(dt);
-            if (revision !== savedRevision) {
+            if (writing === null && (revision !== savedRevision || runner.context().version() !== savedVersion || runner.context().sim.tick() !== savedSimTick)) {
                 const at = clock();
                 if (saveIntervalMs <= 0 || at - lastSaveAt >= saveIntervalMs) {
                     lastSaveAt = at;
-                    persist();
+                    try {
+                        persist();
+                    }
+                    catch { /* Exposed by persistenceError and retried by the next save. */ }
                 }
             }
             return revision;
@@ -70,6 +207,7 @@ export function createHostedWorldSession(options) {
         revision: () => runner.revision(),
         members: () => runner.members(),
         save: persist,
+        persistenceError: () => saveFailure,
         runner: () => runner,
     };
 }
@@ -81,7 +219,7 @@ export async function createHostedWorldSessionAsync(options) {
         ...sessionOptions,
         store: {
             load: () => loaded,
-            save: (record) => { void store.save(record); },
+            save: (record) => store.save(record),
         },
     });
     return session;

package/dist/runtime/hostedWorldStore.d.ts

@@ -13,8 +13,8 @@ export interface HostedWorldStore {
     load(): Promise<HostedWorldRecord | null>;
     save(record: HostedWorldRecord): Promise<void>;
 }
-/** Synchronous store adapter retained for deterministic in-process tests. */
+/** Already-loaded store adapter: synchronous reads, with synchronous or asynchronous writes. */
 export interface SyncHostedWorldStore {
     load(): HostedWorldRecord | null;
-    save(record: HostedWorldRecord): void;
+    save(record: HostedWorldRecord): void | Promise<void>;
 }

package/dist/runtime/inputRecorder.d.ts

@@ -10,7 +10,7 @@ export interface InputRecorderState {
 }
 /** Tick-indexed input log: record per tick, look up the frame in force at any tick. */
 export interface InputRecorder {
-    /** Store the frame in force from `tick` onward. Recording the same tick twice replaces the earlier frame. */
+    /** Store held state from `tick` onward and presses on that tick only. Same-tick recordings merge press identities while replacing continuous state. */
     record(tick: number, frame: InputFrame): void;
     /** The frame in force at `tick`: the latest recorded frame whose tick is at most `tick`, or `null` before the first. */
     frameAt(tick: number): InputFrame | null;

package/dist/runtime/inputRecorder.js

@@ -2,6 +2,7 @@ function cloneFrame(frame) {
     return {
         held: [...frame.held],
         pointer: frame.pointer === null ? null : { ...frame.pointer },
+        ...(frame.presses === undefined ? {} : { presses: frame.presses.map(press => ({ ...press })) }),
         ...(frame.analog === undefined ? {} : { analog: frame.analog === null ? null : { ...frame.analog } }),
         ...(frame.tick === undefined ? {} : { tick: frame.tick }),
     };
@@ -14,6 +15,7 @@ function cloneFrame(frame) {
  */
 export function createInputRecorder() {
     let frames = [];
+    const continuousFrames = new WeakMap();
     function indexAtOrBefore(tick) {
         let lo = 0;
         let hi = frames.length - 1;
@@ -35,6 +37,13 @@ export function createInputRecorder() {
             const entry = { tick, frame: cloneFrame(frame) };
             const index = indexAtOrBefore(tick);
             if (index >= 0 && frames[index].tick === tick) {
+                const previous = frames[index].frame.presses;
+                if (previous !== undefined) {
+                    const presses = new Map(previous.map(press => [press.seq, press]));
+                    for (const press of entry.frame.presses ?? [])
+                        presses.set(press.seq, press);
+                    entry.frame.presses = [...presses.values()].map(press => ({ ...press }));
+                }
                 frames[index] = entry;
                 return;
             }
@@ -42,7 +51,18 @@ export function createInputRecorder() {
         },
         frameAt(tick) {
             const index = indexAtOrBefore(tick);
-            return index < 0 ? null : frames[index].frame;
+            if (index < 0)
+                return null;
+            const entry = frames[index];
+            if (entry.tick === tick || entry.frame.presses === undefined)
+                return entry.frame;
+            let heldFrame = continuousFrames.get(entry.frame);
+            if (heldFrame === undefined) {
+                const { presses: _presses, ...continuous } = entry.frame;
+                heldFrame = continuous;
+                continuousFrames.set(entry.frame, heldFrame);
+            }
+            return heldFrame;
         },
         frames: () => frames,
         lastTick: () => (frames.length === 0 ? -1 : frames[frames.length - 1].tick),

package/dist/runtime/inputSnapshot.d.ts

@@ -1,9 +1,17 @@
 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. */
+import { type HapticChannels } from "../input/haptics.js";
+/** One discrete press, identified across retransmitted live input frames. */
+export interface InputPress {
+    action: string;
+    seq: number;
+}
+/** One client's serializable held state and discrete edges for a simulation tick. */
 export interface InputFrame {
     held: readonly string[];
     pointer: PointerAxisState | null;
+    /** Discrete presses retained through release until the host accepts them. Each identity applies once, on its recorded simulation tick. */
+    presses?: readonly InputPress[];
     /** Analog per-action magnitudes (0..1) for actions driven by a continuous source (virtual joystick, gamepad stick); absent/null means every held action is fully pressed. */
     analog?: Readonly<Record<string, number>> | null;
     /** Simulation tick (`ctx.sim.tick()`) the frame was captured for; hosts and replay align inputs on it. Absent from senders that predate the fixed-step loop. */
@@ -16,8 +24,18 @@ export interface InputSnapshot {
         weak: number;
         ms: number;
     }): Promise<boolean>;
-    /** 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;
+    /**
+     * Continuous rumble channels for a local user (`engine`, `road`, `impact`, …): set levels each tick
+     * and the shell mixes them by priority onto that user's pad. Local only — never in a snapshot or on the wire.
+     */
+    haptics(userId: string): HapticChannels;
+    /** Replaces held state without notifying subscribers. Supplying `edges` buffers short presses until `beginStep`; `reset` discards the current owner's pending edges. Without `edges`, legacy publication-based edge detection is preserved. */
+    publish(held: readonly string[], edges?: {
+        pressed?: readonly string[];
+        reset?: boolean;
+    }): void;
+    /** Sample buffered input once before a simulation step. Zero-step render frames retain presses; subsequent steps retire the sampled edges. */
+    beginStep(): void;
     /** Replaces the normalized pointer-position state for this frame (#293). Same no-notify contract as `publish`. */
     publishPointer(state: PointerAxisState | null): void;
     /** Replaces the analog per-action magnitudes for this frame (#1370) — the virtual joystick's continuous vector, split into 0..1 values per movement action. `null` clears back to digital-only. Same no-notify contract as `publish`. */
@@ -25,7 +43,7 @@ export interface InputSnapshot {
     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[];
-    /** 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. */
+    /** True on the sampled simulation step containing a press; legacy publishers use the last two held sets. */
     justPressed(action: string): boolean;
     /** True only on the frame `action` transitions from down to up (#671); mirrors {@link justPressed}. */
     justReleased(action: string): boolean;