@grafloria/element 0.3.17 → 0.3.19

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

@@ -0,0 +1,227 @@
+"use strict";
+// Incremental (diff) serialization — per-transaction deltas instead of full
+// snapshots. The substrate for autosave, DB persistence, and multiplayer sync
+// (GoJS's toIncrementalJson/applyIncrementalJson is the reference model).
+//
+// Capture side (this file): IncrementalCapture subscribes to a live diagram's
+// event stream and coalesces mutations between commits into a patch:
+//   - added:    full serialized entities (created since last commit)
+//   - removed:  ids
+//   - modified: full serialized entities (REPLACE semantics — deterministic,
+//                and immune to the changeLog ring-buffer truncation that a
+//                per-property delta would depend on)
+//   - diagram:  name/viewport/metadata when they changed
+// add+remove of the same entity within one window coalesces to a no-op.
+//
+// Apply side: DiagramModel.applyIncremental(patch) — lives on the model (it
+// needs the private indices) and installs added entities through the SAME
+// unified restore path as document load, updates modified entities IN PLACE
+// (object identity preserved for renderers holding references), and fires
+// normal change events so listeners repaint.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IncrementalCapture = exports.INCREMENTAL_FORMAT = void 0;
+exports.beginIncrementalCapture = beginIncrementalCapture;
+const DiagramMigrations_1 = require("./DiagramMigrations");
+exports.INCREMENTAL_FORMAT = 'grafloria-incremental';
+const emptyIds = () => ({ added: new Set(), removed: new Set(), modified: new Set() });
+/**
+ * Watches a live diagram and produces a DiagramIncremental per commit().
+ * Continues capturing after commit (autosave-loop friendly) until stop().
+ */
+class IncrementalCapture {
+    constructor(diagram) {
+        this.diagram = diagram;
+        this.nodes = emptyIds();
+        this.links = emptyIds();
+        this.groups = emptyIds();
+        this.strokes = emptyIds(); // wave10/whiteboard
+        this.disposers = [];
+        this.groupDisposers = new Map();
+        this.stopped = false;
+        this.baseVersion = diagram.version;
+        this.nameSnapshot = diagram.name;
+        this.viewportSnapshot = JSON.stringify(diagram.viewport);
+        this.metadataSnapshot = JSON.stringify(Object.fromEntries(diagram.metadata));
+        const track = (ids) => ({
+            added: (entity) => {
+                if (ids.removed.has(entity.id)) {
+                    // removed then re-added inside one window = a modification
+                    ids.removed.delete(entity.id);
+                    ids.modified.add(entity.id);
+                }
+                else {
+                    ids.added.add(entity.id);
+                }
+            },
+            removed: (entity) => {
+                if (ids.added.has(entity.id)) {
+                    // add+remove inside one window coalesces to a no-op
+                    ids.added.delete(entity.id);
+                }
+                else {
+                    ids.removed.add(entity.id);
+                }
+                ids.modified.delete(entity.id);
+            },
+            changed: (entity) => {
+                if (!ids.added.has(entity.id) && !ids.removed.has(entity.id)) {
+                    ids.modified.add(entity.id);
+                }
+            },
+        });
+        const n = track(this.nodes);
+        const l = track(this.links);
+        const g = track(this.groups);
+        const s = track(this.strokes); // wave10/whiteboard
+        this.disposers.push(
+        // Ink. Strokes are immutable after commit (you draw one, you erase one — you do
+        // not edit one point-by-point), so unlike groups there is no per-entity change
+        // stream to watch. If stroke editing ever lands, it needs a watchStroke() exactly
+        // like watchGroup() below, or the edit will not reach this channel.
+        diagram.on('stroke:added', s.added), diagram.on('stroke:removed', s.removed), diagram.on('node:added', n.added), diagram.on('node:removed', n.removed), diagram.on('node:changed', n.changed), 
+        // moves/resizes are forwarded as dedicated events, not node:changed
+        diagram.on('node:moved', ({ nodeId }) => n.changed({ id: nodeId })), diagram.on('node:resized', ({ nodeId }) => n.changed({ id: nodeId })), diagram.on('link:added', l.added), diagram.on('link:removed', l.removed), diagram.on('link:changed', l.changed), diagram.on('group:added', (group) => {
+            g.added(group);
+            this.watchGroup(group.id);
+        }), diagram.on('group:removed', (group) => {
+            g.removed(group);
+            this.unwatchGroup(group.id);
+        }));
+        // Group mutations are NOT forwarded at diagram level — watch each group's
+        // own change stream (and every group that appears while capturing).
+        for (const group of diagram.getGroups()) {
+            this.watchGroup(group.id);
+        }
+    }
+    watchGroup(groupId) {
+        if (this.groupDisposers.has(groupId))
+            return;
+        const group = this.diagram.getGroup(groupId);
+        if (!group)
+            return;
+        this.groupDisposers.set(groupId, group.on('change', () => {
+            if (!this.groups.added.has(groupId) && !this.groups.removed.has(groupId)) {
+                this.groups.modified.add(groupId);
+            }
+        }));
+    }
+    unwatchGroup(groupId) {
+        var _a;
+        (_a = this.groupDisposers.get(groupId)) === null || _a === void 0 ? void 0 : _a();
+        this.groupDisposers.delete(groupId);
+    }
+    /** Anything captured since the window began? */
+    hasChanges() {
+        const any = (ids) => ids.added.size + ids.removed.size + ids.modified.size > 0;
+        return (any(this.nodes) ||
+            any(this.links) ||
+            any(this.groups) ||
+            any(this.strokes) ||
+            this.diagramChanges() !== undefined);
+    }
+    diagramChanges() {
+        const out = {};
+        if (this.diagram.name !== this.nameSnapshot)
+            out.name = this.diagram.name;
+        if (JSON.stringify(this.diagram.viewport) !== this.viewportSnapshot) {
+            out.viewport = Object.assign({}, this.diagram.viewport);
+        }
+        const metadata = Object.fromEntries(this.diagram.metadata);
+        if (JSON.stringify(metadata) !== this.metadataSnapshot)
+            out.metadata = metadata;
+        return Object.keys(out).length ? out : undefined;
+    }
+    /**
+     * 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() {
+        if (this.stopped) {
+            throw new Error('IncrementalCapture is stopped');
+        }
+        if (!this.hasChanges())
+            return null;
+        const serializeNodes = (ids) => [...ids]
+            .map((id) => { var _a; return (_a = this.diagram.getNode(id)) === null || _a === void 0 ? void 0 : _a.serialize(); })
+            .filter((d) => !!d);
+        const serializeLinks = (ids) => [...ids]
+            .map((id) => { var _a; return (_a = this.diagram.getLink(id)) === null || _a === void 0 ? void 0 : _a.serialize(); })
+            .filter((d) => !!d);
+        const serializeGroups = (ids) => [...ids]
+            .map((id) => { var _a; return (_a = this.diagram.getGroup(id)) === null || _a === void 0 ? void 0 : _a.serialize(); })
+            .filter((d) => !!d);
+        const serializeStrokes = (ids) => [...ids]
+            .map((id) => { var _a; return (_a = this.diagram.getStroke(id)) === null || _a === void 0 ? void 0 : _a.serialize(); })
+            .filter((d) => !!d);
+        const patch = {
+            format: exports.INCREMENTAL_FORMAT,
+            schemaVersion: DiagramMigrations_1.DIAGRAM_SCHEMA_VERSION,
+            baseVersion: this.baseVersion,
+            targetVersion: this.diagram.version,
+            added: {
+                nodes: serializeNodes(this.nodes.added),
+                links: serializeLinks(this.links.added),
+                groups: serializeGroups(this.groups.added),
+            },
+            removed: {
+                nodes: [...this.nodes.removed],
+                links: [...this.links.removed],
+                groups: [...this.groups.removed],
+            },
+            modified: {
+                nodes: serializeNodes(this.nodes.modified),
+                links: serializeLinks(this.links.modified),
+                groups: serializeGroups(this.groups.modified),
+            },
+        };
+        // wave10/whiteboard: written only when there IS ink in the window, so a patch from a
+        // diagram nobody has drawn on is byte-identical to the one this class emitted before
+        // this wave. (Same rule as the document's `strokes` key.)
+        if (this.strokes.added.size)
+            patch.added.strokes = serializeStrokes(this.strokes.added);
+        if (this.strokes.removed.size)
+            patch.removed.strokes = [...this.strokes.removed];
+        if (this.strokes.modified.size) {
+            patch.modified.strokes = serializeStrokes(this.strokes.modified);
+        }
+        const diagramDelta = this.diagramChanges();
+        if (diagramDelta)
+            patch.diagram = diagramDelta;
+        // Reset the window IN PLACE — the event listeners hold references to
+        // these exact Ids objects (bound in the constructor); reassigning would
+        // orphan them and silently stop capture after the first commit.
+        const resetIds = (ids) => {
+            ids.added.clear();
+            ids.removed.clear();
+            ids.modified.clear();
+        };
+        resetIds(this.nodes);
+        resetIds(this.links);
+        resetIds(this.groups);
+        resetIds(this.strokes);
+        this.baseVersion = this.diagram.version;
+        this.nameSnapshot = this.diagram.name;
+        this.viewportSnapshot = JSON.stringify(this.diagram.viewport);
+        this.metadataSnapshot = JSON.stringify(Object.fromEntries(this.diagram.metadata));
+        return patch;
+    }
+    /** Unsubscribe everything. The capture cannot be reused afterwards. */
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        for (const dispose of this.disposers)
+            dispose();
+        this.disposers = [];
+        for (const dispose of this.groupDisposers.values())
+            dispose();
+        this.groupDisposers.clear();
+    }
+}
+exports.IncrementalCapture = IncrementalCapture;
+/** Convenience: start watching a diagram for incremental commits. */
+function beginIncrementalCapture(diagram) {
+    return new IncrementalCapture(diagram);
+}
+//# sourceMappingURL=Incremental.js.map

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

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

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

