@series-inc/rundot-syncplay 5.25.0-beta.2 → 5.25.0-beta.4

package/dist/index.js

@@ -23,7 +23,8 @@ export { rewindDeterministicTargets, runDeterministicMovementCrowdSimulation, ru
 export { stepDeterministicCarry3D, stepDeterministicKcc3D } from './movement3d.js';
 export { applyDeterministicReciprocalAvoidance, cookDeterministicNavigationGraph, cookTilemapNavigationGraph, createDeterministicFlowField, findDeterministicPath, smoothDeterministicPath, stepDeterministicNavigationAgents } from './navigation.js';
 export { cookDeterministicNavmesh, cookImportedDeterministicNavmesh, findDeterministicNavmeshPath, findDeterministicNavmeshPointPath, locateDeterministicNavmeshPolygon, runDeterministicNavmeshStress, smoothDeterministicNavmeshPath, stepDeterministicNavmeshAgents, stepDeterministicNavmeshOffMeshTraversal } from './navmesh.js';
-export { createNetworkedSyncplayClient } from './networked-client.js';
+export { createNetworkedSyncplayClient, prepareNetworkedSyncplayTransport } from './networked-client.js';
+export { createSyncplayRunner } from './runner.js';
 export { fbm2D, hash2, hashUint32, valueNoise1D, valueNoise2D } from './noise.js';
 export { circleCastDeterministicPhysics2D, createDeterministicPhysicsWorld2D, nearestDeterministicPhysicsHit2D, queryDeterministicPhysicsAabb2D, queryDeterministicPhysicsShapeOverlap2D, raycastAllDeterministicPhysics2D, raycastDeterministicPhysics2D, stepDeterministicPhysicsWorld2D } from './physics2d.js';
 export { applyDeterministicImpulse3D, applyDeterministicImpulses3D, applyDeterministicWorldEdit3D, contactDetailsDeterministicPhysics3D, createDeterministicPhysicsWorld3D, createTrustedDeterministicPhysicsWorld3D, deriveInverseInertia, deterministicPhysicsBodyById3D, deterministicPhysicsCallback3D, overlapDeterministicPhysics3D, raycastDeterministicPhysics3D, raycastDeterministicPhysics3DDetailed, runDeterministicPhysics3DStress, setDeterministicBodyVelocity3D, shapeCastDeterministicPhysics3D, shapeCastDeterministicPhysics3DDetailed, stepDeterministicPhysicsWorld3D } from './physics3d.js';

package/dist/networked-client.d.ts

@@ -1,6 +1,6 @@
 import type { EncodedInput } from './input-authority.js';
 import { type DeterministicSessionRole } from './session-wire.js';
-import { type KinetixRuntime, type KinetixRuntimeIdentity } from './runtime-session.js';
+import { type KinetixRuntimeIdentity, type ProjectionCapableRuntime } from './runtime-session.js';
 import type { ReplayFile } from './types.js';
 import { type SyncplaySecretsClient } from './secret-client.js';
 import type { SyncplaySecretBrowserCrypto } from './secret-crypto.js';
@@ -21,11 +21,18 @@ export interface NetworkedClientTransport {
     onSecretMessage?(handler: (text: string) => void): void;
     readonly playerId?: string;
 }
-export type KinetixRuntimeFactory<State, Input, Checkpoint = unknown> = (identity: KinetixRuntimeIdentity, sessionConfigBytes: Uint8Array) => KinetixRuntime<State, Input, Checkpoint>;
-export interface NetworkedSyncplayClientOptions<State, Input, Checkpoint = unknown> {
+export type KinetixRuntimeFactory<State, Input, Checkpoint = unknown, Projection = State> = (identity: KinetixRuntimeIdentity, sessionConfigBytes: Uint8Array) => ProjectionCapableRuntime<State, Input, Checkpoint, Projection>;
+export interface NetworkedSyncplayClientOptions<State, Input, Checkpoint = unknown, Projection = State> {
     readonly transport: NetworkedClientTransport;
-    readonly runtimeFactory: KinetixRuntimeFactory<State, Input, Checkpoint>;
+    readonly runtimeFactory: KinetixRuntimeFactory<State, Input, Checkpoint, Projection>;
     readonly defaultInput: Input;
+    /**
+     * Enables a bounded queue of authority-confirmed presentation frames drained
+     * via {@link NetworkedSyncplayClient.drainConfirmedPresentationFrames}. Absent
+     * means no queue and preserves existing client cost. Must be a positive safe
+     * integer.
+     */
+    readonly confirmedPresentationBufferSize?: number;
     readonly snapshotBufferSize?: number;
     readonly checksumIntervalFrames?: number;
     /** This client's own input for a tick (game-defined). */
@@ -107,7 +114,29 @@ export interface NetworkedSyncplayClientNetStats {
     readonly maxRollbackDepth: number;
 }
 export type NetworkedSyncplaySlotPresence = 'human' | 'substituted' | 'empty' | 'unknown';
-export interface NetworkedSyncplayClient {
+export interface ConfirmedSyncplayPresentationFrame<Projection> {
+    readonly frame: number;
+    readonly projection: Readonly<Projection>;
+}
+export interface NetworkedSyncplaySessionDescriptor {
+    readonly slot: number;
+    readonly playerCount: number;
+    readonly seed: number;
+    readonly tickRateHz: number;
+    readonly hardToleranceTicks: number;
+    readonly role: DeterministicSessionRole;
+    readonly runtimeIdentity: KinetixRuntimeIdentity;
+    readonly sessionConfigBytes: Uint8Array;
+    readonly sessionConfigDigest: string;
+}
+export interface PreparedNetworkedSyncplayTransport {
+    readonly descriptor: NetworkedSyncplaySessionDescriptor;
+    readonly transport: NetworkedClientTransport;
+}
+export interface NetworkedSyncplayPreparationOptions {
+    readonly signal?: AbortSignal;
+}
+export interface NetworkedSyncplayClient<Projection = unknown> {
     readonly slot: number;
     /** 'player' (holds a slot) or 'spectator' (read-only follower, slot -1). From session-start. */
     readonly role: DeterministicSessionRole;
@@ -138,5 +167,21 @@ export interface NetworkedSyncplayClient {
     /** Confirmed-state checksum at `frame` (must be <= appliedThrough + 1). */
     confirmedStateChecksum(frame: number): string;
     exportReplay(): ReplayFile;
+    readonly currentFrame: number;
+    readonly renderAlpha: number;
+    readonly caughtUp: boolean;
+    getPresentationFrame(): Readonly<Projection>;
+    drainConfirmedPresentationFrames(): readonly ConfirmedSyncplayPresentationFrame<Projection>[];
+    beginPresentationCatchUp(): void;
+    dispose(): void;
 }
-export declare function createNetworkedSyncplayClient<State, Input, Checkpoint = unknown>(options: NetworkedSyncplayClientOptions<State, Input, Checkpoint>): NetworkedSyncplayClient;
+/**
+ * Attaches to the ordered transport, awaits and validates the first
+ * `session-start`, exposes an immutable descriptor with detached session-config
+ * bytes, buffers subsequent public messages (same 8,192-message ceiling as the
+ * SDK transport), awaits `prepare`, then returns a replaying transport for
+ * {@link createNetworkedSyncplayClient}. Rejects on abort, terminal
+ * session-close/error, duplicate handler attachment, or overflow.
+ */
+export declare function prepareNetworkedSyncplayTransport(transport: NetworkedClientTransport, prepare: (descriptor: NetworkedSyncplaySessionDescriptor, signal: AbortSignal) => Promise<void>, options?: NetworkedSyncplayPreparationOptions): Promise<PreparedNetworkedSyncplayTransport>;
+export declare function createNetworkedSyncplayClient<State, Input, Checkpoint = unknown, Projection = State>(options: NetworkedSyncplayClientOptions<State, Input, Checkpoint, Projection>): NetworkedSyncplayClient<Projection>;

package/dist/networked-client.js

@@ -39,6 +39,141 @@ function equalBytes(left, right) {
     }
     return true;
 }
+const MAX_RUNTIME_PREPARATION_MESSAGES = 8_192;
+function immutableDescriptor(message) {
+    return Object.freeze({
+        slot: message.slot,
+        playerCount: message.playerCount,
+        seed: message.seed,
+        tickRateHz: message.tickRateHz,
+        hardToleranceTicks: message.hardToleranceTicks,
+        role: message.role,
+        runtimeIdentity: Object.freeze({ ...message.runtimeIdentity }),
+        sessionConfigBytes: new Uint8Array(message.sessionConfigBytes),
+        sessionConfigDigest: message.sessionConfigDigest,
+    });
+}
+/**
+ * Attaches to the ordered transport, awaits and validates the first
+ * `session-start`, exposes an immutable descriptor with detached session-config
+ * bytes, buffers subsequent public messages (same 8,192-message ceiling as the
+ * SDK transport), awaits `prepare`, then returns a replaying transport for
+ * {@link createNetworkedSyncplayClient}. Rejects on abort, terminal
+ * session-close/error, duplicate handler attachment, or overflow.
+ */
+export async function prepareNetworkedSyncplayTransport(transport, prepare, options = {}) {
+    const localController = new AbortController();
+    const signal = options.signal ?? localController.signal;
+    const buffered = [];
+    let descriptorValue;
+    // A single gate for descriptor acquisition (resolve on session-start, reject on
+    // terminal/abort) keeps the descriptor→prepare handoff one microtask deep, so a
+    // caller that flushes a single microtask sees preparation already started.
+    let resolveDescriptor;
+    let rejectDescriptor;
+    const descriptorGate = new Promise((resolve, reject) => {
+        resolveDescriptor = resolve;
+        rejectDescriptor = reject;
+    });
+    void descriptorGate.catch(() => undefined);
+    let rejectTerminal;
+    const terminalPromise = new Promise((_resolve, reject) => {
+        rejectTerminal = reject;
+    });
+    void terminalPromise.catch(() => undefined);
+    let failure;
+    let preparationComplete = false;
+    let clientHandler;
+    // Tracks attachment independently of clientHandler: clientHandler is published
+    // only AFTER the replay drains (so re-entrant deliveries buffer in FIFO), but
+    // a second attach must still fail loud even if a replayed message threw
+    // mid-drain and left clientHandler unpublished.
+    let handlerAttached = false;
+    const fail = (error) => {
+        if (failure !== undefined || clientHandler !== undefined)
+            return;
+        failure = error;
+        if (!preparationComplete) {
+            rejectDescriptor(error);
+            rejectTerminal(error);
+        }
+    };
+    const abort = () => fail(new Error('SYNCPLAY_RUNTIME_PREPARATION_ABORTED'));
+    if (signal.aborted)
+        abort();
+    else
+        signal.addEventListener('abort', abort, { once: true });
+    transport.onMessage((text) => {
+        if (clientHandler !== undefined) {
+            clientHandler(text);
+            return;
+        }
+        if (failure !== undefined)
+            return;
+        if (buffered.length >= MAX_RUNTIME_PREPARATION_MESSAGES) {
+            fail(new Error('SYNCPLAY_RUNTIME_PREPARATION_BUFFER_OVERFLOW'));
+            return;
+        }
+        buffered.push(text);
+        const decoded = decodeDeterministicSessionMessage(text);
+        if (!decoded.ok)
+            return;
+        if (decoded.message.kind === 'error') {
+            fail(new Error(decoded.message.message));
+            return;
+        }
+        if (decoded.message.kind === 'close') {
+            fail(new Error(decoded.message.reason));
+            return;
+        }
+        if (decoded.message.kind !== 'session-start')
+            return;
+        if (descriptorValue !== undefined) {
+            fail(new Error('SYNCPLAY_RUNTIME_PREPARATION_SESSION_RESTARTED'));
+            return;
+        }
+        descriptorValue = immutableDescriptor(decoded.message);
+        resolveDescriptor(descriptorValue);
+    });
+    try {
+        const descriptor = await descriptorGate;
+        await Promise.race([prepare(descriptor, signal), terminalPromise]);
+        if (failure !== undefined)
+            throw failure;
+        preparationComplete = true;
+        const replayingTransport = {
+            send: (text) => transport.send(text),
+            onMessage: (handler) => {
+                if (handlerAttached) {
+                    throw new Error('SYNCPLAY_RUNTIME_PREPARATION_HANDLER_ALREADY_ATTACHED');
+                }
+                if (failure !== undefined)
+                    throw failure;
+                handlerAttached = true;
+                // Drain the buffer BEFORE publishing clientHandler: while it is still
+                // undefined, a message the client emits synchronously during replay
+                // loops back through the source onMessage into `buffered` (FIFO) instead
+                // of jumping ahead of the not-yet-replayed tail.
+                while (buffered.length > 0) {
+                    const text = buffered.shift();
+                    handler(text);
+                }
+                clientHandler = handler;
+            },
+            ...(transport.sendSecret === undefined
+                ? {}
+                : { sendSecret: (text) => transport.sendSecret(text) }),
+            ...(transport.onSecretMessage === undefined
+                ? {}
+                : { onSecretMessage: (handler) => transport.onSecretMessage(handler) }),
+            ...(transport.playerId === undefined ? {} : { playerId: transport.playerId }),
+        };
+        return Object.freeze({ descriptor, transport: replayingTransport });
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+    }
+}
 export function createNetworkedSyncplayClient(options) {
     const sessionMsgType = options.sessionMsgType ?? DEFAULT_MSG_TYPE;
     const maxPredictionTicks = options.maxPredictionTicks ?? DEFAULT_MAX_PREDICTION;
@@ -59,6 +194,7 @@ export function createNetworkedSyncplayClient(options) {
     const inputDelayMaxTicks = Math.max(options.inputDelay?.maxTicks ?? inputDelayMinTicks, inputDelayMinTicks);
     const wallClock = options.now ?? (() => Date.now());
     let session;
+    let activeRuntime;
     let slot = -1;
     let role = 'player';
     let seed = 0;
@@ -67,6 +203,17 @@ export function createNetworkedSyncplayClient(options) {
     let appliedThrough = -1;
     let rollbacks = 0;
     let maxRollbackDepth = 0;
+    let hardToleranceTicks = 0;
+    let latestAuthorityTick = -1;
+    let caughtUp = false;
+    let presentationCatchUpFloor;
+    let disposed = false;
+    const confirmedPresentationFrames = [];
+    const confirmedPresentationBufferSize = options.confirmedPresentationBufferSize;
+    if (confirmedPresentationBufferSize !== undefined
+        && (!Number.isSafeInteger(confirmedPresentationBufferSize) || confirmedPresentationBufferSize < 1)) {
+        throw new Error('SYNCPLAY_CONFIRMED_PROJECTION_BUFFER_INVALID');
+    }
     // ── G1/G2 pacing state (only advanced by pumpPaced; inert under raw pump) ──
     let tickRateHz = 0;
     let frameMs = 0;
@@ -111,10 +258,25 @@ export function createNetworkedSyncplayClient(options) {
     const outgoingTransferQueue = [];
     let donorTransferCounter = 0;
     let readyResolve;
-    const readyPromise = new Promise((resolve) => {
+    let readyReject;
+    const readyPromise = new Promise((resolve, reject) => {
         readyResolve = resolve;
+        readyReject = reject;
     });
+    void readyPromise.catch(() => undefined);
+    function assertActiveClient() {
+        if (disposed)
+            throw new Error('SYNCPLAY_CLIENT_DISPOSED');
+    }
+    function requireSession() {
+        assertActiveClient();
+        if (session === undefined)
+            throw new Error('SYNCPLAY_CLIENT_NOT_READY');
+        return session;
+    }
     options.transport.onMessage((text) => {
+        if (disposed)
+            return;
         const decoded = decodeDeterministicSessionMessage(text);
         if (!decoded.ok) {
             // The other frozen wire family (snapshot negotiation) rides the same
@@ -134,6 +296,15 @@ export function createNetworkedSyncplayClient(options) {
             role = message.role;
             seed = message.seed;
             playerCount = message.playerCount;
+            hardToleranceTicks = message.hardToleranceTicks;
+            latestAuthorityTick = -1;
+            caughtUp = false;
+            // A re-greet resets the tick space; a catch-up floor from the prior session
+            // is meaningless here (it would suppress `caughtUp` until the new session
+            // re-reached an old tick number). The runner's own recovery flag bridges
+            // event-silence across the re-hydrate.
+            presentationCatchUpFloor = undefined;
+            confirmedPresentationFrames.length = 0;
             lastConfirmedBySlot = Array.from({ length: playerCount }, () => null);
             confirmedPlayerPresence = unknownPresence();
             appliedThrough = -1;
@@ -168,6 +339,7 @@ export function createNetworkedSyncplayClient(options) {
                 });
             }
             session?.dispose();
+            activeRuntime = runtime;
             session = createSyncplaySession(runtime, {
                 playerCount,
                 defaultInput: options.defaultInput,
@@ -185,7 +357,7 @@ export function createNetworkedSyncplayClient(options) {
         }
         else if (message.kind === 'confirmed-input') {
             observeAuthorityTick(message.authorityTick, wallClock());
-            receiveConfirmedFrames(message.frames);
+            receiveConfirmedFrames(message.frames, message.authorityTick);
         }
         else if (message.kind === 'time-sync-pong') {
             handleTimeSyncPong(message.nonce, message.authorityTick);
@@ -399,6 +571,7 @@ export function createNetworkedSyncplayClient(options) {
         }
     }
     function pump() {
+        assertActiveClient();
         if (secretFailure)
             throw secretFailure;
         if (session === undefined) {
@@ -410,6 +583,7 @@ export function createNetworkedSyncplayClient(options) {
         }
     }
     function pumpPaced(nowMs) {
+        assertActiveClient();
         if (secretFailure)
             throw secretFailure;
         flushOutgoingTransfer();
@@ -447,36 +621,37 @@ export function createNetworkedSyncplayClient(options) {
         options.transport.send(encodeDeterministicSessionMessage({ kind: 'input', slot, tick, input, attempt: 0 }));
     }
     function confirmedStateChecksum(frame) {
-        const active = session;
-        if (active === undefined) {
-            return '';
-        }
+        const active = requireSession();
         active.restoreToFrame(frame);
         return active.getWireStateChecksum(frame);
     }
-    function receiveConfirmedFrames(frames) {
+    function receiveConfirmedFrames(frames, authorityTick) {
         const containsSecretCommands = frames.some((frame) => (frame.commands ?? []).some((command) => (command !== null && typeof command === 'object' && !Array.isArray(command)
             && typeof command.kind === 'string'
             && command.kind.startsWith('syncplay.'))));
         if (!containsSecretCommands && confirmationQueue === undefined) {
-            applyConfirmedFrames(frames);
+            applyConfirmedFrames(frames, authorityTick);
             return;
         }
         const prior = confirmationQueue ?? Promise.resolve();
         const next = prior.then(async () => {
             for (const frame of frames)
                 await secrets.acceptConfirmedCommands(frame.commands ?? []);
-            applyConfirmedFrames(frames);
+            applyConfirmedFrames(frames, authorityTick);
         });
         confirmationQueue = next;
-        void next.catch((error) => {
-            secretFailure = error instanceof Error ? error : new Error('signature-invalid');
+        void next.catch((caught) => {
+            secretFailure = caught instanceof Error ? caught : new Error('signature-invalid');
         }).finally(() => {
             if (confirmationQueue === next)
                 confirmationQueue = undefined;
         });
     }
-    function applyConfirmedFrames(frames) {
+    function applyConfirmedFrames(frames, authorityTick) {
+        const firstNewTick = frames.find((frame) => frame.tick > appliedThrough)?.tick;
+        const presentationWasLive = caughtUp;
+        const freshRoomFirstFrame = appliedThrough === -1 && firstNewTick === 0 && authorityTick === 0;
+        latestAuthorityTick = Math.max(latestAuthorityTick, authorityTick);
         for (const frame of frames) {
             if (frame.tick > appliedThrough) {
                 confirmed.set(frame.tick, {
@@ -496,25 +671,52 @@ export function createNetworkedSyncplayClient(options) {
             if (predFrame === undefined || canonicalStringify(simulationFrame) !== canonicalStringify(predFrame)) {
                 timeline[tick] = { inputs: confInputs.slice(), commands: confFrame.commands };
                 if (predictedThrough > tick) {
-                    // Rollback: we had already predicted this tick and the confirmed inputs differ.
                     rollbacks += 1;
                     maxRollbackDepth = Math.max(maxRollbackDepth, predictedThrough - tick);
                     simulate(tick);
                 }
                 else {
-                    // Confirm leads prediction (a lagging client): the authority confirmed a tick we had not
-                    // predicted yet. Extend the predicted head and apply the confirmed inputs so the session
-                    // actually advances through it — otherwise appliedThrough would outrun the simulated state.
                     predictedThrough = tick + 1;
                     simulate(tick);
                 }
             }
-            for (let s = 0; s < playerCount; s += 1) {
-                lastConfirmedBySlot[s] = confInputs[s];
+            for (let playerSlot = 0; playerSlot < playerCount; playerSlot += 1) {
+                lastConfirmedBySlot[playerSlot] = confInputs[playerSlot];
             }
             appliedThrough = tick;
             confirmedPlayerPresence = classifyPresence(confFrame);
+            const presentationEligible = presentationWasLive || (freshRoomFirstFrame && tick === 0);
+            if (presentationEligible
+                && confirmedPresentationBufferSize !== undefined && activeRuntime?.project !== undefined) {
+                // Bounded ring: drop the oldest when full rather than throw. A consumer
+                // that stalls (e.g. a backgrounded tab whose rAF-driven drain pauses
+                // while the socket keeps delivering) must shed the debt and stay at the
+                // live tail, not throw uncaught out of the transport dispatch and leave a
+                // permanent gap. A single post-live batch fits well under the bound.
+                while (confirmedPresentationFrames.length >= confirmedPresentationBufferSize) {
+                    confirmedPresentationFrames.shift();
+                }
+                const frame = tick + 1;
+                const selected = requireSession().peekSnapshot(frame);
+                const previous = requireSession().peekSnapshot(frame - 1);
+                if (selected === undefined)
+                    throw new Error('SYNCPLAY_CONFIRMED_PROJECTION_MISSING');
+                confirmedPresentationFrames.push(Object.freeze({
+                    frame,
+                    projection: activeRuntime.project(selected.checkpoint, previous?.checkpoint),
+                }));
+            }
         }
+        // `caughtUp` requires having actually observed an authority tick — a joiner
+        // that hydrates from a snapshot before any confirmed-input broadcast has
+        // latestAuthorityTick === -1 and is not yet at any real boundary.
+        const reachedAuthorityBoundary = appliedThrough >= 0 && latestAuthorityTick >= 0
+            && appliedThrough >= latestAuthorityTick - hardToleranceTicks;
+        if (presentationCatchUpFloor !== undefined
+            && reachedAuthorityBoundary && appliedThrough > presentationCatchUpFloor) {
+            presentationCatchUpFloor = undefined;
+        }
+        caughtUp = reachedAuthorityBoundary && presentationCatchUpFloor === undefined;
         autoReportCrossedCadences();
     }
     function unknownPresence() {
@@ -754,7 +956,7 @@ export function createNetworkedSyncplayClient(options) {
         lastAutoReportedTick = Math.max(lastAutoReportedTick, snapshot.tick);
         // Frames that arrived before hydration are buffered in `confirmed` — the
         // normal contiguous-apply drains the tail from here.
-        applyConfirmedFrames([]);
+        applyConfirmedFrames([], latestAuthorityTick);
     }
     return {
         get slot() {
@@ -788,12 +990,56 @@ export function createNetworkedSyncplayClient(options) {
             };
         },
         secrets,
+        get currentFrame() {
+            return requireSession().currentFrame;
+        },
+        get caughtUp() {
+            return session !== undefined && caughtUp;
+        },
+        get renderAlpha() {
+            requireSession();
+            return frameMs > 0 ? pacingAccumulatorMs / frameMs : 0;
+        },
+        getPresentationFrame() {
+            return requireSession().getPresentationFrame();
+        },
+        drainConfirmedPresentationFrames() {
+            requireSession();
+            const drained = confirmedPresentationFrames.splice(0, confirmedPresentationFrames.length);
+            return Object.freeze(drained);
+        },
+        beginPresentationCatchUp() {
+            assertActiveClient();
+            presentationCatchUpFloor = appliedThrough;
+            caughtUp = false;
+            confirmedPresentationFrames.length = 0;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            session?.dispose();
+            session = undefined;
+            activeRuntime = undefined;
+            caughtUp = false;
+            presentationCatchUpFloor = undefined;
+            latestAuthorityTick = -1;
+            confirmedPresentationFrames.length = 0;
+            outgoingTransferQueue.length = 0;
+            pendingPings.clear();
+            const error = new Error('SYNCPLAY_CLIENT_DISPOSED');
+            readyReject?.(error);
+            readyResolve = undefined;
+            readyReject = undefined;
+        },
         whenReady() {
+            assertActiveClient();
             return readyPromise;
         },
         pump,
         pumpPaced,
         reportChecksum() {
+            assertActiveClient();
             if (session === undefined || appliedThrough < 0) {
                 return;
             }
@@ -801,10 +1047,7 @@ export function createNetworkedSyncplayClient(options) {
         },
         confirmedStateChecksum,
         exportReplay() {
-            if (session === undefined) {
-                throw new Error('networked client has not started');
-            }
-            return session.exportReplay();
+            return requireSession().exportReplay();
         },
     };
 }

package/dist/node.d.ts

@@ -20,3 +20,4 @@ export type { SyncplaySecretAuthorityCrypto, SyncplaySecretBrowserCrypto } from
 export * from './ws-frame.js';
 export { assertCookedColliderIsRuntimeValid, cookConvexDecomposition, } from './collider-cooking.js';
 export type { ColliderCookOptions, ColliderSourceMesh, CookedCollider, CookedColliderHull, } from './collider-cooking.js';
+export { DevSyncplayAuthorityRoom } from './dev-authority-room.js';

package/dist/node.js

@@ -16,3 +16,6 @@ export * from './secret-authority.js';
 export { buildMerkleTree, bytesToHex, concatBytes, constantTimeEqual, createBrowserSyncplaySecretCrypto, hexToBytes, merkleLeafHash, merkleNodeHash, merkleProof, sha256Bytes, signedReceiptBytes, verifyHashChainReveal, verifyMerkleProof, verifySyncplaySignedReceipt, } from './secret-crypto.js';
 export * from './ws-frame.js';
 export { assertCookedColliderIsRuntimeValid, cookConvexDecomposition, } from './collider-cooking.js';
+// Dev-server deterministic room class (relocated from the game SDK). A game's
+// vite.config passes this to rundotMultiplayerPlugin({ deterministicRoomClass }).
+export { DevSyncplayAuthorityRoom } from './dev-authority-room.js';

package/dist/replay.d.ts

@@ -1,12 +1,13 @@
-import { type KinetixRuntime, type KinetixRuntimeIdentity } from '@series-inc/rundot-kinetix/runtime';
+import { type KinetixRuntimeIdentity } from '@series-inc/rundot-kinetix/runtime';
 import { type SyncplaySessionPolicy } from './sdk-session.js';
+import type { ProjectionCapableRuntime } from './runtime-session.js';
 import { type SyncplaySecretCommand } from './secret-protocol.js';
 import type { ReplayFile, ReplayVerificationResult } from './types.js';
-export type ReplayRuntimeFactory<State, Input, Checkpoint = unknown> = (identity: KinetixRuntimeIdentity, sessionConfigBytes: Uint8Array) => KinetixRuntime<State, Input, Checkpoint>;
-export interface ReplayVerificationConfig<State, Input, Checkpoint = unknown> {
+export type ReplayRuntimeFactory<State, Input, Checkpoint = unknown, Projection = State> = (identity: KinetixRuntimeIdentity, sessionConfigBytes: Uint8Array) => ProjectionCapableRuntime<State, Input, Checkpoint, Projection>;
+export interface ReplayVerificationConfig<State, Input, Checkpoint = unknown, Projection = State> {
     readonly replay: ReplayFile;
-    readonly runtimeFactory: ReplayRuntimeFactory<State, Input, Checkpoint>;
-    readonly policy: SyncplaySessionPolicy<State, Input, Checkpoint>;
+    readonly runtimeFactory: ReplayRuntimeFactory<State, Input, Checkpoint, Projection>;
+    readonly policy: SyncplaySessionPolicy<State, Input, Checkpoint, Projection>;
     readonly decodeInput?: (recordedInput: unknown, slot: number) => Input;
     readonly throwOnMismatch?: boolean;
     readonly expectedAuthorityId?: string;
@@ -15,6 +16,6 @@ export interface ReplayVerificationConfig<State, Input, Checkpoint = unknown> {
 export interface ReplayVerificationExecution<State> extends ReplayVerificationResult {
     readonly finalState: State;
 }
-export declare function verifyReplay<State, Input, Checkpoint = unknown>(config: ReplayVerificationConfig<State, Input, Checkpoint>): ReplayVerificationResult;
-export declare function executeReplay<State, Input, Checkpoint = unknown>(config: ReplayVerificationConfig<State, Input, Checkpoint>): ReplayVerificationExecution<State>;
+export declare function verifyReplay<State, Input, Checkpoint = unknown, Projection = State>(config: ReplayVerificationConfig<State, Input, Checkpoint, Projection>): ReplayVerificationResult;
+export declare function executeReplay<State, Input, Checkpoint = unknown, Projection = State>(config: ReplayVerificationConfig<State, Input, Checkpoint, Projection>): ReplayVerificationExecution<State>;
 export declare function assertReplayFileStructure(replay: ReplayFile): void;

package/dist/run-room-transport.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Reusable, production-shaped client surface for deterministic multiplayer.
+ *
+ * A game joins a deterministic room by code (or creates one) and gets back a
+ * {@link NetworkedClientTransport} — the exact socket-like surface the
+ * deterministic engine's `createNetworkedSyncplayClient` consumes. There is
+ * NO per-game server logic: the server-side deterministic room (built-in input
+ * authority) is generic, and this transport is a thin, opaque pass-through of the
+ * frozen `rdm-local-authority/v2` session envelope over the `rdm` room channel.
+ *
+ * The room's raw channel ({@link ServerRoom.sendRaw}/{@link ServerRoom.onRaw})
+ * carries the session envelope verbatim; the typed-message path would spread a
+ * raw string and corrupt it, which is why the raw channel exists.
+ */
+import type { NetworkedClientTransport } from './networked-client.js';
+import type { KinetixRuntimeIdentity } from './runtime-session.js';
+import type { MultiplayerApi, ServerPlayer } from '@series-inc/rundot-game-sdk/mp-client';
+/** Connection-health signal surfaced by {@link SyncplayRoomTransport.onConnectionEvent}. */
+export type SyncplayConnectionEvent = {
+    readonly kind: 'error';
+    readonly message: string;
+} | {
+    readonly kind: 'disconnected';
+} | {
+    readonly kind: 'reconnecting';
+};
+export interface SyncplayRoomOptions {
+    readonly maxPlayers?: number;
+    readonly runtimeIdentity: KinetixRuntimeIdentity;
+    readonly sessionConfigBytes: Uint8Array;
+    readonly sessionConfigDigest: string;
+}
+export interface SyncplayOccupancySnapshot {
+    readonly players: readonly ServerPlayer[];
+    readonly occupied: number;
+    readonly maxPlayers: number;
+    readonly full: boolean;
+    readonly locked: boolean;
+}
+export interface SyncplayRoomTransport extends NetworkedClientTransport {
+    /** The shareable room code (e.g. "HX9KWR"). */
+    readonly roomCode: string;
+    /** This client's player id, as assigned by the server on join. */
+    readonly playerId: string;
+    readonly occupancy: SyncplayOccupancySnapshot;
+    readonly isCreator: boolean;
+    /** Leave the deterministic room and close the underlying connection. */
+    close(): void;
+    /**
+     * Connection-health signal: socket errors, disconnects, and reconnect
+     * attempts. Without observing this, a mid-match socket drop is silent — the
+     * room layer no-ops sends while dead, so the engine would predict into a
+     * dead socket forever. Games should surface these to the player and/or tear
+     * the match down.
+     */
+    onConnectionEvent(handler: (event: SyncplayConnectionEvent) => void): void;
+    onOccupancyChange(handler: (snapshot: SyncplayOccupancySnapshot) => void): () => void;
+    setSeatingOpen(open: boolean): void;
+}
+/**
+ * Join an existing deterministic room by its 6-char code and return a transport
+ * ready to hand to `createNetworkedSyncplayClient`.
+ */
+export declare function joinSyncplayRoomByCode(api: MultiplayerApi, code: string): Promise<SyncplayRoomTransport>;
+/** Options for {@link quickMatchSyncplayRoom}. */
+export interface QuickMatchSyncplayOptions extends SyncplayRoomOptions {
+    /**
+     * Auto-inject a coarse `region` criterion (default true). See
+     * {@link quickMatchSyncplayRoom} for the semantics and the tradeoff.
+     */
+    readonly autoRegion?: boolean;
+}
+/**
+ * Quick-match into a deterministic room (M9): the platform's joinOrCreate
+ * matchmaking pools compatible players into an open room or creates a fresh
+ * one. Optional `criteria` narrow the pool (matched exactly by the platform).
+ * With drop-in defaults the match starts immediately; unfilled slots
+ * substitute the canonical null input, which a game can treat as
+ * "bot-controlled" deterministically (see SYNCPLAY.md — Bots & quick match).
+ *
+ * Region-aware by default (G6): a coarse `region` criterion ('na' | 'sa' |
+ * 'eu' | 'africa' | 'asia' | 'oceania', derived from the device timezone) is
+ * auto-injected so cross-ocean pairings — whose RTT forces constant deep
+ * rollback — don't happen by accident. An explicit `criteria.region` wins
+ * over the derived value, and an underivable region ('unknown') is never
+ * injected: pooling globally beats fragmenting into an 'unknown' bucket.
+ *
+ * Tradeoff: strict region pools can go thin for low-traffic games. Pass
+ * `{ autoRegion: false }` (or your own `region` value) to pool globally;
+ * cross-region fallback-after-timeout is future work.
+ */
+export declare function quickMatchSyncplayRoom(api: MultiplayerApi, options: QuickMatchSyncplayOptions, criteria?: Record<string, string | number>): Promise<SyncplayRoomTransport>;
+/**
+ * Create a new deterministic room and return a transport ready to hand to
+ * `createNetworkedSyncplayClient`. The server mints the room code; read it
+ * back from {@link SyncplayRoomTransport.roomCode} to share with peers.
+ * (Caller-chosen codes are not supported on create — when the platform grows
+ * that path, this signature gains a typed parameter rather than a dead one.)
+ */
+export declare function createSyncplayRoom(api: MultiplayerApi, options: SyncplayRoomOptions): Promise<SyncplayRoomTransport>;