@grafloria/element 0.3.18 → 0.3.20

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