@@ -0,0 +1,29 @@
+import { DiagramModel } from '../models/DiagramModel';
+import type { SerializedDiagram as DiagramSerializedData, DiagramLoadOptions } from '../models/DiagramModel';
+import type { DiagramMode } from '../engine/DiagramMode';
+import { type DiagramDocumentEnvelope, type WrapOptions } from './DocumentEnvelope';
+export interface SerializedDiagram extends Omit<DiagramSerializedData, 'version'> {
+    version: string;
+    diagramVersion?: number;
+    mode?: DiagramMode;
+}
+export declare class DiagramSerializer {
+    private readonly VERSION;
+    /**
+     * Serialize diagram to plain object
+     */
+    serialize(diagram: DiagramModel): SerializedDiagram;
+    /**
+     * Serialize wrapped in the portable document envelope (generator identity,
+     * createdAt, integrity checksum). The envelope is the recommended shape for
+     * NEW persistence; deserialize() accepts both it and the legacy flat form.
+     */
+    serializeEnvelope(diagram: DiagramModel, options?: WrapOptions): DiagramDocumentEnvelope;
+    /**
+     * Deserialize diagram from plain object — accepts the enveloped document,
+     * the legacy Serializer flat form, or a raw DiagramModel.serialize payload.
+     * Envelope checksums are verified (mismatch throws — corruption must never
+     * load silently).
+     */
+    deserialize(data: SerializedDiagram | DiagramDocumentEnvelope, options?: DiagramLoadOptions): DiagramModel;
+}

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

