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

package/README.md

@@ -110,3 +110,87 @@ 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.
+
+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';
@@ -82,3 +84,10 @@ export { createSyncplaySecretEventReader, createSyncplaySecretsClient } from './
 export type { SyncplaySecretSystemDefinition, SyncplaySecretSystemsConfig } from './secret-config.js';
 export type { SyncplayOwnedSecretToken, SyncplaySecretCommand, SyncplaySecretErrorCode, SyncplaySecretPrivateMessage, SyncplaySignedReceipt } from './secret-protocol.js';
 export type { SyncplayChoiceClient, SyncplayChoiceResolvedEvent, SyncplayCollectionClient, SyncplayCollectionRevealedEvent, SyncplayOwnedSecret, SyncplayRandomClient, SyncplayRandomDrawnEvent, SyncplayRoleClient, SyncplayRoleRevealedEvent, SyncplaySecretEventReader, SyncplaySecretsClient } from './secret-client.js';
+export * from './run-room-transport.js';
+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';
@@ -42,3 +43,12 @@ export { syncplaySecretConfigHash, syncplaySecretLimits, validateSyncplaySecretS
 export { decodeSyncplaySecretPrivateMessage, isSyncplaySecretCommand, syncplaySecretProtocol } from './secret-protocol.js';
 export { createBrowserSyncplaySecretCrypto, verifySyncplaySignedReceipt } from './secret-crypto.js';
 export { createSyncplaySecretEventReader, createSyncplaySecretsClient } from './secret-client.js';
+// RUN-platform multiplayer glue (relocated from the game SDK — see the dep
+// inversion). The room client/transport + coarse-region matchmaking helpers a
+// game hands to `createNetworkedSyncplayClient`.
+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/coarse-region.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Coarse geographic region derived from the device's IANA timezone (G6:
+ * region-aware quick-match). Matchmaking pools pair on strict criteria
+ * equality, so a `region` criterion IS a region-aware pool key — no server
+ * schema change. Deliberately coarse (continent-scale): fine-grained buckets
+ * fragment thin player pools, and the goal is only to avoid cross-ocean
+ * pairings whose RTT forces constant deep rollback.
+ *
+ * Pure timezone-name mapping: no network calls, no clock reads.
+ */
+export type CoarseRegion = 'na' | 'sa' | 'eu' | 'africa' | 'asia' | 'oceania' | 'unknown';
+/** Pure mapping from an IANA timezone name to a coarse region. */
+export declare function deriveCoarseRegion(timeZone: string): CoarseRegion;
+/**
+ * Coarse region of THIS device, from `Intl.DateTimeFormat` timezone
+ * resolution. 'unknown' when the runtime resolves no zone (or an
+ * unclassifiable one like Etc/UTC) — callers should then skip region
+ * tagging rather than pool players into an 'unknown' bucket.
+ */
+export declare function detectCoarseRegion(): CoarseRegion;

package/dist/coarse-region.js

