@grafloria/element 0.3.18 → 0.3.20

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

@@ -0,0 +1,210 @@
+"use strict";
+// Wave 9 — Card 5: the WebSocket transport.
+//
+// ---------------------------------------------------------------------------
+// WHY THIS DOES NOT `import WebSocket from 'ws'`, AND WHY THAT IS THE WHOLE POINT
+// ---------------------------------------------------------------------------
+//
+// It programs against the WebSocket INTERFACE (`send`/`close`/`onopen`/`onmessage`/
+// `onclose`/`onerror`), never against an implementation. Two things fall out of that, and
+// both of them matter:
+//
+//   • The engine gains ZERO new dependencies. `@grafloria/engine` is a browser library; adding
+//     `ws` to it to satisfy a Node test would put a Node socket implementation in every
+//     user's bundle to make a test go green. That trade is never worth it.
+//   • It becomes PROVABLE. `websocket-transport.spec.ts` starts a REAL `ws` server on a
+//     real port, connects two REAL sockets to it, and drives two peers through a real
+//     document edit and a real mid-session reconnect. `ws` is a devDependency of the
+//     workspace, and it never crosses into the library.
+//
+// So this is not "a WebSocket adapter we could not test". It is a WebSocket adapter tested
+// against a real socket, over a real TCP connection, on localhost. What I did NOT do is
+// ship a SERVER — see below.
+//
+// ---------------------------------------------------------------------------
+// THE SERVER: NOT SHIPPED, AND DELIBERATELY
+// ---------------------------------------------------------------------------
+//
+// A production relay needs auth, room membership, persistence, backpressure, rate limits
+// and an ops story. None of that belongs in a rendering engine, and a half-server that
+// pretends otherwise is worse than none: people deploy it.
+//
+// The server contract, in its entirety, is ONE SENTENCE:
+//
+//     Broadcast every frame you receive to every other socket in the room, verbatim.
+//
+// No parsing, no ordering, no storage, no understanding of ops. That is why the test's
+// server is nine lines, and those nine lines are the reference implementation:
+//
+//     wss.on('connection', (socket) => {
+//       socket.on('message', (data) => {
+//         for (const peer of wss.clients) {
+//           if (peer !== socket && peer.readyState === 1) peer.send(data);
+//         }
+//       });
+//     });
+//
+// If your server does more than that, the extra is YOUR product's (auth, persistence),
+// not this protocol's. The catch-up, the ordering and the merge are all done by the peers.
+//
+// WEBRTC. The card also named it, and I have not shipped it. A DataChannel presents the
+// same five members this class programs against (`send`, `close`, `onopen`, `onmessage`,
+// `onclose`), so the transport itself would be a near-copy of this file — but the part
+// that is actually WebRTC is the SIGNALLING (offer/answer/ICE exchange), which needs a
+// signalling server and two real browsers to prove, and I cannot prove it here. Shipping a
+// WebRTC adapter I could only unit-test against a mocked RTCDataChannel would be exactly
+// the "machinery wired to nothing" this codebase keeps finding. So: not shipped, and the
+// seam it would plug into is this file's interface, unchanged.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketTransport = void 0;
+const OPEN = 1;
+class WebSocketTransport {
+    constructor(options) {
+        var _a, _b, _c, _d;
+        this.options = options;
+        this.socket = null;
+        this.handlers = new Set();
+        this.statusHandlers = new Set();
+        this._status = 'disconnected';
+        this.closed = false;
+        /** Deliberate `disconnect()` must NOT trigger the auto-reconnect. */
+        this.intentionalClose = false;
+        this.retryTimer = null;
+        /** Reconnect attempts made. Asserted on by the backoff test. */
+        this.attempts = 0;
+        this.retryDelay = (_a = options.reconnectBaseMs) !== null && _a !== void 0 ? _a : 250;
+        this.setTimerFn = (_b = options.setTimer) !== null && _b !== void 0 ? _b : ((cb, ms) => setTimeout(cb, ms));
+        this.clearTimerFn =
+            (_c = options.clearTimer) !== null && _c !== void 0 ? _c : ((h) => clearTimeout(h));
+        this.factory =
+            (_d = options.socketFactory) !== null && _d !== void 0 ? _d : ((url) => {
+                const Ctor = globalThis.WebSocket;
+                if (!Ctor)
+                    throw new Error('WebSocketTransport: no global WebSocket; pass socketFactory.');
+                return new Ctor(url);
+            });
+    }
+    get status() {
+        return this._status;
+    }
+    connect() {
+        if (this.closed || this.socket)
+            return;
+        this.intentionalClose = false;
+        this.attempts++;
+        const socket = this.factory(this.options.url);
+        this.socket = socket;
+        socket.onopen = () => {
+            var _a;
+            // Reset the backoff on a SUCCESSFUL open, not on an attempt. Resetting on attempt
+            // means a server that accepts the TCP connection and then immediately dies gets
+            // hammered at the base delay forever.
+            this.retryDelay = (_a = this.options.reconnectBaseMs) !== null && _a !== void 0 ? _a : 250;
+            this.setStatus('connected');
+        };
+        socket.onmessage = (event) => {
+            if (this.closed)
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(String(event.data));
+            }
+            catch (_a) {
+                // A garbage frame must not take the document down. Someone else's protocol on our
+                // port is a config error, not a reason to lose a user's work.
+                return;
+            }
+            if (!msg || typeof msg.t !== 'string')
+                return;
+            for (const h of [...this.handlers])
+                h(msg);
+        };
+        socket.onclose = () => {
+            this.socket = null;
+            this.setStatus('disconnected');
+            if (this.closed || this.intentionalClose)
+                return;
+            if (this.options.reconnect === false)
+                return;
+            this.scheduleRetry();
+        };
+        // `onerror` deliberately does nothing. A WebSocket error is ALWAYS followed by a
+        // close, so reconnecting from both fires two sockets for one failure — and the second
+        // one is orphaned, invisible, and holds the connection open forever. One recovery
+        // path, and it is `onclose`.
+        socket.onerror = () => undefined;
+    }
+    scheduleRetry() {
+        var _a;
+        if (this.retryTimer !== null)
+            return;
+        const delay = this.retryDelay;
+        this.retryDelay = Math.min(this.retryDelay * 2, (_a = this.options.reconnectMaxMs) !== null && _a !== void 0 ? _a : 10000);
+        this.retryTimer = this.setTimerFn(() => {
+            this.retryTimer = null;
+            if (!this.closed && !this.intentionalClose)
+                this.connect();
+        }, delay);
+    }
+    send(message) {
+        if (this.closed)
+            return;
+        const socket = this.socket;
+        // Sending into a socket that is not OPEN throws in the browser. A dropped send is not
+        // a lost edit — the op is in the log, and the reconnect's sync round delivers it —
+        // whereas an exception thrown out of a pointermove handler kills the drag.
+        if (!socket || socket.readyState !== OPEN)
+            return;
+        socket.send(JSON.stringify(message));
+    }
+    onMessage(handler) {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+    onStatus(handler) {
+        this.statusHandlers.add(handler);
+        return () => this.statusHandlers.delete(handler);
+    }
+    disconnect() {
+        this.intentionalClose = true;
+        this.cancelRetry();
+        const socket = this.socket;
+        this.socket = null;
+        if (socket) {
+            socket.onmessage = null;
+            socket.onclose = null;
+            socket.onopen = null;
+            socket.onerror = null;
+            try {
+                socket.close();
+            }
+            catch (_a) {
+                /* already dead */
+            }
+        }
+        this.setStatus('disconnected');
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.disconnect();
+        this.closed = true;
+        this.handlers.clear();
+        this.statusHandlers.clear();
+    }
+    cancelRetry() {
+        if (this.retryTimer !== null) {
+            this.clearTimerFn(this.retryTimer);
+            this.retryTimer = null;
+        }
+    }
+    setStatus(next) {
+        if (this._status === next)
+            return;
+        this._status = next;
+        for (const h of [...this.statusHandlers])
+            h(next);
+    }
+}
+exports.WebSocketTransport = WebSocketTransport;
+//# sourceMappingURL=websocket.js.map

