@yalehwang/plantuml-js 0.3.0 → 0.3.1

package/dist/core.d.ts

@@ -7,12 +7,12 @@
  * engine + `renderDot`.
  */
 import { PlantUmlModel } from './foundation/model.js';
-import { parsePlantUml } from './parser.js';
+import { parsePlantUml } from './parse/parser.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';
+import { ViewSpec, TransformOptions } from './transform/transform.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';
@@ -191,11 +191,11 @@ export interface LineExplanation {
  */
 export declare function explain(puml: string): LineExplanation[];
 export { parsePlantUml, ElkLayoutEngine, renderSvg, SvgRenderer };
-export { toPlantUml } from './serialize.js';
+export { toPlantUml } from './parse/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 { computeLayoutMetrics } from './metrics/layout-metrics.js';
+export type { LayoutMetrics } from './metrics/layout-metrics.js';
+export { applyView, transformModel, aggregateRelations, transitiveReduce, summarizeHubs, markCycles, groupByPathPrefix, } from './transform/transform.js';
+export type { ViewSpec, TransformOptions } from './transform/transform.js';
 export { archguardToPlantUml, archguardAliasMap, pathName, displayName, ARCHGUARD_RELATION_ARROWS, } from './archguard.js';
 export type { ArchguardNode, ArchguardEdge, ArchguardGraph, ArchguardBridgeOptions, ArchguardPlantUml, } from './archguard.js';

package/dist/core.js

@@ -6,11 +6,11 @@
  * `src/index.ts` is the full build: it re-exports this core and adds the viz
  * engine + `renderDot`.
  */
-import { parsePlantUml, parseWithDiagnostics, ENTITY_LINE, ENTITY_KEYWORD, extractDeclaredName, stripComment } from './parser.js';
+import { parsePlantUml, parseWithDiagnostics, ENTITY_LINE, ENTITY_KEYWORD, extractDeclaredName, stripComment } from './parse/parser.js';
 import { applyDetail } from './foundation/layout.js';
 import { ElkLayoutEngine } from './layout/elk.js';
 import { renderSvg, SvgRenderer, } from './render/svg.js';
-import { applyView, transformModel, transformModelDetailed, shouldAutoReduce, INTER_PACKAGE_AGGREGATE_ENTITY_THRESHOLD } from './transform.js';
+import { applyView, transformModel, transformModelDetailed, shouldAutoReduce, INTER_PACKAGE_AGGREGATE_ENTITY_THRESHOLD } from './transform/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 {
@@ -294,7 +294,7 @@ function classifyLine(raw) {
     return { kind: 'unknown', explanation: 'unrecognised line (ignored)' };
 }
 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 { toPlantUml } from './parse/serialize.js';
+export { computeLayoutMetrics } from './metrics/layout-metrics.js';
+export { applyView, transformModel, aggregateRelations, transitiveReduce, summarizeHubs, markCycles, groupByPathPrefix, } from './transform/transform.js';
 export { archguardToPlantUml, archguardAliasMap, pathName, displayName, ARCHGUARD_RELATION_ARROWS, } from './archguard.js';

package/dist/{render → foundation}/labels.d.ts

@@ -7,9 +7,9 @@
  * 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';
+import { PlantUmlModel, PlantUmlEntity } from './model.js';
+import { LayoutResult, NodeLayout, Point } from './layout.js';
+import { Rect } from './edge-router.js';
 export declare const EDGE_LABEL_FONT_SIZE = 11;
 export declare const HUB_BADGE_RADIUS = 9;
 export interface EdgeLabelPlacement {

package/dist/{render → foundation}/labels.js

@@ -7,9 +7,9 @@
  * 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';
+import { METRICS, displayName } from './layout.js';
+import { nodeRect } from './edge-router.js';
+import { measureTextWidth } from './text-measure.js';
 export const EDGE_LABEL_FONT_SIZE = 11;
 const EDGE_LABEL_PAD_X = 3;
 const EDGE_LABEL_HEIGHT = 14;

package/dist/foundation/layout.d.ts

@@ -2,7 +2,7 @@
  * 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.
+ * engines (ELK, Graphviz, a custom tuner) is an injection, not a rewrite.
  */
 import { PlantUmlModel, PlantUmlEntity } from './model.js';
 export interface Point {

package/dist/foundation/layout.js

@@ -2,7 +2,7 @@
  * 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.
+ * engines (ELK, Graphviz, a custom tuner) is an injection, not a rewrite.
  */
 import { measureTextWidth, MONOSPACE_FONT_SIZE } from './text-measure.js';
 /**

package/dist/index.d.ts

@@ -6,10 +6,10 @@
  * bundle stays free of the Graphviz WASM.
  */
 import { VizLayoutEngine } from './layout/viz.js';
-import { renderDot } from './foundation/render-dot.js';
+import { renderDot } from './layout/render-dot.js';
 import { Renderer, RendererOptions } from './core.js';
 export * from './core.js';
-export type { GraphvizEngine } from './foundation/render-dot.js';
+export type { GraphvizEngine } from './layout/render-dot.js';
 export { renderDot, VizLayoutEngine };
 /**
  * Build a renderer. `layout` is `'elk'` (default), `'viz'` (experimental), or a

package/dist/index.js

@@ -6,7 +6,7 @@
  * bundle stays free of the Graphviz WASM.
  */
 import { VizLayoutEngine } from './layout/viz.js';
-import { renderDot } from './foundation/render-dot.js';
+import { renderDot } from './layout/render-dot.js';
 import { createRenderer as createCoreRenderer, } from './core.js';
 export * from './core.js';
 export { renderDot, VizLayoutEngine };

package/dist/layout/compound.d.ts

@@ -15,10 +15,25 @@ import type { PlantUmlModel } from '../foundation/model.js';
 import { type LayoutResult } from '../foundation/layout.js';
 import { type BoxPlacementContext, type PlacementStrategy, type PlacementStrategyOptions, type StubOrbit } from './placement-strategy.js';
 export type { StubOrbit } from './placement-strategy.js';
+/**
+ * Entity count above which the compound layout switches to its cheaper
+ * large-graph mode (see [[CompoundOptions.largeGraphThreshold]]).
+ *
+ * The cross-block router's A* cost grows with the lattice area, i.e. with the
+ * canvas the compound pack produced — 0.3.0 measured a 2000-node nested graph
+ * at ~282 s against 1.2 s at 300 nodes. The 800-node point is the knee of that
+ * curve in the reported scale ladder (500 ≈ 1.4 s, 800 ≈ 4-7 s, 2000 ≈ 282 s).
+ */
+export declare const DEFAULT_LARGE_GRAPH_THRESHOLD = 800;
 export interface CompoundOptions extends PlacementStrategyOptions {
     edgeRouting?: string;
     /** Rip-up passes of the cross-block router; its default when omitted. */
     ripupPasses?: number;
+    /**
+     * Entity count above which the cross-block router degrades to a coarser
+     * lattice with no rip-up passes. Default [[DEFAULT_LARGE_GRAPH_THRESHOLD]].
+     */
+    largeGraphThreshold?: number;
     /**
      * Extra block-placement strategies tried, in order, before the built-in
      * chain; the first to return a placement wins (see [[./placement-strategy]]).

package/dist/layout/compound.js

@@ -75,6 +75,27 @@ const HUB_RAIL_MIN_HEIGHT = 400;
 const CANVAS_MARGIN = 40;
 /** Node gap inside packed blocks of a dense (very large) graph; leaves one routing lane. */
 const DENSE_NODE_SPACING = 36;
+/**
+ * Entity count above which the compound layout switches to its cheaper
+ * large-graph mode (see [[CompoundOptions.largeGraphThreshold]]).
+ *
+ * The cross-block router's A* cost grows with the lattice area, i.e. with the
+ * canvas the compound pack produced — 0.3.0 measured a 2000-node nested graph
+ * at ~282 s against 1.2 s at 300 nodes. The 800-node point is the knee of that
+ * curve in the reported scale ladder (500 ≈ 1.4 s, 800 ≈ 4-7 s, 2000 ≈ 282 s).
+ */
+export const DEFAULT_LARGE_GRAPH_THRESHOLD = 800;
+/**
+ * Lattice pitch of the large-graph router. The default pitch is tied to the
+ * canvas area and becomes very fine on a big canvas (one lattice vertex every
+ * ~9-20 px), which makes every A* search explore hundreds of thousands of
+ * states. A coarser lattice cuts that by roughly the square of the pitch ratio
+ * while still leaving the 64 px gutters between blocks routable. 22 px is the
+ * coarsest value that still finds a terminal vertex outside every node in the
+ * dense nested fixtures; at 24 px a small package can sit entirely between
+ * lattice rows and the router falls back to a node-crossing dog-leg.
+ */
+const LARGE_GRAPH_ROUTER_PITCH = 22;
 /** Tightest gap between neighbouring stubs on the rail, px. */
 const RAIL_MIN_GAP = 24;
 /** Lattice cost of crossing a wire in a view with stub rails (their fans are crossing-prone), and elsewhere. */
@@ -198,12 +219,17 @@ export async function compoundLayout(elk, model, options) {
         target: model.relations[index].target,
         points,
     }));
+    // Large graphs route on a coarser lattice and skip the rip-up refinement:
+    // the A* search is the superlinear term (see DEFAULT_LARGE_GRAPH_THRESHOLD),
+    // and both knobs trade routing polish for a bounded layout time.
+    const large = model.entities.length > (options.largeGraphThreshold ?? DEFAULT_LARGE_GRAPH_THRESHOLD);
     const routed = routeOrthogonal(requests, nodes, {
         width: placed.width,
         height: placed.height,
         frames: packagesOut,
         existing: drawn,
-        ripupPasses: options.ripupPasses,
+        ripupPasses: large ? 0 : options.ripupPasses,
+        pitch: large ? LARGE_GRAPH_ROUTER_PITCH : undefined,
         crossingCost: model.entities.some((e) => e.stub) ? STUB_CROSSING_COST : CROSSING_COST,
     });
     for (const [id, points] of routed)

package/dist/layout/elk.d.ts

@@ -61,6 +61,21 @@ export interface ElkLayoutOptions {
      * desktop panel or 9/16 for a portrait phone. Default 1.6.
      */
     aspectRatio?: number;
+    /**
+     * Entity count above which the compound layout degrades to its cheaper
+     * large-graph mode: the cross-block router uses a coarser lattice with no
+     * rip-up passes, the dependency-ordered block packing is not retried with
+     * rect-packing, and the cosmetic edge-polishing passes (fan-out bundling,
+     * trunk straightening, un-coiling) are skipped. Those passes run A* and
+     * O(edges) crossing scans per candidate edge, which grows superlinearly with
+     * the canvas area — the 0.3.0 nested 2000-node graph measured ~282 s at the
+     * default and is bounded above this threshold.
+     *
+     * Default 800, the knee between the reported 800-node (~4-7 s) and
+     * 2000-node (~282 s) measurements. Set to `Infinity` to keep the full
+     * polishing pipeline at every scale.
+     */
+    largeGraphThreshold?: number;
     /**
      * Extra layout strategies tried, in order, before the built-in decision
      * chain; the first to return a result wins (see [[./strategy]]).
@@ -111,6 +126,8 @@ export declare class ElkLayoutEngine implements LayoutEngine {
      */
     private layoutToward;
     private compound;
+    /** Entity count above which the cheap large-graph pipeline is used. */
+    private isLargeGraph;
     /** One ELK run over the whole nested graph (`INCLUDE_CHILDREN`). */
     private hierarchicalLayout;
 }

package/dist/layout/elk.js

@@ -36,8 +36,8 @@
  */
 import ELKDefault from 'elkjs';
 import { alignRows, alignIsolatedFrames } from '../foundation/layout.js';
-import { compoundLayout } from './compound.js';
-import { computeLayoutMetrics, computeMaxEmptyBlockRatio } from './layout-metrics.js';
+import { compoundLayout, DEFAULT_LARGE_GRAPH_THRESHOLD } from './compound.js';
+import { computeLayoutMetrics, computeMaxEmptyBlockRatio } from '../metrics/layout-metrics.js';
 import { resolveLayerOrder, assignPartitions } from '../foundation/layers.js';
 import { buildElkGraph } from './elk-graph.js';
 import { clipPackageEndpoints } from './package-endpoints.js';
@@ -148,9 +148,16 @@ export class ElkLayoutEngine {
         this.options = options;
     }
     async layout(model) {
-        const finish = (raw) => fitCanvas(liftFlushSegments(
-        // stub views price crossings high on purpose: their rail edges are not un-coiled
-        (model.entities.some((e) => e.stub) ? (l) => l : uncoilWraps)(straightenTrunkDetours(mergeFanoutTrunks(model, spreadParallelLanes(clipPackageEndpoints(model, alignIsolatedFrames(model, alignRows(model, raw)))))))));
+        const large = this.isLargeGraph(model);
+        const spread = (raw) => spreadParallelLanes(clipPackageEndpoints(model, alignIsolatedFrames(model, alignRows(model, raw))));
+        // The edge-polishing passes are quadratic-ish in the canvas size (per-edge
+        // A* plus all-pairs crossing scans) and cannot be bounded by any budget on
+        // a 2000-node nested canvas, so a large graph keeps the raw compound
+        // geometry and only gets the cheap passes.
+        const finish = (raw) => fitCanvas(liftFlushSegments(large
+            ? spread(raw)
+            : // stub views price crossings high on purpose: their rail edges are not un-coiled
+                (model.entities.some((e) => e.stub) ? (l) => l : uncoilWraps)(straightenTrunkDetours(mergeFanoutTrunks(model, spread(raw))))));
         if (!model.entities.some((e) => e.stub))
             return finish((await this.layoutRaw(model)).layout);
         // Where the orbiting stubs sit decides how the router weaves their edges
@@ -239,6 +246,7 @@ export class ElkLayoutEngine {
     }
     async compound(model, layers, partitions, { orbit, quick }) {
         const dense = model.entities.length > COMPOUND_ENTITY_THRESHOLD;
+        const large = this.isLargeGraph(model);
         const run = (rectPackDense) => compoundLayout(this.elk, model, {
             edgeRouting: this.options.edgeRouting,
             aspectRatio: this.options.aspectRatio,
@@ -248,15 +256,22 @@ export class ElkLayoutEngine {
             partitions: layers.length > 0 ? partitions : new Map(),
             stubOrbit: orbit,
             ripupPasses: quick ? 0 : undefined,
+            largeGraphThreshold: this.options.largeGraphThreshold,
         });
         const ordered = await run(false);
         // Dependency-ordered rows cost canvas on very large graphs; past the budget
-        // fall back to the tighter (order-blind) rect packing.
-        if (dense && ordered.width * ordered.height > COMPOUND_AREA_BUDGET) {
+        // fall back to the tighter (order-blind) rect packing. A large graph skips
+        // the retry: laying every nested block out twice doubles the dominant cost
+        // for a canvas-area gain that the large-graph router no longer needs.
+        if (!large && dense && ordered.width * ordered.height > COMPOUND_AREA_BUDGET) {
             return { layout: await run(true), orbited: true };
         }
         return { layout: ordered, orbited: true };
     }
+    /** Entity count above which the cheap large-graph pipeline is used. */
+    isLargeGraph(model) {
+        return model.entities.length > (this.options.largeGraphThreshold ?? DEFAULT_LARGE_GRAPH_THRESHOLD);
+    }
     /** One ELK run over the whole nested graph (`INCLUDE_CHILDREN`). */
     async hierarchicalLayout(model, layers, partitions) {
         const graph = buildElkGraph(model, layers, partitions, {

package/dist/layout/fanout-trunk.js

@@ -11,7 +11,7 @@
  * same direction, the second across) take part — the shape both ELK and the
  * grid router give a plain fan-out. Anything else in the group is left alone.
  */
-import { findParallelBundles } from './layout-metrics.js';
+import { findParallelBundles } from '../metrics/layout-metrics.js';
 import { routeOrthogonal } from './grid-router.js';
 /** Edges leaving (or entering) one side that make a group worth merging. */
 export const TRUNK_MIN_EDGES = 5;

package/dist/layout/trunk-lanes.js

@@ -9,7 +9,7 @@
  * no unrelated node or package frame, and adds at most [[EXTRA_CROSSINGS]] crossings.
  */
 import { routeOrthogonal } from './grid-router.js';
-import { findParallelBundles } from './layout-metrics.js';
+import { findParallelBundles } from '../metrics/layout-metrics.js';
 /** Path length ÷ Manhattan distance above which an edge is considered for a Z. */
 const DETOUR_FACTOR = 2;
 /** Clearance between a Z segment and an unrelated node box. */

package/dist/layout/viz.d.ts

@@ -13,7 +13,7 @@
  */
 import { PlantUmlModel } from '../foundation/model.js';
 import { LayoutEngine, LayoutResult } from '../foundation/layout.js';
-import { GraphvizEngine } from '../foundation/render-dot.js';
+import { GraphvizEngine } from './render-dot.js';
 export declare class VizLayoutEngine implements LayoutEngine {
     private readonly graphvizEngine;
     constructor(graphvizEngine?: GraphvizEngine);

package/dist/layout/viz.js

@@ -12,7 +12,7 @@
  * engine and the SVG renderer already speak.
  */
 import { PACKAGE_LABEL, displayName, estimateEntitySize, } from '../foundation/layout.js';
-import { getViz } from '../foundation/render-dot.js';
+import { getViz } from './render-dot.js';
 import { measureTextWidth } from '../foundation/text-measure.js';
 import { relationSemantics } from '../foundation/relation-semantics.js';
 const POINTS_PER_INCH = 72;

package/dist/{layout → metrics}/layout-metrics.js

@@ -11,7 +11,7 @@
 import { METRICS, PACKAGE_LABEL, displayName } from '../foundation/layout.js';
 import { countEdgeBoxIntersections, countNonOrthogonalSegments, nodeRect } from '../foundation/edge-router.js';
 import { measureTextWidth } from '../foundation/text-measure.js';
-import { entityTextRects, hubBadgeRect, placeEdgeLabels, rectHitsOtherEdge, rectsIntersect, } from '../render/labels.js';
+import { entityTextRects, hubBadgeRect, placeEdgeLabels, rectHitsOtherEdge, rectsIntersect, } from '../foundation/labels.js';
 const registry = [];
 /** Register a metric; the next [[computeLayoutMetrics]] call reports it. */
 export function registerMetric(metric) {

package/dist/{parser.d.ts → parse/parser.d.ts}

@@ -7,7 +7,7 @@
  * generics (`List~Item~`, `BaseEntity<T>`), package/namespace grouping,
  * aliases, and tolerant skipping of skinparam/hide/note directives.
  */
-import { PlantUmlModel } from './foundation/model.js';
+import { PlantUmlModel } from '../foundation/model.js';
 export declare const ENTITY_LINE: RegExp;
 export declare const ENTITY_KEYWORD: RegExp;
 /**

package/dist/{parser.js → parse/parser.js}

@@ -7,7 +7,7 @@
  * generics (`List~Item~`, `BaseEntity<T>`), package/namespace grouping,
  * aliases, and tolerant skipping of skinparam/hide/note directives.
  */
-import { emptyModel, } from './foundation/model.js';
+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 = {

package/dist/{serialize.d.ts → parse/serialize.d.ts}

@@ -19,7 +19,7 @@
  * as n0`), so names carrying a stereotype prefix or `/` path separators survive
  * the round trip as authored.
  */
-import type { PlantUmlModel } from './foundation/model.js';
+import type { PlantUmlModel } from '../foundation/model.js';
 /**
  * Serialize a model to `@startuml … @enduml` class-diagram source.
  *

package/dist/render/svg.js

@@ -5,7 +5,7 @@
  */
 import { METRICS, PACKAGE_LABEL, displayName, } from '../foundation/layout.js';
 import { measureTextWidth } from '../foundation/text-measure.js';
-import { hubBadgeCircle, placeEdgeLabels, EDGE_LABEL_FONT_SIZE } from './labels.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';

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 './foundation/model.js';
+import { PlantUmlModel } from '../foundation/model.js';
 /** Options driving the model-transform pipeline. */
 export interface TransformOptions {
     /**

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

@@ -9,7 +9,7 @@
  * 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';
+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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yalehwang/plantuml-js",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Pure-TypeScript PlantUML class diagram renderer (MIT)",
   "type": "module",
   "license": "MIT",