openrtc-netcode 3.0.1 → 3.0.3

package/dist/replication.js

@@ -0,0 +1,135 @@
+import { MAX_FRAME_BYTES } from './validation.js';
+/** Per-peer replacement, expiry and budgets. flush() is driven by the game tick. */
+export class ReplicationScheduler {
+    constructor(transmit, options = {}) {
+        this.transmit = transmit;
+        this.peers = new Map();
+        this.options = {
+            bytesPerSecond: 128 * 1024, burstBytes: 64 * 1024, maxPendingBytes: 256 * 1024,
+            maxPendingObjects: 1024, maxStateAgeMs: 250, ...options,
+        };
+        if (Object.values(this.options).some((value) => !Number.isFinite(value) || value <= 0)
+            || this.options.burstBytes <= 1024 || this.options.burstBytes > MAX_FRAME_BYTES / 2
+            || !Number.isInteger(this.options.maxPendingObjects) || this.options.maxPendingObjects > 10000)
+            throw new Error('Invalid replication budgets.');
+    }
+    enqueue(peerId, key, value, bytes, priority = 0) {
+        const queue = this.peer(peerId);
+        const old = queue.entries.get(key);
+        if (queue.closed || !Number.isFinite(priority) || !Number.isSafeInteger(bytes) || bytes + 1024 > this.options.burstBytes || bytes < 1
+            || queue.stats.queuedBytes - (old?.bytes ?? 0) + bytes > this.options.maxPendingBytes
+            || (!old && queue.entries.size >= this.options.maxPendingObjects)) {
+            queue.stats.rejected++;
+            return Promise.reject(new Error('Replication budget exhausted.'));
+        }
+        if (old) {
+            old.resolve();
+            queue.stats.superseded++;
+            queue.stats.queuedBytes -= old.bytes;
+        }
+        const promise = new Promise((resolve, reject) => {
+            queue.entries.set(key, { value, bytes, priority, time: performance.now(), resolve, reject });
+        });
+        queue.stats.queuedBytes += bytes;
+        // Batch all updates from this simulation turn, without a network timer.
+        queueMicrotask(() => this.pump(peerId, queue, performance.now()));
+        return promise;
+    }
+    flush(now = performance.now()) {
+        for (const [peerId, queue] of this.peers)
+            this.pump(peerId, queue, now);
+    }
+    cancel(peerId, key) {
+        const queue = this.peers.get(peerId), entry = queue?.entries.get(key);
+        if (!entry || !queue)
+            return;
+        queue.entries.delete(key);
+        queue.stats.queuedBytes -= entry.bytes;
+        entry.resolve();
+    }
+    closePeer(peerId) {
+        const queue = this.peers.get(peerId);
+        if (!queue)
+            return;
+        queue.closed = true;
+        for (const entry of queue.active)
+            entry.reject(new Error('Replication match retired.'));
+        queue.active = [];
+        for (const entry of queue.entries.values())
+            entry.reject(new Error('Replication match retired.'));
+        queue.entries.clear();
+        queue.stats.queuedBytes = 0;
+        this.peers.delete(peerId);
+    }
+    close() { for (const peerId of this.peers.keys())
+        this.closePeer(peerId); }
+    diagnostics(peerId) {
+        const queue = this.peers.get(peerId);
+        if (!queue)
+            return { queuedBytes: 0, oldestStateAgeMs: 0, sentBytes: 0, sentBatches: 0, superseded: 0, expired: 0, rejected: 0 };
+        const oldest = Math.min(performance.now(), ...Array.from(queue.entries.values(), (entry) => entry.time));
+        return { ...queue.stats, oldestStateAgeMs: performance.now() - oldest };
+    }
+    peer(peerId) {
+        let queue = this.peers.get(peerId);
+        if (!queue) {
+            queue = {
+                entries: new Map(), active: [], running: false, closed: false, tokens: this.options.burstBytes, last: performance.now(),
+                stats: { queuedBytes: 0, oldestStateAgeMs: 0, sentBytes: 0, sentBatches: 0, superseded: 0, expired: 0, rejected: 0 },
+            };
+            this.peers.set(peerId, queue);
+        }
+        return queue;
+    }
+    pump(peerId, queue, now) {
+        if (queue.closed || queue.running)
+            return;
+        queue.tokens = Math.min(this.options.burstBytes, queue.tokens + Math.max(0, now - queue.last) * this.options.bytesPerSecond / 1000);
+        queue.last = now;
+        for (const [key, entry] of queue.entries) {
+            if (now - entry.time > this.options.maxStateAgeMs) {
+                queue.entries.delete(key);
+                queue.stats.queuedBytes -= entry.bytes;
+                queue.stats.expired++;
+                entry.resolve();
+            }
+        }
+        const selected = [];
+        let bytes = 1024;
+        for (const [key, entry] of [...queue.entries].sort((a, b) => b[1].priority - a[1].priority || a[1].time - b[1].time)) {
+            if (selected.length >= 1024)
+                break;
+            if (bytes + entry.bytes > Math.min(queue.tokens, this.options.burstBytes))
+                continue;
+            selected.push(entry);
+            bytes += entry.bytes;
+            queue.entries.delete(key);
+            queue.stats.queuedBytes -= entry.bytes;
+        }
+        if (!selected.length)
+            return;
+        queue.tokens -= bytes;
+        queue.running = true;
+        queue.active = selected;
+        void Promise.resolve().then(() => {
+            if (queue.closed)
+                throw new Error('Replication match retired.');
+            return this.transmit(peerId, selected.map((entry) => entry.value));
+        }).then((actualBytes) => {
+            if (queue.closed)
+                throw new Error('Replication match retired.');
+            const charged = typeof actualBytes === 'number' ? actualBytes : bytes;
+            queue.tokens -= Math.max(0, charged - bytes);
+            queue.stats.sentBytes += charged;
+            queue.stats.sentBatches++;
+            for (const entry of selected)
+                entry.resolve();
+        }).catch((error) => { for (const entry of selected)
+            entry.reject(error); }).finally(() => {
+            queue.active = [];
+            queue.running = false;
+            if (!queue.closed)
+                this.pump(peerId, queue, performance.now());
+        });
+    }
+}