package/src/libs/engine/src/sync/version-vector.d.ts

@@ -0,0 +1,47 @@
+import type { ActorId, Op } from '../collab/op';
+/** What one peer holds from one actor. Three numbers; see the header for why not one. */
+export interface ActorFrontier {
+    /** Highest clock seen from this actor. */
+    max: number;
+    /** How many of this actor's ops we hold. A hole below `max` shows up here. */
+    count: number;
+    /** Order-independent fold of the clocks held. Catches a hole `count` cannot see. */
+    hash: number;
+}
+export type VersionVectorJSON = Record<ActorId, ActorFrontier>;
+/**
+ * A peer's exact position in the shared history, per actor.
+ *
+ * Fed ONLY with ops the log genuinely accepted (`Replica.receive()` returns exactly
+ * those). Feed it a duplicate and `count` over-counts, which fakes a hole and triggers a
+ * pointless repair — wasteful, not wrong, but the discipline is worth keeping.
+ */
+export declare class VersionVector {
+    private readonly actors;
+    /** Record ONE op we now hold. Must be genuinely new — see the class doc. */
+    observe(op: Op): void;
+    observeAll(ops: Iterable<Op>): void;
+    frontier(actor: ActorId): ActorFrontier;
+    get actorCount(): number;
+    toJSON(): VersionVectorJSON;
+    /** Rebuild from a log — used on resume-from-disk, and by the tests as an oracle. */
+    static fromOps(ops: Iterable<Op>): VersionVector;
+}
+/**
+ * THE CATCH-UP DELTA: which of `ours` does a peer with frontier `remote` not have?
+ *
+ * Two tiers, and the tier is chosen PER ACTOR:
+ *
+ *   FAST  — our digest of that actor's ops at-or-below the peer's `max` matches theirs.
+ *           Their frontier is honest; send only the tail above `max`.
+ *   REPAIR— it does not match. There is a hole somewhere below their max and neither of
+ *           us can say where. Send everything we have from that actor and let their log
+ *           de-duplicate. Over-sending is free. Under-sending loses the document.
+ *
+ * Returns ops in TOTAL ORDER — so a receiver that applies them in array order applies an
+ * `add` before the `set`s that depend on it, and the causal buffer has nothing to do.
+ */
+export declare function deltaFor(ours: readonly Op[], remote: VersionVectorJSON): {
+    ops: Op[];
+    repairedActors: ActorId[];
+};

