@rse/gradia 0.9.0

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

@@ -0,0 +1,329 @@
+/*
+**  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>
+*/
+/*  external dependencies  */
+import { DagreLayout } from "@antv/layout";
+import { SLOT, SCALE_H, MARGIN } from "./gradia-api-render-base.js";
+import { measureNodes } from "./gradia-api-render-node.js";
+import { simplifyPoly, assignPorts, assignTracks } from "./gradia-api-render-edge.js";
+/*  rendering geometry constants  */
+const CHANNEL = 140; /*  max width of inter-column channels  */
+const GUTTER = 90; /*  max height of inter-row gutters     */
+const MAXCOLS = 5; /*  max number of side-by-side nodes    */
+const CLUSTX = 26; /*  max X distance within a grid column */
+const CLUSTY = 72; /*  max Y distance within a grid row    */
+/*  snap raw node positions onto a discrete grid by clustering the
+    distinct X coordinates into columns and Y coordinates into rows  */
+const snapToGrid = (nodes, rawX, rawY) => {
+    const cluster = (values, threshold) => {
+        const sorted = Array.from(new Set(values)).sort((a, b) => a - b);
+        const reps = [];
+        for (const v of sorted)
+            if (reps.length === 0 || v - reps[reps.length - 1] > threshold)
+                reps.push(v);
+        return reps;
+    };
+    const colReps = cluster(nodes.map((node) => rawX.get(node.id)), CLUSTX);
+    const rowReps = cluster(nodes.map((node) => rawY.get(node.id)), CLUSTY);
+    const indexOf = (reps, v) => {
+        let best = 0;
+        for (let i = 1; i < reps.length; i++)
+            if (Math.abs(reps[i] - v) < Math.abs(reps[best] - v))
+                best = i;
+        return best;
+    };
+    const col = new Map();
+    const row = new Map();
+    for (const node of nodes) {
+        col.set(node.id, indexOf(colReps, rawX.get(node.id)));
+        row.set(node.id, indexOf(rowReps, rawY.get(node.id)));
+    }
+    return { col, row, ncols: colReps.length, nrows: rowReps.length };
+};
+/*  append a value to the array stored under a key of a multi-map  */
+const pushTo = (map, key, value) => {
+    const list = map.get(key);
+    if (list === undefined)
+        map.set(key, [value]);
+    else
+        list.push(value);
+};
+/*  refine the row assignment: the raw Dagre ordering tends to fling
+    low-degree nodes far away from their neighbors, so pull every
+    node vertically toward the median row of its direct neighbors,
+    as far as free grid cells permit. The pull is deliberately gentle
+    to not compress the rows too aggressively: distant nodes are
+    pulled only half the way, and single-row moves are performed
+    only when they align the node with a direct neighbor in an
+    adjacent column (thereby straightening that edge)  */
+const refineRows = (nodes, edges, col, row) => {
+    const cells = new Set();
+    for (const node of nodes)
+        cells.add(`${col.get(node.id)}:${row.get(node.id)}`);
+    const neighborsOf = new Map();
+    for (const edge of edges) {
+        if (edge.source === edge.target)
+            continue;
+        pushTo(neighborsOf, edge.source, edge.target);
+        pushTo(neighborsOf, edge.target, edge.source);
+    }
+    /*  pull every node toward the median row of its neighbors  */
+    for (const node of nodes) {
+        const nb = neighborsOf.get(node.id);
+        if (nb === undefined)
+            continue;
+        const rows = nb.map((id) => row.get(id)).sort((a, b) => a - b);
+        const desired = rows[Math.floor((rows.length - 1) / 2)];
+        const cur = row.get(node.id);
+        const dist = Math.abs(desired - cur);
+        if (dist === 0)
+            continue;
+        const dir = Math.sign(desired - cur);
+        let target;
+        if (dist === 1) {
+            const aligns = nb.some((id) => row.get(id) === desired
+                && Math.abs(col.get(id) - col.get(node.id)) === 1);
+            if (!aligns)
+                continue;
+            target = desired;
+        }
+        else
+            target = cur + dir * Math.ceil(dist / 2);
+        for (let r = target; r !== cur; r -= dir) {
+            if (!cells.has(`${col.get(node.id)}:${r}`)) {
+                cells.delete(`${col.get(node.id)}:${cur}`);
+                cells.add(`${col.get(node.id)}:${r}`);
+                row.set(node.id, r);
+                break;
+            }
+        }
+    }
+};
+/*  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: [] };
+        const sc = col.get(edge.source);
+        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 chanCnt = new Map();
+    const gutCnt = new Map();
+    for (const plan of plans) {
+        for (const c of plan.chans)
+            chanCnt.set(c, (chanCnt.get(c) ?? 0) + 1);
+        for (const g of plan.guts)
+            gutCnt.set(g, (gutCnt.get(g) ?? 0) + 1);
+    }
+    return { plans, chanCnt, gutCnt };
+};
+/*  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) => {
+    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  */
+    const chanW = Array.from({ length: ncols }, (_, c) => {
+        const cnt = chanCnt.get(c) ?? 0;
+        return cnt === 0 ? 24 : Math.min(CHANNEL, 28 + (cnt - 1) * SLOT);
+    });
+    const gutH = Array.from({ length: nrows }, (_, g) => {
+        const cnt = gutCnt.get(g) ?? 0;
+        return cnt === 0 ? 20 : Math.min(GUTTER, 24 + (cnt - 1) * SLOT);
+    });
+    /*  derive the column and row center positions  */
+    const colCX = [];
+    const rowCY = [];
+    let x = MARGIN;
+    for (let c = 0; c < colWidth.length; c++) {
+        colCX.push(x + colWidth[c] / 2);
+        x += colWidth[c] + chanW[c];
+    }
+    let y = MARGIN;
+    for (let r = 0; r < rowHeight.length; r++) {
+        rowCY.push(y + rowHeight[r] / 2);
+        y += rowHeight[r] + gutH[r];
+    }
+    return { colWidth, rowHeight, chanW, gutH, colCX, rowCY };
+};
+/*  assign the parallel tracks within the channels and gutters and derive
+    the resulting track coordinate functions (see assignTracks for the
+    crossing-avoiding ordering scheme, with backward edges entering the
+    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) => {
+    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  */
+    const chanUsers = new Map();
+    edges.forEach((edge, i) => {
+        const { chans, guts } = plans[i];
+        if (chans.length === 0)
+            return;
+        const mirror = col.get(edge.target) < col.get(edge.source);
+        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 });
+        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 });
+        }
+    });
+    const chanOff = new Map();
+    for (const [c, users] of chanUsers)
+        for (const [edge, off] of assignTracks(users, chanW[c], 16))
+            chanOff.set(`${c}:${edge}`, off);
+    const chanX = (c, edge) => colCX[c] + colWidth[c] / 2 + chanW[c] / 2 +
+        chanOff.get(`${c}:${edge}`);
+    /*  assign the horizontal tracks within the inter-row gutters  */
+    const gutUsers = new Map();
+    edges.forEach((_, i) => {
+        const { chans, guts } = plans[i];
+        if (guts.length === 0)
+            return;
+        const sp = portPos.get(`${i}:s`);
+        pushTo(gutUsers, guts[0], {
+            edge: i,
+            posIn: chanX(chans[0], i),
+            posOut: chanX(chans[1], i),
+            mirror: sp.y > gutBase(guts[0])
+        });
+    });
+    const gutOff = new Map();
+    for (const [g, users] of gutUsers)
+        for (const [edge, off] of assignTracks(users, gutH[g], 12))
+            gutOff.set(`${g}:${edge}`, off);
+    const gutY = (g, edge) => gutBase(g) + gutOff.get(`${g}:${edge}`);
+    return { chanX, gutY };
+};
+/*  route every edge as an orthogonal polyline through the channels
+    between columns and the gutters between rows  */
+const routePolys = (edges, plans, col, portPos, boxW, cx, chanX, gutY) => {
+    const loopUse = new Map();
+    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];
+        let pts;
+        if (edge.source === edge.target) {
+            const k = loopUse.get(edge.source) ?? 0;
+            loopUse.set(edge.source, k + 1);
+            const ox = cx(edge.source) + boxW.get(edge.source) / 2 + 24 + k * SLOT;
+            pts = [[sp.x, sp.y], [ox, sp.y], [ox, tp.y], [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)
+                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]];
+        }
+        else {
+            const ch1 = chanX(chans[0], i);
+            const ch2 = chanX(chans[1], i);
+            const gy = gutY(guts[0], i);
+            pts = [[sp.x, sp.y], [ch1, sp.y], [ch1, gy], [ch2, gy], [ch2, tp.y], [tp.x, tp.y]];
+        }
+        return simplifyPoly(pts);
+    });
+};
+/*  lay out a directed graph model  */
+export const render = async (graph, _config) => {
+    const nodes = Array.from(graph.nodes.values());
+    const edges = graph.edges;
+    /*  determine node box sizes from their textual content  */
+    const { boxW, boxH, contentH } = measureNodes(nodes, () => SCALE_H);
+    /*  determine raw node positions with the AntV Dagre layout  */
+    const layout = new DagreLayout({
+        rankdir: "LR",
+        nodesep: 30,
+        ranksep: 60,
+        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);
+    });
+    /*  snap the raw positions onto the discrete column/row grid  */
+    const { col, row, ncols: gridCols, nrows: gridRows } = snapToGrid(nodes, rawX, rawY);
+    /*  refine the row assignment by pulling every node vertically
+        toward the median row of its direct neighbors  */
+    refineRows(nodes, edges, col, row);
+    /*  fold the grid columns: constrain the diagram width to at most
+        MAXCOLS side-by-side nodes by wrapping excess columns into
+        additional row bands below, so wide graphs grow in height  */
+    if (gridCols > MAXCOLS) {
+        for (const node of nodes) {
+            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 } = planRoutes(edges, col, row);
+    /*  determine grid cell sizes and final node center positions  */
+    const grid = computeGrid(nodes, col, row, boxW, boxH, ncols, nrows, chanCnt, gutCnt);
+    const cx = (id) => grid.colCX[col.get(id)];
+    const cy = (id) => grid.rowCY[row.get(id)];
+    /*  determine the attachment sides of every edge (east/west),
+        derived from the column relation of its endpoint nodes  */
+    const sides = edges.map((edge) => {
+        const sc = col.get(edge.source);
+        const tc = col.get(edge.target);
+        if (sc < tc)
+            return { s: "e", t: "w" };
+        else if (sc > tc)
+            return { s: "w", t: "e" };
+        else
+            return { s: "e", t: "e" };
+    });
+    /*  distribute the edge attachment ports along each node side  */
+    const portPos = assignPorts(edges, sides, cx, cy, boxW, boxH);
+    /*  assign the parallel tracks within the channels and gutters  */
+    const { chanX, gutY } = assignTrackCoords(edges, plans, col, portPos, grid);
+    /*  route every edge as an orthogonal polyline through the channels
+        between columns and the gutters between rows  */
+    const polys = routePolys(edges, plans, col, portPos, boxW, cx, chanX, gutY);
+    /*  hand over the laid out graph for SVG rendering  */
+    return { nodes, edges, cx, cy, boxW, boxH, contentH, polys };
+};

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

