@series-inc/rundot-syncplay 5.25.0-beta.3 → 5.25.0-beta.5

package/README.md

@@ -110,3 +110,102 @@ The core suite covers checkpoint ownership/release, frame-zero rollback, v2
 snapshot hydration, replay verification, authority persistence, latency/loss
 convergence, late join, spectators, bots, secrets, and a real Kinetix world
 driven through `createSyncplaySession`.
+
+## Unified session runner
+
+`createSyncplayRunner` owns the offline / co-op / networked lifecycle behind one
+runtime factory and one presentation contract, so a game does not re-implement
+create/join resolution, the local/network tick branch, bot filling, projection
+extraction, and stale-connection invalidation:
+
+```ts
+const runner = createSyncplayRunner({
+  runtimeFactory,
+  prepareNetworkRuntime: (descriptor, signal) => prepareLevelFromUgc(descriptor, signal),
+  defaultInput,
+  encodeInput,
+  decodeInput,
+  presentation: {
+    project: (frame) => frame,
+    interpolate: interpolateRenderState,
+    events: (frame) => frame.events,
+  },
+})
+runner.startOffline({ identity, sessionConfigBytes, playerCount: 2, botInputForTick })
+await runner.startNetworked(() => createSyncplayRoom(api.realtime, roomOptions))
+runner.applyInput(readInput())
+runner.update(deltaMs)
+render(runner.getRenderState(), runner.renderAlpha)
+```
+
+**Status** is exactly `offline | connecting | syncing | live | stopped | error`:
+
+- `connecting` covers the room-open promise.
+- `syncing` covers session-descriptor/asset preparation, reconnect, and catch-up.
+- `live` requires `client.caughtUp` plus at least one applied authority frame.
+- `offline` owns the local fixed-step accumulator and bot filling.
+- `error` carries connection, preparation, and offline-construction failures on
+  the runner snapshot (and the throw is rethrown to the caller).
+- `stop` aborts preparation, closes the transport, and disposes the active
+  client/session — idempotently.
+
+Presentation stays **predicted** for render motion, while side-effect events are
+delivered only from authority-confirmed frames received after the first live
+boundary. Initial and reconnect catch-up history is silent; a post-live
+authority-leading frame still emits its event exactly once. Interpolation is
+presentation-only and never feeds simulation. Starting a new mode always tears
+down the old one, and a stale async connection/preparation closes without
+replacing the current session.
+
+**Incremental adoption (mature games).** A game with its own stateful renderer,
+input model, and connection UI can swap only its lifecycle orchestration onto the
+runner without rewriting those layers:
+
+- Keep your own presentation singleton — use an identity `project: (frame) => frame`
+  and feed your renderer from the `subscribe` snapshot (`renderState`, `renderAlpha`)
+  instead of `getRenderState()`.
+- Supply `localInputForTick: (slot, frame) => Input` when your local input is a
+  per-tick pulse/edge that must be consumed and cleared each frame; the runner then
+  reads it (offline local slot and networked prediction) instead of the persistent
+  `applyInput(...)` value.
+- Drive a room badge from the snapshot's `ready`, `appliedThrough`, `predictedThrough`,
+  `localSlot`, and `status` — no reach into the underlying client (e.g. `appliedThrough < 0`
+  means "waiting for peers"; `predictedThrough - appliedThrough` is the catch-up depth).
+
+Direct `NetworkedSyncplayClient` users get the same projection surface:
+`getPresentationFrame()`, `renderAlpha`, `currentFrame`, `caughtUp`, and a
+bounded confirmed-frame queue via the optional `confirmedPresentationBufferSize`
+(absent = no queue, preserving existing cost) drained with
+`drainConfirmedPresentationFrames()`. Call `beginPresentationCatchUp()` from your
+transport's reconnect signal so replayed history never fills the queue.
+`prepareNetworkedSyncplayTransport(transport, prepare, { signal })` buffers the
+ordered `session-start`/history traffic (same 8,192-message ceiling as the SDK
+transport), exposes a frozen descriptor with `levelEntryId + digest + length`,
+awaits your async preparation, then replays every buffered message once.
+
+**Capacity and late-join budgets.** Snapshot transfer defaults are **256 KiB**
+chunks and a **4 MiB** total ceiling; the immutable level payload is fetched and
+verified separately and never rides a snapshot. `maxPredictionTicks` is a
+rollback/latency budget, not a player-count limit. 128 slots is the tested
+protocol/load ceiling, not a 60 Hz performance guarantee for an arbitrary game.
+
+## Supported correctness kit
+
+`@series-inc/rundot-syncplay/testing` exposes exactly six supported functions —
+no browser or runtime APIs leak through it:
+
+```ts
+import {
+  assertDeterministic,
+  assertLateJoinHydration,
+  assertReplayVerifies,
+  assertTwoClientConvergence,
+} from '@series-inc/rundot-syncplay/testing'
+```
+
+`assertDeterministic` and `assertReplayVerifies` run the straight-run /
+restore-resim / hydration / replay cert; `assertTwoClientConvergence` and
+`assertLateJoinHydration` run the **real** authority room and networked client
+over a deterministic simulated network (`createSimulatedSyncplayMatch`,
+`runSyncplaySynctest`). Failures name the phase, frame, and disagreeing
+checksums.

