@rse/gradia 1.1.9 → 1.2.0

package/dst/gradia-api-render-container.js

@@ -0,0 +1,300 @@
+/*
+**  Gradia -- Object Graph Diagram Rendering
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
+*/
+import { FS_GROUP, FS_TYPE, textWidth } from "./gradia-api-render-base.js";
+import { parentOf, containerTypeOf, containerHead, typeOf, defaultStyleOf } from "./gradia-api-render-node.js";
+import { simplifyPoly } from "./gradia-api-render-edge.js";
+/*  determine the containment tree of the graph (in order of node
+    appearance) and validate it: every "parent" has to be a declared
+    node, no node may be nested into itself, no edge may connect a
+    container with one of its own members, and every "container"
+    annotation has to name a valid diagram type  */
+export const containmentOf = (graph, types) => {
+    const parentOfId = new Map();
+    const childrenOf = new Map();
+    for (const node of graph.nodes.values()) {
+        const type = containerTypeOf(node);
+        if (type !== undefined && !types.includes(type))
+            throw new Error(`invalid container layout type "${type}" of node "${node.id}"`);
+        const parent = parentOf(node);
+        if (parent === undefined)
+            continue;
+        if (!graph.nodes.has(parent))
+            throw new Error(`container "${parent}" of node "${node.id}" is not a declared node`);
+        parentOfId.set(node.id, parent);
+        const children = childrenOf.get(parent);
+        if (children === undefined)
+            childrenOf.set(parent, [node]);
+        else
+            children.push(node);
+    }
+    for (const id of parentOfId.keys()) {
+        const seen = new Set([id]);
+        for (let p = parentOfId.get(id); p !== undefined; p = parentOfId.get(p)) {
+            if (seen.has(p))
+                throw new Error(`node "${id}" cannot be nested into itself (containment cycle)`);
+            seen.add(p);
+        }
+    }
+    const isAncestor = (a, id) => {
+        for (let p = parentOfId.get(id); p !== undefined; p = parentOfId.get(p))
+            if (p === a)
+                return true;
+        return false;
+    };
+    for (const edge of graph.edges)
+        if (isAncestor(edge.source, edge.target) || isAncestor(edge.target, edge.source))
+            throw new Error(`edge "${edge.source}" --> "${edge.target}" ` +
+                "connects a container with one of its own members");
+    return { parentOf: parentOfId, childrenOf };
+};
+/*  the outermost container of a node (the node itself if not nested)  */
+export const rootOf = (containment, id) => {
+    let root = id;
+    for (let p = containment.parentOf.get(root); p !== undefined; p = containment.parentOf.get(root))
+        root = p;
+    return root;
+};
+/*  determine the bounding box of a laid out graph (its nodes, edges,
+    container boxes, and the additionally given polylines)  */
+export const boundsOf = (layout, extra = []) => {
+    const { nodes, cx, cy, boxW, boxH, polys } = layout;
+    let [minX, minY, maxX, maxY] = [Infinity, Infinity, -Infinity, -Infinity];
+    for (const node of nodes) {
+        minX = Math.min(minX, cx(node.id) - boxW.get(node.id) / 2);
+        minY = Math.min(minY, cy(node.id) - boxH.get(node.id) / 2);
+        maxX = Math.max(maxX, cx(node.id) + boxW.get(node.id) / 2);
+        maxY = Math.max(maxY, cy(node.id) + boxH.get(node.id) / 2);
+    }
+    for (const poly of [...polys, ...extra]) {
+        for (const [px, py] of poly) {
+            minX = Math.min(minX, px);
+            minY = Math.min(minY, py);
+            maxX = Math.max(maxX, px);
+            maxY = Math.max(maxY, py);
+        }
+    }
+    for (const c of layout.containers ?? []) {
+        minX = Math.min(minX, c.x);
+        minY = Math.min(minY, c.y);
+        maxX = Math.max(maxX, c.x + c.w);
+        maxY = Math.max(maxY, c.y + c.h);
+    }
+    if (!Number.isFinite(minX))
+        [minX, minY, maxX, maxY] = [0, 0, 0, 0];
+    return { minX, minY, maxX, maxY };
+};
+/*  the id of the gate node carrying the given edge across a container
+    boundary (the control character keeps it apart from all user ids)  */
+const gateId = (edge, side) => `\u0000gate:${edge}:${side}`;
+/*  lay out a graph model with its container nodes: each container is
+    laid out as a containment level of its own (innermost first, with the
+    diagram type of the enclosing level unless annotated otherwise), and
+    then takes part in the layout of its enclosing level as a placeholder
+    node of the size of its box. An edge crossing a container boundary
+    is lifted to the level where both its endpoints (or the containers
+    holding them) are members, while inside every crossed container (of
+    a gated diagram type) it continues from a gate node on the boundary
+    to the inner node. The partial routes are finally stitched into
+    the complete route of the edge  */
+export const renderContained = async (graph, containment, type, types, config) => {
+    const nodes = Array.from(graph.nodes.values());
+    const isContainer = (node) => containment.childrenOf.has(node.id) || containerTypeOf(node) !== undefined;
+    /*  short-cut the plain case of a graph without any container  */
+    if (!nodes.some(isContainer))
+        return types[type].render(graph, config);
+    const pad = config["container-box-padding"];
+    /*  reject the node ids which could collide with the gate node ids  */
+    for (const node of nodes)
+        if (node.id.includes("\u0000"))
+            throw new Error(`node id ${JSON.stringify(node.id)} contains a reserved control character`);
+    /*  the box size of a container placeholder: its content plus
+        the padding and the head, at least as wide as its tag  */
+    const sizeOf = (member, b) => {
+        const tag = Math.max(textWidth(member.name, FS_GROUP), textWidth(typeOf(member) ?? "", FS_TYPE));
+        return {
+            w: Math.max(b.maxX - b.minX, tag) + pad * 2,
+            h: b.maxY - b.minY + pad * 2 + containerHead(member)
+        };
+    };
+    /*  compose a laid out containment level with its inner levels: the
+        inner layouts are shifted into their container boxes, the edges
+        of the level are stitched together with the partial routes
+        inside the containers they leave or enter, and the placeholders
+        and gates are dropped (the container boxes are rendered in
+        their place)  */
+    const composeLevel = (layout, inner, levelEdges, origin, gates, type) => {
+        /*  shift every inner layout into its container box (the parts
+            are the level layout itself and the shifted inner layouts,
+            with every node id dispatching to the part it belongs to)  */
+        const parts = [{ layout, dx: 0, dy: 0 }];
+        const partOf = new Map();
+        for (const node of layout.nodes)
+            partOf.set(node.id, 0);
+        const boxes = [];
+        const innerBoxes = [];
+        for (const [id, level] of inner) {
+            const member = graph.nodes.get(id);
+            if (!layout.nodes.some((node) => node.id === id))
+                throw new Error(`container "${id}" cannot be placed twice by diagram type "${type}"`);
+            const { w, h } = sizeOf(member, level.bounds);
+            const cx = layout.cx(id);
+            const cy = layout.cy(id);
+            const k = parts.push({
+                layout: level.layout,
+                dx: cx - w / 2 + pad - level.bounds.minX,
+                dy: cy - h / 2 + containerHead(member) + pad - level.bounds.minY
+            }) - 1;
+            for (const node of level.layout.nodes)
+                partOf.set(node.id, k);
+            partOf.set(id, k);
+            boxes.push({
+                node: member,
+                x: cx - layout.boxW.get(id) / 2,
+                y: cy - layout.boxH.get(id) / 2,
+                w: layout.boxW.get(id),
+                h: layout.boxH.get(id)
+            });
+            innerBoxes.push(...(level.layout.containers ?? []).map((c) => ({ ...c, x: c.x + parts[k].dx, y: c.y + parts[k].dy })));
+        }
+        const shift = (poly, k) => poly.map(([px, py]) => [px + parts[k].dx, py + parts[k].dy]);
+        /*  collect the edges completed within the inner levels, then
+            the edges of this level, each stitched together with the
+            partial routes inside the containers it leaves or enters
+            (an edge crossing the boundary of this level stays partial)  */
+        const edges = [];
+        const polys = [];
+        const partial = new Map();
+        parts.forEach((part, k) => {
+            if (k === 0)
+                return;
+            part.layout.edges.forEach((edge, ei) => {
+                edges.push(edge);
+                polys.push(shift(part.layout.polys[ei], k));
+            });
+        });
+        levelEdges.forEach((edge, li) => {
+            const i = origin[li];
+            const head = inner.get(edge.source)?.partial.get(i);
+            const tail = inner.get(edge.target)?.partial.get(i);
+            const poly = simplifyPoly([
+                ...(head !== undefined ? shift(head, partOf.get(edge.source)) : []),
+                ...layout.polys[li],
+                ...(tail !== undefined ? shift(tail, partOf.get(edge.target)) : [])
+            ]);
+            if (gates.has(edge.source) || gates.has(edge.target))
+                partial.set(i, poly);
+            else {
+                edges.push(graph.edges[i]);
+                polys.push(poly);
+            }
+        });
+        /*  compose the level (the placeholders and gates are dropped,
+            as the container boxes are rendered in their place)  */
+        const merge = (pick) => new Map(parts.flatMap((part) => Array.from(pick(part.layout).entries())));
+        const composed = {
+            nodes: [
+                ...layout.nodes.filter((node) => !inner.has(node.id) && !gates.has(node.id)),
+                ...parts.slice(1).flatMap((part) => part.layout.nodes)
+            ],
+            edges,
+            cx: (id) => parts[partOf.get(id)].layout.cx(id) + parts[partOf.get(id)].dx,
+            cy: (id) => parts[partOf.get(id)].layout.cy(id) + parts[partOf.get(id)].dy,
+            boxW: merge((layout) => layout.boxW),
+            boxH: merge((layout) => layout.boxH),
+            contentH: merge((layout) => layout.contentH),
+            polys,
+            styleOf: (node) => (parts[partOf.get(node.id)].layout.styleOf ?? defaultStyleOf)(node),
+            containers: [...boxes, ...innerBoxes]
+        };
+        return { layout: composed, bounds: boundsOf(composed, Array.from(partial.values())), partial };
+    };
+    /*  lay out a single containment level  */
+    const layoutLevel = async (container, type) => {
+        const members = container === null ?
+            nodes.filter((node) => parentOf(node) === undefined) :
+            containment.childrenOf.get(container.id) ?? [];
+        const memberIds = new Set(members.map((member) => member.id));
+        /*  the member of this level a node of its subtree belongs to  */
+        const topOf = (id) => {
+            for (let cur = id; cur !== undefined; cur = containment.parentOf.get(cur))
+                if (memberIds.has(cur))
+                    return cur;
+            return undefined;
+        };
+        /*  lay out the member containers first  */
+        const inner = new Map();
+        for (const member of members)
+            if (isContainer(member))
+                inner.set(member.id, await layoutLevel(member, containerTypeOf(member) ?? type));
+        /*  the vertical offset (from the placeholder center) of the
+            port an edge crossing the boundary of a member container
+            attaches at: the position of its inner gate  */
+        const portOffset = (member, y) => {
+            const { bounds } = inner.get(member.id);
+            return (y - bounds.minY) + containerHead(member) + pad - sizeOf(member, bounds).h / 2;
+        };
+        /*  derive the edges of this level: the edges lifted to it (both
+            endpoints in the subtree, but not both inside the same member
+            container), and, for a gated diagram type, the edges crossing
+            its own boundary, continued from a gate node. The name of an
+            edge is placed at its lifted level, its arity at the level
+            holding its arrow head  */
+        const gates = new Map();
+        const levelNodes = new Map(members.map((member) => [member.id, member]));
+        const levelEdges = [];
+        const origin = [];
+        const fixedPort = new Map();
+        const continues = (id, edge) => inner.get(id)?.partial.has(edge) ?? false;
+        graph.edges.forEach((edge, i) => {
+            const ts = topOf(edge.source);
+            const tt = topOf(edge.target);
+            if (ts === undefined && tt === undefined)
+                return;
+            if (ts !== undefined && tt !== undefined && ts === tt && inner.has(ts) && edge.source !== ts)
+                return;
+            let source;
+            let target;
+            if (ts === undefined || tt === undefined) {
+                if (!types[type].gated)
+                    return;
+                const gate = gateId(i, ts === undefined ? "in" : "out");
+                gates.set(gate, ts === undefined ? "in" : "out");
+                levelNodes.set(gate, { id: gate, name: "", attrs: [] });
+                source = ts ?? gate;
+                target = tt ?? gate;
+            }
+            else {
+                source = ts;
+                target = tt;
+            }
+            const li = levelEdges.length;
+            levelEdges.push({
+                source,
+                target,
+                name: ts !== undefined && tt !== undefined ? edge.name : undefined,
+                arity: tt !== undefined && !continues(tt, i) ? edge.arity : undefined
+            });
+            origin.push(i);
+            if (continues(source, i))
+                fixedPort.set(`${li}:s`, portOffset(levelNodes.get(source), inner.get(source).partial.get(i).at(-1)[1]));
+            if (continues(target, i))
+                fixedPort.set(`${li}:t`, portOffset(levelNodes.get(target), inner.get(target).partial.get(i)[0][1]));
+        });
+        /*  lay out the level with the member containers as placeholders  */
+        const fixedSize = new Map();
+        for (const [id, level] of inner)
+            fixedSize.set(id, sizeOf(levelNodes.get(id), level.bounds));
+        for (const gate of gates.keys())
+            fixedSize.set(gate, { w: 0, h: 0 });
+        const layout = await types[type].render({ nodes: levelNodes, edges: levelEdges }, config, {
+            fixedSize,
+            fixedPort: (edge, role) => fixedPort.get(`${edge}:${role}`),
+            gates
+        });
+        return composeLevel(layout, inner, levelEdges, origin, gates, type);
+    };
+    return (await layoutLevel(null, type)).layout;
+};