package/dist/roomRuntime.js

@@ -6,16 +6,6 @@ function assertRoom(room, requested) {
         throw new Error(`Activated OpenRTC room '${room.id}' cannot join '${requested}'.`);
     }
 }
-function peerMember(peer) {
-    const peerId = String(peer.nodeId ?? peer.id ?? peer.deviceId ?? '');
-    return {
-        nodeId: peerId,
-        userId: typeof peer.userId === 'string' ? peer.userId : undefined,
-        ticket: typeof peer.ticket === 'string' ? peer.ticket : undefined,
-        joinedAt: typeof peer.connectedAt === 'number' ? peer.connectedAt : Date.now(),
-        lastSeenAt: Date.now(),
-    };
-}
 /**
  * Adapts one OpenRTC 2.0 capability handle to netcode's transport-only runtime
  * contract. It never creates a second room, user scope, or base space.
@@ -24,7 +14,10 @@ export function runtimeFromRoom(room) {
     // Diagnostics expose raw core connections; only the avenue's public
     // onConnection projection owns the stable media-enabled logical view.
     const adaptedByPeer = new Map();
+    const closeObservers = new Map();
     const listeners = new Set();
+    let localNodeId = '';
+    const membersWithLocal = (peers) => room.closed || !localNodeId ? peers : [{ nodeId: localNodeId }, ...peers.filter((peer) => peer.nodeId !== localNodeId)];
     let stopConnectionObservation = null;
     const rawConnections = () => room.diagnostics.connections();
     const peerIdFor = (connection) => connection.peerId ?? connection.remoteNodeId ?? connection.deviceId ?? connection.id ?? '';
@@ -36,6 +29,8 @@ export function runtimeFromRoom(room) {
         let adapted;
         const removeFromProjection = () => {
             closed = true;
+            closeObservers.get(adapted)?.();
+            closeObservers.delete(adapted);
             if (adaptedByPeer.get(peerId) === adapted)
                 adaptedByPeer.delete(peerId);
         };
@@ -58,12 +53,15 @@ export function runtimeFromRoom(room) {
                 callback();
             }),
         };
-        connection.onClose(removeFromProjection);
+        closeObservers.set(adapted, connection.onClose(removeFromProjection));
         return adapted;
     };
     const publish = (connection) => {
         const peerId = peerIdFor(connection);
-        if (!peerId || adaptedByPeer.has(peerId))
+        if (!peerId)
+            return;
+        const previous = adaptedByPeer.get(peerId);
+        if (previous && previous.id === connection.id)
             return;
         const adapted = adaptConnection(connection);
         if (adapted.isClosed)
@@ -84,11 +82,15 @@ export function runtimeFromRoom(room) {
     return {
         lifecycle: true,
         channels: room.channels,
+        isRoomActive: () => !room.closed,
         initialize: async () => undefined,
         start: async () => undefined,
-        stop: async () => {
+        dispose: async () => {
             stopConnectionObservation?.();
             stopConnectionObservation = null;
+            for (const stop of closeObservers.values())
+                stop();
+            closeObservers.clear();
             listeners.clear();
             adaptedByPeer.clear();
         },
@@ -97,6 +99,7 @@ export function runtimeFromRoom(room) {
             const nodeId = typeof status.localNodeId === 'string' ? status.localNodeId.trim() : '';
             if (!nodeId)
                 throw new Error('The activated OpenRTC room has no local peer identity yet.');
+            localNodeId = nodeId;
             return nodeId;
         },
         createRoom: async (roomId = room.id) => {
@@ -113,12 +116,11 @@ export function runtimeFromRoom(room) {
         },
         watchRoom: (roomId, callback) => {
             assertRoom(room, roomId);
-            return room.peers.watch((peers) => callback(peers.map((peer) => peerMember(peer))));
+            return room.members.watch((members) => callback(membersWithLocal(members.filter((member) => !!member.nodeId).map((member) => ({ nodeId: member.nodeId, userId: member.userId, joinedAt: member.joinedAt })))));
         },
         getRoomMembers: async (roomId) => {
             assertRoom(room, roomId);
-            return room.peers.listConnected()
-                .map((peer) => peerMember(peer));
+            return membersWithLocal((await room.members.list()).filter((member) => !!member.nodeId).map((member) => ({ nodeId: member.nodeId, userId: member.userId, joinedAt: member.joinedAt })));
         },
         onConnection: (callback) => {
             listeners.add(callback);

package/dist/simulation.d.ts

@@ -0,0 +1,80 @@
+import type { NetcodeTransform, NetcodeVector3 } from './types.js';
+/** Game-driven fixed simulation time. This owns no network or browser timer. */
+export declare class SimulationClock {
+    readonly tickRate: number;
+    readonly maxCatchUpTicks: number;
+    tick: number;
+    droppedTicks: number;
+    private accumulator;
+    readonly deltaSeconds: number;
+    constructor(tickRate?: number, maxCatchUpTicks?: number);
+    advance(deltaSeconds: number, simulate: (tick: number, deltaSeconds: number) => void): number;
+    reset(tick?: number): void;
+}
+export interface TransformSnapshot {
+    tick: number;
+    revision: number;
+    epoch: string;
+    transform: NetcodeTransform;
+    linearVelocity?: NetcodeVector3;
+    teleport?: boolean;
+}
+export interface SnapshotBufferOptions {
+    tickRate?: number;
+    capacity?: number;
+    minDelaySeconds?: number;
+    maxDelaySeconds?: number;
+    maxExtrapolationSeconds?: number;
+    hermite?: boolean;
+}
+/** Authoritative-tick interpolation into caller-owned vectors/quaternions. */
+export declare class SnapshotBuffer {
+    private samples;
+    private epoch;
+    private readonly retiredEpochs;
+    private newestRevision;
+    private offsetSeconds;
+    private jitterSeconds;
+    private lastArrival;
+    readonly options: Required<SnapshotBufferOptions>;
+    readonly stats: {
+        underruns: number;
+        duplicateDrops: number;
+        overflowDrops: number;
+        extrapolationSeconds: number;
+    };
+    constructor(options?: SnapshotBufferOptions);
+    get size(): number;
+    get delaySeconds(): number;
+    reset(): void;
+    private clearSamples;
+    push(snapshot: TransformSnapshot, receivedSeconds?: number): boolean;
+    sample(receivedSeconds: number, output: NetcodeTransform): boolean;
+    sampleTick(tick: number, output: NetcodeTransform): boolean;
+}
+/** Input replay is engine-neutral; the supplied step function owns game rules. */
+export declare class InputPrediction<State, Input> {
+    private readonly step;
+    private readonly capacity;
+    private inputs;
+    private sequence;
+    private acknowledged;
+    private current;
+    constructor(initial: State, step: (state: State, input: Input, tick: number) => State, capacity?: number);
+    get state(): State;
+    get pendingInputs(): number;
+    predict(input: Input, tick: number): {
+        sequence: number;
+        state: State;
+    };
+    reconcile(sequence: number, authoritative: State): State;
+    reset(authoritative: State): void;
+}
+/** Bounded authoritative history for application-owned lag-compensated queries. */
+export declare class LagHistory<State> {
+    private readonly capacity;
+    private readonly entries;
+    constructor(capacity?: number);
+    record(tick: number, state: State): void;
+    sample(tick: number, interpolate: (left: State, right: State, alpha: number) => State): State | undefined;
+}

