@grafloria/element 0.3.19 → 0.3.21

package/src/libs/engine/src/sync/index.js

@@ -1,41 +0,0 @@
-"use strict";
-// Wave 9 (Collaboration) — Card 5: the transport layer.
-//
-// Card 0 built a Replica that can merge. This makes it MULTIPLAYER: a transport-agnostic
-// SyncAdapter that owns the four things every transport would otherwise get wrong on its
-// own — catch-up after a reconnect, causal readiness, batching, and awareness — plus the
-// presence channel that must never, under any circumstances, enter the op log.
-//
-//   createSyncSession(diagram, transport, { actor })   ← the one call a host makes
-//
-// Transports shipped: in-memory (two panes in one page; the test substrate),
-// BroadcastChannel (real cross-tab multiplayer, no server), WebSocket (proven against a
-// real `ws` server). WebRTC is NOT shipped — see transports/websocket.ts for why.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketTransport = exports.BroadcastChannelTransport = exports.mulberry32 = exports.UnreliableHub = exports.MemoryTransport = exports.MemoryHub = exports.CausalBuffer = exports.coalesce = exports.OpBatcher = exports.deltaFor = exports.VersionVector = exports.Awareness = exports.isDocumentMessage = exports.createSyncSession = exports.SyncAdapter = void 0;
-var sync_adapter_1 = require("./sync-adapter");
-Object.defineProperty(exports, "SyncAdapter", { enumerable: true, get: function () { return sync_adapter_1.SyncAdapter; } });
-Object.defineProperty(exports, "createSyncSession", { enumerable: true, get: function () { return sync_adapter_1.createSyncSession; } });
-var protocol_1 = require("./protocol");
-Object.defineProperty(exports, "isDocumentMessage", { enumerable: true, get: function () { return protocol_1.isDocumentMessage; } });
-var awareness_1 = require("./awareness");
-Object.defineProperty(exports, "Awareness", { enumerable: true, get: function () { return awareness_1.Awareness; } });
-var version_vector_1 = require("./version-vector");
-Object.defineProperty(exports, "VersionVector", { enumerable: true, get: function () { return version_vector_1.VersionVector; } });
-Object.defineProperty(exports, "deltaFor", { enumerable: true, get: function () { return version_vector_1.deltaFor; } });
-var batcher_1 = require("./batcher");
-Object.defineProperty(exports, "OpBatcher", { enumerable: true, get: function () { return batcher_1.OpBatcher; } });
-Object.defineProperty(exports, "coalesce", { enumerable: true, get: function () { return batcher_1.coalesce; } });
-var causal_buffer_1 = require("./causal-buffer");
-Object.defineProperty(exports, "CausalBuffer", { enumerable: true, get: function () { return causal_buffer_1.CausalBuffer; } });
-var memory_1 = require("./transports/memory");
-Object.defineProperty(exports, "MemoryHub", { enumerable: true, get: function () { return memory_1.MemoryHub; } });
-Object.defineProperty(exports, "MemoryTransport", { enumerable: true, get: function () { return memory_1.MemoryTransport; } });
-var unreliable_1 = require("./transports/unreliable");
-Object.defineProperty(exports, "UnreliableHub", { enumerable: true, get: function () { return unreliable_1.UnreliableHub; } });
-Object.defineProperty(exports, "mulberry32", { enumerable: true, get: function () { return unreliable_1.mulberry32; } });
-var broadcast_channel_1 = require("./transports/broadcast-channel");
-Object.defineProperty(exports, "BroadcastChannelTransport", { enumerable: true, get: function () { return broadcast_channel_1.BroadcastChannelTransport; } });
-var websocket_1 = require("./transports/websocket");
-Object.defineProperty(exports, "WebSocketTransport", { enumerable: true, get: function () { return websocket_1.WebSocketTransport; } });
-//# sourceMappingURL=index.js.map