@@ -0,0 +1,45 @@
+"use strict";
+// DiagramSerializer - Handles diagram serialization/deserialization
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagramSerializer = void 0;
+const DiagramModel_1 = require("../models/DiagramModel");
+const DocumentEnvelope_1 = require("./DocumentEnvelope");
+class DiagramSerializer {
+    constructor() {
+        this.VERSION = '1.0.0';
+    }
+    /**
+     * Serialize diagram to plain object
+     */
+    serialize(diagram) {
+        const serialized = diagram.serialize();
+        // Override version with serializer format version
+        return Object.assign(Object.assign({}, serialized), { version: this.VERSION, diagramVersion: serialized.version });
+    }
+    /**
+     * Serialize wrapped in the portable document envelope (generator identity,
+     * createdAt, integrity checksum). The envelope is the recommended shape for
+     * NEW persistence; deserialize() accepts both it and the legacy flat form.
+     */
+    serializeEnvelope(diagram, options) {
+        return (0, DocumentEnvelope_1.wrapDiagramDocument)(diagram.serialize(), options);
+    }
+    /**
+     * Deserialize diagram from plain object — accepts the enveloped document,
+     * the legacy Serializer flat form, or a raw DiagramModel.serialize payload.
+     * Envelope checksums are verified (mismatch throws — corruption must never
+     * load silently).
+     */
+    deserialize(data, options) {
+        if ((0, DocumentEnvelope_1.isDiagramDocumentEnvelope)(data)) {
+            const { document } = (0, DocumentEnvelope_1.unwrapDiagramDocument)(data);
+            return DiagramModel_1.DiagramModel.fromJSON(document, options);
+        }
+        // Legacy flat form: convert back to diagram format
+        const diagramData = Object.assign(Object.assign({}, data), { version: data.diagramVersion || Number(data.version) || 1 });
+        // Use static fromJSON method (migrations + optional validation run there)
+        return DiagramModel_1.DiagramModel.fromJSON(diagramData, options);
+    }
+}
+exports.DiagramSerializer = DiagramSerializer;
+//# sourceMappingURL=Serializer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Serializer.js","sourceRoot":"","sources":["../../../../../../engine/src/serialization/Serializer.ts"],"names":[],"mappings":";AAAA,oEAAoE;;;AAEpE,yDAAsD;AAMtD,yDAM4B;AAS5B,MAAa,iBAAiB;IAA9B;QACmB,YAAO,GAAG,OAAO,CAAC;IA8CrC,CAAC;IA5CC;;OAEG;IACH,SAAS,CAAC,OAAqB;QAC7B,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;QACvC,kDAAkD;QAClD,uCACK,UAAU,KACb,OAAO,EAAE,IAAI,CAAC,OAAO,EACrB,cAAc,EAAE,UAAU,CAAC,OAAO,IAClC;IACJ,CAAC;IAED;;;;OAIG;IACH,iBAAiB,CAAC,OAAqB,EAAE,OAAqB;QAC5D,OAAO,IAAA,sCAAmB,EAAC,OAAO,CAAC,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;OAKG;IACH,WAAW,CACT,IAAiD,EACjD,OAA4B;QAE5B,IAAI,IAAA,4CAAyB,EAAC,IAAI,CAAC,EAAE,CAAC;YACpC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAA,wCAAqB,EAAC,IAAI,CAAC,CAAC;YACjD,OAAO,2BAAY,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAClD,CAAC;QACD,mDAAmD;QACnD,MAAM,WAAW,mCACZ,IAAI,KACP,OAAO,EAAE,IAAI,CAAC,cAAc,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAC1D,CAAC;QACF,0EAA0E;QAC1E,OAAO,2BAAY,CAAC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACrD,CAAC;CACF;AA/CD,8CA+CC"}

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

