@driftengine/network 3.61.0

package/dist/simNumber.js

@@ -0,0 +1,156 @@
+/**
+ * Fixed-point arithmetic, 48.16, for a simulation that wants determinism by construction.
+ *
+ * **Opt-in, and the gate is the default.** `scripts/determinism.mjs` plus `math/exact.ts` make a
+ * floating-point simulation reproducible across engines, and that is the recommended path: it costs
+ * nothing, changes no stored replay, and is what every package in this repository already does.
+ * This exists for a consumer who would rather not depend on an argument about IEEE 754 at all.
+ *
+ * **A value is an integer held in a double**, scaled by 2^16. Add, subtract, compare and negate are
+ * integer operations and are exact by inspection. Multiply and divide are where a fixed-point
+ * library is either right or quietly wrong, so they are §2 and §3 below.
+ *
+ * ---
+ *
+ * ## 1. Why 48.16 and not 32.32
+ *
+ * A double holds integers exactly to 2^53. Spending 32 bits on the fraction leaves 21 for the
+ * integer part — about two million, which as metres is a world 2,000 km across but as *raw values*
+ * leaves almost nothing for intermediate results. 16 fractional bits give a resolution of 15
+ * micrometres and an integer range of ±2^37, which is more world than anybody has and enough
+ * headroom that a multiply's terms stay exact.
+ *
+ * ## 2. Multiplication is exact wherever its result is representable
+ *
+ * The naive `a * b / ONE` overflows immediately: two raws of 2^40 multiply to 2^80 and a double
+ * stops being exact at 2^53. The fix is to split both operands at the fixed point —
+ * `a = A·2^16 + α` — and sum four terms:
+ *
+ * ```text
+ * a·b/2^16  =  A·B·2^16  +  A·β  +  α·B  +  ⌊α·β/2^16⌋
+ * ```
+ *
+ * Every term is exact for a reason: `A·β` and `α·B` are at most 2^37·2^16 = 2^53; `α·β` is at most
+ * 2^32; and `A·B·2^16` is the result's own integer part, so it is exact exactly when the result is
+ * representable. **The domain is therefore "results that fit", which is the only domain a caller
+ * can reason about.**
+ *
+ * The low term truncates toward negative infinity, which is a decision and not a rounding accident:
+ * `Math.floor` is exactly specified, `Math.round` is too, and either is reproducible — but flooring
+ * is the one that makes the decomposition's arithmetic hold, because `α` and `β` are defined as the
+ * remainders a floor produces.
+ *
+ * ## 3. Division is deterministic rather than exact, and that is the honest word
+ *
+ * `⌊(a/b)·2^16⌋` uses one IEEE division, which every conforming engine rounds identically, then an
+ * exact multiplication by a power of two and an exactly specified floor. The result may differ by a
+ * unit in the last place from the true quotient. **It cannot differ between machines**, which is the
+ * property this file exists for. A caller wanting exact division wants rationals, which is a
+ * different library.
+ *
+ * ## 4. Overflow saturates, and says so
+ *
+ * A result outside the representable range clamps to the end of it. Not a throw, because
+ * `AGENTS.md` forbids one in a frame loop; not a wrap, because a position that teleports from one
+ * edge of the world to the other is a bug that looks like a physics explosion. Saturation is
+ * deterministic, which is the one property that must not be given up — every peer saturates
+ * identically, so a session stays in agreement even while it is wrong.
+ */
+/** Fractional bits. The whole format is this number. */
+export const SIM_FRACTION_BITS = 16;
+/** One, as a raw value. */
+export const SIM_ONE = 65536;
+/** The largest and smallest representable raws, which is a double's exact integer range. */
+export const SIM_MAX = 9007199254740991;
+export const SIM_MIN = -9007199254740991;
+/** From an ordinary number. Truncates toward negative infinity, as everything here does. */
+export function simFrom(value) {
+    return clamp(Math.floor(value * SIM_ONE));
+}
+/** Back to an ordinary number. Exact: a division by a power of two. */
+export function simTo(value) {
+    return value / SIM_ONE;
+}
+/** From an integer, exactly, with no rounding to think about. */
+export function simFromInt(value) {
+    return clamp(Math.trunc(value) * SIM_ONE);
+}
+export function simAdd(a, b) {
+    return clamp(a + b);
+}
+export function simSub(a, b) {
+    return clamp(a - b);
+}
+export function simNeg(a) {
+    return -a;
+}
+export function simAbs(a) {
+    return a < 0 ? -a : a;
+}
+export function simMin(a, b) {
+    return a < b ? a : b;
+}
+export function simMax(a, b) {
+    return a > b ? a : b;
+}
+/** -1, 0 or 1. Present so a caller compares through this file rather than by hand. */
+export function simCompare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Multiply. Exact wherever the result is representable; see §2 of the header.
+ *
+ * The split is at the fixed point, so `high` is the integer part and `low` the fractional part
+ * scaled — both non-negative for a negative operand too, because `Math.floor` goes toward negative
+ * infinity and the remainder is taken against that.
+ */
+export function simMul(a, b) {
+    const aHigh = Math.floor(a / SIM_ONE);
+    const aLow = a - aHigh * SIM_ONE;
+    const bHigh = Math.floor(b / SIM_ONE);
+    const bLow = b - bHigh * SIM_ONE;
+    const product = aHigh * bHigh * SIM_ONE + aHigh * bLow + aLow * bHigh + Math.floor((aLow * bLow) / SIM_ONE);
+    return clamp(product);
+}
+/** Divide. Deterministic rather than exact; see §3 of the header. Division by zero saturates. */
+export function simDiv(a, b) {
+    if (b === 0)
+        return a < 0 ? SIM_MIN : a > 0 ? SIM_MAX : 0;
+    return clamp(Math.floor((a / b) * SIM_ONE));
+}
+/**
+ * Square root, by Newton's method on integers.
+ *
+ * **Not `Math.sqrt` of the scaled value**, even though `Math.sqrt` is exactly rounded and would be
+ * reproducible: the scaling back and forth introduces a rounding this file has no way to pin, and
+ * the whole argument for fixed point is that no floating-point reasoning is needed to believe it.
+ * Newton on integers converges in a bounded number of steps and every step is exact.
+ *
+ * Negative input answers zero, the way a length does. It is not an error worth a branch at every
+ * call site.
+ */
+export function simSqrt(a) {
+    if (a <= 0)
+        return 0;
+    /* sqrt(a/ONE) * ONE = sqrt(a * ONE). The product is the one place range matters. */
+    const target = a * SIM_ONE;
+    if (!Number.isFinite(target) || target > SIM_MAX) {
+        /* Halve the argument twice, take the root, and double the result: sqrt(4x) = 2·sqrt(x). */
+        return clamp(2 * simSqrt(Math.floor(a / 4)));
+    }
+    let guess = Math.floor(a) || 1;
+    for (let i = 0; i < 40; i++) {
+        const next = Math.floor((guess + Math.floor(target / guess)) / 2);
+        if (next === guess || next === guess - 1)
+            return clamp(next);
+        guess = next;
+    }
+    return clamp(guess);
+}
+function clamp(value) {
+    if (value > SIM_MAX)
+        return SIM_MAX;
+    if (value < SIM_MIN)
+        return SIM_MIN;
+    return value;
+}