@@ -0,0 +1,4 @@
+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>;

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

@@ -0,0 +1,52 @@
+/*
+**  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 { SCALE_H, MARGIN } from "./gradia-api-render-base.js";
+import { measureNodes } from "./gradia-api-render-node.js";
+/*  rendering geometry constants  */
+const GAP_H = 40; /*  horizontal gap between the tiles of the grid  */
+const GAP_V = 20; /*  vertical gap between the tiles of the grid    */
+const MAXCOLS = 4; /*  max number of side-by-side tiles              */
+/*  lay out an edge-less graph model as a compact grid of tiles  */
+export const render = async (graph, _config) => {
+    const nodes = Array.from(graph.nodes.values());
+    /*  ensure the graph is completely edge-less  */
+    if (graph.edges.length > 0) {
+        const edge = graph.edges[0];
+        throw new Error("diagram type \"grid\" does not support edges " +
+            `(found ${graph.edges.length}, first is "${edge.source}" --> "${edge.target}")`);
+    }
+    /*  determine node box sizes (keeping the individual widths)
+        and unify only their heights into a single tile height  */
+    const { boxW, boxH, contentH } = measureNodes(nodes, () => SCALE_H / 2);
+    const tileH = nodes.reduce((a, node) => Math.max(a, boxH.get(node.id)), 0);
+    for (const node of nodes)
+        boxH.set(node.id, tileH);
+    /*  place the nodes in declaration order onto a roughly square,
+        row-major grid (capped at MAXCOLS columns, so larger graphs
+        grow only in height), with each column as wide as its widest
+        tile and each tile left-aligned within its column  */
+    const cols = Math.max(Math.min(Math.ceil(Math.sqrt(nodes.length)), MAXCOLS), 1);
+    const colWidth = Array.from({ length: cols }, () => 0);
+    nodes.forEach((node, i) => {
+        colWidth[i % cols] = Math.max(colWidth[i % cols], boxW.get(node.id));
+    });
+    const colLX = [];
+    let x = MARGIN;
+    for (let c = 0; c < cols; c++) {
+        colLX.push(x);
+        x += colWidth[c] + GAP_H;
+    }
+    const nodeCX = new Map();
+    const nodeCY = new Map();
+    nodes.forEach((node, i) => {
+        nodeCX.set(node.id, colLX[i % cols] + boxW.get(node.id) / 2);
+        nodeCY.set(node.id, MARGIN + Math.floor(i / cols) * (tileH + GAP_V) + tileH / 2);
+    });
+    const cx = (id) => nodeCX.get(id);
+    const cy = (id) => nodeCY.get(id);
+    /*  hand over the laid out graph for SVG rendering  */
+    return { nodes, edges: [], cx, cy, boxW, boxH, contentH, polys: [] };
+};

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