package/src/libs/engine/src/sync/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../engine/src/sync/index.ts"],"names":[],"mappings":";AAAA,wDAAwD;AACxD,EAAE;AACF,yFAAyF;AACzF,yFAAyF;AACzF,yFAAyF;AACzF,+EAA+E;AAC/E,EAAE;AACF,mFAAmF;AACnF,EAAE;AACF,6EAA6E;AAC7E,wFAAwF;AACxF,kFAAkF;;;AAElF,+CAAgE;AAAvD,2GAAA,WAAW,OAAA;AAAE,iHAAA,iBAAiB,OAAA;AAYvC,uCAA+C;AAAtC,6GAAA,iBAAiB,OAAA;AAE1B,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAGlB,mDAA2D;AAAlD,+GAAA,aAAa,OAAA;AAAE,0GAAA,QAAQ,OAAA;AAGhC,qCAAgD;AAAvC,oGAAA,SAAS,OAAA;AAAE,mGAAA,QAAQ,OAAA;AAG5B,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAGrB,8CAAiE;AAAxD,mGAAA,SAAS,OAAA;AAAE,yGAAA,eAAe,OAAA;AACnC,sDAAoE;AAA3D,2GAAA,aAAa,OAAA;AAAE,wGAAA,UAAU,OAAA;AAElC,oEAA2E;AAAlE,8HAAA,yBAAyB,OAAA;AAKlC,oDAA4D;AAAnD,+GAAA,kBAAkB,OAAA"}

package/src/libs/engine/src/sync/protocol.d.ts

@@ -1,74 +0,0 @@
-import type { ActorId, Op } from '../collab/op';
-import type { VersionVectorJSON } from './version-vector';
-/** Anything a peer publishes about ITSELF that is not a document edit. */
-export interface AwarenessState {
-    /** Human name for the badge. */
-    name?: string;
-    /** CSS colour. Derived deterministically from the actor id when absent. */
-    color?: string;
-    /** Pointer position in WORLD coordinates — never screen: peers have different cameras. */
-    cursor?: {
-        x: number;
-        y: number;
-    } | null;
-    /** Entity ids this peer has selected. */
-    selection?: string[];
-    /** Free-form (a "typing…" flag, a viewport rect for follow-mode, …). */
-    [key: string]: unknown;
-}
-/**
- * "I have joined." Carries the sender's frontier so an existing peer can push the
- * newcomer the history it lacks WITHOUT the newcomer having to ask a second time.
- */
-export interface HelloMessage {
-    t: 'hello';
-    from: ActorId;
-    vv: VersionVectorJSON;
-    /** The sender's presence, so peers see the badge on the join frame, not 5s later. */
-    awareness?: AwarenessState;
-}
-/**
- * "This is what I have — send me what I am missing."
- *
- * The anti-entropy request. Sent on join, on RECONNECT, and periodically (a transport
- * that can drop a message can drop an op, and the only thing that repairs that is
- * asking again).
- */
-export interface SyncMessage_ {
-    t: 'sync';
-    from: ActorId;
-    vv: VersionVectorJSON;
-    /**
-     * Ask the recipient to answer with its OWN `sync` so we can push it what IT lacks.
-     * False on the reply, or two peers ping-pong sync requests forever.
-     */
-    reply: boolean;
-}
-/** A batch of document ops. The only message that reaches the op log. */
-export interface OpsMessage {
-    t: 'ops';
-    from: ActorId;
-    ops: Op[];
-}
-/** Ephemeral presence. NEVER reaches the op log. See the header. */
-export interface AwarenessMessage {
-    t: 'awareness';
-    from: ActorId;
-    /** null ⇒ this peer is gone (an explicit, immediate tombstone; the TTL is the backup). */
-    state: AwarenessState | null;
-    /**
-     * Per-peer sequence. Awareness is last-write-wins PER PEER, and a reordering
-     * transport will hand you an old cursor after a new one — without this, the cursor
-     * jumps backwards. It is not a Lamport clock: peers never compare each other's
-     * awareness, only their own successive samples.
-     */
-    seq: number;
-}
-/** "I am leaving." Best-effort — the TTL is what actually guarantees cleanup. */
-export interface ByeMessage {
-    t: 'bye';
-    from: ActorId;
-}
-export type SyncMessage = HelloMessage | SyncMessage_ | OpsMessage | AwarenessMessage | ByeMessage;
-/** True for the ONE message kind that is allowed to touch the durable log. */
-export declare function isDocumentMessage(msg: SyncMessage): msg is OpsMessage;