@@ -0,0 +1,51 @@
+import { DiagramModel } from '../models/DiagramModel';
+import { NodeModel, type SerializedNode } from '../models/NodeModel';
+import { LinkModel, type SerializedLink } from '../models/LinkModel';
+import { GroupModel, type SerializedGroup } from '../models/GroupModel';
+import type { Point } from '../types';
+export declare const SUBGRAPH_FORMAT: "grafloria-subgraph";
+export interface SerializedSubgraph {
+    format: typeof SUBGRAPH_FORMAT;
+    schemaVersion: number;
+    sourceDiagramId?: string;
+    nodes: SerializedNode[];
+    links: SerializedLink[];
+    groups: SerializedGroup[];
+    /** Links that crossed the selection boundary and were therefore excluded. */
+    boundaryLinks: Array<{
+        linkId: string;
+        insideEnd: 'source' | 'target';
+    }>;
+}
+export interface SubgraphSelection {
+    nodeIds: Iterable<string>;
+    groupIds?: Iterable<string>;
+}
+export declare function serializeSubgraph(diagram: DiagramModel, selection: SubgraphSelection): SerializedSubgraph;
+export interface DeserializeSubgraphOptions {
+    /**
+     * Mint fresh ids/uuids for every entity (default true). Turn off only when
+     * importing into a diagram KNOWN not to contain the ids (e.g. template
+     * instantiation into an empty document where stable ids are wanted).
+     */
+    remapIds?: boolean;
+    /** Translate all node/group positions by this delta (paste-at-cursor). */
+    offset?: Point;
+}
+export interface DeserializedSubgraph {
+    nodes: NodeModel[];
+    links: LinkModel[];
+    groups: GroupModel[];
+    /** oldId -> newId for nodes and groups (identity map when remapIds=false). */
+    idMap: Map<string, string>;
+    /** oldPortId -> newPortId (identity when remapIds=false). */
+    portIdMap: Map<string, string>;
+}
+/**
+ * Install a subgraph into a live diagram through the unified restore path.
+ *
+ * This is a USER MUTATION (unlike document load): entities are installed via
+ * restore* so the normal node:added/link:added events fire for undo and
+ * rendering, and port registries are reconciled at the end.
+ */
+export declare function deserializeSubgraphInto(diagram: DiagramModel, subgraph: SerializedSubgraph, options?: DeserializeSubgraphOptions): DeserializedSubgraph;

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