package/dist/snapshotter.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The snapshotters this package ships, and the composition that makes them enough.
+ *
+ * **A tick's state is rarely one thing.** It is the world, and the generator anything random drew
+ * from, and whatever the consumer keeps outside both. Restoring two of those three is not a rewind;
+ * it is a rewind plus a source of divergence that will not show up until something draws a random
+ * number during a replayed tick. So `combineSnapshotters` exists, and the ordinary shape of a
+ * session is a combination rather than a single snapshotter.
+ */
+import { type WorldSnapshot, type World } from '@driftengine/entities';
+import type { Snapshotter } from './rewind.ts';
+/** A world, through the identity-preserving snapshot `@driftengine/entities` owns. */
+export declare function worldSnapshotter(world: World): Snapshotter<WorldSnapshot>;
+/**
+ * A seeded generator's position.
+ *
+ * **The shape is declared here and no core type is named**, which is the seam `present/` in
+ * `@driftengine/chemistry` uses for the same reason: this package imports `@driftengine/entities`
+ * and nothing else, so that a deterministic host has no renderer in its module graph.
+ * `savableMulberry32` from core satisfies this structurally.
+ */
+export interface SavablePosition {
+    save(): number;
+    restore(state: number): void;
+}
+/**
+ * A generator, as one number.
+ *
+ * **Not restoring this is the classic silent rollback bug.** Everything looks correct until a
+ * replayed tick draws from the generator, gets the *next* number instead of the one it got the
+ * first time, and produces a world that is plausible and different. Nothing in a frame can see it.
+ */
+export declare function randomSnapshotter(rng: SavablePosition): Snapshotter<{
+    state: number;
+}>;
+/**
+ * Several snapshotters as one, saving and restoring in the order given.
+ *
+ * The slot is an array of the parts' slots, so nothing is allocated per save once the ring is
+ * built. **Restore runs in the same order as save**, which matters for a consumer whose parts are
+ * not independent: state derived from the world has to be restored after it.
+ */
+export declare function combineSnapshotters(parts: readonly Snapshotter<never>[]): Snapshotter<readonly unknown[]>;

