@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/collab/capture.d.ts

@@ -0,0 +1,147 @@
+import { DiagramModel } from '../models/DiagramModel';
+import type { SerializedNode } from '../models/NodeModel';
+import type { SerializedLink } from '../models/LinkModel';
+import type { SerializedGroup } from '../models/GroupModel';
+import { LamportClock, type ActorId, type Op, type OpValue } from './op';
+/**
+ * What the register held BEFORE the op overwrote it.
+ *
+ * Card 4 (undo) needs it and nothing else does, so it is handed to the capture callback
+ * ALONGSIDE the op rather than being put INSIDE it. An op is a wire format: it crosses a
+ * network and a disk, it is broadcast to every peer, and a peer does not need — and must
+ * not be trusted with — the sender's idea of the previous value. Undo is a LOCAL concern.
+ * Widening the op to carry it would have doubled the traffic to serve one machine.
+ */
+export type OpBefore = 
+/** A `set`: the value the register held. `undefined` = the register was empty. */
+{
+    kind: 'value';
+    value: OpValue | undefined;
+}
+/** A `remove`: the entity's full state at the moment it was removed. */
+ | {
+    kind: 'entity';
+    data: SerializedNode | SerializedLink | SerializedGroup;
+}
+/** An `add`: there was nothing before it. */
+ | {
+    kind: 'none';
+};
+export interface OpCaptureOptions {
+    /** Who this peer is. Must be unique across peers; used for the total-order tiebreak. */
+    actor: ActorId;
+    /**
+     * Called for each captured op — hand it to a sync adapter, an autosave, a test.
+     *
+     * `before` is the value the op displaced, for the local undo stack. It is NOT part of
+     * the op and never goes on the wire.
+     */
+    onOp: (op: Op, before: OpBefore) => void;
+    /** Resume a clock across sessions (e.g. from a persisted op-log tail). */
+    startClock?: number;
+}
+/**
+ * Watches a live diagram and emits an Op for every real edit.
+ *
+ * Re-entrancy: while `applyRemote()` is running, capture is SUPPRESSED. Without that,
+ * applying a peer's op would capture it as a local op and re-broadcast it, and the two
+ * peers would ping-pong the same edit forever, each amplifying the other. This is the
+ * single most important line in the file and it is three characters long.
+ */
+export declare class OpCapture {
+    private readonly diagram;
+    private readonly clock;
+    private readonly onOp;
+    private readonly unsubs;
+    private readonly entitySubs;
+    /**
+     * nodeId → (portId → the register value last emitted/seen for that port).
+     *
+     * The per-port `before` shadow for undo. trackChange('ports', …) reports the ONE port
+     * that changed, and a port's own change events report one property — so the register's
+     * prior value has to be remembered here; there is nowhere else to read it from once
+     * the model has been mutated. Seeded from the node's existing ports at watch time, so
+     * `before` for a port's first change is its REAL prior state, not "empty" — the old
+     * whole-collection shadow got that wrong once and undo stripped a node of every port
+     * it was born with.
+     */
+    private readonly portShadows;
+    /** portId → unsubscribe for the live-port watch (Defect 2: port edits must sync). */
+    private readonly portSubs;
+    /**
+     * groupId → the member collection last emitted for that group.
+     *
+     * The same shadow trick as `portShadows`, for the same reason and against a worse bug.
+     * `GroupModel.addMember` reports the funnel change as trackChange('members', null,
+     * <the one id that joined>) — a DELTA, where every other register in this engine
+     * reports the property's VALUE. Emitted verbatim, that put the bare string 'node-1' on
+     * the wire as the whole `members` register (and a bare `null` for a removal), which the
+     * receiving peer wrote straight over its Set. See apply-op.ts for what that did to
+     * serialize().
+     *
+     * So the value is read off the live Set instead — trackChange fires AFTER the mutation,
+     * so the Set is already the post-state — and the shadow supplies `before`. It has to:
+     * `before` for a removal is the collection WITH the member back IN ITS ORIGINAL
+     * POSITION, and a Set that has had an element deleted cannot reproduce that (re-adding
+     * appends). Undo restores `before`, and order is in serialize(), so a reconstructed one
+     * would make undo save a byte-different document.
+     */
+    private readonly memberShadows;
+    /** True while we are applying a REMOTE op: everything the model emits is an echo. */
+    private applying;
+    private stopped;
+    constructor(diagram: DiagramModel, options: OpCaptureOptions);
+    /** The Lamport clock this capture issues from — shared with the sync layer. */
+    get lamport(): LamportClock;
+    /**
+     * Apply remote ops WITHOUT capturing them as local edits.
+     *
+     * The clock observes each remote op first, so any op we issue after this sorts after
+     * theirs. That is what makes the resulting order respect causality between peers and
+     * not merely within one.
+     */
+    applyRemote(ops: readonly Op[], apply: (op: Op) => void): void;
+    /**
+     * Run `fn` with capture SUPPRESSED — the model mutations it makes emit no ops.
+     *
+     * For work that is DERIVED rather than authored: referential integrity moving an
+     * orphaned link out of the document and back again is a function of state that every
+     * peer computes for itself, so broadcasting it would put a redundant op on the wire that
+     * races with the ops it was derived from. Deriving it locally is not just cheaper, it is
+     * the only thing that converges.
+     *
+     * Re-entrant: nesting must not clear the flag early (integrity reconciles INSIDE
+     * applyRemote), or a remote op's mutations would start echoing back mid-batch.
+     */
+    silently(fn: () => void): void;
+    stop(): void;
+    private emit;
+    /**
+     * A `set` draft, with clears made EXPLICIT (Defect 3).
+     *
+     * `undefined` is what the model funnel hands us when a register is being EMPTIED
+     * (deleteMetadata, clearFlexItem) — and `OpValue` forbids it. The old code emitted it
+     * anyway; it crossed the wire only because JSON.stringify drops an undefined key and
+     * the peer's apply read missing-as-undefined. Two accidents, both load-bearing. Now a
+     * clear says so: `clear: true`, no value key, JSON-exact round-trip. (NOT null — null
+     * is a legitimate stored value, and the suite proves the two stay distinct.)
+     */
+    private setDraft;
+    private watchDiagram;
+    private watchEntity;
+    /**
+     * Watch ONE live port (Defect 2).
+     *
+     * Any real change re-emits the port's whole serialized form to its `ports.<id>`
+     * register — coarse-per-port. The wire-value dedupe below is what keeps derived
+     * twitches (a link registering a connection bumps `version` and nothing else) off
+     * the wire: if the register value did not change, nothing is emitted.
+     *
+     * Attached on every path a port can reach a live diagram by: capture attach,
+     * node add (watchEntity seeds and watches), port add (the ports branch above).
+     * Detached on port remove, node remove and stop().
+     */
+    private watchPort;
+    private unwatchPort;
+    private unwatchEntity;
+}

