@rse/gradia 0.9.0 → 0.9.2

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

@@ -3,14 +3,22 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
 */
-import { resolveFont } from "./gradia-api-config.js";
-import { FS_NAME, FS_TYPE, FS_ATTR, FS_EDGE, FS_ARITY, FS_GROUP, MARGIN, textWidth, escapeXML } from "./gradia-api-render-base.js";
+/*  external dependencies  */
+import { customAlphabet } from "nanoid";
+import { resolveFont, cssValueOf } from "./gradia-api-config.js";
+import { FS_NAME, FS_TYPE, FS_ATTR, FS_EDGE, FS_ARITY, FS_GROUP, textWidth, escapeXML } from "./gradia-api-render-base.js";
 import { attrsOfNode, typeOf, urlOf, defaultStyleOf, MIN_H, ATTR_H, ATTR_P, TYPE_H, TYPE_D } from "./gradia-api-render-node.js";
 import { computeHops, pathOf, pointAt } from "./gradia-api-render-edge.js";
 /*  escape a string for use inside a CSS string literal (the XML escaping
     is resolved by the parser before the CSS is parsed, so quotes and
     backslashes have to be neutralized to prevent a CSS injection)  */
 const escapeCSS = (text) => text.replace(/[\\"']/g, "\\$&").replace(/[\r\n]/g, " ");
+/*  generate a per-document identifier prefix, as the SVG identifiers
+    are DOM-global and would collide once multiple diagrams are embedded
+    into the very same document (the alphabet is restricted to
+    alphanumerics to stay a valid XML name and CSS/URL fragment)  */
+const nanoid = customAlphabet("0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ", 12);
+const idPrefix = () => `gradia-${nanoid()}`;
 /*  the placement of a group tag in the top-left corner of its group box  */
 const TAG_DX = 18; /*  left offset of the group tag  */
 const TAG_DY = 12; /*  top offset of the group tag   */
@@ -28,6 +36,7 @@ const labelPlacer = (layout) => {
     for (const group of layout.groups ?? [])
         occupied.push([group.x + TAG_DX, group.y + TAG_DY,
             group.x + TAG_DX + textWidth(group.name, FS_GROUP), group.y + TAG_DY + FS_GROUP * 1.2]);
+    /*  claim the first collision-free candidate box  */
     const collides = (box) => occupied.some((o) => box[0] < o[2] && box[2] > o[0] && box[1] < o[3] && box[3] > o[1]);
     const claim = (candidates) => {
         const box = candidates.find((c) => !collides(c)) ?? candidates[0];
@@ -38,7 +47,7 @@ const labelPlacer = (layout) => {
 };
 /*  generate the SVG fragments for a single node box (a node with a
     "url" attribute becomes a hyperlink covering the whole box)  */
-const renderNode = (node, layout, style, font) => {
+const renderNode = (node, layout, style, font, color) => {
     const { cx, cy, boxW, boxH, contentH } = layout;
     const w = boxW.get(node.id);
     const h = boxH.get(node.id);
@@ -49,7 +58,7 @@ const renderNode = (node, layout, style, font) => {
     const url = urlOf(node);
     const parts = [];
     parts.push(`<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="6" ` +
-        `fill="${escapeXML(style.fill)}" stroke="${escapeXML(style.stroke)}" stroke-width="4.0"` +
+        `style="fill: ${color(style.fill)}; stroke: ${color(style.stroke)}" stroke-width="4.0"` +
         `${style.dash !== undefined ? ` stroke-dasharray="${escapeXML(style.dash)}"` : ""}/>`);
     /*  vertically center the textual content block within the box, with
         the optional type line shifting the name and attributes down  */
@@ -58,15 +67,15 @@ const renderNode = (node, layout, style, font) => {
     const nameY = attrs.length > 0 ? ty + th + 42 : cy(node.id) + th / 2 + FS_NAME * 0.36;
     if (type !== undefined)
         parts.push(`<text x="${cx(node.id)}" y="${nameY - TYPE_D}" text-anchor="middle" ` +
-            `font-family="${font}" font-size="${FS_TYPE}" ` +
-            `fill="${escapeXML(style.text)}">${escapeXML(type)}</text>`);
+            `font-size="${FS_TYPE}" ` +
+            `style="font-family: ${font}; fill: ${color(style.text)}">${escapeXML(type)}</text>`);
     parts.push(`<text x="${cx(node.id)}" y="${nameY}" text-anchor="middle" ` +
-        `font-family="${font}" font-size="${FS_NAME}" font-weight="600" ` +
-        `fill="${escapeXML(style.text)}">${escapeXML(node.name)}</text>`);
+        `font-size="${FS_NAME}" font-weight="600" ` +
+        `style="font-family: ${font}; fill: ${color(style.text)}">${escapeXML(node.name)}</text>`);
     attrs.forEach((attr, k) => {
         parts.push(`<text x="${cx(node.id)}" y="${ty + th + MIN_H + ATTR_P + k * ATTR_H}" text-anchor="middle" ` +
-            `font-family="${font}" font-size="${FS_ATTR}" ` +
-            `fill="${escapeXML(style.text)}">${escapeXML(`${attr.key}: ${attr.val}`)}</text>`);
+            `font-size="${FS_ATTR}" ` +
+            `style="font-family: ${font}; fill: ${color(style.text)}">${escapeXML(`${attr.key}: ${attr.val}`)}</text>`);
     });
     if (url === undefined)
         return parts;
@@ -75,7 +84,7 @@ const renderNode = (node, layout, style, font) => {
 /*  determine the overall bounding box of all rendered elements (the
     node boxes and the placed labels are handed over as already
     computed areas, the edge polylines are scanned here)  */
-const viewBoxOf = (layout, boxes) => {
+const viewBoxOf = (layout, boxes, margin) => {
     const { polys } = layout;
     let [minX, minY, maxX, maxY] = [Infinity, Infinity, -Infinity, -Infinity];
     for (const [bx1, by1, bx2, by2] of boxes) {
@@ -95,20 +104,31 @@ const viewBoxOf = (layout, boxes) => {
     if (!Number.isFinite(minX))
         [minX, minY, maxX, maxY] = [0, 0, 0, 0];
     return {
-        x: Math.floor(minX - MARGIN / 2),
-        y: Math.floor(minY - MARGIN / 2),
-        w: Math.ceil(maxX - minX + MARGIN),
-        h: Math.ceil(maxY - minY + MARGIN)
+        x: Math.floor(minX - margin / 2),
+        y: Math.floor(minY - margin / 2),
+        w: Math.ceil(maxX - minX + margin),
+        h: Math.ceil(maxY - minY + margin)
     };
 };
 /*  render a laid out graph into an SVG document  */
-export const renderSVG = (layout, config) => {
+export const renderSVG = (layout, config, explicit) => {
     const { nodes, edges, polys } = layout;
     const groups = layout.groups ?? [];
-    const styleOf = layout.styleOf ?? defaultStyleOf(config);
+    const styleOf = layout.styleOf ?? defaultStyleOf;
+    /*  resolve the directly embedded configuration options into CSS
+        values: explicitly configured values are hard-coded, while all
+        others are fetched at display time from the "--gradia-<option>"
+        CSS custom properties, falling back to the built-in defaults  */
+    const color = (key) => escapeXML(cssValueOf(explicit, key));
+    /*  derive the collision-free identifiers of this SVG document  */
+    const prefix = idPrefix();
+    const idArrow = `${prefix}-arrow`;
     /*  resolve the configured font into the rendered font family stack  */
-    const { family, embed } = resolveFont(config);
-    const font = escapeXML(`'${escapeCSS(family)}', ui-sans-serif, -apple-system, Helvetica, Arial, sans-serif`);
+    const { family, embed, weight } = resolveFont(config);
+    const stack = Object.hasOwn(explicit, "font-family") ?
+        `'${escapeCSS(family)}'` :
+        `var(--gradia-font-family, '${escapeCSS(family)}')`;
+    const font = escapeXML(`${stack}, ui-sans-serif, -apple-system, Helvetica, Arial, sans-serif`);
     /*  detect the edge crossings requiring rendered hops  */
     const hops = computeHops(polys);
     /*  prepare the collision-free placement of the edge labels  */
@@ -116,11 +136,13 @@ export const renderSVG = (layout, config) => {
     /*  generate the SVG fragments for the edges (paths below, labels above)  */
     const svgEdges = [];
     const svgLabels = [];
-    /*  the white halo rendered behind the edge labels for readability  */
-    const halo = "stroke=\"#ffffff\" stroke-width=\"4.5\" paint-order=\"stroke\" stroke-linejoin=\"round\"";
+    /*  the halo rendered behind the edge labels for readability
+        (its color is emitted into the style attribute below, as only
+        there the CSS custom property lookup can be resolved)  */
+    const halo = "stroke-width=\"4.5\" paint-order=\"stroke\" stroke-linejoin=\"round\"";
     edges.forEach((edge, i) => {
-        svgEdges.push(`<path d="${pathOf(polys[i], hops[i])}" fill="none" ` +
-            `stroke="${escapeXML(config["color-edge-line"])}" stroke-width="3" marker-end="url(#arrow)"/>`);
+        svgEdges.push(`<path d="${pathOf(polys[i], hops[i], config["size-edge-corner-radius"], config["size-edge-hop-radius"])}" fill="none" ` +
+            `style="stroke: ${color("color-edge-line")}" stroke-width="3.0" marker-end="url(#${idArrow})"/>`);
         if (edge.name !== undefined) {
             const w = textWidth(edge.name, FS_EDGE);
             const candidates = [];
@@ -137,8 +159,10 @@ export const renderSVG = (layout, config) => {
             }
             const box = claim(candidates);
             svgLabels.push(`<text x="${(box[0] + box[2]) / 2}" y="${box[3] - 3}" text-anchor="middle" ` +
-                `font-family="${font}" font-size="${FS_EDGE}" ` +
-                `fill="${escapeXML(config["color-edge-name"])}" ${halo}>${escapeXML(edge.name)}</text>`);
+                `font-size="${FS_EDGE}" ` +
+                `style="font-family: ${font}; fill: ${color("color-edge-name")}; ` +
+                `stroke: ${color("color-edge-halo")}" ` +
+                `${halo}>${escapeXML(edge.name)}</text>`);
         }
         if (edge.arity !== undefined) {
             const w = textWidth(edge.arity, FS_ARITY);
@@ -152,25 +176,27 @@ export const renderSVG = (layout, config) => {
                 [ax - w / 2 - dx * 14, p.y - 17, ax + w / 2 - dx * 14, p.y - 4]
             ]);
             svgLabels.push(`<text x="${(box[0] + box[2]) / 2}" y="${box[3] - 3}" text-anchor="middle" ` +
-                `font-family="${font}" font-size="${FS_ARITY}" ` +
-                `fill="${escapeXML(config["color-edge-arity"])}" ${halo}>${escapeXML(edge.arity)}</text>`);
+                `font-size="${FS_ARITY}" ` +
+                `style="font-family: ${font}; fill: ${color("color-edge-arity")}; ` +
+                `stroke: ${color("color-edge-halo")}" ` +
+                `${halo}>${escapeXML(edge.arity)}</text>`);
         }
     });
     /*  generate the SVG fragments for the node boxes  */
-    const svgNodes = nodes.flatMap((node) => renderNode(node, layout, styleOf(node), font));
+    const svgNodes = nodes.flatMap((node) => renderNode(node, layout, styleOf(node), font, color));
     /*  generate the SVG fragments for the group boxes (drawn below
         everything else) and their tags in the top-left corners  */
     const svgGroups = groups.flatMap((group) => [
         `<rect x="${group.x}" y="${group.y}" width="${group.w}" height="${group.h}" rx="12" ` +
-            `fill="${escapeXML(config["color-group-box"])}" ` +
-            `stroke="${escapeXML(config["color-group-border"])}" stroke-width="3.0"/>`,
+            `style="fill: ${color("color-group-box")}; ` +
+            `stroke: ${color("color-group-border")}" stroke-width="3.0"/>`,
         `<text x="${group.x + TAG_DX}" y="${group.y + TAG_DY + FS_GROUP}" ` +
-            `font-family="${font}" font-size="${FS_GROUP}" font-weight="600" ` +
-            `fill="${escapeXML(config["color-group-name"])}">${escapeXML(group.name)}</text>`
+            `font-size="${FS_GROUP}" font-weight="600" ` +
+            `style="font-family: ${font}; fill: ${color("color-group-name")}">${escapeXML(group.name)}</text>`
     ]);
     /*  determine the overall bounding box of all rendered elements  */
     const groupBoxes = groups.map((group) => [group.x, group.y, group.x + group.w, group.y + group.h]);
-    const vb = viewBoxOf(layout, [...occupied, ...groupBoxes]);
+    const vb = viewBoxOf(layout, [...occupied, ...groupBoxes], config["size-canvas-margin"]);
     /*  assemble the final SVG document  */
     return [
         "<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
@@ -180,13 +206,14 @@ export const renderSVG = (layout, config) => {
         ...(embed !== undefined ? [
             "<style>",
             `@font-face { font-family: "${escapeXML(escapeCSS(family))}"; ` +
+                (weight !== undefined ? `font-weight: ${escapeXML(escapeCSS(weight))}; ` : "") +
                 `src: url(data:font/woff2;base64,${embed}) format("woff2"); }`,
             "</style>"
         ] : []),
-        "<marker id=\"arrow\" viewBox=\"0 0 10 10\" refX=\"9\" refY=\"5\" " +
+        `<marker id="${idArrow}" viewBox="0 0 10 10" refX="9" refY="5" ` +
             "markerWidth=\"21\" markerHeight=\"21\" markerUnits=\"userSpaceOnUse\" " +
             "orient=\"auto-start-reverse\">",
-        `<path d="M 0 1 L 9 5 L 0 9 z" fill="${escapeXML(config["color-edge-line"])}"/>`,
+        `<path d="M 0 1 L 9 5 L 0 9 z" style="fill: ${color("color-edge-line")}"/>`,
         "</marker>",
         "</defs>",
         ...svgGroups,

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

@@ -1,4 +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>;
+export declare const render: (graph: Graph, config: Config) => Promise<Layout>;

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

@@ -5,15 +5,11 @@
 */
 /*  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    */
+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) => {
@@ -137,7 +133,7 @@ const planRoutes = (edges, col, row) => {
 /*  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 computeGrid = (nodes, col, row, boxW, boxH, ncols, nrows, chanCnt, gutCnt, config) => {
     const colWidth = Array.from({ length: ncols }, () => 0);
     const rowHeight = Array.from({ length: nrows }, () => 0);
     for (const node of nodes) {
@@ -147,21 +143,21 @@ const computeGrid = (nodes, col, row, boxW, boxH, ncols, nrows, chanCnt, gutCnt)
     /*  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);
+        return cnt === 0 ? 24 : Math.min(config["graph-channel-width-max"], 28 + (cnt - 1) * config["size-edge-track-gap"]);
     });
     const gutH = Array.from({ length: nrows }, (_, g) => {
         const cnt = gutCnt.get(g) ?? 0;
-        return cnt === 0 ? 20 : Math.min(GUTTER, 24 + (cnt - 1) * SLOT);
+        return cnt === 0 ? 20 : Math.min(config["graph-gutter-height-max"], 24 + (cnt - 1) * config["size-edge-track-gap"]);
     });
     /*  derive the column and row center positions  */
     const colCX = [];
     const rowCY = [];
-    let x = MARGIN;
+    let x = config["size-canvas-margin"];
     for (let c = 0; c < colWidth.length; c++) {
         colCX.push(x + colWidth[c] / 2);
         x += colWidth[c] + chanW[c];
     }
-    let y = MARGIN;
+    let y = config["size-canvas-margin"];
     for (let r = 0; r < rowHeight.length; r++) {
         rowCY.push(y + rowHeight[r] / 2);
         y += rowHeight[r] + gutH[r];
@@ -174,7 +170,7 @@ 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) => {
+const assignTrackCoords = (edges, plans, col, 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  */
@@ -196,7 +192,7 @@ const assignTrackCoords = (edges, plans, col, portPos, grid) => {
     });
     const chanOff = new Map();
     for (const [c, users] of chanUsers)
-        for (const [edge, off] of assignTracks(users, chanW[c], 16))
+        for (const [edge, off] of assignTracks(users, chanW[c], 16, config["size-edge-track-gap"]))
             chanOff.set(`${c}:${edge}`, off);
     const chanX = (c, edge) => colCX[c] + colWidth[c] / 2 + chanW[c] / 2 +
         chanOff.get(`${c}:${edge}`);
@@ -216,14 +212,14 @@ const assignTrackCoords = (edges, plans, col, portPos, grid) => {
     });
     const gutOff = new Map();
     for (const [g, users] of gutUsers)
-        for (const [edge, off] of assignTracks(users, gutH[g], 12))
+        for (const [edge, off] of assignTracks(users, gutH[g], 12, config["size-edge-track-gap"]))
             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 routePolys = (edges, plans, col, portPos, boxW, cx, chanX, gutY, config) => {
     const loopUse = new Map();
     return edges.map((edge, i) => {
         const sc = col.get(edge.source);
@@ -235,7 +231,7 @@ const routePolys = (edges, plans, col, portPos, boxW, cx, chanX, gutY) => {
         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;
+            const ox = cx(edge.source) + boxW.get(edge.source) / 2 + 24 + k * config["size-edge-track-gap"];
             pts = [[sp.x, sp.y], [ox, sp.y], [ox, tp.y], [tp.x, tp.y]];
         }
         else if (chans.length === 1) {
@@ -255,16 +251,16 @@ const routePolys = (edges, plans, col, portPos, boxW, cx, chanX, gutY) => {
     });
 };
 /*  lay out a directed graph model  */
-export const render = async (graph, _config) => {
+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);
+    const { boxW, boxH, contentH } = measureNodes(nodes, config, () => config["size-node-height-scale"]);
     /*  determine raw node positions with the AntV Dagre layout  */
     const layout = new DagreLayout({
         rankdir: "LR",
-        nodesep: 30,
-        ranksep: 60,
+        nodesep: config["graph-node-separation"],
+        ranksep: config["graph-rank-separation"],
         nodeSize: (node) => node.size
     });
     await layout.execute({
@@ -283,16 +279,18 @@ export const render = async (graph, _config) => {
         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) {
+        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) {
             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);
+            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);
+    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]));
@@ -302,7 +300,7 @@ export const render = async (graph, _config) => {
     /*  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 grid = computeGrid(nodes, col, row, boxW, boxH, ncols, nrows, chanCnt, gutCnt, config);
     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),
@@ -320,10 +318,10 @@ export const render = async (graph, _config) => {
     /*  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);
+    const { chanX, gutY } = 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 polys = routePolys(edges, plans, col, portPos, boxW, cx, chanX, gutY);
+    const polys = routePolys(edges, plans, col, portPos, boxW, cx, chanX, gutY, config);
     /*  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

@@ -1,4 +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>;
+export declare const render: (graph: Graph, config: Config) => Promise<Layout>;

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

@@ -3,15 +3,15 @@
 **  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) => {
+export const render = async (graph, config) => {
     const nodes = Array.from(graph.nodes.values());
+    /*  resolve the configurable rendering geometry  */
+    const margin = config["size-canvas-margin"];
+    const gapH = config["grid-gap-horizontal"];
+    const gapV = config["grid-gap-vertical"];
+    const maxCols = Math.max(Math.floor(config["grid-columns-max"]), 1);
     /*  ensure the graph is completely edge-less  */
     if (graph.edges.length > 0) {
         const edge = graph.edges[0];
@@ -20,30 +20,30 @@ export const render = async (graph, _config) => {
     }
     /*  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 { boxW, boxH, contentH } = measureNodes(nodes, config, () => config["size-node-height-scale"] / 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);
+        row-major grid (capped at the configured maximum of 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;
+    let x = margin;
     for (let c = 0; c < cols; c++) {
         colLX.push(x);
-        x += colWidth[c] + GAP_H;
+        x += colWidth[c] + gapH;
     }
     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);
+        nodeCY.set(node.id, margin + Math.floor(i / cols) * (tileH + gapV) + tileH / 2);
     });
     const cx = (id) => nodeCX.get(id);
     const cy = (id) => nodeCY.get(id);

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

@@ -3,13 +3,8 @@
 **  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";
@@ -23,6 +18,9 @@ const CLONE = "\u0000";
     corresponding placement  */
 const classifyTopology = (graph) => {
     const declared = Array.from(graph.nodes.values());
+    for (const node of declared)
+        if (node.id.includes(CLONE))
+            throw new Error(`node id ${JSON.stringify(node.id)} contains a reserved control character`);
     const primaries = declared.filter(isPrimary);
     if (primaries.length !== 1)
         throw new Error(`expected exactly one node annotated with "primary: true" (found ${primaries.length})`);
@@ -77,26 +75,30 @@ export const render = async (graph, config) => {
         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));
+    /*  resolve the configurable rendering geometry  */
+    const margin = config["size-canvas-margin"];
+    const gap = config["hub-node-gap"];
+    const scale = config["size-node-height-scale"];
     /*  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);
+    const { boxW, boxH, contentH } = measureNodes(nodes, config, (node) => node.id === center.id ? scale : scale / 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 stackH = (list) => list.reduce((a, node) => a + boxH.get(node.id), 0) + Math.max(list.length - 1, 0) * gap;
     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;
+        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;
+            y += boxH.get(node.id) + gap;
         }
     };
     stack(inputs);
     stack(outputs);
-    nodeCY.set(center.id, MARGIN + totalH / 2);
+    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);
@@ -110,9 +112,9 @@ export const render = async (graph, config) => {
         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 chanW = chanCnt.map((cnt) => Math.min(config["hub-channel-width-max"], Math.max(config["hub-channel-width-min"], 28 + (cnt - 1) * config["size-edge-track-gap"])));
     const colLX = [];
-    let x = MARGIN;
+    let x = margin;
     for (let c = 0; c < 3; c++) {
         colLX.push(x);
         x += colWidth[c] + (c < 2 ? chanW[c] : 0);
@@ -135,7 +137,7 @@ export const render = async (graph, config) => {
     /*  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
+        for the crossing-avoiding ordering scheme; a hub graph has no backward
         edges, hence no channel user is ever mirrored)  */
     const chanUsers = [[], []];
     edges.forEach((edge, i) => {
@@ -148,7 +150,7 @@ export const render = async (graph, config) => {
     });
     const chanOff = new Map();
     chanUsers.forEach((users, c) => {
-        for (const [edge, off] of assignTracks(users, chanW[c], 16))
+        for (const [edge, off] of assignTracks(users, chanW[c], 16, config["size-edge-track-gap"]))
             chanOff.set(`${c}:${edge}`, off);
     });
     /*  determine the X position of an edge's assigned track within a channel  */
@@ -169,12 +171,11 @@ export const render = async (graph, config) => {
     /*  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"],
+        fill: "color-node-ghost-box",
+        stroke: "color-node-ghost-border",
+        text: "color-node-ghost-name",
         dash: "10 6"
-    } : styleDefault(node);
+    } : defaultStyleOf(node);
     return { nodes, edges, cx, cy, boxW, boxH, contentH, polys, styleOf };
 };

package/dst/gradia-api.d.ts

@@ -4,9 +4,9 @@ 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>;
+    graph: (graph: Graph, config: Config) => Promise<Layout>;
     hub: (graph: Graph, config: Config) => Promise<Layout>;
-    grid: (graph: Graph, _config: Config) => Promise<Layout>;
+    grid: (graph: Graph, config: Config) => Promise<Layout>;
 };
 export type DiagramType = keyof typeof renderers;
 export declare const diagramTypes: DiagramType[];

package/dst/gradia-api.js

@@ -18,6 +18,20 @@ const renderers = {
 };
 export const diagramTypes = Object.keys(renderers);
 export const diagramTypeDefault = "graph";
+/*  parse the "#type <type>" directive from a graph description (a line
+    which is otherwise treated as a plain comment): the last occurrence
+    wins and an invalid type is silently skipped, as the directives are
+    lines of an untrusted input and never abort the rendering  */
+const parseTypeDirective = (input) => {
+    let type;
+    for (const line of input.split(/\r?\n/)) {
+        const m = /^[ \t]*#type[ \t]+([a-z][a-z0-9-]*)[ \t]*$/.exec(line);
+        if (m === null || !Object.hasOwn(renderers, m[1]))
+            continue;
+        type = m[1];
+    }
+    return type;
+};
 /*  the supported output formats  */
 export const diagramFormats = ["svg:standalone", "svg:embedded", "url:xml", "url:base64"];
 export const diagramFormatDefault = "svg:standalone";
@@ -29,7 +43,9 @@ export class Gradia {
     }
     /*  generate an SVG document or data URL from a graph model
         (the rendering configuration is layered: defaults, then the
-        explicit config options)  */
+        explicit config options; the directly embedded options become
+        hard-coded values when explicitly configured and CSS custom
+        property lookups "--gradia-<option>" otherwise)  */
     static async generate(graph, options = {}) {
         /*  determine and validate the diagram type and output format  */
         const type = options.type ?? diagramTypeDefault;
@@ -39,16 +55,17 @@ export class Gradia {
         if (!diagramFormats.includes(format))
             throw new Error(`invalid output format "${format}"`);
         /*  layer the rendering configuration  */
-        const config = { ...configDefaults, ...(options.config ?? {}) };
+        const explicit = options.config ?? {};
+        const config = { ...configDefaults, ...explicit };
         /*  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))));
+            composeGroups(parts, await Promise.all(parts.map((part) => renderers[type](part.graph, config))), config);
         /*  render the laid out graph into an SVG document  */
-        const svg = renderSVG(layout, config);
+        const svg = renderSVG(layout, config, explicit);
         /*  convert the SVG document into the requested output format  */
         if (format === "svg:embedded")
             return svg.replace(/^<\?xml[^?]*\?>\n/, "");
@@ -60,12 +77,13 @@ export class Gradia {
             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)  */
+        (combines parse and generate, with the "#type <type>" and
+        "#config <option> <value>" directives from the spec layered
+        between the defaults and the explicit options)  */
     static async render(spec, options = {}) {
         const graph = Gradia.parse(spec);
+        const type = options.type ?? parseTypeDirective(spec);
         const config = { ...parseDirectives(spec), ...(options.config ?? {}) };
-        return Gradia.generate(graph, { ...options, config });
+        return Gradia.generate(graph, { ...options, type, config });
     }
 }