package/dist/snapshotter.js

@@ -0,0 +1,81 @@
+/**
+ * The snapshotters this package ships, and the composition that makes them enough.
+ *
+ * **A tick's state is rarely one thing.** It is the world, and the generator anything random drew
+ * from, and whatever the consumer keeps outside both. Restoring two of those three is not a rewind;
+ * it is a rewind plus a source of divergence that will not show up until something draws a random
+ * number during a replayed tick. So `combineSnapshotters` exists, and the ordinary shape of a
+ * session is a combination rather than a single snapshotter.
+ */
+import { createWorldSnapshot } from '@driftengine/entities';
+import { Fingerprint, fingerprintSnapshot } from './fingerprint.js';
+/** A world, through the identity-preserving snapshot `@driftengine/entities` owns. */
+export function worldSnapshotter(world) {
+    const shared = new Fingerprint();
+    return {
+        create: () => createWorldSnapshot(),
+        save: (into) => world.saveInto(into),
+        restore: (from) => world.loadFrom(from),
+        digest: (from) => fingerprintSnapshot(from, shared),
+    };
+}
+/**
+ * A generator, as one number.
+ *
+ * **Not restoring this is the classic silent rollback bug.** Everything looks correct until a
+ * replayed tick draws from the generator, gets the *next* number instead of the one it got the
+ * first time, and produces a world that is plausible and different. Nothing in a frame can see it.
+ */
+export function randomSnapshotter(rng) {
+    return {
+        create: () => ({ state: rng.save() }),
+        save: (into) => {
+            into.state = rng.save();
+        },
+        restore: (from) => rng.restore(from.state),
+        /* The position is one integer, so its hash is its hex. Two peers whose generators sit at
+           different positions have diverged even when every visible value still matches. */
+        digest: (from) => (from.state >>> 0).toString(16).padStart(8, '0'),
+    };
+}
+/**
+ * Several snapshotters as one, saving and restoring in the order given.
+ *
+ * The slot is an array of the parts' slots, so nothing is allocated per save once the ring is
+ * built. **Restore runs in the same order as save**, which matters for a consumer whose parts are
+ * not independent: state derived from the world has to be restored after it.
+ */
+export function combineSnapshotters(parts) {
+    const members = parts;
+    return {
+        create: () => members.map((part) => part.create()),
+        save: (into) => {
+            for (let i = 0; i < members.length; i++) {
+                members[i].save(into[i]);
+            }
+        },
+        restore: (from) => {
+            for (let i = 0; i < members.length; i++) {
+                members[i].restore(from[i]);
+            }
+        },
+        /*
+         * Every part's digest, folded into one. A part with none contributes nothing rather than
+         * disabling the whole — a consumer combining a world with a scratch buffer they do not care
+         * about should still get a comparable hash of the world.
+         */
+        digest: (from) => {
+            const combined = new Fingerprint();
+            for (let i = 0; i < members.length; i++) {
+                const part = members[i];
+                if (part.digest === undefined)
+                    continue;
+                const text = part.digest(from[i]);
+                combined.int32(i);
+                for (let at = 0; at < text.length; at++)
+                    combined.byte(text.charCodeAt(at));
+            }
+            return combined.digest();
+        },
+    };
+}