@@ -0,0 +1,4 @@
+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>;

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

@@ -0,0 +1,180 @@
+/*
+**  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 { SLOT, SCALE_H, MARGIN } from "./gradia-api-render-base.js";
+import { isPrimary, measureNodes, defaultStyleOf } from "./gradia-api-render-node.js";
+import { simplifyPoly, assignPorts, assignTracks } from "./gradia-api-render-edge.js";
+/*  rendering geometry constants  */
+const CHANNEL = 340; /*  max width of inter-column channels  */
+const CHANMIN = 240; /*  min width of inter-column channels  */
+const STACK = 20; /*  vertical gap between stacked nodes  */
+/*  the separator between a node id and its placement suffix,
+    distinguishing the two clones of a twice-placed node  */
+const CLONE = "\u0000";
+/*  validate the constrained input topology and classify the declared
+    nodes: exactly one node is annotated with "primary: true" and every
+    edge connects the primary with another node. Each other node is
+    classified as input (edges point toward the primary) and/or output
+    (edges originate from the primary); a node referenced in both
+    directions is placed twice, once in the input column and once in
+    the output column, with its edges rewritten to attach to the
+    corresponding placement  */
+const classifyTopology = (graph) => {
+    const declared = Array.from(graph.nodes.values());
+    const primaries = declared.filter(isPrimary);
+    if (primaries.length !== 1)
+        throw new Error(`expected exactly one node annotated with "primary: true" (found ${primaries.length})`);
+    const center = primaries[0];
+    const inSet = new Set();
+    const outSet = new Set();
+    for (const edge of graph.edges) {
+        if (edge.source === center.id && edge.target === center.id)
+            throw new Error(`self-loop on primary node "${center.id}" not supported`);
+        else if (edge.target === center.id)
+            inSet.add(edge.source);
+        else if (edge.source === center.id)
+            outSet.add(edge.target);
+        else
+            throw new Error(`edge "${edge.source}" --> "${edge.target}" does not connect to primary node "${center.id}"`);
+    }
+    /*  classify every non-primary node into the input and/or output column  */
+    const dual = new Set();
+    const inputs = [];
+    const outputs = [];
+    for (const node of declared) {
+        if (node.id === center.id)
+            continue;
+        const isInput = inSet.has(node.id);
+        const isOutput = outSet.has(node.id);
+        if (!isInput && !isOutput)
+            throw new Error(`node "${node.id}" is neither input nor output of primary node "${center.id}"`);
+        if (isInput && isOutput) {
+            dual.add(node.id);
+            inputs.push({ ...node, id: node.id + CLONE + "in" });
+            outputs.push({ ...node, id: node.id + CLONE + "out" });
+        }
+        else if (isInput)
+            inputs.push(node);
+        else
+            outputs.push(node);
+    }
+    /*  rewrite the edges of the twice-placed nodes onto their clones  */
+    const edges = graph.edges.map((edge) => {
+        if (edge.target === center.id && dual.has(edge.source))
+            return { ...edge, source: edge.source + CLONE + "in" };
+        else if (edge.source === center.id && dual.has(edge.target))
+            return { ...edge, target: edge.target + CLONE + "out" };
+        else
+            return edge;
+    });
+    return { center, inputs, outputs, nodes: [center, ...inputs, ...outputs], edges };
+};
+/*  lay out a hub graph model (N input nodes, one central hub node, M output nodes)  */
+export const render = async (graph, config) => {
+    /*  validate the constrained input topology and classify the
+        declared nodes into the input and output columns  */
+    const { center, inputs, outputs, nodes, edges } = classifyTopology(graph);
+    const inputSet = new Set(inputs.map((node) => node.id));
+    /*  determine node box sizes from their textual content (the primary
+        box at full and all other boxes at half height scale)  */
+    const { boxW, boxH, contentH } = measureNodes(nodes, (node) => node.id === center.id ? SCALE_H : SCALE_H / 2);
+    /*  fixed three-column layout: stack the input nodes in the first
+        column and the output nodes in the third column (each stack
+        vertically centered), and place the center node in the second
+        column at the vertical center of the canvas  */
+    const stackH = (list) => list.reduce((a, node) => a + boxH.get(node.id), 0) + Math.max(list.length - 1, 0) * STACK;
+    const totalH = Math.max(stackH(inputs), boxH.get(center.id), stackH(outputs));
+    const nodeCY = new Map();
+    const stack = (list) => {
+        let y = MARGIN + (totalH - stackH(list)) / 2;
+        for (const node of list) {
+            nodeCY.set(node.id, y + boxH.get(node.id) / 2);
+            y += boxH.get(node.id) + STACK;
+        }
+    };
+    stack(inputs);
+    stack(outputs);
+    nodeCY.set(center.id, MARGIN + totalH / 2);
+    /*  determine column widths and left edge positions, with the two
+        inter-column channel widths sized by actual edge usage  */
+    const colOf = (id) => id === center.id ? 1 : (inputSet.has(id) ? 0 : 2);
+    const colWidth = [
+        inputs.reduce((a, node) => Math.max(a, boxW.get(node.id)), 0),
+        boxW.get(center.id),
+        outputs.reduce((a, node) => Math.max(a, boxW.get(node.id)), 0)
+    ];
+    const chanOf = (edge) => Math.min(colOf(edge.source), colOf(edge.target));
+    const chanCnt = [
+        edges.filter((edge) => chanOf(edge) === 0).length,
+        edges.filter((edge) => chanOf(edge) === 1).length
+    ];
+    const chanW = chanCnt.map((cnt) => Math.min(CHANNEL, Math.max(CHANMIN, 28 + (cnt - 1) * SLOT)));
+    const colLX = [];
+    let x = MARGIN;
+    for (let c = 0; c < 3; c++) {
+        colLX.push(x);
+        x += colWidth[c] + (c < 2 ? chanW[c] : 0);
+    }
+    /*  place the nodes within their column: input nodes right-aligned,
+        output nodes left-aligned, and the center node centered  */
+    const cx = (id) => {
+        const c = colOf(id);
+        if (c === 0)
+            return colLX[0] + colWidth[0] - boxW.get(id) / 2;
+        else if (c === 2)
+            return colLX[2] + boxW.get(id) / 2;
+        else
+            return colLX[1] + colWidth[1] / 2;
+    };
+    const cy = (id) => nodeCY.get(id);
+    /*  determine the attachment sides of every edge (east/west),
+        derived from the column relation of its endpoint nodes  */
+    const sides = edges.map((edge) => colOf(edge.source) < colOf(edge.target) ? { s: "e", t: "w" } : { s: "w", t: "e" });
+    /*  distribute the edge attachment ports along each node side  */
+    const portPos = assignPorts(edges, sides, cx, cy, boxW, boxH);
+    /*  assign the vertical tracks within each channel (see assignTracks
+        for the crossing-avoiding ordering scheme; an IOG has no backward
+        edges, hence no channel user is ever mirrored)  */
+    const chanUsers = [[], []];
+    edges.forEach((edge, i) => {
+        chanUsers[chanOf(edge)].push({
+            edge: i,
+            posIn: portPos.get(`${i}:s`).y,
+            posOut: portPos.get(`${i}:t`).y,
+            mirror: false
+        });
+    });
+    const chanOff = new Map();
+    chanUsers.forEach((users, c) => {
+        for (const [edge, off] of assignTracks(users, chanW[c], 16))
+            chanOff.set(`${c}:${edge}`, off);
+    });
+    /*  determine the X position of an edge's assigned track within a channel  */
+    const chanX = (c, edge) => colLX[c] + colWidth[c] + chanW[c] / 2 +
+        chanOff.get(`${c}:${edge}`);
+    /*  route every edge as an orthogonal polyline through its channel  */
+    const polys = edges.map((edge, i) => {
+        const sp = portPos.get(`${i}:s`);
+        const tp = portPos.get(`${i}:t`);
+        const ch = chanX(chanOf(edge), i);
+        let pts;
+        if (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]];
+        return simplifyPoly(pts);
+    });
+    /*  hand over the laid out graph for SVG rendering (the output copy
+        of a twice-placed node is rendered as a dashed grey "ghost" box,
+        all other boxes get the default primary/regular coloring)  */
+    const styleDefault = defaultStyleOf(config);
+    const styleOf = (node) => node.id.endsWith(CLONE + "out") ? {
+        fill: config["color-node-ghost-box"],
+        stroke: config["color-node-ghost-border"],
+        text: config["color-node-ghost-name"],
+        dash: "10 6"
+    } : styleDefault(node);
+    return { nodes, edges, cx, cy, boxW, boxH, contentH, polys, styleOf };
+};