package/dist/simulation.js

@@ -0,0 +1,269 @@
+import { cloneJson, isCounter } from './validation.js';
+/** Game-driven fixed simulation time. This owns no network or browser timer. */
+export class SimulationClock {
+    constructor(tickRate = 60, maxCatchUpTicks = 8) {
+        this.tickRate = tickRate;
+        this.maxCatchUpTicks = maxCatchUpTicks;
+        this.tick = 0;
+        this.droppedTicks = 0;
+        this.accumulator = 0;
+        if (!Number.isFinite(tickRate) || tickRate < 1 || tickRate > 240 || !Number.isInteger(maxCatchUpTicks) || maxCatchUpTicks < 1) {
+            throw new Error('Invalid simulation clock configuration.');
+        }
+        this.deltaSeconds = 1 / tickRate;
+    }
+    advance(deltaSeconds, simulate) {
+        if (!Number.isFinite(deltaSeconds) || deltaSeconds < 0)
+            throw new Error('Invalid simulation delta.');
+        // Bound background-tab catch-up and arithmetic even for huge finite deltas.
+        deltaSeconds = Math.min(deltaSeconds, 3600);
+        this.accumulator += deltaSeconds;
+        const due = Math.floor((this.accumulator + 1e-10) / this.deltaSeconds);
+        const count = Math.min(due, this.maxCatchUpTicks);
+        this.droppedTicks += due - count;
+        this.accumulator -= due * this.deltaSeconds;
+        if (!isCounter(this.tick + count))
+            throw new Error('Simulation tick exhausted.');
+        for (let i = 0; i < count; i++)
+            simulate(++this.tick, this.deltaSeconds);
+        return count;
+    }
+    reset(tick = 0) {
+        if (!isCounter(tick))
+            throw new Error('Invalid simulation tick.');
+        this.tick = tick;
+        this.accumulator = 0;
+        this.droppedTicks = 0;
+    }
+}
+/** Authoritative-tick interpolation into caller-owned vectors/quaternions. */
+export class SnapshotBuffer {
+    constructor(options = {}) {
+        this.samples = [];
+        this.epoch = null;
+        this.retiredEpochs = new Set();
+        this.newestRevision = -1;
+        this.offsetSeconds = Infinity;
+        this.jitterSeconds = 0;
+        this.lastArrival = null;
+        this.stats = { underruns: 0, duplicateDrops: 0, overflowDrops: 0, extrapolationSeconds: 0 };
+        this.options = {
+            tickRate: 60, capacity: 32, minDelaySeconds: 0.05, maxDelaySeconds: 0.2,
+            maxExtrapolationSeconds: 0.12, hermite: false, ...options,
+        };
+        const o = this.options;
+        if (!Number.isFinite(o.tickRate) || o.tickRate < 1 || o.tickRate > 240
+            || !Number.isInteger(o.capacity) || o.capacity < 2 || o.capacity > 256
+            || !Number.isFinite(o.minDelaySeconds) || o.minDelaySeconds < 0 || o.maxDelaySeconds < o.minDelaySeconds
+            || o.maxExtrapolationSeconds < 0 || !Number.isFinite(o.maxDelaySeconds + o.maxExtrapolationSeconds)) {
+            throw new Error('Invalid snapshot buffer configuration.');
+        }
+    }
+    get size() { return this.samples.length; }
+    get delaySeconds() {
+        return Math.min(this.options.maxDelaySeconds, this.options.minDelaySeconds + this.jitterSeconds * 2);
+    }
+    reset() {
+        this.retiredEpochs.clear();
+        this.clearSamples();
+    }
+    clearSamples() {
+        this.newestRevision = -1;
+        this.samples.length = 0;
+        this.epoch = null;
+        this.offsetSeconds = Infinity;
+        this.lastArrival = null;
+        this.jitterSeconds = 0;
+    }
+    push(snapshot, receivedSeconds = performance.now() / 1000) {
+        if (!isCounter(snapshot.tick) || !isCounter(snapshot.revision) || !snapshot.epoch || !Number.isFinite(receivedSeconds)) {
+            throw new Error('Invalid transform snapshot.');
+        }
+        const value = cloneJson(snapshot);
+        const p = value.transform?.position, q = value.transform?.rotation;
+        if (!p || ![p.x, p.y, p.z].every(Number.isFinite) || (q && ![q.x, q.y, q.z, q.w].every(Number.isFinite)))
+            throw new Error('Invalid snapshot transform.');
+        if (this.retiredEpochs.has(value.epoch) || (this.epoch === value.epoch && value.revision <= this.newestRevision)) {
+            this.stats.duplicateDrops++;
+            return false;
+        }
+        if (this.epoch !== value.epoch) {
+            if (this.epoch) {
+                if (this.retiredEpochs.size >= 256)
+                    throw new Error('Snapshot epoch capacity exhausted; reset required.');
+                this.retiredEpochs.add(this.epoch);
+            }
+            this.clearSamples();
+        }
+        else if (value.teleport)
+            this.clearSamples();
+        this.epoch = value.epoch;
+        this.newestRevision = value.revision;
+        const existing = this.samples.findIndex((sample) => sample.tick === value.tick);
+        if (existing >= 0 && this.samples[existing].revision >= value.revision) {
+            this.stats.duplicateDrops++;
+            return false;
+        }
+        if (existing >= 0)
+            this.samples.splice(existing, 1);
+        this.samples.push(value);
+        this.samples.sort((a, b) => a.tick - b.tick);
+        while (this.samples.length > this.options.capacity) {
+            this.samples.shift();
+            this.stats.overflowDrops++;
+        }
+        const previous = this.lastArrival;
+        if (!previous || value.tick > previous.tick) {
+            if (previous) {
+                const deviation = Math.abs(receivedSeconds - previous.time - (value.tick - previous.tick) / this.options.tickRate);
+                this.jitterSeconds += (deviation - this.jitterSeconds) / 8;
+            }
+            this.lastArrival = { tick: value.tick, time: receivedSeconds };
+            this.offsetSeconds = Math.min(this.offsetSeconds + 0.001, receivedSeconds - value.tick / this.options.tickRate);
+        }
+        return true;
+    }
+    sample(receivedSeconds, output) {
+        return this.sampleTick((receivedSeconds - this.offsetSeconds - this.delaySeconds) * this.options.tickRate, output);
+    }
+    sampleTick(tick, output) {
+        if (!this.samples.length || !Number.isFinite(tick))
+            return false;
+        let left = this.samples[0];
+        let right = left;
+        for (const sample of this.samples) {
+            if (sample.tick <= tick)
+                left = sample;
+            if (sample.tick >= tick) {
+                right = sample;
+                break;
+            }
+            right = sample;
+        }
+        const span = right.tick - left.tick;
+        const alpha = span > 0 ? Math.max(0, Math.min(1, (tick - left.tick) / span)) : 0;
+        const a = left.transform.position;
+        const b = right.transform.position;
+        const dt = span / this.options.tickRate;
+        for (const axis of ['x', 'y', 'z']) {
+            if (this.options.hermite && left.linearVelocity && right.linearVelocity && span > 0) {
+                const t2 = alpha * alpha, t3 = t2 * alpha;
+                output.position[axis] = (2 * t3 - 3 * t2 + 1) * a[axis]
+                    + (t3 - 2 * t2 + alpha) * dt * left.linearVelocity[axis]
+                    + (-2 * t3 + 3 * t2) * b[axis] + (t3 - t2) * dt * right.linearVelocity[axis];
+            }
+            else
+                output.position[axis] = a[axis] + (b[axis] - a[axis]) * alpha;
+        }
+        if (output.rotation)
+            slerp(left.transform.rotation ?? IDENTITY, right.transform.rotation ?? IDENTITY, alpha, output.rotation);
+        if (output.scale) {
+            for (const axis of ['x', 'y', 'z']) {
+                const start = left.transform.scale?.[axis] ?? 1;
+                output.scale[axis] = start + ((right.transform.scale?.[axis] ?? 1) - start) * alpha;
+            }
+        }
+        const newest = this.samples[this.samples.length - 1];
+        this.stats.extrapolationSeconds = 0;
+        if (tick > newest.tick) {
+            this.stats.underruns++;
+            const age = newest.teleport ? 0 : Math.min(this.options.maxExtrapolationSeconds, (tick - newest.tick) / this.options.tickRate);
+            this.stats.extrapolationSeconds = age;
+            if (newest.linearVelocity)
+                for (const axis of ['x', 'y', 'z'])
+                    output.position[axis] += newest.linearVelocity[axis] * age;
+        }
+        return true;
+    }
+}
+const IDENTITY = { x: 0, y: 0, z: 0, w: 1 };
+function slerp(a, b, t, out) {
+    const an = Math.hypot(a.x, a.y, a.z, a.w) || 1, bn = Math.hypot(b.x, b.y, b.z, b.w) || 1;
+    let dot = (a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w) / (an * bn);
+    const sign = dot < 0 ? -1 : 1;
+    dot = Math.abs(Math.min(1, Math.max(-1, dot)));
+    const angle = Math.acos(dot), sin = Math.sin(angle);
+    const aw = sin < 1e-6 ? 1 - t : Math.sin((1 - t) * angle) / sin;
+    const bw = sin < 1e-6 ? t : Math.sin(t * angle) / sin;
+    for (const axis of ['x', 'y', 'z', 'w'])
+        out[axis] = aw * a[axis] / an + bw * sign * b[axis] / bn;
+    const norm = Math.hypot(out.x, out.y, out.z, out.w);
+    if (norm < 1e-8)
+        Object.assign(out, IDENTITY);
+    else
+        for (const axis of ['x', 'y', 'z', 'w'])
+            out[axis] /= norm;
+}
+/** Input replay is engine-neutral; the supplied step function owns game rules. */
+export class InputPrediction {
+    constructor(initial, step, capacity = 256) {
+        this.step = step;
+        this.capacity = capacity;
+        this.inputs = [];
+        this.sequence = 0;
+        this.acknowledged = -1;
+        this.current = cloneJson(initial);
+        if (!Number.isInteger(capacity) || capacity < 1 || capacity > 4096)
+            throw new Error('Invalid prediction capacity.');
+    }
+    get state() { return cloneJson(this.current); }
+    get pendingInputs() { return this.inputs.length; }
+    predict(input, tick) {
+        if (!isCounter(tick) || (this.inputs.length && tick < this.inputs[this.inputs.length - 1].tick))
+            throw new Error('Prediction tick moved backwards.');
+        if (this.inputs.length >= this.capacity)
+            throw new Error('Prediction history exhausted; authoritative resync required.');
+        if (!isCounter(this.sequence + 1))
+            throw new Error('Input sequence exhausted.');
+        const sequence = ++this.sequence;
+        const value = cloneJson(input);
+        this.inputs.push({ sequence, tick, input: value });
+        this.current = this.step(cloneJson(this.current), value, tick);
+        return { sequence, state: this.state };
+    }
+    reconcile(sequence, authoritative) {
+        if (!isCounter(sequence) || sequence > this.sequence)
+            throw new Error('Invalid acknowledged input.');
+        if (sequence <= this.acknowledged)
+            return this.state;
+        this.acknowledged = sequence;
+        this.inputs = this.inputs.filter((entry) => entry.sequence > sequence);
+        this.current = cloneJson(authoritative);
+        for (const entry of this.inputs)
+            this.current = this.step(cloneJson(this.current), entry.input, entry.tick);
+        return this.state;
+    }
+    reset(authoritative) {
+        this.current = cloneJson(authoritative);
+        this.inputs.length = 0;
+        this.sequence = 0;
+        this.acknowledged = -1;
+    }
+}
+/** Bounded authoritative history for application-owned lag-compensated queries. */
+export class LagHistory {
+    constructor(capacity = 64) {
+        this.capacity = capacity;
+        this.entries = [];
+        if (!Number.isInteger(capacity) || capacity < 2 || capacity > 4096)
+            throw new Error('Invalid history capacity.');
+    }
+    record(tick, state) {
+        if (!isCounter(tick) || (this.entries.length && tick <= this.entries[this.entries.length - 1].tick))
+            throw new Error('History ticks must advance.');
+        this.entries.push({ tick, state: cloneJson(state) });
+        if (this.entries.length > this.capacity)
+            this.entries.shift();
+    }
+    sample(tick, interpolate) {
+        if (!Number.isFinite(tick) || !this.entries.length || tick < this.entries[0].tick || tick > this.entries[this.entries.length - 1].tick)
+            return undefined;
+        let left = this.entries[0];
+        for (const right of this.entries) {
+            if (right.tick >= tick)
+                return interpolate(cloneJson(left.state), cloneJson(right.state), right.tick === left.tick ? 0 : (tick - left.tick) / (right.tick - left.tick));
+            left = right;
+        }
+        return undefined;
+    }
+}

