@yalehwang/plantuml-js 0.2.0 → 0.3.0

package/README.md

@@ -53,12 +53,32 @@ console.log(svg);
 |---|---|
 | `createRenderer({ layout })` | Build a renderer. `layout` is `'elk'` (default), `'viz'` (experimental), or a custom `LayoutEngine`. |
 | `renderer.render(puml)` | Parse + layout + emit SVG. Returns `{ svg, diagramType, warnings }`. Throws `RenderError` on structurally invalid puml. |
+| `renderDetailed(pumlOrModel, options?)` | Run the same pipeline as `renderer.render` and return every intermediate: `{ model, layout, svg, layoutMs, hiddenTransitive }`. Accepts a puml string (throws `RenderError` on invalid input) or an already-parsed `PlantUmlModel`. `DetailedRender.layout` carries the **stable** node/package/edge rectangles — see [Stable layout geometry](#stable-layout-geometry-renderdetailed) — so tooling never has to re-read bounding boxes from the SVG. Exported from both `.` and `./elk`. |
 | `parsePlantUml(puml)` | Parse a puml string into a `PlantUmlModel`. |
 | `checkSyntax(puml)` | Validate without throwing. Returns `{ ok, errors, warnings }` of line-accurate `SyntaxDiagnostic`s. |
 | `explain(puml)` | Explain each line. Returns `LineExplanation[]` (line, kind, explanation). |
 | `renderDot(dot, engine)` | Render a raw DOT string to SVG via `@viz-js/viz`. `engine` is `'dot'` (default), `'neato'`, `'fdp'`, `'sfdp'`, `'circo'`, `'twopi'`, `'osage'`, or `'patchwork'`. |
 | `ElkLayoutEngine` / `VizLayoutEngine` | The two built-in `LayoutEngine` implementations, exported for direct use. |
 
+### Stable layout geometry (`renderDetailed`)
+
+`DetailedRender.layout` is a **stable public contract**: the rectangle fields
+describe exactly what the renderer drew, so a thumbnail, a search jump or a
+selection box can use them directly instead of parsing the SVG. Coordinates are
+relative to the diagram origin (the SVG `viewBox` offset).
+
+| `layout` field | Shape | Corresponding SVG hook |
+|---|---|---|
+| `nodes[]` | `{ id, x, y, width, height }` | `<g class="uml-node" data-entity-id="{id}">` |
+| `packages[]` (engines with container support, e.g. `'elk'`) | `{ id, x, y, width, height }` | `<g class="uml-package" data-package-id="{id}">`; grouped nodes also carry `data-package-id` |
+| `edges[]` | `{ id, source, target, points }` | `<g class="uml-edge" data-edge-source="{source}" data-edge-target="{target}" data-edge-type="…">`; aggregated package corridors add `data-weight`, bundled arrowheads carry `data-edge-target` on `uml-bundle-head` |
+| `width`, `height` | `number` | The `viewBox` extent |
+
+`points` is the same polyline the SVG draws, so an edge hit-test can reuse it
+without re-routing. `model` is the diagram actually drawn (after view,
+transforms and detail), and `hiddenTransitive` counts the edges dropped by
+transitive reduction.
+
 ### Error semantics
 
 `createRenderer` fails closed on an unknown layout name (`'elk'`, `'viz'`, or a

package/dist/core.d.ts

@@ -6,14 +6,18 @@
  * `src/index.ts` is the full build: it re-exports this core and adds the viz
  * engine + `renderDot`.
  */
-import { PlantUmlModel } from './model.js';
+import { PlantUmlModel } from './foundation/model.js';
 import { parsePlantUml } from './parser.js';
-import { LayoutEngine } from './layout.js';
-import { ElkLayoutEngine } from './layout/elk.js';
-import { renderSvg } from './render/svg.js';
+import { LayoutEngine, LayoutResult, DetailLevel } from './foundation/layout.js';
+import { ThemeOverrides } from './render/theme.js';
+import { ElkLayoutEngine, type ElkLayoutOptions } from './layout/elk.js';
+import { renderSvg, RenderSvgOptions, RenderEngine, RenderFrameOptions, SvgRenderer, SvgRendererOptions } from './render/svg.js';
 import { ViewSpec, TransformOptions } from './transform.js';
-export type { PlantUmlModel, PlantUmlEntity, PlantUmlMember, PlantUmlRelation, PlantUmlPackage, EntityKind, RelationType, } from './model.js';
-export type { LayoutEngine, LayoutResult, NodeLayout, EdgeLayout, Point, } from './layout.js';
+export type { PlantUmlModel, PlantUmlEntity, PlantUmlMember, PlantUmlRelation, PlantUmlPackage, EntityKind, RelationType, } from './foundation/model.js';
+export { defaultTheme, resolveTheme } from './render/theme.js';
+export type { Theme, ThemeOverrides } from './render/theme.js';
+export type { DetailLevel } from './foundation/layout.js';
+export type { LayoutEngine, LayoutResult, NodeLayout, EdgeLayout, Point, } from './foundation/layout.js';
 export interface RendererOptions {
     /**
      * `'elk'` (default) | a custom `LayoutEngine` instance. `'viz'` is only
@@ -21,16 +25,80 @@ export interface RendererOptions {
      * fails closed on it.
      */
     layout?: 'elk' | 'viz' | LayoutEngine;
+    /** ELK tuning (e.g. `aspectRatio`); only applies to the `'elk'` engine, ignored by `'viz'` and custom engines. */
+    layoutOptions?: ElkLayoutOptions;
+    /**
+     * Custom `RenderEngine` instance. Default: the built-in [[SvgRenderer]],
+     * configured with `theme` and `legend`. When set, this engine owns the
+     * rendering configuration, so `theme`/`legend` are not applied to it.
+     */
+    renderer?: RenderEngine;
     /** Collapse/expand the diagram before layout (overview, single package, …). */
     view?: ViewSpec;
     /** Extra model transforms applied on top of the view (aggregation, cycles, …). */
     transform?: TransformOptions;
+    /** Draw a legend of the visual encodings. Default: on for diagrams with more than 30 entities. */
+    legend?: boolean;
+    /** Visual theme tokens; unspecified tokens fall back to `defaultTheme`. */
+    theme?: ThemeOverrides;
+    /**
+     * Member detail: `'full'`, `'compact'` (first rows + count) or `'names'`.
+     * Default: chosen by entity count (≤40 full, ≤150 compact, else names).
+     */
+    detail?: DetailLevel;
+    /**
+     * `'aggregate'` folds the relations between two packages into one weighted
+     * box-to-box corridor edge (originals kept in its `<title>`); `'raw'` draws
+     * every edge. Default: `'aggregate'` for diagrams with more than 150 entities.
+     */
+    interPackage?: 'aggregate' | 'raw';
+    /**
+     * Transitive edge reduction (A→B→C hides A→C). `'auto'` (default) reduces only
+     * when every relation is a dependency/association and edges outnumber nodes
+     * more than 3:1; `'transitive'` always reduces; `'none'` draws every edge.
+     * Hidden edges are counted in the legend and in `data-hidden-transitive`.
+     */
+    edgeReduction?: 'auto' | 'transitive' | 'none';
 }
 export interface RenderResult {
     svg: string;
     diagramType: string;
     warnings: string[];
 }
+/**
+ * Everything {@link renderDetailed} computed for one diagram: the model that was
+ * actually laid out and drawn, the geometry the renderer used, the SVG it
+ * emitted, and the reduction bookkeeping.
+ *
+ * This is a **public, stable API** (available from both the `.` and `./elk`
+ * entries). Consumers such as an architecture tab should read geometry from
+ * `layout` instead of parsing `svg` back into bounding boxes. In particular the
+ * rectangle fields below are a stable contract:
+ *
+ * - `layout.nodes[i]` — `{ id, x, y, width, height }`; `id` is the same string
+ *   the SVG puts on `<g class="uml-node" data-entity-id="…">`.
+ * - `layout.packages[i]` (present for engines with container support, e.g.
+ *   `'elk'`) — `{ id, x, y, width, height }`; `id` matches
+ *   `<g class="uml-package" data-package-id="…">`.
+ * - `layout.edges[i]` — `{ id, source, target, points }`; `source`/`target`
+ *   match the SVG's `data-edge-source`/`data-edge-target` (aggregated package
+ *   corridors are emitted as `data-edge-source`/`data-edge-target` pairs with
+ *   `data-weight`), and `points` is the same polyline the SVG draws.
+ *
+ * `x`/`y` are relative to the diagram origin (the SVG's `viewBox` offset), so
+ * they can be translated into a thumbnail directly.
+ */
+export interface DetailedRender {
+    /** The model actually laid out and drawn (after view, transforms and detail). */
+    model: PlantUmlModel;
+    /** Geometry actually used by the renderer; its node/package/edge rectangles are a stable contract (see above). */
+    layout: LayoutResult;
+    svg: string;
+    /** Layout engine wall time in milliseconds (excludes transforms, SVG and any rasterisation). */
+    layoutMs: number;
+    /** Edges hidden by transitive reduction (0 when it did not apply). */
+    hiddenTransitive: number;
+}
 export interface Renderer {
     render(puml: string): Promise<RenderResult>;
 }
@@ -54,6 +122,23 @@ export declare class RenderError extends Error {
     constructor(diagnostics: SyntaxDiagnostic[]);
 }
 export declare function createRenderer(options?: RendererOptions): Renderer;
+/**
+ * Render one diagram through the exact pipeline `createRenderer` uses
+ * (view/transforms → detail → layout → svg) and return every intermediate, so
+ * tooling can read real geometry instead of reverse-engineering the SVG.
+ *
+ * Accepts either a puml string (the counterpart of
+ * `createRenderer(options).render(puml)`, with the same fail-closed
+ * {@link RenderError} on invalid input) or an already-parsed
+ * {@link PlantUmlModel} (used by the sample harness, which parses first to also
+ * read parse diagnostics).
+ *
+ * Stable public API, exported from both the `.` and `./elk` package entries.
+ * The returned {@link DetailedRender.layout} rectangles are the stable contract
+ * documented on {@link DetailedRender}.
+ */
+export declare function renderDetailed(input: string, options?: RendererOptions): Promise<DetailedRender>;
+export declare function renderDetailed(input: PlantUmlModel, options?: RendererOptions): Promise<DetailedRender>;
 /**
  * Entity count at or above which the default full-graph render enables hub
  * summarization. Smaller models stay untouched so a hand-authored diagram is
@@ -76,6 +161,12 @@ export declare const FULL_GRAPH_HUB_IN_DEGREE_THRESHOLD = 6;
  * drawing of the hub's incoming edges.
  */
 export declare function transformFullGraph(model: PlantUmlModel, overrides?: TransformOptions): PlantUmlModel;
+/**
+ * Apply a view, then the same default transforms as the full graph (computed on
+ * the *viewed* model, so a large single-package view summarizes its hubs too).
+ * `overrides` wins over the defaults.
+ */
+export declare function transformView(model: PlantUmlModel, view: ViewSpec, overrides?: TransformOptions): PlantUmlModel;
 /**
  * Validate a puml string without throwing. Returns structured diagnostics for
  * structurally invalid input (content outside a diagram, unbalanced
@@ -99,9 +190,11 @@ export interface LineExplanation {
  * human-readable description. Purely descriptive — it never mutates or throws.
  */
 export declare function explain(puml: string): LineExplanation[];
-export { parsePlantUml, ElkLayoutEngine, renderSvg };
-export { computeLayoutMetrics } from './layout-metrics.js';
-export type { LayoutMetrics } from './layout-metrics.js';
+export { parsePlantUml, ElkLayoutEngine, renderSvg, SvgRenderer };
+export { toPlantUml } from './serialize.js';
+export type { RenderSvgOptions, RenderEngine, RenderFrameOptions, SvgRendererOptions };
+export { computeLayoutMetrics } from './layout/layout-metrics.js';
+export type { LayoutMetrics } from './layout/layout-metrics.js';
 export { applyView, transformModel, aggregateRelations, transitiveReduce, summarizeHubs, markCycles, groupByPathPrefix, } from './transform.js';
 export type { ViewSpec, TransformOptions } from './transform.js';
 export { archguardToPlantUml, archguardAliasMap, pathName, displayName, ARCHGUARD_RELATION_ARROWS, } from './archguard.js';

package/dist/core.js

@@ -6,10 +6,12 @@
  * `src/index.ts` is the full build: it re-exports this core and adds the viz
  * engine + `renderDot`.
  */
-import { parsePlantUml } from './parser.js';
+import { parsePlantUml, parseWithDiagnostics, ENTITY_LINE, ENTITY_KEYWORD, extractDeclaredName, stripComment } from './parser.js';
+import { applyDetail } from './foundation/layout.js';
 import { ElkLayoutEngine } from './layout/elk.js';
-import { renderSvg } from './render/svg.js';
-import { applyView, transformModel } from './transform.js';
+import { renderSvg, SvgRenderer, } from './render/svg.js';
+import { applyView, transformModel, transformModelDetailed, shouldAutoReduce, INTER_PACKAGE_AGGREGATE_ENTITY_THRESHOLD } from './transform.js';
+export { defaultTheme, resolveTheme } from './render/theme.js';
 /** Error thrown by {@link createRenderer}'s `render` on structurally invalid puml. */
 export class RenderError extends Error {
     diagnostics;
@@ -20,9 +22,9 @@ export class RenderError extends Error {
         this.diagnostics = diagnostics;
     }
 }
-function resolveEngine(layout) {
+function resolveEngine(layout, layoutOptions) {
     if (layout === undefined || layout === 'elk')
-        return new ElkLayoutEngine();
+        return new ElkLayoutEngine(layoutOptions);
     if (typeof layout === 'string') {
         throw new Error(`unknown layout engine ${JSON.stringify(layout)} (expected 'elk' or a LayoutEngine instance; ` +
             `'viz' is only available from the full build '@yalehwang/plantuml-js')`);
@@ -32,8 +34,25 @@ function resolveEngine(layout) {
     }
     return layout;
 }
+/**
+ * Resolve the render engine the same way [[resolveEngine]] resolves layout:
+ * the injected instance wins; otherwise the built-in [[SvgRenderer]] takes the
+ * renderer-wide static configuration (`theme`, `legend`). Structural validation
+ * fails closed instead of rendering an empty SVG.
+ */
+function resolveRenderer(options) {
+    const renderer = options.renderer;
+    if (renderer === undefined) {
+        return new SvgRenderer({ legend: options.legend, theme: options.theme });
+    }
+    if (typeof renderer.render !== 'function') {
+        throw new Error('invalid RenderEngine: a custom engine must expose a render(model, layout) method');
+    }
+    return renderer;
+}
 export function createRenderer(options = {}) {
-    const engine = resolveEngine(options.layout);
+    const engine = resolveEngine(options.layout, options.layoutOptions);
+    const renderEngine = resolveRenderer(options);
     return {
         async render(puml) {
             // Fail closed on structurally invalid puml: checkSyntax reports instead of
@@ -41,14 +60,35 @@ export function createRenderer(options = {}) {
             const syntax = checkSyntax(puml);
             if (!syntax.ok)
                 throw new RenderError(syntax.errors);
-            const parsed = parsePlantUml(puml);
-            const model = transformForRender(parsed, options);
-            const layout = await engine.layout(model);
-            const svg = renderSvg(model, layout);
-            return { svg, diagramType: model.diagramType, warnings: [] };
+            const { model: parsed, diagnostics } = parseWithDiagnostics(puml);
+            const { svg, model } = await renderParsed(parsed, options, engine, renderEngine);
+            return { svg, diagramType: model.diagramType, warnings: diagnostics.map((d) => `line ${d.line}: ${d.message}`) };
         },
     };
 }
+async function renderParsed(parsed, options, engine, renderEngine) {
+    const { model: transformed, hiddenTransitive } = transformForRender(parsed, options);
+    const model = applyDetail(transformed, options.detail);
+    const started = performance.now();
+    const layout = await engine.layout(model);
+    const layoutMs = Math.round((performance.now() - started) * 100) / 100;
+    const svg = renderEngine.render(model, layout, { hiddenTransitive });
+    return { model, layout, svg, layoutMs, hiddenTransitive };
+}
+export async function renderDetailed(input, options = {}) {
+    const parsed = typeof input === 'string' ? parseForDetailed(input) : input;
+    return renderParsed(parsed, options, resolveEngine(options.layout, options.layoutOptions), resolveRenderer(options));
+}
+/**
+ * Parse the string form of {@link renderDetailed} with the same fail-closed
+ * semantics as `createRenderer().render` (structured `RenderError`).
+ */
+function parseForDetailed(puml) {
+    const syntax = checkSyntax(puml);
+    if (!syntax.ok)
+        throw new RenderError(syntax.errors);
+    return parseWithDiagnostics(puml).model;
+}
 /**
  * Apply the configured view and transforms. A view collapses/expands first,
  * then the transform pipeline runs with the view's defaults (aggregation +
@@ -59,13 +99,22 @@ export function createRenderer(options = {}) {
  * unreadable arrow cluster.
  */
 function transformForRender(model, options) {
+    const overrides = {
+        ...(options.interPackage ? { interPackage: options.interPackage } : {}),
+        ...options.transform,
+    };
+    const mode = options.edgeReduction ?? 'auto';
+    const reduction = (m) => overrides.transitiveReduction !== undefined || mode === 'none'
+        ? {}
+        : { transitiveReduction: mode === 'transitive' || shouldAutoReduce(m) };
     if (options.view) {
         const viewed = applyView(model, options.view);
-        return transformModel(viewed, { aggregate: true, cycles: true, ...options.transform });
+        return transformModelDetailed(viewed, { ...defaultTransformOptions(viewed), ...reduction(viewed), ...overrides });
+    }
+    if (options.transform) {
+        return transformModelDetailed(model, { interPackage: defaultInterPackage(model), ...reduction(model), ...overrides });
     }
-    if (options.transform)
-        return transformModel(model, options.transform);
-    return transformFullGraph(model);
+    return transformModelDetailed(model, { ...defaultTransformOptions(model), ...reduction(model), ...overrides });
 }
 /**
  * Entity count at or above which the default full-graph render enables hub
@@ -89,14 +138,27 @@ export const FULL_GRAPH_HUB_IN_DEGREE_THRESHOLD = 6;
  * drawing of the hub's incoming edges.
  */
 export function transformFullGraph(model, overrides = {}) {
-    const options = { aggregate: true, cycles: true };
+    return transformModel(model, { ...defaultTransformOptions(model), ...overrides });
+}
+/**
+ * Apply a view, then the same default transforms as the full graph (computed on
+ * the *viewed* model, so a large single-package view summarizes its hubs too).
+ * `overrides` wins over the defaults.
+ */
+export function transformView(model, view, overrides = {}) {
+    const viewed = applyView(model, view);
+    return transformModel(viewed, { ...defaultTransformOptions(viewed), ...overrides });
+}
+function defaultInterPackage(model) {
+    return model.entities.length > INTER_PACKAGE_AGGREGATE_ENTITY_THRESHOLD ? 'aggregate' : 'raw';
+}
+function defaultTransformOptions(model) {
+    const options = { aggregate: true, cycles: true, interPackage: defaultInterPackage(model) };
     if (model.entities.length > FULL_GRAPH_HUB_NODE_THRESHOLD) {
         options.hubThreshold = FULL_GRAPH_HUB_IN_DEGREE_THRESHOLD;
     }
-    return transformModel(model, { ...options, ...overrides });
+    return options;
 }
-const ENTITY_DECL = /^(?:abstract\s+)?(?:class|interface|enum)\s+(.+)$/i;
-const ENTITY_KEYWORD = /^(?:abstract\s+)?(?:class|interface|enum)\b/i;
 /**
  * Validate a puml string without throwing. Returns structured diagnostics for
  * structurally invalid input (content outside a diagram, unbalanced
@@ -153,8 +215,8 @@ export function checkSyntax(puml) {
         if (code === '')
             continue;
         if (ENTITY_KEYWORD.test(code)) {
-            const match = ENTITY_DECL.exec(code);
-            const name = match ? extractDeclaredName(match[1]) : null;
+            const match = ENTITY_LINE.exec(code);
+            const name = match ? extractDeclaredName(match[3]) : null;
             if (name === null) {
                 errors.push({
                     line: lineNo,
@@ -164,6 +226,9 @@ export function checkSyntax(puml) {
             }
         }
     }
+    for (const d of parseWithDiagnostics(puml).diagnostics) {
+        warnings.push({ line: d.line, severity: 'warning', message: d.message });
+    }
     if (sawStart && inDiagram) {
         errors.push({
             line: lines.length,
@@ -204,8 +269,8 @@ function classifyLine(raw) {
     if (code === '')
         return { kind: 'comment', explanation: 'PlantUML comment' };
     if (ENTITY_KEYWORD.test(code)) {
-        const match = ENTITY_DECL.exec(code);
-        const name = match ? extractDeclaredName(match[1]) : null;
+        const match = ENTITY_LINE.exec(code);
+        const name = match ? extractDeclaredName(match[3]) : null;
         if (name === null) {
             return { kind: 'entity', explanation: 'malformed entity declaration' };
         }
@@ -228,33 +293,8 @@ function classifyLine(raw) {
         };
     return { kind: 'unknown', explanation: 'unrecognised line (ignored)' };
 }
-/**
- * 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.
- */
-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;
-}
-/** Strip PlantUML `'` line comments (a leading `'` or a trailing inline `'`). */
-function stripComment(line) {
-    const idx = line.indexOf("'");
-    if (idx === -1)
-        return line.trim();
-    return line.slice(0, idx).trim();
-}
-export { parsePlantUml, ElkLayoutEngine, renderSvg };
-export { computeLayoutMetrics } from './layout-metrics.js';
+export { parsePlantUml, ElkLayoutEngine, renderSvg, SvgRenderer };
+export { toPlantUml } from './serialize.js';
+export { computeLayoutMetrics } from './layout/layout-metrics.js';
 export { applyView, transformModel, aggregateRelations, transitiveReduce, summarizeHubs, markCycles, groupByPathPrefix, } from './transform.js';
 export { archguardToPlantUml, archguardAliasMap, pathName, displayName, ARCHGUARD_RELATION_ARROWS, } from './archguard.js';

package/dist/foundation/layers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Semantic layer resolution for the ELK engine: which layer a package belongs
+ * to, how layers are ordered, and which ELK partition each package lands in.
+ * Pure functions over the model; no ELK types involved.
+ */
+import { PlantUmlModel, PlantUmlPackage } from './model.js';
+/** Resolve a package's semantic layer from its explicit field or its name. */
+export declare function packageLayer(pkg: PlantUmlPackage): string | undefined;
+/**
+ * Order semantic layers by dependency topology instead of puml declaration
+ * order: a layer that depends on another (`A ..> B` across layers) sits *above*
+ * its dependency, so entry layers (Tests, Examples) stack over the base they
+ * consume (Src) and independent layers (Templates) fall out of the sandwich.
+ *
+ * A Kahn topological sort places in-degree-zero layers (nothing depends on
+ * them) first, breaking ties in declaration order for determinism. Layers left
+ * over because of a dependency cycle are appended in declaration order, so a
+ * cyclic graph still yields a stable (if not strictly topological) order; the
+ * renderer marks the offending back-edges as feedback arcs.
+ */
+export declare function topologicalLayerOrder(model: PlantUmlModel): string[];
+/** Ordered, de-duplicated list of semantic layers (dependency topology by default). */
+export declare function resolveLayerOrder(model: PlantUmlModel, layerOrder?: string[]): string[];
+/** Map each package to its partition index (layers first, unlayered last). */
+export declare function assignPartitions(model: PlantUmlModel, layers: string[]): Map<string, number>;

package/dist/foundation/layers.js

@@ -0,0 +1,101 @@
+/**
+ * Semantic layer resolution for the ELK engine: which layer a package belongs
+ * to, how layers are ordered, and which ELK partition each package lands in.
+ * Pure functions over the model; no ELK types involved.
+ */
+/** Name convention: `"X Layer"` declares a semantic layer `X`. */
+const LAYER_SUFFIX = /^(.*)\s+Layer$/i;
+/** Resolve a package's semantic layer from its explicit field or its name. */
+export function packageLayer(pkg) {
+    if (pkg.layer !== undefined)
+        return pkg.layer;
+    const m = LAYER_SUFFIX.exec(pkg.name);
+    if (!m)
+        return undefined;
+    const core = m[1].trim();
+    return core === '' ? undefined : core;
+}
+/**
+ * Order semantic layers by dependency topology instead of puml declaration
+ * order: a layer that depends on another (`A ..> B` across layers) sits *above*
+ * its dependency, so entry layers (Tests, Examples) stack over the base they
+ * consume (Src) and independent layers (Templates) fall out of the sandwich.
+ *
+ * A Kahn topological sort places in-degree-zero layers (nothing depends on
+ * them) first, breaking ties in declaration order for determinism. Layers left
+ * over because of a dependency cycle are appended in declaration order, so a
+ * cyclic graph still yields a stable (if not strictly topological) order; the
+ * renderer marks the offending back-edges as feedback arcs.
+ */
+export function topologicalLayerOrder(model) {
+    const declared = [];
+    for (const pkg of model.packages) {
+        const layer = packageLayer(pkg);
+        if (layer !== undefined && !declared.includes(layer))
+            declared.push(layer);
+    }
+    if (declared.length <= 1)
+        return declared;
+    const pkgById = new Map(model.packages.map((p) => [p.id, p]));
+    const layerOf = new Map();
+    for (const entity of model.entities) {
+        const pkg = entity.packageId ? pkgById.get(entity.packageId) : undefined;
+        layerOf.set(entity.id, pkg ? packageLayer(pkg) : undefined);
+    }
+    const dependsOn = new Map();
+    const dependents = new Map();
+    for (const layer of declared) {
+        dependsOn.set(layer, new Set());
+        dependents.set(layer, 0);
+    }
+    for (const relation of model.relations) {
+        const source = layerOf.get(relation.source);
+        const target = layerOf.get(relation.target);
+        if (source === undefined || target === undefined || source === target)
+            continue;
+        const set = dependsOn.get(source);
+        if (!set.has(target)) {
+            set.add(target);
+            dependents.set(target, (dependents.get(target) ?? 0) + 1);
+        }
+    }
+    const order = [];
+    const done = new Set();
+    const queue = declared.filter((layer) => (dependents.get(layer) ?? 0) === 0);
+    for (let i = 0; i < queue.length; i++) {
+        const layer = queue[i];
+        order.push(layer);
+        done.add(layer);
+        for (const dep of dependsOn.get(layer) ?? []) {
+            const remaining = (dependents.get(dep) ?? 0) - 1;
+            dependents.set(dep, remaining);
+            if (remaining === 0 && !done.has(dep))
+                queue.push(dep);
+        }
+    }
+    // Cyclic remainder: keep declaration order so the output is stable.
+    for (const layer of declared) {
+        if (!done.has(layer))
+            order.push(layer);
+    }
+    return order;
+}
+/** Ordered, de-duplicated list of semantic layers (dependency topology by default). */
+export function resolveLayerOrder(model, layerOrder) {
+    if (layerOrder) {
+        return layerOrder.filter((layer, i, all) => all.indexOf(layer) === i);
+    }
+    return topologicalLayerOrder(model);
+}
+/** Map each package to its partition index (layers first, unlayered last). */
+export function assignPartitions(model, layers) {
+    const partitions = new Map();
+    if (layers.length === 0)
+        return partitions;
+    for (const pkg of model.packages) {
+        const layer = packageLayer(pkg);
+        const index = layer !== undefined ? layers.indexOf(layer) : -1;
+        partitions.set(pkg.id, index >= 0 ? index : layers.length);
+    }
+    return partitions;
+}

package/dist/foundation/layout.d.ts

@@ -0,0 +1,116 @@
+/**
+ * LayoutEngine — the pluggable layout contract. A LayoutEngine is a pure
+ * function from PlantUmlModel to concrete positions; the parser never talks
+ * to a layout engine and the renderer never talks to the parser, so swapping
+ * engines (elkjs, @viz-js/viz, a custom tuner) is an injection, not a rewrite.
+ */
+import { PlantUmlModel, PlantUmlEntity } from './model.js';
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface NodeLayout {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface EdgeLayout {
+    id: string;
+    source: string;
+    target: string;
+    points: Point[];
+}
+export interface PackageLayout {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface LayoutResult {
+    nodes: NodeLayout[];
+    edges: EdgeLayout[];
+    /** Package frames; engines without container support may omit this. */
+    packages?: PackageLayout[];
+    width: number;
+    height: number;
+}
+export interface LayoutEngine {
+    layout(model: PlantUmlModel): Promise<LayoutResult>;
+}
+/**
+ * Shared drawing metrics. The renderer reads these so entity sizing and the
+ * emitted SVG stay in lockstep: the font family and size are bound to the same
+ * monospace advance [[../text-measure]] measures with.
+ */
+export declare const METRICS: {
+    readonly fontFamily: "monospace";
+    readonly fontSize: 13;
+    readonly lineHeight: 18;
+    readonly paddingX: 10;
+    readonly paddingY: 8;
+    readonly minWidth: 60;
+};
+/**
+ * Package label-tab geometry, shared by the renderer and the layout-metrics
+ * overlap counter so a drawn tab and a measured tab are the same rectangle.
+ */
+export declare const PACKAGE_LABEL: {
+    readonly tabHeight: 20;
+    readonly fontSize: 12;
+    readonly tabPadding: 8;
+};
+/** Spacing grid (px). Entity box sizes snap up to a multiple of it. */
+export declare const GRID = 8;
+export declare function snapUp(n: number, grid?: number): number;
+/** Reconstruct the name drawn in the title compartment, generics expanded. */
+export declare function displayName(entity: PlantUmlEntity): string;
+/**
+ * Approximate the on-canvas size of an entity box. The title plus every member
+ * line contributes one row; the width is the longest rendered line measured
+ * through the text table plus padding, never below MIN_WIDTH.
+ */
+export declare function estimateEntitySize(entity: PlantUmlEntity): {
+    width: number;
+    height: number;
+};
+/**
+ * Level of member detail drawn per entity: every member (`full`), the first
+ * few plus a count (`compact`), or just the class name (`names`).
+ */
+export type DetailLevel = 'full' | 'compact' | 'names';
+/** Entity count up to which `full` is chosen automatically. */
+export declare const DETAIL_FULL_MAX_ENTITIES = 40;
+/** Entity count up to which `compact` is chosen automatically (beyond: `names`). */
+export declare const DETAIL_COMPACT_MAX_ENTITIES = 150;
+/** Member rows kept per entity in `compact` mode. */
+export declare const COMPACT_MEMBER_ROWS = 4;
+export declare function autoDetail(entityCount: number): DetailLevel;
+/**
+ * Reduce member rows to the requested detail level *before* layout, so boxes
+ * are sized for what is actually drawn. `undefined` picks by entity count.
+ */
+export declare function applyDetail(model: PlantUmlModel, detail?: DetailLevel): PlantUmlModel;
+/**
+ * Group nodes into rows: within one package (or the top level), nodes whose
+ * vertical extents overlap belong to the same layered-layout rank. Returns
+ * arrays of node ids, each sorted top-to-bottom.
+ */
+export declare function layoutRows(model: PlantUmlModel, layout: LayoutResult): NodeLayout[][];
+/**
+ * Top-align the nodes of every row (never moving a node down or out of its
+ * package) and keep edges attached: an endpoint on a moved node shifts with it,
+ * dragging along the next bend when the first segment is horizontal, so
+ * orthogonal routes stay orthogonal. Mutates and returns `layout`.
+ */
+export declare function alignRows(model: PlantUmlModel, layout: LayoutResult): LayoutResult;
+/**
+ * Top-align an isolated package frame (no edge touches any entity inside it)
+ * with the topmost side-by-side neighbour frame, so a lone package sits level
+ * with its neighbour instead of floating at its own offset. Only moves up, and
+ * only when the frame (with its contents) stays clear of everything else.
+ * Mutates and returns `layout`.
+ */
+export declare function alignIsolatedFrames(model: PlantUmlModel, layout: LayoutResult): LayoutResult;