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

package/README.md

@@ -52,6 +52,33 @@ session-config bytes, asks the game for a matching runtime through its runtime
 factory, and rejects a locally loaded pack mismatch before frame 0. Replays use
 the same identity/config/factory path.
 
+## Presentation frames
+
+`session.getState()` returns a detached deep copy of the current frame, which
+costs O(state) per read and is unaffordable for a large mutable world (a
+destructible voxel city, a big streaming map).
+
+`session.getPresentationFrame()` is the no-clone path. It calls the runtime's
+optional `project(checkpoint, previous)` and returns the result untouched:
+
+- **Requires** a runtime built with a `projectState` hook. A runtime without
+  `project` throws `SYNCPLAY_PROJECTION_UNSUPPORTED` — there is no silent
+  fallback to `inspect`.
+- **The result is immutable.** Callers must not mutate it. It may share structure
+  with authoritative state and with previously returned projections, which is
+  exactly what lets a renderer diff persistent roots and skip shared subtrees.
+- **`previous` is the last frame this session projected**, enabling delta
+  projections. It is absent — meaning the runtime should produce a full frame —
+  on the first call, after `restoreToFrame` or `restoreSnapshot`, and whenever
+  the previously projected frame is no longer retained (pruned or rolled past).
+- **Reading the same frame twice is free and idempotent.** Repeat calls return
+  the identical projection rather than re-projecting the frame against itself
+  (which would report an empty delta). Authoritative state cannot change without
+  the frame advancing, so multiple render passes per frame are safe.
+
+Projections are presentation-only: they never re-enter simulation and are not
+part of deterministic identity.
+
 ## Public projections and secrets
 
 Every peer applies the same confirmed inputs and authority commands. Optional

package/dist/browser.d.ts

@@ -82,3 +82,8 @@ 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';

package/dist/browser.js

@@ -42,3 +42,9 @@ 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';

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

package/dist/run-room-transport.js

