@grafloria/element 0.3.18 → 0.3.19

package/src/libs/engine/src/sync/transports/broadcast-channel.js

@@ -0,0 +1,117 @@
+"use strict";
+// Wave 9 — Card 5: the BroadcastChannel transport. REAL, CROSS-TAB MULTIPLAYER, NO SERVER.
+//
+// The card named WebSocket and WebRTC. This one is not on that list and it is the one I
+// would ship first, for three reasons:
+//
+//   1. IT IS A PRODUCT FEATURE ON ITS OWN. Open the same document in two tabs today and
+//      you get two divergent copies and a last-save-wins fight. That is a bug users hit
+//      constantly, it needs no backend, no auth, no infrastructure and no ops budget, and
+//      this fixes it in ~80 lines.
+//   2. IT IS THE ONLY TRANSPORT THAT IS BOTH REAL AND FULLY TESTABLE. `BroadcastChannel`
+//      is a browser primitive AND a Node ≥18 global, so the same class is exercised for
+//      real in `nx test engine` (node) and for real across two Playwright tabs — no mock
+//      of the transport anywhere in the proof.
+//   3. IT IS THE HONEST DEMONSTRATION THAT THE SEAM WORKS. Nothing above this file
+//      changes. Not the adapter, not the protocol, not one test. If "transport-agnostic"
+//      were a slogan rather than a design, swapping the bus would break something.
+//
+// SEMANTICS, AND THE ONE THAT MATTERS: a BroadcastChannel is RELIABLE and ORDERED between
+// live tabs, and DELIVERS NOTHING AT ALL to a tab that is not listening. There is no
+// buffering, no history, no server. So a tab opened five minutes late has missed
+// everything — which is precisely why `hello`/`sync` exist, and why a new tab is caught up
+// by an EXISTING tab rather than by the channel. Anti-entropy is not belt-and-braces here;
+// it is the only reason a second tab ever sees the document.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BroadcastChannelTransport = void 0;
+class BroadcastChannelTransport {
+    constructor(options) {
+        this.options = options;
+        this.channel = null;
+        this.handlers = new Set();
+        this.statusHandlers = new Set();
+        this._status = 'disconnected';
+        this.closed = false;
+    }
+    get status() {
+        return this._status;
+    }
+    /** True when this environment can actually do cross-tab sync. */
+    static isSupported() {
+        return typeof globalThis.BroadcastChannel === 'function';
+    }
+    connect() {
+        var _a;
+        if (this.closed || this.channel)
+            return;
+        const create = (_a = this.options.create) !== null && _a !== void 0 ? _a : ((name) => {
+            const Ctor = globalThis
+                .BroadcastChannel;
+            if (!Ctor) {
+                throw new Error('BroadcastChannelTransport: BroadcastChannel is not available in this environment. ' +
+                    'Guard with BroadcastChannelTransport.isSupported() and fall back to a socket.');
+            }
+            return new Ctor(name);
+        });
+        const channel = create(this.options.name);
+        channel.onmessage = (event) => this.receive(event.data);
+        this.channel = channel;
+        this.setStatus('connected');
+    }
+    send(message) {
+        if (this.closed || !this.channel || this._status !== 'connected')
+            return;
+        // The spec already excludes the sender from delivery, so — unlike a server relay —
+        // there is no echo to filter. We stamp `from` anyway because the ADAPTER needs to know
+        // who sent it (to answer their sync, to attribute their cursor); the transport just
+        // does not have to use it for de-duplication.
+        this.channel.postMessage(message);
+    }
+    receive(data) {
+        if (this.closed || this._status !== 'connected')
+            return;
+        const msg = data;
+        if (!msg || typeof msg !== 'object' || typeof msg.t !== 'string')
+            return;
+        // Belt and braces: another app on the same origin could, in principle, pick the same
+        // channel name. A malformed message must not take the document down.
+        if (msg.from === this.options.actor)
+            return;
+        for (const h of [...this.handlers])
+            h(msg);
+    }
+    onMessage(handler) {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+    onStatus(handler) {
+        this.statusHandlers.add(handler);
+        return () => this.statusHandlers.delete(handler);
+    }
+    /** Simulates (and, on `pagehide`, effects) a drop. Re-`connect()` to come back. */
+    disconnect() {
+        if (!this.channel)
+            return;
+        this.channel.onmessage = null;
+        this.channel.close();
+        this.channel = null;
+        this.setStatus('disconnected');
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.disconnect();
+        this.closed = true;
+        this.handlers.clear();
+        this.statusHandlers.clear();
+    }
+    setStatus(next) {
+        if (this._status === next)
+            return;
+        this._status = next;
+        for (const h of [...this.statusHandlers])
+            h(next);
+    }
+}
+exports.BroadcastChannelTransport = BroadcastChannelTransport;
+//# sourceMappingURL=broadcast-channel.js.map

package/src/libs/engine/src/sync/transports/broadcast-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast-channel.js","sourceRoot":"","sources":["../../../../../../../engine/src/sync/transports/broadcast-channel.ts"],"names":[],"mappings":";AAAA,2FAA2F;AAC3F,EAAE;AACF,wFAAwF;AACxF,uCAAuC;AACvC,EAAE;AACF,wFAAwF;AACxF,wFAAwF;AACxF,0FAA0F;AAC1F,mCAAmC;AACnC,yFAAyF;AACzF,wFAAwF;AACxF,yFAAyF;AACzF,+CAA+C;AAC/C,mFAAmF;AACnF,yFAAyF;AACzF,mFAAmF;AACnF,EAAE;AACF,0FAA0F;AAC1F,qFAAqF;AACrF,iFAAiF;AACjF,2FAA2F;AAC3F,2FAA2F;AAC3F,6DAA6D;;;AAqB7D,MAAa,yBAAyB;IAOpC,YAA6B,OAAyC;QAAzC,YAAO,GAAP,OAAO,CAAkC;QAN9D,YAAO,GAAgC,IAAI,CAAC;QACnC,aAAQ,GAAG,IAAI,GAAG,EAA4B,CAAC;QAC/C,mBAAc,GAAG,IAAI,GAAG,EAAgC,CAAC;QAClE,YAAO,GAAoB,cAAc,CAAC;QAC1C,WAAM,GAAG,KAAK,CAAC;IAEkD,CAAC;IAE1E,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,iEAAiE;IACjE,MAAM,CAAC,WAAW;QAChB,OAAO,OAAQ,UAA6C,CAAC,gBAAgB,KAAK,UAAU,CAAC;IAC/F,CAAC;IAED,OAAO;;QACL,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QAExC,MAAM,MAAM,GACV,MAAA,IAAI,CAAC,OAAO,CAAC,MAAM,mCACnB,CAAC,CAAC,IAAY,EAAE,EAAE;YAChB,MAAM,IAAI,GAAI,UAA6E;iBACxF,gBAAgB,CAAC;YACpB,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CACb,oFAAoF;oBAClF,+EAA+E,CAClF,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC,CAAC,CAAC;QAEL,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1C,OAAO,CAAC,SAAS,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,CAAC,OAAoB;QACvB,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,KAAK,WAAW;YAAE,OAAO;QACzE,mFAAmF;QACnF,uFAAuF;QACvF,oFAAoF;QACpF,8CAA8C;QAC9C,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAEO,OAAO,CAAC,IAAa;QAC3B,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,KAAK,WAAW;YAAE,OAAO;QACxD,MAAM,GAAG,GAAG,IAAmB,CAAC;QAChC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,CAAC,KAAK,QAAQ;YAAE,OAAO;QACzE,qFAAqF;QACrF,qEAAqE;QACrE,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK;YAAE,OAAO;QAC5C,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED,SAAS,CAAC,OAAiC;QACzC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,QAAQ,CAAC,OAAqC;QAC5C,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACnD,CAAC;IAED,mFAAmF;IACnF,UAAU;QACR,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;QAC9B,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;IACjC,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;IAC9B,CAAC;IAEO,SAAS,CAAC,IAAqB;QACrC,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;YAAE,OAAO;QAClC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC;YAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;CACF;AA5FD,8DA4FC"}

package/src/libs/engine/src/sync/transports/memory.d.ts

@@ -0,0 +1,38 @@
+import type { ActorId } from '../../collab/op';
+import type { SyncMessage } from '../protocol';
+import type { SyncTransport, TransportStatus, Unsubscribe } from '../transport';
+type Handler = (message: SyncMessage) => void;
+/** A shared bus. One hub = one document = one "room". */
+export declare class MemoryHub {
+    protected readonly ports: Set<MemoryTransport>;
+    /** Every message that crossed the bus — the wire tap the tests assert against. */
+    readonly traffic: Array<{
+        from: ActorId;
+        message: SyncMessage;
+    }>;
+    connect(actor: ActorId): MemoryTransport;
+    /** Deliver to everyone EXCEPT the sender. A peer never hears its own echo. */
+    deliver(from: MemoryTransport, message: SyncMessage): void;
+    detach(port: MemoryTransport): void;
+    get peerCount(): number;
+}
+export declare class MemoryTransport implements SyncTransport {
+    private readonly hub;
+    readonly actor: ActorId;
+    private handlers;
+    private statusHandlers;
+    private _status;
+    private closed;
+    constructor(hub: MemoryHub, actor: ActorId);
+    get status(): TransportStatus;
+    send(message: SyncMessage): void;
+    /** Inbound. Ignored while disconnected — a dropped peer hears nothing, by definition. */
+    accept(message: SyncMessage): void;
+    onMessage(handler: Handler): Unsubscribe;
+    onStatus(handler: (s: TransportStatus) => void): Unsubscribe;
+    connect(): void;
+    disconnect(): void;
+    close(): void;
+    private setStatus;
+}
+export {};

package/src/libs/engine/src/sync/transports/memory.js

@@ -0,0 +1,111 @@
+"use strict";
+// Wave 9 — Card 5: the in-memory transport.
+//
+// SHIPPED, not a test double. Three real jobs:
+//
+//   1. THE TEST SUBSTRATE. Every convergence property in this wave is proven over this
+//      transport, because it is the only one where "peer B has now received it" is a
+//      statement you can make without a timer, a poll or a flake.
+//   2. TWO PANES IN ONE PAGE. Split-view, a linked minimap, an embedded preview that must
+//      track the live document — all of them are two Replicas in one JS context, and
+//      routing that through a socket to a server and back would be absurd.
+//   3. THE REFERENCE. It is 90 lines. If a new transport is longer than this plus its
+//      protocol's framing, the author has put logic in the wrong layer.
+//
+// Delivery is SYNCHRONOUS: `send()` returns after every other peer's handler has run.
+// That makes the tests deterministic and it is exactly what a same-thread bus should do.
+// The `UnreliableHub` next door is the same class with the network's malice added back.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryTransport = exports.MemoryHub = void 0;
+/** A shared bus. One hub = one document = one "room". */
+class MemoryHub {
+    constructor() {
+        this.ports = new Set();
+        /** Every message that crossed the bus — the wire tap the tests assert against. */
+        this.traffic = [];
+    }
+    connect(actor) {
+        const port = new MemoryTransport(this, actor);
+        this.ports.add(port);
+        return port;
+    }
+    /** Deliver to everyone EXCEPT the sender. A peer never hears its own echo. */
+    deliver(from, message) {
+        this.traffic.push({ from: from.actor, message });
+        for (const port of [...this.ports]) {
+            if (port === from)
+                continue;
+            port.accept(message);
+        }
+    }
+    detach(port) {
+        this.ports.delete(port);
+    }
+    get peerCount() {
+        return this.ports.size;
+    }
+}
+exports.MemoryHub = MemoryHub;
+class MemoryTransport {
+    constructor(hub, actor) {
+        this.hub = hub;
+        this.actor = actor;
+        this.handlers = new Set();
+        this.statusHandlers = new Set();
+        this._status = 'disconnected';
+        this.closed = false;
+    }
+    get status() {
+        return this._status;
+    }
+    send(message) {
+        // A send while down is a NO-OP, not an error. This is what a real socket does, and it
+        // is what makes "the peer was offline for 30 seconds" a survivable event rather than
+        // an exception to handle at every call site. The ops are in the log; the reconnect's
+        // sync round delivers them.
+        if (this.closed || this._status !== 'connected')
+            return;
+        this.hub.deliver(this, message);
+    }
+    /** Inbound. Ignored while disconnected — a dropped peer hears nothing, by definition. */
+    accept(message) {
+        if (this.closed || this._status !== 'connected')
+            return;
+        for (const h of [...this.handlers])
+            h(message);
+    }
+    onMessage(handler) {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+    onStatus(handler) {
+        this.statusHandlers.add(handler);
+        return () => this.statusHandlers.delete(handler);
+    }
+    connect() {
+        if (this.closed || this._status === 'connected')
+            return;
+        this.setStatus('connected');
+    }
+    disconnect() {
+        if (this._status === 'disconnected')
+            return;
+        this.setStatus('disconnected');
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.disconnect();
+        this.closed = true;
+        this.hub.detach(this);
+        this.handlers.clear();
+        this.statusHandlers.clear();
+    }
+    setStatus(next) {
+        this._status = next;
+        for (const h of [...this.statusHandlers])
+            h(next);
+    }
+}
+exports.MemoryTransport = MemoryTransport;
+//# sourceMappingURL=memory.js.map

package/src/libs/engine/src/sync/transports/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../../../../../engine/src/sync/transports/memory.ts"],"names":[],"mappings":"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"}

package/src/libs/engine/src/sync/transports/unreliable.d.ts

@@ -0,0 +1,59 @@
+import type { ActorId } from '../../collab/op';
+import type { SyncMessage } from '../protocol';
+import { MemoryHub, MemoryTransport } from './memory';
+/** Deterministic PRNG (mulberry32). A fuzz you cannot replay is an anecdote. */
+export declare function mulberry32(seed: number): () => number;
+export interface UnreliableOptions {
+    seed?: number;
+    /** P(message is simply never delivered). */
+    dropRate?: number;
+    /** P(message is delivered more than once). */
+    duplicateRate?: number;
+    /** P(message is held in flight instead of delivered now) — this is what reorders. */
+    delayRate?: number;
+    /** Max extra copies when duplicating. */
+    maxDuplicates?: number;
+}
+/**
+ * A `MemoryHub` with the network's malice put back.
+ *
+ * Same API, same adapters, same protocol — the ONLY difference is that this one behaves
+ * like the internet. If the sync layer is correct, nothing above it needs to change; if
+ * it is not, this is where you find out.
+ */
+export declare class UnreliableHub extends MemoryHub {
+    private readonly rand;
+    private readonly inFlight;
+    private dropRate;
+    private duplicateRate;
+    private delayRate;
+    private readonly maxDuplicates;
+    /** What the network actually did. Asserted on — a fuzz whose faults never fired is a lie. */
+    readonly faults: {
+        dropped: number;
+        duplicated: number;
+        delayed: number;
+        delivered: number;
+    };
+    constructor(options?: UnreliableOptions);
+    deliver(from: MemoryTransport, message: SyncMessage): void;
+    /**
+     * Release some of the in-flight queue, in a RANDOM order.
+     *
+     * The random order is the point. A FIFO flush would only ever produce late delivery, and
+     * late-but-ordered is the easy case — the LWW gate handles it alone. Releasing out of
+     * order is what lets a `set` land before its `add`, which is the case that used to be
+     * unrecoverable and is the reason `CausalBuffer` exists.
+     */
+    step(fraction?: number): number;
+    /**
+     * Stop breaking things. The network has recovered; from here on it is a plain, honest
+     * bus. Anything still lost was lost DURING the storm, and anti-entropy — not the
+     * transport — is what has to find it.
+     */
+    heal(): void;
+    /** Deliver everything still in flight. */
+    settle(): void;
+    get inFlightCount(): number;
+    connect(actor: ActorId): MemoryTransport;
+}

package/src/libs/engine/src/sync/transports/unreliable.js

@@ -0,0 +1,153 @@
+"use strict";
+// Wave 9 — Card 5: THE HOSTILE TRANSPORT.
+//
+// This is the most important file in the card, and it is a test fixture that ships.
+//
+// A transport that works is not evidence of anything. The in-memory hub delivers every
+// message exactly once, in order, instantly — and under those conditions a completely
+// broken sync layer looks perfect. Every bug this card exists to prevent (the causal
+// drop, the frontier hole, the coalescer that keeps the wrong write) is INVISIBLE on a
+// healthy channel and fatal on a real one. So the only way to know whether the
+// composition holds is to build a channel that behaves like the worst afternoon your
+// users will ever have, and demand convergence anyway.
+//
+// It does, on purpose, all at once, with a seeded PRNG so a failure is a bug report and
+// not a ghost story:
+//
+//   DROPS      — a message vanishes. Nothing retransmits it. The ONLY thing that ever
+//                recovers it is an anti-entropy round, which is exactly the mechanism
+//                under test.
+//   DUPLICATES — a message is delivered twice (or five times). Every real transport does
+//                this; a WebSocket reconnect replays, a peer re-sends on timeout, a mesh
+//                relays the same op from two directions.
+//   REORDERS   — messages are held and released out of order, so a `set` overtakes the
+//                `add` it depends on. This is the one that used to be unrecoverable.
+//   DELAYS     — a message arrives after later messages, and after the peer has already
+//                edited the same register. The LWW gate must REFUSE it.
+//   PARTITIONS — `disconnect()` / `connect()`, so both halves edit blind and must merge.
+//
+// WHY DELIVERY IS PUMPED BY HAND (`step()`), NOT BY A TIMER
+// A fuzz that depends on wall-clock timers is a fuzz that fails once a fortnight on CI
+// for reasons no one can reproduce, and gets deleted within a month. Here the test IS the
+// clock: `step()` releases some of the in-flight queue, and the harness decides when.
+// Nothing is racing anything, the seed reproduces the failure exactly, and a red test is
+// a bug rather than a mood.
+//
+// WHY THE NETWORK IS HEALED BEFORE THE FINAL ASSERT
+// Convergence under PERMANENT loss is impossible — an op that is never delivered, by any
+// route, at any time, cannot be merged, and no algorithm in the literature claims
+// otherwise. So the shape of an honest test is: be savage while they edit, then heal, then
+// run anti-entropy, THEN demand byte-identical documents. The savagery is what creates the
+// holes; the healing is what lets the repair prove it can close them. A fuzz that never
+// heals proves nothing except that the assert is unreachable.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnreliableHub = void 0;
+exports.mulberry32 = mulberry32;
+const memory_1 = require("./memory");
+/** Deterministic PRNG (mulberry32). A fuzz you cannot replay is an anecdote. */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * A `MemoryHub` with the network's malice put back.
+ *
+ * Same API, same adapters, same protocol — the ONLY difference is that this one behaves
+ * like the internet. If the sync layer is correct, nothing above it needs to change; if
+ * it is not, this is where you find out.
+ */
+class UnreliableHub extends memory_1.MemoryHub {
+    constructor(options = {}) {
+        var _a, _b, _c, _d, _e;
+        super();
+        this.inFlight = [];
+        /** What the network actually did. Asserted on — a fuzz whose faults never fired is a lie. */
+        this.faults = { dropped: 0, duplicated: 0, delayed: 0, delivered: 0 };
+        this.rand = mulberry32((_a = options.seed) !== null && _a !== void 0 ? _a : 1);
+        this.dropRate = (_b = options.dropRate) !== null && _b !== void 0 ? _b : 0.2;
+        this.duplicateRate = (_c = options.duplicateRate) !== null && _c !== void 0 ? _c : 0.15;
+        this.delayRate = (_d = options.delayRate) !== null && _d !== void 0 ? _d : 0.35;
+        this.maxDuplicates = (_e = options.maxDuplicates) !== null && _e !== void 0 ? _e : 2;
+    }
+    deliver(from, message) {
+        this.traffic.push({ from: from.actor, message });
+        for (const port of [...this.ports]) {
+            if (port === from)
+                continue;
+            if (this.rand() < this.dropRate) {
+                this.faults.dropped++;
+                continue;
+            }
+            // A structured-clone stand-in. It is not decoration: without it, two "peers" in one
+            // process share op OBJECTS, and a bug where one peer mutates an op in place would
+            // be invisible here and explode across a real socket. Peers must not share memory.
+            const copy = () => JSON.parse(JSON.stringify(message));
+            const copies = 1 + (this.rand() < this.duplicateRate ? 1 + Math.floor(this.rand() * this.maxDuplicates) : 0);
+            if (copies > 1)
+                this.faults.duplicated += copies - 1;
+            for (let i = 0; i < copies; i++) {
+                if (this.rand() < this.delayRate) {
+                    this.faults.delayed++;
+                    this.inFlight.push({ to: port, message: copy() });
+                }
+                else {
+                    this.faults.delivered++;
+                    port.accept(copy());
+                }
+            }
+        }
+    }
+    /**
+     * Release some of the in-flight queue, in a RANDOM order.
+     *
+     * The random order is the point. A FIFO flush would only ever produce late delivery, and
+     * late-but-ordered is the easy case — the LWW gate handles it alone. Releasing out of
+     * order is what lets a `set` land before its `add`, which is the case that used to be
+     * unrecoverable and is the reason `CausalBuffer` exists.
+     */
+    step(fraction = 0.5) {
+        if (this.inFlight.length === 0)
+            return 0;
+        const n = Math.max(1, Math.floor(this.inFlight.length * fraction));
+        let released = 0;
+        for (let i = 0; i < n && this.inFlight.length > 0; i++) {
+            const idx = Math.floor(this.rand() * this.inFlight.length);
+            const [item] = this.inFlight.splice(idx, 1);
+            // A held message for a peer who has since dropped is simply lost — which is exactly
+            // what a real network does to a packet whose destination went away, and exactly the
+            // hole anti-entropy has to be able to close.
+            item.to.accept(item.message);
+            this.faults.delivered++;
+            released++;
+        }
+        return released;
+    }
+    /**
+     * Stop breaking things. The network has recovered; from here on it is a plain, honest
+     * bus. Anything still lost was lost DURING the storm, and anti-entropy — not the
+     * transport — is what has to find it.
+     */
+    heal() {
+        this.dropRate = 0;
+        this.duplicateRate = 0;
+        this.delayRate = 0;
+    }
+    /** Deliver everything still in flight. */
+    settle() {
+        while (this.inFlight.length > 0)
+            this.step(1);
+    }
+    get inFlightCount() {
+        return this.inFlight.length;
+    }
+    connect(actor) {
+        return super.connect(actor);
+    }
+}
+exports.UnreliableHub = UnreliableHub;
+//# sourceMappingURL=unreliable.js.map

package/src/libs/engine/src/sync/transports/unreliable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreliable.js","sourceRoot":"","sources":["../../../../../../../engine/src/sync/transports/unreliable.ts"],"names":[],"mappings":"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"}

package/src/libs/engine/src/sync/transports/websocket.d.ts

@@ -0,0 +1,60 @@
+import type { SyncMessage } from '../protocol';
+import type { SyncTransport, TransportStatus, Unsubscribe } from '../transport';
+/** The standard WebSocket surface — satisfied by the browser global AND by `ws`. */
+export interface WebSocketLike {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    readyState: number;
+    onopen: ((event?: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event?: unknown) => void) | null;
+    onerror: ((event?: unknown) => void) | null;
+}
+export interface WebSocketTransportOptions {
+    url: string;
+    /** The constructor. Defaults to the global. `ws` satisfies this in Node. */
+    socketFactory?: (url: string) => WebSocketLike;
+    /**
+     * Reconnect backoff. The first retry waits `reconnectBaseMs`, then doubles to a cap.
+     *
+     * NOT a constant delay: every tab reconnects the instant a server restarts, and a fixed
+     * retry turns that into a synchronised stampede that knocks the server back over. Set
+     * `reconnect: false` to own the policy yourself.
+     */
+    reconnect?: boolean;
+    reconnectBaseMs?: number;
+    reconnectMaxMs?: number;
+    /** Injectable, so the backoff test does not take 30 seconds of wall clock. */
+    setTimer?: (cb: () => void, ms: number) => unknown;
+    clearTimer?: (h: unknown) => void;
+}
+export declare class WebSocketTransport implements SyncTransport {
+    private readonly options;
+    private socket;
+    private readonly handlers;
+    private readonly statusHandlers;
+    private _status;
+    private closed;
+    /** Deliberate `disconnect()` must NOT trigger the auto-reconnect. */
+    private intentionalClose;
+    private retryTimer;
+    private retryDelay;
+    private readonly factory;
+    private readonly setTimerFn;
+    private readonly clearTimerFn;
+    /** Reconnect attempts made. Asserted on by the backoff test. */
+    attempts: number;
+    constructor(options: WebSocketTransportOptions);
+    get status(): TransportStatus;
+    connect(): void;
+    private scheduleRetry;
+    send(message: SyncMessage): void;
+    onMessage(handler: (m: SyncMessage) => void): Unsubscribe;
+    onStatus(handler: (s: TransportStatus) => void): Unsubscribe;
+    disconnect(): void;
+    close(): void;
+    private cancelRetry;
+    private setStatus;
+}