package/src/libs/engine/src/sync/protocol.js

@@ -1,39 +0,0 @@
-"use strict";
-// Wave 9 (Collaboration) — Card 5: the wire protocol.
-//
-// Five message kinds, all JSON-safe, all small. The protocol is deliberately
-// transport-agnostic: it says nothing about sockets, rooms, servers or framing. A
-// transport's ONLY job is to move a `SyncMessage` from one peer to the others; every
-// decision that matters — batching, catch-up, causal readiness, awareness lifetime —
-// is made above it, in the SyncAdapter, and is therefore tested once and works for
-// every transport.
-//
-// ---------------------------------------------------------------------------
-// THE ONE LINE THAT MATTERS: AWARENESS IS NOT AN OP
-// ---------------------------------------------------------------------------
-//
-// `ops` and `awareness` are DIFFERENT MESSAGE KINDS, and that is not cosmetic — it is
-// the load-bearing separation in this card.
-//
-// A document op is durable, causally ordered, replayable and persisted forever. A cursor
-// position is none of those things: it is ephemeral, emitted at 60Hz, meaningless five
-// seconds later, and meaningless AT ALL once its author closes the tab. Put a cursor in
-// the op log and you have (a) permanently poisoned the document's history with
-// megabytes of mouse jitter, (b) made "replay the log" reproduce someone's mouse
-// movements from last March, and (c) given every cursor sample a Lamport clock, which
-// pushes every real edit's clock into the millions for no reason whatsoever.
-//
-// So awareness travels on the same WIRE and never touches the LOG. Different lifecycle
-// (last-write-wins per peer, expires on timeout), different delivery guarantee (none —
-// dropping a cursor sample costs you nothing, the next one is 16ms away), different
-// storage (a Map that is emptied when you disconnect).
-//
-// There is a test that asserts precisely this: drive a thousand cursor moves through a
-// live adapter and assert the op log is still EMPTY.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isDocumentMessage = isDocumentMessage;
-/** True for the ONE message kind that is allowed to touch the durable log. */
-function isDocumentMessage(msg) {
-    return msg.t === 'ops';
-}
-//# sourceMappingURL=protocol.js.map

package/src/libs/engine/src/sync/protocol.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../../../../engine/src/sync/protocol.ts"],"names":[],"mappings":";AAAA,sDAAsD;AACtD,EAAE;AACF,6EAA6E;AAC7E,kFAAkF;AAClF,qFAAqF;AACrF,qFAAqF;AACrF,mFAAmF;AACnF,mBAAmB;AACnB,EAAE;AACF,8EAA8E;AAC9E,oDAAoD;AACpD,8EAA8E;AAC9E,EAAE;AACF,sFAAsF;AACtF,4CAA4C;AAC5C,EAAE;AACF,yFAAyF;AACzF,uFAAuF;AACvF,wFAAwF;AACxF,+EAA+E;AAC/E,iFAAiF;AACjF,sFAAsF;AACtF,6EAA6E;AAC7E,EAAE;AACF,uFAAuF;AACvF,uFAAuF;AACvF,oFAAoF;AACpF,uDAAuD;AACvD,EAAE;AACF,uFAAuF;AACvF,qDAAqD;;AAqFrD,8CAEC;AAHD,8EAA8E;AAC9E,SAAgB,iBAAiB,CAAC,GAAgB;IAChD,OAAO,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC;AACzB,CAAC"}

