@grafloria/element 0.3.20 → 0.3.21

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

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

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

@@ -1,12 +0,0 @@
-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';