package/src/libs/engine/src/sync/version-vector.js

@@ -0,0 +1,218 @@
+"use strict";
+// Wave 9 — Card 5: WHAT DOES THIS PEER ALREADY HAVE?
+//
+// Every reconnect, every join and every anti-entropy round asks that one question, and
+// answering it wrong is how a collaboration engine silently diverges. This file is the
+// answer, and it took three attempts to get right. Both wrong ones are written down,
+// because both look correct and one of them is already in the codebase.
+//
+// ---------------------------------------------------------------------------
+// WRONG ANSWER #1 — THE SCALAR WATERMARK. (`OpLog.since(clock)`, which exists TODAY.)
+// ---------------------------------------------------------------------------
+//
+// "Ask for everything with a clock greater than mine." It is the obvious thing, the log
+// already has the method, and it is BROKEN — because a Lamport clock is not a timeline.
+// Two peers hold the same clock value at the same time all the time; that is what
+// "concurrent" MEANS.
+//
+//     Alice and Bob are both at clock 10 (they have seen each other's work).
+//     The network drops.
+//     Alice edits → her op is clock 11.   Bob edits → his op is ALSO clock 11.
+//     They reconnect. Alice asks Bob: "everything after 11, please."
+//     Bob's op IS 11. `o.clock > 11` is false. Bob sends NOTHING.
+//     Alice never learns Bob's edit. Forever. No error anywhere.
+//
+// One dropped connection and two users are permanently editing different documents.
+// `version-vector.spec.ts` reproduces exactly this, against the real `since()`, and it
+// is the reason this file exists.
+//
+// ---------------------------------------------------------------------------
+// WRONG ANSWER #2 — THE PLAIN VERSION VECTOR. (per-actor max clock)
+// ---------------------------------------------------------------------------
+//
+// "Per actor, remember the highest clock I have seen from them; send me anything above
+// it." This is what Yjs and Automerge do, and for THEM it is exactly right — because
+// their per-actor counters are CONTIGUOUS (1,2,3,…), so "I have up to 7 from Bob" really
+// does mean "I have 1..7 from Bob".
+//
+// A Lamport clock is NOT contiguous. It leaps whenever its owner observes a peer:
+// Bob's own ops might be clocked 3, 5, 12, 13, 40. So "my max from Bob is 40" says
+// nothing at all about whether I have Bob's op at 12. Reorder or drop one op in the
+// middle and the max keeps rising right over the hole:
+//
+//     I hold Bob@3 and Bob@40. Bob@12 was dropped in transit.
+//     My vector says max[Bob] = 40. I ask for "> 40". I get nothing.
+//     Bob@12 is gone forever, and my vector cheerfully reports that I am fully caught up.
+//
+// That hole is not hypothetical — the hostile-transport fuzz drills it in the first
+// dozen trials.
+//
+// ---------------------------------------------------------------------------
+// THE ANSWER: A DIGESTED FRONTIER
+// ---------------------------------------------------------------------------
+//
+// Per actor we keep three numbers instead of one:
+//
+//     max    — highest clock seen from that actor   (the cheap "send me the tail" filter)
+//     count  — HOW MANY ops we hold from that actor (detects a hole below the max)
+//     hash   — an order-independent fold of their clocks (detects a hole that `count`
+//              cannot see: I have Bob@{3,40}, you have Bob@{12,40} — same count, same
+//              max, DIFFERENT SETS)
+//
+// The responder compares its own three numbers, restricted to `clock <= remote.max`,
+// against the requester's. If they agree, the requester's frontier is TRUSTWORTHY and we
+// send only the tail above `max` — the cheap path, and the only path a healthy FIFO
+// transport ever takes. If they disagree there is a hole, and we send EVERY op we have
+// from that actor. The requester's log de-duplicates, so over-sending costs bandwidth and
+// nothing else, while under-sending costs the document.
+//
+// Cost: O(number of actors) on the wire, always. The expensive repair fires only when the
+// network actually lost something in the middle, which is precisely when you want to pay
+// for it.
+//
+// (Why not a Merkle tree, which is what a database would do? Because the whole delta here
+// is "the ops from one actor", the actor count is a handful, and a tree would be a
+// hundred lines of machinery to save a payload nobody has ever measured. When the log is
+// big enough for that to hurt, the right move is a compacted snapshot, not a fancier
+// digest — and that is a different card.)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VersionVector = void 0;
+exports.deltaFor = deltaFor;
+const op_1 = require("../collab/op");
+/**
+ * Mix one clock into a 32-bit avalanche.
+ *
+ * XOR-folding raw clocks would be a disaster — {3,40} and {40,3} are the same set (fine)
+ * but {1,2} and {3,0} would collide (not fine). A real avalanche makes an accidental
+ * collision a ~2^-32 event, and a collision merely means we take the CHEAP path when we
+ * should have repaired — which the next anti-entropy round, with a different set, catches
+ * anyway. Failure is delayed, never permanent.
+ */
+function mix32(n) {
+    let x = n | 0;
+    x = Math.imul(x ^ (x >>> 16), 0x45d9f3b);
+    x = Math.imul(x ^ (x >>> 16), 0x45d9f3b);
+    return (x ^ (x >>> 16)) >>> 0;
+}
+const EMPTY = { max: 0, count: 0, hash: 0 };
+/**
+ * A peer's exact position in the shared history, per actor.
+ *
+ * Fed ONLY with ops the log genuinely accepted (`Replica.receive()` returns exactly
+ * those). Feed it a duplicate and `count` over-counts, which fakes a hole and triggers a
+ * pointless repair — wasteful, not wrong, but the discipline is worth keeping.
+ */
+class VersionVector {
+    constructor() {
+        this.actors = new Map();
+    }
+    /** Record ONE op we now hold. Must be genuinely new — see the class doc. */
+    observe(op) {
+        const f = this.actors.get(op.actor);
+        if (!f) {
+            this.actors.set(op.actor, {
+                max: op.clock,
+                count: 1,
+                hash: mix32(op.clock),
+            });
+            return;
+        }
+        if (op.clock > f.max)
+            f.max = op.clock;
+        f.count++;
+        // XOR, so the fold is order-independent: two peers that received the same ops in
+        // different orders must produce the SAME digest, or every sync round would "repair"
+        // a hole that is not there.
+        f.hash = (f.hash ^ mix32(op.clock)) >>> 0;
+    }
+    observeAll(ops) {
+        for (const op of ops)
+            this.observe(op);
+    }
+    frontier(actor) {
+        var _a;
+        return (_a = this.actors.get(actor)) !== null && _a !== void 0 ? _a : EMPTY;
+    }
+    get actorCount() {
+        return this.actors.size;
+    }
+    toJSON() {
+        const out = {};
+        for (const [actor, f] of this.actors)
+            out[actor] = Object.assign({}, f);
+        return out;
+    }
+    /** Rebuild from a log — used on resume-from-disk, and by the tests as an oracle. */
+    static fromOps(ops) {
+        const vv = new VersionVector();
+        vv.observeAll(ops);
+        return vv;
+    }
+}
+exports.VersionVector = VersionVector;
+/**
+ * THE CATCH-UP DELTA: which of `ours` does a peer with frontier `remote` not have?
+ *
+ * Two tiers, and the tier is chosen PER ACTOR:
+ *
+ *   FAST  — our digest of that actor's ops at-or-below the peer's `max` matches theirs.
+ *           Their frontier is honest; send only the tail above `max`.
+ *   REPAIR— it does not match. There is a hole somewhere below their max and neither of
+ *           us can say where. Send everything we have from that actor and let their log
+ *           de-duplicate. Over-sending is free. Under-sending loses the document.
+ *
+ * Returns ops in TOTAL ORDER — so a receiver that applies them in array order applies an
+ * `add` before the `set`s that depend on it, and the causal buffer has nothing to do.
+ */
+function deltaFor(ours, remote) {
+    var _a;
+    // Group our log by actor once — the alternative is a full scan per actor.
+    const byActor = new Map();
+    for (const op of ours) {
+        const list = byActor.get(op.actor);
+        if (list)
+            list.push(op);
+        else
+            byActor.set(op.actor, [op]);
+    }
+    const out = [];
+    const repairedActors = [];
+    for (const [actor, ops] of byActor) {
+        const rf = (_a = remote[actor]) !== null && _a !== void 0 ? _a : EMPTY;
+        // Our own digest of this actor's history, RESTRICTED to what the peer claims to
+        // have covered (clock <= their max). Anything above their max is the tail and is
+        // not evidence of anything.
+        let count = 0;
+        let hash = 0;
+        for (const op of ops) {
+            if (op.clock <= rf.max) {
+                count++;
+                hash = (hash ^ mix32(op.clock)) >>> 0;
+            }
+        }
+        // ANY disagreement below their frontier means "we do not hold the same ops down
+        // there", and that is enough — we must not try to be clever about WHO is missing
+        // WHAT.
+        //
+        // The tempting shortcut is `count > rf.count` — "they're behind me, repair; they're
+        // ahead of me, not my problem". It is WRONG, and subtly. I hold Bob@{5}; they hold
+        // Bob@{3,40}. Their count is bigger, so the shortcut concludes they are ahead and
+        // sends nothing — but they are missing Bob@5, which only I have. Both peers reason
+        // that way, both send nothing, and the two edits never meet.
+        //
+        // Count OR hash disagreeing ⇒ repair. When they are genuinely ahead of us we resend a
+        // subset they already have; their log drops it on the floor. Over-sending is free.
+        const holed = count !== rf.count || hash !== rf.hash;
+        if (holed) {
+            repairedActors.push(actor);
+            out.push(...ops);
+            continue;
+        }
+        for (const op of ops)
+            if (op.clock > rf.max)
+                out.push(op);
+    }
+    out.sort(op_1.compareOps);
+    return { ops: out, repairedActors };
+}
+//# sourceMappingURL=version-vector.js.map