package/dist/transport.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The seam a caller supplies, and the three roles a session can hold.
+ *
+ * **`AGENTS.md` settles the shape without being asked**: *"Nothing here may call a platform API
+ * directly when a consumer might want a different one ... Same for any clock, network or filesystem
+ * access — take the capability as a parameter, ship a browser implementation as the default."* So
+ * `Transport` is an interface, `LoopbackTransport` is the one that needs no network, and the two
+ * real ones are beside them.
+ *
+ * ---
+ *
+ * ## Three roles, because a relay need not be a simulator
+ *
+ * Most netcode assumes the machine that relays messages is the machine that runs the simulation.
+ * That assumption fails the moment the relay is written in another language — and a service that
+ * forwards messages, hosts rooms and re-simulates replays for anti-cheat is exactly the kind of
+ * thing written in another language. Such a service cannot run this simulation, because this
+ * engine is TypeScript.
+ *
+ * So the roles separate:
+ *
+ * - **Relay** forwards messages and reads none of them. Language-agnostic, and a Rust service is a
+ *   perfectly good one. Lockstep needs nothing more than this.
+ * - **Authority** runs the simulation and its state is the truth. A browser peer today; a Node
+ *   process once the packages can be imported without a bundler.
+ * - **Participant** sends inputs, receives inputs or state, and predicts locally.
+ *
+ * A session declares which it holds. Nothing in the protocol assumes the relay and the authority
+ * are the same process.
+ *
+ * ## Delivery is drained, never pushed into a frame
+ *
+ * A transport does not call back into a simulation. It collects what has arrived and a caller
+ * drains it at a point of their choosing, which is the top of a tick. A callback that fired
+ * mid-frame would deliver an input into the middle of a step that had already read its inputs, and
+ * the resulting world would depend on packet timing — which is the one thing a deterministic
+ * simulation must not do.
+ */
+/** Which participant a message is for or from. Small integers, assigned by the host. */
+export type PeerId = number;
+/** Send to everyone the transport can reach. */
+export declare const BROADCAST: PeerId;
+export type TransportState = 'connecting' | 'open' | 'closed';
+/** What a role means is in this file's header, not in these names. */
+export type SessionRole = 'relay' | 'authority' | 'participant';
+/**
+ * Where a drained message goes.
+ *
+ * The bytes are **borrowed**, not given: the array is the transport's and may be reused as soon as
+ * this returns. A sink that needs to keep one copies it. That is the same contract `MessageQueue`
+ * and the render passes use, and it is what keeps a drain allocation-free.
+ */
+export type MessageSink = (from: PeerId, message: Uint8Array) => void;
+export interface Transport {
+    readonly state: TransportState;
+    /** This end's own id, or -1 before a host has assigned one. */
+    readonly self: PeerId;
+    /** Queue a message. Whether it arrives, in order, or at all is the implementation's business. */
+    send(to: PeerId, message: Uint8Array): void;
+    /** Hand every message that has arrived to the sink, oldest first, and clear them. */
+    drain(into: MessageSink): void;
+    close(): void;
+}

package/dist/transport.js

