@grafloria/element 0.3.17 → 0.3.19

package/src/libs/engine/src/serialization/DiagramMigrations.js

@@ -0,0 +1,124 @@
+"use strict";
+// Document-level schema versioning + ordered migration chain.
+//
+// `schemaVersion` describes the SHAPE of a serialized diagram document and is
+// distinct from the per-entity `version` counter (which counts mutations of a
+// live entity). Documents written before this system exist are treated as
+// schemaVersion 1; the current writer stamps DIAGRAM_SCHEMA_VERSION.
+//
+// On load, `runDiagramMigrations` upgrades an older document step by step
+// (1→2→…→current) through registered migrations, and FAILS LOUDLY — instead of
+// silently mis-loading — when the document is newer than the runtime or when a
+// migration step is missing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIAGRAM_SCHEMA_VERSION = void 0;
+exports.registerDiagramMigration = registerDiagramMigration;
+exports.getDiagramMigrations = getDiagramMigrations;
+exports.runDiagramMigrations = runDiagramMigrations;
+const tslib_1 = require("tslib");
+/**
+ * The schema version this engine writes.
+ *
+ * History:
+ *  - 1: implicit — documents written before schemaVersion existed
+ *       (fromJSON bypassed the wired restore path; groups could carry a
+ *       runtime 'diagram' metadata key).
+ *  - 2: documents written by the unified load/save path. Structurally
+ *       identical to v1 except: `schemaVersion` is stamped, `groups` is
+ *       always present, and runtime-only metadata is never serialized.
+ */
+exports.DIAGRAM_SCHEMA_VERSION = 3;
+const registry = [];
+/**
+ * Register a document migration. Apps embedding the engine can register their
+ * own steps when they extend the document shape.
+ */
+function registerDiagramMigration(migration) {
+    if (migration.to !== migration.from + 1) {
+        throw new Error(`Diagram migration must upgrade exactly one step (got ${migration.from} → ${migration.to})`);
+    }
+    if (registry.some((m) => m.from === migration.from)) {
+        throw new Error(`A diagram migration from schemaVersion ${migration.from} is already registered`);
+    }
+    registry.push(migration);
+    registry.sort((a, b) => a.from - b.from);
+}
+/** Registered migrations, in order (primarily for tests/diagnostics). */
+function getDiagramMigrations() {
+    return registry;
+}
+/**
+ * Upgrade a serialized document to DIAGRAM_SCHEMA_VERSION.
+ *
+ * - A document with no `schemaVersion` is treated as v1.
+ * - A document NEWER than the runtime throws (loading it would silently drop
+ *   or mangle data written by a newer app — the caller must upgrade instead).
+ * - A missing step in the chain throws (a partial upgrade is worse than none).
+ *
+ * @param migrations override the global registry (tests / embedders).
+ */
+function runDiagramMigrations(data, migrations = registry) {
+    var _a;
+    let doc = data;
+    let v = (_a = doc.schemaVersion) !== null && _a !== void 0 ? _a : 1;
+    if (v > exports.DIAGRAM_SCHEMA_VERSION) {
+        throw new Error(`Diagram document has schemaVersion ${v}, but this engine only knows ` +
+            `${exports.DIAGRAM_SCHEMA_VERSION}. Refusing to load a newer document — ` +
+            `upgrade the engine (or re-export from an app on schema ${exports.DIAGRAM_SCHEMA_VERSION}).`);
+    }
+    while (v < exports.DIAGRAM_SCHEMA_VERSION) {
+        const step = migrations.find((m) => m.from === v);
+        if (!step) {
+            throw new Error(`No diagram migration registered for schemaVersion ${v} → ${v + 1}; ` +
+                `cannot upgrade this document to ${exports.DIAGRAM_SCHEMA_VERSION}.`);
+        }
+        doc = step.migrate(doc);
+        v = step.to;
+        // Stamp defensively so a forgetful migrate() cannot stall the loop.
+        doc.schemaVersion = v;
+    }
+    return doc;
+}
+// ---------------------------------------------------------------------------
+// Built-in chain
+// ---------------------------------------------------------------------------
+registerDiagramMigration({
+    from: 1,
+    to: 2,
+    description: 'v1 → v2: stamp schemaVersion, guarantee the groups collection exists, ' +
+        'and strip runtime-only group metadata (the live diagram back-reference) ' +
+        'that pre-unified writers could leak into payloads.',
+    migrate(data) {
+        var _a;
+        const groups = ((_a = data.groups) !== null && _a !== void 0 ? _a : []).map((g) => {
+            if (g && g.metadata && 'diagram' in g.metadata) {
+                const _a = g.metadata, { diagram: _runtimeRef } = _a, metadata = tslib_1.__rest(_a, ["diagram"]);
+                return Object.assign(Object.assign({}, g), { metadata });
+            }
+            return g;
+        });
+        return Object.assign(Object.assign({}, data), { groups, schemaVersion: 2 });
+    },
+});
+registerDiagramMigration({
+    from: 2,
+    to: 3,
+    description: 'v2 → v3: a node with a parentId is RELATIVE unless it explicitly says otherwise. ' +
+        'Pre-v3 engines summed the parent chain in getWorldPosition() regardless of ' +
+        'positionMode, so a parented node whose mode was absent or the "absolute" default ' +
+        'was in fact rendered relatively. v3 makes getWorldPosition honour positionMode; ' +
+        're-labelling those nodes "relative" here is what keeps every legacy document ' +
+        'rendering BYTE-IDENTICALLY under the new, consistent semantics. ("layout" mode ' +
+        'is left alone — it was never part of the summation contract.)',
+    migrate(data) {
+        var _a;
+        const nodes = ((_a = data.nodes) !== null && _a !== void 0 ? _a : []).map((n) => {
+            if (n && n.parentId && (n.positionMode === undefined || n.positionMode === 'absolute')) {
+                return Object.assign(Object.assign({}, n), { positionMode: 'relative' });
+            }
+            return n;
+        });
+        return Object.assign(Object.assign({}, data), { nodes, schemaVersion: 3 });
+    },
+});
+//# sourceMappingURL=DiagramMigrations.js.map