package/dist/snapshots.d.ts

@@ -0,0 +1,12 @@
+import type { ObjectSnapshotBody } from './protocol.js';
+/** Bounded reliable pages. A view becomes visible only after every page arrives. */
+export declare function snapshotPages(snapshot: ObjectSnapshotBody): ObjectSnapshotBody[];
+export declare class SnapshotAssembly {
+    private revision;
+    private pages;
+    private expected;
+    private bytes;
+    private count;
+    private since;
+    push(body: ObjectSnapshotBody, now?: number): ObjectSnapshotBody | null;
+}

package/dist/snapshots.js

@@ -0,0 +1,71 @@
+import { boundedJson, isCounter } from './validation.js';
+const MAX_SNAPSHOT_BYTES = 8 * 1024 * 1024;
+const encoder = new TextEncoder();
+/** Bounded reliable pages. A view becomes visible only after every page arrives. */
+export function snapshotPages(snapshot) {
+    const pages = [];
+    let current = { objects: {}, removed: {}, viewRevision: snapshot.viewRevision };
+    let bytes = 0, total = 0, count = 0;
+    const flush = () => { pages.push(current); current = { objects: {}, removed: {}, viewRevision: snapshot.viewRevision }; bytes = count = 0; };
+    for (const category of ['objects', 'removed']) {
+        for (const [id, value] of Object.entries(snapshot[category] ?? {})) {
+            const size = encoder.encode(JSON.stringify([id, value])).byteLength;
+            total += size;
+            if (size > 220 * 1024 || total > MAX_SNAPSHOT_BYTES)
+                throw new Error('Object snapshot capacity exceeded.');
+            if (count && (bytes + size > 24 * 1024 || count >= 128))
+                flush();
+            current[category][id] = value;
+            bytes += size;
+            count++;
+            if (!boundedJson(current, 25000, 28))
+                throw new Error('Object snapshot complexity exceeded.');
+        }
+    }
+    if (count || !pages.length)
+        flush();
+    return pages.map((page, index) => ({ ...page, page: index, pages: pages.length }));
+}
+export class SnapshotAssembly {
+    constructor() {
+        this.revision = 0;
+        this.pages = new Map();
+        this.expected = 0;
+        this.bytes = 0;
+        this.count = 0;
+        this.since = 0;
+    }
+    push(body, now = performance.now()) {
+        const page = body.page ?? 0, total = body.pages ?? 1, revision = body.viewRevision;
+        if (!isCounter(revision) || revision < 1 || !isCounter(page) || !isCounter(total) || total < 1 || total > 2048 || page >= total)
+            return null;
+        if (revision < this.revision)
+            return null;
+        if (revision > this.revision || now - this.since > 15000) {
+            this.revision = revision;
+            this.pages.clear();
+            this.bytes = this.count = 0;
+            this.expected = total;
+            this.since = now;
+        }
+        if (total !== this.expected || this.pages.has(page))
+            return null;
+        this.bytes += encoder.encode(JSON.stringify(body)).byteLength;
+        this.count += Object.keys(body.objects).length + Object.keys(body.removed ?? {}).length;
+        if (this.bytes > MAX_SNAPSHOT_BYTES || this.count > 10000) {
+            this.pages.clear();
+            return null;
+        }
+        this.pages.set(page, body);
+        if (this.pages.size !== total)
+            return null;
+        const result = { objects: Object.create(null), removed: Object.create(null), viewRevision: revision };
+        for (let i = 0; i < total; i++) {
+            const part = this.pages.get(i);
+            Object.assign(result.objects, part.objects);
+            Object.assign(result.removed, part.removed);
+        }
+        this.pages.clear();
+        return result;
+    }
+}