@@ -0,0 +1,40 @@
+/**
+ * The seam a caller supplies, and the three roles a session can hold.
+ *
+ * **`AGENTS.md` settles the shape without being asked**: *"Nothing here may call a platform API
+ * directly when a consumer might want a different one ... Same for any clock, network or filesystem
+ * access — take the capability as a parameter, ship a browser implementation as the default."* So
+ * `Transport` is an interface, `LoopbackTransport` is the one that needs no network, and the two
+ * real ones are beside them.
+ *
+ * ---
+ *
+ * ## Three roles, because a relay need not be a simulator
+ *
+ * Most netcode assumes the machine that relays messages is the machine that runs the simulation.
+ * That assumption fails the moment the relay is written in another language — and a service that
+ * forwards messages, hosts rooms and re-simulates replays for anti-cheat is exactly the kind of
+ * thing written in another language. Such a service cannot run this simulation, because this
+ * engine is TypeScript.
+ *
+ * So the roles separate:
+ *
+ * - **Relay** forwards messages and reads none of them. Language-agnostic, and a Rust service is a
+ *   perfectly good one. Lockstep needs nothing more than this.
+ * - **Authority** runs the simulation and its state is the truth. A browser peer today; a Node
+ *   process once the packages can be imported without a bundler.
+ * - **Participant** sends inputs, receives inputs or state, and predicts locally.
+ *
+ * A session declares which it holds. Nothing in the protocol assumes the relay and the authority
+ * are the same process.
+ *
+ * ## Delivery is drained, never pushed into a frame
+ *
+ * A transport does not call back into a simulation. It collects what has arrived and a caller
+ * drains it at a point of their choosing, which is the top of a tick. A callback that fired
+ * mid-frame would deliver an input into the middle of a step that had already read its inputs, and
+ * the resulting world would depend on packet timing — which is the one thing a deterministic
+ * simulation must not do.
+ */
+/** Send to everyone the transport can reach. */
+export const BROADCAST = -1;

package/dist/webrtc.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `Transport` over a WebRTC data channel, which is what peer lockstep actually wants.
+ *
+ * **Unreliable and unordered, and that is the feature.** An input is only useful for the tick it
+ * names: a frame that took two retransmissions to arrive is a frame whose tick has been simulated,
+ * corrected and forgotten. Reliable ordered delivery makes the input *behind* it wait for that —
+ * head-of-line blocking, paid on every drop, on a link where the sender is about to send a newer
+ * one anyway. `{ ordered: false, maxRetransmits: 0 }` is the configuration, and `unreliableChannel`
+ * below is the one line of it worth not getting wrong.
+ *
+ * ---
+ *
+ * ## Signalling is a service and is not here
+ *
+ * Two peers cannot exchange WebRTC offers over WebRTC. Something else — a WebSocket, a REST
+ * endpoint, a person pasting a string — has to carry the first messages, and that something is a
+ * *service*: it has an address, an operator, and a lifetime longer than a session. Building one
+ * into a transport would make this package own a server.
+ *
+ * So a consumer opens the connection, does whatever signalling they already do, and hands over a
+ * channel. That is the same shape `KeyValueStore` has for persistence and `Transport` has for the
+ * network one level up.
+ *
+ * ## What this limits about testing, stated rather than discovered
+ *
+ * A data channel needs two real peer connections and an ICE exchange. There is no headless harness
+ * for that here, so what is tested is everything on this side of the channel — queueing, draining,
+ * the state mapping, and that the channel is configured unreliably — against a double. **The
+ * channel itself is exercised by `demo/dev/network.html`, in a browser, against a loopback pair.**
+ * That is a weaker guarantee than the loopback transport has, and it is why WebSocket is the
+ * default rather than this.
+ */
+import { type MessageSink, type PeerId, type Transport, type TransportState } from './transport.ts';
+/** What an `RTCDataChannel` satisfies. Declared rather than imported; see `websocket.ts`. */
+export interface DataChannelLike {
+    readonly readyState: string;
+    binaryType?: string;
+    send(data: ArrayBufferView | ArrayBuffer): void;
+    close(): void;
+    addEventListener(type: string, listener: (event: unknown) => void): void;
+}
+/** The part of `RTCPeerConnection` `unreliableChannel` needs. */
+export interface PeerConnectionLike {
+    createDataChannel(label: string, options: Record<string, unknown>): DataChannelLike;
+}
+/**
+ * A channel configured the way a simulation wants one.
+ *
+ * **`maxRetransmits: 0` and `ordered: false` together**, and both matter. Unordered alone still
+ * retransmits, so a drop still costs a round trip before the data arrives — late, for a tick that
+ * has gone. Zero retransmissions alone still delivers in order, so a lost frame still blocks the
+ * ones behind it. Either on its own reads like the fix and is half of it.
+ */
+export declare function unreliableChannel(connection: PeerConnectionLike, label?: string): DataChannelLike;
+export interface WebRtcTransportOptions {
+    readonly channel: DataChannelLike;
+    readonly self?: PeerId;
+    /** See `WebSocketTransportOptions.maxQueued`; the oldest goes for the same reason. */
+    readonly maxQueued?: number;
+}
+export declare class WebRtcTransport implements Transport {
+    readonly self: PeerId;
+    private readonly channel;
+    private readonly maxQueued;
+    private readonly arrived;
+    private closedByUs;
+    private droppedCount;
+    constructor(options: WebRtcTransportOptions);
+    get state(): TransportState;
+    get dropped(): number;
+    send(_to: PeerId, message: Uint8Array): void;
+    drain(into: MessageSink): void;
+    close(): void;
+}

