@yalehwang/plantuml-js 0.2.0 → 0.3.0

package/dist/parser.d.ts

@@ -7,7 +7,9 @@
  * generics (`List~Item~`, `BaseEntity<T>`), package/namespace grouping,
  * aliases, and tolerant skipping of skinparam/hide/note directives.
  */
-import { PlantUmlModel } from './model.js';
+import { PlantUmlModel } from './foundation/model.js';
+export declare const ENTITY_LINE: RegExp;
+export declare const ENTITY_KEYWORD: RegExp;
 /**
  * Parse a PlantUML source string into a PlantUmlModel.
  *
@@ -15,3 +17,27 @@ import { PlantUmlModel } from './model.js';
  * legend, …) are tolerated and skipped rather than failing the parse.
  */
 export declare function parsePlantUml(source: string): PlantUmlModel;
+/** An undeclared relation endpoint that the parser resolved on the author's behalf. */
+export interface EndpointDiagnostic {
+    /** 1-based source line of the relation. */
+    line: number;
+    message: string;
+}
+/**
+ * Parse and also report how relation endpoints were resolved: endpoints naming
+ * a package are re-attached to a representative entity inside it, and endpoints
+ * naming nothing declared become implicit (empty) classes, as PlantUML does.
+ */
+export declare function parseWithDiagnostics(source: string): {
+    model: PlantUmlModel;
+    diagnostics: EndpointDiagnostic[];
+};
+/** Strip PlantUML `'` line comments (a leading `'` or a trailing inline `'`). */
+export declare function stripComment(line: string): string;
+/**
+ * Extract a declaration name from an entity line's tail, mirroring the parser:
+ * accepts a bare token (`class A`) or a quoted name (`class "User Repo"`), and
+ * tolerates a trailing `as <alias>`. Returns null when the name is missing or
+ * the quoted name is unterminated.
+ */
+export declare function extractDeclaredName(rest: string): string | null;

package/dist/parser.js

@@ -7,8 +7,9 @@
  * generics (`List~Item~`, `BaseEntity<T>`), package/namespace grouping,
  * aliases, and tolerant skipping of skinparam/hide/note directives.
  */