package/src/libs/engine/src/serialization/DiagramMigrations.js.map

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

package/src/libs/engine/src/serialization/DiagramValidator.d.ts

@@ -0,0 +1,20 @@
+import type { SerializedDiagram } from '../models/DiagramModel';
+export interface DiagramValidationFinding {
+    severity: 'error' | 'warning';
+    /** Stable machine-readable code (e.g. 'duplicate-id', 'dangling-link-endpoint'). */
+    code: string;
+    message: string;
+    /** Id of the entity the finding is about, when applicable. */
+    entityId?: string;
+}
+export interface DiagramValidationReport {
+    ok: boolean;
+    errors: DiagramValidationFinding[];
+    warnings: DiagramValidationFinding[];
+}
+/** Thrown by strict-mode loads when the document has integrity errors. */
+export declare class DiagramValidationError extends Error {
+    readonly report: DiagramValidationReport;
+    constructor(report: DiagramValidationReport);
+}
+export declare function validateSerializedDiagram(data: SerializedDiagram): DiagramValidationReport;

package/src/libs/engine/src/serialization/DiagramValidator.js

@@ -0,0 +1,136 @@
+"use strict";
+// Load-time structural integrity validation for serialized diagrams.
+//
+// The validator inspects the SERIALIZED shape (before entities are
+// constructed) and reports structured findings instead of throwing, so
+// callers choose their policy: ignore, warn, or fail hard. It catches the
+// corruption classes that otherwise surface as silent misbehavior long after
+// load — dangling link endpoints, duplicate ids, orphaned group references.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagramValidationError = void 0;
+exports.validateSerializedDiagram = validateSerializedDiagram;
+/** Thrown by strict-mode loads when the document has integrity errors. */
+class DiagramValidationError extends Error {
+    constructor(report) {
+        super(`Diagram document failed integrity validation with ${report.errors.length} error(s): ` +
+            report.errors.map((e) => `[${e.code}] ${e.message}`).join('; '));
+        this.report = report;
+        this.name = 'DiagramValidationError';
+    }
+}
+exports.DiagramValidationError = DiagramValidationError;
+function validateSerializedDiagram(data) {
+    var _a, _b, _c, _d, _e, _f;
+    const errors = [];
+    const warnings = [];
+    const error = (code, message, entityId) => errors.push({ severity: 'error', code, message, entityId });
+    const warning = (code, message, entityId) => warnings.push({ severity: 'warning', code, message, entityId });
+    const nodes = (_a = data.nodes) !== null && _a !== void 0 ? _a : [];
+    const links = (_b = data.links) !== null && _b !== void 0 ? _b : [];
+    const groups = (_c = data.groups) !== null && _c !== void 0 ? _c : [];
+    const strokes = (_d = data.strokes) !== null && _d !== void 0 ? _d : []; // wave10/whiteboard
+    // --- duplicate ids (within and across collections) -----------------------
+    const seen = new Map(); // id -> collection
+    const checkId = (id, kind) => {
+        if (!id) {
+            error('missing-id', `A serialized ${kind} has no id`);
+            return;
+        }
+        const prior = seen.get(id);
+        if (prior) {
+            error('duplicate-id', `Id '${id}' is used by both a ${prior} and a ${kind}`, id);
+        }
+        else {
+            seen.set(id, kind);
+        }
+    };
+    nodes.forEach((n) => checkId(n === null || n === void 0 ? void 0 : n.id, 'node'));
+    links.forEach((l) => checkId(l === null || l === void 0 ? void 0 : l.id, 'link'));
+    groups.forEach((g) => checkId(g === null || g === void 0 ? void 0 : g.id, 'group'));
+    // wave10/whiteboard. Ink joins the CROSS-COLLECTION id check, which is the point: a
+    // stroke sharing an id with a node is exactly the corruption `applyOp` cannot survive
+    // (the op targets are per-kind, but undo's register key is `target id path`, and two
+    // kinds under one id make two different entities share one register).
+    strokes.forEach((s) => checkId(s === null || s === void 0 ? void 0 : s.id, 'stroke'));
+    // A stroke with no points draws nothing and hit-tests as nothing — it is invisible
+    // débris that can only be removed by an eraser that cannot find it. Not an error (the
+    // document is structurally sound), but the user should know it is there.
+    for (const s of strokes) {
+        if (!s)
+            continue;
+        if (!Array.isArray(s.points) || s.points.length === 0) {
+            warning('empty-stroke', `Stroke '${s.id}' has no points and can never be seen`, s.id);
+        }
+        else if (s.points.some((p) => !p || !isFinite(p.x) || !isFinite(p.y))) {
+            error('invalid-stroke-point', `Stroke '${s.id}' has a non-finite point, which poisons its bounds to NaN and ` +
+                `culls it from every viewport query`, s.id);
+        }
+    }
+    // --- port ownership map ---------------------------------------------------
+    const portOwner = new Map(); // portId -> nodeId
+    for (const n of nodes) {
+        for (const p of (_e = n === null || n === void 0 ? void 0 : n.ports) !== null && _e !== void 0 ? _e : []) {
+            if (!(p === null || p === void 0 ? void 0 : p.id))
+                continue;
+            const prior = portOwner.get(p.id);
+            if (prior && prior !== n.id) {
+                error('duplicate-port-id', `Port id '${p.id}' appears on both node '${prior}' and node '${n.id}'`, p.id);
+            }
+            portOwner.set(p.id, n.id);
+        }
+    }
+    // --- link endpoints resolve to real ports ---------------------------------
+    for (const l of links) {
+        if (!l)
+            continue;
+        for (const [end, portId] of [
+            ['source', l.sourcePortId],
+            ['target', l.targetPortId],
+        ]) {
+            if (!portId || !portOwner.has(portId)) {
+                error('dangling-link-endpoint', `Link '${l.id}' ${end} port '${portId !== null && portId !== void 0 ? portId : '(none)'}' does not exist on any serialized node`, l.id);
+            }
+        }
+    }
+    // --- node parent references ------------------------------------------------
+    const nodeIds = new Set(nodes.map((n) => n === null || n === void 0 ? void 0 : n.id).filter(Boolean));
+    for (const n of nodes) {
+        if ((n === null || n === void 0 ? void 0 : n.parentId) && !nodeIds.has(n.parentId)) {
+            warning('missing-parent', `Node '${n.id}' references missing parent '${n.parentId}'`, n.id);
+        }
+    }
+    // --- group membership + containment tree -----------------------------------
+    const groupIds = new Set(groups.map((g) => g === null || g === void 0 ? void 0 : g.id).filter(Boolean));
+    for (const g of groups) {
+        if (!g)
+            continue;
+        for (const member of (_f = g.members) !== null && _f !== void 0 ? _f : []) {
+            if (!nodeIds.has(member) && !groupIds.has(member)) {
+                warning('missing-group-member', `Group '${g.id}' references missing member '${member}'`, g.id);
+            }
+        }
+        if (g.parentGroupId !== undefined) {
+            if (!groupIds.has(g.parentGroupId)) {
+                error('missing-parent-group', `Group '${g.id}' references missing parent group '${g.parentGroupId}'`, g.id);
+            }
+        }
+    }
+    // containment cycles (follow parentGroupId pointers)
+    const parentOf = new Map(groups.filter(Boolean).map((g) => [g.id, g.parentGroupId]));
+    for (const g of groups) {
+        if (!g)
+            continue;
+        const trail = new Set([g.id]);
+        let cur = parentOf.get(g.id);
+        while (cur !== undefined) {
+            if (trail.has(cur)) {
+                error('group-cycle', `Group containment cycle involving '${g.id}'`, g.id);
+                break;
+            }
+            trail.add(cur);
+            cur = parentOf.get(cur);
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+//# sourceMappingURL=DiagramValidator.js.map

package/src/libs/engine/src/serialization/DiagramValidator.js.map

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

package/src/libs/engine/src/serialization/DocumentEnvelope.d.ts

@@ -0,0 +1,53 @@
+import type { SerializedDiagram } from '../models/DiagramModel';
+export declare const DIAGRAM_ENVELOPE_FORMAT: "grafloria-diagram";
+export declare const DIAGRAM_ENVELOPE_VERSION = 1;
+export interface DiagramDocumentEnvelope {
+    format: typeof DIAGRAM_ENVELOPE_FORMAT;
+    envelopeVersion: number;
+    /** Writer identity, e.g. '@grafloria/engine'. */
+    generator: string;
+    /** Writer version — the document schemaVersion the writer targets. */
+    generatorVersion: string;
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+    /** FNV-1a hash of the canonical JSON of `document` (see canonicalStringify). */
+    checksum?: string;
+    document: SerializedDiagram;
+}
+/**
+ * Deterministic JSON: object keys sorted recursively so the same logical
+ * document always hashes identically, regardless of property insertion order.
+ * (Arrays keep their order — element order IS meaning in nodes/links.)
+ */
+export declare function canonicalStringify(value: unknown): string;
+/** FNV-1a 32-bit over a string, hex encoded — cheap, dependency-free. */
+export declare function fnv1aHex(text: string): string;
+/** Integrity checksum of a document's canonical JSON. */
+export declare function checksumOf(document: SerializedDiagram): string;
+export interface WrapOptions {
+    generator?: string;
+    generatorVersion?: string;
+    /** Include an integrity checksum (default true). */
+    checksum?: boolean;
+    /** Timestamp override (tests / deterministic exports). */
+    createdAt?: string;
+}
+export declare function wrapDiagramDocument(document: SerializedDiagram, options?: WrapOptions): DiagramDocumentEnvelope;
+export declare function isDiagramDocumentEnvelope(value: unknown): value is DiagramDocumentEnvelope;
+export declare class DiagramChecksumError extends Error {
+    readonly expected: string;
+    readonly actual: string;
+    constructor(expected: string, actual: string);
+}
+export interface UnwrapResult {
+    document: SerializedDiagram;
+    /** Present when the input was enveloped. */
+    envelope?: DiagramDocumentEnvelope;
+}
+/**
+ * Accepts an enveloped document OR a legacy flat SerializedDiagram and
+ * returns the inner document. When the envelope carries a checksum it is
+ * verified (throws DiagramChecksumError on mismatch — an integrity failure
+ * must never load silently).
+ */
+export declare function unwrapDiagramDocument(input: SerializedDiagram | DiagramDocumentEnvelope): UnwrapResult;

package/src/libs/engine/src/serialization/DocumentEnvelope.js

@@ -0,0 +1,111 @@
+"use strict";
+// Portable document envelope — the stable OUTER shape of a persisted diagram.
+//
+// The envelope answers the questions a document store, an export file, or a
+// support ticket needs answered WITHOUT parsing the model: what format is
+// this, which app/version wrote it, when, and has it been corrupted in
+// transit (checksum over a canonical serialization). The inner `document` is
+// the SerializedDiagram, which carries its own schemaVersion + migration
+// chain (DiagramMigrations).
+//
+// Adoption is opt-in: `unwrapDiagramDocument` accepts BOTH enveloped and
+// legacy flat payloads, so existing persisted documents keep loading.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagramChecksumError = exports.DIAGRAM_ENVELOPE_VERSION = exports.DIAGRAM_ENVELOPE_FORMAT = void 0;
+exports.canonicalStringify = canonicalStringify;
+exports.fnv1aHex = fnv1aHex;
+exports.checksumOf = checksumOf;
+exports.wrapDiagramDocument = wrapDiagramDocument;
+exports.isDiagramDocumentEnvelope = isDiagramDocumentEnvelope;
+exports.unwrapDiagramDocument = unwrapDiagramDocument;
+exports.DIAGRAM_ENVELOPE_FORMAT = 'grafloria-diagram';
+exports.DIAGRAM_ENVELOPE_VERSION = 1;
+/**
+ * Deterministic JSON: object keys sorted recursively so the same logical
+ * document always hashes identically, regardless of property insertion order.
+ * (Arrays keep their order — element order IS meaning in nodes/links.)
+ */
+function canonicalStringify(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeysDeep);
+    }
+    if (value && typeof value === 'object') {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = sortKeysDeep(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/** FNV-1a 32-bit over a string, hex encoded — cheap, dependency-free. */
+function fnv1aHex(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+/** Integrity checksum of a document's canonical JSON. */
+function checksumOf(document) {
+    return fnv1aHex(canonicalStringify(document));
+}
+function wrapDiagramDocument(document, options = {}) {
+    var _a, _b, _c, _d;
+    const envelope = {
+        format: exports.DIAGRAM_ENVELOPE_FORMAT,
+        envelopeVersion: exports.DIAGRAM_ENVELOPE_VERSION,
+        generator: (_a = options.generator) !== null && _a !== void 0 ? _a : '@grafloria/engine',
+        generatorVersion: (_b = options.generatorVersion) !== null && _b !== void 0 ? _b : String((_c = document.schemaVersion) !== null && _c !== void 0 ? _c : 1),
+        createdAt: (_d = options.createdAt) !== null && _d !== void 0 ? _d : new Date().toISOString(),
+        document,
+    };
+    if (options.checksum !== false) {
+        envelope.checksum = checksumOf(document);
+    }
+    return envelope;
+}
+function isDiagramDocumentEnvelope(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        value.format === exports.DIAGRAM_ENVELOPE_FORMAT &&
+        typeof value.envelopeVersion === 'number' &&
+        !!value.document);
+}
+class DiagramChecksumError extends Error {
+    constructor(expected, actual) {
+        super(`Diagram document checksum mismatch (expected ${expected}, computed ${actual}) — ` +
+            `the payload was modified or corrupted after it was written.`);
+        this.expected = expected;
+        this.actual = actual;
+        this.name = 'DiagramChecksumError';
+    }
+}
+exports.DiagramChecksumError = DiagramChecksumError;
+/**
+ * Accepts an enveloped document OR a legacy flat SerializedDiagram and
+ * returns the inner document. When the envelope carries a checksum it is
+ * verified (throws DiagramChecksumError on mismatch — an integrity failure
+ * must never load silently).
+ */
+function unwrapDiagramDocument(input) {
+    if (isDiagramDocumentEnvelope(input)) {
+        if (input.envelopeVersion > exports.DIAGRAM_ENVELOPE_VERSION) {
+            throw new Error(`Diagram envelope version ${input.envelopeVersion} is newer than this runtime ` +
+                `(${exports.DIAGRAM_ENVELOPE_VERSION}) — refusing to load.`);
+        }
+        if (input.checksum) {
+            const actual = checksumOf(input.document);
+            if (actual !== input.checksum) {
+                throw new DiagramChecksumError(input.checksum, actual);
+            }
+        }
+        return { document: input.document, envelope: input };
+    }
+    return { document: input };
+}
+//# sourceMappingURL=DocumentEnvelope.js.map

package/src/libs/engine/src/serialization/DocumentEnvelope.js.map

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

package/src/libs/engine/src/serialization/Incremental.d.ts

@@ -0,0 +1,77 @@
+import type { DiagramModel } from '../models/DiagramModel';
+import type { SerializedNode } from '../models/NodeModel';
+import type { SerializedLink } from '../models/LinkModel';
+import type { SerializedGroup } from '../models/GroupModel';
+import type { SerializedStroke } from '../models/StrokeModel';
+export declare const INCREMENTAL_FORMAT: "grafloria-incremental";
+export interface DiagramIncremental {
+    format: typeof INCREMENTAL_FORMAT;
+    schemaVersion: number;
+    /** diagram.version at the moment the window began (ordering hint). */
+    baseVersion: number;
+    /** diagram.version at commit — apply converges the replica's counter to it. */
+    targetVersion: number;
+    added: {
+        nodes: SerializedNode[];
+        links: SerializedLink[];
+        groups: SerializedGroup[];
+        strokes?: SerializedStroke[];
+    };
+    removed: {
+        nodes: string[];
+        links: string[];
+        groups: string[];
+        strokes?: string[];
+    };
+    modified: {
+        nodes: SerializedNode[];
+        links: SerializedLink[];
+        groups: SerializedGroup[];
+        strokes?: SerializedStroke[];
+    };
+    diagram?: {
+        name?: string;
+        viewport?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+            zoom: number;
+        };
+        metadata?: Record<string, unknown>;
+    };
+}
+/**
+ * Watches a live diagram and produces a DiagramIncremental per commit().
+ * Continues capturing after commit (autosave-loop friendly) until stop().
+ */
+export declare class IncrementalCapture {
+    private readonly diagram;
+    private nodes;
+    private links;
+    private groups;
+    private strokes;
+    private baseVersion;
+    private nameSnapshot;
+    private viewportSnapshot;
+    private metadataSnapshot;
+    private disposers;
+    private groupDisposers;
+    private stopped;
+    constructor(diagram: DiagramModel);
+    private watchGroup;
+    private unwatchGroup;
+    /** Anything captured since the window began? */
+    hasChanges(): boolean;
+    private diagramChanges;
+    /**
+     * Drain the window into a patch (null when nothing changed) and keep
+     * capturing. Added/modified entities are serialized LIVE at commit time,
+     * so intra-window churn costs nothing.
+     */
+    commit(): DiagramIncremental | null;
+    /** Unsubscribe everything. The capture cannot be reused afterwards. */
+    stop(): void;
+}
+/** Convenience: start watching a diagram for incremental commits. */
+export declare function beginIncrementalCapture(diagram: DiagramModel): IncrementalCapture;