package/src/libs/engine/src/sync/sync-adapter.d.ts

@@ -1,243 +0,0 @@
-import type { DiagramModel } from '../models/DiagramModel';
-import { Replica } from '../collab/replica';
-import { type ActorId, type Op } from '../collab/op';
-import { Awareness, type AwarenessState } from './awareness';
-import { type OpBatcherOptions } from './batcher';
-import type { SyncTransport } from './transport';
-import { type VersionVectorJSON } from './version-vector';
-export interface SyncAdapterOptions {
-    /** Batching. `false` sends every op the instant it happens — legal, and a bad idea. */
-    batch?: Omit<OpBatcherOptions, 'onFlush'> | false;
-    /**
-     * Forward ops that were NEW to us on to our other peers.
-     *
-     * OFF by default, because every transport shipped here is a BROADCAST bus — everyone
-     * already got the message, so relaying it doubles the traffic to deliver nothing. Turn
-     * it ON for a point-to-point mesh (WebRTC, a chain of relays) where a peer may be
-     * reachable only through us. It terminates because `Replica.receive()` returns the ops
-     * that were genuinely new, and a re-delivery is new to nobody.
-     */
-    relay?: boolean;
-    /** Periodic anti-entropy, ms. 0 disables it (the tests drive `sync()` by hand). */
-    syncIntervalMs?: number;
-    /** Re-publish our awareness this often so peers do not time us out while we sit still. */
-    heartbeatMs?: number;
-    /** Minimum ms between awareness sends. 60Hz in, ~20Hz out. */
-    awarenessThrottleMs?: number;
-    /** Drop a peer's presence after this long without a word. */
-    awarenessTimeoutMs?: number;
-    /** Injectables, so every timing test is deterministic instead of a race. */
-    setTimer?: (cb: () => void, ms: number) => unknown;
-    clearTimer?: (handle: unknown) => void;
-    setInterval?: (cb: () => void, ms: number) => unknown;
-    clearInterval?: (handle: unknown) => void;
-    now?: () => number;
-}
-/** Counters. Every one of them is something a test asserts on, not decoration. */
-export interface SyncStats {
-    /** Messages handed to the transport. */
-    messagesSent: number;
-    /** Messages taken from the transport. */
-    messagesReceived: number;
-    /** Ops we put on the wire (post-coalescing). */
-    opsSent: number;
-    /** Ops that arrived. */
-    opsReceived: number;
-    /** …of which the log had already seen: duplicate delivery, absorbed. */
-    opsDuplicate: number;
-    /** Ops currently HELD by the causal buffer, waiting for an `add`. */
-    opsHeld: number;
-    /** Anti-entropy rounds we asked for. */
-    syncsRequested: number;
-    /**
-     * Times a peer's frontier turned out to have a HOLE and we resent an actor's history.
-     *
-     * The number that proves the hostile-transport fuzz is not vacuous. If this is 0 after
-     * a thousand lossy trials, the repair path never ran and the test proved nothing.
-     */
-    repairs: number;
-    /** Ops the batcher swallowed because a later write superseded them. */
-    opsCoalesced: number;
-    /** Reconnects observed. */
-    reconnects: number;
-}
-/**
- * Binds one `Replica` to one `SyncTransport`.
- *
- * The replica must be constructed with `onLocalOp` pointing at `adapter.publish` — use
- * {@link createSyncSession}, which does that wiring for you and cannot get it backwards.
- */
-export declare class SyncAdapter {
-    readonly replica: Replica;
-    private readonly transport;
-    private readonly options;
-    readonly awareness: Awareness;
-    private readonly buffer;
-    private readonly vv;
-    /**
-     * Ops we COALESCED AWAY and will therefore never transmit — to anyone, ever.
-     *
-     * They are in our LOG (they really happened) but not in the history we SHARE, so they must
-     * not appear in our frontier or in any catch-up delta we serve. See `sharedHistory()` for
-     * the bug this prevents; it is the difference between "one op per drag" and "the entire
-     * document history, resent on every sync round, forever".
-     */
-    private readonly suppressed;
-    private readonly batcher;
-    private readonly unsubs;
-    private syncTimer;
-    private heartbeatTimer;
-    private awarenessTimer;
-    private awarenessPending;
-    private lastAwarenessSend;
-    private joined;
-    /** Have we ever successfully announced? Distinguishes the first connect from a RECONNECT. */
-    private announced;
-    private disposed;
-    private readonly nowFn;
-    private readonly setTimerFn;
-    private readonly clearTimerFn;
-    private readonly setIntervalFn;
-    private readonly clearIntervalFn;
-    readonly stats: SyncStats;
-    constructor(replica: Replica, transport: SyncTransport, options?: SyncAdapterOptions);
-    get actor(): ActorId;
-    get diagram(): DiagramModel;
-    /** Ops still waiting on an `add` that has not arrived. Should return to 0. */
-    get pendingOps(): Op[];
-    /**
-     * What we tell peers we have.
-     *
-     * THE INVARIANT, and it is worth stating as one because it is the whole correctness
-     * condition of this layer in a single line:
-     *
-     *     frontier() === VersionVector.fromOps(sharedHistory())     — ALWAYS.
-     *
-     * SHARED history, not the local log — an op coalescing withheld is not part of the history
-     * we share with anyone, and advertising it would make every peer chase a hole that can
-     * never be filled. That distinction IS the bug documented on `sharedHistory()`.
-     *
-     * The frontier is a CACHE of that summary, maintained incrementally so we do not rescan
-     * the history on every sync. A cache that disagrees with its source is not a performance
-     * detail; it is a peer lying to the network about what it holds. Claim too much and you
-     * never receive the op you are missing (silent data loss); claim too little and every
-     * round resends an actor's entire history (a silent O(history) amplifier on the flakiest
-     * connections, which is precisely where you can least afford it).
-     *
-     * `sync-adapter.spec.ts` asserts this equality after a full hostile session, which is what
-     * makes it a checked invariant rather than a comment.
-     */
-    frontier(): VersionVectorJSON;
-    /**
-     * Announce ourselves and ask for what we are missing.
-     *
-     * `hello` carries our frontier, so an existing peer can push us the history we lack
-     * without a second round trip — a joining peer should see the document on the first
-     * message, not the third.
-     */
-    join(): void;
-    /** Say goodbye and stop. Best-effort — the peers' TTL is what actually guarantees it. */
-    leave(): void;
-    /**
-     * An anti-entropy round: "here is my frontier; send me what I lack, and tell me yours."
-     *
-     * Called on join, on RECONNECT, and (optionally) on a timer. The timer is not paranoia:
-     * a transport that can drop a message can drop an op, and the ONLY thing that ever
-     * repairs that is asking again.
-     */
-    sync(): void;
-    /** Push any queued local ops onto the wire now. */
-    flush(): void;
-    /**
-     * Our own edits. Wired to `Replica.onLocalOp` — see {@link createSyncSession}.
-     *
-     * The local op is ALREADY in our log and already applied (the Replica did both before
-     * calling us). Our job is only to get it to the others, so a failure to send is not a
-     * failure to edit — it is a divergence the next sync round will close.
-     */
-    publish(op: Op): void;
-    /**
-     * THE LOG AS THE NETWORK SEES IT — our history, minus everything coalescing withheld.
-     *
-     * ---------------------------------------------------------------------------
-     * THE BUG THIS EXISTS TO FIX, WHICH WAS MINE, AND WHICH ONLY THE BROWSER FOUND
-     * ---------------------------------------------------------------------------
-     * A 20-frame drag puts ONE op on the wire and leaves TWENTY in the local log — that is
-     * coalescing working exactly as designed, and the two peers' documents agree perfectly.
-     *
-     * But anti-entropy compares FRONTIERS DERIVED FROM LOGS. So on the next sync round my
-     * frontier said "I hold 20 ops from alice" and the peer's said "I hold 1", and the digest
-     * — which cannot tell a withheld op from a lost one — declared a HOLE and repaired it by
-     * resending my entire history. Measured: `opsSent` went from 1 to 21 on the first sync
-     * after a single drag. And it never settles, because the peer can NEVER obtain the 19 ops
-     * I have deliberately decided never to send. Every sync round, forever, for the rest of
-     * the session, on the most common interaction in the product.
-     *
-     * It is invisible to a convergence oracle — the document is perfectly correct throughout —
-     * and it was invisible to my own frontier-invariant test, which flushed after every single
-     * op and therefore never once coalesced anything while syncing. It took driving a real drag
-     * through a real browser to compose the two.
-     *
-     * THE FIX is a definition, not a patch: THE FRONTIER DESCRIBES THE SHARED LOG. An op we
-     * chose never to transmit is not part of the history we share with anyone, so it is not in
-     * our frontier and it is not in the catch-up delta we serve — to ANY peer, including one
-     * that joins tomorrow. Every peer therefore holds the same shared set, every digest agrees,
-     * and the fast path stays fast.
-     */
-    sharedHistory(): Op[];
-    /**
-     * Publish our cursor / selection / name.
-     *
-     * THROTTLED, not debounced. A debounce would send nothing at all while the mouse keeps
-     * moving — the cursor would only appear once you stopped, which is the exact opposite
-     * of the feature. A throttle sends the newest sample at a bounded rate and drops the
-     * ones in between, which is precisely correct for a value where only the latest matters.
-     */
-    setAwareness(patch: Partial<AwarenessState>): void;
-    private sendAwareness;
-    private send;
-    private sendOps;
-    private onStatus;
-    /**
-     * "Here I am; here is what I have."
-     *
-     * Fired on the first connect and on every RECONNECT, and it is the same two messages
-     * both times — because "I have been away for 30 seconds" and "I have just arrived" are
-     * the same question from the network's point of view, and answering them with one code
-     * path is why the reconnect case cannot rot: it is exercised by every single join.
-     *
-     * Everything both sides did while apart is sitting in their logs. Nothing was lost; it
-     * was only undelivered. `deltaFor` works out exactly what each side missed.
-     */
-    private announce;
-    private onMessage;
-    /** Ship a peer exactly the ops its frontier says it does not have. */
-    private answer;
-    /**
-     * The receive path, in the only order that works.
-     *
-     *   CausalBuffer → Replica → VersionVector → relay
-     *
-     * The buffer FIRST, and that ordering is the load-bearing part: an op that reaches the
-     * Replica before its `add` is logged, stamped, and silently dropped, and no later
-     * delivery can ever resurrect it (the log de-duplicates it, and the LWW gate now refuses
-     * it as superseded by itself). Once it is past the Replica it is too late. See
-     * causal-buffer.ts.
-     */
-    private ingest;
-    private stopTimers;
-    dispose(): void;
-}
-export interface SyncSessionOptions extends SyncAdapterOptions {
-    actor: ActorId;
-    /** Resume the Lamport clock from a persisted tail. */
-    startClock?: number;
-}
-/**
- * Build a Replica and a SyncAdapter, correctly wired to each other.
- *
- * The wiring is one line and it is easy to forget, and forgetting it produces the exact
- * failure this codebase is famous for: everything green, every unit test passing, and not
- * one edit ever reaching the wire — because `onLocalOp` went nowhere.
- */
-export declare function createSyncSession(diagram: DiagramModel, transport: SyncTransport, options: SyncSessionOptions): SyncAdapter;