package/dist/webrtc.js

@@ -0,0 +1,108 @@
+/**
+ * `Transport` over a WebRTC data channel, which is what peer lockstep actually wants.
+ *
+ * **Unreliable and unordered, and that is the feature.** An input is only useful for the tick it
+ * names: a frame that took two retransmissions to arrive is a frame whose tick has been simulated,
+ * corrected and forgotten. Reliable ordered delivery makes the input *behind* it wait for that —
+ * head-of-line blocking, paid on every drop, on a link where the sender is about to send a newer
+ * one anyway. `{ ordered: false, maxRetransmits: 0 }` is the configuration, and `unreliableChannel`
+ * below is the one line of it worth not getting wrong.
+ *
+ * ---
+ *
+ * ## Signalling is a service and is not here
+ *
+ * Two peers cannot exchange WebRTC offers over WebRTC. Something else — a WebSocket, a REST
+ * endpoint, a person pasting a string — has to carry the first messages, and that something is a
+ * *service*: it has an address, an operator, and a lifetime longer than a session. Building one
+ * into a transport would make this package own a server.
+ *
+ * So a consumer opens the connection, does whatever signalling they already do, and hands over a
+ * channel. That is the same shape `KeyValueStore` has for persistence and `Transport` has for the
+ * network one level up.
+ *
+ * ## What this limits about testing, stated rather than discovered
+ *
+ * A data channel needs two real peer connections and an ICE exchange. There is no headless harness
+ * for that here, so what is tested is everything on this side of the channel — queueing, draining,
+ * the state mapping, and that the channel is configured unreliably — against a double. **The
+ * channel itself is exercised by `demo/dev/network.html`, in a browser, against a loopback pair.**
+ * That is a weaker guarantee than the loopback transport has, and it is why WebSocket is the
+ * default rather than this.
+ */
+import { BROADCAST, } from './transport.js';
+/**
+ * A channel configured the way a simulation wants one.
+ *
+ * **`maxRetransmits: 0` and `ordered: false` together**, and both matter. Unordered alone still
+ * retransmits, so a drop still costs a round trip before the data arrives — late, for a tick that
+ * has gone. Zero retransmissions alone still delivers in order, so a lost frame still blocks the
+ * ones behind it. Either on its own reads like the fix and is half of it.
+ */
+export function unreliableChannel(connection, label = 'drift') {
+    return connection.createDataChannel(label, { ordered: false, maxRetransmits: 0 });
+}
+export class WebRtcTransport {
+    self;
+    channel;
+    maxQueued;
+    arrived = [];
+    closedByUs = false;
+    droppedCount = 0;
+    constructor(options) {
+        this.channel = options.channel;
+        this.self = options.self ?? -1;
+        this.maxQueued = Math.max(1, options.maxQueued ?? 1024);
+        if ('binaryType' in this.channel)
+            this.channel.binaryType = 'arraybuffer';
+        this.channel.addEventListener('message', (event) => {
+            const data = event.data;
+            const bytes = toBytes(data);
+            if (bytes === null)
+                return;
+            if (this.arrived.length >= this.maxQueued) {
+                this.arrived.shift();
+                this.droppedCount += 1;
+            }
+            this.arrived.push(bytes);
+        });
+    }
+    get state() {
+        if (this.closedByUs)
+            return 'closed';
+        const ready = this.channel.readyState;
+        if (ready === 'open')
+            return 'open';
+        if (ready === 'connecting')
+            return 'connecting';
+        return 'closed';
+    }
+    get dropped() {
+        return this.droppedCount;
+    }
+    send(_to, message) {
+        if (this.state !== 'open')
+            return;
+        this.channel.send(message);
+    }
+    drain(into) {
+        for (const message of this.arrived)
+            into(BROADCAST, message);
+        this.arrived.length = 0;
+    }
+    close() {
+        this.closedByUs = true;
+        this.arrived.length = 0;
+        this.channel.close();
+    }
+}
+function toBytes(data) {
+    if (data instanceof Uint8Array)
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data)) {
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    }
+    return null;
+}

