@grafloria/element 0.3.20 → 0.3.21

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

@@ -1,117 +0,0 @@
-"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

@@ -1,38 +0,0 @@
-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

@@ -1,111 +0,0 @@
-"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

@@ -1,59 +0,0 @@
-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

@@ -1,153 +0,0 @@
-"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

@@ -1,60 +0,0 @@
-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;
-}