@grafloria/element 0.3.20 → 0.3.22

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

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

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

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

@@ -1,46 +0,0 @@
-/**
- * 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;
-};