package/dst/gradia-api.d.ts

@@ -0,0 +1,26 @@
+import { Graph } from "./gradia-api-model.js";
+import { Config } from "./gradia-api-config.js";
+import { Layout } from "./gradia-api-render-svg.js";
+export type { Attr, Node, Edge, Graph } from "./gradia-api-model.js";
+export type { Config } from "./gradia-api-config.js";
+declare const renderers: {
+    graph: (graph: Graph, _config: Config) => Promise<Layout>;
+    hub: (graph: Graph, config: Config) => Promise<Layout>;
+    grid: (graph: Graph, _config: Config) => Promise<Layout>;
+};
+export type DiagramType = keyof typeof renderers;
+export declare const diagramTypes: DiagramType[];
+export declare const diagramTypeDefault: DiagramType;
+export declare const diagramFormats: readonly ["svg:standalone", "svg:embedded", "url:xml", "url:base64"];
+export type DiagramFormat = typeof diagramFormats[number];
+export declare const diagramFormatDefault: DiagramFormat;
+export interface DiagramOptions {
+    type?: DiagramType;
+    format?: DiagramFormat;
+    config?: Partial<Config>;
+}
+export declare class Gradia {
+    static parse(spec: string): Graph;
+    static generate(graph: Graph, options?: DiagramOptions): Promise<string>;
+    static render(spec: string, options?: DiagramOptions): Promise<string>;
+}