package/src/libs/engine/src/template-library/common-templates.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Common Node Templates (Phase 4)
+ * Pre-built templates for common use cases
+ */
+import type { NodeTemplate } from '../templates/NodeTemplate';
+/**
+ * User Avatar Template
+ * Circular node for displaying user information
+ */
+export declare const UserAvatarTemplate: NodeTemplate;
+/**
+ * Card Node Template
+ * Rectangular card for displaying structured content
+ */
+export declare const CardNodeTemplate: NodeTemplate;
+/**
+ * Button Node Template
+ * Interactive button element
+ */
+export declare const ButtonNodeTemplate: NodeTemplate;
+/**
+ * Input Field Template
+ * Form input element
+ */
+export declare const InputFieldTemplate: NodeTemplate;
+/**
+ * Badge/Label Template
+ * Small label or status badge
+ */
+export declare const BadgeLabelTemplate: NodeTemplate;
+/**
+ * Icon Node Template
+ * Simple icon with optional label
+ */
+export declare const IconNodeTemplate: NodeTemplate;
+/**
+ * Export all common templates
+ */
+export declare const CommonTemplates: {
+    UserAvatar: NodeTemplate;
+    CardNode: NodeTemplate;
+    ButtonNode: NodeTemplate;
+    InputField: NodeTemplate;
+    BadgeLabel: NodeTemplate;
+    IconNode: NodeTemplate;
+};