package/dst/gradia-api-render-edge.d.ts

@@ -5,7 +5,7 @@ export type Side = "e" | "w" | "n";
 export declare const assignPorts: (edges: Edge[], sides: {
     s: Side;
     t: Side;
-}[], cx: (id: string) => number, cy: (id: string) => number, boxW: Map<string, number>, boxH: Map<string, number>, portGap: number, approachY?: (edge: number) => number | undefined) => Map<string, {
+}[], cx: (id: string) => number, cy: (id: string) => number, boxW: Map<string, number>, boxH: Map<string, number>, portGap: number, approachY?: (edge: number) => number | undefined, fixedY?: (edge: number, role: "s" | "t") => number | undefined) => Map<string, {
     x: number;
     y: number;
 }>;

package/dst/gradia-api-render-edge.js

@@ -28,8 +28,12 @@ export const simplifyPoly = (pts) => {
     by the vertical position the edge approaches from (the approachY
     override where given, the opposite endpoint center otherwise) and
     separated by at most portGap (less, if the node box is too small
-    to hold them all)  */
-export const assignPorts = (edges, sides, cx, cy, boxW, boxH, portGap, approachY) => {
+    to hold them all). A port with a fixed vertical offset from the
+    box center (fixedY, the edge ends attaching to a container box at
+    the position of the inner gate node) is placed exactly there and
+    the distributed ports of the same side are dealt into the gaps
+    around it  */
+export const assignPorts = (edges, sides, cx, cy, boxW, boxH, portGap, approachY, fixedY) => {
     /*  group the edge endpoints by the node side they attach to  */
     const portGroups = new Map();
     const addPort = (key, edge, role) => {
@@ -63,15 +67,59 @@ export const assignPorts = (edges, sides, cx, cy, boxW, boxH, portGap, approachY
             });
             continue;
         }
+        const px = cx(id) + (side === "e" ? +1 : -1) * boxW.get(id) / 2;
+        /*  place the fixed ports at their given offsets  */
+        const fixedOf = (p) => fixedY?.(p.edge, p.role);
+        const taken = [];
+        for (const p of group.filter((p) => fixedOf(p) !== undefined)) {
+            const py = cy(id) + fixedOf(p);
+            portPos.set(`${p.edge}:${p.role}`, { x: px, y: py });
+            taken.push(py);
+        }
+        taken.sort((a, b) => a - b);
+        /*  spread the remaining ports, ordered by their approach and
+            at the spacing leaving room for the fixed ports, too (with
+            no fixed port, simply centered on the box)  */
+        const free = group.filter((p) => fixedOf(p) === undefined);
         const otherOf = (p) => p.role === "s" ? edges[p.edge].target : edges[p.edge].source;
         const keyOf = (p) => approachY?.(p.edge) ?? cy(otherOf(p));
-        group.sort((a, b) => (keyOf(a) - keyOf(b)) || (a.edge - b.edge));
-        const spacing = Math.min(portGap, (boxH.get(id) - PORT_PAD) / group.length);
-        group.forEach((p, idx) => {
-            portPos.set(`${p.edge}:${p.role}`, {
-                x: cx(id) + (side === "e" ? +1 : -1) * boxW.get(id) / 2,
-                y: cy(id) + (idx - (group.length - 1) / 2) * spacing
-            });
+        free.sort((a, b) => (keyOf(a) - keyOf(b)) || (a.edge - b.edge));
+        const n = free.length + taken.length;
+        const spacing = Math.min(portGap, (boxH.get(id) - PORT_PAD) / n);
+        const place = (p, py) => portPos.set(`${p.edge}:${p.role}`, { x: px, y: py });
+        if (taken.length === 0) {
+            free.forEach((p, idx) => place(p, cy(id) + (idx - (n - 1) / 2) * spacing));
+            continue;
+        }
+        /*  deal the free ports into the gaps between the fixed ports
+            (each into the gap its approach falls into, overflowing into
+            the neighboring gaps once a gap holds as many ports as fit
+            into it at the spacing) and place the ports of every gap at
+            their slots of the even distribution of all ports, shifted
+            into the gap as far as needed (and squeezed if not fitting)  */
+        const lo = cy(id) - (boxH.get(id) - PORT_PAD) / 2 + spacing / 2;
+        const hi = cy(id) + (boxH.get(id) - PORT_PAD) / 2 - spacing / 2;
+        const walls = [lo - spacing, ...taken, hi + spacing];
+        const gapOf = (p) => taken.filter((ty) => ty < keyOf(p)).length;
+        const gaps = walls.slice(1).map((wall, j) => ({
+            lo: Math.max(lo, walls[j] + spacing),
+            hi: Math.min(hi, wall - spacing),
+            ports: free.filter((p) => gapOf(p) === j)
+        }));
+        const capOf = (gap) => gap.hi < gap.lo ? 0 : Math.floor((gap.hi - gap.lo) / spacing) + 1;
+        for (let j = 0; j < gaps.length - 1; j++)
+            while (gaps[j].ports.length > capOf(gaps[j]))
+                gaps[j + 1].ports.unshift(gaps[j].ports.pop());
+        for (let j = gaps.length - 1; j > 0; j--)
+            while (gaps[j].ports.length > capOf(gaps[j]))
+                gaps[j - 1].ports.push(gaps[j].ports.shift());
+        let k = 0;
+        gaps.forEach((gap, j) => {
+            const r = gap.ports.length;
+            const step = r > 1 ? Math.min(spacing, Math.max(gap.hi - gap.lo, 0) / (r - 1)) : spacing;
+            const first = Math.min(Math.max(cy(id) + (k + j - (n - 1) / 2) * spacing, gap.lo), gap.hi - (r - 1) * step);
+            gap.ports.forEach((p, i) => place(p, first + i * step));
+            k += r;
         });
     }
     return portPos;
@@ -79,6 +127,12 @@ export const assignPorts = (edges, sides, cx, cy, boxW, boxH, portGap, approachY
 /*  the minimum cross-axis distance between the track-following segments
     of two edges sharing a track, keeping their rounded corners apart  */
 const TRACK_CLEARANCE = 24;
+/*  the cross-axis positions of the stubs of a track user reaching the
+    near side of the channel/gutter (its entering segment, or its
+    exiting one if mirrored, or both if hairpin, or none if mirrored
+    hairpin) and the far side  */
+const nears = (u) => u.hairpin ? (u.mirror ? [] : [u.posIn, u.posOut]) : [u.mirror ? u.posOut : u.posIn];
+const fars = (u) => u.hairpin ? (u.mirror ? [u.posIn, u.posOut] : []) : [u.mirror ? u.posIn : u.posOut];
 /*  the number of crossings caused by placing user a on a nearer track
     than user b: the far-side stubs of a (its exiting segment, or its
     entering one if mirrored) cross the track-following segment of b,
@@ -86,26 +140,33 @@ const TRACK_CLEARANCE = 24;
     the end of a segment counts too, as it would overlap a corner)  */
 const trackCrossings = (a, b) => {
     const within = (u, pos) => pos >= Math.min(u.posIn, u.posOut) && pos <= Math.max(u.posIn, u.posOut);
-    const nears = (u) => u.hairpin ? [u.posIn, u.posOut] : [u.mirror ? u.posOut : u.posIn];
-    const fars = (u) => u.hairpin ? [] : [u.mirror ? u.posIn : u.posOut];
     return fars(a).filter((pos) => within(b, pos)).length +
         nears(b).filter((pos) => within(a, pos)).length;
 };
+/*  the number of collinear overlaps caused by placing user a on a
+    nearer track than user b: a far-side stub of a and a near-side stub
+    of b at the very same cross-axis position run on top of each other
+    between the two tracks (unlike a crossing, which is still readable
+    through its hop, an overlap merges the two edges visually)  */
+const trackOverlaps = (a, b) => fars(a).filter((pos) => nears(b).includes(pos)).length;
 /*  the maximum number of users for which the crossing-minimal track
     order is determined exactly (the effort doubles with every user)  */
 const TRACK_EXACT_MAX = 14;
 /*  reorder the seeded track users to the order causing the fewest
-    crossings, with ties broken toward the seed order: for small user
-    sets exactly, by a dynamic programming over the user subsets (the
-    linear ordering problem), for larger ones by a local search moving
-    single users while this reduces the crossings  */
+    overlaps and then the fewest crossings, with ties broken toward the
+    seed order: for small user sets exactly, by a dynamic programming
+    over the user subsets (the linear ordering problem), for larger
+    ones by a local search moving blocks of adjacent users while this
+    reduces the overlaps/crossings  */
 const minimizeCrossings = (seed) => {
     const n = seed.length;
     if (n < 2)
         return seed;
-    /*  the weighted cost of placing seed user i before seed user j:
-        the crossings dominate, a seed order inversion breaks ties  */
-    const cost = seed.map((a, i) => seed.map((b, j) => trackCrossings(a, b) * n * n + (i > j ? 1 : 0)));
+    /*  the weighted cost of placing seed user i before seed user j: the
+        overlaps dominate (one outweighs all crossings possible among the
+        users, at most three per pair), then the crossings, and finally
+        a seed order inversion breaks ties  */
+    const cost = seed.map((a, i) => seed.map((b, j) => (trackOverlaps(a, b) * 2 * n * n + trackCrossings(a, b)) * n * n + (i > j ? 1 : 0)));
     let order;
     if (n <= TRACK_EXACT_MAX) {
         const best = new Float64Array(1 << n).fill(Infinity);
@@ -131,28 +192,36 @@ const minimizeCrossings = (seed) => {
             order.unshift(last[s]);
     }
     else {
-        const totalOf = (list) => {
-            let total = 0;
-            for (let i = 0; i < list.length; i++)
-                for (let j = i + 1; j < list.length; j++)
-                    total += cost[list[i]][list[j]];
-            return total;
-        };
+        /*  move a block of adjacent users over the run of users behind
+            or ahead of it, as soon as this reduces the cost (which only
+            the pairs between the block and the run passed contribute
+            to, so the cost change is accumulated while extending the
+            run), until no such move remains (a single-user move is
+            the block move of length one, while the longer blocks let
+            groups of users pass an obstacle which none of its users
+            could pass on its own)  */
         order = seed.map((_, i) => i);
-        let total = totalOf(order);
         for (let improved = true; improved;) {
             improved = false;
-            for (let i = 0; i < n && !improved; i++) {
-                for (let j = 0; j < n && !improved; j++) {
-                    if (i === j)
-                        continue;
-                    const moved = [...order];
-                    moved.splice(j, 0, ...moved.splice(i, 1));
-                    const t = totalOf(moved);
-                    if (t < total) {
-                        order = moved;
-                        total = t;
-                        improved = true;
+            for (let len = 1; len < n && !improved; len++) {
+                for (let i = 0; i + len <= n && !improved; i++) {
+                    let delta = 0;
+                    for (let k = i + len; k < n && !improved; k++) {
+                        for (let b = i; b < i + len; b++)
+                            delta += cost[order[k]][order[b]] - cost[order[b]][order[k]];
+                        if (delta < 0) {
+                            order.splice(k - len + 1, 0, ...order.splice(i, len));
+                            improved = true;
+                        }
+                    }
+                    delta = 0;
+                    for (let k = i - 1; k >= 0 && !improved; k--) {
+                        for (let b = i; b < i + len; b++)
+                            delta += cost[order[b]][order[k]] - cost[order[k]][order[b]];
+                        if (delta < 0) {
+                            order.splice(k, 0, ...order.splice(i, len));
+                            improved = true;
+                        }
                     }
                 }
             }

package/dst/gradia-api-render-group.d.ts

@@ -1,10 +1,11 @@
 import { Node, Graph } from "./gradia-api-model.js";
 import { Config } from "./gradia-api-config.js";
-import { Layout } from "./gradia-api-render-svg.js";
+import { Layout } from "./gradia-api-render-base.js";
+import { Containment } from "./gradia-api-render-container.js";
 export declare const groupOf: (node: Node) => string | undefined;
 export interface GroupPart {
     name: string;
     graph: Graph;
 }
-export declare const partitionGroups: (graph: Graph) => GroupPart[] | null;
+export declare const partitionGroups: (graph: Graph, containment: Containment) => GroupPart[] | null;
 export declare const composeGroups: (parts: GroupPart[], layouts: Layout[], config: Config) => Layout;

package/dst/gradia-api-render-group.js

@@ -4,22 +4,31 @@
 **  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
 */
 import { FS_GROUP, textWidth } from "./gradia-api-render-base.js";
+import { defaultStyleOf } from "./gradia-api-render-node.js";
+import { rootOf, boundsOf } from "./gradia-api-render-container.js";
 /*  rendering geometry constants  */
 const GROUP_HEAD = 34; /*  extra top space for the group tag  */
 /*  the special "group" annotation (assigning a node to a named group)  */
 export const groupOf = (node) => node.attrs.findLast((attr) => attr.key === "group")?.val;
 /*  partition the graph into its named groups (in order of first
     appearance), implying "group: default" for the nodes without one,
-    or return null when no node uses a group at all. Edges have to
-    stay within a single group, so reject any group-crossing edge  */
-export const partitionGroups = (graph) => {
+    or return null when no node uses a group at all. A nested node
+    belongs to the group of its outermost container, so reject any
+    deviating group of its own. Edges have to stay within a single
+    group, so reject any group-crossing edge  */
+export const partitionGroups = (graph, containment) => {
     const nodes = Array.from(graph.nodes.values());
     if (!nodes.some((node) => groupOf(node) !== undefined))
         return null;
     const parts = new Map();
     const nameOf = new Map();
     for (const node of nodes) {
-        const name = groupOf(node) ?? "default";
+        const root = rootOf(containment, node.id);
+        const name = groupOf(graph.nodes.get(root)) ?? "default";
+        const own = groupOf(node);
+        if (own !== undefined && own !== name)
+            throw new Error(`node "${node.id}" cannot be a member of group "${own}", ` +
+                `as its container "${root}" is a member of group "${name}"`);
         nameOf.set(node.id, name);
         let part = parts.get(name);
         if (part === undefined) {
@@ -38,26 +47,6 @@ export const partitionGroups = (graph) => {
     }
     return Array.from(parts.entries()).map(([name, subgraph]) => ({ name, graph: subgraph }));
 };
-/*  determine the bounding box of a laid out group (nodes and edges)  */
-const boundsOf = (layout) => {
-    const { nodes, cx, cy, boxW, boxH, polys } = layout;
-    let [minX, minY, maxX, maxY] = [Infinity, Infinity, -Infinity, -Infinity];
-    for (const node of nodes) {
-        minX = Math.min(minX, cx(node.id) - boxW.get(node.id) / 2);
-        minY = Math.min(minY, cy(node.id) - boxH.get(node.id) / 2);
-        maxX = Math.max(maxX, cx(node.id) + boxW.get(node.id) / 2);
-        maxY = Math.max(maxY, cy(node.id) + boxH.get(node.id) / 2);
-    }
-    for (const poly of polys) {
-        for (const [px, py] of poly) {
-            minX = Math.min(minX, px);
-            minY = Math.min(minY, py);
-            maxX = Math.max(maxX, px);
-            maxY = Math.max(maxY, py);
-        }
-    }
-    return { minX, minY, maxX, maxY };
-};
 /*  compose the per-group layouts into a single layout: the groups are
     stacked vertically, each one shifted into its surrounding group box
     (a node id is unique across the groups, as every node is a member
@@ -98,8 +87,8 @@ export const composeGroups = (parts, layouts, config) => {
         boxH: merge((layout) => layout.boxH),
         contentH: merge((layout) => layout.contentH),
         polys: layouts.flatMap((layout, i) => layout.polys.map((poly) => poly.map(([px, py]) => [px + dxs[i], py + dys[i]]))),
-        styleOf: layouts.every((layout) => layout.styleOf !== undefined) ?
-            (node) => layouts[groupIdxOf(node.id)].styleOf(node) : undefined,
-        groups
+        styleOf: (node) => (layouts[groupIdxOf(node.id)].styleOf ?? defaultStyleOf)(node),
+        groups,
+        containers: layouts.flatMap((layout, i) => (layout.containers ?? []).map((c) => ({ ...c, x: c.x + dxs[i], y: c.y + dys[i] })))
     };
 };

package/dst/gradia-api-render-node.d.ts

@@ -4,6 +4,11 @@ import { NodeStyle } from "./gradia-api-render-base.js";
 export declare const isPrimary: (node: Node) => boolean;
 export declare const defaultStyleOf: (node: Node) => NodeStyle;
 export declare const typeOf: (node: Node) => string | undefined;
+export declare const parentOf: (node: Node) => string | undefined;
+export declare const containerTypeOf: (node: Node) => string | undefined;
+export declare const HEAD_H = 34;
+export declare const HEAD_T = 20;
+export declare const containerHead: (node: Node) => number;
 export declare const attrsOfNode: (node: Node) => Attr[];
 export declare const urlOf: (node: Node) => string | undefined;
 export declare const PAD_W = 18;
@@ -20,7 +25,10 @@ export interface NodeLines {
     attrs: string[];
 }
 export declare const linesOfNode: (node: Node, config: Config) => NodeLines;
-export declare const measureNodes: (nodes: Node[], config: Config, scaleOf: (node: Node) => number) => {
+export declare const measureNodes: (nodes: Node[], config: Config, scaleOf: (node: Node) => number, fixed?: Map<string, {
+    w: number;
+    h: number;
+}>) => {
     boxW: Map<string, number>;
     boxH: Map<string, number>;
     contentH: Map<string, number>;