@@ -0,0 +1,87 @@
+/**
+ * Coarse geographic region derived from the device's IANA timezone (G6:
+ * region-aware quick-match). Matchmaking pools pair on strict criteria
+ * equality, so a `region` criterion IS a region-aware pool key — no server
+ * schema change. Deliberately coarse (continent-scale): fine-grained buckets
+ * fragment thin player pools, and the goal is only to avoid cross-ocean
+ * pairings whose RTT forces constant deep rollback.
+ *
+ * Pure timezone-name mapping: no network calls, no clock reads.
+ */
+/**
+ * America/* zones that are South America. Everything else under America/
+ * (including Central America and the Caribbean) stays 'na' — coarse on
+ * purpose. Covers the second path segment, so both `America/Sao_Paulo` and
+ * `America/Argentina/Buenos_Aires` resolve via 'Sao_Paulo' / 'Argentina'.
+ */
+const SOUTH_AMERICA_SEGMENTS = new Set([
+    'Araguaina',
+    'Argentina',
+    'Asuncion',
+    'Bahia',
+    'Belem',
+    'Boa_Vista',
+    'Bogota',
+    'Buenos_Aires',
+    'Campo_Grande',
+    'Catamarca',
+    'Cayenne',
+    'Cordoba',
+    'Cuiaba',
+    'Eirunepe',
+    'Fortaleza',
+    'Guayaquil',
+    'Guyana',
+    'Jujuy',
+    'La_Paz',
+    'Lima',
+    'Maceio',
+    'Manaus',
+    'Mendoza',
+    'Montevideo',
+    'Noronha',
+    'Paramaribo',
+    'Porto_Velho',
+    'Punta_Arenas',
+    'Recife',
+    'Rio_Branco',
+    'Rosario',
+    'Santarem',
+    'Santiago',
+    'Sao_Paulo',
+]);
+const AREA_REGIONS = {
+    Africa: 'africa',
+    // Arctic/Longyearbyen is the area's only zone (Svalbard, Norway).
+    Arctic: 'eu',
+    Asia: 'asia',
+    // Mostly Europe-adjacent islands (Azores, Canary, Reykjavik, Faroe...).
+    Atlantic: 'eu',
+    Australia: 'oceania',
+    Europe: 'eu',
+    // Mostly African-coast islands (Mauritius, Reunion, Antananarivo...).
+    Indian: 'africa',
+    Pacific: 'oceania',
+};
+/** Pure mapping from an IANA timezone name to a coarse region. */
+export function deriveCoarseRegion(timeZone) {
+    const [area, subArea] = timeZone.split('/');
+    if (area === 'America' && subArea !== undefined) {
+        return SOUTH_AMERICA_SEGMENTS.has(subArea) ? 'sa' : 'na';
+    }
+    return AREA_REGIONS[area] ?? 'unknown';
+}
+/**
+ * Coarse region of THIS device, from `Intl.DateTimeFormat` timezone
+ * resolution. 'unknown' when the runtime resolves no zone (or an
+ * unclassifiable one like Etc/UTC) — callers should then skip region
+ * tagging rather than pool players into an 'unknown' bucket.
+ */
+export function detectCoarseRegion() {
+    try {
+        return deriveCoarseRegion(Intl.DateTimeFormat().resolvedOptions().timeZone);
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/dev-authority-room.d.ts

@@ -0,0 +1,14 @@
+import type { Logger, RoomProtocol } from '@series-inc/rundot-game-sdk/mp-server';
+interface DevSyncplayRoomContext {
+    protocol: RoomProtocol;
+    roomId: string;
+    config: Readonly<Record<string, unknown>>;
+    log: Logger;
+}
+export declare class DevSyncplayAuthorityRoom {
+    private readonly players;
+    private readonly room;
+    private tickTimer;
+    constructor(ctx: DevSyncplayRoomContext);
+}
+export {};

package/dist/dev-authority-room.js

@@ -0,0 +1,227 @@
+import { createDeterministicAuthorityRoom, } from './authority-room.js';
+import { SYSTEM_MSG_RECONNECTED } from '@series-inc/rundot-game-sdk/mp-server';
+import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, sign } from 'node:crypto';
+import { validateSyncplaySecretSystemsConfig } from './secret-config.js';
+import { assertKinetixRuntimeIdentity, kinetixSessionConfigDigest, } from '@series-inc/rundot-kinetix/runtime';
+/**
+ * Built-in deterministic (Syncplay) room for the dev sidecar — the playground
+ * counterpart of mp-room-server's SyncplayAuthorityGameRoom.
+ *
+ * When a rooms-config room declares `deterministic: true`, the sidecar
+ * instantiates this instead of loading the creator's GameRoom file: syncplay games
+ * have NO per-game server code — the engine's input authority orders/confirms
+ * inputs and never runs the sim. Clients speak the `rdm-local-authority/v2`
+ * session protocol under msgType `rdm`: `session-start` (unicast on join),
+ * `input` (client→server), `confirmed-input` (broadcast each authority tick).
+ *
+ * Unlike mp-room-server (whose worker harness drives `handleTick`), the sidecar
+ * has no tick driver, so this room owns its own interval at `tickRateHz`,
+ * started on create and cleared on dispose.
+ */
+const SESSION_MSG_TYPE = 'rdm';
+const SECRET_MSG_TYPE = 'rdm-secret';
+const DEFAULT_HARD_TOLERANCE_TICKS = 6;
+const DEFAULT_REDUNDANCY_WINDOW_TICKS = 8;
+const DEFAULT_TICK_RATE_HZ = 30;
+const DEFAULT_MAX_PLAYERS = 2;
+export class DevSyncplayAuthorityRoom {
+    players = new Map();
+    room;
+    tickTimer = null;
+    constructor(ctx) {
+        const config = ctx.config;
+        const maxPlayers = readPositiveInt(config.maxPlayers, DEFAULT_MAX_PLAYERS);
+        const playerCount = readPositiveInt(config.playerCount, maxPlayers);
+        const tickRateHz = readPositiveInt(config.tickRateHz, DEFAULT_TICK_RATE_HZ);
+        const deterministic = isRecord(config.deterministic) ? config.deterministic : undefined;
+        const runtime = parseRuntimeMetadata(config.syncplayRuntime);
+        const secretConfig = deterministic?.secrets === undefined
+            ? undefined
+            : validateSyncplaySecretSystemsConfig(deterministic.secrets, playerCount);
+        const secretCrypto = secretConfig === undefined ? undefined : createEphemeralSecretCrypto();
+        // The server owns the seed: derive it deterministically from the room id so
+        // every client of this room receives the same seed (same scheme as prod).
+        const seed = deriveSeed(ctx.roomId);
+        this.room = createDeterministicAuthorityRoom({
+            broadcast: (msgType, payload) => ctx.protocol.broadcast(msgType, payload),
+            sendTo: (playerId, msgType, payload) => ctx.protocol.sendTo(playerId, msgType, payload),
+        }, {
+            playerCount,
+            seed,
+            // The engine accepts hardToleranceTicks >= 0 (0 = confirm immediately); honor an explicit 0.
+            hardToleranceTicks: readNonNegativeInt(config.hardToleranceTicks, DEFAULT_HARD_TOLERANCE_TICKS),
+            tickRateHz,
+            runtimeIdentity: runtime.runtimeIdentity,
+            sessionConfigBytes: runtime.sessionConfigBytes,
+            sessionConfigDigest: runtime.sessionConfigDigest,
+            redundancyWindowTicks: readPositiveInt(config.redundancyWindowTicks, DEFAULT_REDUNDANCY_WINDOW_TICKS),
+            // Game-agnostic no-op input: the authority substitutes canonical null for
+            // a slot with no prior input; the client maps null to the game's default.
+            neutralInput: null,
+            sessionMsgType: SESSION_MSG_TYPE,
+            ...(secretConfig === undefined
+                ? {}
+                : {
+                    authorityId: ctx.roomId,
+                    secrets: secretConfig,
+                    secretCrypto,
+                    secretMsgType: SECRET_MSG_TYPE,
+                }),
+            ...(config.waitForFullRoom === true ? { waitForFullRoom: true } : {}),
+            ...(typeof config.historyRetentionTicks === 'number'
+                ? { historyRetentionTicks: config.historyRetentionTicks }
+                : {}),
+            // Snapshot late-join (M5.5) knobs — same names as prod (mp-room-server).
+            ...(typeof config.snapshotCadenceTicks === 'number'
+                ? { snapshotCadenceTicks: config.snapshotCadenceTicks }
+                : {}),
+            ...(typeof config.transferTimeoutTicks === 'number'
+                ? { transferTimeoutTicks: config.transferTimeoutTicks }
+                : {}),
+            ...(typeof config.maxSnapshotBytes === 'number'
+                ? { maxSnapshotBytes: config.maxSnapshotBytes }
+                : {}),
+            // Detection only, never enforcement — surface it to the dev console.
+            onDesync: (info) => {
+                ctx.log.warn('deterministic room desync detected', { roomId: ctx.roomId, ...info });
+            },
+            onSnapshotEvent: (event) => {
+                if (event.kind === 'rejected') {
+                    ctx.log.warn('deterministic room snapshot transfer rejected', { roomId: ctx.roomId, ...event });
+                }
+            },
+        });
+        ctx.protocol.handleCreate = async () => {
+            const intervalMs = Math.max(1, Math.round(1000 / tickRateHz));
+            this.tickTimer = setInterval(() => this.room.onTick(), intervalMs);
+            // Never hold the vite dev process open on our account.
+            this.tickTimer.unref?.();
+        };
+        ctx.protocol.handleRestore = async () => { };
+        ctx.protocol.handleDispose = async () => {
+            if (this.tickTimer !== null) {
+                clearInterval(this.tickTimer);
+                this.tickTimer = null;
+            }
+        };
+        ctx.protocol.handleJoin = async (data) => {
+            const result = this.room.onPlayerJoin(data.id);
+            if (!result.accepted) {
+                return { accepted: false, reason: result.reason ?? 'join-rejected' };
+            }
+            const player = {
+                id: data.id,
+                username: data.username,
+                avatarUrl: data.avatarUrl ?? null,
+                joinedAt: Date.now(),
+                connected: true,
+            };
+            this.players.set(data.id, player);
+            return { accepted: true, player };
+        };
+        ctx.protocol.handleMessage = async (playerId, msgType, data) => {
+            // Grace-window socket reattach (dev-server reattach): refill any confirmed
+            // frames missed while offline. Idempotent — clients dedupe applied ticks.
+            if (msgType === SYSTEM_MSG_RECONNECTED) {
+                this.room.onPlayerReconnected(playerId);
+                return;
+            }
+            if (msgType === SECRET_MSG_TYPE) {
+                const envelope = typeof data === 'string' ? data : JSON.stringify(data);
+                this.room.onPlayerSecretMessage(playerId, envelope);
+                return;
+            }
+            if (msgType !== SESSION_MSG_TYPE)
+                return;
+            // The engine envelope is a JSON string; the transport may deliver it parsed.
+            const envelope = typeof data === 'string' ? data : JSON.stringify(data);
+            this.room.onPlayerMessage(playerId, envelope);
+        };
+        ctx.protocol.handleLeave = async (playerId) => {
+            this.room.onPlayerLeave(playerId);
+            this.players.delete(playerId);
+        };
+        // Ticking is owned by handleCreate's interval (the sidecar has no external
+        // tick driver). handleTick stays a no-op so a harness that DOES drive ticks
+        // can never double-advance the authority.
+        ctx.protocol.handleTick = async () => { };
+        ctx.protocol.serializePersistState = () => ({
+            ...this.room.snapshot(),
+            ...(this.room.secretSnapshot() === undefined ? {} : { secretState: this.room.secretSnapshot() }),
+        });
+        ctx.protocol.getLocked = () => false;
+        ctx.protocol.getPlayers = () => this.players;
+    }
+}
+function parseRuntimeMetadata(value) {
+    if (!isRecord(value)
+        || Object.keys(value).sort().join('\0') !== 'runtimeIdentity\0sessionConfigBytes\0sessionConfigDigest'
+        || typeof value.sessionConfigBytes !== 'string'
+        || typeof value.sessionConfigDigest !== 'string') {
+        throw new Error('SYNCPLAY_RUNTIME_METADATA_INVALID');
+    }
+    assertKinetixRuntimeIdentity(value.runtimeIdentity);
+    const sessionConfigBytes = decodeCanonicalBase64(value.sessionConfigBytes);
+    if (sessionConfigBytes.byteLength < 1
+        || sessionConfigBytes.byteLength > 65_536
+        || kinetixSessionConfigDigest(sessionConfigBytes) !== value.sessionConfigDigest) {
+        throw new Error('SYNCPLAY_RUNTIME_METADATA_INVALID');
+    }
+    return {
+        runtimeIdentity: value.runtimeIdentity,
+        sessionConfigBytes,
+        sessionConfigDigest: value.sessionConfigDigest,
+    };
+}
+function decodeCanonicalBase64(value) {
+    if (value.length === 0 || value.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(value)) {
+        throw new Error('SYNCPLAY_RUNTIME_METADATA_INVALID');
+    }
+    let binary;
+    try {
+        binary = atob(value);
+    }
+    catch {
+        throw new Error('SYNCPLAY_RUNTIME_METADATA_INVALID');
+    }
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    const canonical = btoa(Array.from(bytes, (byte) => String.fromCharCode(byte)).join(''));
+    if (canonical !== value)
+        throw new Error('SYNCPLAY_RUNTIME_METADATA_INVALID');
+    return bytes;
+}
+function readPositiveInt(value, fallback) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function readNonNegativeInt(value, fallback) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : fallback;
+}
+function deriveSeed(roomId) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < roomId.length; index += 1) {
+        hash ^= roomId.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+function createEphemeralSecretCrypto() {
+    const pair = generateKeyPairSync('ed25519');
+    const privateKey = createPrivateKey(pair.privateKey.export({ type: 'pkcs8', format: 'pem' }));
+    const spkiDer = Buffer.from(new Uint8Array(pair.publicKey.export({ type: 'spki', format: 'der' })));
+    return {
+        kid: 'dev-ephemeral',
+        publicKeySpki: spkiDer.toString('base64'),
+        randomBytes(length) {
+            return Uint8Array.from(randomBytes(length));
+        },
+        sha256(bytes) {
+            return Uint8Array.from(createHash('sha256').update(bytes).digest());
+        },
+        sign(bytes) {
+            return Uint8Array.from(sign(null, bytes, privateKey));
+        },
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

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