@yalehwang/plantuml-js 0.2.2 → 0.3.1

package/dist/render/svg.js

@@ -3,12 +3,13 @@
  * The renderer consumes only the LayoutResult (positions/sizes) plus the
  * model's display fields; it never reaches back into the parser.
  */
-import { METRICS, PACKAGE_LABEL, displayName, } from '../layout.js';
-import { measureTextWidth } from '../text-measure.js';
-const STROKE = '#333333';
-const TRIANGLE_SIZE = 10;
-const CHEVRON_SIZE = 9;
-const DIAMOND_SIZE = 13;
+import { METRICS, PACKAGE_LABEL, displayName, } from '../foundation/layout.js';
+import { measureTextWidth } from '../foundation/text-measure.js';
+import { hubBadgeCircle, placeEdgeLabels, EDGE_LABEL_FONT_SIZE } from '../foundation/labels.js';
+import { renderLegend, LEGEND_DEFAULT_NODE_THRESHOLD } from './legend.js';
+import { resolveTheme } from './theme.js';
+import { packageLayer } from '../foundation/layers.js';
+import { relationSemantics } from '../foundation/relation-semantics.js';
 export function escapeXml(text) {
     return text
         .replace(/&/g, '&')
@@ -21,193 +22,420 @@ function fmt(n) {
     const r = Math.round(n * 100) / 100;
     return Object.is(r, -0) ? '0' : String(r);
 }
-export function renderSvg(model, layout) {
+/**
+ * The built-in {@link RenderEngine}: the SVG backend. Theme and legend
+ * configuration are fixed at construction; the per-frame `hiddenTransitive`
+ * count is passed to [[SvgRenderer.render]].
+ */
+export class SvgRenderer {
+    legend;
+    theme;
+    constructor(options = {}) {
+        this.legend = options.legend;
+        this.theme = options.theme;
+    }
+    render(model, layout, frame = {}) {
+        return drawSvg(model, layout, {
+            legend: this.legend,
+            theme: this.theme,
+            hiddenTransitive: frame.hiddenTransitive,
+        });
+    }
+}
+/**
+ * Convenience wrapper over {@link SvgRenderer}, kept for callers that build the
+ * SVG directly from a model + layout (the renderer class is preferred when
+ * injecting into `RendererOptions.renderer`).
+ */
+export function renderSvg(model, layout, options = {}) {
+    return new SvgRenderer(options).render(model, layout, {
+        hiddenTransitive: options.hiddenTransitive,
+    });
+}
+function drawSvg(model, layout, options) {
+    const theme = resolveTheme(options.theme);
     const nodesById = new Map(layout.nodes.map((n) => [n.id, n]));
     const packagesById = new Map((layout.packages ?? []).map((p) => [p.id, p]));
     const edgesById = new Map((layout.edges ?? []).map((e) => [e.id, e]));
     const body = [];
+    const pkgById = new Map(model.packages.map((p) => [p.id, p]));
+    const layerNames = [];
+    for (const pkg of model.packages) {
+        const layer = packageLayer(pkg);
+        if (layer !== undefined && !layerNames.includes(layer))
+            layerNames.push(layer);
+    }
     for (const pkg of model.packages) {
         const box = packagesById.get(pkg.id);
-        if (box)
-            body.push(renderPackage(pkg, box));
+        if (!box)
+            continue;
+        let depth = 0;
+        for (let p = pkg.parentId ? pkgById.get(pkg.parentId) : undefined; p; p = p.parentId ? pkgById.get(p.parentId) : undefined)
+            depth++;
+        const layer = packageLayer(pkg);
+        const tone = (layer !== undefined ? layerNames.indexOf(layer) : 0) + depth;
+        body.push(renderPackage(pkg, box, theme, tone));
+    }
+    const weightLabels = new Map();
+    const plainLabels = new Map();
+    for (const label of placeEdgeLabels(model, layout)) {
+        if (label.kind === 'weight')
+            weightLabels.set(label.edge, label);
+        else
+            plainLabels.set(label.edge, label);
+    }
+    const bundles = findEdgeBundles(model, edgesById);
+    const bundled = new Set(bundles.flat());
+    for (const group of bundles) {
+        body.push(renderBundle(group.map((i) => ({ rel: model.relations[i], edge: edgesById.get(`rel-${i}`), weightLabel: weightLabels.get(i) })), theme));
     }
     for (let i = 0; i < model.relations.length; i++) {
         const edge = edgesById.get(`rel-${i}`);
-        if (edge)
-            body.push(renderEdge(model.relations[i], edge));
+        if (edge && !bundled.has(i))
+            body.push(renderEdge(model.relations[i], edge, theme, weightLabels.get(i), plainLabels.get(i)));
     }
     for (const entity of model.entities) {
         const node = nodesById.get(entity.id);
         if (node)
-            body.push(renderEntity(entity, node));
+            body.push(renderEntity(entity, node, theme));
+    }
+    let width = layout.width;
+    let height = layout.height;
+    const hidden = options.hiddenTransitive ?? 0;
+    const showLegend = options.legend ?? (hidden > 0 || model.entities.length > LEGEND_DEFAULT_NODE_THRESHOLD);
+    if (showLegend) {
+        const legend = renderLegend(12, layout.height + 8, theme);
+        body.push(legend.svg);
+        width = Math.max(width, legend.width + 24);
+        height = layout.height + 8 + legend.height + 12;
+        if (hidden > 0) {
+            const note = `${hidden} transitive ${hidden === 1 ? 'dependency' : 'dependencies'} hidden (A→B→C implies A→C); set edgeReduction: 'none' to show all`;
+            body.push(`<g class="uml-legend-note">` +
+                textEl(note, 12 + 10, height + 4, 'start', 11, 'normal', theme.color.textMember, theme) +
+                `</g>`);
+            height += 22;
+            width = Math.max(width, 12 + 10 + 7 * note.length * 0.9 + 12);
+        }
     }
-    const width = layout.width;
-    const height = layout.height;
-    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${fmt(width)}" height="${fmt(height)}"` +
-        ` viewBox="0 0 ${fmt(width)} ${fmt(height)}">${body.join('')}</svg>`);
+    const hiddenAttr = hidden > 0 ? ` data-hidden-transitive="${hidden}"` : '';
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${fmt(width)}" height="${fmt(height)}"${hiddenAttr}` +
+        ` viewBox="0 0 ${fmt(width)} ${fmt(height)}">` +
+        `<rect class="uml-canvas" x="0" y="0" width="${fmt(width)}" height="${fmt(height)}" fill="${theme.color.canvas}"/>` +
+        `${body.join('')}</svg>`);
 }