package/dst/gradia-api.js

@@ -0,0 +1,71 @@
+/*
+**  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 { parse } from "./gradia-api-parser.js";
+import { configDefaults, parseDirectives } from "./gradia-api-config.js";
+import { partitionGroups, composeGroups } from "./gradia-api-render-group.js";
+import { renderSVG } from "./gradia-api-render-svg.js";
+import { render as renderGraph } from "./gradia-api-type-graph.js";
+import { render as renderHub } from "./gradia-api-type-hub.js";
+import { render as renderGrid } from "./gradia-api-type-grid.js";
+/*  the supported diagram types and their renderers  */
+const renderers = {
+    graph: renderGraph,
+    hub: renderHub,
+    grid: renderGrid
+};
+export const diagramTypes = Object.keys(renderers);
+export const diagramTypeDefault = "graph";
+/*  the supported output formats  */
+export const diagramFormats = ["svg:standalone", "svg:embedded", "url:xml", "url:base64"];
+export const diagramFormatDefault = "svg:standalone";
+/*  the Gradia API facade  */
+export class Gradia {
+    /*  parse a graph description into the graph model  */
+    static parse(spec) {
+        return parse(spec);
+    }
+    /*  generate an SVG document or data URL from a graph model
+        (the rendering configuration is layered: defaults, then the
+        explicit config options)  */
+    static async generate(graph, options = {}) {
+        /*  determine and validate the diagram type and output format  */
+        const type = options.type ?? diagramTypeDefault;
+        if (!Object.hasOwn(renderers, type))
+            throw new Error(`invalid diagram type "${type}"`);
+        const format = options.format ?? diagramFormatDefault;
+        if (!diagramFormats.includes(format))
+            throw new Error(`invalid output format "${format}"`);
+        /*  layer the rendering configuration  */
+        const config = { ...configDefaults, ...(options.config ?? {}) };
+        /*  lay out the graph model: either as a whole, or partitioned
+            into its named groups which are laid out individually and
+            then stacked vertically as decorated group boxes  */
+        const parts = partitionGroups(graph);
+        const layout = parts === null ?
+            await renderers[type](graph, config) :
+            composeGroups(parts, await Promise.all(parts.map((part) => renderers[type](part.graph, config))));
+        /*  render the laid out graph into an SVG document  */
+        const svg = renderSVG(layout, config);
+        /*  convert the SVG document into the requested output format  */
+        if (format === "svg:embedded")
+            return svg.replace(/^<\?xml[^?]*\?>\n/, "");
+        else if (format === "url:xml")
+            return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+        else if (format === "url:base64")
+            return `data:image/svg+xml;base64,${Buffer.from(svg, "utf8").toString("base64")}`;
+        else
+            return svg;
+    }
+    /*  render a graph description into an SVG document or data URL
+        (combines parse and generate, with the "#config <option> <value>"
+        directives from the spec layered between the defaults and the
+        explicit config options)  */
+    static async render(spec, options = {}) {
+        const graph = Gradia.parse(spec);
+        const config = { ...parseDirectives(spec), ...(options.config ?? {}) };
+        return Gradia.generate(graph, { ...options, config });
+    }
+}