@series-inc/rundot-syncplay 5.23.0-beta.7

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

@@ -0,0 +1,69 @@
+import { type DeterminismCheckMode, type DeterminismDiagnostic } from './static-checker.js';
+export interface DeterministicProjectCertificationPluginOptions {
+    readonly manifestPath: string;
+    readonly require?: readonly string[];
+    readonly frames?: number;
+    readonly agents?: number;
+    readonly slots?: readonly number[];
+    readonly outDir?: string;
+    readonly json?: string;
+    readonly cwd?: string;
+    readonly cliCommand?: readonly [string, ...string[]];
+}
+export interface DeterministicProjectCheckPluginOptions extends DeterministicProjectCertificationPluginOptions {
+    readonly certification?: string;
+    readonly summary?: string;
+    readonly summaryJson?: string;
+    readonly preflight?: string;
+    readonly preflightJson?: string;
+    readonly dist?: string;
+    readonly out?: string;
+    readonly junit?: string;
+    readonly releaseJson?: string;
+    readonly browserRuntime?: 'chromium' | 'webkit';
+    readonly browserJson?: string;
+    readonly playwrightModule?: string;
+}
+export interface SyncplayPluginOptions {
+    readonly mode?: DeterminismCheckMode;
+    readonly simulationEntries?: readonly string[];
+    readonly projectCertification?: DeterministicProjectCertificationPluginOptions;
+    readonly projectCheck?: DeterministicProjectCheckPluginOptions;
+    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;
+}
+export interface MinimalVitePlugin {
+    readonly name: string;
+    readonly apply?: MinimalVitePluginApply;
+    readonly enforce?: MinimalVitePluginEnforce;
+    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;
+export declare function runProjectCertification(options: DeterministicProjectCertificationPluginOptions): Promise<void>;
+export declare function createProjectCertificationCommand(options: DeterministicProjectCertificationPluginOptions): {
+    readonly executable: string;
+    readonly args: readonly string[];
+};
+export declare function runProjectCheck(options: DeterministicProjectCheckPluginOptions): Promise<void>;
+export declare function createProjectCheckCommand(options: DeterministicProjectCheckPluginOptions): {
+    readonly executable: string;
+    readonly args: readonly string[];
+};

package/dist/tools/vite-plugin.js

@@ -0,0 +1,203 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { checkDeterminism } from './static-checker.js';
+const execFileAsync = promisify(execFile);
+const nodeProcess = process;
+export function rundotSyncplayPlugin(options) {
+    return {
+        name: 'rundot-syncplay',
+        apply: options.apply,
+        enforce: options.enforce,
+        async buildStart() {
+            const simulationEntries = options.simulationEntries ?? [];
+            if (simulationEntries.length > 0) {
+                const diagnostics = await checkDeterminism({
+                    paths: simulationEntries,
+                    mode: options.mode ?? 'warn',
+                });
+                const errors = diagnostics.filter((diagnostic) => diagnostic.severity === 'error');
+                if (errors.length > 0) {
+                    throw new Error(formatDiagnostics(errors));
+                }
+            }
+            if (options.projectCertification !== undefined) {
+                await runProjectCertification(options.projectCertification);
+            }
+        },
+        async closeBundle() {
+            if (options.projectCheck !== undefined) {
+                await runProjectCheck(options.projectCheck);
+            }
+        },
+    };
+}
+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');
+}
+export async function runProjectCertification(options) {
+    const command = createProjectCertificationCommand(options);
+    try {
+        await execFileAsync(command.executable, command.args, {
+            cwd: options.cwd,
+            maxBuffer: 20 * 1024 * 1024,
+        });
+    }
+    catch (error) {
+        throw new Error(await formatProjectCertificationError(error, options));
+    }
+}
+export function createProjectCertificationCommand(options) {
+    const [executable, ...prefixArgs] = options.cliCommand ?? defaultProjectCertificationCliCommand();
+    const args = [
+        ...prefixArgs,
+        'project:certify',
+        options.manifestPath,
+    ];
+    pushStringFlag(args, 'require', options.require?.join(','));
+    pushIntegerFlag(args, 'frames', options.frames);
+    pushIntegerFlag(args, 'agents', options.agents);
+    pushStringFlag(args, 'slots', options.slots?.join(','));
+    pushStringFlag(args, 'out-dir', options.outDir);
+    pushStringFlag(args, 'json', options.json);
+    return { executable, args };
+}
+export async function runProjectCheck(options) {
+    const command = createProjectCheckCommand(options);
+    try {
+        await execFileAsync(command.executable, command.args, {
+            cwd: options.cwd,
+            maxBuffer: 20 * 1024 * 1024,
+        });
+    }
+    catch (error) {
+        throw new Error(await formatProjectCheckError(error, options));
+    }
+}
+export function createProjectCheckCommand(options) {
+    const [executable, ...prefixArgs] = options.cliCommand ?? defaultProjectCertificationCliCommand();
+    const args = [
+        ...prefixArgs,
+        'project:check',
+        options.manifestPath,
+    ];
+    pushStringFlag(args, 'require', options.require?.join(','));
+    pushIntegerFlag(args, 'frames', options.frames);
+    pushIntegerFlag(args, 'agents', options.agents);
+    pushStringFlag(args, 'slots', options.slots?.join(','));
+    pushStringFlag(args, 'out-dir', options.outDir);
+    pushStringFlag(args, 'certification', options.certification);
+    pushStringFlag(args, 'summary', options.summary);
+    pushStringFlag(args, 'summary-json', options.summaryJson);
+    pushStringFlag(args, 'preflight', options.preflight);
+    pushStringFlag(args, 'preflight-json', options.preflightJson);
+    pushStringFlag(args, 'dist', options.dist);
+    pushStringFlag(args, 'out', options.out);
+    pushStringFlag(args, 'json', options.json);
+    pushStringFlag(args, 'junit', options.junit);
+    pushStringFlag(args, 'release-json', options.releaseJson);
+    pushStringFlag(args, 'browser-runtime', options.browserRuntime);
+    pushStringFlag(args, 'browser-json', options.browserJson);
+    pushStringFlag(args, 'playwright-module', options.playwrightModule);
+    return { executable, args };
+}
+function defaultProjectCertificationCliCommand() {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    return [nodeProcess.execPath, resolve(moduleDir, '../cli.js')];
+}
+function pushStringFlag(args, name, value) {
+    if (value === undefined || value.length === 0) {
+        return;
+    }
+    args.push(`--${name}`, value);
+}
+function pushIntegerFlag(args, name, value) {
+    if (value === undefined) {
+        return;
+    }
+    args.push(`--${name}`, String(value));
+}
+async function formatProjectCertificationError(error, options) {
+    const reportFailures = await readProjectCertificationFailures(options);
+    const child = error;
+    const stdout = String(child.stdout).trim();
+    const stderr = String(child.stderr).trim();
+    return [
+        'Deterministic project certification failed.',
+        child.message,
+        reportFailures.diagnostic,
+        reportFailures.failures.length === 0 ? undefined : `failures:\n${reportFailures.failures.join('\n')}`,
+        stdout.length === 0 ? undefined : `stdout:\n${stdout}`,
+        stderr.length === 0 ? undefined : `stderr:\n${stderr}`,
+    ].filter((line) => line !== undefined).join('\n\n');
+}
+async function readProjectCertificationFailures(options) {
+    if (options.json === undefined || options.json.length === 0) {
+        return { failures: [] };
+    }
+    try {
+        const path = options.cwd === undefined ? options.json : resolve(options.cwd, options.json);
+        const report = JSON.parse(await readFile(path, 'utf8'));
+        return { failures: (report.failures ?? []).filter((failure) => typeof failure === 'string') };
+    }
+    catch (error) {
+        return {
+            failures: [],
+            diagnostic: `report unreadable: ${String(error)}`,
+        };
+    }
+}
+async function formatProjectCheckError(error, options) {
+    const reportFailures = await readProjectCheckFailures(options);
+    const child = error;
+    const stdout = String(child.stdout).trim();
+    const stderr = String(child.stderr).trim();
+    return [
+        'Deterministic project check failed.',
+        child.message,
+        reportFailures.diagnostic,
+        reportFailures.failures.length === 0 ? undefined : `failures:\n${reportFailures.failures.join('\n')}`,
+        stdout.length === 0 ? undefined : `stdout:\n${stdout}`,
+        stderr.length === 0 ? undefined : `stderr:\n${stderr}`,
+    ].filter((line) => line !== undefined).join('\n\n');
+}
+async function readProjectCheckFailures(options) {
+    if (options.json === undefined || options.json.length === 0) {
+        return { failures: [] };
+    }
+    try {
+        const path = options.cwd === undefined ? options.json : resolve(options.cwd, options.json);
+        const report = JSON.parse(await readFile(path, 'utf8'));
+        return { failures: (report.failures ?? []).filter((failure) => typeof failure === 'string') };
+    }
+    catch (error) {
+        return {
+            failures: [],
+            diagnostic: `report unreadable: ${String(error)}`,
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,148 @@
+import type { DeterministicMath } from './math.js';
+import type { DeterministicRandom } from './random.js';
+import type { CanonicalValue } from './canonical.js';
+export type TickRate = 10 | 20 | 30 | 60;
+export type ReplayRecordingMode = 'memory' | 'none';
+export interface DeterministicStepContext {
+    readonly frame: number;
+    readonly dtTicks: 1;
+    readonly random: DeterministicRandom;
+    readonly math: DeterministicMath;
+    readonly commands: readonly CanonicalValue[];
+}
+export type DeterministicStep<State, Input> = (state: Readonly<State>, inputs: readonly Readonly<Input>[], frame: number, ctx: DeterministicStepContext) => State;
+export interface DeterministicSessionConfig<State, Input> {
+    readonly tickRate: TickRate;
+    readonly playerCount: number;
+    readonly initialState: State;
+    readonly step: DeterministicStep<State, Input>;
+    readonly defaultInput: Input;
+    readonly inputSchemaId: string;
+    readonly stateSchemaId: string;
+    readonly deterministicVersion: string;
+    readonly engineIdentityHash?: string;
+    readonly assetDbHash?: string;
+    readonly configHash?: string;
+    readonly replayMetadata?: Readonly<Record<string, string | number | boolean>>;
+    readonly checksum?: (state: State) => string | number;
+    readonly canonicalizeState?: (state: State) => unknown;
+    readonly canonicalizeInput?: (input: Input) => unknown;
+    readonly hydrateInput?: (recordedInput: unknown) => Input;
+    readonly serializeState?: (state: State) => Uint8Array;
+    readonly deserializeState?: (bytes: Uint8Array) => State;
+    readonly checksumIntervalFrames?: number;
+    readonly snapshotBufferSize?: number;
+    readonly randomSeed?: number;
+    readonly maxCatchUpFrames?: number;
+    readonly replayRecordingMode?: ReplayRecordingMode;
+    readonly onInputFrameRecorded?: (inputFrame: RecordedInputFrame) => void;
+    readonly onCommandFrameRecorded?: (commandFrame: RecordedCommandFrame) => void;
+    readonly onChecksumRecorded?: (checksum: RecordedChecksum) => void;
+    readonly canonicalizeCommand?: (command: unknown) => unknown;
+    readonly runtimeGuards?: boolean;
+}
+export interface RecordedInputFrame {
+    readonly frame: number;
+    readonly inputs: readonly CanonicalValue[];
+    readonly inputFlags?: readonly RecordedInputFlags[];
+}
+export interface RecordedInputFlags {
+    readonly slot: number;
+    readonly playerPresent: boolean;
+    readonly repeatedPrevious: boolean;
+    readonly replacedByServer: boolean;
+    readonly commandInput: boolean;
+}
+export interface RecordedChecksum {
+    readonly frame: number;
+    readonly checksum: string;
+}
+export interface RecordedCommandFrame {
+    readonly frame: number;
+    readonly commands: readonly CanonicalValue[];
+}
+export interface RecordedDebugEvent {
+    readonly frame: number;
+    readonly type: string;
+    readonly payload: CanonicalValue;
+}
+export interface ReplayFile {
+    readonly formatVersion: 1;
+    readonly deterministicVersion: string;
+    readonly tickRate: TickRate;
+    readonly playerCount: number;
+    readonly inputSchemaId: string;
+    readonly stateSchemaId: string;
+    readonly engineIdentityHash?: string;
+    readonly assetDbHash?: string;
+    readonly configHash?: string;
+    readonly metadata?: Readonly<Record<string, string | number | boolean>>;
+    readonly randomSeed: number;
+    readonly initialState: CanonicalValue;
+    readonly inputFrames: readonly RecordedInputFrame[];
+    readonly commandHistory?: readonly RecordedCommandFrame[];
+    readonly checksums: readonly RecordedChecksum[];
+    readonly debugEvents?: readonly RecordedDebugEvent[];
+}
+/**
+ * The portable subset of a {@link FrameSnapshot} another session exported —
+ * everything a fresh session needs to hydrate mid-match (snapshot late-join).
+ * `stateBytes` is game-opaque (the game's serializeState seam produced it).
+ */
+export interface ExternalSessionSnapshot<Input> {
+    readonly frame: number;
+    readonly stateBytes: Uint8Array;
+    readonly randomState: number;
+    readonly inputs: readonly Input[];
+}
+export interface FrameSnapshot<State, Input> {
+    readonly frame: number;
+    readonly inputs: readonly Input[];
+    readonly checksum: string;
+    readonly state: State;
+    readonly stateBytes: Uint8Array;
+    readonly randomState: number;
+}
+export interface SessionSchemaIdentity {
+    readonly inputSchemaId: string;
+    readonly stateSchemaId: string;
+    readonly deterministicVersion: string;
+}
+export interface OfflineSession<State, Input> {
+    readonly currentFrame: number;
+    readonly accumulatedMs: number;
+    /** The game-build identity from config — lets transport layers hash it without game code. */
+    readonly schemaIdentity: SessionSchemaIdentity;
+    setInput(slot: number, input: Input): void;
+    setInputFlags(slot: number, flags: Partial<Omit<RecordedInputFlags, 'slot'>>): void;
+    recordCommands(commands: readonly unknown[]): void;
+    update(deltaMs: number): number;
+    stepFrames(count: number): void;
+    getState(): State;
+    exportReplay(): ReplayFile;
+    getSnapshot(frame: number): FrameSnapshot<State, Input> | undefined;
+    restoreToFrame(frame: number): void;
+    /**
+     * Hydrate from a snapshot exported by ANOTHER session (snapshot late-join):
+     * jumps to `snapshot.frame`, restoring state (via the game's deserialize
+     * seam) and RNG. The hydrated frame seeds the rolling snapshot buffer.
+     * The session can no longer export a replay (its history does not start at
+     * tick 0) — `exportReplay()` throws after this.
+     */
+    restoreSnapshot(snapshot: ExternalSessionSnapshot<Input>): void;
+    getSnapshotFrames(): readonly number[];
+}
+export interface ReplayVerificationResult {
+    readonly frames: number;
+    readonly checksums: number;
+    readonly mismatches: number;
+    readonly finalChecksum: string;
+    readonly firstMismatch?: ReplayVerificationMismatch;
+}
+export interface ReplayVerificationMismatch {
+    readonly frame: number;
+    readonly expectedChecksum: string;
+    readonly actualChecksum: string;
+    readonly inputFrame: RecordedInputFrame;
+    readonly state: CanonicalValue;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/venus-mp-budget.d.ts

@@ -0,0 +1,29 @@
+export interface VenusMpBudgetOptions {
+    readonly players: number;
+    readonly hz: number;
+    readonly framesPerMessage: number;
+    readonly maxPlayers: number;
+    readonly rateLimitPerSecond: number;
+    readonly maxMessageBytes: number;
+    readonly seed: number;
+}
+export interface VenusMpBudgetResult {
+    readonly players: number;
+    readonly hz: number;
+    readonly framesPerMessage: number;
+    readonly maxPlayers: number;
+    readonly rateLimitPerSecond: number;
+    readonly maxMessageBytes: number;
+    readonly messagesPerSecondPerPlayer: string;
+    readonly roomInboundMessagesPerSecond: string;
+    readonly jsonMessageBytes: number;
+    readonly packedMessageBytes: number;
+    readonly jsonWithinMaxMessage: boolean;
+    readonly packedWithinMaxMessage: boolean;
+    readonly withinRateLimit: boolean;
+    readonly withinMaxPlayers: boolean;
+    readonly recommendation: 'pass' | 'increase-max-players' | 'increase-bundle-size' | 'compact-payload' | 'multiple-changes';
+    readonly checksum: string;
+    readonly result: 'pass' | 'fail';
+}
+export declare function runVenusMpBudgetLab(options: VenusMpBudgetOptions): VenusMpBudgetResult;

package/dist/venus-mp-budget.js

@@ -0,0 +1,122 @@
+import { defaultChecksum } from './canonical.js';
+import { DeterministicRandom } from './random.js';
+import { makeLabInput, packLabInputFrame } from './sample-lab.js';
+export function runVenusMpBudgetLab(options) {
+    validateOptions(options);
+    const random = new DeterministicRandom(options.seed);
+    const frames = Array.from({ length: options.framesPerMessage }, (_, frame) => ({
+        frame,
+        inputs: Array.from({ length: options.players }, () => makeLabInput(random)),
+    }));
+    const jsonPayload = {
+        type: 'message',
+        msgType: 'rdm.input.v1',
+        data: {
+            startFrame: 0,
+            frames,
+        },
+    };
+    const packedPayloadBytes = frames.reduce((sum, frame) => sum + packLabInputFrame(frame.inputs).byteLength, 0);
+    const packedEnvelopeBytes = JSON.stringify({
+        type: 'message',
+        msgType: 'rdm.input-packed.v1',
+        data: {
+            startFrame: 0,
+            frames: options.framesPerMessage,
+            bytes: packedPayloadBytes,
+        },
+    }).length;
+    const jsonMessageBytes = JSON.stringify(jsonPayload).length;
+    const packedMessageBytes = packedEnvelopeBytes + packedPayloadBytes;
+    const messagesPerSecondPerPlayer = options.hz / options.framesPerMessage;
+    const roomInboundMessagesPerSecond = messagesPerSecondPerPlayer * options.players;
+    const withinMaxPlayers = options.players <= options.maxPlayers;
+    const withinRateLimit = roomInboundMessagesPerSecond <= options.rateLimitPerSecond;
+    const jsonWithinMaxMessage = jsonMessageBytes <= options.maxMessageBytes;
+    const packedWithinMaxMessage = packedMessageBytes <= options.maxMessageBytes;
+    let result = 'fail';
+    if (withinMaxPlayers && withinRateLimit && (jsonWithinMaxMessage || packedWithinMaxMessage)) {
+        result = 'pass';
+    }
+    const recommendation = chooseRecommendation({
+        withinMaxPlayers,
+        withinRateLimit,
+        jsonWithinMaxMessage,
+        packedWithinMaxMessage,
+    });
+    const reportWithoutChecksum = {
+        ...options,
+        messagesPerSecondPerPlayer,
+        roomInboundMessagesPerSecond,
+        jsonMessageBytes,
+        packedMessageBytes,
+        jsonWithinMaxMessage,
+        packedWithinMaxMessage,
+        withinRateLimit,
+        withinMaxPlayers,
+        recommendation,
+        result,
+    };
+    return {
+        players: options.players,
+        hz: options.hz,
+        framesPerMessage: options.framesPerMessage,
+        maxPlayers: options.maxPlayers,
+        rateLimitPerSecond: options.rateLimitPerSecond,
+        maxMessageBytes: options.maxMessageBytes,
+        messagesPerSecondPerPlayer: messagesPerSecondPerPlayer.toFixed(2),
+        roomInboundMessagesPerSecond: roomInboundMessagesPerSecond.toFixed(2),
+        jsonMessageBytes,
+        packedMessageBytes,
+        jsonWithinMaxMessage,
+        packedWithinMaxMessage,
+        withinRateLimit,
+        withinMaxPlayers,
+        recommendation,
+        checksum: defaultChecksum(reportWithoutChecksum),
+        result,
+    };
+}
+function chooseRecommendation(config) {
+    const failures = [
+        !config.withinMaxPlayers,
+        !config.withinRateLimit,
+        !config.jsonWithinMaxMessage && !config.packedWithinMaxMessage,
+    ].filter(Boolean).length;
+    if (failures === 0) {
+        return 'pass';
+    }
+    if (failures > 1) {
+        return 'multiple-changes';
+    }
+    if (!config.withinMaxPlayers) {
+        return 'increase-max-players';
+    }
+    if (!config.withinRateLimit) {
+        return 'increase-bundle-size';
+    }
+    return 'compact-payload';
+}
+function validateOptions(options) {
+    if (!Number.isInteger(options.players) || options.players < 1 || options.players > 128) {
+        throw new Error('Venus MP budget players must be between 1 and 128');
+    }
+    if (![10, 20, 30, 60].includes(options.hz)) {
+        throw new Error('Venus MP budget hz must be 10, 20, 30, or 60');
+    }
+    if (!Number.isInteger(options.framesPerMessage) || options.framesPerMessage < 1 || options.framesPerMessage > 60) {
+        throw new Error('Venus MP budget framesPerMessage must be between 1 and 60');
+    }
+    if (!Number.isInteger(options.maxPlayers) || options.maxPlayers < 1) {
+        throw new Error('Venus MP budget maxPlayers must be positive');
+    }
+    if (!Number.isInteger(options.rateLimitPerSecond) || options.rateLimitPerSecond < 1) {
+        throw new Error('Venus MP budget rateLimitPerSecond must be positive');
+    }
+    if (!Number.isInteger(options.maxMessageBytes) || options.maxMessageBytes < 1) {
+        throw new Error('Venus MP budget maxMessageBytes must be positive');
+    }
+    if (!Number.isInteger(options.seed) || options.seed < 0 || options.seed > 0xffff_ffff) {
+        throw new Error('Venus MP budget seed must be a uint32 integer');
+    }
+}

package/dist/ws-frame.d.ts

@@ -0,0 +1,49 @@
+import { type IncomingMessage } from 'node:http';
+export declare function webSocketAcceptKey(secWebSocketKey: string): string;
+export declare function encodeWebSocketTextFrame(text: string): Uint8Array;
+/** A minimal, bodyless close frame (opcode 0x8, FIN set). */
+export declare function encodeWebSocketCloseFrame(): Uint8Array;
+export interface DecodedWebSocketFrame {
+    readonly opcode: number;
+    readonly text: string;
+    readonly bytesRead: number;
+}
+export type WebSocketFrameReadResult = {
+    readonly kind: 'frame';
+    readonly frame: DecodedWebSocketFrame;
+}
+/** Not enough buffered bytes yet — wait for more data. */
+ | {
+    readonly kind: 'incomplete';
+}
+/** Malformed/unsupported frame — the connection must be closed, never crashed. */
+ | {
+    readonly kind: 'invalid';
+    readonly reason: string;
+};
+/**
+ * NEVER throws: this runs inside raw `socket.on('data')` handlers, where an
+ * uncaught throw is not routed to the 'error' listener and takes the process
+ * down — a handful of malformed bytes from any client would be an
+ * unauthenticated crash. Malformed input is reported as `kind: 'invalid'` so
+ * the receive loop can close the connection instead.
+ */
+export declare function readWebSocketFrame(bytes: Uint8Array): WebSocketFrameReadResult;
+export interface WebSocketConnection {
+    send(text: string): void;
+    onMessage(handler: (text: string) => void): void;
+    onClose(handler: () => void): void;
+    close(): void;
+}
+export interface WebSocketServerHandle {
+    readonly port: number;
+    readonly url: string;
+    close(): Promise<void>;
+}
+export interface WebSocketServerOptions {
+    readonly path?: string;
+    readonly port?: number;
+    onConnection(connection: WebSocketConnection, request: IncomingMessage): void;
+}
+export declare function startWebSocketServer(options: WebSocketServerOptions): Promise<WebSocketServerHandle>;
+export declare function connectWebSocketClient(url: string): Promise<WebSocketConnection>;