@@ -0,0 +1,172 @@
+"use strict";
+// First-class subgraph serialization — ONE code path for clipboard fragments,
+// templates, and cross-diagram slices.
+//
+// serializeSubgraph captures a selection as a self-contained document: the
+// selected nodes, every link whose BOTH endpoints live inside the selection,
+// and the selected groups with their membership filtered to the selection.
+// Links that cross the boundary are recorded (not silently dropped) so
+// callers can surface them.
+//
+// deserializeSubgraphInto installs a subgraph into a live diagram through the
+// SAME unified restore path as document load (fully wired entities), with
+// id/uuid remapping on by default — pasting twice must yield two independent
+// copies, never id collisions.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBGRAPH_FORMAT = void 0;
+exports.serializeSubgraph = serializeSubgraph;
+exports.deserializeSubgraphInto = deserializeSubgraphInto;
+const NodeModel_1 = require("../models/NodeModel");
+const remapNodePortIds_1 = require("../commands/basic/remapNodePortIds");
+const id_1 = require("../utils/id");
+const DiagramMigrations_1 = require("./DiagramMigrations");
+exports.SUBGRAPH_FORMAT = 'grafloria-subgraph';
+function serializeSubgraph(diagram, selection) {
+    var _a;
+    const nodeIds = new Set(selection.nodeIds);
+    const groupIds = new Set((_a = selection.groupIds) !== null && _a !== void 0 ? _a : []);
+    const nodes = [];
+    const selectedPortIds = new Set();
+    for (const nodeId of nodeIds) {
+        const node = diagram.getNode(nodeId);
+        if (!node)
+            continue;
+        nodes.push(node.serialize());
+        for (const port of node.getPorts()) {
+            selectedPortIds.add(port.id);
+        }
+    }
+    const links = [];
+    const boundaryLinks = [];
+    for (const link of diagram.getLinks()) {
+        const sourceIn = selectedPortIds.has(link.sourcePortId);
+        const targetIn = selectedPortIds.has(link.targetPortId);
+        if (sourceIn && targetIn) {
+            links.push(link.serialize());
+        }
+        else if (sourceIn || targetIn) {
+            boundaryLinks.push({ linkId: link.id, insideEnd: sourceIn ? 'source' : 'target' });
+        }
+    }
+    const groups = [];
+    for (const groupId of groupIds) {
+        const group = diagram.getGroup(groupId);
+        if (!group)
+            continue;
+        const serialized = group.serialize();
+        // Self-containment: membership and containment pointers may only
+        // reference things that travel with the subgraph.
+        serialized.members = serialized.members.filter((m) => nodeIds.has(m) || groupIds.has(m));
+        if (serialized.parentGroupId !== undefined && !groupIds.has(serialized.parentGroupId)) {
+            serialized.parentGroupId = undefined;
+        }
+        groups.push(serialized);
+    }
+    return {
+        format: exports.SUBGRAPH_FORMAT,
+        schemaVersion: DiagramMigrations_1.DIAGRAM_SCHEMA_VERSION,
+        sourceDiagramId: diagram.id,
+        nodes,
+        links,
+        groups,
+        boundaryLinks,
+    };
+}
+/**
+ * Install a subgraph into a live diagram through the unified restore path.
+ *
+ * This is a USER MUTATION (unlike document load): entities are installed via
+ * restore* so the normal node:added/link:added events fire for undo and
+ * rendering, and port registries are reconciled at the end.
+ */
+function deserializeSubgraphInto(diagram, subgraph, options = {}) {
+    var _a, _b;
+    const remap = options.remapIds !== false;
+    const offset = (_a = options.offset) !== null && _a !== void 0 ? _a : { x: 0, y: 0 };
+    const idMap = new Map();
+    const portIdMap = new Map();
+    // --- nodes ---------------------------------------------------------------
+    const nodes = [];
+    for (const nodeData of subgraph.nodes) {
+        const node = NodeModel_1.NodeModel.fromJSON(nodeData);
+        const oldId = node.id;
+        if (remap) {
+            const newId = (0, id_1.generateId)();
+            node.id = newId;
+            idMap.set(oldId, newId);
+            // Fresh port ids + uuids for the clone; records old->new port ids.
+            (0, remapNodePortIds_1.remapNodePortIds)(node, newId, portIdMap);
+        }
+        else {
+            idMap.set(oldId, oldId);
+            for (const port of node.getPorts()) {
+                portIdMap.set(port.id, port.id);
+            }
+        }
+        // Direct field write (not setPosition): applying the paste offset is part
+        // of materializing the clone, not a user mutation to version-track.
+        node.position = { x: node.position.x + offset.x, y: node.position.y + offset.y };
+        // Parent pointers may only reference nodes that travel with the subgraph.
+        if (node.parentId) {
+            node.parentId = (_b = idMap.get(node.parentId)) !== null && _b !== void 0 ? _b : undefined;
+        }
+        diagram.restoreNode(node.serialize());
+        // restoreNode re-creates from JSON; fetch the installed instance.
+        const installed = diagram.getNode(node.id);
+        nodes.push(installed);
+    }
+    // Second pass: parentId of an earlier node may reference a LATER node in
+    // the subgraph — resolve any still-unmapped parents now that idMap is full.
+    if (remap) {
+        for (const installed of nodes) {
+            if (installed.parentId && idMap.has(installed.parentId)) {
+                installed.parentId = idMap.get(installed.parentId);
+            }
+        }
+    }
+    // --- links ---------------------------------------------------------------
+    const links = [];
+    for (const linkData of subgraph.links) {
+        const sourcePortId = portIdMap.get(linkData.sourcePortId);
+        const targetPortId = portIdMap.get(linkData.targetPortId);
+        if (!sourcePortId || !targetPortId) {
+            // Endpoint didn't travel with the subgraph — skip rather than install
+            // a dangling link (serializeSubgraph should have excluded it already).
+            continue;
+        }
+        const data = Object.assign(Object.assign({}, linkData), { id: remap ? (0, id_1.generateId)() : linkData.id, uuid: remap ? (0, id_1.generateUUID)() : linkData.uuid, sourcePortId,
+            targetPortId, sourceNodeId: linkData.sourceNodeId ? idMap.get(linkData.sourceNodeId) : undefined, targetNodeId: linkData.targetNodeId ? idMap.get(linkData.targetNodeId) : undefined });
+        const link = diagram.restoreLink(data);
+        if (link)
+            links.push(link);
+    }
+    // --- groups --------------------------------------------------------------
+    const groups = [];
+    // First mint group ids so nested parentGroupId can remap regardless of order.
+    if (remap) {
+        for (const groupData of subgraph.groups) {
+            idMap.set(groupData.id, (0, id_1.generateId)());
+        }
+    }
+    else {
+        for (const groupData of subgraph.groups) {
+            idMap.set(groupData.id, groupData.id);
+        }
+    }
+    for (const groupData of subgraph.groups) {
+        const data = Object.assign(Object.assign({}, groupData), { id: idMap.get(groupData.id), uuid: remap ? (0, id_1.generateUUID)() : groupData.uuid, members: groupData.members
+                .map((m) => idMap.get(m))
+                .filter((m) => !!m), parentGroupId: groupData.parentGroupId !== undefined
+                ? idMap.get(groupData.parentGroupId)
+                : undefined, position: groupData.position
+                ? { x: groupData.position.x + offset.x, y: groupData.position.y + offset.y }
+                : groupData.position });
+        const group = diagram.restoreGroup(data);
+        if (group)
+            groups.push(group);
+    }
+    // --- derived state -------------------------------------------------------
+    diagram.reconcilePortConnections();
+    return { nodes, links, groups, idMap, portIdMap };
+}
+//# sourceMappingURL=Subgraph.js.map

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

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

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