-import { emptyModel, } from './model.js';
-const ENTITY_LINE = /^(abstract\s+)?(class|interface|enum)\s+(.+)$/i;
+import { emptyModel, } from './foundation/model.js';
+export const ENTITY_LINE = /^(abstract\s+)?(class|interface|enum)\s+(.+)$/i;
+export const ENTITY_KEYWORD = /^(?:abstract\s+)?(?:class|interface|enum)\b/i;
 const ARROWS = {
     '--|>': { type: 'inheritance' },
     '<|--': { type: 'inheritance', swap: true },
@@ -31,6 +32,91 @@ const ARROWS = {
  * legend, …) are tolerated and skipped rather than failing the parse.
  */
 export function parsePlantUml(source) {
+    return parseWithDiagnostics(source).model;
+}
+/**
+ * Parse and also report how relation endpoints were resolved: endpoints naming
+ * a package are re-attached to a representative entity inside it, and endpoints
+ * naming nothing declared become implicit (empty) classes, as PlantUML does.
+ */
+export function parseWithDiagnostics(source) {
+    const relationLines = [];
+    const model = parseRaw(source, relationLines);
+    const diagnostics = resolveEndpoints(model, relationLines);
+    return { model, diagnostics };
+}
+function resolveEndpoints(model, relationLines) {
+    const diagnostics = [];
+    const entityIds = new Set(model.entities.map((e) => e.id));
+    const packageIds = new Set(model.packages.map((p) => p.id));
+    const parentOf = new Map(model.packages.map((p) => [p.id, p.parentId]));
+    const inPackage = (entityPkg, pkg) => {
+        for (let cur = entityPkg; cur !== undefined; cur = parentOf.get(cur)) {
+            if (cur === pkg)
+                return true;
+        }
+        return false;
+    };
+    const representative = (pkg) => model.entities.find((e) => inPackage(e.packageId, pkg))?.id;
+    // An endpoint may name a package by its id or by the identifier form of its
+    // display name (`CLI_Layer` for `"CLI Layer (命令层)"`), as authors write it.
+    const packageByKey = new Map();
+    for (const p of model.packages) {
+        for (const key of [p.id, packageKey(p.name)]) {
+            if (!packageByKey.has(key))
+                packageByKey.set(key, p.id);
+        }
+    }
+    const asPackage = (id) => packageIds.has(id) ? id : packageByKey.get(id);
+    const resolve = (id, line, pkgOut) => {
+        if (entityIds.has(id))
+            return id;
+        const pkg = asPackage(id);
+        if (pkg !== undefined) {
+            const rep = representative(pkg);
+            if (rep !== undefined) {
+                diagnostics.push({
+                    line,
+                    message: `relation endpoint "${id}" is a package; edge attached to "${rep}" inside it`,
+                });
+                pkgOut(pkg);
+                return rep;
+            }
+        }
+        model.entities.push({
+            id,
+            name: id,
+            generics: [],
+            kind: 'class',
+            members: [],
+            external: true,
+        });
+        entityIds.add(id);
+        diagnostics.push({
+            line,
+            message: `relation endpoint "${id}" is not declared; implicit class created`,
+        });
+        return id;
+    };
+    model.relations.forEach((r, i) => {
+        const line = relationLines[i] ?? 0;
+        r.source = resolve(r.source, line, (p) => {
+            r.sourcePackageId = p;
+        });
+        r.target = resolve(r.target, line, (p) => {
+            r.targetPackageId = p;
+        });
+    });
+    return diagnostics;
+}
+/** Identifier form of a package display name: parenthetical dropped, non-word runs → `_`. */
+function packageKey(name) {
+    return name
+        .replace(/\s*\([^)]*\)\s*$/, '')
+        .trim()
+        .replace(/[^\p{L}\p{N}]+/gu, '_');
+}
+function parseRaw(source, relationLines) {
     const model = emptyModel();
     const lines = source.split(/\r?\n/);
     let inDiagram = false;
@@ -40,8 +126,8 @@ export function parsePlantUml(source) {
         stack.push(frame);
         lastDeclaration = null;
     };
-    for (const raw of lines) {
-        const line = raw.trim();
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+        const line = lines[lineIdx].trim();
         if (line === '')
             continue;
         if (/^@startuml\b/i.test(line)) {
@@ -116,6 +202,7 @@ export function parsePlantUml(source) {
             const relation = parseRelationLine(code);
             if (relation) {
                 model.relations.push(relation);
+                relationLines.push(lineIdx + 1);
                 lastDeclaration = null;
                 continue;
             }
@@ -366,9 +453,28 @@ function stripQuotes(token) {
     return token;
 }
 /** Strip PlantUML `'` line comments (a leading `'` or a trailing inline `'`). */
-function stripComment(line) {
+export function stripComment(line) {
     const idx = line.indexOf("'");
     if (idx === -1)
         return line.trim();
     return line.slice(0, idx).trim();
 }
+/**
+ * Extract a declaration name from an entity line's tail, mirroring the parser:
+ * accepts a bare token (`class A`) or a quoted name (`class "User Repo"`), and
+ * tolerates a trailing `as <alias>`. Returns null when the name is missing or
+ * the quoted name is unterminated.
+ */
+export function extractDeclaredName(rest) {
+    const asIndex = rest.search(/\s+as\s+\S+\s*$/i);
+    const core = asIndex === -1 ? rest.trim() : rest.slice(0, asIndex).trim();
+    if (core === '')
+        return null;
+    if (core.startsWith('"')) {
+        const close = core.indexOf('"', 1);
+        if (close === -1)
+            return null;
+        return core.slice(1, close);
+    }
+    return core.split(/\s+/)[0] || null;
+}

package/dist/render/labels.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Edge-label and hub-badge geometry shared by the SVG renderer and the layout
+ * metrics, so a drawn label and a measured label are the same rectangle.
+ *
+ * Weight labels (`×N`) are placed on the edge itself over a white backing box.
+ * Candidate anchors run along the edge's segments, longest first; the first
+ * candidate that collides with no node and no previously placed label wins, so
+ * labels of neighbouring edges do not pile onto each other.
+ */
+import { PlantUmlModel, PlantUmlEntity } from '../foundation/model.js';
+import { LayoutResult, NodeLayout, Point } from '../foundation/layout.js';
+import { Rect } from '../foundation/edge-router.js';
+export declare const EDGE_LABEL_FONT_SIZE = 11;
+export declare const HUB_BADGE_RADIUS = 9;
+export interface EdgeLabelPlacement {
+    /** Index into `model.relations` (edge id `rel-<index>`). */
+    edge: number;
+    kind: 'weight' | 'label';
+    text: string;
+    rect: Rect;
+}
+/** Hub badge circle: centred on the node's top-right corner, half outside the box. */
+export declare function hubBadgeCircle(node: NodeLayout): {
+    cx: number;
+    cy: number;
+    r: number;
+};
+export declare function hubBadgeRect(node: NodeLayout): Rect;
+/** Bounding boxes of the text lines drawn inside a node (title + members). */
+export declare function entityTextRects(entity: PlantUmlEntity, node: NodeLayout): Rect[];
+export declare function rectsIntersect(a: Rect, b: Rect): boolean;
+/** Same-text labels sharing a source (or target) and the other end's package collapse to one. */
+export declare const LABEL_DEDUPE_MIN = 3;
+/** A collapsed label standing for at least this many edges carries a `×N` count. */
+export declare const LABEL_COUNT_BADGE_MIN = 4;
+/** True when the segment ab touches the rectangle (Liang–Barsky clip). */
+export declare function segmentIntersectsRect(a: Point, b: Point, r: Rect): boolean;
+/** Edge ids (`rel-<i>`) of every segment of every edge other than `ownId` that crosses `rect`. */
+export declare function rectHitsOtherEdge(rect: Rect, edges: {
+    id: string;
+    points: Point[];
+}[], ownId: string): boolean;
+/** Place every weight label and collect every plain edge label, deterministically. */
+export declare function placeEdgeLabels(model: PlantUmlModel, layout: LayoutResult): EdgeLabelPlacement[];

package/dist/render/labels.js

@@ -0,0 +1,231 @@
+/**
+ * Edge-label and hub-badge geometry shared by the SVG renderer and the layout
+ * metrics, so a drawn label and a measured label are the same rectangle.
+ *
+ * Weight labels (`×N`) are placed on the edge itself over a white backing box.
+ * Candidate anchors run along the edge's segments, longest first; the first
+ * candidate that collides with no node and no previously placed label wins, so
+ * labels of neighbouring edges do not pile onto each other.
+ */
+import { METRICS, displayName } from '../foundation/layout.js';
+import { nodeRect } from '../foundation/edge-router.js';
+import { measureTextWidth } from '../foundation/text-measure.js';
+export const EDGE_LABEL_FONT_SIZE = 11;
+const EDGE_LABEL_PAD_X = 3;
+const EDGE_LABEL_HEIGHT = 14;
+/** Fractions along a segment tried, in order, for a label anchor. */
+const ANCHOR_FRACTIONS = [0.5, 0.3, 0.7, 0.15, 0.85];
+export const HUB_BADGE_RADIUS = 9;
+/** Hub badge circle: centred on the node's top-right corner, half outside the box. */
+export function hubBadgeCircle(node) {
+    return { cx: node.x + node.width, cy: node.y, r: HUB_BADGE_RADIUS };
+}
+export function hubBadgeRect(node) {
+    const { cx, cy, r } = hubBadgeCircle(node);
+    return { x: cx - r, y: cy - r, width: 2 * r, height: 2 * r };
+}
+/** Bounding boxes of the text lines drawn inside a node (title + members). */
+export function entityTextRects(entity, node) {
+    const rects = [];
+    const title = measureTextWidth(displayName(entity), METRICS.fontSize);
+    rects.push({
+        x: node.x + (node.width - title) / 2,
+        y: node.y + METRICS.paddingY,
+        width: title,
+        height: METRICS.lineHeight,
+    });
+    entity.members.forEach((member, i) => {
+        rects.push({
+            x: node.x + METRICS.paddingX,
+            y: node.y + METRICS.paddingY + METRICS.lineHeight * (i + 1),
+            width: measureTextWidth(member.raw, METRICS.fontSize),
+            height: METRICS.lineHeight,
+        });
+    });
+    return rects;
+}
+export function rectsIntersect(a, b) {
+    return (a.x < b.x + b.width &&
+        b.x < a.x + a.width &&
+        a.y < b.y + b.height &&
+        b.y < a.y + a.height);
+}
+/** Same-text labels sharing a source (or target) and the other end's package collapse to one. */
+export const LABEL_DEDUPE_MIN = 3;
+/** A collapsed label standing for at least this many edges carries a `×N` count. */
+export const LABEL_COUNT_BADGE_MIN = 4;
+const PLAIN_LABEL_FONT_SIZE = 12;
+const PLAIN_LABEL_HEIGHT = 14;
+/** Gap between a beside-the-line label and the line. */
+const LABEL_SIDE_GAP = 2;
+/** True when the segment ab touches the rectangle (Liang–Barsky clip). */
+export function segmentIntersectsRect(a, b, r) {
+    let t0 = 0;
+    let t1 = 1;
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const clip = (p, q) => {
+        if (p === 0)
+            return q >= 0;
+        const t = q / p;
+        if (p < 0) {
+            if (t > t1)
+                return false;
+            if (t > t0)
+                t0 = t;
+        }
+        else {
+            if (t < t0)
+                return false;
+            if (t < t1)
+                t1 = t;
+        }
+        return true;
+    };
+    return (clip(-dx, a.x - r.x) &&
+        clip(dx, r.x + r.width - a.x) &&
+        clip(-dy, a.y - r.y) &&
+        clip(dy, r.y + r.height - a.y));
+}
+/** Edge ids (`rel-<i>`) of every segment of every edge other than `ownId` that crosses `rect`. */
+export function rectHitsOtherEdge(rect, edges, ownId) {
+    for (const e of edges) {
+        if (e.id === ownId)
+            continue;
+        for (let i = 0; i + 1 < e.points.length; i++) {
+            if (segmentIntersectsRect(e.points[i], e.points[i + 1], rect))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Plain labels that repeat along one bundle (same text, same source — or same
+ * target — and the same package at the other end) show on a single
+ * representative edge; the rest keep a `<title>` tooltip. Returns the
+ * representative index → group size, and the set of suppressed indexes.
+ */
+function dedupePlainLabels(model) {
+    const pkgOf = new Map(model.entities.map((e) => [e.id, e.packageId ?? e.id]));
+    const reps = new Map();
+    const suppressed = new Set();
+    for (const end of ['source', 'target']) {
+        const other = end === 'source' ? 'target' : 'source';
+        const groups = new Map();
+        model.relations.forEach((rel, i) => {
+            if (!rel.label || suppressed.has(i))
+                return;
+            const key = `${rel[end]}\u0000${rel.label}\u0000${pkgOf.get(rel[other]) ?? rel[other]}`;
+            const list = groups.get(key);
+            if (list)
+                list.push(i);
+            else
+                groups.set(key, [i]);
+        });
+        for (const g of groups.values()) {
+            if (g.length < LABEL_DEDUPE_MIN)
+                continue;
+            const total = g.reduce((n, i) => n + (reps.get(i) ?? 1), 0);
+            reps.set(g[0], total);
+            for (const i of g.slice(1)) {
+                suppressed.add(i);
+                reps.delete(i);
+            }
+        }
+    }
+    return { reps, suppressed };
+}
+/**
+ * Candidate rectangles for a plain label: beside each segment (longest first),
+ * offset to either side so the text never sits on its own line.
+ */
+function plainLabelCandidates(points, width, height) {
+    const segs = [];
+    for (let i = 0; i + 1 < points.length; i++) {
+        const len = Math.hypot(points[i + 1].x - points[i].x, points[i + 1].y - points[i].y);
+        if (len > 0)
+            segs.push({ a: points[i], b: points[i + 1], len });
+    }
+    segs.sort((p, q) => q.len - p.len);
+    const rects = [];
+    for (const { a, b } of segs) {
+        const horizontal = Math.abs(b.x - a.x) >= Math.abs(b.y - a.y);
+        for (const t of ANCHOR_FRACTIONS) {
+            const cx = a.x + (b.x - a.x) * t;
+            const cy = a.y + (b.y - a.y) * t;
+            for (const side of [-1, 1]) {
+                rects.push(horizontal
+                    ? { x: cx - width / 2, y: side < 0 ? cy - LABEL_SIDE_GAP - height : cy + LABEL_SIDE_GAP, width, height }
+                    : { x: side < 0 ? cx - LABEL_SIDE_GAP - width : cx + LABEL_SIDE_GAP, y: cy - height / 2, width, height });
+            }
+        }
+    }
+    return rects;
+}
+/** Place every weight label and collect every plain edge label, deterministically. */
+export function placeEdgeLabels(model, layout) {
+    const edges = layout.edges ?? [];
+    const edgesById = new Map(edges.map((e) => [e.id, e]));
+    const nodeRects = layout.nodes.map(nodeRect);
+    const out = [];
+    const placed = [];
+    const { reps, suppressed } = dedupePlainLabels(model);
+    // A plain label sits beside its own edge, clear of every node, every other
+    // edge and every earlier label. A label that fits nowhere is left out (the
+    // renderer keeps it as a `<title>` tooltip).
+    model.relations.forEach((rel, edge) => {
+        const points = edgesById.get(`rel-${edge}`)?.points;
+        if (!points || points.length < 2 || !rel.label || suppressed.has(edge))
+            return;
+        const count = reps.get(edge) ?? 1;
+        const text = count >= LABEL_COUNT_BADGE_MIN ? `${rel.label} ×${count}` : rel.label;
+        const width = measureTextWidth(text, PLAIN_LABEL_FONT_SIZE);
+        const free = plainLabelCandidates(points, width, PLAIN_LABEL_HEIGHT).find((rect) => !nodeRects.some((n) => rectsIntersect(rect, n)) &&
+            !placed.some((p) => rectsIntersect(rect, p)) &&
+            !rectHitsOtherEdge(rect, edges, `rel-${edge}`) &&
+            !ownEdgeTouches(rect, points));
+        if (!free)
+            return;
+        placed.push(free);
+        out.push({ edge, kind: 'label', text, rect: free });
+    });
+    model.relations.forEach((rel, edge) => {
+        const points = edgesById.get(`rel-${edge}`)?.points;
+        if (!points || points.length < 2 || !rel.weight || rel.weight <= 1)
+            return;
+        const text = `×${rel.weight}`;
+        const width = measureTextWidth(text, EDGE_LABEL_FONT_SIZE) + EDGE_LABEL_PAD_X * 2;
+        const candidates = labelCandidates(points, width, EDGE_LABEL_HEIGHT);
+        const clear = (rect) => !nodeRects.some((n) => rectsIntersect(rect, n)) && !placed.some((p) => rectsIntersect(rect, p));
+        const free = candidates.find((rect) => clear(rect) && !rectHitsOtherEdge(rect, edges, `rel-${edge}`)) ??
+            candidates.find(clear);
+        const rect = free ?? candidates[0];
+        placed.push(rect);
+        out.push({ edge, kind: 'weight', text, rect });
+    });
+    return out;
+}
+function ownEdgeTouches(rect, points) {
+    for (let i = 0; i + 1 < points.length; i++) {
+        if (segmentIntersectsRect(points[i], points[i + 1], rect))
+            return true;
+    }
+    return false;
+}
+function labelCandidates(points, width, height) {
+    const segs = [];
+    for (let i = 0; i + 1 < points.length; i++) {
+        const len = Math.hypot(points[i + 1].x - points[i].x, points[i + 1].y - points[i].y);
+        segs.push({ a: points[i], b: points[i + 1], len });
+    }
+    segs.sort((p, q) => q.len - p.len);
+    const rects = [];
+    for (const { a, b } of segs) {
+        for (const t of ANCHOR_FRACTIONS) {
+            const cx = a.x + (b.x - a.x) * t;
+            const cy = a.y + (b.y - a.y) * t;
+            rects.push({ x: cx - width / 2, y: cy - height / 2, width, height });
+        }
+    }
+    return rects;
+}

package/dist/render/legend.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Legend — a small key explaining the visual encodings of a rendered diagram:
+ * feedback (back) edges, hub badges, `×N` weights and the dashed/solid node
+ * frames. Drawn below the diagram, so it never covers layout geometry.
+ */
+import { Theme } from './theme.js';
+/** Entity count above which the legend is drawn by default. */
+export declare const LEGEND_DEFAULT_NODE_THRESHOLD = 30;
+export interface Legend {
+    /** `<g class="uml-legend">` markup positioned at (x, y). */
+    svg: string;
+    width: number;
+    height: number;
+}
+export declare function renderLegend(x: number, y: number, theme: Theme): Legend;

package/dist/render/legend.js

@@ -0,0 +1,42 @@
+/**
+ * Legend — a small key explaining the visual encodings of a rendered diagram:
+ * feedback (back) edges, hub badges, `×N` weights and the dashed/solid node
+ * frames. Drawn below the diagram, so it never covers layout geometry.
+ */
+const ROW_HEIGHT = 20;
+const PAD = 10;
+const SWATCH_WIDTH = 34;
+const FONT_SIZE = 11;
+/** Entity count above which the legend is drawn by default. */
+export const LEGEND_DEFAULT_NODE_THRESHOLD = 30;
+const ITEMS = [
+    'feedback edge (dash-dot; closes a dependency cycle)',
+    'hub badge: number of dependents (edges hidden)',
+    '×N: number of merged relations',
+    'dashed frame: grouped / external package',
+    'solid frame: single module',
+];
+export function renderLegend(x, y, theme) {
+    const { color } = theme;
+    const width = PAD * 2 + SWATCH_WIDTH + 8 + 300;
+    const height = PAD * 2 + ROW_HEIGHT * ITEMS.length;
+    const rowY = (i) => y + PAD + ROW_HEIGHT * i + ROW_HEIGHT / 2;
+    const sx = x + PAD;
+    const tx = sx + SWATCH_WIDTH + 8;
+    const swatches = [
+        `<line x1="${sx}" y1="${rowY(0)}" x2="${sx + SWATCH_WIDTH}" y2="${rowY(0)}" stroke="${color.warn}" stroke-width="${theme.stroke.edge}" stroke-dasharray="${theme.dash.feedback}"/>`,
+        `<circle cx="${sx + SWATCH_WIDTH / 2}" cy="${rowY(1)}" r="8" fill="${color.accent}"/>` +
+            `<text x="${sx + SWATCH_WIDTH / 2}" y="${rowY(1) + 3.5}" text-anchor="middle" font-family="${theme.font.family}" font-size="10" fill="${color.accentText}">N</text>`,
+        `<line x1="${sx}" y1="${rowY(2)}" x2="${sx + SWATCH_WIDTH}" y2="${rowY(2)}" stroke="${color.edge}" stroke-width="2.5" stroke-opacity="${theme.stroke.opacity.strong}"/>`,
+        `<rect x="${sx}" y="${rowY(3) - 7}" width="${SWATCH_WIDTH}" height="14" rx="3" fill="${color.stubFill}" stroke="${color.strokeStub}" stroke-width="${theme.stroke.node}" stroke-dasharray="${theme.dash.stub}"/>`,
+        `<rect x="${sx}" y="${rowY(4) - 7}" width="${SWATCH_WIDTH}" height="14" rx="3" fill="${color.nodeFill}" stroke="${color.stroke}" stroke-width="${theme.stroke.node}"/>`,
+    ];
+    const texts = ITEMS.map((item, i) => `<text x="${tx}" y="${rowY(i) + 4}" text-anchor="start" font-family="${theme.font.family}"` +
+        ` font-size="${FONT_SIZE}" fill="${color.textMember}">${item.replace(/&/g, '&amp;').replace(/</g, '&lt;')}</text>`);
+    const svg = `<g class="uml-legend">` +
+        `<rect x="${x}" y="${y}" width="${width}" height="${height}" rx="6" fill="${color.canvas}" stroke="${color.legendStroke}" stroke-width="${theme.stroke.node}"/>` +
+        swatches.join('') +
+        texts.join('') +
+        `</g>`;
+    return { svg, width, height };
+}

package/dist/render/svg.d.ts

@@ -3,7 +3,64 @@
  * The renderer consumes only the LayoutResult (positions/sizes) plus the
  * model's display fields; it never reaches back into the parser.
  */
-import { PlantUmlModel } from '../model.js';
-import { LayoutResult } from '../layout.js';
+import { PlantUmlModel } from '../foundation/model.js';
+import { LayoutResult, Point } from '../foundation/layout.js';
+import { ThemeOverrides } from './theme.js';
 export declare function escapeXml(text: string): string;
-export declare function renderSvg(model: PlantUmlModel, layout: LayoutResult): string;
+export interface RenderSvgOptions {
+    /** Draw a legend of the visual encodings. Default: on for models with more than 30 entities. */
+    legend?: boolean;
+    /** Theme token overrides over `defaultTheme`. */
+    theme?: ThemeOverrides;
+    /** Edges hidden by transitive reduction; > 0 forces the legend and is reported there and in `data-hidden-transitive`. */
+    hiddenTransitive?: number;
+}
+/**
+ * Per-frame values handed to {@link RenderEngine.render}. Only values computed
+ * for the frame being rendered belong here; configuration that outlives a
+ * frame (theme, legend override) is constructor state of the engine.
+ */
+export interface RenderFrameOptions {
+    /** Edges hidden by transitive reduction in this frame; > 0 forces the legend and is reported there and in `data-hidden-transitive`. */
+    hiddenTransitive?: number;
+}
+/**
+ * The rendering counterpart of `LayoutEngine`: draw an already laid-out model.
+ * Synchronous because SVG assembly is synchronous, unlike layout. Inject one
+ * through `RendererOptions.renderer` to swap the rendering backend.
+ */
+export interface RenderEngine {
+    render(model: PlantUmlModel, layout: LayoutResult, frame?: RenderFrameOptions): string;
+}
+/** Configuration that outlives a frame — constructor state of {@link SvgRenderer}. */
+export interface SvgRendererOptions {
+    /** Draw a legend of the visual encodings. Default: on for models with more than 30 entities. */
+    legend?: boolean;
+    /** Theme token overrides over `defaultTheme`. */
+    theme?: ThemeOverrides;
+}
+/**
+ * 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 declare class SvgRenderer implements RenderEngine {
+    private readonly legend;
+    private readonly theme;
+    constructor(options?: SvgRendererOptions);
+    render(model: PlantUmlModel, layout: LayoutResult, frame?: RenderFrameOptions): string;
+}
+/**
+ * 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 declare function renderSvg(model: PlantUmlModel, layout: LayoutResult, options?: RenderSvgOptions): string;
+/** Edges sharing a source and exit direction beyond this count are drawn as one bundle. */
+export declare const EDGE_BUNDLE_MIN = 5;
+/**
+ * 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 declare function roundedPath(points: Point[], radius: number): string;