@yalehwang/plantuml-js 0.2.2 → 0.3.1

package/dist/render/theme.js

@@ -0,0 +1,99 @@
+/**
+ * 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 const defaultTheme = {
+    font: {
+        family: 'monospace',
+        size: { title: 13, member: 12, packageLabel: 12, edgeLabel: 11, badge: 11 },
+        weight: { title: 'bold', member: 'normal', packageLabel: 'bold' },
+    },
+    color: {
+        canvas: '#ffffff',
+        stroke: '#64748b',
+        strokeStub: '#7c8ba1',
+        nodeFill: '#ffffff',
+        stubFill: '#f1f5f9',
+        textTitle: '#1e293b',
+        textMember: '#475569',
+        textPackage: '#334155',
+        edge: '#5b6a80',
+        edgeWeak: '#566479',
+        labelHalo: '#ffffff',
+        warn: '#3b0a0a',
+        accent: '#475569',
+        accentText: '#ffffff',
+        packageFills: ['#f8fafc', '#f1f5f9', '#eef2f7', '#e8eef5'],
+        packageStroke: '#94a3b8',
+        legendStroke: '#94a3b8',
+    },
+    shape: { nodeRadius: 6, packageRadius: 8, edgeCornerRadius: 6 },
+    stroke: {
+        node: 1,
+        package: 1,
+        edge: 1,
+        arrow: 1,
+        weightStep: 0.5,
+        edgeWidthMax: 4,
+        feedback: 1.5,
+        heavyWeight: 3,
+        opacity: { light: 0.8, medium: 0.9, strong: 1, feedback: 0.95 },
+        edgeNonScaling: true,
+        labelHalo: 3,
+    },
+    dash: { weak: '6,3', stub: '5,3', feedback: '10,3,2,3' },
+    arrow: { triangle: 12, chevron: 10, diamond: 14 },
+    grid: 8,
+};
+/** Merge a partial theme over the defaults (arrays replace, objects merge). */
+export function resolveTheme(overrides) {
+    return mergeDeep(defaultTheme, overrides ?? {});
+}
+function mergeDeep(base, over) {
+    if (over === undefined)
+        return base;
+    if (typeof base === 'object' && base !== null && !Array.isArray(base) &&
+        typeof over === 'object' && over !== null && !Array.isArray(over)) {
+        const out = {};
+        const b = base;
+        const o = over;
+        for (const key of Object.keys(b))
+            out[key] = mergeDeep(b[key], o[key]);
+        return out;
+    }
+    return over;
+}
+/** Every colour value of a theme (for token-membership assertions). */
+export function themeColors(theme) {
+    const out = new Set();
+    for (const v of Object.values(theme.color)) {
+        if (Array.isArray(v))
+            v.forEach((c) => out.add(c));
+        else
+            out.add(v);
+    }
+    return out;
+}
+/** `fg` at `alpha` composited over `bg` (both `#rrggbb`), as a `#rrggbb` colour. */
+export function blendOver(fg, bg, alpha) {
+    const f = parseInt(fg.slice(1), 16);
+    const b = parseInt(bg.slice(1), 16);
+    const mix = (shift) => Math.round(alpha * ((f >> shift) & 255) + (1 - alpha) * ((b >> shift) & 255));
+    return `#${((mix(16) << 16) | (mix(8) << 8) | mix(0)).toString(16).padStart(6, '0')}`;
+}
+/** WCAG relative luminance contrast ratio between two `#rrggbb` colours. */
+export function contrastRatio(a, b) {
+    const la = luminance(a);
+    const lb = luminance(b);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+function luminance(hex) {
+    const n = parseInt(hex.slice(1), 16);
+    const ch = [(n >> 16) & 255, (n >> 8) & 255, n & 255].map((v) => {
+        const s = v / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * ch[0] + 0.7152 * ch[1] + 0.0722 * ch[2];
+}

package/dist/{transform.d.ts → transform/transform.d.ts}

@@ -9,7 +9,7 @@
  * input and produces the same output for the same input, so a transformed
  * render stays byte-for-byte reproducible.
  */
-import { PlantUmlModel } from './model.js';
+import { PlantUmlModel } from '../foundation/model.js';
 /** Options driving the model-transform pipeline. */
 export interface TransformOptions {
     /**
@@ -25,6 +25,12 @@ export interface TransformOptions {
      * hub summarization. Default undefined.
      */
     hubThreshold?: number;
+    /**
+     * `'aggregate'` folds all relations between two packages into one
+     * box-to-box weighted corridor edge; `'raw'` keeps every edge. Default:
+     * `'aggregate'` above [[INTER_PACKAGE_AGGREGATE_ENTITY_THRESHOLD]] entities.
+     */
+    interPackage?: 'aggregate' | 'raw';
     /** Detect cycles and mark one edge per cycle as a `feedback` arc. Default false. */
     cycles?: boolean;
 }
@@ -44,19 +50,59 @@ export type ViewSpec = {
 } | {
     kind: 'package';
     id: string;
+    stubGroupThreshold?: number;
 } | {
     kind: 'neighborhood';
     entity: string;
     hops: number;
 };
+/** Entity count above which inter-package edges aggregate into corridors by default. */
+export declare const INTER_PACKAGE_AGGREGATE_ENTITY_THRESHOLD = 150;
+/** Stub count above which a single-package view groups stubs by name prefix. */
+export declare const DEFAULT_STUB_GROUP_THRESHOLD = 8;
 /**
  * Run the transform pipeline over a model. Order matters: aggregation first
  * (so transitive reduction sees one edge per pair), then reduction, then hub
  * summarization, then cycle marking on the final edge set.
  */
 export declare function transformModel(model: PlantUmlModel, options?: TransformOptions): PlantUmlModel;
+/** [[transformModel]] plus the number of edges the transitive reduction hid. */
+export declare function transformModelDetailed(model: PlantUmlModel, options?: TransformOptions): {
+    model: PlantUmlModel;
+    hiddenTransitive: number;
+};
+/** Edge count ÷ node count above which `edgeReduction: 'auto'` reduces a pure dependency graph. */
+export declare const AUTO_REDUCTION_EDGE_NODE_RATIO = 3;
+/**
+ * Whether `edgeReduction: 'auto'` applies: every relation is bundlable
+ * (dependency/association) and there are more than
+ * [[AUTO_REDUCTION_EDGE_NODE_RATIO]] times as many edges as nodes.
+ */
+export declare function shouldAutoReduce(model: PlantUmlModel): boolean;
+/** Incoming edges at which an external type's edges collapse into a count badge. */
+export declare const EXTERNAL_SUMMARY_MIN_IN_EDGES = 3;
+/** Id of the synthetic package that gathers implicit/external types. */
+export declare const EXTERNAL_PACKAGE_ID = "__external__";
+/**
+ * Implicit/external types (`Error`, `EventEmitter`, …) receive many parallel
+ * edges that would fly across the whole canvas. Once one has `minEdges` or more
+ * incoming relations they are dropped and replaced by a `usageCount` badge that
+ * carries the original incoming-edge count.
+ */
+export declare function summarizeExternals(model: PlantUmlModel, minEdges: number): PlantUmlModel;
+/** Gather top-level external entities into one synthetic External package. */
+export declare function groupExternals(model: PlantUmlModel): PlantUmlModel;
 /** Merge relations sharing (source, target) into one edge with `weight`. */
 export declare function aggregateRelations(model: PlantUmlModel): PlantUmlModel;
+/**
+ * Fold every relation between two different packages into one corridor edge
+ * per ordered package pair: `weight` = number of originals, `descriptions`
+ * keeps each original, and the endpoints are the entities carrying most of the
+ * traffic with `sourcePackageId`/`targetPackageId` set so the layout clips the
+ * edge to the frame boundaries. Intra-package edges and edges touching
+ * package-less entities, or between nested packages, are left as they are.
+ */
+export declare function aggregateInterPackage(model: PlantUmlModel): PlantUmlModel;
 /**
  * Remove a relation A→B when A still reaches B through another path (an edge
  * derivable by transitivity). Only the redundant direct edge is dropped; the
@@ -90,3 +136,11 @@ export declare function applyView(model: PlantUmlModel, view?: ViewSpec): PlantU
  * edges are dropped (they do not cross the collapsed boundary).
  */
 export declare function groupByPathPrefix(model: PlantUmlModel, depth: number): PlantUmlModel;
+/**
+ * Past `threshold` stubs, merge stubs sharing a name prefix into one group stub
+ * (`Src Cli … (×6)`), dropping trailing words until the group count fits (or nothing shortens any
+ * more). The edges to the members of a group collapse onto
+ * the group stub per (entity, direction): `weight` counts the originals and
+ * `descriptions` keeps each one for the edge's `<title>`.
+ */
+export declare function groupStubs(model: Pick<PlantUmlModel, 'entities' | 'relations'>, threshold: number): Pick<PlantUmlModel, 'entities' | 'relations'>;

package/dist/{transform.js → transform/transform.js}

@@ -9,6 +9,11 @@
  * input and produces the same output for the same input, so a transformed
  * render stays byte-for-byte reproducible.
  */
+import { relationSemantics } from '../foundation/relation-semantics.js';
+/** Entity count above which inter-package edges aggregate into corridors by default. */
+export const INTER_PACKAGE_AGGREGATE_ENTITY_THRESHOLD = 150;
+/** Stub count above which a single-package view groups stubs by name prefix. */
+export const DEFAULT_STUB_GROUP_THRESHOLD = 8;
 const ROOT = '__root__';
 function cloneModel(model) {
     return {
@@ -24,23 +29,89 @@ function cloneModel(model) {
  * summarization, then cycle marking on the final edge set.
  */
 export function transformModel(model, options = {}) {
-    const { aggregate = true, transitiveReduction = false, hubThreshold, cycles = false } = options;
+    return transformModelDetailed(model, options).model;
+}
+/** [[transformModel]] plus the number of edges the transitive reduction hid. */
+export function transformModelDetailed(model, options = {}) {
+    const { aggregate = true, transitiveReduction = false, hubThreshold, cycles = false, interPackage = 'raw' } = options;
     let out = cloneModel(model);
+    out = summarizeExternals(out, EXTERNAL_SUMMARY_MIN_IN_EDGES);
     if (aggregate)
         out = aggregateRelations(out);
-    if (transitiveReduction)
+    let hiddenTransitive = 0;
+    if (transitiveReduction) {
+        const before = out.relations.length;
         out = transitiveReduce(out);
+        hiddenTransitive = before - out.relations.length;
+    }
     if (hubThreshold !== undefined)
         out = summarizeHubs(out, hubThreshold);
+    if (interPackage === 'aggregate')
+        out = aggregateInterPackage(out);
     if (cycles)
         out = markCycles(out);
-    return out;
+    return { model: groupExternals(out), hiddenTransitive };
+}
+/** Edge count ÷ node count above which `edgeReduction: 'auto'` reduces a pure dependency graph. */
+export const AUTO_REDUCTION_EDGE_NODE_RATIO = 3;
+/**
+ * Whether `edgeReduction: 'auto'` applies: every relation is bundlable
+ * (dependency/association) and there are more than
+ * [[AUTO_REDUCTION_EDGE_NODE_RATIO]] times as many edges as nodes.
+ */
+export function shouldAutoReduce(model) {
+    if (model.relations.length === 0)
+        return false;
+    if (!model.relations.every((r) => relationSemantics(r.type).isBundlable()))
+        return false;
+    const nodes = model.entities.length;
+    const distinct = new Set(model.relations.map((r) => `${r.source}\u0000${r.target}`)).size;
+    return distinct > AUTO_REDUCTION_EDGE_NODE_RATIO * nodes;
+}
+/** Incoming edges at which an external type's edges collapse into a count badge. */
+export const EXTERNAL_SUMMARY_MIN_IN_EDGES = 3;
+/** Id of the synthetic package that gathers implicit/external types. */
+export const EXTERNAL_PACKAGE_ID = '__external__';
+/**
+ * Implicit/external types (`Error`, `EventEmitter`, …) receive many parallel
+ * edges that would fly across the whole canvas. Once one has `minEdges` or more
+ * incoming relations they are dropped and replaced by a `usageCount` badge that
+ * carries the original incoming-edge count.
+ */
+export function summarizeExternals(model, minEdges) {
+    const incoming = new Map();
+    for (const r of model.relations) {
+        const e = model.entities.find((x) => x.id === r.target);
+        if (e?.external)
+            incoming.set(r.target, (incoming.get(r.target) ?? 0) + (r.weight ?? 1));
+    }
+    const summarized = new Set([...incoming].filter(([, n]) => n >= minEdges).map(([id]) => id));
+    if (summarized.size === 0)
+        return model;
+    return {
+        ...model,
+        entities: model.entities.map((e) => summarized.has(e.id) ? { ...e, usageCount: incoming.get(e.id) } : e),
+        relations: model.relations.filter((r) => !summarized.has(r.target)),
+    };
+}
+/** Gather top-level external entities into one synthetic External package. */
+export function groupExternals(model) {
+    const externals = model.entities.filter((e) => e.external && e.packageId === undefined);
+    if (externals.length < 2 || model.packages.some((p) => p.id === EXTERNAL_PACKAGE_ID)) {
+        return model;
+    }
+    const ids = new Set(externals.map((e) => e.id));
+    return {
+        ...model,
+        entities: model.entities.map((e) => (ids.has(e.id) ? { ...e, packageId: EXTERNAL_PACKAGE_ID } : e)),
+        packages: [...model.packages, { id: EXTERNAL_PACKAGE_ID, name: 'External' }],
+    };
 }
 /** Merge relations sharing (source, target) into one edge with `weight`. */
 export function aggregateRelations(model) {
     const byKey = new Map();
     for (const relation of model.relations) {
-        const key = `${relation.source}\u0000${relation.target}`;
+        const key = `${relation.source}\u0000${relation.target}\u0000${relation.sourcePackageId ?? ''}\u0000${relation.targetPackageId ?? ''}`;
         const existing = byKey.get(key);
         if (existing) {
             existing.weight = (existing.weight ?? 1) + 1;
@@ -51,6 +122,89 @@ export function aggregateRelations(model) {
     }
     return { ...model, relations: [...byKey.values()] };
 }
+/**
+ * Fold every relation between two different packages into one corridor edge
+ * per ordered package pair: `weight` = number of originals, `descriptions`
+ * keeps each original, and the endpoints are the entities carrying most of the
+ * traffic with `sourcePackageId`/`targetPackageId` set so the layout clips the
+ * edge to the frame boundaries. Intra-package edges and edges touching
+ * package-less entities, or between nested packages, are left as they are.
+ */
+export function aggregateInterPackage(model) {
+    const pkgOf = new Map(model.entities.map((e) => [e.id, e.packageId]));
+    const parent = new Map(model.packages.map((p) => [p.id, p.parentId]));
+    const nested = (a, b) => {
+        for (const [x, y] of [[a, b], [b, a]]) {
+            for (let p = parent.get(x); p !== undefined; p = parent.get(p))
+                if (p === y)
+                    return true;
+        }
+        return false;
+    };
+    const groups = new Map();
+    const relations = [];
+    for (const rel of model.relations) {
+        const a = pkgOf.get(rel.source);
+        const b = pkgOf.get(rel.target);
+        if (!a || !b || a === b || nested(a, b) || rel.sourcePackageId || rel.targetPackageId) {
+            relations.push(rel);
+            continue;
+        }
+        const key = `${a}\u0000${b}`;
+        let g = groups.get(key);
+        if (!g) {
+            g = { src: a, dst: b, items: [], srcCount: new Map(), dstCount: new Map(), at: relations.length };
+            groups.set(key, g);
+            relations.push(g);
+        }
+        g.items.push(rel);
+        g.srcCount.set(rel.source, (g.srcCount.get(rel.source) ?? 0) + 1);
+        g.dstCount.set(rel.target, (g.dstCount.get(rel.target) ?? 0) + 1);
+    }
+    const top = (m) => {
+        let best = '';
+        let n = -1;
+        for (const [k, v] of m)
+            if (v > n) {
+                best = k;
+                n = v;
+            }
+        return best;
+    };
+    const out = relations.map((r) => {
+        if (!('items' in r))
+            return r;
+        const types = new Set(r.items.map((i) => i.type));
+        const only = r.items.length === 1 ? r.items[0].type : [...types][0];
+        const type = types.size === 1 && relationSemantics(only).isBundlable() ? only : 'dependency';
+        return {
+            source: top(r.srcCount),
+            target: top(r.dstCount),
+            type,
+            weight: r.items.reduce((sum, i) => sum + (i.weight ?? 1), 0),
+            feedback: r.items.every((i) => i.feedback) || undefined,
+            sourcePackageId: r.src,
+            targetPackageId: r.dst,
+            descriptions: r.items.map((i) => `${i.source} ${ARROWS[i.type]} ${i.target}${i.label ? ` : ${i.label}` : ''}`),
+        };
+    });
+    return { ...model, relations: out.map(dropUndefined) };
+}
+const ARROWS = {
+    inheritance: '--|>',
+    implementation: '..|>',
+    dependency: '..>',
+    association: '-->',
+    aggregation: 'o--',
+    composition: '*--',
+};
+function dropUndefined(r) {
+    const copy = { ...r };
+    for (const k of Object.keys(copy))
+        if (copy[k] === undefined)
+            delete copy[k];
+    return copy;
+}
 /**
  * Remove a relation A→B when A still reaches B through another path (an edge
  * derivable by transitivity). Only the redundant direct edge is dropped; the
@@ -58,37 +212,52 @@ export function aggregateRelations(model) {
  */
 export function transitiveReduce(model) {
     const targets = new Map();
-    for (const relation of model.relations) {
-        const list = targets.get(relation.source);
-        if (list)
-            list.push(relation.target);
-        else
-            targets.set(relation.source, [relation.target]);
-    }
-    const reachable = (start, goal, skipTarget) => {
-        const seen = new Set();
-        const queue = [start];
-        while (queue.length > 0) {
-            const u = queue.shift();
-            for (const v of targets.get(u) ?? []) {
-                if (u === start && v === skipTarget)
-                    continue; // ignore the direct edge under test
+    const addEdge = (u, v) => {
+        const m = targets.get(u) ?? new Map();
+        m.set(v, (m.get(v) ?? 0) + 1);
+        targets.set(u, m);
+    };
+    for (const relation of model.relations)
+        addEdge(relation.source, relation.target);
+    const reachable = (start, goal) => {
+        const seen = new Set([start]);
+        const stack = [start];
+        while (stack.length > 0) {
+            const u = stack.pop();
+            for (const v of targets.get(u)?.keys() ?? []) {
                 if (v === goal)
                     return true;
                 if (!seen.has(v)) {
                     seen.add(v);
-                    queue.push(v);
+                    stack.push(v);
                 }
             }
         }
         return false;
     };
-    const relations = model.relations.filter((relation) => {
-        // A self-loop is its own shortest witness; keep it. A single-hop edge with
-        // no alternate path is necessary; keep it.
-        return !reachable(relation.source, relation.target, relation.target);
+    // Greedy in authored order: an edge is dropped when its end points stay
+    // connected through the edges still present, so reachability is preserved
+    // exactly (also inside cycles, where dropping every "redundant" edge at once
+    // would disconnect the cycle). A self-loop is its own witness and is kept.
+    const removed = new Set();
+    model.relations.forEach((relation, i) => {
+        if (relation.source === relation.target)
+            return;
+        const out = targets.get(relation.source);
+        const count = out.get(relation.target);
+        if (count > 1) {
+            // A parallel duplicate of the same pair is always redundant.
+            out.set(relation.target, count - 1);
+            removed.add(i);
+            return;
+        }
+        out.delete(relation.target);
+        if (reachable(relation.source, relation.target))
+            removed.add(i);
+        else
+            out.set(relation.target, 1);
     });
-    return { ...model, relations };
+    return { ...model, relations: model.relations.filter((_, i) => !removed.has(i)) };
 }
 /**
  * Nodes with an in-degree above `threshold` have their incoming edges dropped
@@ -170,7 +339,7 @@ export function applyView(model, view) {
             }
             return overviewView(model);
         case 'package':
-            return packageView(model, view.id);
+            return packageView(model, view.id, view.stubGroupThreshold ?? DEFAULT_STUB_GROUP_THRESHOLD);
         case 'neighborhood':
             return neighborhoodView(model, view.entity, view.hops);
     }
@@ -276,7 +445,7 @@ export function groupByPathPrefix(model, depth) {
  * merged by aggregation). Entities and relations entirely outside the package
  * are dropped.
  */
-function packageView(model, id) {
+function packageView(model, id, stubGroupThreshold) {
     const pkgById = new Map(model.packages.map((p) => [p.id, p]));
     const selected = pkgById.get(id);
     if (!selected) {
@@ -332,13 +501,92 @@ function packageView(model, id) {
         const stub = stubFor(externalKey);
         relations.push(sourceIn ? { ...relation, target: stub.id } : { ...relation, source: stub.id });
     }
+    const grouped = groupStubs({ entities, relations }, stubGroupThreshold);
     return {
         diagramType: 'class',
-        entities,
-        relations,
+        entities: grouped.entities,
+        relations: grouped.relations,
         packages: [{ ...selected, parentId: undefined }],
     };
 }
+/** Name with its last word dropped (`Src Cli Utils` → `Src Cli`); a one-word name stays as is. */
+function namePrefix(name) {
+    const words = name.trim().split(/\s+/);
+    return words.length > 1 ? words.slice(0, -1).join(' ') : name;
+}
+/**
+ * Past `threshold` stubs, merge stubs sharing a name prefix into one group stub
+ * (`Src Cli … (×6)`), dropping trailing words until the group count fits (or nothing shortens any
+ * more). The edges to the members of a group collapse onto
+ * the group stub per (entity, direction): `weight` counts the originals and
+ * `descriptions` keeps each one for the edge's `<title>`.
+ */
+export function groupStubs(model, threshold) {
+    const stubs = model.entities.filter((e) => e.stub);
+    if (stubs.length <= threshold)
+        return model;
+    let keyOf = new Map(stubs.map((e) => [e.id, e.name]));
+    for (;;) {
+        if (new Set(keyOf.values()).size <= threshold)
+            break;
+        const next = new Map([...keyOf].map(([id, k]) => [id, namePrefix(k)]));
+        if ([...next].every(([id, k]) => k === keyOf.get(id)))
+            break;
+        keyOf = next;
+    }
+    const members = new Map();
+    for (const stub of stubs) {
+        const key = keyOf.get(stub.id);
+        const list = members.get(key);
+        if (list)
+            list.push(stub);
+        else
+            members.set(key, [stub]);
+    }
+    const groupId = new Map();
+    const entities = [];
+    for (const e of model.entities) {
+        if (!e.stub) {
+            entities.push(e);
+            continue;
+        }
+        const key = keyOf.get(e.id);
+        const list = members.get(key);
+        if (list.length === 1) {
+            groupId.set(e.id, e.id);
+            entities.push(e);
+        }
+        else if (list[0] === e) {
+            const id = `stub::group::${key}`;
+            for (const m of list)
+                groupId.set(m.id, id);
+            entities.push({ ...e, id, name: `${list.length} other ${key} packages`, groupMembers: list.map((m) => m.name) });
+        }
+    }
+    const merged = new Map();
+    const out = [];
+    const label = (r) => `${r.source} ${r.type} ${r.target}`;
+    for (const r of model.relations) {
+        const source = groupId.get(r.source) ?? r.source;
+        const target = groupId.get(r.target) ?? r.target;
+        if (source === r.source && target === r.target) {
+            out.push(r);
+            continue;
+        }
+        const key = `${source}\u0000${target}`;
+        const existing = merged.get(key);
+        if (existing) {
+            existing.weight = (existing.weight ?? 1) + (r.weight ?? 1);
+            existing.descriptions.push(...(r.descriptions ?? [label(r)]));
+        }
+        else {
+            const rel = { ...r, source, target, weight: r.weight ?? 1, descriptions: [...(r.descriptions ?? [label(r)])] };
+            merged.set(key, rel);
+            out.push(rel);
+        }
+    }
+    return { entities, relations: out };
+}
 /**
  * Expand one entity plus every entity within `hops` undirected hops, together
  * with the package frames that contain the kept entities.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yalehwang/plantuml-js",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Pure-TypeScript PlantUML class diagram renderer (MIT)",
   "type": "module",
   "license": "MIT",
@@ -34,12 +34,13 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.test.json",
     "test": "vitest run",
     "demo:build": "node scripts/build-demo.mjs",
     "release": "node scripts/release.mjs",
-    "prepublishOnly": "npm run typecheck && npm run build"
+    "prepublishOnly": "npm run typecheck && npm run build && node scripts/check-dist-clean.mjs"
   },
   "dependencies": {
     "@viz-js/viz": "^3.31.0",

package/dist/layout-metrics.d.ts

@@ -1,42 +0,0 @@
-/**
- * Layout quality metrics. Pure functions from (model, layout) to numbers, so a
- * layout strategy change can be judged by a diff in figures rather than by eye.
- *
- * Edge polylines are taken at face value: for the viz engine they are bezier
- * control points, which is a coarse but consistent approximation. Every metric
- * is deterministic — the same (model, layout) always yields the same numbers —
- * so a run can be committed as `rendered/metrics.baseline.json` and diffed
- * against a later run to prove an improvement or a regression.
- */
-import { PlantUmlModel } from './model.js';
-import { LayoutResult } from './layout.js';
-export interface LayoutMetrics {
-    /** Proper crossings between segments of two different edges. */
-    edgeCrossings: number;
-    /** Edge segments passing through the interior of an unrelated node. */
-    edgeNodeIntersections: number;
-    /** Summed polyline length of every edge, in canvas pixels. */
-    totalEdgeLength: number;
-    /** Sum of node areas divided by canvas area (0..1). */
-    areaUtilization: number;
-    /** Canvas width / height. */
-    aspectRatio: number;
-    /** Entity text lines wider than the box they are drawn in. */
-    textOverflowCount: number;
-    /** Package label tabs that overlap content or are narrower than their text. */
-    labelOverlapCount: number;
-    /**
-     * Summed length of collinear, overlapping segments from *different* edges —
-     * the orthogonal router's "parallel-line wall" is invisible to
-     * [[edgeCrossings]] (segments that merely overlap never *cross*), so this
-     * counts that hidden overlap in canvas pixels.
-     */
-    overlappingEdgeLength: number;
-    /**
-     * Incoming arrowheads stacked beyond a threshold on the same side of the
-     * same node — the "everything points at this hub" pile-up that
-     * [[edgeCrossings]] cannot see either.
-     */
-    hubArrowStack: number;
-}
-export declare function computeLayoutMetrics(model: PlantUmlModel, layout: LayoutResult): LayoutMetrics;