@@ -0,0 +1,71 @@
+import { DiagramModel, type DiagramLoadOptions, type SerializedDiagram } from '../models/DiagramModel';
+export declare const GRAFLORIA_DOC_PREFIX = "%%grafloria:document ";
+export declare const GRAFLORIA_HASH_PREFIX = "%%grafloria:body-hash ";
+export interface ExportTextOptions {
+    /**
+     * Append the lossless sidecar (default true). Without it the text is pure
+     * Mermaid and imports are best-effort DSL parses (the lossy boundary).
+     */
+    lossless?: boolean;
+}
+export interface ImportTextOptions extends DiagramLoadOptions {
+    /**
+     * Which source wins when both exist:
+     *  - 'auto' (default): the sidecar wins UNLESS the body hash shows the body
+     *    was hand-edited after export — then the edited body wins.
+     *  - 'sidecar': always load the sidecar document (ignore body edits).
+     *  - 'text': always parse the body text (ignore the sidecar).
+     */
+    prefer?: 'auto' | 'sidecar' | 'text';
+}
+export interface ImportTextResult {
+    diagram: DiagramModel;
+    /** Which source actually produced the model. */
+    source: 'sidecar' | 'text';
+    /** True when a sidecar existed but the body had been hand-edited. */
+    bodyEdited: boolean;
+    /**
+     * True when a hand-edited body was applied ON TOP of the sidecar document —
+     * the edit took, and everything the grammar cannot express (positions,
+     * styles, ports, groups, viewport) survived from the sidecar.
+     */
+    sidecarMerged?: boolean;
+    /** True when a sidecar line existed but its JSON would not parse. */
+    sidecarInvalid?: boolean;
+    /**
+     * Set to the diagram-type name when the body is a Mermaid type we recognise
+     * but do not yet parse (sequenceDiagram, gantt, pie, …). The diagram is empty
+     * rather than a garbage flowchart. See docs/MERMAID-GAP-ANALYSIS.md Phase 0.
+     */
+    unsupported?: string;
+}
+/** The body without any %%grafloria sidecar lines (what a human reads/edits). */
+export declare function stripGrafloriaSidecar(text: string): string;
+/**
+ * Export a diagram as Mermaid-compatible text. With `lossless` (default) the
+ * exact document travels in a `%%grafloria:document` comment, so importing this
+ * text reproduces the diagram byte-for-byte (serialize-equality), while the
+ * body stays renderable by any Mermaid consumer.
+ */
+export declare function exportDiagramText(diagram: DiagramModel, options?: ExportTextOptions): string;
+/**
+ * The sidecar carries the DOCUMENT — not the viewing session and not derived
+ * per-frame state. Two families are stripped:
+ *
+ * - EPHEMERAL entity state (selected / hovered / focused): per-viewer facts.
+ *   Baked in, a committed file re-imports with a node pre-selected because
+ *   someone happened to have it selected at export time. Same reasoning (and
+ *   same key set) as the collab layer's EPHEMERAL exclusion in OpCapture.
+ * - Link `points`: the routed polyline is DERIVED — the renderer re-routes and
+ *   re-syncs it on the first frame. Serialized, a single smooth link drags a
+ *   17-sample flattened curve into the text form, churning every git diff the
+ *   "git-diffable text" story exists for.
+ */
+export declare function sanitizeForSidecar(doc: SerializedDiagram): SerializedDiagram;
+/**
+ * Import diagram text. Sidecar-carrying text loads losslessly through the
+ * unified JSON path; pure Mermaid text parses through the DSL (best effort —
+ * the documented lossy boundary). See ImportTextOptions.prefer for who wins
+ * when the body was hand-edited after export.
+ */
+export declare function importDiagramText(text: string, options?: ImportTextOptions): ImportTextResult;