@grafloria/element 0.3.17 → 0.3.19

package/src/libs/engine/src/models/NodeModel.js

@@ -0,0 +1,1512 @@
+"use strict";
+// NodeModel - Represents a node in the diagram
+// Layout item configuration storage added in Phase 1.7
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeModel = void 0;
+const DiagramEntity_1 = require("./DiagramEntity");
+const readonly_lock_1 = require("./readonly-lock"); // Wave 9 — Card 7
+const PortModel_1 = require("./PortModel");
+const utils_1 = require("../utils");
+const transform_1 = require("../utils/transform");
+/**
+ * The keys of `NodeState` that describe a VIEWER rather than the DOCUMENT.
+ *
+ * The same list collab/capture.ts strips before an op goes on the wire, and the same list
+ * the convergence oracle exempts. It lives here too because `replaceState` has to put them
+ * BACK: a register value never carries them, so a wholesale replace would blank the
+ * receiving user's own selection.
+ */
+const VIEW_STATE_KEYS = ['selected', 'hovered', 'highlighted', 'focused'];
+class NodeModel extends DiagramEntity_1.DiagramEntity {
+    /**
+     * Wave 9 — Card 7. Is a DOCUMENT write to this node forbidden right now?
+     * True only while the owning diagram is read-only and we are not inside a
+     * system write (auto-size / measurement). A detached node — one not yet added
+     * to any diagram — is freely mutable; `DiagramModel.addNode` is what refuses.
+     */
+    writeBlocked() {
+        return (0, readonly_lock_1.writeBlocked)(this.diagram);
+    }
+    /**
+     * D — is a DOCUMENT write to this node's GEOMETRY forbidden right now?
+     *
+     * `state.locked` used to be honoured by the input layers and by nothing else, so
+     * a "locked" node was moved without complaint by any command, script or importer
+     * that called `setPosition` — the same security-shaped lie the Wave-9 document
+     * lock was built to kill, one scope down.
+     *
+     * It draws exactly the Wave-9 distinction and for exactly the Wave-9 reason: a
+     * SYSTEM write (auto-size measuring text, a portal placing itself — anything
+     * inside `ReadonlyLock.runSystemWrite`) still passes, because refusing those
+     * renders a locked node at the wrong size and would have "worked" in a unit test
+     * while destroying the product.
+     *
+     * Scope is GEOMETRY only: position, size, rotation, scale. Style, data, classes,
+     * selection and `setState` itself stay open — you must be able to un-lock a
+     * locked node, and pinning a widget should not freeze its colour.
+     *
+     * A DETACHED node (no diagram back-reference) is freely mutable even with
+     * `locked` set: there is no document yet to protect, and you have to be able to
+     * BUILD a node before you can add it. Same tolerance `writeBlocked()` has.
+     */
+    geometryWriteBlocked() {
+        if (this.writeBlocked())
+            return true;
+        if (this.state.locked !== true)
+            return false;
+        // Locked, and attached: refuse unless the engine is doing a system write.
+        return this.diagram !== undefined && !(0, readonly_lock_1.isSystemWrite)(this.diagram);
+    }
+    constructor(config) {
+        super(config.id);
+        this.rotation = 0;
+        this.scale = { x: 1, y: 1 };
+        this.positionMode = 'absolute'; // Phase 1.6a: Default to absolute for backward compatibility
+        this.transformOrigin = { x: 0.5, y: 0.5 }; // Phase 1.6a: Default to center (normalized 0-1)
+        this.children = new Set();
+        this.depth = 0;
+        // Ports
+        this.ports = new Map();
+        // State
+        this.state = {
+            visible: true,
+            locked: false,
+            selected: false,
+            hovered: false,
+            focused: false,
+            expanded: true,
+            enabled: true,
+        };
+        // Behavior
+        this.behavior = {
+            selectable: true,
+            draggable: true,
+            resizable: true,
+            rotatable: false,
+            deletable: true,
+            editable: true,
+            connectable: true,
+            groupable: true,
+            cloneable: true,
+        };
+        // Styling
+        this.style = {};
+        this.classes = new Set();
+        // User Data
+        this.data = {};
+        this.computed = new Map();
+        this.type = config.type;
+        this.systemType = config.systemType;
+        this.definitionId = config.definitionId;
+        this.position = Object.assign({}, config.position);
+        this.size = config.size || { width: 100, height: 50 };
+        // Define diagram property as non-enumerable to prevent circular reference issues (Phase 1.6a)
+        Object.defineProperty(this, 'diagram', {
+            value: undefined,
+            writable: true,
+            enumerable: false,
+            configurable: true
+        });
+        // Phase 0.5.1: Auto-create default ports (industry standard)
+        this.initializeDefaultPorts();
+    }
+    /**
+     * Initialize default ports (Phase 0.5.1)
+     * Creates 4 bidirectional ports (top, right, bottom, left) automatically
+     * This matches industry standards (Draw.io, Lucidchart, mxGraph, yFiles)
+     *
+     * Ports can be accessed via:
+     * - node.getPortBySide('top')
+     * - node.getPortsBySide('right')
+     * - node.getPorts() // all ports
+     */
+    initializeDefaultPorts() {
+        const defaultPorts = [
+            { side: 'top', position: { x: 0.5, y: 0 } },
+            { side: 'right', position: { x: 1, y: 0.5 } },
+            { side: 'bottom', position: { x: 0.5, y: 1 } },
+            { side: 'left', position: { x: 0, y: 0.5 } },
+        ];
+        defaultPorts.forEach(({ side, position }) => {
+            const port = new PortModel_1.PortModel({
+                type: 'bi', // Bidirectional - can act as input or output
+                side,
+                position,
+                index: 0, // First (and only) port on this side
+            });
+            port.nodeId = this.id;
+            port.setMetadata('default', true); // Mark as auto-created
+            port.setMetadata('side', side); // Store side for easy querying
+            this.ports.set(port.id, port);
+        });
+    }
+    /**
+     * Set position
+     */
+    setPosition(x, y, z) {
+        if (this.geometryWriteBlocked())
+            return;
+        const oldPosition = Object.assign({}, this.position);
+        this.position = { x, y, z };
+        this.trackChange('position', oldPosition, this.position);
+        // Emit transform propagation event (Phase 1.6a Part 4)
+        this.emitTransformPropagated('position', this.position);
+    }
+    /**
+     * Move by delta
+     */
+    move(dx, dy, dz) {
+        if (this.geometryWriteBlocked())
+            return;
+        this.setPosition(this.position.x + dx, this.position.y + dy, this.position.z !== undefined && dz !== undefined
+            ? this.position.z + dz
+            : this.position.z);
+    }
+    /**
+     * Set size.
+     *
+     * A — this used to be five lines that wrote a field and told NOBODY, while its
+     * sibling `setPosition` has propagated since Phase 1.6a. A node growing inside a
+     * flex/grid container is a layout-invalidating event: its siblings have to move.
+     *
+     * It notifies its LAYOUT CONTAINERS, and deliberately NOT the transform chain
+     * `setPosition` uses: a parent's size does not move a relative child (the child's
+     * offset is measured from the parent ORIGIN), so emitting `transform-propagated`
+     * here would be noise that says something untrue.
+     */
+    setSize(width, height, depth) {
+        if (this.geometryWriteBlocked())
+            return;
+        const oldSize = Object.assign({}, this.size);
+        if (oldSize.width === width && oldSize.height === height && oldSize.depth === depth) {
+            return; // no-op: never wake a layout pass for a write that changed nothing
+        }
+        this.size = { width, height, depth };
+        this.trackChange('size', oldSize, this.size);
+        this.notifyLayoutContainers();
+    }
+    /**
+     * A — tell every layout container that owns this node that its geometry moved.
+     *
+     * The re-entrancy this obviously invites (container lays out → writes a child's
+     * size → child notifies the container → …) is closed on the container side by
+     * `GroupModel.applyLayout`'s in-flight guard: a push that arrives DURING a pass
+     * is dropped, because that pass is already computing the answer it would ask for.
+     */
+    notifyLayoutContainers() {
+        const diagram = this.diagram;
+        // `setSize` is HOT — layout adapters write thousands of them per run on graphs
+        // that have no groups at all. Iterate the Map directly (no `getGroups()` array
+        // allocation) and bail on the empty case before touching anything.
+        const groups = diagram === null || diagram === void 0 ? void 0 : diagram.groups;
+        if (!groups || groups.size === 0)
+            return;
+        for (const group of groups.values()) {
+            if (group.members.has(this.id)) {
+                group.requestLayout(diagram);
+            }
+        }
+    }
+    /**
+     * Resize by delta
+     */
+    resize(dw, dh, dd) {
+        if (this.geometryWriteBlocked())
+            return;
+        this.setSize(this.size.width + dw, this.size.height + dh, this.size.depth !== undefined && dd !== undefined
+            ? this.size.depth + dd
+            : this.size.depth);
+    }
+    /**
+     * Set rotation
+     */
+    setRotation(degrees) {
+        if (this.geometryWriteBlocked())
+            return;
+        const oldRotation = this.rotation;
+        this.rotation = degrees % 360;
+        this.trackChange('rotation', oldRotation, this.rotation);
+        // Emit transform propagation event (Phase 1.6a Part 4)
+        this.emitTransformPropagated('rotation', this.rotation);
+    }
+    /**
+     * Rotate by delta
+     */
+    rotate(degrees) {
+        if (this.geometryWriteBlocked())
+            return;
+        this.setRotation(this.rotation + degrees);
+    }
+    /**
+     * Set scale
+     */
+    setScale(x, y) {
+        if (this.geometryWriteBlocked())
+            return;
+        const oldScale = Object.assign({}, this.scale);
+        this.scale = { x, y };
+        this.trackChange('scale', oldScale, this.scale);
+        // Emit transform propagation event (Phase 1.6a Part 4)
+        this.emitTransformPropagated('scale', this.scale);
+    }
+    /**
+     * Add port
+     */
+    addPort(port) {
+        if (this.writeBlocked())
+            return;
+        if (this.ports.has(port.id)) {
+            throw new Error(`Port with id ${port.id} already exists`);
+        }
+        port.nodeId = this.id;
+        this.ports.set(port.id, port);
+        this.trackChange('ports', null, port);
+        this.emitter.emit('port:added', port);
+    }
+    /**
+     * Remove port
+     */
+    removePort(portId) {
+        if (this.writeBlocked())
+            return undefined;
+        const port = this.ports.get(portId);
+        if (port) {
+            this.ports.delete(portId);
+            this.trackChange('ports', port, null);
+            this.emitter.emit('port:removed', port);
+        }
+        return port;
+    }
+    /**
+     * Get port by ID
+     */
+    getPort(portId) {
+        return this.ports.get(portId);
+    }
+    /**
+     * Get all ports
+     */
+    getPorts() {
+        return Array.from(this.ports.values());
+    }
+    /**
+     * Links arriving at this node (resolved through the owning diagram; empty
+     * when the node isn't attached to a diagram yet)
+     */
+    getIncomingLinks() {
+        const diagram = this.diagram;
+        if (!(diagram === null || diagram === void 0 ? void 0 : diagram.getLinks))
+            return [];
+        return diagram.getLinks().filter((link) => link.targetNodeId === this.id);
+    }
+    /**
+     * Links leaving this node (resolved through the owning diagram)
+     */
+    getOutgoingLinks() {
+        const diagram = this.diagram;
+        if (!(diagram === null || diagram === void 0 ? void 0 : diagram.getLinks))
+            return [];
+        return diagram.getLinks().filter((link) => link.sourceNodeId === this.id);
+    }
+    /**
+     * Get ports by type
+     */
+    getPortsByType(type) {
+        return this.getPorts().filter((p) => p.type === type);
+    }
+    /**
+     * Get port by side (Phase 0.5.1)
+     * Returns the first port found on the specified side
+     *
+     * @param side - The side to search ('top', 'right', 'bottom', 'left')
+     * @returns The first port on that side, or undefined if none found
+     */
+    getPortBySide(side) {
+        return Array.from(this.ports.values()).find((port) => port.side === side);
+    }
+    /**
+     * Get all ports on a specific side (Phase 0.5.1)
+     * Useful for nodes with multiple ports per side
+     *
+     * @param side - The side to search ('top', 'right', 'bottom', 'left')
+     * @returns Array of ports on that side, sorted by index
+     */
+    getPortsBySide(side) {
+        return Array.from(this.ports.values())
+            .filter((port) => port.side === side)
+            .sort((a, b) => a.index - b.index); // Sort by index for consistent ordering
+    }
+    /**
+     * Get available ports that can accept connections (Phase 0.5.1)
+     *
+     * @param type - Optional filter by port type ('input', 'output', 'bi')
+     * @returns Array of ports that can accept more connections
+     */
+    getAvailablePorts(type) {
+        let ports = Array.from(this.ports.values());
+        if (type) {
+            ports = ports.filter((port) => port.type === type || port.type === 'bi');
+        }
+        return ports.filter((port) => port.canConnect());
+    }
+    /**
+     * Get ports that have active connections (Phase 0.5.1)
+     *
+     * @returns Array of ports with at least one connection
+     */
+    getConnectedPorts() {
+        return Array.from(this.ports.values()).filter((port) => port.getConnectionCount() > 0);
+    }
+    /**
+     * Set state property
+     */
+    setState(state) {
+        // Wave 9 — Card 7. A read-only document still needs EPHEMERAL view state:
+        // selection, hover, highlight and a11y focus are how a viewer reads the
+        // diagram, and the Wave-6 screen-reader layer depends on them. So read-only
+        // filters setState to the view keys instead of refusing it — refusing
+        // outright would have made a presentation-mode diagram unnavigable and
+        // silently broken the roving-tabindex contract.
+        //
+        // Everything else on NodeState (locked, visible, expanded, enabled, error,
+        // warning, status) is DOCUMENT state and is dropped while locked. `visible`
+        // and `expanded` in particular are written by group collapse/expand, which
+        // is an edit.
+        let incoming = state;
+        if (this.writeBlocked()) {
+            const view = {};
+            if ('selected' in state)
+                view.selected = state.selected;
+            if ('hovered' in state)
+                view.hovered = state.hovered;
+            if ('highlighted' in state)
+                view.highlighted = state.highlighted;
+            if ('focused' in state)
+                view.focused = state.focused;
+            if (Object.keys(view).length === 0)
+                return;
+            incoming = view;
+        }
+        const oldState = Object.assign({}, this.state);
+        this.state = Object.assign(Object.assign({}, this.state), incoming);
+        this.trackChange('state', oldState, this.state);
+    }
+    /**
+     * REPLACE the DOCUMENT half of `state`, keeping THIS viewer's own view half.
+     *
+     * The write `setState` cannot express, and the collab reducer's write path.
+     *
+     * ## Why a merge was wrong
+     *
+     * `state` is a value register: the op carries the whole (projected) object the author
+     * now holds. Applying it with the merging `setState` meant a peer could GAIN a key and
+     * never LOSE one — `NodeState.error`, `warning`, `status` and `animateStatus` are all
+     * optional, so the author clears an error badge and every other peer keeps it FOREVER,
+     * with no later edit able to correct it. Node `style` had exactly this defect and was
+     * fixed with `replaceStyle`; this is the same fix for the register next to it.
+     *
+     * ## Why it is not a plain wholesale replace either
+     *
+     * `selected` / `hovered` / `highlighted` / `focused` are facts about a VIEWER, not about
+     * the document. Capture strips them (see collab/capture.ts — syncing them meant your
+     * cursor lit up my node and your click deselected it), so an incoming register value
+     * never carries them. Replacing wholesale would therefore BLANK the receiving user's own
+     * selection on every remote state edit — reintroducing the very bug through the back
+     * door. So: durable keys replaced wholesale, view keys taken from what this replica
+     * already had.
+     *
+     * ## The read-only posture, deliberately UNCHANGED
+     *
+     * This refuses outright while the document is locked, exactly like `setPosition`,
+     * `setStyle` and `replaceStyle`. It does NOT copy `setState`'s Wave-9 Card-7 filter,
+     * and that is not an oversight:
+     *
+     *   • That filter exists so a LOCAL user can still select, hover and keyboard-navigate a
+     *     presentation-mode diagram. It is about input, not about the wire.
+     *   • It would be a no-op here anyway: capture strips the view keys, so an incoming
+     *     `state` value contains none of the keys the filter admits — a locked replica
+     *     already dropped remote state ops entirely, before this method existed. Behaviour
+     *     is therefore identical, and `setState` is left untouched.
+     *   • Making `state` the one register that DID reach a locked replica would be
+     *     incoherent: a read-only replica currently applies no remote document write at all
+     *     (verified — a locked peer ignores remote `position` and `style` too). That gap is
+     *     real and systemic, and it belongs to the lock, not to this register.
+     */
+    replaceState(state) {
+        if (this.writeBlocked())
+            return;
+        const oldState = Object.assign({}, this.state);
+        const next = Object.assign({}, state);
+        const prevView = oldState;
+        const nextView = next;
+        for (const key of VIEW_STATE_KEYS) {
+            if (key in prevView)
+                nextView[key] = prevView[key];
+        }
+        this.state = next;
+        this.trackChange('state', oldState, this.state);
+    }
+    /**
+     * Set behavior property
+     */
+    setBehavior(behavior) {
+        if (this.writeBlocked())
+            return;
+        const oldBehavior = Object.assign({}, this.behavior);
+        this.behavior = Object.assign(Object.assign({}, this.behavior), behavior);
+        this.trackChange('behavior', oldBehavior, this.behavior);
+    }
+    /**
+     * Check if node is selected
+     */
+    isSelected() {
+        return this.state.selected;
+    }
+    /**
+     * Set selection state
+     * @param selected - Whether the node should be selected
+     * @emits node:selected when node becomes selected
+     * @emits node:deselected when node becomes deselected
+     */
+    setSelected(selected) {
+        if (this.state.selected === selected) {
+            return; // No change
+        }
+        const oldState = Object.assign({}, this.state);
+        this.state.selected = selected;
+        this.trackChange('state', oldState, this.state);
+        // Emit specific selection events
+        this.emitter.emit(selected ? 'node:selected' : 'node:deselected', this);
+    }
+    /**
+     * Check if node is highlighted (attention state, independent of selection)
+     */
+    isHighlighted() {
+        return this.state.highlighted === true;
+    }
+    /**
+     * Set highlight state (attention emphasis without selecting the node)
+     * @param highlighted - Whether the node should be highlighted
+     * @emits node:highlighted when node becomes highlighted
+     * @emits node:unhighlighted when node stops being highlighted
+     */
+    setHighlighted(highlighted) {
+        if (this.isHighlighted() === highlighted) {
+            return; // No change
+        }
+        const oldState = Object.assign({}, this.state);
+        this.state.highlighted = highlighted;
+        this.trackChange('state', oldState, this.state);
+        this.emitter.emit(highlighted ? 'node:highlighted' : 'node:unhighlighted', this);
+    }
+    /**
+     * Check if node is selectable (based on behavior)
+     * Note: Locked nodes are still selectable so users can unlock them
+     */
+    isSelectable() {
+        return this.behavior.selectable;
+    }
+    /**
+     * Check if node is draggable (based on behavior and state)
+     * Note: Locked nodes cannot be dragged
+     */
+    isDraggable() {
+        return this.behavior.draggable && !this.state.locked;
+    }
+    /**
+     * Set style property
+     */
+    setStyle(style) {
+        if (this.writeBlocked())
+            return;
+        const oldStyle = Object.assign({}, this.style);
+        this.style = Object.assign(Object.assign({}, this.style), style);
+        this.trackChange('style', oldStyle, this.style);
+    }
+    /**
+     * REPLACE the whole style object — the write `setStyle` cannot express.
+     *
+     * `setStyle` merges, so it can add a key and overwrite a key but can never REMOVE
+     * one. Restoring a snapshot therefore has to assign wholesale, and the obvious way to
+     * do that — `node.style = snapshot` — is a plain field write that never passes
+     * `trackChange()`. That funnel is what collab captures from, so the direct assignment
+     * reaches the renderer (via markDirty) and reaches no other peer at all. That is not
+     * hypothetical: it is exactly how an undone LINK style stayed applied on every peer
+     * but the one that pressed Ctrl+Z. See collab/style-undo.spec.ts.
+     *
+     * Undo paths must use this, not the field.
+     */
+    replaceStyle(style) {
+        if (this.writeBlocked())
+            return;
+        const oldStyle = Object.assign({}, this.style);
+        this.style = Object.assign({}, style);
+        this.trackChange('style', oldStyle, this.style);
+    }
+    /**
+     * Add CSS class
+     */
+    addClass(className) {
+        if (this.writeBlocked())
+            return;
+        if (!this.classes.has(className)) {
+            const prev = [...this.classes];
+            this.classes.add(className);
+            // THE VALUE, NOT THE DELTA — see setClasses. This reported the class NAME, and a
+            // peer assigned that bare string over its Set: the peer's own next addClass() then
+            // threw "this.classes.has is not a function".
+            this.trackChange('classes', prev, [...this.classes]);
+        }
+    }
+    /**
+     * Remove CSS class
+     */
+    removeClass(className) {
+        if (this.writeBlocked())
+            return;
+        if (this.classes.has(className)) {
+            const prev = [...this.classes];
+            this.classes.delete(className);
+            // The VALUE. This reported `null`, which a peer assigned over its Set.
+            this.trackChange('classes', prev, [...this.classes]);
+        }
+    }
+    /**
+     * REPLACE the whole class collection.
+     *
+     * `classes` is a `Set`, so it needs the same treatment `members` and `ports` needed: a
+     * register whose in-memory form is a collection and whose wire form is an array must be
+     * REBUILT on the receiving side, never assigned. The collab reducer writes it through
+     * here.
+     *
+     * A non-array is REFUSED rather than read as "no classes" — logs persisted before the
+     * funnel fix carry a bare class name (the old addClass) or a bare `null` (the old
+     * removeClass), and assigning either is what corrupted the Set in the first place.
+     */
+    setClasses(classNames) {
+        if (this.writeBlocked())
+            return;
+        if (!Array.isArray(classNames))
+            return;
+        const prev = [...this.classes];
+        const next = classNames.filter((c) => typeof c === 'string');
+        this.classes = new Set(next);
+        this.trackChange('classes', prev, [...this.classes]);
+    }
+    /**
+     * Set data property
+     */
+    setData(key, value) {
+        if (this.writeBlocked())
+            return;
+        const oldValue = this.data[key];
+        this.data[key] = value;
+        this.trackChange(`data.${key}`, oldValue, value);
+    }
+    /**
+     * Get data property
+     */
+    getData(key) {
+        return this.data[key];
+    }
+    /**
+     * Set computed property
+     */
+    setComputed(key, value) {
+        this.computed.set(key, value);
+    }
+    /**
+     * Get computed property
+     */
+    getComputed(key) {
+        return this.computed.get(key);
+    }
+    /**
+     * Get world position (absolute coordinates accounting for parent chain)
+     * For nodes without parents, this is the same as position
+     * For child nodes, this walks up the parent chain and accumulates offsets
+     */
+    getWorldPosition() {
+        let worldX = this.position.x;
+        let worldY = this.position.y;
+        let worldZ = this.position.z || 0;
+        // Walk up the parent chain, honouring positionMode.
+        //
+        // wave13: fold in a parent's position only while the CURRENT node is RELATIVE to it —
+        // an absolute node's stored position IS world coordinates, so it ends the walk. This
+        // used to sum unconditionally, which double-counted an absolute-mode child that carried
+        // a parentId, disagreeing with getGlobalPosition/getGlobalBounds. It is safe now because
+        // setParent() finally declares its semantics (it flips a default-'absolute' child to
+        // 'relative'), and a schema migration re-labels legacy documents the same way — so every
+        // node that RELIED on the summation is 'relative' by the time this runs, and the walk
+        // produces byte-identical results for all of them. Only the genuinely inconsistent case
+        // (explicitly absolute + parentId) changes: it now means what it says.
+        //
+        // wave6/a11y — CYCLE GUARD, preserved. Without it a cyclic `parentId` (a→b→a) spins this
+        // loop forever, and `getBoundingBox()` calls this on every node on every frame — one
+        // corrupt parent link hangs the whole tab with no error. (`SetParentCommand`'s own cycle
+        // check walks this same chain via `getAncestors()`, so it would hang too.)
+        const seen = new Set([this.id]);
+        let current = this;
+        while (current.positionMode !== 'absolute' && current.parentId && this.diagram) {
+            if (seen.has(current.parentId))
+                break; // cycle — stop, do not spin
+            seen.add(current.parentId);
+            const parentNode = this.diagram.getNode(current.parentId);
+            if (!parentNode) {
+                // wave14/model — TOLERANT READER. An unresolvable parent resolves to its
+                // LAST-KNOWN ANCHOR (see DetachedParentAnchor): the anchor IS the missing
+                // parent's accumulated world position at removal time, so it terminates the
+                // walk. Children of a deleted parent FREEZE where they were instead of
+                // jumping to their raw offsets; the ref itself stays dangling so an undo
+                // re-resolves it through the live node again. A parentId the diagram never
+                // held (a document loaded with a dangle) has no anchor and keeps the old
+                // deterministic raw-offset fallback — DiagramValidator owns flagging that.
+                const anchor = this.diagram.getDetachedAnchor(current.parentId);
+                if (anchor) {
+                    worldX += anchor.world.x;
+                    worldY += anchor.world.y;
+                    worldZ += anchor.world.z || 0;
+                }
+                break;
+            }
+            worldX += parentNode.position.x;
+            worldY += parentNode.position.y;
+            worldZ += parentNode.position.z || 0;
+            current = parentNode;
+        }
+        return { x: worldX, y: worldY, z: worldZ };
+    }
+    /**
+     * Get bounding box in world coordinates
+     * For child nodes, this accounts for parent position
+     */
+    getBoundingBox() {
+        const worldPos = this.getWorldPosition();
+        return (0, utils_1.createBoundingBox)(worldPos, this.size);
+    }
+    /**
+     * Get center point in world coordinates
+     */
+    getCenter() {
+        const worldPos = this.getWorldPosition();
+        return {
+            x: worldPos.x + this.size.width / 2,
+            y: worldPos.y + this.size.height / 2,
+            z: worldPos.z,
+        };
+    }
+    /**
+     * Check if point is inside node
+     */
+    containsPoint(point) {
+        const bounds = this.getBoundingBox();
+        return (point.x >= bounds.left &&
+            point.x <= bounds.right &&
+            point.y >= bounds.top &&
+            point.y <= bounds.bottom);
+    }
+    /**
+     * Check if intersects with bounding box
+     */
+    intersectsBounds(bounds) {
+        const myBounds = this.getBoundingBox();
+        return !(myBounds.right < bounds.left ||
+            myBounds.left > bounds.right ||
+            myBounds.bottom < bounds.top ||
+            myBounds.top > bounds.bottom);
+    }
+    /**
+     * Set parent
+     */
+    setParent(parentId) {
+        var _a, _b;
+        if (this.writeBlocked())
+            return;
+        const oldParent = this.parentId;
+        this.parentId = parentId;
+        this.trackChange('parentId', oldParent, parentId);
+        // The hierarchy has TWO writers — `parentId` here, the parent's `children`
+        // Set in addChild/removeChild — and this method maintained only its own,
+        // so getChildren() (Set-based) answered [] for a setParent() child and
+        // transform propagation never saw it: the drag-handle grip stayed painted
+        // at the old spot when its window moved. Keep both sides agreeing on every
+        // path through here.
+        if (this.diagram) {
+            if (oldParent && oldParent !== parentId) {
+                (_a = this.diagram.getNode(oldParent)) === null || _a === void 0 ? void 0 : _a.removeChild(this.id);
+            }
+            if (parentId) {
+                (_b = this.diagram.getNode(parentId)) === null || _b === void 0 ? void 0 : _b.addChild(this.id);
+            }
+        }
+        // wave13: gaining a parent through this API MEANS relative positioning — every consumer
+        // (ERD tables, nested nodes, the world-coordinates contract) treats the child's position
+        // as an offset from the parent, and getWorldPosition sums the chain on that assumption.
+        // The model just never SAID so: positionMode stayed at its 'absolute' default, which made
+        // it disagree with getGlobalPosition/getGlobalBounds (which honour positionMode) — an
+        // absolute-mode child with a parentId double-counted in one method and not the other.
+        // setLocalPosition/setGlobalPosition already set 'relative'; this was the odd one out.
+        // Clearing the parent leaves the mode alone: 'relative' with no parent behaves as
+        // absolute in every consumer, and flipping it back would lie about history.
+        if (parentId && this.positionMode === 'absolute') {
+            const oldMode = this.positionMode;
+            this.positionMode = 'relative';
+            this.trackChange('positionMode', oldMode, 'relative');
+        }
+    }
+    /**
+     * Add child
+     */
+    addChild(childId) {
+        if (this.writeBlocked())
+            return;
+        if (!this.children.has(childId)) {
+            const prev = [...this.children];
+            this.children.add(childId);
+            // THE VALUE, NOT THE DELTA. This reported the child id, and `children` IS
+            // serialized (`Array.from(this.children)`) — so a peer that assigned the bare
+            // string 'beta' over its Set serialized it as ['b','e','t','a']: four child ids
+            // that exist nowhere. The exact `members` defect, on a second register.
+            this.trackChange('children', prev, [...this.children]);
+        }
+    }
+    /**
+     * Remove child
+     */
+    removeChild(childId) {
+        if (this.writeBlocked())
+            return;
+        if (this.children.has(childId)) {
+            const prev = [...this.children];
+            this.children.delete(childId);
+            // The VALUE. This reported `null`, so a peer's `children` became null and
+            // `Array.from(null)` threw inside serialize().
+            this.trackChange('children', prev, [...this.children]);
+        }
+    }
+    /**
+     * REPLACE the whole child collection. The collab reducer's write path.
+     *
+     * Same contract as {@link setClasses}: a Set in memory, an array on the wire, rebuilt
+     * rather than assigned, and a non-array refused so a pre-fix log degrades instead of
+     * destroying the collection.
+     *
+     * This maintains only its own half of the hierarchy, exactly as `addChild`/`removeChild`
+     * do — the child's `parentId` is its own register with its own op.
+     */
+    setChildren(childIds) {
+        if (this.writeBlocked())
+            return;
+        if (!Array.isArray(childIds))
+            return;
+        const prev = [...this.children];
+        const next = childIds.filter((c) => typeof c === 'string');
+        this.children = new Set(next);
+        this.trackChange('children', prev, [...this.children]);
+    }
+    /**
+     * Set transform origin (Phase 1.6a)
+     * @param x Normalized X coordinate (0-1)
+     * @param y Normalized Y coordinate (0-1)
+     */
+    setTransformOrigin(x, y) {
+        const oldOrigin = Object.assign({}, this.transformOrigin);
+        this.transformOrigin = { x, y };
+        this.trackChange('transformOrigin', oldOrigin, this.transformOrigin);
+        // Emit transform propagation event (Phase 1.6a Part 4)
+        this.emitTransformPropagated('transformOrigin', this.transformOrigin);
+    }
+    /**
+     * Get absolute transform origin in pixels (Phase 1.6a)
+     */
+    getAbsoluteTransformOrigin() {
+        return {
+            x: this.transformOrigin.x * this.size.width,
+            y: this.transformOrigin.y * this.size.height,
+            z: this.transformOrigin.z !== undefined && this.size.depth !== undefined
+                ? this.transformOrigin.z * this.size.depth
+                : 0
+        };
+    }
+    /**
+     * Get local position (Phase 1.6a)
+     * Returns the position property as-is
+     */
+    getLocalPosition() {
+        return Object.assign({}, this.position);
+    }
+    /**
+     * Get global position (Phase 1.6a)
+     * In absolute mode: returns position as-is
+     * In relative mode: transforms position by parent's hierarchy transform
+     */
+    getGlobalPosition() {
+        var _a;
+        if (this.positionMode === 'absolute' || !this.parentId) {
+            return Object.assign({}, this.position);
+        }
+        // In relative mode with parent: apply parent's hierarchy transform
+        const parent = this.getParentNode();
+        if (!parent) {
+            // wave14/model — TOLERANT READER (see getWorldPosition): a removed parent's
+            // frozen frame keeps the transform-aware reading in agreement with the walk.
+            const anchor = (_a = this.diagram) === null || _a === void 0 ? void 0 : _a.getDetachedAnchor(this.parentId);
+            if (anchor) {
+                return this.composeGlobalFromParentFrame(anchor.global, anchor.rotation, anchor.scale);
+            }
+            return Object.assign({}, this.position);
+        }
+        return this.composeGlobalFromParentFrame(parent.getGlobalPosition(), parent.rotation, parent.scale);
+    }
+    /**
+     * Compose this node's global position from a parent FRAME (global position +
+     * local rotation/scale). For hierarchical positioning, apply:
+     * scale -> rotate -> translate (without transform origin offsets, which are
+     * for visual transforms). Shared by the live-parent path and the
+     * detached-anchor path of getGlobalPosition so the two can never disagree.
+     */
+    composeGlobalFromParentFrame(parentGlobalPos, rotation, scale) {
+        var _a, _b;
+        // Scale child position by parent's scale
+        let x = this.position.x * scale.x;
+        let y = this.position.y * scale.y;
+        // Rotate scaled position by parent's rotation
+        if (rotation !== 0) {
+            const cos = Math.cos(rotation);
+            const sin = Math.sin(rotation);
+            const rotatedX = x * cos - y * sin;
+            const rotatedY = x * sin + y * cos;
+            x = rotatedX;
+            y = rotatedY;
+        }
+        // Add parent's global position
+        return {
+            x: parentGlobalPos.x + x,
+            y: parentGlobalPos.y + y,
+            z: ((_a = this.position.z) !== null && _a !== void 0 ? _a : 0) + ((_b = parentGlobalPos.z) !== null && _b !== void 0 ? _b : 0)
+        };
+    }
+    /**
+     * Set local position (Phase 1.6a)
+     * Sets position directly and switches to relative mode
+     */
+    setLocalPosition(x, y, z) {
+        this.positionMode = 'relative';
+        this.setPosition(x, y, z);
+    }
+    /**
+     * Set global position (Phase 1.6a)
+     * Converts global coordinates to local if parent exists
+     */
+    setGlobalPosition(x, y, z) {
+        var _a;
+        if (!this.parentId) {
+            this.setPosition(x, y, z);
+            return;
+        }
+        const parent = this.getParentNode();
+        if (!parent) {
+            // wave14/model — the WRITER must share the readers' frame, or dragging an
+            // orphaned child teleports it: convert through the removed parent's frozen
+            // frame when one exists (see DetachedParentAnchor).
+            const anchor = (_a = this.diagram) === null || _a === void 0 ? void 0 : _a.getDetachedAnchor(this.parentId);
+            if (anchor) {
+                this.positionMode = 'relative';
+                this.setPositionFromGlobalInParentFrame(anchor.global, anchor.rotation, anchor.scale, x, y, z);
+                return;
+            }
+            this.setPosition(x, y, z);
+            return;
+        }
+        // Convert global to local by inverting parent's hierarchy transform
+        this.positionMode = 'relative';
+        this.setPositionFromGlobalInParentFrame(parent.getGlobalPosition(), parent.rotation, parent.scale, x, y, z);
+    }
+    /**
+     * Inverse of {@link composeGlobalFromParentFrame}: write a GLOBAL point as a
+     * local offset against a parent frame. Shared by the live-parent path and the
+     * detached-anchor path of setGlobalPosition.
+     */
+    setPositionFromGlobalInParentFrame(parentGlobalPos, rotation, scale, x, y, z) {
+        var _a;
+        // Subtract parent's global position
+        let localX = x - parentGlobalPos.x;
+        let localY = y - parentGlobalPos.y;
+        // Rotate by -parent.rotation
+        if (rotation !== 0) {
+            const cos = Math.cos(-rotation);
+            const sin = Math.sin(-rotation);
+            const rotatedX = localX * cos - localY * sin;
+            const rotatedY = localX * sin + localY * cos;
+            localX = rotatedX;
+            localY = rotatedY;
+        }
+        // Divide by parent's scale
+        localX /= scale.x;
+        localY /= scale.y;
+        this.setPosition(localX, localY, z !== undefined ? z - ((_a = parentGlobalPos.z) !== null && _a !== void 0 ? _a : 0) : undefined);
+    }
+    /**
+     * Get local transform matrix (Phase 1.6a)
+     * Composes translation, rotation, and scale relative to transform origin
+     */
+    getLocalTransformMatrix() {
+        const origin = this.getAbsoluteTransformOrigin();
+        // Compose: translate to position, rotate around origin, scale around origin
+        // Order: translate-to-origin, scale, rotate, translate-back, translate-to-position
+        return (0, transform_1.composeMatrices)((0, transform_1.createTranslateMatrix)(this.position.x, this.position.y), (0, transform_1.createTranslateMatrix)(origin.x, origin.y), (0, transform_1.createRotateMatrix)(this.rotation), (0, transform_1.createScaleMatrix)(this.scale.x, this.scale.y), (0, transform_1.createTranslateMatrix)(-origin.x, -origin.y));
+    }
+    /**
+     * Get global transform matrix (Phase 1.6a)
+     * In absolute mode: returns local matrix
+     * In relative mode: composes parent's global matrix with local matrix
+     */
+    getGlobalTransformMatrix() {
+        var _a;
+        const localMatrix = this.getLocalTransformMatrix();
+        if (this.positionMode === 'absolute' || !this.parentId) {
+            return localMatrix;
+        }
+        const parent = this.getParentNode();
+        if (!parent) {
+            // wave14/model — TOLERANT READER (see getWorldPosition): compose against the
+            // removed parent's frozen global matrix so getGlobalBounds does not jump.
+            const anchor = (_a = this.diagram) === null || _a === void 0 ? void 0 : _a.getDetachedAnchor(this.parentId);
+            if (anchor) {
+                return (0, transform_1.composeMatrices)(anchor.matrix, localMatrix);
+            }
+            return localMatrix;
+        }
+        const parentMatrix = parent.getGlobalTransformMatrix();
+        return (0, transform_1.composeMatrices)(parentMatrix, localMatrix);
+    }
+    /**
+     * Get global bounding box (Phase 1.6a)
+     * Calculates bounds by transforming all 4 corners through global matrix
+     */
+    getGlobalBounds() {
+        const matrix = this.getGlobalTransformMatrix();
+        // Get 4 corners in local space
+        const corners = [
+            { x: 0, y: 0 },
+            { x: this.size.width, y: 0 },
+            { x: this.size.width, y: this.size.height },
+            { x: 0, y: this.size.height }
+        ];
+        // Transform all corners
+        const transformedCorners = corners.map(corner => (0, transform_1.transformPoint)(corner, matrix));
+        // Find min/max to create axis-aligned bounding box
+        const xs = transformedCorners.map(p => p.x);
+        const ys = transformedCorners.map(p => p.y);
+        const left = Math.min(...xs);
+        const right = Math.max(...xs);
+        const top = Math.min(...ys);
+        const bottom = Math.max(...ys);
+        return {
+            left,
+            top,
+            right,
+            bottom,
+            width: right - left,
+            height: bottom - top
+        };
+    }
+    /**
+     * Helper to get parent node (Phase 1.6a)
+     * Uses diagram reference to look up parent by ID
+     */
+    getParentNode() {
+        if (!this.parentId || !this.diagram) {
+            return undefined;
+        }
+        return this.diagram.getNode(this.parentId);
+    }
+    /**
+     * Get direct children nodes (Phase 1.6a Part 3)
+     */
+    getChildren() {
+        if (!this.diagram) {
+            return [];
+        }
+        const children = [];
+        for (const childId of this.children) {
+            const child = this.diagram.getNode(childId);
+            if (child) {
+                children.push(child);
+            }
+        }
+        return children;
+    }
+    /**
+     * Get parent node (Phase 1.6a Part 3)
+     * Public version of getParentNode
+     */
+    getParent() {
+        return this.getParentNode();
+    }
+    /**
+     * Get all ancestor nodes up to root (Phase 1.6a Part 3)
+     * Returns array with direct parent first, then grandparent, etc.
+     */
+    getAncestors() {
+        const ancestors = [];
+        let current = this.getParent();
+        // wave6/a11y — CYCLE GUARD, same bug as `getWorldPosition()`. This is the
+        // walk `SetParentCommand` uses to REJECT a cycle, so leaving it unguarded
+        // meant the cycle check hung the moment a cycle actually existed.
+        const seen = new Set([this.id]);
+        while (current && !seen.has(current.id)) {
+            seen.add(current.id);
+            ancestors.push(current);
+            current = current.getParent();
+        }
+        return ancestors;
+    }
+    /**
+     * Get all descendant nodes recursively (Phase 1.6a Part 3)
+     */
+    getDescendants() {
+        const descendants = [];
+        const children = this.getChildren();
+        for (const child of children) {
+            descendants.push(child);
+            descendants.push(...child.getDescendants());
+        }
+        return descendants;
+    }
+    /**
+     * Get root node of hierarchy (Phase 1.6a Part 3)
+     * Returns self if this is the root
+     */
+    getRoot() {
+        let current = this;
+        let parent = current.getParent();
+        while (parent) {
+            current = parent;
+            parent = current.getParent();
+        }
+        return current;
+    }
+    /**
+     * Get sibling nodes (same parent, excluding self) (Phase 1.6a Part 3)
+     */
+    getSiblings() {
+        const parent = this.getParent();
+        if (!parent) {
+            return [];
+        }
+        return parent.getChildren().filter(child => child.id !== this.id);
+    }
+    /**
+     * Check if this node is an ancestor of another node (Phase 1.6a Part 3)
+     * @param nodeId ID of node to check
+     * @returns true if this node is an ancestor of the given node
+     */
+    isAncestorOf(nodeId) {
+        if (nodeId === this.id) {
+            return false; // Node is not ancestor of itself
+        }
+        if (!this.diagram) {
+            return false;
+        }
+        const targetNode = this.diagram.getNode(nodeId);
+        if (!targetNode) {
+            return false;
+        }
+        const ancestors = targetNode.getAncestors();
+        return ancestors.some(ancestor => ancestor.id === this.id);
+    }
+    /**
+     * Get depth in hierarchy (Phase 1.6a Part 3)
+     * Root nodes have depth 0, their children have depth 1, etc.
+     * @returns depth level (0 = root)
+     */
+    getDepth() {
+        let depth = 0;
+        let current = this.getParent();
+        // wave6/a11y — CYCLE GUARD (the third unguarded parent walk in this class;
+        // `validateHierarchy()` below has always had one, which is the irony: the
+        // cycle DETECTOR was safe while every hot path that walks the same chain
+        // was not).
+        const seen = new Set([this.id]);
+        while (current && !seen.has(current.id)) {
+            seen.add(current.id);
+            depth++;
+            current = current.getParent();
+        }
+        return depth;
+    }
+    /**
+     * Validate hierarchy for circular references (Phase 1.6a Part 3)
+     * @returns true if hierarchy is valid (no cycles)
+     */
+    validateHierarchy() {
+        const visited = new Set();
+        let current = this;
+        while (current) {
+            if (visited.has(current.id)) {
+                // Found circular reference
+                return false;
+            }
+            visited.add(current.id);
+            current = current.getParent();
+        }
+        return true;
+    }
+    /**
+     * Update depth for this node and all descendants (Phase 1.6a Part 3)
+     * Recalculates depth values based on current hierarchy
+     */
+    updateHierarchyDepth() {
+        // Update own depth
+        this.depth = this.getDepth();
+        // Recursively update children
+        const children = this.getChildren();
+        for (const child of children) {
+            child.updateHierarchyDepth();
+        }
+    }
+    /**
+     * Get all nodes affected by transform changes (Phase 1.6a Part 4)
+     * Returns this node plus all descendants in relative positioning mode
+     * @returns Array of nodes that would be affected by this node's transform
+     */
+    getAffectedByTransform() {
+        const affected = [this];
+        const children = this.getChildren();
+        for (const child of children) {
+            // Only include children in relative mode (they inherit parent's transform)
+            if (child.positionMode === 'relative') {
+                affected.push(...child.getAffectedByTransform());
+            }
+        }
+        return affected;
+    }
+    /**
+     * Emit transform propagation event (Phase 1.6a Part 4)
+     * Called after transform changes to notify renderers
+     */
+    emitTransformPropagated(type, value) {
+        const affectedNodes = this.getAffectedByTransform();
+        // Only emit if there are affected children (besides self)
+        if (affectedNodes.length > 1) {
+            this.emitter.emit('transform-propagated', {
+                type,
+                value,
+                affectedNodes
+            });
+        }
+    }
+    // ========================================
+    // C — Z-order (mirrors GroupModel's Wave-5 API)
+    // ========================================
+    /**
+     * The stacking index a renderer should paint by.
+     *
+     * Precedence is explicit-model-field → legacy `style.zIndex` → 0. That ordering
+     * is the whole compatibility story: diagrams that restacked via style keep
+     * working untouched, and the moment a node states a model z-index it wins — so
+     * `setZIndex(1)` on a node styled `zIndex: 4` does what it says instead of
+     * silently losing to a stylesheet.
+     */
+    getEffectiveZIndex() {
+        var _a, _b, _c;
+        return (_c = (_a = this.zIndex) !== null && _a !== void 0 ? _a : (_b = this.style) === null || _b === void 0 ? void 0 : _b.zIndex) !== null && _c !== void 0 ? _c : 0;
+    }
+    /** Set the stacking index (lower renders further back). Tracked for undo/diff. */
+    setZIndex(z) {
+        if (this.writeBlocked())
+            return;
+        if (this.zIndex === z)
+            return;
+        const old = this.zIndex;
+        this.zIndex = z;
+        this.trackChange('zIndex', old, z);
+        this.emitter.emit('zindex:changed', z);
+    }
+    /**
+     * Bring this node in front of every other node in the diagram.
+     * Falls back to a relative bump when the node is detached, exactly as
+     * `GroupModel.bringToFront` does.
+     */
+    bringToFront(diagram) {
+        const dm = diagram !== null && diagram !== void 0 ? diagram : this.diagram;
+        if (!dm) {
+            this.setZIndex(this.getEffectiveZIndex() + 1);
+            return;
+        }
+        const max = Math.max(0, ...dm.getNodes().map((n) => n.getEffectiveZIndex()));
+        this.setZIndex(max + 1);
+    }
+    /** Send this node behind every other node in the diagram. */
+    sendToBack(diagram) {
+        const dm = diagram !== null && diagram !== void 0 ? diagram : this.diagram;
+        if (!dm) {
+            this.setZIndex(this.getEffectiveZIndex() - 1);
+            return;
+        }
+        const min = Math.min(0, ...dm.getNodes().map((n) => n.getEffectiveZIndex()));
+        this.setZIndex(min - 1);
+    }
+    /**
+     * Set flexbox item configuration (Phase 1.7)
+     */
+    setFlexItem(config) {
+        const oldConfig = this.flexConfig;
+        this.flexConfig = config;
+        this.trackChange('flexConfig', oldConfig, config);
+        this.emitter.emit('flex-item:changed', config);
+    }
+    /**
+     * Clear flexbox item configuration (Phase 1.7)
+     */
+    clearFlexItem() {
+        const oldConfig = this.flexConfig;
+        this.flexConfig = undefined;
+        this.trackChange('flexConfig', oldConfig, undefined);
+        this.emitter.emit('flex-item:cleared');
+    }
+    /**
+     * Get flexbox item configuration (Phase 1.7)
+     */
+    getFlexItem() {
+        return this.flexConfig;
+    }
+    /**
+     * Check if node has flex item configuration (Phase 1.7)
+     */
+    hasFlexItem() {
+        return this.flexConfig !== undefined;
+    }
+    /**
+     * Set grid item configuration (Phase 1.7)
+     */
+    setGridItem(config) {
+        const oldConfig = this.gridConfig;
+        this.gridConfig = config;
+        this.trackChange('gridConfig', oldConfig, config);
+        this.emitter.emit('grid-item:changed', config);
+    }
+    /**
+     * Clear grid item configuration (Phase 1.7)
+     */
+    clearGridItem() {
+        const oldConfig = this.gridConfig;
+        this.gridConfig = undefined;
+        this.trackChange('gridConfig', oldConfig, undefined);
+        this.emitter.emit('grid-item:cleared');
+    }
+    /**
+     * Get grid item configuration (Phase 1.7)
+     */
+    getGridItem() {
+        return this.gridConfig;
+    }
+    /**
+     * Check if node has grid item configuration (Phase 1.7)
+     */
+    hasGridItem() {
+        return this.gridConfig !== undefined;
+    }
+    // ========================================
+    // Template Support Methods (Phase 2)
+    // ========================================
+    /**
+     * Set port rendering configuration (Phase 2)
+     */
+    setPortRenderingConfig(config) {
+        const oldConfig = this.portRenderingConfig;
+        this.portRenderingConfig = config;
+        this.trackChange('portRenderingConfig', oldConfig, config);
+        this.emitter.emit('port-rendering:changed', config);
+    }
+    /**
+     * Get port rendering configuration (Phase 2)
+     */
+    getPortRenderingConfig() {
+        return this.portRenderingConfig;
+    }
+    /**
+     * Get port rendering mode (Phase 2)
+     * Auto-detects based on configuration and metadata
+     */
+    getPortRenderingMode() {
+        var _a;
+        // Priority 1: Explicit metadata override
+        const metadataMode = this.getMetadata('portRenderingMode');
+        if (metadataMode) {
+            return metadataMode;
+        }
+        // Priority 2: Port rendering config
+        if ((_a = this.portRenderingConfig) === null || _a === void 0 ? void 0 : _a.mode) {
+            return this.portRenderingConfig.mode;
+        }
+        // Priority 3: Auto-detect from HTML layer flag
+        const useHTMLLayer = this.getMetadata('useHTMLLayer');
+        if (useHTMLLayer === true) {
+            return 'html';
+        }
+        // Default: SVG mode
+        return 'svg';
+    }
+    /**
+     * Set drag handler configuration (Phase 2)
+     */
+    setDragHandlerConfig(config) {
+        const oldConfig = this.dragHandlerConfig;
+        this.dragHandlerConfig = config;
+        this.trackChange('dragHandlerConfig', oldConfig, config);
+        this.emitter.emit('drag-handler:changed', config);
+    }
+    /**
+     * Get drag handler configuration (Phase 2)
+     */
+    getDragHandlerConfig() {
+        return this.dragHandlerConfig;
+    }
+    /**
+     * Check if this node is a drag handler (Phase 2)
+     */
+    isDragHandler() {
+        var _a;
+        return ((_a = this.dragHandlerConfig) === null || _a === void 0 ? void 0 : _a.isDragHandler) === true;
+    }
+    /**
+     * Set connection group (Phase 2)
+     */
+    setConnectionGroup(group) {
+        const oldGroup = this.connectionGroup;
+        this.connectionGroup = group;
+        this.trackChange('connectionGroup', oldGroup, group);
+        this.emitter.emit('connection-group:changed', { group });
+    }
+    /**
+     * Get connection group (Phase 2)
+     */
+    getConnectionGroup() {
+        return this.connectionGroup;
+    }
+    /**
+     * Serialize to JSON
+     */
+    serialize() {
+        const serialized = {
+            id: this.id,
+            uuid: this.uuid,
+            type: this.type,
+            version: this.version,
+            metadata: Object.fromEntries(this.metadata),
+            position: Object.assign({}, this.position),
+            size: Object.assign({}, this.size),
+            rotation: this.rotation,
+            scale: Object.assign({}, this.scale),
+            systemType: this.systemType,
+            definitionId: this.definitionId,
+            parentId: this.parentId,
+            children: Array.from(this.children),
+            ports: Array.from(this.ports.values()).map((p) => p.serialize()),
+            state: Object.assign({}, this.state),
+            behavior: Object.assign({}, this.behavior),
+            style: Object.assign({}, this.style),
+            data: Object.assign({}, this.data),
+            positionMode: this.positionMode, // Phase 1.6a
+            transformOrigin: Object.assign({}, this.transformOrigin), // Phase 1.6a
+        };
+        // C: only present when the node actually stated a z-index — see the field
+        // comment. `0` is a real, serialized value; `undefined` writes no key at all.
+        if (this.zIndex !== undefined) {
+            serialized.zIndex = this.zIndex;
+        }
+        // Phase 1.7: Include layout configs if they exist
+        if (this.flexConfig) {
+            serialized.flexConfig = Object.assign({}, this.flexConfig);
+        }
+        if (this.gridConfig) {
+            serialized.gridConfig = Object.assign({}, this.gridConfig);
+        }
+        // Phase 2: Include template properties if they exist
+        if (this.portRenderingConfig) {
+            serialized.portRenderingConfig = Object.assign({}, this.portRenderingConfig);
+        }
+        if (this.dragHandlerConfig) {
+            serialized.dragHandlerConfig = Object.assign({}, this.dragHandlerConfig);
+        }
+        if (this.connectionGroup) {
+            serialized.connectionGroup = this.connectionGroup;
+        }
+        return serialized;
+    }
+    /**
+     * Deserialize from JSON
+     */
+    static fromJSON(data) {
+        const node = new NodeModel({
+            id: data.id,
+            type: data.type,
+            position: data.position,
+            size: data.size,
+            systemType: data.systemType,
+            definitionId: data.definitionId,
+        });
+        node.rotation = data.rotation;
+        node.scale = data.scale;
+        node.parentId = data.parentId;
+        node.children = new Set(data.children);
+        node.state = data.state;
+        node.behavior = data.behavior;
+        node.style = data.style;
+        node.data = data.data;
+        // Restore Phase 1.6a properties (with defaults for backward compatibility)
+        node.positionMode = data.positionMode || 'absolute';
+        node.transformOrigin = data.transformOrigin || { x: 0.5, y: 0.5 };
+        // C: an absent key stays UNSET (not 0) so a legacy document keeps deferring to
+        // whatever `style.zIndex` it was painted with.
+        if (typeof data.zIndex === 'number') {
+            node.zIndex = data.zIndex;
+        }
+        // Restore metadata
+        for (const [key, value] of Object.entries(data.metadata)) {
+            node.metadata.set(key, value);
+        }
+        // Restore ports. The SAVED port set is authoritative: the constructor
+        // auto-creates default ports (Phase 0.5.1), and appending the serialized
+        // ports on top of them made every save/load cycle GROW the set (4 defaults
+        // + 4 restored = 8, then 12, …). Clear the auto-created defaults first so
+        // a restored node has exactly the ports it was saved with — including
+        // zero, if they were all removed. Legacy payloads with no `ports` field
+        // keep the constructor defaults.
+        if (Array.isArray(data.ports)) {
+            node.ports.clear();
+            for (const portData of data.ports) {
+                const port = PortModel_1.PortModel.fromJSON(portData);
+                node.ports.set(port.id, port);
+            }
+        }
+        // (wave14/model — a legacy `behaviorOverrides` key, if present, is deliberately
+        // IGNORED here: unknown-key tolerance. See the note on SerializedNode.)
+        // Restore Phase 1.7 layout configs
+        if (data.flexConfig) {
+            node.flexConfig = data.flexConfig;
+        }
+        if (data.gridConfig) {
+            node.gridConfig = data.gridConfig;
+        }
+        // Restore Phase 2 template properties (backward compatible)
+        if (data.portRenderingConfig) {
+            node.portRenderingConfig = data.portRenderingConfig;
+        }
+        if (data.dragHandlerConfig) {
+            node.dragHandlerConfig = data.dragHandlerConfig;
+        }
+        if (data.connectionGroup) {
+            node.connectionGroup = data.connectionGroup;
+        }
+        // Last: restore persisted identity (uuid) and mutation counter (version)
+        // so a loaded node is indistinguishable from the one that was saved.
+        node.restoreIdentity(data);
+        return node;
+    }
+}
+exports.NodeModel = NodeModel;
+//# sourceMappingURL=NodeModel.js.map