@@ -0,0 +1,280 @@
+/**
+ * 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 { detectCoarseRegion } from './coarse-region.js';
+/** Wire envelope msgType the deterministic session protocol travels under. */
+const SESSION_MSG_TYPE = 'rdm';
+const SECRET_MSG_TYPE = 'rdm-secret';
+/** Room type the platform registers the generic deterministic room under. */
+const SYNCPLAY_ROOM_TYPE = 'deterministic';
+const SYNCPLAY_MAX_PLAYERS_CRITERION = '__syncplay.maxPlayers';
+const SYNCPLAY_ENGINE_IDENTITY_CRITERION = '__syncplay.engineIdentityHash';
+const SYNCPLAY_CONFIG_DIGEST_CRITERION = '__syncplay.sessionConfigDigest';
+const SYNCPLAY_RUNTIME_METADATA_KEY = 'syncplayRuntime';
+const MAX_SESSION_CONFIG_BYTES = 65_536;
+/**
+ * Session traffic buffered between transport creation and the engine attaching
+ * its onMessage handler (a game may await asset loads in between). ~4.5 min of
+ * confirmed-input at 30 Hz — past that the transport fails LOUD (error event +
+ * close) instead of silently dropping frames, which would wedge the engine's
+ * contiguous-tick application forever.
+ */
+const MAX_EARLY_SESSION_MESSAGES = 8192;
+function toTransport(room) {
+    const connectionHandlers = [];
+    const emitConnectionEvent = (event) => {
+        for (const handler of connectionHandlers)
+            handler(event);
+    };
+    const occupancyHandlers = new Set();
+    const occupancy = () => {
+        const players = Object.freeze(room.players.map((player) => Object.freeze({ ...player })));
+        return Object.freeze({
+            players,
+            occupied: players.length,
+            maxPlayers: room.maxPlayers,
+            full: players.length >= room.maxPlayers,
+            locked: room.locked,
+        });
+    };
+    const emitOccupancy = () => {
+        const snapshot = occupancy();
+        for (const handler of occupancyHandlers)
+            handler(snapshot);
+    };
+    // Fail-closed wiring: a transport that only carries send/onMessage swallows
+    // every disconnect — the room layer silently no-ops sends while the socket is
+    // dead, so the engine would keep predicting with no confirmed-input and the
+    // game would freeze with no signal. Register the health handlers up front
+    // (RundotServerRoom.on merges, so a game's own handlers are unaffected).
+    room.on({
+        onError: (error) => emitConnectionEvent({ kind: 'error', message: error }),
+        onDisconnect: () => emitConnectionEvent({ kind: 'disconnected' }),
+        onReconnecting: () => emitConnectionEvent({ kind: 'reconnecting' }),
+        onPlayerJoined: emitOccupancy,
+        onPlayerLeft: emitOccupancy,
+        onLock: emitOccupancy,
+        onUnlock: emitOccupancy,
+    });
+    // Register the raw handler EAGERLY — synchronously, before this function
+    // returns — so no `rdm` payload ever races the game's client construction.
+    // The deterministic authority emits `session-start` right after join, and
+    // `confirmed-input` starts flowing immediately; anything received before the
+    // engine attaches via onMessage is buffered here in order and flushed on
+    // attach.
+    let messageHandler;
+    let earlyMessages = [];
+    let secretMessageHandler;
+    let earlySecretMessages = [];
+    room.onRaw(SESSION_MSG_TYPE, (data) => {
+        const text = typeof data === 'string' ? data : JSON.stringify(data);
+        if (messageHandler !== undefined) {
+            messageHandler(text);
+            return;
+        }
+        if (earlyMessages.length >= MAX_EARLY_SESSION_MESSAGES) {
+            emitConnectionEvent({
+                kind: 'error',
+                message: 'syncplay transport buffered too much session traffic with no onMessage attached — closing the room instead of silently dropping frames',
+            });
+            room.leave();
+            return;
+        }
+        earlyMessages.push(text);
+    });
+    room.onRaw(SECRET_MSG_TYPE, (data) => {
+        const text = typeof data === 'string' ? data : JSON.stringify(data);
+        if (secretMessageHandler !== undefined) {
+            secretMessageHandler(text);
+            return;
+        }
+        if (earlySecretMessages.length >= MAX_EARLY_SESSION_MESSAGES) {
+            emitConnectionEvent({
+                kind: 'error',
+                message: 'syncplay transport buffered too much secret traffic with no onSecretMessage attached — closing the room instead of silently dropping frames',
+            });
+            room.leave();
+            return;
+        }
+        earlySecretMessages.push(text);
+    });
+    return {
+        roomCode: room.roomCode,
+        playerId: room.playerId,
+        get occupancy() {
+            return occupancy();
+        },
+        isCreator: room.isCreator,
+        send: (text) => room.sendRaw(SESSION_MSG_TYPE, text),
+        onMessage: (handler) => {
+            messageHandler = handler;
+            const buffered = earlyMessages;
+            earlyMessages = [];
+            for (const text of buffered)
+                handler(text);
+        },
+        sendSecret: (text) => room.sendRaw(SECRET_MSG_TYPE, text),
+        onSecretMessage: (handler) => {
+            secretMessageHandler = handler;
+            const buffered = earlySecretMessages;
+            earlySecretMessages = [];
+            for (const text of buffered)
+                handler(text);
+        },
+        close: () => room.leave(),
+        onConnectionEvent: (handler) => {
+            connectionHandlers.push(handler);
+        },
+        onOccupancyChange: (handler) => {
+            occupancyHandlers.add(handler);
+            handler(occupancy());
+            return () => {
+                occupancyHandlers.delete(handler);
+            };
+        },
+        setSeatingOpen: (open) => room.setSeatingOpen(open),
+    };
+}
+/**
+ * Join an existing deterministic room by its 6-char code and return a transport
+ * ready to hand to `createNetworkedSyncplayClient`.
+ */
+export async function joinSyncplayRoomByCode(api, code) {
+    const room = await api.joinRoomByCode(code);
+    return toTransport(room);
+}
+function validateMaxPlayers(maxPlayers) {
+    if (maxPlayers !== undefined && (!Number.isInteger(maxPlayers) || maxPlayers <= 0)) {
+        throw new Error('maxPlayers must be a positive integer');
+    }
+}
+function runtimeMetadata(options) {
+    if (options === undefined)
+        throw new Error('Syncplay runtime identity and canonical session config are required');
+    const identity = options.runtimeIdentity;
+    if (identity === undefined || identity.abiVersion !== 1 || ![10, 20, 30, 60].includes(identity.tickRate)
+        || identity.inputSchemaId.length === 0 || identity.stateSchemaId.length === 0
+        || identity.deterministicVersion.length === 0 || identity.engineIdentityHash.length === 0) {
+        throw new Error('Syncplay runtime identity is invalid');
+    }
+    if (!(options.sessionConfigBytes instanceof Uint8Array)
+        || options.sessionConfigBytes.byteLength < 1
+        || options.sessionConfigBytes.byteLength > MAX_SESSION_CONFIG_BYTES) {
+        throw new Error('Syncplay canonical session config bytes are empty or oversized');
+    }
+    if (!/^[a-f0-9]{64}$/u.test(options.sessionConfigDigest)) {
+        throw new Error('Syncplay session config digest is invalid');
+    }
+    return {
+        [SYNCPLAY_RUNTIME_METADATA_KEY]: {
+            runtimeIdentity: { ...identity },
+            sessionConfigBytes: bytesToBase64(options.sessionConfigBytes),
+            sessionConfigDigest: options.sessionConfigDigest,
+        },
+    };
+}
+function withRuntimeCriteria(criteria, options) {
+    runtimeMetadata(options);
+    return {
+        ...criteria,
+        [SYNCPLAY_ENGINE_IDENTITY_CRITERION]: options.runtimeIdentity.engineIdentityHash,
+        [SYNCPLAY_CONFIG_DIGEST_CRITERION]: options.sessionConfigDigest,
+    };
+}
+function withRequestedCapacity(criteria, maxPlayers) {
+    validateMaxPlayers(maxPlayers);
+    if (maxPlayers === undefined)
+        return criteria;
+    return { ...criteria, [SYNCPLAY_MAX_PLAYERS_CRITERION]: maxPlayers };
+}
+/**
+ * Auto-region (G6): pools pair on strict criteria equality, so tagging the
+ * request with the device's coarse region regionalizes the pool key with no
+ * server change. An explicit caller `region` always wins; a derived 'unknown'
+ * is NOT injected (better to pool globally than fragment into an 'unknown'
+ * bucket).
+ */
+function withAutoRegion(criteria, autoRegion) {
+    if (!autoRegion)
+        return criteria;
+    if (criteria !== undefined && 'region' in criteria)
+        return criteria;
+    const region = detectCoarseRegion();
+    if (region === 'unknown')
+        return criteria;
+    return { ...criteria, region };
+}
+/**
+ * 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 async function quickMatchSyncplayRoom(api, options, criteria) {
+    const effectiveCriteria = withRequestedCapacity(withRuntimeCriteria(withAutoRegion(criteria, options?.autoRegion ?? true), options), options?.maxPlayers);
+    const roomOptions = {
+        ...(effectiveCriteria === undefined ? {} : { criteria: effectiveCriteria }),
+        createOptions: {
+            ...(options?.maxPlayers === undefined ? {} : { maxPlayers: options.maxPlayers }),
+            metadata: runtimeMetadata(options),
+        },
+    };
+    const room = await api.joinOrCreateRoom(SYNCPLAY_ROOM_TYPE, Object.keys(roomOptions).length === 0 ? undefined : roomOptions);
+    return toTransport(room);
+}
+/**
+ * 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 async function createSyncplayRoom(api, options) {
+    validateMaxPlayers(options?.maxPlayers);
+    const metadata = runtimeMetadata(options);
+    const room = await api.createRoom(SYNCPLAY_ROOM_TYPE, {
+        createOptions: {
+            ...(options?.maxPlayers === undefined ? {} : { maxPlayers: options.maxPlayers }),
+            metadata,
+        },
+    });
+    return toTransport(room);
+}
+function bytesToBase64(bytes) {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+    let output = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const b0 = bytes[index];
+        const b1 = index + 1 < bytes.length ? bytes[index + 1] : 0;
+        const b2 = index + 2 < bytes.length ? bytes[index + 2] : 0;
+        output += alphabet[b0 >> 2];
+        output += alphabet[((b0 & 3) << 4) | (b1 >> 4)];
+        output += index + 1 < bytes.length ? alphabet[((b1 & 15) << 2) | (b2 >> 6)] : '=';
+        output += index + 2 < bytes.length ? alphabet[b2 & 63] : '=';
+    }
+    return output;
+}

package/dist/runtime-session.d.ts

@@ -1,6 +1,19 @@
 import { type KinetixRuntime, type KinetixRuntimeIdentity } from '@series-inc/rundot-kinetix/runtime';
 import type { RecordedChecksum, RecordedCommandFrame, RecordedInputFlags, RecordedInputFrame, ReplayFile } from './types.js';
 export type { KinetixRuntime, KinetixRuntimeIdentity } from '@series-inc/rundot-kinetix/runtime';
+/**
+ * A Kinetix runtime that may expose the optional no-clone presentation
+ * projection, re-typed for this session's Projection.
+ *
+ * `project` is omitted and re-declared rather than inherited so this compiles
+ * against both Kinetix builds we resolve against: the published ABI v1 runtime
+ * (no `project`) that the lockfile pins and publish lanes keep, and the
+ * in-repo runtime (whose `project` defaults to `Projection = State`) that test
+ * lanes overlay. Presence is feature-detected at runtime either way.
+ */
+export type ProjectionCapableRuntime<State, Input, Checkpoint, Projection> = Omit<KinetixRuntime<State, Input, Checkpoint>, 'project'> & {
+    project?(checkpoint: Checkpoint, previous?: Checkpoint): Readonly<Projection>;
+};
 export interface RuntimeExternalSnapshot<Input> {
     readonly frame: number;
     readonly runtimeBytes: Uint8Array;
@@ -16,8 +29,8 @@ export interface RuntimeFrameSnapshot<State, Input, Checkpoint> {
     readonly checkpoint: Checkpoint;
     readonly state: State;
 }
-export interface RuntimeSessionConfig<State, Input, Checkpoint> {
-    readonly runtime: KinetixRuntime<State, Input, Checkpoint>;
+export interface RuntimeSessionConfig<State, Input, Checkpoint, Projection = State> {
+    readonly runtime: ProjectionCapableRuntime<State, Input, Checkpoint, Projection>;
     readonly playerCount: number;
     readonly defaultInput: Input;
     readonly snapshotBufferSize?: number;
@@ -30,7 +43,7 @@ export interface RuntimeSessionConfig<State, Input, Checkpoint> {
     readonly onCommandFrameRecorded?: (frame: RecordedCommandFrame) => void;
     readonly onChecksumRecorded?: (checksum: RecordedChecksum) => void;
 }
-export interface RuntimeSession<State, Input, Checkpoint = unknown> {
+export interface RuntimeSession<State, Input, Checkpoint = unknown, Projection = State> {
     readonly currentFrame: number;
     readonly accumulatedMs: number;
     readonly schemaIdentity: KinetixRuntimeIdentity;
@@ -40,6 +53,13 @@ export interface RuntimeSession<State, Input, Checkpoint = unknown> {
     update(deltaMs: number): number;
     stepFrames(count: number): void;
     getState(): State;
+    /**
+     * Projects the current frame for presentation without cloning. Requires a
+     * runtime that implements `project`; throws SYNCPLAY_PROJECTION_UNSUPPORTED
+     * otherwise. The result is immutable and may share structure with previous
+     * frames — callers must not mutate it.
+     */
+    getPresentationFrame(): Readonly<Projection>;
     exportReplay(): ReplayFile;
     peekSnapshot(frame: number): RuntimeFrameSnapshot<State, Input, Checkpoint> | undefined;
     getSnapshot(frame: number): RuntimeFrameSnapshot<State, Input, Checkpoint> | undefined;
@@ -53,4 +73,4 @@ export interface RuntimeSession<State, Input, Checkpoint = unknown> {
     getSnapshotFrames(): readonly number[];
     dispose(): void;
 }
-export declare function createRuntimeSession<State, Input, Checkpoint>(config: RuntimeSessionConfig<State, Input, Checkpoint>): RuntimeSession<State, Input, Checkpoint>;
+export declare function createRuntimeSession<State, Input, Checkpoint, Projection = State>(config: RuntimeSessionConfig<State, Input, Checkpoint, Projection>): RuntimeSession<State, Input, Checkpoint, Projection>;

package/dist/runtime-session.js

@@ -38,6 +38,7 @@ export function createRuntimeSession(config) {
     let accumulatedMs = 0;
     let disposed = false;
     let hydrated = false;
+    let lastProjected;
     const frame0 = config.runtime.capture();
     retained.set(config.runtime.currentFrame, {
         checkpoint: frame0,
@@ -116,7 +117,19 @@ export function createRuntimeSession(config) {
                 checksum: frame % checksumInterval === 0,
             });
         }
-        const results = config.runtime.advance(requests);
+        let results;
+        try {
+            results = config.runtime.advance(requests);
+        }
+        catch (error) {
+            // advance() is atomic: the batch stepped no frames, so its commands must
+            // not be replayed on the next attempt. A command the runtime refuses to
+            // decode would otherwise be rebuilt into every subsequent request and
+            // wedge the session permanently.
+            for (const request of requests)
+                pendingCommands.delete(request.frame);
+            throw error;
+        }
         if (results.length !== requests.length)
             throw new Error('SYNCPLAY_RUNTIME_RESULT_COUNT_MISMATCH');
         for (let index = 0; index < results.length; index += 1) {
@@ -217,6 +230,29 @@ export function createRuntimeSession(config) {
             active();
             return structuredClone(config.runtime.inspect(requireRetained(config.runtime.currentFrame).checkpoint));
         },
+        getPresentationFrame() {
+            active();
+            const project = config.runtime.project;
+            if (typeof project !== 'function')
+                throw new Error('SYNCPLAY_PROJECTION_UNSUPPORTED');
+            const frame = config.runtime.currentFrame;
+            const entry = requireRetained(frame);
+            // Re-reading a frame must not diff it against itself — a delta hook given
+            // the current frame as its own baseline would report nothing changed.
+            // State cannot move without the frame advancing, so the projection this
+            // frame already produced is still the answer.
+            if (lastProjected?.frame === frame)
+                return lastProjected.projection;
+            // A previously projected frame may have been pruned or rolled past; the
+            // runtime then gets no baseline and produces a full frame. Deliberate
+            // contract, not a fallback.
+            const previous = lastProjected === undefined
+                ? undefined
+                : retained.get(lastProjected.frame)?.checkpoint;
+            const projection = project.call(config.runtime, entry.checkpoint, previous);
+            lastProjected = { frame, projection };
+            return projection;
+        },
         exportReplay() {
             active();
             if (hydrated)
@@ -279,6 +315,7 @@ export function createRuntimeSession(config) {
             commandFrames.splice(0, commandFrames.length, ...commandFrames.filter((record) => record.frame <= frame));
             checksums.splice(0, checksums.length, ...checksums.filter((record) => record.frame <= frame));
             accumulatedMs = 0;
+            lastProjected = undefined;
         },
         restoreSnapshot(snapshot) {
             active();
@@ -316,6 +353,7 @@ export function createRuntimeSession(config) {
             commandFrames.length = 0;
             checksums.length = 0;
             accumulatedMs = 0;
+            lastProjected = undefined;
             hydrated = true;
         },
         getSnapshotFrames() { active(); return [...retained.keys()]; },
@@ -325,6 +363,9 @@ export function createRuntimeSession(config) {
             for (const entry of retained.values())
                 release(entry.checkpoint);
             retained.clear();
+            // A projection may share structure with the whole world; releasing the
+            // checkpoints while still pinning it would defeat the release.
+            lastProjected = undefined;
             disposed = true;
         },
     };

package/dist/sdk-session.d.ts

@@ -1,5 +1,4 @@
-import type { KinetixRuntime } from '@series-inc/rundot-kinetix/runtime';
-import { type RuntimeSession, type RuntimeSessionConfig } from './runtime-session.js';
-export type SyncplaySessionPolicy<State, Input, Checkpoint = unknown> = Omit<RuntimeSessionConfig<State, Input, Checkpoint>, 'runtime'>;
-export type SyncplaySession<State, Input, Checkpoint = unknown> = RuntimeSession<State, Input, Checkpoint>;
-export declare function createSyncplaySession<State, Input, Checkpoint = unknown>(runtime: KinetixRuntime<State, Input, Checkpoint>, policy: SyncplaySessionPolicy<State, Input, Checkpoint>): SyncplaySession<State, Input, Checkpoint>;
+import { type ProjectionCapableRuntime, type RuntimeSession, type RuntimeSessionConfig } from './runtime-session.js';
+export type SyncplaySessionPolicy<State, Input, Checkpoint = unknown, Projection = State> = Omit<RuntimeSessionConfig<State, Input, Checkpoint, Projection>, 'runtime'>;
+export type SyncplaySession<State, Input, Checkpoint = unknown, Projection = State> = RuntimeSession<State, Input, Checkpoint, Projection>;
+export declare function createSyncplaySession<State, Input, Checkpoint = unknown, Projection = State>(runtime: ProjectionCapableRuntime<State, Input, Checkpoint, Projection>, policy: SyncplaySessionPolicy<State, Input, Checkpoint, Projection>): SyncplaySession<State, Input, Checkpoint, Projection>;

package/dist/tools/index.d.ts

@@ -2,3 +2,4 @@ export { defineKinetixProject } from '@series-inc/rundot-kinetix/authoring';
 export type { KinetixProjectDeclaration } from '@series-inc/rundot-kinetix/authoring';
 export { checkDeterminism, checkSourceText, collectDeterminismSuppressions, type DeterminismCheckMode, type DeterminismCheckOptions, type DeterminismDiagnostic, type DeterminismParserKind, type DeterminismSeverity, type DeterminismSuppression, } from './static-checker.js';
 export { runSyncplaySynctest, type SyncplaySynctestConfig, type SyncplaySynctestDivergence, type SyncplaySynctestInputFuzz, type SyncplaySynctestPhase, type SyncplaySynctestResult, } from '../synctest.js';
+export { rundotSyncplayPlugin, createSyncplayViteConfig, withSyncplayViteConfig, formatDiagnostics, type SyncplayPluginOptions, type MinimalVitePlugin, type MinimalVitePluginApply, type MinimalVitePluginEnforce, type MinimalVitePluginEnvironment, type MinimalViteResolvedConfig, type MinimalViteConfig, } from './vite-plugin.js';

package/dist/tools/index.js

@@ -1,3 +1,5 @@
 export { defineKinetixProject } from '@series-inc/rundot-kinetix/authoring';
 export { checkDeterminism, checkSourceText, collectDeterminismSuppressions, } from './static-checker.js';
 export { runSyncplaySynctest, } from '../synctest.js';
+// Determinism-lint Vite plugin (relocated from the game SDK's syncplay/tools).
+export { rundotSyncplayPlugin, createSyncplayViteConfig, withSyncplayViteConfig, formatDiagnostics, } from './vite-plugin.js';

package/dist/tools/vite-plugin.d.ts

@@ -0,0 +1,40 @@
+import { type DeterminismCheckMode, type DeterminismDiagnostic } from './static-checker.js';
+export interface SyncplayPluginOptions {
+    readonly mode?: DeterminismCheckMode;
+    readonly simulationEntries?: readonly string[];
+    readonly apply?: MinimalVitePluginApply;
+    readonly enforce?: MinimalVitePluginEnforce;
+}
+export type MinimalVitePluginApply = 'serve' | 'build' | ((config: unknown, env: MinimalVitePluginEnvironment) => boolean);
+export type MinimalVitePluginEnforce = 'pre' | 'post';
+export interface MinimalVitePluginEnvironment {
+    readonly command: 'serve' | 'build';
+    readonly mode: string;
+    readonly isSsrBuild?: boolean;
+    readonly isPreview?: boolean;
+}
+/** The slice of Vite's ResolvedConfig this plugin reads in configResolved. */
+export interface MinimalViteResolvedConfig {
+    readonly root?: string;
+    readonly logger?: {
+        warn(msg: string): void;
+    };
+}
+export interface MinimalVitePlugin {
+    readonly name: string;
+    readonly apply?: MinimalVitePluginApply;
+    readonly enforce?: MinimalVitePluginEnforce;
+    configResolved?(config: MinimalViteResolvedConfig): void;
+    buildStart(): Promise<void>;
+    closeBundle?(): Promise<void>;
+}
+export interface MinimalViteConfig {
+    readonly plugins?: readonly (MinimalVitePlugin | false | null | undefined)[];
+    readonly [key: string]: unknown;
+}
+export declare function rundotSyncplayPlugin(options: SyncplayPluginOptions): MinimalVitePlugin;
+export declare function createSyncplayViteConfig(options: SyncplayPluginOptions): MinimalViteConfig;
+export declare function withSyncplayViteConfig<TConfig extends MinimalViteConfig>(config: TConfig, options: SyncplayPluginOptions): TConfig & {
+    readonly plugins: readonly (MinimalVitePlugin | false | null | undefined)[];
+};
+export declare function formatDiagnostics(diagnostics: readonly DeterminismDiagnostic[]): string;

package/dist/tools/vite-plugin.js

@@ -0,0 +1,100 @@
+import { stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { checkDeterminism, } from './static-checker.js';
+export function rundotSyncplayPlugin(options) {
+    let viteRoot;
+    let warnLog = (msg) => console.warn(msg);
+    return {
+        name: 'rundot-syncplay',
+        apply: options.apply,
+        enforce: options.enforce,
+        configResolved(config) {
+            viteRoot = config.root;
+            if (config.logger !== undefined) {
+                warnLog = (msg) => config.logger.warn(msg);
+            }
+        },
+        async buildStart() {
+            const mode = options.mode ?? 'warn';
+            const strict = mode === 'strict';
+            const simulationEntries = options.simulationEntries ?? [];
+            if (simulationEntries.length === 0) {
+                // In strict mode a missing entries list is a build error: a deployable
+                // SyncPlay build must certify SOMETHING, not silently skip the check.
+                if (strict) {
+                    throw new Error('[rundot-syncplay] simulationEntries is required in strict mode — '
+                        + 'point it at the deterministic simulation file(s) or directory to certify.');
+                }
+                warnLog('[rundot-syncplay] no simulationEntries configured — determinism checking is OFF for this build');
+            }
+            else {
+                // Entries are LITERAL file/directory paths resolved against the Vite
+                // root (matching runProjectCertification/runProjectCheck's cwd
+                // behavior) — glob patterns are not expanded.
+                const root = viteRoot ?? process.cwd();
+                const resolvedEntries = [];
+                for (const entry of simulationEntries) {
+                    if (/[*?[\]{}]/.test(entry)) {
+                        throw new Error(`[rundot-syncplay] simulationEntries takes literal file or directory paths, not globs: "${entry}". `
+                            + 'Point it at a directory to check everything under it.');
+                    }
+                    const resolved = resolve(root, entry);
+                    try {
+                        await stat(resolved);
+                        resolvedEntries.push(resolved);
+                    }
+                    catch {
+                        if (strict) {
+                            throw new Error(`[rundot-syncplay] simulationEntries path does not exist: "${entry}" (resolved to ${resolved}).`);
+                        }
+                        warnLog(`[rundot-syncplay] skipping missing simulationEntries path: "${entry}" (resolved to ${resolved})`);
+                    }
+                }
+                if (resolvedEntries.length === 0) {
+                    warnLog('[rundot-syncplay] every simulationEntries path was missing — determinism checking is OFF for this build');
+                }
+                else {
+                    const diagnostics = await checkDeterminism({
+                        paths: resolvedEntries,
+                        mode,
+                    });
+                    const errors = diagnostics.filter((diagnostic) => diagnostic.severity === 'error');
+                    const warnings = diagnostics.filter((diagnostic) => diagnostic.severity !== 'error');
+                    if (warnings.length > 0) {
+                        warnLog(formatDiagnostics(warnings));
+                    }
+                    // error-class rules (Math.random, Date.now, timers, fetch, dynamic
+                    // import) fail the build in EVERY mode — no report-only path for them.
+                    if (errors.length > 0) {
+                        throw new Error(formatDiagnostics(errors));
+                    }
+                }
+            }
+        },
+    };
+}
+export function createSyncplayViteConfig(options) {
+    return {
+        plugins: [rundotSyncplayPlugin(options)],
+    };
+}
+export function withSyncplayViteConfig(config, options) {
+    return {
+        ...config,
+        plugins: [
+            ...(config.plugins ?? []),
+            rundotSyncplayPlugin(options),
+        ],
+    };
+}
+export function formatDiagnostics(diagnostics) {
+    return diagnostics
+        .map((diagnostic) => {
+        return [
+            `${diagnostic.ruleId} ${diagnostic.severity.toUpperCase()} ${diagnostic.path}:${diagnostic.line}:${diagnostic.column}`,
+            diagnostic.message,
+            `Use: ${diagnostic.suggestion}`,
+        ].join('\n');
+    })
+        .join('\n\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/rundot-syncplay",
-  "version": "5.25.0-beta.1",
+  "version": "5.25.0-beta.3",
   "description": "Kinetix orchestration, rollback, replay, late-join, and deterministic networking for RUN.game",
   "repository": {
     "type": "git",
@@ -49,8 +49,9 @@
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "test": "npm run test:core",
-    "test:core": "tsx --test tests/canonical.test.ts tests/runtime-session.test.ts tests/kinetix-runtime-session.test.ts tests/runtime-support.test.ts tests/runtime-guards.test.ts tests/r3f-render-adapter.test.ts tests/snapshot-cost.test.ts tests/sdkSession.test.ts tests/input-authority.test.ts tests/session-wire.test.ts tests/session-snapshot.test.ts tests/authority-room.test.ts tests/networked-client-snapshot.test.ts tests/secret-config.test.ts tests/secret-protocol.test.ts tests/secret-authority.test.ts tests/secret-client.test.ts tests/late-join-checksum.test.ts tests/replay-scoring.test.ts tests/bot-backfill.test.ts tests/latency-simulation.test.ts tests/time-sync.test.ts tests/match-log.test.ts tests/spectator.test.ts tests/synctest.test.ts tests/instant-replay.test.ts tests/session-promotion.test.ts tests/physics3d-broadphase-stats.test.ts tests/entrypoints.test.ts tests/export-surface.test.ts",
+    "test:core": "tsx --test tests/canonical.test.ts tests/runtime-session.test.ts tests/kinetix-runtime-session.test.ts tests/runtime-support.test.ts tests/runtime-guards.test.ts tests/r3f-render-adapter.test.ts tests/snapshot-cost.test.ts tests/sdkSession.test.ts tests/input-authority.test.ts tests/session-wire.test.ts tests/session-snapshot.test.ts tests/authority-room.test.ts tests/networked-client-snapshot.test.ts tests/secret-config.test.ts tests/secret-protocol.test.ts tests/secret-authority.test.ts tests/secret-client.test.ts tests/late-join-checksum.test.ts tests/replay-scoring.test.ts tests/bot-backfill.test.ts tests/latency-simulation.test.ts tests/time-sync.test.ts tests/match-log.test.ts tests/spectator.test.ts tests/synctest.test.ts tests/instant-replay.test.ts tests/session-promotion.test.ts tests/physics3d-broadphase-stats.test.ts tests/entrypoints.test.ts tests/export-surface.test.ts tests/test-manifest.test.ts tests/coarse-region.test.ts tests/run-glue-surface.test.mjs",
     "test:soak": "tsx --test tests/runtime-soak.test.ts",
+    "test:extended": "tsx --test tests/animation.test.ts tests/asset-cooking.test.ts tests/backend-proof-checksum-vectors.test.ts tests/bot-documents.test.ts tests/bot-primitives.test.ts tests/collider-cooking.test.ts tests/collision.test.ts tests/command-timeline.test.ts tests/config-bundle.test.ts tests/cosmetic-physics3d.test.ts tests/deterministic-primitives.test.ts tests/ecs-lite.test.ts tests/effects-adapter.test.ts tests/engine-runtime.test.ts tests/errors.test.ts tests/events.test.ts tests/input-button.test.ts tests/load-128-players.test.ts tests/math.test.ts tests/movement.test.ts tests/movement3d.test.ts tests/multiclient-authority.test.ts tests/navigation.test.ts tests/noise.test.ts tests/physics-cert.test.ts tests/physics2d.test.ts tests/physics3d-ccd.test.ts tests/physics3d-coverage.test.ts tests/physics3d-destruction-cert.test.ts tests/physics3d-heightfield.test.ts tests/physics3d-hull.test.ts tests/physics3d-joints.test.ts tests/physics3d-kinematic-mesh.test.ts tests/physics3d-mass.test.ts tests/physics3d-materials.test.ts tests/physics3d-mesh-onesided.test.ts tests/physics3d-query-index.test.ts tests/physics3d-recipes.test.ts tests/physics3d-rotation-convention.test.ts tests/physics3d-shared.test.ts tests/physics3d-sleeping-manifold-reuse.test.ts tests/physics3d-solver.test.ts tests/physics3d-stacking.test.ts tests/physics3d-toi.test.ts tests/physics3d-vehicle.test.ts tests/physics3d-voxel.test.ts tests/physics3d-world-edit.test.ts tests/physics3d.test.ts tests/random.test.ts tests/rollback-history.test.ts tests/schema-artifacts.test.ts tests/schema-codegen.test.ts tests/schema-dsl-binary.test.ts tests/schema.test.ts tests/signals.test.ts tests/sparse-set.test.ts tests/static-checker.test.ts tests/system-lifecycle.test.ts tests/wire-canonical-sentinels.test.ts tests/ws-frame.test.ts",
     "test:ci": "npm run build && npm run test:core",
     "pack:dry-run": "npm pack --dry-run"
   },
@@ -64,7 +65,8 @@
     "Kinetix"
   ],
   "dependencies": {
-    "@series-inc/rundot-kinetix": "0.1.0-beta.5"
+    "@series-inc/rundot-game-sdk": "5.25.0-beta.1",
+    "@series-inc/rundot-kinetix": "0.1.0-beta.6"
   },
   "devDependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",