-function renderEntity(entity, node) {
+function textEl(text, x, y, anchor, size, weight, fill, theme, extra = '') {
+    const w = weight === 'normal' ? '' : ` font-weight="${weight}"`;
+    return (`<text x="${fmt(x)}" y="${fmt(y)}" text-anchor="${anchor}"` +
+        ` font-family="${theme.font.family}" font-size="${size}"${w}${extra}` +
+        ` fill="${fill}">${escapeXml(text)}</text>`);
+}
+function renderEntity(entity, node, theme) {
     const italic = entity.kind === 'interface' || entity.kind === 'abstract';
     const fontStyle = italic ? ' font-style="italic"' : '';
     const stub = entity.stub === true;
+    const { color, font } = theme;
     const parts = [];
-    const fill = stub ? '#f6f8fa' : '#ffffff';
-    const stubAttrs = stub ? ` class="uml-stub" stroke-dasharray="5,3"` : '';
+    if (entity.groupMembers)
+        parts.push(`<title>${entity.groupMembers.map(escapeXml).join('\n')}</title>`);
+    const weak = stub || entity.external === true;
+    const stubAttrs = weak
+        ? ` class="${stub ? 'uml-stub' : 'uml-external'}" stroke-dasharray="${theme.dash.stub}"`
+        : '';
     parts.push(`<rect x="${fmt(node.x)}" y="${fmt(node.y)}" width="${fmt(node.width)}"` +
-        ` height="${fmt(node.height)}" rx="2" ry="2" fill="${fill}"` +
-        `${stubAttrs} stroke="${STROKE}" stroke-width="1.5"/>`);
-    const titleBaseline = node.y + METRICS.paddingY + METRICS.fontSize - 2;
-    parts.push(`<line x1="${fmt(node.x)}" y1="${fmt(node.y + METRICS.paddingY + METRICS.lineHeight)}"` +
-        ` x2="${fmt(node.x + node.width)}" y2="${fmt(node.y + METRICS.paddingY + METRICS.lineHeight)}"` +
-        ` stroke="${STROKE}" stroke-width="1"/>`);
-    parts.push(`<text x="${fmt(node.x + node.width / 2)}" y="${fmt(titleBaseline)}"` +
-        ` text-anchor="middle" font-family="${METRICS.fontFamily}" font-size="${METRICS.fontSize}"` +
-        `${fontStyle} fill="#000000">${escapeXml(displayName(entity))}</text>`);
+        ` height="${fmt(node.height)}" rx="${theme.shape.nodeRadius}" ry="${theme.shape.nodeRadius}"` +
+        ` fill="${weak ? color.stubFill : color.nodeFill}"` +
+        `${stubAttrs} stroke="${weak ? color.strokeStub : color.stroke}" stroke-width="${theme.stroke.node}"/>`);
+    const headerBottom = node.y + METRICS.paddingY + METRICS.lineHeight;
+    const titleBaseline = node.y + METRICS.paddingY + METRICS.fontSize + 1;
+    if (entity.members.length > 0) {
+        parts.push(`<line x1="${fmt(node.x)}" y1="${fmt(headerBottom)}"` +
+            ` x2="${fmt(node.x + node.width)}" y2="${fmt(headerBottom)}"` +
+            ` stroke="${color.stroke}" stroke-width="${theme.stroke.node}"/>`);
+    }
+    parts.push(textEl(displayName(entity), node.x + node.width / 2, titleBaseline, 'middle', font.size.title, font.weight.title, color.textTitle, theme, fontStyle));
     entity.members.forEach((member, i) => {
-        const baseline = node.y + METRICS.paddingY + METRICS.lineHeight * (i + 1) + METRICS.fontSize - 2;
-        parts.push(`<text x="${fmt(node.x + METRICS.paddingX)}" y="${fmt(baseline)}"` +
-            ` text-anchor="start" font-family="${METRICS.fontFamily}" font-size="${METRICS.fontSize}"` +
-            ` fill="#000000">${escapeXml(member.raw)}</text>`);
+        const baseline = node.y + METRICS.paddingY + METRICS.lineHeight * (i + 1) + METRICS.fontSize + 1;
+        parts.push(textEl(member.raw, node.x + METRICS.paddingX, baseline, 'start', font.size.member, font.weight.member, color.textMember, theme));
     });
     if (entity.usageCount && entity.usageCount > 0) {
-        parts.push(renderHubBadge(node, entity.usageCount));
+        parts.push(renderHubBadge(node, entity.usageCount, theme));
     }
-    // Each entity is a single DOM group carrying its stable id, so a browser host
-    // can bind hover/click handlers and cross-panel linkage by `data-entity-id`.
-    return (`<g data-entity-id="${escapeXml(entity.id)}" class="uml-node">` +
+    // Each entity is a single DOM group carrying its stable id and its innermost
+    // package, so a browser host can bind hover/click handlers, cross-panel
+    // linkage, and package-containment queries without geometric hit-testing.
+    const packageAttr = entity.packageId !== undefined
+        ? ` data-package-id="${escapeXml(entity.packageId)}"`
+        : '';
+    return (`<g data-entity-id="${escapeXml(entity.id)}"${packageAttr} class="uml-node${entity.external ? ' uml-external' : ''}">` +
         parts.join('') +
         `</g>`);
 }
 /**
- * Hub badge — the "used by N packages" marker drawn at the top-right corner of
- * a node whose incoming edges were summarized away (see [[../transform]]).
+ * Hub badge — the "used by N packages" marker drawn on the top-right corner of
+ * a node whose incoming edges were summarized away (see [[../transform]]). It
+ * is centred on the corner, so half of it sits outside the box and never covers
+ * the node's name. Neutral accent colour: red is reserved for feedback edges.
  */
-function renderHubBadge(node, count) {
-    const cx = node.x + node.width - 12;
-    const cy = node.y + 13;
+function renderHubBadge(node, count, theme) {
+    const { cx, cy, r } = hubBadgeCircle(node);
     return (`<g class="uml-hub-badge">` +
-        `<circle cx="${fmt(cx)}" cy="${fmt(cy)}" r="9" fill="#c0392b"/>` +
-        `<text x="${fmt(cx)}" y="${fmt(cy + 3.5)}" text-anchor="middle"` +
-        ` font-family="${METRICS.fontFamily}" font-size="11" fill="#ffffff">${count}</text>` +
+        `<circle cx="${fmt(cx)}" cy="${fmt(cy)}" r="${r}" fill="${theme.color.accent}"` +
+        ` stroke="${theme.color.canvas}" stroke-width="1"/>` +
+        textEl(String(count), cx, cy + 3.5, 'middle', theme.font.size.badge, 'normal', theme.color.accentText, theme) +
         `</g>`);
 }
-function renderPackage(pkg, box) {
+function renderPackage(pkg, box, theme, tone) {
+    const { color } = theme;
+    const fills = color.packageFills;
+    const fill = fills[((tone % fills.length) + fills.length) % fills.length];
     const tabWidth = Math.min(box.width, Math.max(24, measureTextWidth(pkg.name, PACKAGE_LABEL.fontSize) + PACKAGE_LABEL.tabPadding));
     const parts = [];
     parts.push(`<rect x="${fmt(box.x)}" y="${fmt(box.y)}" width="${fmt(box.width)}"` +
-        ` height="${fmt(box.height)}" fill="none" stroke="${STROKE}" stroke-width="1.5"/>`);
-    parts.push(`<rect x="${fmt(box.x)}" y="${fmt(box.y)}" width="${fmt(tabWidth)}"` +
-        ` height="${PACKAGE_LABEL.tabHeight}" fill="#ffffff" stroke="${STROKE}" stroke-width="1.5"/>`);
-    parts.push(`<text x="${fmt(box.x + 6)}" y="${fmt(box.y + 13)}" text-anchor="start"` +
-        ` font-family="${METRICS.fontFamily}" font-size="${PACKAGE_LABEL.fontSize}" fill="#000000">${escapeXml(pkg.name)}</text>`);
+        ` height="${fmt(box.height)}" rx="${theme.shape.packageRadius}" ry="${theme.shape.packageRadius}"` +
+        ` fill="${fill}" stroke="${color.packageStroke}" stroke-width="${theme.stroke.package}"/>`);
+    parts.push(`<line class="uml-package-tab" x1="${fmt(box.x)}" y1="${fmt(box.y + PACKAGE_LABEL.tabHeight)}"` +
+        ` x2="${fmt(box.x + tabWidth)}" y2="${fmt(box.y + PACKAGE_LABEL.tabHeight)}"` +
+        ` stroke="${color.packageStroke}" stroke-width="${theme.stroke.package}"/>`);
+    parts.push(textEl(pkg.name, box.x + 8, box.y + PACKAGE_LABEL.tabHeight - 8, 'start', theme.font.size.packageLabel, theme.font.weight.packageLabel, color.textPackage, theme));
     return (`<g data-package-id="${escapeXml(pkg.id)}" class="uml-package">` +
         parts.join('') +
         `</g>`);
 }
-function renderEdge(rel, edge) {
+/** Edges sharing a source and exit direction beyond this count are drawn as one bundle. */
+export const EDGE_BUNDLE_MIN = 5;
+/**
+ * Groups of ≥ [[EDGE_BUNDLE_MIN]] unlabelled bundlable edges that leave one
+ * source in the same direction — the "comb" of near-parallel lines a hub-like
+ * source otherwise draws. Returns relation indexes per group.
+ */
+function findEdgeBundles(model, edgesById) {
+    const groups = new Map();
+    model.relations.forEach((rel, i) => {
+        const edge = edgesById.get(`rel-${i}`);
+        if (!edge || edge.points.length < 2 || rel.label || rel.feedback || rel.descriptions)
+            return;
+        if (!relationSemantics(rel.type).isBundlable())
+            return;
+        const from = edge.points[0];
+        const next = edge.points[1];
+        const dx = next.x - from.x;
+        const dy = next.y - from.y;
+        const dir = Math.abs(dx) >= Math.abs(dy) ? (dx >= 0 ? 'E' : 'W') : dy >= 0 ? 'S' : 'N';
+        const key = `${rel.source}\u0000${rel.type}\u0000${dir}`;
+        const list = groups.get(key);
+        if (list)
+            list.push(i);
+        else
+            groups.set(key, [i]);
+    });
+    return [...groups.values()].filter((g) => g.length >= EDGE_BUNDLE_MIN);
+}
+/**
+ * One visible line for a fan-out: the union of the member polylines with
+ * shared segments drawn once, tagged with the summed `data-weight`. Each member
+ * keeps its own arrowhead (carrying `data-edge-target`).
+ */
+function renderBundle(members, theme) {
+    const first = members[0].rel;
+    const semantics = relationSemantics(first.type);
+    const color = semantics.isWeak() ? theme.color.edgeWeak : theme.color.edge;
+    const dash = semantics.isDashed() ? theme.dash.weak : undefined;
+    const totalWeight = members.reduce((sum, m) => sum + (m.rel.weight && m.rel.weight > 1 ? m.rel.weight : 1), 0);
+    const strokeWidth = Math.min(theme.stroke.edge + Math.log2(members.length) * theme.stroke.weightStep, theme.stroke.edgeWidthMax);
+    const seen = new Set();
+    const segments = [];
+    const heads = [];
+    for (const { rel, edge, weightLabel } of members) {
+        if (weightLabel)
+            heads.push(renderWeightLabel(weightLabel, theme));
+        const line = trimPolyline(edge.points, 0, theme.arrow.chevron);
+        for (let i = 0; i + 1 < line.length; i++) {
+            const a = line[i];
+            const b = line[i + 1];
+            const [p, q] = a.x < b.x || (a.x === b.x && a.y <= b.y) ? [a, b] : [b, a];
+            const key = `${fmt(p.x)},${fmt(p.y)}-${fmt(q.x)},${fmt(q.y)}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            segments.push(`M${fmt(p.x)} ${fmt(p.y)}L${fmt(q.x)} ${fmt(q.y)}`);
+        }
+        heads.push(`<g data-edge-target="${escapeXml(rel.target)}" class="uml-bundle-head">` +
+            renderChevron(edge.points, rel.type, color, theme) +
+            `</g>`);
+    }
+    return (`<g data-edge-source="${escapeXml(first.source)}" data-edge-type="${first.type}"` +
+        ` data-bundle-size="${members.length}" data-weight="${totalWeight}" class="uml-edge uml-edge-bundle">` +
+        `<path d="${segments.join('')}" fill="none" stroke="${color}" stroke-width="${fmt(strokeWidth)}"` +
+        ` stroke-opacity="${edgeOpacity(totalWeight, false, theme)}"` +
+        `${dash ? ` stroke-dasharray="${dash}"` : ''} stroke-linejoin="round"${nonScaling(theme)}/>` +
+        heads.join('') +
+        `</g>`);
+}
+function nonScaling(theme) {
+    return theme.stroke.edgeNonScaling ? ' vector-effect="non-scaling-stroke"' : '';
+}
+/** Opacity tier of an edge: heavier (more merged relations) edges are more opaque. */
+function edgeOpacity(weight, feedback, theme) {
+    const { opacity, heavyWeight } = theme.stroke;
+    if (feedback)
+        return opacity.feedback;
+    return weight >= heavyWeight ? opacity.strong : weight > 1 ? opacity.medium : opacity.light;
+}
+function renderEdge(rel, edge, theme, weightLabel, plainLabel) {
     if (edge.points.length < 2)
         return '';
     const points = edge.points;
-    const dashed = rel.type === 'implementation' || rel.type === 'dependency';
-    const color = rel.feedback ? '#c0392b' : STROKE;
-    const sourceTrim = rel.type === 'aggregation' || rel.type === 'composition' ? DIAMOND_SIZE : 0;
-    const targetTrim = rel.type === 'inheritance' || rel.type === 'implementation'
-        ? TRIANGLE_SIZE
-        : rel.type === 'dependency' || rel.type === 'association'
-            ? CHEVRON_SIZE
+    const semantics = relationSemantics(rel.type);
+    const color = rel.feedback ? theme.color.warn : semantics.isWeak() ? theme.color.edgeWeak : theme.color.edge;
+    // Line type carries relation kind only: the dashed fact comes from the
+    // relation-semantics table; a cycle feedback edge is dash-dot. Weight is
+    // width + opacity, never dashes.
+    const dash = rel.feedback ? theme.dash.feedback : semantics.isDashed() ? theme.dash.weak : undefined;
+    const { arrow } = theme;
+    const arrowKind = semantics.arrowKind();
+    const sourceTrim = arrowKind === 'diamond' ? arrow.diamond : 0;
+    const targetTrim = arrowKind === 'triangle'
+        ? arrow.triangle
+        : arrowKind === 'chevron'
+            ? arrow.chevron
             : 0;
     const linePoints = trimPolyline(points, sourceTrim, targetTrim);
     const parts = [];
-    // Weight encodes the number of aggregated original edges: a thicker line,
-    // plus a `×N` label when more than one relation collapsed into this edge.
+    // Weight encodes the number of aggregated original edges: a thicker,
+    // semi-transparent line, plus a `×N` label when more than one relation
+    // collapsed into this edge.
     const weight = rel.weight && rel.weight > 1 ? rel.weight : 1;
-    const strokeWidth = Math.min(1.2 + (weight - 1) * 0.4, 6);
+    const weightWidth = Math.min(theme.stroke.edge + 2 * theme.stroke.weightStep * (Math.log(weight) / Math.log(theme.stroke.heavyWeight)), theme.stroke.edgeWidthMax);
+    const strokeWidth = rel.feedback ? Math.max(theme.stroke.feedback, weightWidth) : weightWidth;
+    const opacity = ` stroke-opacity="${edgeOpacity(weight, !!rel.feedback, theme)}"`;
     const feedbackClass = rel.feedback ? ' class="uml-feedback"' : '';
-    parts.push(`<polyline points="${pointsAttr(linePoints)}" fill="none" stroke="${color}"` +
-        ` stroke-width="${fmt(strokeWidth)}"${dashed ? ' stroke-dasharray="6,4"' : ''}${feedbackClass}/>`);
-    if (rel.type === 'aggregation' || rel.type === 'composition') {
-        parts.push(renderDiamond(points, rel.type === 'composition', color));
+    parts.push(`<path d="${roundedPath(linePoints, theme.shape.edgeCornerRadius)}" fill="none" stroke="${color}"` +
+        ` stroke-width="${fmt(strokeWidth)}"${opacity}${dash ? ` stroke-dasharray="${dash}"` : ''}` +
+        ` stroke-linejoin="round"${nonScaling(theme)}${feedbackClass}/>`);
+    if (arrowKind === 'diamond') {
+        parts.push(renderDiamond(points, semantics.isFilled(), color, theme));
     }
-    if (rel.type === 'inheritance' || rel.type === 'implementation') {
-        parts.push(renderTriangle(points, rel.type, color));
+    if (arrowKind === 'triangle') {
+        parts.push(renderTriangle(points, rel.type, color, theme));
     }
-    if (rel.type === 'dependency' || rel.type === 'association') {
-        parts.push(renderChevron(points, rel.type, color));
+    if (arrowKind === 'chevron') {
+        parts.push(renderChevron(points, rel.type, color, theme));
     }
-    parts.push(...renderEdgeTexts(rel, points, color));
-    if (weight > 1) {
-        const mid = points[Math.floor(points.length / 2)];
-        parts.push(textAt(`×${weight}`, mid.x, mid.y - (rel.label ? 20 : 10), 11, color));
+    parts.push(...renderEdgeTexts(rel, points, theme, plainLabel));
+    if (weightLabel)
+        parts.push(renderWeightLabel(weightLabel, theme));
+    if (rel.label && !plainLabel) {
+        // No label position clear of the nodes: keep the text reachable as a tooltip.
+        parts.unshift(`<title>${escapeXml(rel.label)}</title>`);
     }
     // Each edge is one DOM group tagged with its endpoints + type so hosts can
     // highlight an edge and its neighbours via data attributes.
+    if (rel.descriptions) {
+        parts.unshift(`<title>${rel.descriptions.map(escapeXml).join('\n')}</title>`);
+    }
     return (`<g data-edge-source="${escapeXml(rel.source)}" data-edge-target="${escapeXml(rel.target)}"` +
-        ` data-edge-type="${rel.type}" class="uml-edge">` +
+        ` data-edge-type="${rel.type}"${rel.weight && rel.weight > 1 ? ` data-weight="${rel.weight}"` : ''} class="uml-edge">` +
         parts.join('') +
         `</g>`);
 }
-function renderTriangle(points, type, color = STROKE) {
+/** `×N` weight label on a canvas-coloured backing box so it stays legible over its line. */
+function renderWeightLabel(weightLabel, theme) {
+    const r = weightLabel.rect;
+    return (`<rect class="uml-edge-label-bg" x="${fmt(r.x)}" y="${fmt(r.y)}" width="${fmt(r.width)}"` +
+        ` height="${fmt(r.height)}" fill="${theme.color.canvas}" fill-opacity="0.92"/>` +
+        textEl(weightLabel.text, r.x + r.width / 2, r.y + r.height / 2 + 4, 'middle', EDGE_LABEL_FONT_SIZE, 'normal', theme.color.textMember, theme));
+}
+function renderTriangle(points, type, color, theme) {
+    const size = theme.arrow.triangle;
     const { u, tip } = targetDir(points);
-    const base = { x: tip.x - u.x * TRIANGLE_SIZE, y: tip.y - u.y * TRIANGLE_SIZE };
+    const base = { x: tip.x - u.x * size, y: tip.y - u.y * size };
     const px = -u.y;
     const py = u.x;
-    const half = TRIANGLE_SIZE / 2;
+    const half = size / 2;
     const pts = [
         tip,
         { x: base.x + px * half, y: base.y + py * half },
         { x: base.x - px * half, y: base.y - py * half },
     ];
     return (`<polygon class="uml-arrow uml-arrow-${type}" points="${pointsAttr(pts)}"` +
-        ` fill="none" stroke="${color}" stroke-width="1.2"/>`);
+        ` fill="${theme.color.canvas}" stroke="${color}" stroke-width="${theme.stroke.arrow}" stroke-linejoin="round"/>`);
 }
-function renderChevron(points, type, color = STROKE) {
+/** Solid arrowhead for dependency / association (readable beside small text). */
+function renderChevron(points, type, color, theme) {
+    const size = theme.arrow.chevron;
     const { u, tip } = targetDir(points);
-    const back = { x: tip.x - u.x * CHEVRON_SIZE, y: tip.y - u.y * CHEVRON_SIZE };
+    const back = { x: tip.x - u.x * size, y: tip.y - u.y * size };
     const px = -u.y;
     const py = u.x;
-    const half = CHEVRON_SIZE / 2;
+    const half = size * 0.4;
     const pts = [
-        { x: back.x + px * half, y: back.y + py * half },
         tip,
+        { x: back.x + px * half, y: back.y + py * half },
         { x: back.x - px * half, y: back.y - py * half },
     ];
-    return (`<polyline class="uml-arrow uml-arrow-${type}" points="${pointsAttr(pts)}"` +
-        ` fill="none" stroke="${color}" stroke-width="1.2"/>`);
+    return (`<polygon class="uml-arrow uml-arrow-${type}" points="${pointsAttr(pts)}"` +
+        ` fill="${color}" stroke="${color}" stroke-width="${theme.stroke.arrow}" stroke-linejoin="round"/>`);
 }
-function renderDiamond(points, filled, color = STROKE) {
+function renderDiamond(points, filled, color, theme) {
+    const size = theme.arrow.diamond;
     const { u, tip } = sourceDir(points);
     const px = -u.y;
     const py = u.x;
-    const half = DIAMOND_SIZE / 2;
+    const half = size / 2;
     const mid = { x: tip.x + u.x * half, y: tip.y + u.y * half };
     const pts = [
         tip,
         { x: mid.x + px * half, y: mid.y + py * half },
-        { x: tip.x + u.x * DIAMOND_SIZE, y: tip.y + u.y * DIAMOND_SIZE },
+        { x: tip.x + u.x * size, y: tip.y + u.y * size },
         { x: mid.x - px * half, y: mid.y - py * half },
     ];
     return (`<polygon class="uml-arrow uml-arrow-${filled ? 'composition' : 'aggregation'}"` +
-        ` points="${pointsAttr(pts)}" fill="${filled ? color : 'none'}"` +
-        ` stroke="${color}" stroke-width="1.2"/>`);
+        ` points="${pointsAttr(pts)}" fill="${filled ? color : theme.color.canvas}"` +
+        ` stroke="${color}" stroke-width="${theme.stroke.arrow}" stroke-linejoin="round"/>`);
 }
-function renderEdgeTexts(rel, points, color = '#000000') {
+function renderEdgeTexts(rel, points, theme, plainLabel) {
     const parts = [];
+    const t = (text, x, y, size) => textEl(text, x, y, 'middle', size, 'normal', theme.color.textMember, theme);
     if (rel.sourceCardinality) {
-        parts.push(textAt(rel.sourceCardinality, points[0].x, points[0].y - 7, 11, color));
+        parts.push(t(rel.sourceCardinality, points[0].x, points[0].y - 7, 11));
     }
     if (rel.targetCardinality) {
         const last = points[points.length - 1];
-        parts.push(textAt(rel.targetCardinality, last.x, last.y - 7, 11, color));
+        parts.push(t(rel.targetCardinality, last.x, last.y - 7, 11));
     }
-    if (rel.label) {
-        const mid = points[Math.floor(points.length / 2)];
-        parts.push(textAt(rel.label, mid.x, mid.y - 10, 12, color));
+    if (rel.label && plainLabel) {
+        const r = plainLabel.rect;
+        parts.push(textEl(plainLabel.text, r.x + r.width / 2, r.y + 12, 'middle', 12, 'normal', theme.color.textMember, theme, ` class="uml-edge-label" stroke="${theme.color.labelHalo}" stroke-width="${theme.stroke.labelHalo}"` +
+            ` stroke-linejoin="round" paint-order="stroke"`));
     }
     return parts;
 }
-function textAt(text, x, y, size, color = '#000000') {
-    return (`<text x="${fmt(x)}" y="${fmt(y)}" text-anchor="middle"` +
-        ` font-family="${METRICS.fontFamily}" font-size="${size}" fill="${color}">${escapeXml(text)}</text>`);
+/**
+ * Polyline as an SVG path whose interior corners are rounded with quadratic
+ * curves of radius ≤ `radius` (clamped to half of each adjoining segment). The
+ * routing — the vertices — is unchanged.
+ */
+export function roundedPath(points, radius) {
+    if (points.length < 3 || radius <= 0)
+        return 'M' + pointsAttr(points).replace(/ /g, ' L');
+    let d = `M${fmt(points[0].x)},${fmt(points[0].y)}`;
+    for (let i = 1; i < points.length - 1; i++) {
+        const prev = points[i - 1];
+        const cur = points[i];
+        const next = points[i + 1];
+        const l1 = Math.hypot(cur.x - prev.x, cur.y - prev.y);
+        const l2 = Math.hypot(next.x - cur.x, next.y - cur.y);
+        const r = Math.min(radius, l1 / 2, l2 / 2);
+        if (r <= 0) {
+            d += ` L${fmt(cur.x)},${fmt(cur.y)}`;
+            continue;
+        }
+        const a = { x: cur.x + ((prev.x - cur.x) / l1) * r, y: cur.y + ((prev.y - cur.y) / l1) * r };
+        const b = { x: cur.x + ((next.x - cur.x) / l2) * r, y: cur.y + ((next.y - cur.y) / l2) * r };
+        d += ` L${fmt(a.x)},${fmt(a.y)} Q${fmt(cur.x)},${fmt(cur.y)} ${fmt(b.x)},${fmt(b.y)}`;
+    }
+    const last = points[points.length - 1];
+    return d + ` L${fmt(last.x)},${fmt(last.y)}`;
 }
 function pointsAttr(points) {
     return points.map((p) => `${fmt(p.x)},${fmt(p.y)}`).join(' ');

package/dist/render/theme.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Theme — every visual decision of the SVG renderer as a token. `svg.ts` and
+ * `legend.ts` read only from a resolved Theme, so no colour, size or dash
+ * pattern lives as a literal in drawing code. Rationale and the font decision
+ * are recorded in docs/visual-design.md.
+ */
+export interface Theme {
+    font: {
+        /** Monospace keeps the pure-JS width table (src/text-measure.ts) exact. */
+        family: string;
+        /** Size ladder: title/member/package label/edge label/badge. */
+        size: {
+            title: number;
+            member: number;
+            packageLabel: number;
+            edgeLabel: number;
+            badge: number;
+        };
+        weight: {
+            title: string;
+            member: string;
+            packageLabel: string;
+        };
+    };
+    color: {
+        canvas: string;
+        /** Node/package outlines (slate, never pure black). */
+        stroke: string;
+        strokeStub: string;
+        nodeFill: string;
+        stubFill: string;
+        textTitle: string;
+        textMember: string;
+        textPackage: string;
+        edge: string;
+        edgeWeak: string;
+        /** Halo drawn around edge-label text so a line never strikes through it. */
+        labelHalo: string;
+        /** Cycle feedback edges — the only use of red. */
+        warn: string;
+        /** Neutral informational accent (hub badge). */
+        accent: string;
+        accentText: string;
+        /** Low-saturation package fills, cycled by layer / nesting depth. */
+        packageFills: string[];
+        packageStroke: string;
+        legendStroke: string;
+    };
+    shape: {
+        nodeRadius: number;
+        packageRadius: number;
+        edgeCornerRadius: number;
+    };
+    stroke: {
+        node: number;
+        package: number;
+        edge: number;
+        arrow: number;
+        /** Width grows by two steps per ×`heavyWeight` merged relations (log-scaled); `edgeWidthMax` caps it. */
+        weightStep: number;
+        edgeWidthMax: number;
+        /** Width of a cycle feedback edge (weight can only widen it). */
+        feedback: number;
+        /** Weight (merged relations) from which an edge counts as heavy. */
+        heavyWeight: number;
+        /** Edge opacity tiers: light = weight 1, medium = weight 2, strong = heavy, feedback = cycle back edge. */
+        opacity: {
+            light: number;
+            medium: number;
+            strong: number;
+            feedback: number;
+        };
+        /**
+         * Edge strokes keep their width in screen pixels (`vector-effect:
+         * non-scaling-stroke`) so a thumbnail of a large diagram still shows every
+         * edge at >= 1px instead of dropping below a pixel.
+         */
+        edgeNonScaling: boolean;
+        /** Width of the label halo stroke. */
+        labelHalo: number;
+    };
+    /** Line types: weak = dashed relation kinds (dependency, implementation); feedback = cycle back edge (dash-dot). Every other relation kind is solid. */
+    dash: {
+        weak: string;
+        stub: string;
+        feedback: string;
+    };
+    arrow: {
+        triangle: number;
+        chevron: number;
+        diamond: number;
+    };
+    /** Spacing grid (px); node sizes snap to it. */
+    grid: number;
+}
+export declare const defaultTheme: Theme;
+export type ThemeOverrides = {
+    [K in keyof Theme]?: Theme[K] extends readonly unknown[] ? Theme[K] : Theme[K] extends object ? {
+        [P in keyof Theme[K]]?: Theme[K][P] extends object ? Partial<Theme[K][P]> : Theme[K][P];
+    } : Theme[K];
+};
+/** Merge a partial theme over the defaults (arrays replace, objects merge). */
+export declare function resolveTheme(overrides?: ThemeOverrides): Theme;
+/** Every colour value of a theme (for token-membership assertions). */
+export declare function themeColors(theme: Theme): Set<string>;
+/** `fg` at `alpha` composited over `bg` (both `#rrggbb`), as a `#rrggbb` colour. */
+export declare function blendOver(fg: string, bg: string, alpha: number): string;
+/** WCAG relative luminance contrast ratio between two `#rrggbb` colours. */
+export declare function contrastRatio(a: string, b: string): number;