@grafloria/element 0.3.17 → 0.3.19

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/transports/websocket.js.map

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

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/sync/version-vector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-vector.js","sourceRoot":"","sources":["../../../../../../engine/src/sync/version-vector.ts"],"names":[],"mappings":";AAAA,qDAAqD;AACrD,EAAE;AACF,uFAAuF;AACvF,uFAAuF;AACvF,qFAAqF;AACrF,wEAAwE;AACxE,EAAE;AACF,8EAA8E;AAC9E,sFAAsF;AACtF,8EAA8E;AAC9E,EAAE;AACF,wFAAwF;AACxF,wFAAwF;AACxF,kFAAkF;AAClF,sBAAsB;AACtB,EAAE;AACF,6EAA6E;AAC7E,yBAAyB;AACzB,+EAA+E;AAC/E,qEAAqE;AACrE,kEAAkE;AAClE,iEAAiE;AACjE,EAAE;AACF,oFAAoF;AACpF,uFAAuF;AACvF,kCAAkC;AAClC,EAAE;AACF,8EAA8E;AAC9E,oEAAoE;AACpE,8EAA8E;AAC9E,EAAE;AACF,uFAAuF;AACvF,qFAAqF;AACrF,yFAAyF;AACzF,oCAAoC;AACpC,EAAE;AACF,kFAAkF;AAClF,mFAAmF;AACnF,oFAAoF;AACpF,uDAAuD;AACvD,EAAE;AACF,8DAA8D;AAC9D,qEAAqE;AACrE,0FAA0F;AAC1F,EAAE;AACF,oFAAoF;AACpF,gBAAgB;AAChB,EAAE;AACF,8EAA8E;AAC9E,kCAAkC;AAClC,8EAA8E;AAC9E,EAAE;AACF,kDAAkD;AAClD,EAAE;AACF,0FAA0F;AAC1F,mFAAmF;AACnF,sFAAsF;AACtF,sFAAsF;AACtF,oCAAoC;AACpC,EAAE;AACF,qFAAqF;AACrF,yFAAyF;AACzF,oFAAoF;AACpF,uFAAuF;AACvF,0FAA0F;AAC1F,wDAAwD;AACxD,EAAE;AACF,0FAA0F;AAC1F,yFAAyF;AACzF,UAAU;AACV,EAAE;AACF,0FAA0F;AAC1F,mFAAmF;AACnF,yFAAyF;AACzF,qFAAqF;AACrF,0CAA0C;;;AAwG1C,4BAuDC;AA5JD,qCAA0C;AAc1C;;;;;;;;GAQG;AACH,SAAS,KAAK,CAAC,CAAS;IACtB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACd,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;IACzC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,KAAK,GAAkB,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAE3D;;;;;;GAMG;AACH,MAAa,aAAa;IAA1B;QACmB,WAAM,GAAG,IAAI,GAAG,EAA0B,CAAC;IA6C9D,CAAC;IA3CC,4EAA4E;IAC5E,OAAO,CAAC,EAAM;QACZ,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE;gBACxB,GAAG,EAAE,EAAE,CAAC,KAAK;gBACb,KAAK,EAAE,CAAC;gBACR,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC;aACtB,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,IAAI,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG;YAAE,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC;QACvC,CAAC,CAAC,KAAK,EAAE,CAAC;QACV,iFAAiF;QACjF,oFAAoF;QACpF,4BAA4B;QAC5B,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED,UAAU,CAAC,GAAiB;QAC1B,KAAK,MAAM,EAAE,IAAI,GAAG;YAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,QAAQ,CAAC,KAAc;;QACrB,OAAO,MAAA,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,mCAAI,KAAK,CAAC;IACzC,CAAC;IAED,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED,MAAM;QACJ,MAAM,GAAG,GAAsB,EAAE,CAAC;QAClC,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM;YAAE,GAAG,CAAC,KAAK,CAAC,qBAAQ,CAAC,CAAE,CAAC;QAC5D,OAAO,GAAG,CAAC;IACb,CAAC;IAED,oFAAoF;IACpF,MAAM,CAAC,OAAO,CAAC,GAAiB;QAC9B,MAAM,EAAE,GAAG,IAAI,aAAa,EAAE,CAAC;QAC/B,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACnB,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AA9CD,sCA8CC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,QAAQ,CACtB,IAAmB,EACnB,MAAyB;;IAEzB,0EAA0E;IAC1E,MAAM,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAC;IACzC,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;;YACnB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,GAAG,GAAS,EAAE,CAAC;IACrB,MAAM,cAAc,GAAc,EAAE,CAAC;IAErC,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC;QACnC,MAAM,EAAE,GAAG,MAAA,MAAM,CAAC,KAAK,CAAC,mCAAI,KAAK,CAAC;QAElC,gFAAgF;QAChF,iFAAiF;QACjF,4BAA4B;QAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACrB,IAAI,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC;gBACvB,KAAK,EAAE,CAAC;gBACR,IAAI,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QAED,gFAAgF;QAChF,iFAAiF;QACjF,QAAQ;QACR,EAAE;QACF,oFAAoF;QACpF,mFAAmF;QACnF,kFAAkF;QAClF,mFAAmF;QACnF,6DAA6D;QAC7D,EAAE;QACF,sFAAsF;QACtF,mFAAmF;QACnF,MAAM,KAAK,GAAG,KAAK,KAAK,EAAE,CAAC,KAAK,IAAI,IAAI,KAAK,EAAE,CAAC,IAAI,CAAC;QAErD,IAAI,KAAK,EAAE,CAAC;YACV,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC3B,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;YACjB,SAAS;QACX,CAAC;QAED,KAAK,MAAM,EAAE,IAAI,GAAG;YAAE,IAAI,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG;gBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,GAAG,CAAC,IAAI,CAAC,eAAU,CAAC,CAAC;IACrB,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,cAAc,EAAE,CAAC;AACtC,CAAC"}

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