@rse/gradia 1.1.8 → 1.2.0

package/dst/gradia-api-type-graph.js

@@ -19,8 +19,8 @@ const GUT_H0 = 20; /*  height of an edge-less inter-row gutter     */
 const GUT_H1 = 24; /*  height of a one-edge inter-row gutter       */
 const GUT_PAD = 12; /*  cross-axis padding inside a gutter          */
 const GUT_LBL = 22; /*  clearance above/below a label in a gutter   */
-const LOOP_GAP = 24; /*  detour of a self-loop beside its node box   */
 const LOOP_TOP = 52; /*  detour of a self-loop above its node box    */
+/*  node nudging constants  */
 const NUDGE_GAP = 24; /*  min port distance of a nudged node from its gutter tracks  */
 const NUDGE_PASSES = 3; /*  max number of node nudging passes                          */
 /*  snap raw node positions onto a discrete grid by clustering the
@@ -136,35 +136,150 @@ const refineRows = (nodes, edges, col, row) => {
         }
     }
 };
+/*  compact the rows of the grid, as the layered layout and the column
+    folding leave many sparsely occupied rows behind: first lift every
+    edge-less node (bound by no ordering constraint at all) into the
+    topmost free cell of its column, then merge every row into the row
+    above it as long as no column is occupied in both (which keeps the
+    vertical order of all nodes and the row alignment of the nodes
+    sharing a row), and finally renumber the rows densely  */
+const compactRows = (nodes, edges, col, row) => {
+    const cells = new Set();
+    for (const node of nodes)
+        cells.add(`${col.get(node.id)}:${row.get(node.id)}`);
+    /*  lift every edge-less node into the topmost free cell of its column  */
+    const linked = new Set();
+    for (const edge of edges) {
+        linked.add(edge.source);
+        linked.add(edge.target);
+    }
+    const isolated = nodes.filter((node) => !linked.has(node.id))
+        .sort((a, b) => row.get(a.id) - row.get(b.id));
+    for (const node of isolated) {
+        const c = col.get(node.id);
+        for (let r = 0; r < row.get(node.id); r++)
+            if (!cells.has(`${c}:${r}`)) {
+                cells.delete(`${c}:${row.get(node.id)}`);
+                cells.add(`${c}:${r}`);
+                row.set(node.id, r);
+                break;
+            }
+    }
+    /*  merge every row into the row above it as long as no column is
+        occupied in both, then renumber the rows densely  */
+    const byRow = new Map();
+    for (const node of nodes)
+        pushTo(byRow, row.get(node.id), node);
+    const rowMax = Math.max(...byRow.keys());
+    const rowIdx = new Map();
+    let idx = -1;
+    let occupied = new Set();
+    for (let r = 0; r <= rowMax; r++) {
+        const members = byRow.get(r) ?? [];
+        if (idx < 0 || members.some((node) => occupied.has(col.get(node.id)))) {
+            idx++;
+            occupied = new Set();
+        }
+        for (const node of members)
+            occupied.add(col.get(node.id));
+        rowIdx.set(r, idx);
+    }
+    for (const node of nodes)
+        row.set(node.id, rowIdx.get(row.get(node.id)));
+    return idx + 1;
+};
+/*  place the gate nodes of a containment level: the "in" gates into an
+    additional first column and the "out" gates into an additional last
+    column (both reserved for the gates, so the stubs from the container
+    border to the gates never cross a node box), each gate into the row
+    of the node its edge connects to, else into the nearest free row of
+    the gate column, else into a row newly inserted below the wanted one  */
+const placeGates = (gates, edges, col, row, ncols, nrows) => {
+    const ins = Array.from(gates).filter(([, side]) => side === "in").map(([id]) => id);
+    const outs = Array.from(gates).filter(([, side]) => side === "out").map(([id]) => id);
+    if (ins.length > 0) {
+        for (const id of col.keys())
+            col.set(id, col.get(id) + 1);
+        ncols++;
+    }
+    if (outs.length > 0)
+        ncols++;
+    const place = (ids, c) => {
+        /*  the gates are placed in the order of their wanted rows, so
+            the ones displaced into other rows never cross each other
+            (the wanted row is the current row of the connected node,
+            re-read per gate, as an inserted row shifts the nodes below)  */
+        const otherOf = new Map();
+        for (const id of ids) {
+            const edge = edges.find((edge) => edge.source === id || edge.target === id);
+            otherOf.set(id, edge.source === id ? edge.target : edge.source);
+        }
+        const wantOf = (id) => row.get(otherOf.get(id));
+        ids.sort((a, b) => wantOf(a) - wantOf(b));
+        const placed = [];
+        for (const id of ids) {
+            const want = wantOf(id);
+            const taken = (r) => placed.some((other) => row.get(other) === r);
+            let r;
+            for (let d = 0; r === undefined && d < nrows; d++) {
+                if (want + d < nrows && !taken(want + d))
+                    r = want + d;
+                else if (want - d >= 0 && !taken(want - d))
+                    r = want - d;
+            }
+            if (r === undefined) {
+                for (const [other, otherRow] of row)
+                    if (otherRow > want)
+                        row.set(other, otherRow + 1);
+                nrows++;
+                r = want + 1;
+            }
+            col.set(id, c);
+            row.set(id, r);
+            placed.push(id);
+        }
+    };
+    place(ins, 0);
+    place(outs, ncols - 1);
+    return { ncols, nrows };
+};
 /*  plan the coarse route of every edge: which inter-column channels
-    and inter-row gutters it occupies (based on grid indices only)  */
-const planRoutes = (edges, col, row) => {
-    const plans = edges.map((edge) => {
-        /*  a self-loop is routed around its own node box and uses no channel  */
-        if (edge.source === edge.target)
-            return { chans: [], guts: [] };
+    and inter-row gutters it occupies (based on the grid indices and
+    the attachment sides only): the source stub reaches the channel
+    beside its attachment side, the target stub the channel beside
+    its one, and, if those differ, the gutter next to the target row
+    connects them  */
+const planRoutes = (edges, col, row, sides) => {
+    const flag = (from, to) => ({ mirror: from === "r", hairpin: from === to });
+    const plans = edges.map((edge, i) => {
+        /*  a self-loop detours as a hairpin through the channel beside
+            its own node box (in from the near side and out on it again)  */
         const sc = col.get(edge.source);
+        if (edge.source === edge.target)
+            return { chans: [sc], guts: [], flags: [flag("l", "l")] };
         const tc = col.get(edge.target);
         const sr = row.get(edge.source);
         const tr = row.get(edge.target);
-        let chans;
-        let guts = [];
-        if (sc === tc)
-            chans = [sc];
-        else if (Math.abs(sc - tc) === 1)
-            chans = [Math.min(sc, tc)];
-        else {
-            chans = [sc < tc ? sc : sc - 1, sc < tc ? tc - 1 : tc];
-            guts = [tr > sr ? tr - 1 : tr];
-        }
-        return { chans, guts };
+        const sChan = sides[i].s === "e" ? sc : sc - 1;
+        const tChan = sides[i].t === "w" ? tc - 1 : tc;
+        const sFrom = sides[i].s === "e" ? "l" : "r";
+        const tTo = sides[i].t === "w" ? "r" : "l";
+        if (sChan === tChan)
+            return { chans: [sChan], guts: [], flags: [flag(sFrom, tTo)] };
+        const dir = tChan > sChan ? "r" : "l";
+        return {
+            chans: [sChan, tChan],
+            guts: [tr > sr ? tr - 1 : tr],
+            flags: [flag(sFrom, dir), flag(dir === "r" ? "l" : "r", tTo)]
+        };
     });
     /*  count the edges occupying each channel and gutter and determine
         the room the edge labels need there: a name is placed in the
         single channel of its edge, or, for a two-channel edge, along
         its gutter run, costing one label line there; an arity is always
         placed in the channel through which its edge finally approaches
-        the target node, set back from the arrow head  */
+        the target node, set back from the arrow head (the labels of a
+        self-loop land on its detour above the box and need no room)  */
     const chanCnt = new Map();
     const gutCnt = new Map();
     const chanLbl = new Map();
@@ -175,7 +290,9 @@ const planRoutes = (edges, col, row) => {
             chanCnt.set(c, (chanCnt.get(c) ?? 0) + 1);
         for (const g of plan.guts)
             gutCnt.set(g, (gutCnt.get(g) ?? 0) + 1);
-        const { name, arity } = edges[i];
+        const { name, arity, source, target } = edges[i];
+        if (source === target)
+            return;
         if (name !== undefined && plan.chans.length === 1)
             chanNeed(plan.chans[0], textWidth(name, FS_EDGE) + 2 * CHAN_LBL);
         else if (name !== undefined && plan.guts.length > 0)
@@ -183,22 +300,34 @@ const planRoutes = (edges, col, row) => {
         if (arity !== undefined && plan.chans.length > 0)
             chanNeed(plan.chans[plan.chans.length - 1], ARITY_OFF + textWidth(arity, FS_ARITY) + CHAN_LBL);
     });
-    return { plans, chanCnt, gutCnt, chanLbl, gutLbl };
+    /*  count the self-loops of every node, as their detours stack up
+        above its box and have to fit into the gutter above its row
+        (the demand of a gutter is the deepest stack of any node below it)  */
+    const loopCnt = new Map();
+    const gutLoop = new Map();
+    for (const edge of edges.filter((edge) => edge.source === edge.target)) {
+        const cnt = (loopCnt.get(edge.source) ?? 0) + 1;
+        loopCnt.set(edge.source, cnt);
+        const g = row.get(edge.source) - 1;
+        gutLoop.set(g, Math.max(gutLoop.get(g) ?? 0, cnt));
+    }
+    return { plans, chanCnt, gutCnt, chanLbl, gutLbl, gutLoop };
 };
 /*  determine grid cell sizes and final node center positions, with
     channel widths and gutter heights sized by actual edge usage to
     keep the overall layout compact  */
-const computeGrid = (nodes, col, row, boxW, boxH, ncols, nrows, chanCnt, gutCnt, chanLbl, gutLbl, config) => {
+const computeGrid = (nodes, col, row, boxW, boxH, ncols, nrows, chanCnt, gutCnt, chanLbl, gutLbl, gutLoop, config) => {
     const colWidth = Array.from({ length: ncols }, () => 0);
     const rowHeight = Array.from({ length: nrows }, () => 0);
     for (const node of nodes) {
         colWidth[col.get(node.id)] = Math.max(colWidth[col.get(node.id)], boxW.get(node.id));
         rowHeight[row.get(node.id)] = Math.max(rowHeight[row.get(node.id)], boxH.get(node.id));
     }
-    /*  size the channels and gutters by their actual edge usage, each
-        additionally grown to hold the edge labels landing inside it (a
-        channel by its widest label demand, a gutter by one line per
-        label) and floored by the configured minimum width/height  */
+    /*  size the channels and gutters by their actual edge usage, grown
+        to hold the edge labels landing inside (a channel by its widest
+        label demand, a gutter by one line per label) and the self-loop
+        detours rising into a gutter from the row below, and floored by
+        the configured minimum width/height  */
     const chanW = Array.from({ length: ncols }, (_, c) => {
         const cnt = chanCnt.get(c) ?? 0;
         return Math.min(config["graph-channel-width-max"], Math.max(config["graph-channel-width-min"], cnt === 0 ? CHAN_W0 : CHAN_W1 + (cnt - 1) * config["size-edge-track-gap"], chanLbl.get(c) ?? 0));
@@ -206,7 +335,8 @@ const computeGrid = (nodes, col, row, boxW, boxH, ncols, nrows, chanCnt, gutCnt,
     const gutH = Array.from({ length: nrows }, (_, g) => {
         const cnt = gutCnt.get(g) ?? 0;
         const lbl = gutLbl.get(g) ?? 0;
-        return Math.min(config["graph-gutter-height-max"], Math.max(config["graph-gutter-height-min"], cnt === 0 ? GUT_H0 : GUT_H1 + (cnt - 1) * config["size-edge-track-gap"], lbl > 0 ? GUT_H1 + lbl * GUT_LBL : 0));
+        const loop = gutLoop.get(g) ?? 0;
+        return Math.min(config["graph-gutter-height-max"], Math.max(config["graph-gutter-height-min"], cnt === 0 ? GUT_H0 : GUT_H1 + (cnt - 1) * config["size-edge-track-gap"], lbl > 0 ? GUT_H1 + lbl * GUT_LBL : 0, loop > 0 ? LOOP_TOP + (loop - 1) * config["size-edge-track-gap"] + GUT_PAD : 0));
     });
     /*  derive the column and row center positions  */
     const colCX = [];
@@ -229,26 +359,26 @@ const computeGrid = (nodes, col, row, boxW, boxH, ncols, nrows, chanCnt, gutCnt,
     channel mirrored from the right side; the gutters use the very same
     scheme, just transposed: edges dropping in from above enter from the
     near side, edges rising from below are the mirrored users)  */
-const assignTrackCoords = (edges, plans, col, portPos, grid, config) => {
+const assignTrackCoords = (edges, plans, portPos, grid, config) => {
     const { colWidth, rowHeight, chanW, gutH, colCX, rowCY } = grid;
     const gutBase = (g) => rowCY[g] + rowHeight[g] / 2 + gutH[g] / 2;
-    /*  assign the vertical tracks within the inter-column channels  */
+    /*  assign the vertical tracks within the inter-column channels (the
+        leg of a self-loop spans up to its detour above the box)  */
     const chanUsers = new Map();
     edges.forEach((edge, i) => {
-        const { chans, guts } = plans[i];
+        const { chans, guts, flags } = plans[i];
         if (chans.length === 0)
             return;
-        const [sc, tc] = [col.get(edge.source), col.get(edge.target)];
-        const mirror = tc < sc;
-        const hairpin = tc === sc;
         const sp = portPos.get(`${i}:s`);
         const tp = portPos.get(`${i}:t`);
-        if (chans.length === 1)
-            pushTo(chanUsers, chans[0], { edge: i, posIn: sp.y, posOut: tp.y, mirror, hairpin });
+        if (edge.source === edge.target)
+            pushTo(chanUsers, chans[0], { edge: i, posIn: sp.y, posOut: tp.y - LOOP_TOP, ...flags[0] });
+        else if (chans.length === 1)
+            pushTo(chanUsers, chans[0], { edge: i, posIn: sp.y, posOut: tp.y, ...flags[0] });
         else {
             const gy = gutBase(guts[0]);
-            pushTo(chanUsers, chans[0], { edge: i, posIn: sp.y, posOut: gy, mirror });
-            pushTo(chanUsers, chans[1], { edge: i, posIn: gy, posOut: tp.y, mirror });
+            pushTo(chanUsers, chans[0], { edge: i, posIn: sp.y, posOut: gy, ...flags[0] });
+            pushTo(chanUsers, chans[1], { edge: i, posIn: gy, posOut: tp.y, ...flags[1] });
         }
     });
     const chanOff = new Map();
@@ -280,31 +410,33 @@ const assignTrackCoords = (edges, plans, col, portPos, grid, config) => {
 };
 /*  route every edge as an orthogonal polyline through the channels
     between columns and the gutters between rows  */
-const routePolys = (edges, plans, col, portPos, boxW, boxH, cx, cy, chanX, gutY, config) => {
-    const loopUse = new Map();
+const routePolys = (edges, plans, portPos, boxH, cy, chanX, gutY) => {
+    /*  the innermost channel track among the self-loops of each node  */
+    const loopX = new Map();
+    edges.forEach((edge, i) => {
+        if (edge.source === edge.target)
+            loopX.set(edge.source, Math.min(loopX.get(edge.source) ?? Infinity, chanX(plans[i].chans[0], i)));
+    });
     return edges.map((edge, i) => {
-        const sc = col.get(edge.source);
-        const tc = col.get(edge.target);
         const sp = portPos.get(`${i}:s`);
         const tp = portPos.get(`${i}:t`);
-        const { chans, guts } = plans[i];
+        const { chans, guts, flags } = plans[i];
         let pts;
         if (edge.source === edge.target) {
             /*  route the self-loop counter-clockwise around the top-right
-                box corner: out on the east side, up beside the box, back
-                left above it, and down into the north side again (the
-                detour above the box is the wider one, as its final
-                descent has to stay readable behind the arrow head)  */
-            const k = loopUse.get(edge.source) ?? 0;
-            loopUse.set(edge.source, k + 1);
-            const off = k * config["size-edge-track-gap"];
-            const ox = cx(edge.source) + boxW.get(edge.source) / 2 + LOOP_GAP + off;
-            const oy = cy(edge.source) - boxH.get(edge.source) / 2 - LOOP_TOP - off;
+                box corner: out on the east side, up along its channel
+                track, back left above the box, and down into the north
+                side again (the detour above the box is the wider one, as
+                its final descent has to stay readable behind the arrow
+                head, and grows with the track distance from the innermost
+                loop of the node, so the nested loops stay apart)  */
+            const ox = chanX(chans[0], i);
+            const oy = cy(edge.source) - boxH.get(edge.source) / 2 - LOOP_TOP - (ox - loopX.get(edge.source));
             pts = [[sp.x, sp.y], [ox, sp.y], [ox, oy], [tp.x, oy], [tp.x, tp.y]];
         }
         else if (chans.length === 1) {
             const ch = chanX(chans[0], i);
-            if (Math.abs(sc - tc) === 1 && sp.y === tp.y)
+            if (!flags[0].hairpin && sp.y === tp.y)
                 pts = [[sp.x, sp.y], [tp.x, tp.y]];
             else
                 pts = [[sp.x, sp.y], [ch, sp.y], [ch, tp.y], [tp.x, tp.y]];
@@ -328,13 +460,13 @@ const routePolys = (edges, plans, col, portPos, boxW, boxH, cx, cy, chanX, gutY,
     tracks on top of the moved ports and finally route every edge as an
     orthogonal polyline through the channels between the columns and
     the gutters between the rows  */
-const routeEdges = (edges, plans, col, sides, boxW, boxH, cx, cy, grid, config) => {
-    const portPre = assignPorts(edges, sides, cx, cy, boxW, boxH, config["size-edge-port-gap"]);
-    const trackPre = assignTrackCoords(edges, plans, col, portPre, grid, config);
+const routeEdges = (edges, plans, sides, boxW, boxH, cx, cy, grid, config, level) => {
+    const portPre = assignPorts(edges, sides, cx, cy, boxW, boxH, config["size-edge-port-gap"], undefined, level.fixedPort);
+    const trackPre = assignTrackCoords(edges, plans, portPre, grid, config);
     const portPos = assignPorts(edges, sides, cx, cy, boxW, boxH, config["size-edge-port-gap"], (edge) => plans[edge].guts.length > 0 ?
-        trackPre.gutY(plans[edge].guts[0], edge) : undefined);
-    const { chanX, gutY } = assignTrackCoords(edges, plans, col, portPos, grid, config);
-    const polys = routePolys(edges, plans, col, portPos, boxW, boxH, cx, cy, chanX, gutY, config);
+        trackPre.gutY(plans[edge].guts[0], edge) : undefined, level.fixedPort);
+    const { chanX, gutY } = assignTrackCoords(edges, plans, portPos, grid, config);
+    const polys = routePolys(edges, plans, portPos, boxH, cy, chanX, gutY);
     const hops = computeHops(polys).reduce((sum, segs) => sum + Array.from(segs.values()).reduce((n, xs) => n + xs.length, 0), 0);
     return { portPos, gutY, polys, hops };
 };
@@ -343,18 +475,19 @@ const routeEdges = (edges, plans, col, sides, boxW, boxH, cx, cy, grid, config)
     far as this improves the overall routing (fewer crossings, or as many
     crossings but fewer jogged direct edges): a node may leave its row
     band into an adjacent gutter only as far as no gutter track runs
-    across its column (and it carries no self-loop, detouring above its
-    box), and only as long as its own gutter-routed edges keep
-    approaching it from their gutter side  */
+    across its column and no self-loop detours through it there (a loop
+    rises above the box of its node), and only as long as its own
+    gutter-routed edges keep approaching it from their gutter side  */
 const nudgeNodes = (nodes, edges, plans, col, row, boxH, grid, nrows, dy, route) => {
     const gutterFree = (g, c) => !plans.some((plan) => plan.guts[0] === g
-        && Math.min(...plan.chans) < c && c <= Math.max(...plan.chans));
+        && Math.min(...plan.chans) < c && c <= Math.max(...plan.chans))
+        && !edges.some((edge) => edge.source === edge.target
+            && row.get(edge.source) === g + 1 && col.get(edge.source) === c);
     const shiftRange = (id) => {
         const r = row.get(id);
         const c = col.get(id);
         const slack = (grid.rowHeight[r] - boxH.get(id)) / 2;
-        const loop = edges.some((edge) => edge.source === id && edge.target === id);
-        const up = r > 0 && gutterFree(r - 1, c) && !loop ? grid.gutH[r - 1] - GUT_H0 : 0;
+        const up = r > 0 && gutterFree(r - 1, c) ? grid.gutH[r - 1] - GUT_H0 : 0;
         const down = r < nrows - 1 && gutterFree(r, c) ? grid.gutH[r] - GUT_H0 : 0;
         return [-(slack + up), slack + down];
     };
@@ -366,8 +499,8 @@ const nudgeNodes = (nodes, edges, plans, col, row, boxH, grid, nrows, dy, route)
         const gap = routing.portPos.get(`${i}:${role}`).y - routing.gutY(g, i);
         return row.get(id) > g ? gap >= NUDGE_GAP : gap <= -NUDGE_GAP;
     });
-    const direct = edges.map((edge, i) => plans[i].guts.length === 0
-        && Math.abs(col.get(edge.source) - col.get(edge.target)) === 1
+    const direct = edges.map((edge, i) => plans[i].chans.length === 1
+        && !plans[i].flags[0].hairpin
         && row.get(edge.source) === row.get(edge.target));
     const jogs = (routing) => edges.filter((_, i) => direct[i]
         && routing.portPos.get(`${i}:s`).y !== routing.portPos.get(`${i}:t`).y).length;
@@ -413,95 +546,118 @@ const nudgeNodes = (nodes, edges, plans, col, row, boxH, grid, nrows, dy, route)
     }
     return current;
 };
-/*  lay out a directed graph model  */
-export const render = async (graph, config) => {
+/*  determine the attachment sides of every edge, derived from the
+    column relation of its endpoint nodes (a self-loop leaves on the
+    east side and re-enters on the north side of its own box), except
+    for an edge end attaching at a fixed port of a container box,
+    which always uses the side of the inner gate: the west side
+    when entering the container, the east side when leaving it  */
+const attachSides = (edges, col, level) => edges.map((edge, i) => {
+    const sc = col.get(edge.source);
+    const tc = col.get(edge.target);
+    if (edge.source === edge.target)
+        return { s: "e", t: "n" };
+    const s = level.fixedPort?.(i, "s") !== undefined ? "e" : sc <= tc ? "e" : "w";
+    const t = level.fixedPort?.(i, "t") !== undefined ? "w" : sc < tc ? "w" : "e";
+    return { s, t };
+});
+/*  grow every box whose edge attachments exceed the configured
+    per-side maximum, step-wise by one port separation per
+    additional edge, so the edges keep enough attachment room
+    without a fixed height increase (the fixed-size boxes of a
+    containment level are exempt)  */
+const growBoxes = (nodes, edges, sides, boxH, config, level) => {
+    const portCnt = new Map();
+    edges.forEach((edge, i) => {
+        portCnt.set(`${sides[i].s}:${edge.source}`, (portCnt.get(`${sides[i].s}:${edge.source}`) ?? 0) + 1);
+        portCnt.set(`${sides[i].t}:${edge.target}`, (portCnt.get(`${sides[i].t}:${edge.target}`) ?? 0) + 1);
+    });
+    for (const node of nodes) {
+        if (level.fixedSize?.has(node.id))
+            continue;
+        const cnt = Math.max(portCnt.get(`w:${node.id}`) ?? 0, portCnt.get(`e:${node.id}`) ?? 0);
+        if (cnt > config["graph-node-degree-max"])
+            boxH.set(node.id, boxH.get(node.id) +
+                (cnt - config["graph-node-degree-max"]) * config["size-edge-port-gap"]);
+    }
+};
+/*  lay out a directed graph model (for a containment level: with the
+    container placeholders at their fixed sizes, the edge ends attaching
+    to them at their fixed ports, and the gate nodes on the boundary)  */
+export const render = async (graph, config, level = {}) => {
     const nodes = Array.from(graph.nodes.values());
     const edges = graph.edges;
+    /*  the gate nodes are kept out of the layered layout and the grid
+        refinement, as they are placed into their own columns afterwards  */
+    const gates = level.gates ?? new Map();
+    const real = nodes.filter((node) => !gates.has(node.id));
+    const realEdges = edges.filter((edge) => !gates.has(edge.source) && !gates.has(edge.target));
     /*  determine node box sizes from their textual content
         (all boxes at half height scale, grown by their edge
         attachment needs once the attachment sides are known)  */
-    const { boxW, boxH, contentH } = measureNodes(nodes, config, () => config["size-node-height-scale"] / 2);
+    const { boxW, boxH, contentH } = measureNodes(nodes, config, () => config["size-node-height-scale"] / 2, level.fixedSize);
     /*  determine raw node positions with the AntV Dagre layout  */
-    const layout = new DagreLayout({
-        rankdir: "LR",
-        nodesep: config["graph-node-separation"],
-        ranksep: config["graph-rank-separation"],
-        nodeSize: (node) => node.size
-    });
-    await layout.execute({
-        nodes: nodes.map((node) => ({ id: node.id, size: [boxW.get(node.id), boxH.get(node.id)] })),
-        edges: edges.map((edge, i) => ({ id: `e${i}`, source: edge.source, target: edge.target }))
-    });
     const rawX = new Map();
     const rawY = new Map();
-    layout.forEachNode((node) => {
-        rawX.set(String(node.id), node.x);
-        rawY.set(String(node.id), node.y);
-    });
+    if (real.length > 0) {
+        const layout = new DagreLayout({
+            rankdir: "LR",
+            nodesep: config["graph-node-separation"],
+            ranksep: config["graph-rank-separation"],
+            nodeSize: (node) => node.size
+        });
+        await layout.execute({
+            nodes: real.map((node) => ({ id: node.id, size: [boxW.get(node.id), boxH.get(node.id)] })),
+            edges: realEdges.map((edge, i) => ({ id: `e${i}`, source: edge.source, target: edge.target }))
+        });
+        layout.forEachNode((node) => {
+            rawX.set(String(node.id), node.x);
+            rawY.set(String(node.id), node.y);
+        });
+    }
     /*  snap the raw positions onto the discrete column/row grid  */
-    const { col, row, ncols: gridCols, nrows: gridRows } = snapToGrid(nodes, rawX, rawY);
+    const { col, row, ncols: gridCols, nrows: gridRows } = snapToGrid(real, rawX, rawY);
     /*  refine the row assignment by pulling every node vertically
         toward the median row of its direct neighbors  */
-    refineRows(nodes, edges, col, row);
+    refineRows(real, realEdges, col, row);
     /*  fold the grid columns: constrain the diagram width to at most
         the configured maximum of side-by-side nodes by wrapping excess
         columns into additional row bands below, so wide graphs grow in
         height  */
     const maxCols = Math.max(Math.floor(config["graph-columns-max"]), 1);
     if (gridCols > maxCols) {
-        for (const node of nodes) {
+        for (const node of real) {
             const c = col.get(node.id);
             col.set(node.id, c % maxCols);
             row.set(node.id, row.get(node.id) + Math.floor(c / maxCols) * gridRows);
         }
     }
-    const ncols = Math.min(gridCols, maxCols);
-    /*  drop the grid rows which are completely empty  */
-    const usedRows = Array.from(new Set(nodes.map((node) => row.get(node.id)))).sort((a, b) => a - b);
-    const rowIdx = new Map(usedRows.map((r, idx) => [r, idx]));
-    for (const node of nodes)
-        row.set(node.id, rowIdx.get(row.get(node.id)));
-    const nrows = usedRows.length;
-    /*  plan the coarse channel/gutter route of every edge  */
-    const { plans, chanCnt, gutCnt, chanLbl, gutLbl } = planRoutes(edges, col, row);
-    /*  determine the attachment sides of every edge, derived from the
-        column relation of its endpoint nodes (a self-loop leaves on the
-        east side and re-enters on the north side of its own box)  */
-    const sides = edges.map((edge) => {
-        const sc = col.get(edge.source);
-        const tc = col.get(edge.target);
-        if (edge.source === edge.target)
-            return { s: "e", t: "n" };
-        else if (sc < tc)
-            return { s: "e", t: "w" };
-        else if (sc > tc)
-            return { s: "w", t: "e" };
-        else
-            return { s: "e", t: "e" };
-    });
-    /*  grow every box whose edge attachments exceed the configured
-        per-side maximum, step-wise by one port separation per
-        additional edge, so the edges keep enough attachment room
-        without a fixed height increase  */
-    const portCnt = new Map();
-    edges.forEach((edge, i) => {
-        portCnt.set(`${sides[i].s}:${edge.source}`, (portCnt.get(`${sides[i].s}:${edge.source}`) ?? 0) + 1);
-        portCnt.set(`${sides[i].t}:${edge.target}`, (portCnt.get(`${sides[i].t}:${edge.target}`) ?? 0) + 1);
-    });
-    for (const node of nodes) {
-        const cnt = Math.max(portCnt.get(`w:${node.id}`) ?? 0, portCnt.get(`e:${node.id}`) ?? 0);
-        if (cnt > config["graph-node-degree-max"])
-            boxH.set(node.id, boxH.get(node.id) +
-                (cnt - config["graph-node-degree-max"]) * config["size-edge-port-gap"]);
+    /*  compact the sparsely occupied grid rows into fewer, denser ones,
+        then place the gate nodes into their own boundary columns  */
+    let { ncols, nrows } = placeGates(gates, edges, col, row, Math.min(gridCols, maxCols), compactRows(real, realEdges, col, row));
+    /*  determine the attachment sides of every edge  */
+    const sides = attachSides(edges, col, level);
+    /*  plan the coarse channel/gutter route of every edge (a west side
+        attachment in the first column needs a channel left of it, so
+        the whole grid is shifted one column to the right then)  */
+    let routes = planRoutes(edges, col, row, sides);
+    if (routes.plans.some((plan) => plan.chans.some((c) => c < 0))) {
+        for (const node of nodes)
+            col.set(node.id, col.get(node.id) + 1);
+        ncols++;
+        routes = planRoutes(edges, col, row, sides);
     }
+    const { plans, chanCnt, gutCnt, chanLbl, gutLbl, gutLoop } = routes;
+    /*  grow the boxes by their edge attachment needs  */
+    growBoxes(nodes, edges, sides, boxH, config, level);
     /*  determine grid cell sizes and node center positions (the nodes
         centered in their rows, before any vertical nudging)  */
-    const grid = computeGrid(nodes, col, row, boxW, boxH, ncols, nrows, chanCnt, gutCnt, chanLbl, gutLbl, config);
+    const grid = computeGrid(nodes, col, row, boxW, boxH, ncols, nrows, chanCnt, gutCnt, chanLbl, gutLbl, gutLoop, config);
     const dy = new Map();
     const cx = (id) => grid.colCX[col.get(id)];
     const cy = (id) => grid.rowCY[row.get(id)] + (dy.get(id) ?? 0);
     /*  route the edges for the current node positions  */
-    const route = () => routeEdges(edges, plans, col, sides, boxW, boxH, cx, cy, grid, config);
+    const route = () => routeEdges(edges, plans, sides, boxW, boxH, cx, cy, grid, config, level);
     /*  nudge nodes vertically off their row centers where this
         straightens edges and thereby simplifies the routing  */
     const routing = nudgeNodes(nodes, edges, plans, col, row, boxH, grid, nrows, dy, route);

package/dst/gradia-api-type-grid.d.ts

@@ -1,4 +1,5 @@
 import { Graph } from "./gradia-api-model.js";
 import { Config } from "./gradia-api-config.js";
-import { Layout } from "./gradia-api-render-svg.js";
-export declare const render: (graph: Graph, config: Config) => Promise<Layout>;
+import { Layout } from "./gradia-api-render-base.js";
+import { LevelContext } from "./gradia-api-render-container.js";
+export declare const render: (graph: Graph, config: Config, level?: LevelContext) => Promise<Layout>;

package/dst/gradia-api-type-grid.js

@@ -4,8 +4,10 @@
 **  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
 */
 import { measureNodes } from "./gradia-api-render-node.js";
-/*  lay out an edge-less graph model as a compact grid of tiles  */
-export const render = async (graph, config) => {
+/*  lay out an edge-less graph model as a compact grid of tiles (for a
+    containment level: with the container placeholders at their fixed
+    sizes, which take part in the tile size unification)  */
+export const render = async (graph, config, level = {}) => {
     const nodes = Array.from(graph.nodes.values());
     /*  resolve the configurable rendering geometry  */
     const margin = config["size-canvas-margin"];
@@ -21,7 +23,7 @@ export const render = async (graph, config) => {
     }
     /*  determine node box sizes and unify their heights into a single
         tile height and, if configured, their widths into a single tile width  */
-    const { boxW, boxH, contentH } = measureNodes(nodes, config, () => config["size-node-height-scale"] / 2);
+    const { boxW, boxH, contentH } = measureNodes(nodes, config, () => config["size-node-height-scale"] / 2, level.fixedSize);
     const tileH = nodes.reduce((a, node) => Math.max(a, boxH.get(node.id)), 0);
     const tileW = nodes.reduce((a, node) => Math.max(a, boxW.get(node.id)), 0);
     for (const node of nodes) {

package/dst/gradia-api-type-hub.d.ts

@@ -1,4 +1,5 @@
 import { Graph } from "./gradia-api-model.js";
 import { Config } from "./gradia-api-config.js";
-import { Layout } from "./gradia-api-render-svg.js";
-export declare const render: (graph: Graph, config: Config) => Promise<Layout>;
+import { Layout } from "./gradia-api-render-base.js";
+import { LevelContext } from "./gradia-api-render-container.js";
+export declare const render: (graph: Graph, config: Config, level?: LevelContext) => Promise<Layout>;