@grafloria/element 0.3.18 → 0.3.20

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

@@ -0,0 +1,1373 @@
+"use strict";
+// GroupModel - Entity for organizing nodes into groups (Phase 1.6c)
+// Layout configuration storage added in Phase 1.7
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GroupModel = exports.DEFAULT_GROUP_HEADER_HEIGHT = exports.DEFAULT_GROUP_PADDING = void 0;
+const DiagramEntity_1 = require("./DiagramEntity");
+/**
+ * Defaults for groups AUTHORED in code (constructor path). A fitted frame needs
+ * breathing room and a title band or its label lands under the first member.
+ * Loaded documents are exempt: restore assigns the stored values (padding
+ * verbatim — possibly undefined, which getPadding() resolves to 0 — and
+ * headerHeight number-or-0), so legacy geometry is byte-stable.
+ */
+exports.DEFAULT_GROUP_PADDING = 16;
+exports.DEFAULT_GROUP_HEADER_HEIGHT = 24;
+class GroupModel extends DiagramEntity_1.DiagramEntity {
+    constructor(config) {
+        super(config.id);
+        this.members = new Set();
+        this.isCollapsed = false;
+        // Phase 1.7: Layout configuration storage
+        this.layoutType = 'none';
+        // Position and size for layout calculations
+        this.position = { x: 0, y: 0 };
+        // Wave-2: transient drag-hover highlight state (not serialized).
+        this.isHovered = false;
+        this.headerHeight = exports.DEFAULT_GROUP_HEADER_HEIGHT;
+        this.zIndex = 0;
+        this.fitMode = 'exact';
+        this.constrainChildren = false;
+        // ---------------------------------------------------------------------------
+        // A — PUSH-DRIVEN LAYOUT
+        //
+        // `applyLayout` has always been a real layout engine. It was just never CALLED:
+        // it was pulled by hand, plus a one-shot on `addMember` behind an opt-IN metadata
+        // flag. Resize a container, delete a widget, or grow a child, and nothing
+        // reflowed. Everything below turns those three events into pushes, following the
+        // precedent already set by `NodeModel.setPosition` (which propagates) and
+        // `SwimlaneService.reflow` (the one place that already did this correctly).
+        // ---------------------------------------------------------------------------
+        /**
+         * Re-entrancy guard. The cycle this closes is real and one hop long: layout
+         * writes a child's size → the child notifies its containers → the container lays
+         * out again → it writes the child's size… Held for the duration of one pass;
+         * every push that arrives DURING a pass is dropped, because that pass is already
+         * producing the answer the push would ask for.
+         */
+        this.layoutInFlight = false;
+        this.name = config.name;
+    }
+    /**
+     * Resolve the owning diagram, preferring an explicit argument and falling
+     * back to the reference stashed in metadata by DiagramModel.addGroup.
+     */
+    resolveDiagram(diagram) {
+        return diagram !== null && diagram !== void 0 ? diagram : this.metadata.get('diagram');
+    }
+    /**
+     * Whether `candidateId` may legally join this group (Wave-2).
+     * Rejects self-membership, ancestor cycles (adding an ancestor group as a
+     * member would create a containment loop), and candidates failing the
+     * per-group `memberValidation` predicate. Node candidates only run the
+     * predicate check (nodes can't form group cycles).
+     */
+    canAddMember(candidateId, diagram) {
+        if (candidateId === this.id) {
+            return false;
+        }
+        const dm = this.resolveDiagram(diagram);
+        const candidateGroup = dm === null || dm === void 0 ? void 0 : dm.getGroup(candidateId);
+        // Cycle prevention: reject if the candidate is an ancestor of this group.
+        if (candidateGroup && dm) {
+            const ancestors = dm.getAncestors(this.id);
+            if (ancestors.some((g) => g.id === candidateId)) {
+                return false;
+            }
+        }
+        // Wave-5 Card 7: capacity / WIP limit — reject an add that would push the
+        // group past its limit. Already-present candidates never count (re-adds are
+        // no-ops), so this only gates genuinely new members (incl. drops, which flow
+        // through GroupMembershipService → canAddMember).
+        if (this.capacity !== undefined &&
+            !this.members.has(candidateId) &&
+            this.members.size >= this.capacity) {
+            return false;
+        }
+        // Per-group membership predicate.
+        if (this.memberValidation && !this.memberValidation(candidateId, this)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Wave-5 Card 7: WIP state for the capacity limit. 'under' = room to spare,
+     * 'full' = exactly at the limit (the visual warning threshold), 'over' = past
+     * it (only reachable by lowering capacity below the current count). Returns
+     * 'unlimited' when no capacity is set.
+     */
+    getWipState() {
+        const count = this.members.size;
+        if (this.capacity === undefined) {
+            return { count, state: 'unlimited' };
+        }
+        const state = count > this.capacity ? 'over' : count >= this.capacity ? 'full' : 'under';
+        return { count, capacity: this.capacity, state };
+    }
+    /** Wave-5 Card 7: true when at or beyond the capacity limit (warning state). */
+    isOverCapacity() {
+        const s = this.getWipState().state;
+        return s === 'full' || s === 'over';
+    }
+    /** Set (or clear) the capacity / WIP limit, tracked for undo/diff. */
+    setCapacity(capacity) {
+        if (this.capacity === capacity) {
+            return;
+        }
+        const old = this.capacity;
+        this.capacity = capacity;
+        this.trackChange('capacity', old, capacity);
+        this.emitter.emit('capacity:changed', this.getWipState());
+    }
+    /**
+     * Add member to group.
+     *
+     * When the member is itself a group, this establishes containment by setting
+     * the child's `parentGroupId` (detaching it from any previous parent), which
+     * keeps the nesting tree consistent for getAncestors/getDescendants. Members
+     * that would create a cycle or fail `memberValidation` are rejected (no-op).
+     */
+    addMember(entityId, diagram) {
+        if (this.members.has(entityId)) {
+            return;
+        }
+        const dm = this.resolveDiagram(diagram);
+        // Guard cycles + validation (no-op on rejection to preserve void contract).
+        if (!this.canAddMember(entityId, dm)) {
+            return;
+        }
+        this.members.add(entityId);
+        // Group member => maintain the containment back-pointer.
+        const childGroup = dm === null || dm === void 0 ? void 0 : dm.getGroup(entityId);
+        if (childGroup) {
+            this.linkChildGroup(childGroup, dm);
+        }
+        this.trackChange('members', null, entityId);
+        this.emitter.emit('member:added', entityId);
+        // PUSH (A): a container that declares a layout reflows when its membership
+        // changes. This used to require an explicit `autoLayout` metadata flag, which
+        // meant the default behaviour of a layout container was "do nothing".
+        this.requestLayout(dm);
+    }
+    /**
+     * Remove member from group. When the member is a group whose parent is this
+     * group, its `parentGroupId` back-pointer is cleared so the nesting tree
+     * stays consistent.
+     */
+    removeMember(entityId, diagram) {
+        if (this.members.has(entityId)) {
+            this.members.delete(entityId);
+            const dm = this.resolveDiagram(diagram);
+            const childGroup = dm === null || dm === void 0 ? void 0 : dm.getGroup(entityId);
+            if (childGroup && childGroup.parentGroupId === this.id) {
+                childGroup.clearParentGroupId();
+            }
+            this.trackChange('members', entityId, null);
+            this.emitter.emit('member:removed', entityId);
+            // PUSH (A): the survivors close the gap. Deleting a dashboard widget and
+            // leaving a hole is the single most obvious symptom of a pull-only layout.
+            this.requestLayout(dm);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Make `child` a nested group of this group: detach from previous parent's
+     * members and point `parentGroupId` here. Uses protected access allowed
+     * between GroupModel instances.
+     */
+    linkChildGroup(child, diagram) {
+        if (child.parentGroupId === this.id) {
+            return;
+        }
+        // Detach from a previous parent so its members set stays consistent.
+        //
+        // THROUGH THE FUNNEL. `trackChange` is the single channel every mutation in this
+        // engine is observed on — dirty tracking, versioning, and (wave 9) the collab capture
+        // layer that turns edits into ops. This detach mutates a THIRD group's Set and used
+        // to do it SILENTLY, so re-parenting a nested group never reached any peer: the old
+        // parent kept the child in `members` forever on every machine but the author's, and
+        // the two documents disagreed with nothing anywhere reporting a problem. Mirrors
+        // removeMember's own three lines exactly — a half-mirror is the next bug.
+        if (child.parentGroupId) {
+            const oldParent = diagram.getGroup(child.parentGroupId);
+            if (oldParent === null || oldParent === void 0 ? void 0 : oldParent.members.delete(child.id)) {
+                oldParent.trackChange('members', child.id, null);
+                oldParent.emitter.emit('member:removed', child.id);
+                oldParent.requestLayout(diagram);
+            }
+        }
+        const old = child.parentGroupId;
+        child.parentGroupId = this.id;
+        child.trackChange('parentGroupId', old, this.id);
+        child.emitter.emit('parent:changed', { oldParentId: old, newParentId: this.id });
+    }
+    /**
+     * Clear this group's parent back-pointer (used when detached from a parent).
+     */
+    clearParentGroupId() {
+        if (this.parentGroupId === undefined) {
+            return;
+        }
+        const old = this.parentGroupId;
+        this.parentGroupId = undefined;
+        this.trackChange('parentGroupId', old, undefined);
+        this.emitter.emit('parent:changed', { oldParentId: old, newParentId: undefined });
+    }
+    /**
+     * Reparent this group under `newParentId` (or detach when undefined),
+     * keeping both the `parentGroupId` pointer and the parents' `members` sets
+     * consistent. Rejects cycles (a group cannot be nested under one of its own
+     * descendants) and returns false without mutating anything.
+     */
+    setParent(newParentId, diagram) {
+        const dm = this.resolveDiagram(diagram);
+        if (newParentId !== undefined) {
+            if (newParentId === this.id) {
+                return false;
+            }
+            // Cycle prevention: the new parent must not live inside this subtree.
+            if (dm && dm.getDescendants(this.id).some((g) => g.id === newParentId)) {
+                return false;
+            }
+            // Honour the target group's own membership predicate.
+            const newParent = dm === null || dm === void 0 ? void 0 : dm.getGroup(newParentId);
+            if (newParent && !newParent.canAddMember(this.id, dm)) {
+                return false;
+            }
+        }
+        const oldParentId = this.parentGroupId;
+        if (oldParentId === newParentId) {
+            return true;
+        }
+        // Detach from old parent's members — THROUGH THE FUNNEL, see linkChildGroup. These
+        // two writes touch a group that is neither `this` nor the caller, and mutating a
+        // model this engine is watching without telling it is how an edit becomes invisible
+        // to undo, to dirty tracking and to every peer in the session at once.
+        if (dm && oldParentId) {
+            const oldParent = dm.getGroup(oldParentId);
+            if (oldParent === null || oldParent === void 0 ? void 0 : oldParent.members.delete(this.id)) {
+                oldParent.trackChange('members', this.id, null);
+                oldParent.emitter.emit('member:removed', this.id);
+                oldParent.requestLayout(dm);
+            }
+        }
+        this.parentGroupId = newParentId;
+        this.trackChange('parentGroupId', oldParentId, newParentId);
+        this.emitter.emit('parent:changed', { oldParentId, newParentId });
+        // Attach to new parent's members (kept in sync with parentGroupId).
+        if (dm && newParentId) {
+            const newParent = dm.getGroup(newParentId);
+            if (newParent && !newParent.members.has(this.id)) {
+                newParent.members.add(this.id);
+                newParent.trackChange('members', null, this.id);
+                newParent.emitter.emit('member:added', this.id);
+                newParent.requestLayout(dm);
+            }
+        }
+        return true;
+    }
+    /**
+     * Set transient drag-hover highlight state and notify listeners (Wave-2).
+     * Renderers/canvas can subscribe to 'hover:changed' to outline a drop target.
+     */
+    setHovered(hovered) {
+        if (this.isHovered !== hovered) {
+            this.isHovered = hovered;
+            this.emitter.emit('hover:changed', hovered);
+        }
+    }
+    /**
+     * Expand the group
+     */
+    expand() {
+        if (this.isCollapsed) {
+            this.isCollapsed = false;
+            this.trackChange('isCollapsed', true, false);
+            this.emitter.emit('expanded');
+        }
+    }
+    /**
+     * Collapse the group
+     */
+    collapse() {
+        if (!this.isCollapsed) {
+            this.isCollapsed = true;
+            this.trackChange('isCollapsed', false, true);
+            this.emitter.emit('collapsed');
+        }
+    }
+    /**
+     * Wave-5 Card 4: set (or clear) the reversible collapse snapshot. Tracked as a
+     * change so the incremental diff-capture serializes it and undo/redo see it.
+     */
+    setCollapsedState(state) {
+        const old = this.collapsedState;
+        this.collapsedState = state;
+        this.trackChange('collapsedState', old, state);
+    }
+    setLayout(type, config) {
+        const oldType = this.layoutType;
+        const oldConfig = this.layoutConfig;
+        this.layoutType = type;
+        this.layoutConfig = config;
+        this.version++;
+        this.trackChange('layoutType', oldType, type);
+        this.trackChange('layoutConfig', oldConfig, config);
+        this.emitter.emit('layout:changed', { type, config });
+    }
+    /**
+     * Clear layout configuration (Phase 1.7)
+     */
+    clearLayout() {
+        const oldType = this.layoutType;
+        const oldConfig = this.layoutConfig;
+        this.layoutType = 'none';
+        this.layoutConfig = undefined;
+        this.version++;
+        this.trackChange('layoutType', oldType, 'none');
+        this.trackChange('layoutConfig', oldConfig, undefined);
+        this.emitter.emit('layout:cleared');
+    }
+    /**
+     * Get layout configuration (Phase 1.7)
+     */
+    getLayout() {
+        return {
+            type: this.layoutType,
+            config: this.layoutConfig,
+        };
+    }
+    /**
+     * Check if group has layout configured (Phase 1.7)
+     */
+    hasLayout() {
+        return this.layoutType !== 'none' && this.layoutConfig !== undefined;
+    }
+    /**
+     * Get layout as flexbox config (Phase 1.7)
+     * @throws Error if layout is not flexbox
+     */
+    getFlexboxLayout() {
+        if (this.layoutType !== 'flexbox') {
+            throw new Error(`Group ${this.id} does not have flexbox layout`);
+        }
+        return this.layoutConfig;
+    }
+    /**
+     * Get layout as grid config (Phase 1.7)
+     * @throws Error if layout is not grid
+     */
+    getGridLayout() {
+        if (this.layoutType !== 'grid') {
+            throw new Error(`Group ${this.id} does not have grid layout`);
+        }
+        return this.layoutConfig;
+    }
+    /**
+     * Calculate bounds from member nodes using global bounds
+     */
+    calculateBounds(diagram) {
+        const nodes = Array.from(this.members)
+            .map(id => diagram.getNode(id))
+            .filter(n => n !== undefined);
+        if (nodes.length === 0) {
+            this.bounds = undefined;
+            return;
+        }
+        // Use global bounds (accounts for transforms)
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        for (const node of nodes) {
+            const bounds = node.getGlobalBounds();
+            minX = Math.min(minX, bounds.left);
+            minY = Math.min(minY, bounds.top);
+            maxX = Math.max(maxX, bounds.right);
+            maxY = Math.max(maxY, bounds.bottom);
+        }
+        this.bounds = {
+            x: minX,
+            y: minY,
+            width: maxX - minX,
+            height: maxY - minY
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Wave-5 Card 3 — Subflow geometry: auto-fit, extent clamping & z-order
+    // ---------------------------------------------------------------------------
+    /**
+     * Resolve {@link padding} to a full four-sided rectangle. `undefined` (the
+     * author never said) resolves to {@link DEFAULT_GROUP_PADDING}; an explicit
+     * value — including the 0 that loaders pin for legacy documents — is taken
+     * as written.
+     */
+    getPadding() {
+        var _a, _b, _c, _d;
+        const p = this.padding;
+        if (p === undefined) {
+            return {
+                top: exports.DEFAULT_GROUP_PADDING,
+                right: exports.DEFAULT_GROUP_PADDING,
+                bottom: exports.DEFAULT_GROUP_PADDING,
+                left: exports.DEFAULT_GROUP_PADDING,
+            };
+        }
+        if (typeof p === 'number') {
+            return { top: p, right: p, bottom: p, left: p };
+        }
+        return {
+            top: (_a = p.top) !== null && _a !== void 0 ? _a : 0,
+            right: (_b = p.right) !== null && _b !== void 0 ? _b : 0,
+            bottom: (_c = p.bottom) !== null && _c !== void 0 ? _c : 0,
+            left: (_d = p.left) !== null && _d !== void 0 ? _d : 0,
+        };
+    }
+    /**
+     * The group's outer frame rectangle in world coordinates. Prefers explicit
+     * geometry (position + size) and falls back to the derived member `bounds`,
+     * matching how GroupMembershipService hit-tests a group.
+     */
+    getOuterBounds() {
+        if (this.size) {
+            return {
+                x: this.position.x,
+                y: this.position.y,
+                width: this.size.width,
+                height: this.size.height,
+            };
+        }
+        if (this.bounds) {
+            return Object.assign({}, this.bounds);
+        }
+        return { x: this.position.x, y: this.position.y, width: 0, height: 0 };
+    }
+    /**
+     * The rectangle members must stay inside: the outer frame minus padding and
+     * minus the header band (which is reserved at the top). Never returns a
+     * negative width/height.
+     */
+    getInnerBounds() {
+        const outer = this.getOuterBounds();
+        const pad = this.getPadding();
+        const x = outer.x + pad.left;
+        const y = outer.y + pad.top + this.headerHeight;
+        const width = Math.max(0, outer.width - pad.left - pad.right);
+        const height = Math.max(0, outer.height - pad.top - pad.bottom - this.headerHeight);
+        return { x, y, width, height };
+    }
+    /**
+     * Auto-fit the group frame to its members' bounding box plus padding and the
+     * header band. This is the real consumer of `padding`/`headerHeight` that
+     * `calculateBounds` (a tight, padding-free box) never was.
+     *
+     * Member groups contribute their own OUTER frame (so a parent fits around a
+     * nested group's full extent, not just its raw member points). With
+     * `deepRecursive`, descendant groups are fitted first (deepest first) so the
+     * parent fits around already-fitted children.
+     *
+     * The computed content rectangle is reconciled with the current frame per the
+     * effective fit mode (grow-only / shrink-only / exact) and written to both
+     * `position`/`size` (authoritative geometry) and `bounds` (hit-test rect).
+     * No-op with no positioned members (nothing to fit around).
+     */
+    fitToContents(diagram, options) {
+        var _a;
+        const dm = this.resolveDiagram(diagram);
+        if (!dm) {
+            return;
+        }
+        if (options === null || options === void 0 ? void 0 : options.deepRecursive) {
+            // Deepest-first so each parent fits around already-fitted children.
+            const descendants = dm
+                .getDescendants(this.id)
+                .sort((a, b) => dm.getDepth(b.id) - dm.getDepth(a.id));
+            for (const child of descendants) {
+                child.fitToContents(dm, { mode: options.mode });
+            }
+        }
+        const content = this.computeMemberExtent(dm);
+        if (!content) {
+            return;
+        }
+        const pad = this.getPadding();
+        const fitted = {
+            x: content.x - pad.left,
+            y: content.y - pad.top - this.headerHeight,
+            width: content.width + pad.left + pad.right,
+            height: content.height + pad.top + pad.bottom + this.headerHeight,
+        };
+        const mode = (_a = options === null || options === void 0 ? void 0 : options.mode) !== null && _a !== void 0 ? _a : this.fitMode;
+        const target = this.reconcileFit(fitted, mode);
+        this.setFrame(target);
+    }
+    /**
+     * Bounding box (world coords) of this group's members. Nodes contribute their
+     * global bounds; member groups contribute their outer frame. Returns
+     * undefined when nothing is positioned.
+     */
+    computeMemberExtent(diagram) {
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        let count = 0;
+        for (const id of this.members) {
+            const node = diagram.getNode(id);
+            if (node) {
+                const b = node.getGlobalBounds();
+                minX = Math.min(minX, b.left);
+                minY = Math.min(minY, b.top);
+                maxX = Math.max(maxX, b.right);
+                maxY = Math.max(maxY, b.bottom);
+                count++;
+                continue;
+            }
+            const child = diagram.getGroup(id);
+            if (child) {
+                const r = child.getOuterBounds();
+                if (r.width > 0 || r.height > 0) {
+                    minX = Math.min(minX, r.x);
+                    minY = Math.min(minY, r.y);
+                    maxX = Math.max(maxX, r.x + r.width);
+                    maxY = Math.max(maxY, r.y + r.height);
+                    count++;
+                }
+            }
+        }
+        if (count === 0) {
+            return undefined;
+        }
+        return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+    }
+    /** Apply a fit mode to reconcile a freshly computed rect with the current frame. */
+    reconcileFit(fitted, mode) {
+        if (mode === 'exact' || !this.size) {
+            return fitted;
+        }
+        const current = this.getOuterBounds();
+        if (mode === 'grow-only') {
+            // Union: expand to contain content, never shrink.
+            const x = Math.min(current.x, fitted.x);
+            const y = Math.min(current.y, fitted.y);
+            const right = Math.max(current.x + current.width, fitted.x + fitted.width);
+            const bottom = Math.max(current.y + current.height, fitted.y + fitted.height);
+            return { x, y, width: right - x, height: bottom - y };
+        }
+        // shrink-only: never grow beyond the current frame — clamp the fitted rect
+        // inside it (but still snap smaller when content is smaller).
+        const x = Math.max(current.x, fitted.x);
+        const y = Math.max(current.y, fitted.y);
+        const right = Math.min(current.x + current.width, fitted.x + fitted.width);
+        const bottom = Math.min(current.y + current.height, fitted.y + fitted.height);
+        return {
+            x,
+            y,
+            width: Math.max(0, right - x),
+            height: Math.max(0, bottom - y),
+        };
+    }
+    /**
+     * Write a world rectangle into the group's authoritative geometry
+     * (position + size) and the derived hit-test `bounds`, keeping the existing
+     * `depth` when present. Tracks a single 'bounds' change for undo/diff.
+     */
+    setFrame(rect) {
+        var _a, _b;
+        const oldBounds = this.bounds;
+        this.position = { x: rect.x, y: rect.y };
+        this.size = {
+            width: rect.width,
+            height: rect.height,
+            depth: (_b = (_a = this.size) === null || _a === void 0 ? void 0 : _a.depth) !== null && _b !== void 0 ? _b : 0,
+        };
+        this.bounds = { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+        this.trackChange('bounds', oldBounds, this.bounds);
+        this.emitter.emit('bounds:changed', this.bounds);
+        // PUSH (A): the frame IS the layout's coordinate system and available width.
+        // Resizing or moving a container without reflowing its children is how you
+        // get a 12-column dashboard whose columns stop matching its own edges.
+        this.requestLayout();
+    }
+    /**
+     * Clamp a member node so it stays fully inside the group's inner extent.
+     * No-op unless `constrainChildren` is set and the node is a direct member.
+     * Returns true when the node was actually moved. Absolute-coordinate model:
+     * this adjusts the node's world position directly.
+     */
+    clampChildToExtent(nodeId, diagram) {
+        if (!this.constrainChildren || !this.members.has(nodeId)) {
+            return false;
+        }
+        const dm = this.resolveDiagram(diagram);
+        const node = dm === null || dm === void 0 ? void 0 : dm.getNode(nodeId);
+        if (!node) {
+            return false;
+        }
+        const inner = this.getInnerBounds();
+        if (inner.width <= 0 || inner.height <= 0) {
+            return false;
+        }
+        const b = node.getGlobalBounds();
+        const w = b.right - b.left;
+        const h = b.bottom - b.top;
+        // Largest top-left that still fits; clamp within [inner.x, inner.right - w].
+        const maxX = Math.max(inner.x, inner.x + inner.width - w);
+        const maxY = Math.max(inner.y, inner.y + inner.height - h);
+        const clampedLeft = Math.min(Math.max(b.left, inner.x), maxX);
+        const clampedTop = Math.min(Math.max(b.top, inner.y), maxY);
+        const dx = clampedLeft - b.left;
+        const dy = clampedTop - b.top;
+        if (dx === 0 && dy === 0) {
+            return false;
+        }
+        node.setPosition(node.position.x + dx, node.position.y + dy);
+        return true;
+    }
+    /**
+     * Wave-5 Card 4: restore raw geometry (position + optional size + bounds)
+     * captured before a collapse. Unlike setFrame this permits size === undefined
+     * so a group that had no explicit frame is restored to exactly that.
+     */
+    restoreGeometry(geo) {
+        const oldBounds = this.bounds;
+        this.position = { x: geo.position.x, y: geo.position.y };
+        this.size = geo.size ? Object.assign({}, geo.size) : undefined;
+        this.bounds = geo.bounds ? Object.assign({}, geo.bounds) : undefined;
+        this.trackChange('bounds', oldBounds, this.bounds);
+        this.emitter.emit('bounds:changed', this.bounds);
+    }
+    /** Set the group's stacking index (lower renders further back). */
+    setZIndex(z) {
+        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 group in front of every other group (highest zIndex + 1).
+     * Minimal z-order API — the renderer honors zIndex ordering.
+     */
+    bringToFront(diagram) {
+        const dm = this.resolveDiagram(diagram);
+        if (!dm) {
+            this.setZIndex(this.zIndex + 1);
+            return;
+        }
+        const max = Math.max(0, ...dm.getGroups().map((g) => g.zIndex));
+        this.setZIndex(max + 1);
+    }
+    /** Send this group behind every other group (lowest zIndex - 1). */
+    sendToBack(diagram) {
+        const dm = this.resolveDiagram(diagram);
+        if (!dm) {
+            this.setZIndex(this.zIndex - 1);
+            return;
+        }
+        const min = Math.min(0, ...dm.getGroups().map((g) => g.zIndex));
+        this.setZIndex(min - 1);
+    }
+    /**
+     * Is push-driven reflow active for this container?
+     *
+     * DEFAULT ON for any group that declares a layout — a container that says
+     * "I am a 12-column grid" and then lets its children drift is not a layout
+     * container. `metadata('autoLayout')` survives as the explicit override:
+     * set it to `false` to freeze the children (useful while dragging, or for a
+     * container whose positions are authored by hand). Setting it to `true`
+     * remains valid and is now simply the default.
+     */
+    isAutoLayoutEnabled() {
+        if (this.getMetadata('autoLayout') === false) {
+            return false;
+        }
+        return this.hasLayout();
+    }
+    /**
+     * THE push entry point: "something changed, reflow if you are supposed to."
+     * Distinct from {@link applyLayout}, which is the unconditional PULL — an
+     * explicit `applyLayout()` still works on an opted-out container.
+     */
+    requestLayout(diagram) {
+        if (!this.isAutoLayoutEnabled()) {
+            return;
+        }
+        this.applyLayout(diagram);
+    }
+    /**
+     * Apply layout to member nodes (Phase 1.7+)
+     * Positions child nodes based on flex or grid layout configuration
+     */
+    applyLayout(diagram) {
+        if (!this.hasLayout() || this.layoutInFlight) {
+            return;
+        }
+        // Get diagram from metadata if not provided
+        const diagramToUse = diagram || this.metadata.get('diagram');
+        if (!diagramToUse) {
+            console.warn(`Cannot apply layout to group ${this.id}: diagram not available`);
+            return;
+        }
+        // Get member entities (nodes and groups)
+        const entities = [];
+        for (const id of this.members) {
+            const node = diagramToUse.getNode(id);
+            if (node) {
+                entities.push(node);
+            }
+            else {
+                const group = diagramToUse.getGroup(id);
+                if (group) {
+                    entities.push(group);
+                }
+            }
+        }
+        if (entities.length === 0) {
+            return;
+        }
+        this.layoutInFlight = true;
+        try {
+            if (this.layoutType === 'flexbox') {
+                this.applyFlexboxLayout(entities);
+            }
+            else if (this.layoutType === 'grid') {
+                this.applyGridLayout(entities);
+            }
+        }
+        finally {
+            this.layoutInFlight = false;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Entity writers — the ONLY places a layout pass touches a child's geometry
+    // ---------------------------------------------------------------------------
+    /**
+     * D — auto-layout SKIPS LOCKED MEMBERS.
+     *
+     * A locked member keeps both its position and its size, but still consumes its
+     * slot in the flow (callers advance the cursor by the child's CURRENT size), so
+     * the container never stacks another widget on top of a pinned one. This is the
+     * precedent `LayoutManager` already set for graph layouts — it restores locked
+     * node positions after every run — and it is what "pin this tile" means to
+     * someone building a dashboard.
+     */
+    isPinned(entity) {
+        var _a;
+        return ((_a = entity.state) === null || _a === void 0 ? void 0 : _a.locked) === true;
+    }
+    /**
+     * Move a member. Nodes go through `setPosition` (tracked + propagating);
+     * member GROUPS go through `setFrame` when they have a frame, which is what
+     * cascades the reflow down into a nested container's own children.
+     */
+    placeEntity(entity, x, y) {
+        if (this.isPinned(entity)) {
+            return;
+        }
+        if ('setPosition' in entity && typeof entity.setPosition === 'function') {
+            entity.setPosition(x, y);
+            return;
+        }
+        const group = entity;
+        if (group.size) {
+            group.setFrame({ x, y, width: group.size.width, height: group.size.height });
+            return;
+        }
+        group.position = { x, y };
+        group.requestLayout();
+    }
+    /**
+     * Resize a member along one or both axes. `undefined` leaves that axis alone.
+     * Nodes go through `setSize` so the write is tracked and honours the per-node
+     * lock; member groups go through `setFrame` so their own children follow.
+     */
+    resizeEntity(entity, width, height) {
+        if (this.isPinned(entity) || !entity.size) {
+            return;
+        }
+        const w = width !== null && width !== void 0 ? width : entity.size.width;
+        const h = height !== null && height !== void 0 ? height : entity.size.height;
+        if (w === entity.size.width && h === entity.size.height) {
+            return;
+        }
+        if ('setSize' in entity && typeof entity.setSize === 'function') {
+            entity.setSize(w, h, entity.size.depth);
+            return;
+        }
+        const group = entity;
+        group.setFrame({ x: group.position.x, y: group.position.y, width: w, height: h });
+    }
+    /**
+     * B — the per-item flex config, finally read. `order` is a stable sort key
+     * (equal orders keep membership order), exactly like CSS.
+     */
+    orderFlexEntities(entities) {
+        const anyOrdered = entities.some((e) => { var _a; return ((_a = this.flexItemOf(e)) === null || _a === void 0 ? void 0 : _a.order) !== undefined; });
+        if (!anyOrdered) {
+            return entities;
+        }
+        return entities
+            .map((entity, i) => ({ entity, i }))
+            .sort((a, b) => {
+            var _a, _b, _c, _d;
+            const oa = (_b = (_a = this.flexItemOf(a.entity)) === null || _a === void 0 ? void 0 : _a.order) !== null && _b !== void 0 ? _b : 0;
+            const ob = (_d = (_c = this.flexItemOf(b.entity)) === null || _c === void 0 ? void 0 : _c.order) !== null && _d !== void 0 ? _d : 0;
+            return oa !== ob ? oa - ob : a.i - b.i;
+        })
+            .map((e) => e.entity);
+    }
+    /** FlexItemConfig of a member, if it is a node that carries one. */
+    flexItemOf(entity) {
+        const node = entity;
+        return typeof node.getFlexItem === 'function' ? node.getFlexItem() : undefined;
+    }
+    /** GridItemConfig of a member, if it is a node that carries one. */
+    gridItemOf(entity) {
+        const node = entity;
+        return typeof node.getGridItem === 'function' ? node.getGridItem() : undefined;
+    }
+    /**
+     * Apply flexbox layout to entities (nodes or groups).
+     *
+     * B — a real single-pass flex algorithm, written axis-agnostically so `row` and
+     * `column` share one code path: line breaking (`wrap`), `flexGrow` distribution,
+     * `justifyContent` on the main axis, and `alignItems`/`alignSelf` (including
+     * `stretch`) on the cross axis. Previously only `justifyContent: 'center'` and
+     * `alignItems: 'center'` existed and `wrap` was unread.
+     *
+     * The Bootstrap-style `columns` path is untouched and still takes priority for
+     * row containers — see {@link applyColumnBasedLayout}.
+     */
+    applyFlexboxLayout(entities) {
+        var _a, _b, _c;
+        const config = this.getFlexboxLayout();
+        const padding = this.normalizePadding(config.padding);
+        const isColumn = config.direction === 'column' || config.direction === 'column-reverse';
+        const isReverse = config.direction.endsWith('-reverse');
+        // PRESERVED QUIRK: the main-axis gap reads `gap.row` for BOTH directions when
+        // gap is an object. Every asserted pixel in the existing specs was produced by
+        // that reading; the cross-axis (line) gap is new and picks the correct member.
+        const mainGap = typeof config.gap === 'number' ? config.gap : config.gap.row;
+        const crossGap = typeof config.gap === 'number' ? config.gap : isColumn ? config.gap.column : config.gap.row;
+        const ordered = this.orderFlexEntities(entities);
+        const directed = isReverse ? ordered.slice().reverse() : ordered;
+        const startX = this.position.x + padding.left;
+        const startY = this.position.y + padding.top;
+        // Bootstrap 12-column path (rows only), unchanged.
+        if (!isColumn && config.columns !== undefined && config.columns > 0 && this.size) {
+            this.applyColumnBasedLayout(directed, config, padding, startX, startY);
+            return;
+        }
+        const contentWidth = this.size ? this.size.width - padding.left - padding.right : undefined;
+        const contentHeight = this.size ? this.size.height - padding.top - padding.bottom : undefined;
+        const mainAvail = isColumn ? contentHeight : contentWidth;
+        const crossAvail = isColumn ? contentWidth : contentHeight;
+        const mainOf = (e) => { var _a, _b, _c; return (_c = (isColumn ? (_a = e.size) === null || _a === void 0 ? void 0 : _a.height : (_b = e.size) === null || _b === void 0 ? void 0 : _b.width)) !== null && _c !== void 0 ? _c : (isColumn ? 50 : 100); };
+        const crossOf = (e) => { var _a, _b, _c; return (_c = (isColumn ? (_a = e.size) === null || _a === void 0 ? void 0 : _a.width : (_b = e.size) === null || _b === void 0 ? void 0 : _b.height)) !== null && _c !== void 0 ? _c : (isColumn ? 100 : 50); };
+        // ---- 1. Line breaking (`wrap`) -----------------------------------------
+        // Without a container extent there is no overflow to detect, so an unsized
+        // container is always single-line regardless of `wrap` — which is exactly the
+        // behaviour every pre-existing spec was written against.
+        const wraps = config.wrap !== 'nowrap' && mainAvail !== undefined;
+        const lines = [];
+        if (!wraps) {
+            lines.push(directed);
+        }
+        else {
+            let line = [];
+            let used = 0;
+            for (const entity of directed) {
+                const size = mainOf(entity);
+                const next = line.length === 0 ? size : used + mainGap + size;
+                if (line.length > 0 && next > mainAvail) {
+                    lines.push(line);
+                    line = [entity];
+                    used = size;
+                }
+                else {
+                    line.push(entity);
+                    used = next;
+                }
+            }
+            if (line.length > 0) {
+                lines.push(line);
+            }
+        }
+        if (config.wrap === 'wrap-reverse') {
+            lines.reverse();
+        }
+        // ---- 2. Per-line: grow, justify, align ----------------------------------
+        let crossCursor = isColumn ? startX : startY;
+        for (const line of lines) {
+            // flexGrow — distribute leftover main-axis space by factor.
+            if (mainAvail !== undefined) {
+                const totalGrow = line.reduce((s, e) => { var _a, _b; return s + ((_b = (_a = this.flexItemOf(e)) === null || _a === void 0 ? void 0 : _a.flexGrow) !== null && _b !== void 0 ? _b : 0); }, 0);
+                if (totalGrow > 0) {
+                    const used = line.reduce((s, e) => s + mainOf(e), 0) + mainGap * Math.max(0, line.length - 1);
+                    const free = mainAvail - used;
+                    if (free > 0) {
+                        for (const entity of line) {
+                            const grow = (_b = (_a = this.flexItemOf(entity)) === null || _a === void 0 ? void 0 : _a.flexGrow) !== null && _b !== void 0 ? _b : 0;
+                            if (grow <= 0)
+                                continue;
+                            const target = mainOf(entity) + (free * grow) / totalGrow;
+                            this.resizeEntity(entity, isColumn ? undefined : target, isColumn ? target : undefined);
+                        }
+                    }
+                }
+            }
+            // The line's cross extent. A SINGLE line in a sized container fills the
+            // container's content box (that is what makes `center`/`end`/`stretch`
+            // measure against the container, as the legacy centering code did); wrapped
+            // lines measure against their own tallest item, as CSS does.
+            const lineCross = lines.length === 1 && crossAvail !== undefined
+                ? crossAvail
+                : line.reduce((m, e) => Math.max(m, crossOf(e)), 0);
+            // justifyContent — main-axis offset + inter-item spacing.
+            const usedMain = line.reduce((s, e) => s + mainOf(e), 0) + mainGap * Math.max(0, line.length - 1);
+            const free = mainAvail !== undefined ? mainAvail - usedMain : 0;
+            const { offset, spacing } = this.resolveJustify(config.justifyContent, mainAvail !== undefined ? free : 0, line.length);
+            let mainCursor = (isColumn ? startY : startX) + offset;
+            for (const entity of line) {
+                const align = (_c = this.flexItemOf(entity)) === null || _c === void 0 ? void 0 : _c.alignSelf;
+                const effectiveAlign = align === undefined || align === 'auto' ? config.alignItems : align;
+                if (effectiveAlign === 'stretch') {
+                    this.resizeEntity(entity, isColumn ? lineCross : undefined, isColumn ? undefined : lineCross);
+                }
+                const crossOffset = this.resolveAlign(effectiveAlign, lineCross, crossOf(entity));
+                const cross = crossCursor + crossOffset;
+                this.placeEntity(entity, isColumn ? cross : mainCursor, isColumn ? mainCursor : cross);
+                mainCursor += mainOf(entity) + mainGap + spacing;
+            }
+            crossCursor += lineCross + crossGap;
+        }
+    }
+    /**
+     * Main-axis distribution for one flex line: how far the first item is pushed in,
+     * and how much EXTRA space goes between consecutive items (on top of `gap`).
+     * `start` (and anything unrecognised) is the identity, so a container with no
+     * size — where `free` is passed as 0 — always lays out from the content origin.
+     */
+    resolveJustify(justify, free, count) {
+        if (free <= 0 || count === 0) {
+            return { offset: 0, spacing: 0 };
+        }
+        switch (justify) {
+            case 'center':
+                return { offset: free / 2, spacing: 0 };
+            case 'end':
+                return { offset: free, spacing: 0 };
+            case 'space-between':
+                return count === 1
+                    ? { offset: 0, spacing: 0 }
+                    : { offset: 0, spacing: free / (count - 1) };
+            case 'space-around': {
+                const unit = free / count;
+                return { offset: unit / 2, spacing: unit };
+            }
+            case 'space-evenly': {
+                const unit = free / (count + 1);
+                return { offset: unit, spacing: unit };
+            }
+            default:
+                return { offset: 0, spacing: 0 };
+        }
+    }
+    /**
+     * Cross-axis offset of one item inside its line. `stretch` has already resized
+     * the item by the time this runs, so it lands at the line start like `start`.
+     * `baseline` degrades to `start`: this model has no text baselines to align to,
+     * and quietly inventing one would be worse than saying so.
+     */
+    resolveAlign(align, lineCross, itemCross) {
+        switch (align) {
+            case 'center':
+                return (lineCross - itemCross) / 2;
+            case 'end':
+                return lineCross - itemCross;
+            default:
+                return 0;
+        }
+    }
+    /**
+     * Apply column-based layout (like Bootstrap 12-column grid)
+     */
+    applyColumnBasedLayout(entities, config, padding, startX, startY) {
+        var _a, _b, _c;
+        if (!this.size || !config.columns)
+            return;
+        const totalColumns = config.columns;
+        const gap = typeof config.gap === 'number' ? config.gap : config.gap.column || 0;
+        // Available width for content (excluding padding)
+        const availableWidth = this.size.width - padding.left - padding.right;
+        // Calculate column width (including gaps)
+        const totalGaps = (totalColumns - 1) * gap;
+        const columnWidth = (availableWidth - totalGaps) / totalColumns;
+        let currentX = startX;
+        let currentY = startY;
+        let currentColumn = 0;
+        let currentRowHeight = 0; // Track max height in current row
+        const rowEntities = []; // Track entities in current row
+        for (const entity of entities) {
+            // Get column span from metadata (default = 1)
+            const columnSpan = entity.getMetadata('columnSpan') || 1;
+            const clampedSpan = Math.min(columnSpan, totalColumns);
+            // Check if entity fits in current row
+            if (currentColumn + clampedSpan > totalColumns) {
+                // Move to next row
+                currentColumn = 0;
+                currentX = startX;
+                currentY += currentRowHeight + gap;
+                currentRowHeight = 0;
+                rowEntities.length = 0; // Clear row entities
+            }
+            // Calculate entity width based on column span
+            const entityWidth = columnWidth * clampedSpan + gap * (clampedSpan - 1);
+            // Update entity size to match column width. Routed through resizeEntity /
+            // placeEntity so the write is tracked, honours the per-node lock (D), and
+            // cascades into a member group's own children (A).
+            this.resizeEntity(entity, entityWidth);
+            this.placeEntity(entity, currentX, currentY);
+            // Track row height (max height in this row). A PINNED member keeps its own
+            // size, so the cursor advances by what it actually occupies.
+            const occupiedWidth = this.isPinned(entity) ? (_b = (_a = entity.size) === null || _a === void 0 ? void 0 : _a.width) !== null && _b !== void 0 ? _b : entityWidth : entityWidth;
+            const entityHeight = ((_c = entity.size) === null || _c === void 0 ? void 0 : _c.height) || 100;
+            currentRowHeight = Math.max(currentRowHeight, entityHeight);
+            rowEntities.push(entity);
+            // Move to next column position
+            currentX += occupiedWidth + gap;
+            currentColumn += clampedSpan;
+        }
+    }
+    /**
+     * Apply grid layout to entities (nodes or groups).
+     *
+     * B — placement now comes from each item's {@link GridItemConfig} (explicit
+     * `columnStart`/`rowStart` lines and `columnEnd`/`rowEnd` spans), not from the
+     * member's ARRAY INDEX. Items with no explicit placement auto-flow into the
+     * first cell no explicit item has claimed, in `autoFlow` order. Tracks are
+     * uniform: derived from the container's content box when it has one, and from
+     * the widest/tallest member otherwise (which is what the old per-entity
+     * arithmetic already produced for the equal-sized children it was written for).
+     */
+    applyGridLayout(entities) {
+        var _a, _b;
+        const config = this.getGridLayout();
+        const columns = Math.max(1, this.parseGridColumns(config.templateColumns));
+        const columnGap = config.columnGap || 0;
+        const rowGap = config.rowGap || 0;
+        const padding = this.normalizePadding(config.padding);
+        const startX = this.position.x + padding.left;
+        const startY = this.position.y + padding.top;
+        // `templateRows` bounds a column-flow grid's row axis (CSS: column flow grows
+        // COLUMNS, so the rows have to be finite). With none declared, fall back to
+        // "as many rows as there are members", which can never force a wrap.
+        const templateRowCount = config.templateRows ? this.parseGridColumns(config.templateRows) : 0;
+        const rowLimit = templateRowCount > 0 ? templateRowCount : Math.max(1, entities.length);
+        const placements = this.resolveGridPlacements(entities, columns, config.autoFlow, rowLimit);
+        // Track sizes.
+        const rowCount = placements.reduce((m, p) => Math.max(m, p.row + p.rowSpan), 1);
+        const contentWidth = this.size ? this.size.width - padding.left - padding.right : undefined;
+        const contentHeight = this.size ? this.size.height - padding.top - padding.bottom : undefined;
+        const rowTracks = Math.max(rowCount, templateRowCount || 0, 1);
+        const columnWidth = contentWidth !== undefined
+            ? (contentWidth - columnGap * (columns - 1)) / columns
+            : entities.reduce((m, e) => { var _a, _b; return Math.max(m, (_b = (_a = e.size) === null || _a === void 0 ? void 0 : _a.width) !== null && _b !== void 0 ? _b : 0); }, 0) || 100;
+        const rowHeight = contentHeight !== undefined
+            ? (contentHeight - rowGap * (rowTracks - 1)) / rowTracks
+            : entities.reduce((m, e) => { var _a, _b; return Math.max(m, (_b = (_a = e.size) === null || _a === void 0 ? void 0 : _a.height) !== null && _b !== void 0 ? _b : 0); }, 0) || 100;
+        for (const { entity, row, column, rowSpan, columnSpan } of placements) {
+            const x = startX + column * (columnWidth + columnGap);
+            const y = startY + row * (rowHeight + rowGap);
+            // Cell-filling is OPT-IN. CSS defaults `justify-items`/`align-items` to
+            // stretch, but this engine's grid never resized anything, and silently
+            // starting to would re-geometry every existing grid container. Ask for it.
+            const item = this.gridItemOf(entity);
+            const justify = (_a = item === null || item === void 0 ? void 0 : item.justifySelf) !== null && _a !== void 0 ? _a : config.justifyItems;
+            const alignSelf = (_b = item === null || item === void 0 ? void 0 : item.alignSelf) !== null && _b !== void 0 ? _b : config.alignItems;
+            const stretchW = justify === 'stretch';
+            const stretchH = alignSelf === 'stretch';
+            if (stretchW || stretchH) {
+                this.resizeEntity(entity, stretchW ? columnWidth * columnSpan + columnGap * (columnSpan - 1) : undefined, stretchH ? rowHeight * rowSpan + rowGap * (rowSpan - 1) : undefined);
+            }
+            this.placeEntity(entity, x, y);
+        }
+    }
+    /**
+     * Resolve every member to a 0-based grid cell + span.
+     *
+     * Two passes, because explicit placement must WIN: pass 1 reserves the cells
+     * claimed by items with a `GridItemConfig` line (or a `gridColumn`/`gridRow`
+     * metadata fallback); pass 2 flows the rest into the first cell still free.
+     * Without the reservation an auto item would happily land under a pinned one —
+     * which is precisely the bug "placement by array index" always had.
+     */
+    resolveGridPlacements(entities, columns, autoFlow, rowLimit) {
+        var _a, _b;
+        const occupied = new Set();
+        const key = (r, c) => `${r}:${c}`;
+        const occupy = (p) => {
+            for (let r = p.row; r < p.row + p.rowSpan; r++) {
+                for (let c = p.column; c < p.column + p.columnSpan; c++) {
+                    occupied.add(key(r, c));
+                }
+            }
+        };
+        const fits = (row, column, rowSpan, columnSpan) => {
+            if (column + columnSpan > columns)
+                return false;
+            for (let r = row; r < row + rowSpan; r++) {
+                for (let c = column; c < column + columnSpan; c++) {
+                    if (occupied.has(key(r, c)))
+                        return false;
+                }
+            }
+            return true;
+        };
+        const line = (v) => typeof v === 'number' && v >= 1 ? v - 1 : undefined; // CSS lines are 1-based
+        const specs = entities.map((entity) => {
+            var _a, _b;
+            const item = this.gridItemOf(entity);
+            const column = (_a = line(item === null || item === void 0 ? void 0 : item.columnStart)) !== null && _a !== void 0 ? _a : line(entity.getMetadata('gridColumn'));
+            const row = (_b = line(item === null || item === void 0 ? void 0 : item.rowStart)) !== null && _b !== void 0 ? _b : line(entity.getMetadata('gridRow'));
+            // Span: the CSS end-line form first, then the `columnSpan`/`rowSpan`
+            // metadata the Bootstrap path already uses (kept working on purpose).
+            const endCol = line(item === null || item === void 0 ? void 0 : item.columnEnd);
+            const endRow = line(item === null || item === void 0 ? void 0 : item.rowEnd);
+            const columnSpan = Math.max(1, Math.min(columns, endCol !== undefined && column !== undefined
+                ? endCol - column
+                : entity.getMetadata('columnSpan') || 1));
+            const rowSpan = Math.max(1, endRow !== undefined && row !== undefined
+                ? endRow - row
+                : entity.getMetadata('rowSpan') || 1);
+            return { entity, row, column, rowSpan, columnSpan };
+        });
+        const placements = [];
+        // Pass 1 — explicit placements reserve their cells.
+        for (const spec of specs) {
+            if (spec.row === undefined || spec.column === undefined)
+                continue;
+            const p = {
+                entity: spec.entity,
+                row: spec.row,
+                column: Math.min(spec.column, Math.max(0, columns - spec.columnSpan)),
+                rowSpan: spec.rowSpan,
+                columnSpan: spec.columnSpan,
+            };
+            occupy(p);
+            placements.push(p);
+        }
+        // Pass 2 — auto-flow the rest into the first cell pass 1 left free.
+        //
+        // `row` flow scans row-major (across, then down); `column` flow scans
+        // column-major (down `rowLimit` rows, then across). The row axis is
+        // unbounded in row flow, so the scan is capped rather than trusted.
+        const columnFirst = autoFlow === 'column';
+        const maxScan = (entities.length + 2) * (columns + 2);
+        for (const spec of specs) {
+            if (spec.row !== undefined && spec.column !== undefined)
+                continue;
+            let row = (_a = spec.row) !== null && _a !== void 0 ? _a : 0;
+            let column = (_b = spec.column) !== null && _b !== void 0 ? _b : 0;
+            if (spec.column !== undefined) {
+                // Column pinned by the author: walk DOWN that column for a free row.
+                while (!fits(row, column, spec.rowSpan, spec.columnSpan) && row < maxScan)
+                    row++;
+            }
+            else if (spec.row !== undefined) {
+                // Row pinned: walk ACROSS that row.
+                while (!fits(row, column, spec.rowSpan, spec.columnSpan) && column < columns)
+                    column++;
+                if (column >= columns)
+                    column = 0;
+            }
+            else if (columnFirst) {
+                let scanned = 0;
+                while (!fits(row, column, spec.rowSpan, spec.columnSpan) && scanned++ < maxScan) {
+                    row++;
+                    if (row + spec.rowSpan > rowLimit) {
+                        row = 0;
+                        column++;
+                    }
+                }
+            }
+            else {
+                let scanned = 0;
+                while (!fits(row, column, spec.rowSpan, spec.columnSpan) && scanned++ < maxScan) {
+                    column++;
+                    if (column + spec.columnSpan > columns) {
+                        column = 0;
+                        row++;
+                    }
+                }
+            }
+            const p = {
+                entity: spec.entity,
+                row,
+                column: Math.min(column, Math.max(0, columns - spec.columnSpan)),
+                rowSpan: spec.rowSpan,
+                columnSpan: spec.columnSpan,
+            };
+            occupy(p);
+            placements.push(p);
+        }
+        return placements;
+    }
+    /**
+     * Normalize padding to all four sides
+     */
+    normalizePadding(padding) {
+        if (padding === undefined) {
+            return { top: 0, right: 0, bottom: 0, left: 0 };
+        }
+        if (typeof padding === 'number') {
+            return { top: padding, right: padding, bottom: padding, left: padding };
+        }
+        return padding;
+    }
+    /**
+     * Parse grid template columns to get column count
+     */
+    parseGridColumns(templateColumns) {
+        // Simple parser - count space-separated values
+        // Example: "1fr 1fr 1fr" = 3 columns, "repeat(3, 1fr)" = 3 columns
+        const repeatMatch = templateColumns.match(/repeat\((\d+),/);
+        if (repeatMatch) {
+            return parseInt(repeatMatch[1], 10);
+        }
+        return templateColumns.split(' ').length;
+    }
+    /**
+     * Serialize to JSON
+     */
+    serialize() {
+        var _a;
+        // The 'diagram' metadata key is RUNTIME wiring (a live DiagramModel
+        // back-reference stashed by DiagramModel.addGroup/installGroup). It must
+        // never reach the payload: serializing it embeds the entire live model
+        // into the JSON (circular reference — JSON.stringify throws). The install
+        // path re-stashes it on load.
+        const metadata = Object.fromEntries(Array.from(this.metadata).filter(([key]) => key !== 'diagram'));
+        return {
+            id: this.id,
+            uuid: this.uuid,
+            type: 'group',
+            version: this.version,
+            metadata,
+            name: this.name,
+            members: Array.from(this.members),
+            isCollapsed: this.isCollapsed,
+            bounds: this.bounds,
+            layoutType: this.layoutType, // Phase 1.7
+            layoutConfig: this.layoutConfig, // Phase 1.7
+            // Group geometry: round-trip position (always present) and size (optional)
+            // so layout/placement survives save/load.
+            position: { x: this.position.x, y: this.position.y },
+            size: this.size
+                ? { width: this.size.width, height: this.size.height, depth: this.size.depth }
+                : undefined,
+            // Wave-2: containment tree pointer (undefined for top-level groups).
+            parentGroupId: this.parentGroupId,
+            // Wave-5 Card 3: padding is RESOLVED at save time — a document must mean
+            // what it meant, so an authored group pins today's default into the file
+            // (a future default change can never re-geometry it). headerHeight 0 is
+            // still omitted: loaders pin the absent key back to 0, which keeps legacy
+            // documents byte-stable through load→save.
+            padding: (_a = this.padding) !== null && _a !== void 0 ? _a : exports.DEFAULT_GROUP_PADDING,
+            headerHeight: this.headerHeight !== 0 ? this.headerHeight : undefined,
+            zIndex: this.zIndex !== 0 ? this.zIndex : undefined,
+            fitMode: this.fitMode !== 'exact' ? this.fitMode : undefined,
+            constrainChildren: this.constrainChildren ? true : undefined,
+            // Wave-5 Card 4: present only while collapsed.
+            collapsedState: this.collapsedState,
+            // Wave-5 Card 5: per-group compound-layout intent (present only when set).
+            subgraphLayout: this.subgraphLayout,
+            // Wave-5 Card 6: swimlane/pool band config (present only on pools & lanes).
+            laneConfig: this.laneConfig,
+            // Wave-5 Card 7: declarative auto-membership rule + capacity/WIP limit.
+            membershipRule: this.membershipRule,
+            capacity: this.capacity,
+        };
+    }
+    /**
+     * Deserialize from JSON
+     */
+    static fromJSON(data) {
+        var _a;
+        const group = new GroupModel({ id: data.id, name: data.name });
+        group.members = new Set(data.members);
+        group.isCollapsed = data.isCollapsed;
+        group.bounds = data.bounds;
+        // Wave-2: restore containment tree pointer.
+        if (data.parentGroupId !== undefined) {
+            group.parentGroupId = data.parentGroupId;
+        }
+        // Restore group geometry (position/size). Position defaults to origin when
+        // absent so older serialized payloads keep working.
+        if (data.position) {
+            group.position = { x: data.position.x, y: data.position.y };
+        }
+        if (data.size) {
+            group.size = {
+                width: data.size.width,
+                height: data.size.height,
+                depth: data.size.depth,
+            };
+        }
+        // Phase 1.7: Restore layout configuration
+        if (data.layoutType) {
+            group.layoutType = data.layoutType;
+        }
+        if (data.layoutConfig) {
+            group.layoutConfig = data.layoutConfig;
+        }
+        // Wave-5 Card 3: restore subflow geometry. Absent keys PIN TO 0 — they were
+        // written by an engine whose values were 0, and a loaded document must mean
+        // what it meant when saved. Leaving padding `undefined` here would let
+        // getPadding() resolve it to the authored default and silently re-geometry
+        // every legacy fit.
+        group.padding = (_a = data.padding) !== null && _a !== void 0 ? _a : 0;
+        group.headerHeight = typeof data.headerHeight === 'number' ? data.headerHeight : 0;
+        if (typeof data.zIndex === 'number') {
+            group.zIndex = data.zIndex;
+        }
+        if (data.fitMode) {
+            group.fitMode = data.fitMode;
+        }
+        if (data.constrainChildren !== undefined) {
+            group.constrainChildren = data.constrainChildren;
+        }
+        // Wave-5 Card 4: restore collapse snapshot (only present while collapsed).
+        if (data.collapsedState) {
+            group.collapsedState = data.collapsedState;
+        }
+        // Wave-5 Card 5: restore per-group compound-layout intent.
+        if (data.subgraphLayout) {
+            group.subgraphLayout = data.subgraphLayout;
+        }
+        // Wave-5 Card 6: restore swimlane/pool band config.
+        if (data.laneConfig) {
+            group.laneConfig = data.laneConfig;
+        }
+        // Wave-5 Card 7: restore declarative membership rule + capacity/WIP limit.
+        if (data.membershipRule) {
+            group.membershipRule = data.membershipRule;
+        }
+        if (typeof data.capacity === 'number') {
+            group.capacity = data.capacity;
+        }
+        // Restore metadata
+        for (const [key, value] of Object.entries(data.metadata)) {
+            group.metadata.set(key, value);
+        }
+        // Last: restore persisted identity (uuid) and mutation counter (version).
+        group.restoreIdentity(data);
+        return group;
+    }
+}
+exports.GroupModel = GroupModel;
+//# sourceMappingURL=GroupModel.js.map