package/src/libs/engine/src/collab/capture.js

@@ -0,0 +1,510 @@
+"use strict";
+// Wave 9 — Card 0: turning real edits into ops.
+//
+// THIS FILE IS THE ONE THAT MATTERS, and it is the one the roadmap did not ask for.
+//
+// It would be very easy to ship Card 0 as: an Op type, a LamportClock, an applyOp()
+// reducer, a replay() function, and a suite of tests that hand-construct ops and
+// replay them. Everything green. Everything documented. And the log would be fed by
+// NOTHING — an op format that no actual edit ever produces.
+//
+// That is precisely the bug this engine has shipped in every wave: `setLayoutService()`
+// that nothing called, 17 LOD presets that were all a no-op, a worker stack whose tests
+// all forced `useWorker:false`, a quality governor (mine) wired to nothing, and — right
+// here in this capability — a `Command.serialize()` on every command with NO
+// DESERIALIZER ANYWHERE. Write-only. Green tests, zero reachability.
+//
+// So the capture layer exists, and the load-bearing test in this wave is not "ops
+// replay" — it is: DRIVE THE REAL ENGINE WITH REAL EDITS, CAPTURE, REPLAY INTO AN EMPTY
+// DIAGRAM, AND DEMAND BYTE-IDENTICAL serialize(). That is the only test that can tell
+// you the log is COMPLETE (nothing an edit does is missed), REPLAYABLE, and
+// DETERMINISTIC — and no amount of hand-written ops can substitute for it.
+//
+// ---------------------------------------------------------------------------
+// HOW
+// ---------------------------------------------------------------------------
+// `DiagramEntity.trackChange(property, old, new)` is the SINGLE funnel every mutation
+// in this engine passes through (it is what powers dirty-tracking, versioning and the
+// change events). It emits `change` with the property name — and, beautifully, the
+// vocabulary it already speaks is exactly the vocabulary an op path needs:
+// 'position', 'size', 'state', 'style', 'points', 'metadata.<key>'. The diagram itself
+// emits trackChange('nodes'|'links'|'groups', old, new) for add/remove.
+//
+// So capture is a listener on that funnel. No parallel bookkeeping, no second source of
+// truth that can drift from the first.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpCapture = void 0;
+const tslib_1 = require("tslib");
+const NodeModel_1 = require("../models/NodeModel");
+const GroupModel_1 = require("../models/GroupModel");
+const op_1 = require("./op");
+/** Property names that are structural (add/remove), not property registers. */
+const STRUCTURAL = new Set(['nodes', 'links', 'groups', 'strokes']);
+/** The `trackChange` collection name → the op target it adds/removes. */
+const STRUCTURAL_TARGET = {
+    nodes: 'node',
+    links: 'link',
+    groups: 'group',
+    strokes: 'stroke',
+};
+/**
+ * Properties we do NOT put on the wire — SCOPED PER TARGET.
+ *
+ * `points` is a LINK's ROUTED geometry — it is DERIVED, recomputed by the renderer from
+ * the node positions and the router on every frame that needs it. Broadcasting it would
+ * (a) trade a 2-number node move for an N-point path on every drag frame, and (b) be
+ * actively wrong: the receiving peer recomputes the route anyway, so the transmitted
+ * points are overwritten milliseconds later. A collaboration engine must sync CAUSES,
+ * not their derived consequences.
+ *
+ * The exception is a link the user has hand-routed — those waypoints are authored
+ * intent, not derived geometry — and the model already distinguishes the two with the
+ * `hasManualWaypoints` metadata flag, which IS synced (it is a metadata.* register).
+ * So a manual reroute travels; an automatic one does not. That is the correct line, and
+ * it is the model's own line, not one invented here.
+ *
+ * wave10/whiteboard: `points` ON A STROKE IS THE OPPOSITE — it is the authored content
+ * itself, nothing derives it, and a global `DERIVED = {points}` would drop the one thing a
+ * stroke edit changes, so editing a stroke's geometry would silently never reach a peer.
+ * (StrokeModel.setPoints documents exactly this trap.) Hence per-target: `points` is
+ * derived for a link and authored for a stroke.
+ */
+const DERIVED_BY_TARGET = {
+    link: new Set(['points']),
+    diagram: new Set(['points']),
+};
+function isDerived(target, property) {
+    var _a, _b;
+    return (_b = (_a = DERIVED_BY_TARGET[target]) === null || _a === void 0 ? void 0 : _a.has(property)) !== null && _b !== void 0 ? _b : false;
+}
+/**
+ * ---------------------------------------------------------------------------
+ * EPHEMERAL VIEWER STATE — THE BUG THIS SET EXISTS TO CLOSE
+ * ---------------------------------------------------------------------------
+ *
+ * `NodeState` mixes two completely different kinds of fact in one object:
+ *
+ *     DURABLE (about the DOCUMENT):  visible, locked, expanded, enabled, error, status
+ *     EPHEMERAL (about a VIEWER):    selected, hovered, highlighted, focused
+ *
+ * …and this capture layer used to sync the whole object as a single register. The
+ * consequences, found by wave9/sync driving a real two-peer session:
+ *
+ *   • MOVING YOUR MOUSE ACROSS A NODE WROTE TWO PERMANENT OPS INTO THE SHARED DOCUMENT
+ *     (hover on, hover off) — and the peer APPLIED them, so a node lit up on my screen
+ *     because your cursor was somewhere near it.
+ *   • YOUR CLICK DESELECTED MY NODE. Selection is not a property of the diagram; it is a
+ *     property of a person looking at it.
+ *   • And every one of those ops went into the replayable, persisted, totally-ordered log
+ *     FOREVER. A five-minute session would bury the actual edit history under thousands
+ *     of hover events.
+ *
+ * `LinkModel.state` is worse still: its ONLY values are 'default' | 'selected' | 'hovered'
+ * | 'highlighted'. It is ephemeral in its entirety, so a link's state is never synced at
+ * all.
+ *
+ * This is the same distinction wave9/comments drew for read-markers ("Ada read this" is a
+ * fact about Ada, not about the document) and the same one that keeps live cursors out of
+ * the op log. Presence belongs on the awareness channel — ephemeral, per-peer, expiring —
+ * and NEVER in the document.
+ */
+const EPHEMERAL_NODE_STATE = new Set(['selected', 'hovered', 'highlighted', 'focused']);
+/** A link's `state` is view state, top to bottom. Never synced. */
+const EPHEMERAL_BY_TARGET = {
+    link: new Set(['state']),
+};
+/** Strip the viewer-local keys out of a node/group `state` object. */
+function durableState(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (!EPHEMERAL_NODE_STATE.has(k))
+            out[k] = v;
+    }
+    return out;
+}
+/** Structural equality, so a hover that changes nothing durable emits nothing. */
+function sameJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * A port as it travels: the serialized form MINUS `version`.
+ *
+ * `version` is a per-replica mutation counter — a local quantity, like a vector-clock
+ * component; the convergence oracle already exempts it for exactly that reason. Keeping
+ * it in the register value would also defeat the coarse-per-port dedupe below: every
+ * derived-state twitch (a link registering a connection bumps the port's version and
+ * nothing else) would look like a fresh register value and go on the wire.
+ */
+function portWireValue(port) {
+    const _a = port.serialize(), { version: _version } = _a, data = tslib_1.__rest(_a, ["version"]);
+    return data;
+}
+/**
+ * Port properties that are DERIVED and must not re-emit the register.
+ *
+ * `connections` is rebuilt from the diagram's links on every peer (PortModel calls it
+ * derived state in so many words) — broadcasting it would race the link ops it is
+ * derived from. It is not in serialize() anyway; this skip just avoids doing the
+ * serialize-and-compare work on every link attach/detach.
+ */
+const PORT_DERIVED = new Set(['connections']);
+/**
+ * Watches a live diagram and emits an Op for every real edit.
+ *
+ * Re-entrancy: while `applyRemote()` is running, capture is SUPPRESSED. Without that,
+ * applying a peer's op would capture it as a local op and re-broadcast it, and the two
+ * peers would ping-pong the same edit forever, each amplifying the other. This is the
+ * single most important line in the file and it is three characters long.
+ */
+class OpCapture {
+    constructor(diagram, options) {
+        var _a;
+        this.diagram = diagram;
+        this.unsubs = [];
+        this.entitySubs = new Map();
+        /**
+         * nodeId → (portId → the register value last emitted/seen for that port).
+         *
+         * The per-port `before` shadow for undo. trackChange('ports', …) reports the ONE port
+         * that changed, and a port's own change events report one property — so the register's
+         * prior value has to be remembered here; there is nowhere else to read it from once
+         * the model has been mutated. Seeded from the node's existing ports at watch time, so
+         * `before` for a port's first change is its REAL prior state, not "empty" — the old
+         * whole-collection shadow got that wrong once and undo stripped a node of every port
+         * it was born with.
+         */
+        this.portShadows = new Map();
+        /** portId → unsubscribe for the live-port watch (Defect 2: port edits must sync). */
+        this.portSubs = new Map();
+        /**
+         * groupId → the member collection last emitted for that group.
+         *
+         * The same shadow trick as `portShadows`, for the same reason and against a worse bug.
+         * `GroupModel.addMember` reports the funnel change as trackChange('members', null,
+         * <the one id that joined>) — a DELTA, where every other register in this engine
+         * reports the property's VALUE. Emitted verbatim, that put the bare string 'node-1' on
+         * the wire as the whole `members` register (and a bare `null` for a removal), which the
+         * receiving peer wrote straight over its Set. See apply-op.ts for what that did to
+         * serialize().
+         *
+         * So the value is read off the live Set instead — trackChange fires AFTER the mutation,
+         * so the Set is already the post-state — and the shadow supplies `before`. It has to:
+         * `before` for a removal is the collection WITH the member back IN ITS ORIGINAL
+         * POSITION, and a Set that has had an element deleted cannot reproduce that (re-adding
+         * appends). Undo restores `before`, and order is in serialize(), so a reconstructed one
+         * would make undo save a byte-different document.
+         */
+        this.memberShadows = new Map();
+        /** True while we are applying a REMOTE op: everything the model emits is an echo. */
+        this.applying = false;
+        this.stopped = false;
+        this.clock = new op_1.LamportClock(options.actor, (_a = options.startClock) !== null && _a !== void 0 ? _a : 0);
+        this.onOp = options.onOp;
+        this.watchDiagram();
+        // Entities that already exist when capture starts still need watching — a diagram
+        // is rarely empty at the moment you decide to start collaborating on it.
+        for (const n of diagram.getNodes())
+            this.watchEntity('node', n);
+        for (const l of diagram.getLinks())
+            this.watchEntity('link', l);
+        for (const g of diagram.getGroups())
+            this.watchEntity('group', g);
+        for (const s of diagram.getStrokes())
+            this.watchEntity('stroke', s);
+    }
+    /** The Lamport clock this capture issues from — shared with the sync layer. */
+    get lamport() {
+        return this.clock;
+    }
+    /**
+     * Apply remote ops WITHOUT capturing them as local edits.
+     *
+     * The clock observes each remote op first, so any op we issue after this sorts after
+     * theirs. That is what makes the resulting order respect causality between peers and
+     * not merely within one.
+     */
+    applyRemote(ops, apply) {
+        this.silently(() => {
+            for (const op of ops) {
+                this.clock.observe(op.clock);
+                apply(op);
+            }
+        });
+    }
+    /**
+     * Run `fn` with capture SUPPRESSED — the model mutations it makes emit no ops.
+     *
+     * For work that is DERIVED rather than authored: referential integrity moving an
+     * orphaned link out of the document and back again is a function of state that every
+     * peer computes for itself, so broadcasting it would put a redundant op on the wire that
+     * races with the ops it was derived from. Deriving it locally is not just cheaper, it is
+     * the only thing that converges.
+     *
+     * Re-entrant: nesting must not clear the flag early (integrity reconciles INSIDE
+     * applyRemote), or a remote op's mutations would start echoing back mid-batch.
+     */
+    silently(fn) {
+        const was = this.applying;
+        this.applying = true;
+        try {
+            fn();
+        }
+        finally {
+            // finally, not a trailing assignment: if fn() throws, a stuck `applying` flag would
+            // silently disable capture for the rest of the session — every subsequent local edit
+            // lost, with no error anywhere.
+            this.applying = was;
+        }
+    }
+    stop() {
+        this.stopped = true;
+        for (const u of this.unsubs)
+            u();
+        for (const u of this.entitySubs.values())
+            u();
+        for (const u of this.portSubs.values())
+            u();
+        this.unsubs.length = 0;
+        this.entitySubs.clear();
+        this.portSubs.clear();
+        this.portShadows.clear();
+        this.memberShadows.clear();
+    }
+    // -------------------------------------------------------------------------
+    emit(op, before) {
+        if (this.applying || this.stopped)
+            return;
+        this.onOp(Object.assign(Object.assign({}, op), { clock: this.clock.tick(), actor: this.clock.actorId }), before);
+    }
+    /**
+     * A `set` draft, with clears made EXPLICIT (Defect 3).
+     *
+     * `undefined` is what the model funnel hands us when a register is being EMPTIED
+     * (deleteMetadata, clearFlexItem) — and `OpValue` forbids it. The old code emitted it
+     * anyway; it crossed the wire only because JSON.stringify drops an undefined key and
+     * the peer's apply read missing-as-undefined. Two accidents, both load-bearing. Now a
+     * clear says so: `clear: true`, no value key, JSON-exact round-trip. (NOT null — null
+     * is a legitimate stored value, and the suite proves the two stay distinct.)
+     */
+    setDraft(target, id, path, value) {
+        return value === undefined
+            ? { op: 'set', target, id, path, clear: true }
+            : { op: 'set', target, id, path, value };
+    }
+    watchDiagram() {
+        const onChange = (entry) => {
+            const { property, oldValue, newValue } = entry;
+            if (STRUCTURAL.has(property)) {
+                // trackChange('nodes', null, node) = add · trackChange('nodes', node, null) = remove
+                const target = STRUCTURAL_TARGET[property];
+                if (newValue && !oldValue) {
+                    const e = newValue;
+                    this.emit({ op: 'add', target, id: e.id, data: e.serialize() }, { kind: 'none' });
+                    this.watchEntity(target, e);
+                }
+                else if (oldValue && !newValue) {
+                    // The entity's FULL STATE at the moment it was removed — the only thing that can
+                    // undo a delete. (deepClone hands class instances through untouched, so this is
+                    // the live model, and serialize() on it is exact rather than a stale snapshot.)
+                    const e = oldValue;
+                    this.emit({ op: 'remove', target, id: e.id }, { kind: 'entity', data: e.serialize() });
+                    this.unwatchEntity(e.id);
+                }
+                return;
+            }
+            // A property of the diagram itself (name, viewport, …).
+            if (!isDerived('diagram', property)) {
+                this.emit(this.setDraft('diagram', '', property, newValue), { kind: 'value', value: oldValue });
+            }
+        };
+        // on() hands back its own unsubscriber — no need to reconstruct the handler identity
+        this.unsubs.push(this.diagram.on('change', onChange));
+    }
+    watchEntity(target, entity) {
+        if (this.entitySubs.has(entity.id))
+            return;
+        // SEED the per-port shadows with what the node ALREADY has, and WATCH each port.
+        //
+        // The seed: without it, `before` for a port's first change is undefined — and undo
+        // reads that as "the register was empty", so undoing the first edit to a port the
+        // node was born with would DELETE that port. (The whole-collection ancestor of this
+        // bug once stripped a node of every port it had; the fuzz found it as a node with an
+        // empty ports array on one peer.)
+        //
+        // The watch is Defect 2's fix: PortModel is a DiagramEntity with trackChange calls of
+        // its own (position, alignment, offset, allowedTypes) that no one was listening to —
+        // editing a LIVE port silently never synced.
+        if (entity instanceof NodeModel_1.NodeModel) {
+            const shadows = new Map();
+            this.portShadows.set(entity.id, shadows);
+            for (const p of entity.getPorts()) {
+                shadows.set(p.id, portWireValue(p));
+                this.watchPort(entity, p);
+            }
+        }
+        // SEED the member shadow with what the group ALREADY has, for the same reason the
+        // port shadows are seeded: `before` for a group's first membership change must be its
+        // REAL prior collection, not "empty" — or undoing the first add would strip the group
+        // of every member it was born with.
+        if (entity instanceof GroupModel_1.GroupModel) {
+            this.memberShadows.set(entity.id, [...entity.members]);
+        }
+        const onChange = (entry) => {
+            var _a, _b;
+            // Per-target: a LINK's `points` is derived and dropped; a STROKE's `points` is the
+            // authored content and must travel. See DERIVED_BY_TARGET.
+            if (isDerived(target, entry.property))
+                return;
+            // Wholly-ephemeral registers never reach the wire at all. A link's `state` is
+            // 'default' | 'selected' | 'hovered' | 'highlighted' — view state, top to bottom.
+            if ((_a = EPHEMERAL_BY_TARGET[target]) === null || _a === void 0 ? void 0 : _a.has(entry.property))
+                return;
+            // PORTS: ONE REGISTER PER PORT — `ports.<portId>` — because the whole-collection
+            // register this used to be was Card 0's rejected design smuggled back in one level
+            // down. Two peers concurrently adding a DIFFERENT port to the same node raced one
+            // register; one collection write superseded the other, and the reconciling apply
+            // branch DELETED the losing port from its creator's own node — orphaning every
+            // link already attached to it. The user watched their work vanish, silently.
+            //
+            // The path IS the register key (op.ts), so per-port needs no new op kind: an
+            // add/update is `set(node, 'ports.<id>', <serialized port>)` and a remove is the
+            // explicit clear of that register. COARSE per-port, deliberately: the value is the
+            // whole serialized port, never `ports.<id>.position` sub-registers — the register
+            // keyspace stays prefix-free (the comments-suite lesson), and a port is small.
+            //
+            // NodeModel.addPort() emits trackChange('ports', null, <the live PortModel>) and
+            // deepClone hands class instances through untouched — so entry.newValue here IS the
+            // port, and it must be SERIALIZED before it can be a value (a live instance on the
+            // wire is how the original Map-corruption bug happened; see apply-op.ts, which
+            // still refuses to write ports except through the real addPort/removePort).
+            if (entry.property === 'ports' && entity instanceof NodeModel_1.NodeModel) {
+                const shadows = this.portShadows.get(entity.id);
+                if (entry.newValue && !entry.oldValue) {
+                    // add — watch it (bookkeeping runs even while applying a REMOTE op, exactly
+                    // like watchEntity below: only EMISSION is suppressed, or a remotely-added
+                    // port would be invisible to capture for the rest of the session)
+                    const port = entry.newValue;
+                    const now = portWireValue(port);
+                    const was = shadows === null || shadows === void 0 ? void 0 : shadows.get(port.id);
+                    shadows === null || shadows === void 0 ? void 0 : shadows.set(port.id, now);
+                    this.watchPort(entity, port);
+                    this.emit(this.setDraft(target, entity.id, `ports.${port.id}`, now), { kind: 'value', value: was });
+                }
+                else if (entry.oldValue && !entry.newValue) {
+                    // remove — the clear of exactly one register, with the port's last state as
+                    // `before` so undo restores exactly one port
+                    const port = entry.oldValue;
+                    const was = (_b = shadows === null || shadows === void 0 ? void 0 : shadows.get(port.id)) !== null && _b !== void 0 ? _b : portWireValue(port);
+                    shadows === null || shadows === void 0 ? void 0 : shadows.delete(port.id);
+                    this.unwatchPort(port.id);
+                    this.emit(this.setDraft(target, entity.id, `ports.${port.id}`, undefined), { kind: 'value', value: was });
+                }
+                return;
+            }
+            // MEMBERS: the register value is THE WHOLE COLLECTION, never the delta the funnel
+            // reports. GroupModel.addMember/removeMember call trackChange('members', null, id)
+            // and ('members', id, null) — they name the member that MOVED, not the value the
+            // register now holds, which makes `members` the one register in the engine whose
+            // funnel payload is not its value. Emitting it verbatim shipped a bare id string
+            // (and a bare null) as the whole Set; see memberShadows and apply-op.ts.
+            //
+            // Read off the live Set — trackChange fires after the mutation, so it is the
+            // post-state — and take `before` from the shadow, which is the only thing that
+            // remembers the collection's ORDER before a delete.
+            if (entry.property === 'members' && entity instanceof GroupModel_1.GroupModel) {
+                const now = [...entity.members];
+                const was = this.memberShadows.get(entity.id);
+                // A membership change that changes nothing emits nothing: re-adding a member the
+                // group already has is a no-op in the model, and it must be one on the wire too.
+                if (sameJson(now, was))
+                    return;
+                this.memberShadows.set(entity.id, now);
+                this.emit(this.setDraft(target, entity.id, 'members', now), { kind: 'value', value: was });
+                return;
+            }
+            let value = entry.newValue;
+            let before = entry.oldValue;
+            if (entry.property === 'state') {
+                // `state` is a MIXED register: durable document facts (visible, locked, expanded)
+                // sitting in the same object as per-viewer ephemera (selected, hovered, focused).
+                // Project BOTH sides — and emit NOTHING when only the ephemera moved.
+                //
+                // Without the second half of that, hovering a node still puts an op on the wire and
+                // in the permanent log on every mouse-over. The receiver's redundant-write guard
+                // would drop it, so the DOCUMENT would look correct and the bug would be invisible
+                // to every convergence test — while the log filled with hover events that outlive
+                // the session. (Found by wave9/sync, in two real browser tabs. jsdom does not hover.)
+                //
+                // `before` is projected TOO, and that is not symmetry for its own sake: undo
+                // restores `before`, so an unprojected one would put the undoing user's stale
+                // selection back onto every peer's screen — reintroducing the very bug through the
+                // undo path.
+                const next = durableState(entry.newValue);
+                const prev = durableState(entry.oldValue);
+                if (sameJson(next, prev))
+                    return;
+                value = next;
+                before = prev;
+            }
+            this.emit(this.setDraft(target, entity.id, entry.property, value), { kind: 'value', value: before });
+        };
+        this.entitySubs.set(entity.id, entity.on('change', onChange));
+    }
+    /**
+     * Watch ONE live port (Defect 2).
+     *
+     * Any real change re-emits the port's whole serialized form to its `ports.<id>`
+     * register — coarse-per-port. The wire-value dedupe below is what keeps derived
+     * twitches (a link registering a connection bumps `version` and nothing else) off
+     * the wire: if the register value did not change, nothing is emitted.
+     *
+     * Attached on every path a port can reach a live diagram by: capture attach,
+     * node add (watchEntity seeds and watches), port add (the ports branch above).
+     * Detached on port remove, node remove and stop().
+     */
+    watchPort(node, port) {
+        if (this.portSubs.has(port.id))
+            return;
+        const onPortChange = (entry) => {
+            if (PORT_DERIVED.has(entry.property))
+                return;
+            const shadows = this.portShadows.get(node.id);
+            const now = portWireValue(port);
+            const was = shadows === null || shadows === void 0 ? void 0 : shadows.get(port.id);
+            if (sameJson(now, was))
+                return;
+            shadows === null || shadows === void 0 ? void 0 : shadows.set(port.id, now);
+            this.emit(this.setDraft('node', node.id, `ports.${port.id}`, now), { kind: 'value', value: was });
+        };
+        this.portSubs.set(port.id, port.on('change', onPortChange));
+    }
+    unwatchPort(portId) {
+        const un = this.portSubs.get(portId);
+        if (un) {
+            un();
+            this.portSubs.delete(portId);
+        }
+    }
+    unwatchEntity(id) {
+        const un = this.entitySubs.get(id);
+        if (un) {
+            un();
+            this.entitySubs.delete(id);
+        }
+        // A removed NODE takes its port watches with it — the shadows too, or a node
+        // deleted and re-added (resurrection) would inherit stale `before` values.
+        const shadows = this.portShadows.get(id);
+        if (shadows) {
+            for (const portId of shadows.keys())
+                this.unwatchPort(portId);
+            this.portShadows.delete(id);
+        }
+        // Same for a removed GROUP's member shadow: a group deleted and resurrected must not
+        // inherit the membership its previous incarnation had.
+        this.memberShadows.delete(id);
+    }
+}
+exports.OpCapture = OpCapture;
+//# sourceMappingURL=capture.js.map

package/src/libs/engine/src/collab/index.d.ts

@@ -0,0 +1,12 @@
+export { LamportClock, compareOps, opId } from './op';
+export type { ActorId, Op, AddOp, RemoveOp, SetOp, OpPath, OpTarget, OpValue } from './op';
+export { applyOp, applyEntitySet, OpApplyError } from './apply-op';
+export { OpLog, replay } from './op-log';
+export { OpCapture } from './capture';
+export type { OpCaptureOptions, OpBefore } from './capture';
+export { Replica } from './replica';
+export type { ReplicaOptions } from './replica';
+export { LwwRegistry } from './lww';
+export type { Stamp } from './lww';
+export { ReferentialIntegrity } from './integrity';
+export { UndoStack } from './undo';