package/dist/websocket.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `Transport` over a WebSocket, which is the browser default.
+ *
+ * **Ordered and reliable, which is the wrong guarantee for inputs and the right one for this
+ * topology.** A dropped input frame blocks the frames behind it while TCP retransmits, and by the
+ * time it arrives the tick it belonged to is usually past — so a lockstep peer waits for news it no
+ * longer needs. The unordered answer is `WebRtcTransport` beside this.
+ *
+ * It is the default anyway, for a reason outside the protocol: WebSocket and WebTransport are what
+ * a relay service realistically speaks, whatever language it is written in. A transport nothing can
+ * connect to is not a default.
+ *
+ * ---
+ *
+ * ## The socket is supplied and its type is declared structurally
+ *
+ * No `WebSocket` type is named. `@driftengine/network` imports `@driftengine/entities` and nothing
+ * else, and that is the property that lets an authoritative host run it — a package that named a
+ * DOM type would compile only where a DOM does. The shape below is what a browser `WebSocket` and
+ * a Node `ws` socket both satisfy, which is also what makes the tests possible.
+ *
+ * The socket is **supplied rather than constructed**, so a consumer owns the URL, the protocols,
+ * the credentials and the reconnection policy. A transport that opened its own connection would be
+ * making four decisions that belong to whoever is paying for the server.
+ */
+import { type MessageSink, type PeerId, type Transport, type TransportState } from './transport.ts';
+/** What a browser `WebSocket` and a Node `ws` both satisfy. Named here so neither is imported. */
+export interface SocketLike {
+    readonly readyState: number;
+    binaryType?: string;
+    send(data: ArrayBufferView | ArrayBuffer): void;
+    close(): void;
+    addEventListener(type: string, listener: (event: unknown) => void): void;
+}
+export interface WebSocketTransportOptions {
+    readonly socket: SocketLike;
+    /** This end's id, or -1 to wait for a host to assign one through a welcome. */
+    readonly self?: PeerId;
+    /**
+     * How many messages may queue before the oldest is dropped.
+     *
+     * A bound rather than none, because a socket that stops draining is a socket behind a paused tab
+     * or a stalled link, and an unbounded queue there is a leak that ends the session with a crash
+     * instead of a disconnection. **The oldest goes**, because in a simulation the newest input is
+     * the one still worth having.
+     */
+    readonly maxQueued?: number;
+}
+export declare class WebSocketTransport implements Transport {
+    readonly self: PeerId;
+    private readonly socket;
+    private readonly maxQueued;
+    private readonly arrived;
+    private closedByUs;
+    private droppedCount;
+    constructor(options: WebSocketTransportOptions);
+    get state(): TransportState;
+    /** Messages dropped because nothing drained. A consumer watching for a stalled tab reads this. */
+    get dropped(): number;
+    /**
+     * Send, or do nothing if the socket is not open yet.
+     *
+     * **Nothing is queued while connecting, deliberately.** Every message this package sends is
+     * addressed to a tick, and a tick that has passed by the time the socket opens is a tick nobody
+     * can use. Flushing a backlog of stale inputs on connect is worse than having sent none.
+     */
+    send(_to: PeerId, message: Uint8Array): void;
+    drain(into: MessageSink): void;
+    close(): void;
+}