package/dist/browser.d.ts

@@ -19,7 +19,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';
@@ -58,7 +59,8 @@ export type { DeterministicFpsAimState, DeterministicFpsInput, DeterministicKccB
 export type { DeterministicKccBody3D, DeterministicKccCarrierPose3D, DeterministicKccCarryResult3D, DeterministicKccCarryState3D, DeterministicKccCollisionCandidate3D, DeterministicKccCollisionFilter3D, DeterministicKccExternalImpulse3D, DeterministicKccGeometry3D, DeterministicKccInput3D, DeterministicKccPhysicsImpulse3D, DeterministicKccProcessor3D, DeterministicKccStepResult3D, DeterministicKccWorld3D, DeterministicMovingPlatform3D, DeterministicSlope3D, DeterministicStep3D } from './movement3d.js';
 export type { CookedDeterministicNavigationGraph, DeterministicFlowField, DeterministicNavEdge, DeterministicNavigationAgent, DeterministicNavigationGraphSource, DeterministicNavigationStepOptions, DeterministicNavigationStepResult, DeterministicNavNode, DeterministicNavRegion, DeterministicPathQuery, DeterministicPathResult, DeterministicTilemapSource } from './navigation.js';
 export type { CookedDeterministicNavmesh, DeterministicNavmeshAgent, DeterministicNavmeshAgentStepResult, DeterministicNavmeshImportSource, DeterministicNavmeshLink, DeterministicNavmeshMovingAvoidanceObstacle, DeterministicNavmeshOffMeshTraversalState, DeterministicNavmeshOffMeshTraversalStep, DeterministicNavmeshPath, DeterministicNavmeshPoint, DeterministicNavmeshPolygon, DeterministicNavmeshSource } from './navmesh.js';
-export type { NetworkedClientTransport, NetworkedSyncplayClient, NetworkedSyncplayClientInputDelayOptions, NetworkedSyncplayClientNetStats, NetworkedSyncplayClientOptions, NetworkedSyncplayClientPacingOptions, NetworkedSyncplaySlotPresence } from './networked-client.js';
+export type { ConfirmedSyncplayPresentationFrame, KinetixRuntimeFactory, NetworkedClientTransport, NetworkedSyncplayClient, NetworkedSyncplayClientInputDelayOptions, NetworkedSyncplayClientNetStats, NetworkedSyncplayClientOptions, NetworkedSyncplayClientPacingOptions, NetworkedSyncplayPreparationOptions, NetworkedSyncplaySessionDescriptor, NetworkedSyncplaySlotPresence, PreparedNetworkedSyncplayTransport } from './networked-client.js';
+export type { SyncplayRunner, SyncplayRunnerConfig, SyncplayRunnerConnectionEvent, SyncplayRunnerOfflineOptions, SyncplayRunnerPresentation, SyncplayRunnerSnapshot, SyncplayRunnerStatus, SyncplayRunnerTransport } from './runner.js';
 export type { DeterministicBodyKind, DeterministicContactEvent2D, DeterministicContactEventType, DeterministicPhysicsAabbQuery2D, DeterministicPhysicsActivePair2D, DeterministicPhysicsBody2D, DeterministicPhysicsCircleCastQuery2D, DeterministicPhysicsConstraint2D, DeterministicPhysicsHit2D, DeterministicPhysicsQueryOptions2D, DeterministicPhysicsRaycastQuery2D, DeterministicPhysicsShape2D, DeterministicPhysicsShapeOverlapQuery2D, DeterministicPhysicsStepOptions2D, DeterministicPhysicsStepResult2D, DeterministicPhysicsWorld2D } from './physics2d.js';
 export type { DeterministicContactCacheEntry3D, DeterministicJointCacheEntry3D, DeterministicPhysicsActivePair3D, DeterministicPhysicsAxisLock3D, DeterministicPhysicsBody3D, DeterministicPhysicsCallbackMask3D, DeterministicPhysicsCompoundChild3D, DeterministicPhysicsCompoundChildShape3D, DeterministicPhysicsConstraint3D, DeterministicPhysicsContactDetail3D, DeterministicPhysicsContactEvent3D, DeterministicPhysicsDetailedHit3D, DeterministicPhysicsHit3D, DeterministicPhysicsHullShape3D, DeterministicPhysicsImpulseApplication3D, DeterministicPhysicsOverlapQuery3D, DeterministicPhysicsPrimitiveShape3D, DeterministicPhysicsQuaternion3D, DeterministicPhysicsQueryOptions3D, DeterministicPhysicsRaycastQuery3D, DeterministicPhysicsScheduledQuery3D, DeterministicPhysicsShape3D, DeterministicPhysicsShapeCastQuery3D, DeterministicPhysicsStepResult3D, DeterministicPhysicsVec3, DeterministicPhysicsWorld3D, DeterministicPhysicsWorldEdit3D } from './physics3d.js';
 export type { DeterministicVoxelChunk3D, DeterministicVoxelCompoundShape3D } from './physics3d-voxel.js';
@@ -87,3 +89,5 @@ export { deriveCoarseRegion, detectCoarseRegion } from './coarse-region.js';
 export type { CoarseRegion } from './coarse-region.js';
 export { WsMultiplayerApi } from '@series-inc/rundot-game-sdk/mp-client';
 export type { MultiplayerApi, JoinTicketRequest } from '@series-inc/rundot-game-sdk/mp-client';
+export { openSyncplayBrowserRoom, resolveSyncplayBrowserIntent, shareSyncplayRoom, } from './browserSession.js';
+export type { OpenSyncplayBrowserRoomOptions, OpenSyncplayBrowserRoomResult, ResolveSyncplayBrowserIntentOptions, SyncplayBrowserApi, SyncplayBrowserIntent, } from './browserSession.js';

package/dist/browser.js

@@ -20,7 +20,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';
@@ -48,3 +49,6 @@ export { createSyncplaySecretEventReader, createSyncplaySecretsClient } from './
 export * from './run-room-transport.js';
 export { deriveCoarseRegion, detectCoarseRegion } from './coarse-region.js';
 export { WsMultiplayerApi } from '@series-inc/rundot-game-sdk/mp-client';
+// Browser launch-intent / room-open / share composition over the RUN game API
+// (RundotGameAPI comes from the SDK — syncplay may depend on the SDK).
+export { openSyncplayBrowserRoom, resolveSyncplayBrowserIntent, shareSyncplayRoom, } from './browserSession.js';

package/dist/browserSession.d.ts

@@ -0,0 +1,44 @@
+import type { RundotGameAPI } from '@series-inc/rundot-game-sdk/api';
+import { type SyncplayRoomOptions, type SyncplayRoomTransport } from './run-room-transport.js';
+export type SyncplayBrowserIntent = {
+    readonly kind: 'offline';
+} | {
+    readonly kind: 'create';
+} | {
+    readonly kind: 'join';
+    readonly roomCode: string;
+} | {
+    readonly kind: 'quick-match';
+};
+export type SyncplayBrowserApi = Pick<RundotGameAPI, 'app' | 'accessGate' | 'social' | 'realtime'>;
+export interface ResolveSyncplayBrowserIntentOptions {
+    readonly override?: SyncplayBrowserIntent;
+    readonly search?: string;
+    readonly maxWaitMs?: number;
+}
+export interface OpenSyncplayBrowserRoomOptions extends ResolveSyncplayBrowserIntentOptions {
+    readonly quickMatch?: {
+        readonly autoRegion?: boolean;
+        readonly criteria?: Record<string, string | number>;
+    };
+}
+export type OpenSyncplayBrowserRoomResult = {
+    readonly kind: 'offline';
+    readonly intent: {
+        readonly kind: 'offline';
+    };
+} | {
+    readonly kind: 'sign-in-required';
+    readonly intent: Exclude<SyncplayBrowserIntent, {
+        readonly kind: 'offline';
+    }>;
+} | {
+    readonly kind: 'connected';
+    readonly intent: Exclude<SyncplayBrowserIntent, {
+        readonly kind: 'offline';
+    }>;
+    readonly transport: SyncplayRoomTransport;
+};
+export declare function resolveSyncplayBrowserIntent(api: SyncplayBrowserApi, options?: ResolveSyncplayBrowserIntentOptions): Promise<SyncplayBrowserIntent>;
+export declare function openSyncplayBrowserRoom(api: SyncplayBrowserApi, roomOptions: SyncplayRoomOptions, options?: OpenSyncplayBrowserRoomOptions): Promise<OpenSyncplayBrowserRoomResult>;
+export declare function shareSyncplayRoom(api: Pick<RundotGameAPI, 'social'>, roomCode: string): ReturnType<RundotGameAPI['social']['shareLinkAsync']>;

package/dist/browserSession.js

@@ -0,0 +1,70 @@
+import { createSyncplayRoom, joinSyncplayRoomByCode, quickMatchSyncplayRoom, } from './run-room-transport.js';
+function normalizeRoomCode(value) {
+    const code = value.trim().toUpperCase();
+    if (!/^[A-Z0-9]{6}$/u.test(code))
+        throw new Error('SYNCPLAY_ROOM_CODE_INVALID');
+    return code;
+}
+// `lenient` degrades a malformed room code (ignore it, fall through to offline)
+// instead of throwing a boot-crash out of intent resolution. It is used for
+// EVERY external channel — the raw URL query AND the RUN launch intent, whose
+// `share`/`deeplink` kinds carry share-link and OS-deep-link params an attacker
+// can craft. Only the game's explicit UI `override` is trusted and stays strict
+// (a bad code there is a programming error worth surfacing).
+function intentFromParams(params, lenient = false) {
+    if (params.room !== undefined) {
+        const code = params.room.trim().toUpperCase();
+        if (/^[A-Z0-9]{6}$/u.test(code))
+            return { kind: 'join', roomCode: code };
+        if (!lenient)
+            throw new Error('SYNCPLAY_ROOM_CODE_INVALID');
+        // lenient: ignore the malformed code and fall through to the other params
+    }
+    if (params.host === '1')
+        return { kind: 'create' };
+    if (params.quickMatch === '1')
+        return { kind: 'quick-match' };
+    return undefined;
+}
+function paramsFromSearch(search) {
+    const params = new URLSearchParams(search);
+    return Object.fromEntries([...params.entries()]);
+}
+function normalizeIntent(intent) {
+    return intent.kind === 'join'
+        ? { kind: 'join', roomCode: normalizeRoomCode(intent.roomCode) }
+        : intent;
+}
+export async function resolveSyncplayBrowserIntent(api, options = {}) {
+    if (options.override !== undefined)
+        return normalizeIntent(options.override);
+    const launch = await api.app.resolveLaunchIntent(options.maxWaitMs === undefined ? undefined : { maxWaitMs: options.maxWaitMs });
+    if (launch.kind !== 'timed_out') {
+        const launchIntent = intentFromParams(launch.params, true);
+        if (launchIntent !== undefined)
+            return launchIntent;
+    }
+    const search = options.search ?? (typeof globalThis.location === 'object' ? globalThis.location.search : '');
+    return intentFromParams(paramsFromSearch(search), true) ?? { kind: 'offline' };
+}
+export async function openSyncplayBrowserRoom(api, roomOptions, options = {}) {
+    const intent = await resolveSyncplayBrowserIntent(api, options);
+    if (intent.kind === 'offline')
+        return { kind: 'offline', intent };
+    if (api.accessGate.isAnonymous())
+        return { kind: 'sign-in-required', intent };
+    let transport;
+    if (intent.kind === 'join') {
+        transport = await joinSyncplayRoomByCode(api.realtime, intent.roomCode);
+    }
+    else if (intent.kind === 'create') {
+        transport = await createSyncplayRoom(api.realtime, roomOptions);
+    }
+    else {
+        transport = await quickMatchSyncplayRoom(api.realtime, { ...roomOptions, autoRegion: options.quickMatch?.autoRegion }, options.quickMatch?.criteria);
+    }
+    return { kind: 'connected', intent, transport };
+}
+export async function shareSyncplayRoom(api, roomCode) {
+    return api.social.shareLinkAsync({ shareParams: { room: normalizeRoomCode(roomCode) } });
+}

package/dist/index.d.ts

@@ -22,7 +22,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';
@@ -70,7 +71,8 @@ export type { DeterministicFpsAimState, DeterministicFpsInput, DeterministicKccB
 export type { DeterministicKccBody3D, DeterministicKccCarrierPose3D, DeterministicKccCarryResult3D, DeterministicKccCarryState3D, DeterministicKccCollisionCandidate3D, DeterministicKccCollisionFilter3D, DeterministicKccExternalImpulse3D, DeterministicKccGeometry3D, DeterministicKccInput3D, DeterministicKccPhysicsImpulse3D, DeterministicKccProcessor3D, DeterministicKccStepResult3D, DeterministicKccWorld3D, DeterministicMovingPlatform3D, DeterministicSlope3D, DeterministicStep3D } from './movement3d.js';
 export type { CookedDeterministicNavigationGraph, DeterministicFlowField, DeterministicNavEdge, DeterministicNavigationAgent, DeterministicNavigationGraphSource, DeterministicNavigationStepOptions, DeterministicNavigationStepResult, DeterministicNavNode, DeterministicNavRegion, DeterministicPathQuery, DeterministicPathResult, DeterministicTilemapSource } from './navigation.js';
 export type { CookedDeterministicNavmesh, DeterministicNavmeshAgent, DeterministicNavmeshAgentStepResult, DeterministicNavmeshImportSource, DeterministicNavmeshLink, DeterministicNavmeshMovingAvoidanceObstacle, DeterministicNavmeshOffMeshTraversalState, DeterministicNavmeshOffMeshTraversalStep, DeterministicNavmeshPath, DeterministicNavmeshPoint, DeterministicNavmeshPolygon, DeterministicNavmeshSource } from './navmesh.js';
-export type { NetworkedClientTransport, NetworkedSyncplayClient, NetworkedSyncplayClientInputDelayOptions, NetworkedSyncplayClientNetStats, NetworkedSyncplayClientOptions, NetworkedSyncplayClientPacingOptions } from './networked-client.js';
+export type { ConfirmedSyncplayPresentationFrame, KinetixRuntimeFactory, NetworkedClientTransport, NetworkedSyncplayClient, NetworkedSyncplayClientInputDelayOptions, NetworkedSyncplayClientNetStats, NetworkedSyncplayClientOptions, NetworkedSyncplayClientPacingOptions, NetworkedSyncplayPreparationOptions, NetworkedSyncplaySessionDescriptor, PreparedNetworkedSyncplayTransport } from './networked-client.js';
+export type { SyncplayRunner, SyncplayRunnerConfig, SyncplayRunnerConnectionEvent, SyncplayRunnerOfflineOptions, SyncplayRunnerPresentation, SyncplayRunnerSnapshot, SyncplayRunnerStatus, SyncplayRunnerTransport } from './runner.js';
 export type { DeterministicBodyKind, DeterministicContactEvent2D, DeterministicContactEventType, DeterministicPhysicsAabbQuery2D, DeterministicPhysicsBody2D, DeterministicPhysicsCircleCastQuery2D, DeterministicPhysicsConstraint2D, DeterministicPhysicsHit2D, DeterministicPhysicsQueryOptions2D, DeterministicPhysicsRaycastQuery2D, DeterministicPhysicsShape2D, DeterministicPhysicsShapeOverlapQuery2D, DeterministicPhysicsStepOptions2D, DeterministicPhysicsStepResult2D, DeterministicPhysicsWorld2D } from './physics2d.js';
 export type { DeterministicContactCacheEntry3D, DeterministicJointCacheEntry3D, DeterministicPhysicsActivePair3D, DeterministicPhysicsAxisLock3D, DeterministicPhysicsBody3D, DeterministicPhysicsCallbackMask3D, DeterministicPhysicsCompoundChild3D, DeterministicPhysicsCompoundChildShape3D, DeterministicPhysicsConstraint3D, DeterministicPhysicsContactDetail3D, DeterministicPhysicsContactEvent3D, DeterministicPhysicsDetailedHit3D, DeterministicPhysicsHit3D, DeterministicPhysicsHullShape3D, DeterministicPhysicsImpulseApplication3D, DeterministicPhysicsOverlapQuery3D, DeterministicPhysicsPrimitiveShape3D, DeterministicPhysicsQuaternion3D, DeterministicPhysicsQueryOptions3D, DeterministicPhysicsRaycastQuery3D, DeterministicPhysicsScheduledQuery3D, DeterministicPhysicsShape3D, DeterministicPhysicsShapeCastQuery3D, DeterministicPhysicsStepResult3D, DeterministicPhysicsVec3, DeterministicPhysicsWorld3D, DeterministicPhysicsWorldEdit3D } from './physics3d.js';
 export type { DeterministicVoxelChunk3D, DeterministicVoxelCompoundShape3D } from './physics3d-voxel.js';

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>;