@yalehwang/plantuml-js 0.0.0-stage → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yale Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @yalehwang/plantuml-js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pure-TypeScript PlantUML **class diagram** renderer (MIT). Renders `.puml`
+class diagrams to SVG with a pluggable layout engine — `elkjs` (pure JS) by
+default, `@viz-js/viz` (WASM Graphviz) as an option.
+
+> **Engine status** — `'viz'` is **experimental**. It reaches only a fraction
+> of `'elk'`'s area utilization and still routes a few edges through unrelated
+> nodes on large package diagrams. See [`docs/viz-decision.md`](docs/viz-decision.md)
+> for the measured comparison. Use `'elk'` (the default) for production diagrams.
+
+## Install
+
+```bash
+npm install @yalehwang/plantuml-js
+```
+
+## Usage
+
+```ts
+import { createRenderer } from '@yalehwang/plantuml-js';
+
+const renderer = createRenderer({ layout: 'elk' }); // or 'viz' (experimental)
+const { svg, diagramType, warnings } = await renderer.render(`
+@startuml
+class A
+@enduml
+`);
+```
+
+A minimal runnable example (works in Node 18+ and browsers with a bundler):
+
+```js
+import { createRenderer } from '@yalehwang/plantuml-js';
+
+const renderer = createRenderer({ layout: 'viz' });
+const { svg } = await renderer.render('@startuml\nclass A\nclass B\n@enduml');
+console.log(svg);
+// <svg xmlns="http://www.w3.org/2000/svg" ...><rect .../></svg>
+```
+
+## Status
+
+- **M1** — scaffolding, class-subset parser, PlantUmlModel IR, elkjs layout,
+  SVG emission. `render("@startuml\nclass A\n@enduml")` produces a correct SVG.
+- **M2** — members / relations / generics / package grouping / aliases,
+  orthogonal edge routing, text metrics.
+- **M3** — `@viz-js/viz` engine, API polish, npm publish.
+
+## API
+
+| Function | Description |
+|---|---|
+| `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. |
+| `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. |
+
+### Error semantics
+
+`createRenderer` fails closed on an unknown layout name (`'elk'`, `'viz'`, or a
+`LayoutEngine` instance only), and `render` throws a `RenderError` whose
+`diagnostics` carry the offending line numbers. `checkSyntax` reports the same
+problems as structured data instead of throwing.
+
+## License
+
+MIT

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,286 @@
+# Third-Party Licenses
+
+`@yalehwang/plantuml-js` is distributed under the MIT license. This file lists
+third-party software the package depends on, together with the license terms
+under which each is distributed.
+
+## elkjs
+
+- **Package**: `elkjs`
+- **Version**: 0.12.0
+- **License**: `EPL-2.0` — SPDX `EPL-2.0 OR GPL-3.0-or-later`. This project
+  elects the **EPL-2.0** option (not the GPL-3.0 option).
+- **Copyright**: Copyright (c) the elkjs contributors — Kiel University,
+  TypeFox, and others.
+- **Source**: https://github.com/kieler/elkjs
+- **Usage**: standalone npm dependency used for layered graph layout. It is
+  installed via npm and is **not** vendored, copied, or modified into this
+  package's source; it is distributed unmodified under EPL-2.0.
+
+The full EPL-2.0 license text follows.
+
+---
+
+# Eclipse Public License - v 2.0
+
+THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE
+PUBLIC LICENSE (“AGREEMENT”). ANY USE, REPRODUCTION OR DISTRIBUTION OF
+THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.
+
+## 1. DEFINITIONS
+
+“Contribution” means:
+
+-   a\) in the case of the initial Contributor, the initial content
+    Distributed under this Agreement, and
+-   b\) in the case of each subsequent Contributor:
+    -   i\) changes to the Program, and
+    -   ii\) additions to the Program;
+
+    where such changes and/or additions to the Program originate from
+    and are Distributed by that particular Contributor. A Contribution
+    “originates” from a Contributor if it was added to the Program by
+    such Contributor itself or anyone acting on such Contributor's
+    behalf. Contributions do not include changes or additions to the
+    Program that are not Modified Works.
+
+“Contributor” means any person or entity that Distributes the Program.
+
+“Licensed Patents” mean patent claims licensable by a Contributor which
+are necessarily infringed by the use or sale of its Contribution alone
+or when combined with the Program.
+
+“Program” means the Contributions Distributed in accordance with this
+Agreement.
+
+“Recipient” means anyone who receives the Program under this Agreement
+or any Secondary License (as applicable), including Contributors.
+
+“Derivative Works” shall mean any work, whether in Source Code or other
+form, that is based on (or derived from) the Program and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship.
+
+“Modified Works” shall mean any work in Source Code or other form that
+results from an addition to, deletion from, or modification of the
+contents of the Program, including, for purposes of clarity any new file
+in Source Code form that contains any contents of the Program. Modified
+Works shall not include works that contain only declarations,
+interfaces, types, classes, structures, or files of the Program solely
+in each case in order to link to, bind by name, or subclass the Program
+or Modified Works thereof.
+
+“Distribute” means the acts of a) distributing or b) making available in
+any manner that enables the transfer of a copy.
+
+“Source Code” means the form of a Program preferred for making
+modifications, including but not limited to software source code,
+documentation source, and configuration files.
+
+“Secondary License” means either the GNU General Public License, Version
+2.0, or any later versions of that license, including any exceptions or
+additional permissions as identified by the initial Contributor.
+
+## 2. GRANT OF RIGHTS
+
+-   a\) Subject to the terms of this Agreement, each Contributor hereby
+    grants Recipient a non-exclusive, worldwide, royalty-free copyright
+    license to reproduce, prepare Derivative Works of, publicly display,
+    publicly perform, Distribute and sublicense the Contribution of such
+    Contributor, if any, and such Derivative Works.
+-   b\) Subject to the terms of this Agreement, each Contributor hereby
+    grants Recipient a non-exclusive, worldwide, royalty-free patent license
+    under Licensed Patents to make, use, sell, offer to sell, import and
+    otherwise transfer the Contribution of such Contributor, if any, in
+    Source Code or other form. This patent license shall apply to the
+    combination of the Contribution and the Program if, at the time the
+    Contribution is added by the Contributor, such addition of the
+    Contribution causes such combination to be covered by the
+    Licensed Patents. The patent license shall not apply to any other
+    combinations which include the Contribution. No hardware per se is
+    licensed hereunder.
+-   c\) Recipient understands that although each Contributor grants the
+    licenses to its Contributions set forth herein, no assurances are
+    provided by any Contributor that the Program does not infringe the
+    patent or other intellectual property rights of any other entity. Each
+    Contributor disclaims any liability to Recipient for claims brought by
+    any other entity based on infringement of intellectual property rights
+    or otherwise. As a condition to exercising the rights and licenses
+    granted hereunder, each Recipient hereby assumes sole responsibility to
+    secure any other intellectual property rights needed, if any. For
+    example, if a third party patent license is required to allow Recipient
+    to Distribute the Program, it is Recipient's responsibility to acquire
+    that license before distributing the Program.
+-   d\) Each Contributor represents that to its knowledge it has sufficient
+    copyright rights in its Contribution, if any, to grant the copyright
+    license set forth in this Agreement.
+-   e\) Notwithstanding the terms of any Secondary License, no Contributor
+    makes additional grants to any Recipient (other than those set forth in
+    this Agreement) as a result of such Recipient's receipt of the Program
+    under the terms of a Secondary License (if permitted under the terms of
+    Section 3).
+
+## 3. REQUIREMENTS
+
+3.1 If a Contributor Distributes the Program in any form, then:
+
+-   a\) the Program must also be made available as Source Code, in accordance
+    with section 3.2, and the Contributor must accompany the Program with a
+    statement that the Source Code for the Program is available under this
+    Agreement, and informs Recipients how to obtain it in a reasonable
+    manner on or through a medium customarily used for software exchange;
+    and
+-   b\) the Contributor may Distribute the Program under a license different
+    than this Agreement, provided that such license:
+    -   i\) effectively disclaims on behalf of all other Contributors all
+        warranties and conditions, express and implied, including warranties or
+        conditions of title and non-infringement, and implied warranties or
+        conditions of merchantability and fitness for a particular purpose;
+    -   ii\) effectively excludes on behalf of all other Contributors all
+        liability for damages, including direct, indirect, special, incidental
+        and consequential damages, such as lost profits;
+    -   iii\) does not attempt to limit or alter the recipients' rights in the
+        Source Code under section 3.2; and
+    -   iv\) requires any subsequent distribution of the Program by any party to
+        be under a license that satisfies the requirements of this section 3.
+
+3.2 When the Program is Distributed as Source Code:
+
+-   a\) it must be made available under this Agreement, or if the Program (i)
+    is combined with other material in a separate file or files made
+    available under a Secondary License, and (ii) the initial Contributor
+    attached to the Source Code the notice described in Exhibit A of this
+    Agreement, then the Program may be made available under the terms of
+    such Secondary Licenses, and
+-   b\) a copy of this Agreement must be included with each copy of
+    the Program.
+
+3.3 Contributors may not remove or alter any copyright, patent,
+trademark, attribution notices, disclaimers of warranty, or limitations
+of liability (‘notices’) contained within the Program from any copy of
+the Program which they Distribute, provided that Contributors may add
+their own appropriate notices.
+
+## 4. COMMERCIAL DISTRIBUTION
+
+Commercial distributors of software may accept certain responsibilities
+with respect to end users, business partners and the like. While this
+license is intended to facilitate the commercial use of the Program, the
+Contributor who includes the Program in a commercial product offering
+should do so in a manner which does not create potential liability for
+other Contributors. Therefore, if a Contributor includes the Program in
+a commercial product offering, such Contributor (“Commercial
+Contributor”) hereby agrees to defend and indemnify every other
+Contributor (“Indemnified Contributor”) against any losses, damages and
+costs (collectively “Losses”) arising from claims, lawsuits and other
+legal actions brought by a third party against the Indemnified
+Contributor to the extent caused by the acts or omissions of such
+Commercial Contributor in connection with its distribution of the
+Program in a commercial product offering. The obligations in this
+section do not apply to any claims or Losses relating to any actual or
+alleged intellectual property infringement. In order to qualify, an
+Indemnified Contributor must: a) promptly notify the Commercial
+Contributor in writing of such claim, and b) allow the Commercial
+Contributor to control, and cooperate with the Commercial Contributor
+in, the defense and any related settlement negotiations. The Indemnified
+Contributor may participate in any such claim at its own expense.
+
+For example, a Contributor might include the Program in a commercial
+product offering, Product X. That Contributor is then a Commercial
+Contributor. If that Commercial Contributor then makes performance
+claims, or offers warranties related to Product X, those performance
+claims and warranties are such Commercial Contributor's responsibility
+alone. Under this section, the Commercial Contributor would have to
+defend claims against the other Contributors related to those
+performance claims and warranties, and if a court requires any other
+Contributor to pay any damages as a result, the Commercial Contributor
+must pay those damages.
+
+## 5. NO WARRANTY {#warranty}
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN “AS IS”
+BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR
+IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF
+TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+PURPOSE. Each Recipient is solely responsible for determining the
+appropriateness of using and distributing the Program and assumes all
+risks associated with its exercise of rights under this Agreement,
+including but not limited to the risks and costs of program errors,
+compliance with applicable laws, damage to or loss of data, programs or
+equipment, and unavailability or interruption of operations.
+
+## 6. DISCLAIMER OF LIABILITY {#disclaimer}
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS
+SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST
+PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE
+EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+## 7. GENERAL
+
+If any provision of this Agreement is invalid or unenforceable under
+applicable law, it shall not affect the validity or enforceability of
+the remainder of the terms of this Agreement, and without further action
+by the parties hereto, such provision shall be reformed to the minimum
+extent necessary to make such provision valid and enforceable.
+
+If Recipient institutes patent litigation against any entity (including
+a cross-claim or counterclaim in a lawsuit) alleging that the Program
+itself (excluding combinations of the Program with other software or
+hardware) infringes such Recipient's patent(s), then such Recipient's
+rights granted under Section 2(b) shall terminate as of the date such
+litigation is filed.
+
+All Recipient's rights under this Agreement shall terminate if it fails
+to comply with any of the material terms or conditions of this Agreement
+and does not cure such failure in a reasonable period of time after
+becoming aware of such noncompliance. If all Recipient's rights under
+this Agreement terminate, Recipient agrees to cease use and distribution
+of the Program as soon as reasonably practicable. However, Recipient's
+obligations under this Agreement and any licenses granted by Recipient
+relating to the Program shall continue and survive.
+
+Everyone is permitted to copy and distribute copies of this Agreement,
+but in order to avoid inconsistency the Agreement is copyrighted and may
+only be modified in the following manner. The Agreement Steward reserves
+the right to publish new versions (including revisions) of this
+Agreement from time to time. No one other than the Agreement Steward has
+the right to modify this Agreement. The Eclipse Foundation is the
+initial Agreement Steward. The Eclipse Foundation may assign the
+responsibility to serve as the Agreement Steward to a suitable separate
+entity. Each new version of the Agreement will be given a distinguishing
+version number. The Program (including Contributions) may always be
+Distributed subject to the version of the Agreement under which it was
+received. In addition, after a new version of the Agreement is
+published, Contributor may elect to Distribute the Program (including
+its Contributions) under the new version.
+
+Except as expressly stated in Sections 2(a) and 2(b) above, Recipient
+receives no rights or licenses to the intellectual property of any
+Contributor under this Agreement, whether expressly, by implication,
+estoppel or otherwise. All rights in the Program not expressly granted
+under this Agreement are reserved. Nothing in this Agreement is intended
+to be enforceable by any entity that is not a Contributor or Recipient.
+No third-party beneficiary rights are created under this Agreement.
+
+## Exhibit A – Form of Secondary Licenses Notice {#exhibit-a}
+
+“This Source Code may also be made available under the following
+Secondary Licenses when the conditions for such availability set forth
+in the Eclipse Public License, v. 2.0 are satisfied: GNU General Public License v3.0 or later”
+
+> Simply including a copy of this Agreement, including this Exhibit A is
+> not sufficient to license the Source Code under Secondary Licenses.
+>
+> If it is not possible or desirable to put the notice in a particular
+> file, then You may include the notice in a location (such as a LICENSE
+> file in a relevant directory) where a recipient would be likely to
+> look for such a notice.
+>
+> You may add additional accurate notices of copyright ownership.

package/dist/archguard.d.ts

@@ -0,0 +1,76 @@
+/**
+ * ArchGuard neighbourhood-JSON → PlantUML class-diagram bridge.
+ *
+ * Converts ArchGuard's neighbourhood shape
+ *   { nodes: [{ id, label, distance }], edges: [{ from, to, relationType }] }
+ * into a `@startuml … @enduml` string the renderer consumes. `id` is
+ * `<scopeKey>/<relpath>.<EntityName>`; the bridge drops the scopeKey prefix for
+ * display and keeps `relpath.EntityName` (with its `/` separators) so the
+ * renderer's path-prefix overview (`view: {kind:'overview', depth}`) can group
+ * by directory.
+ *
+ * Aliases are stable (`n<i>` by node index), so a filtered subset still
+ * addresses the same node ids. The returned `aliasOf` map (original id →
+ * alias) is what the host uses to link a rendered `data-entity-id` back to the
+ * source node — the renderer draws that alias as the entity id.
+ */
+export interface ArchguardNode {
+    id: string;
+    label: string;
+    distance?: number;
+}
+export interface ArchguardEdge {
+    from: string;
+    to: string;
+    relationType: string;
+}
+export interface ArchguardGraph {
+    nodes: ArchguardNode[];
+    edges: ArchguardEdge[];
+}
+/**
+ * ArchGuard relationType → PlantUML arrow + optional stereotype label.
+ *
+ * Semantics follow the archguard-aligned decision, NOT the renderer's raw
+ * six-way set:
+ *   - `dependency` → Dependency (`..>`, `<<uses>>`)
+ *   - `call`       → Dependency (`..>`, `<<call>>`) — a call is a use, not a
+ *     structural Association
+ *   - `composition` → Aggregation (`o--` hollow diamond) — field-held
+ *     reference, lifecycle unknown; deliberately NOT Composition `*--`
+ *   - `aggregation` → Aggregation (`o--`)
+ *   - `inheritance` → Generalization (`--|>`)
+ *   - `implementation` → Realization (`..|>`)
+ */
+export declare const ARCHGUARD_RELATION_ARROWS: Record<string, {
+    arrow: string;
+    label?: string;
+}>;
+/** Strip the leading `<scopeKey>/` so only the relpath remains. */
+export declare function pathName(id: string): string;
+/**
+ * Display name `relpath.EntityName`, optionally truncated to the last
+ * `maxDirSegments` directory segments (front-truncated, tail + entity kept).
+ * `maxDirSegments = 0` keeps the full path.
+ */
+export declare function displayName(id: string, maxDirSegments?: number): string;
+/** Deterministic alias map: node at index `i` → `n<i>`. */
+export declare function archguardAliasMap(nodes: ArchguardNode[]): Map<string, string>;
+export interface ArchguardBridgeOptions {
+    /**
+     * Stable alias map. Pass the map built over the *full* graph when rendering a
+     * filtered subset, so the subset keeps the original node ids. Defaults to a
+     * fresh map over `graph.nodes`.
+     */
+    aliasOf?: Map<string, string>;
+    /** Display-name truncation passed to {@link displayName}. */
+    maxDirSegments?: number;
+}
+export interface ArchguardPlantUml {
+    /** The generated `@startuml … @enduml` class diagram. */
+    puml: string;
+    /** original id → alias (`n<i>`); use to map a rendered `data-entity-id` back. */
+    aliasOf: Map<string, string>;
+}
+/** Emit a `@startuml … @enduml` class diagram for a (possibly filtered) graph. */
+export declare function archguardToPlantUml(graph: ArchguardGraph, options?: ArchguardBridgeOptions): ArchguardPlantUml;

package/dist/archguard.js

@@ -0,0 +1,103 @@
+/**
+ * ArchGuard neighbourhood-JSON → PlantUML class-diagram bridge.
+ *
+ * Converts ArchGuard's neighbourhood shape
+ *   { nodes: [{ id, label, distance }], edges: [{ from, to, relationType }] }
+ * into a `@startuml … @enduml` string the renderer consumes. `id` is
+ * `<scopeKey>/<relpath>.<EntityName>`; the bridge drops the scopeKey prefix for
+ * display and keeps `relpath.EntityName` (with its `/` separators) so the
+ * renderer's path-prefix overview (`view: {kind:'overview', depth}`) can group
+ * by directory.
+ *
+ * Aliases are stable (`n<i>` by node index), so a filtered subset still
+ * addresses the same node ids. The returned `aliasOf` map (original id →
+ * alias) is what the host uses to link a rendered `data-entity-id` back to the
+ * source node — the renderer draws that alias as the entity id.
+ */
+/**
+ * ArchGuard relationType → PlantUML arrow + optional stereotype label.
+ *
+ * Semantics follow the archguard-aligned decision, NOT the renderer's raw
+ * six-way set:
+ *   - `dependency` → Dependency (`..>`, `<<uses>>`)
+ *   - `call`       → Dependency (`..>`, `<<call>>`) — a call is a use, not a
+ *     structural Association
+ *   - `composition` → Aggregation (`o--` hollow diamond) — field-held
+ *     reference, lifecycle unknown; deliberately NOT Composition `*--`
+ *   - `aggregation` → Aggregation (`o--`)
+ *   - `inheritance` → Generalization (`--|>`)
+ *   - `implementation` → Realization (`..|>`)
+ */
+export const ARCHGUARD_RELATION_ARROWS = {
+    dependency: { arrow: '..>', label: '<<uses>>' },
+    call: { arrow: '..>', label: '<<call>>' },
+    composition: { arrow: 'o--' },
+    aggregation: { arrow: 'o--' },
+    inheritance: { arrow: '--|>' },
+    implementation: { arrow: '..|>' },
+};
+/** Strip the leading `<scopeKey>/` so only the relpath remains. */
+export function pathName(id) {
+    const slash = id.indexOf('/');
+    return slash === -1 ? id : id.slice(slash + 1);
+}
+/**
+ * Display name `relpath.EntityName`, optionally truncated to the last
+ * `maxDirSegments` directory segments (front-truncated, tail + entity kept).
+ * `maxDirSegments = 0` keeps the full path.
+ */
+export function displayName(id, maxDirSegments = 0) {
+    const rel = pathName(id);
+    const dot = rel.lastIndexOf('.');
+    const dirs = dot === -1 ? '' : rel.slice(0, dot);
+    const entity = dot === -1 ? rel : rel.slice(dot + 1);
+    const segments = dirs.split('/').filter(Boolean);
+    if (maxDirSegments > 0 && segments.length > maxDirSegments) {
+        return [...segments.slice(-maxDirSegments), entity].join('/');
+    }
+    return rel;
+}
+/** Deterministic alias map: node at index `i` → `n<i>`. */
+export function archguardAliasMap(nodes) {
+    const aliasOf = new Map();
+    nodes.forEach((node, i) => aliasOf.set(node.id, `n${i}`));
+    return aliasOf;
+}
+/** Escape a name for a quoted PlantUML identifier. */
+function sanitizeName(name) {
+    return name.replace(/["\r\n\t\\]/g, "'").replace(/\s+/g, ' ').trim();
+}
+/** Assign (and remember) a stable alias for a node. */
+function aliasFor(node, index, aliasOf) {
+    const existing = aliasOf.get(node.id);
+    if (existing !== undefined)
+        return existing;
+    let alias = `n${index}`;
+    let k = index;
+    while ([...aliasOf.values()].includes(alias)) {
+        alias = `n${++k}`;
+    }
+    aliasOf.set(node.id, alias);
+    return alias;
+}
+/** Emit a `@startuml … @enduml` class diagram for a (possibly filtered) graph. */
+export function archguardToPlantUml(graph, options = {}) {
+    const aliasOf = options.aliasOf ?? archguardAliasMap(graph.nodes);
+    const maxDirSegments = options.maxDirSegments ?? 0;
+    const lines = ['@startuml'];
+    graph.nodes.forEach((node, i) => {
+        const alias = aliasFor(node, i, aliasOf);
+        lines.push(`class "${sanitizeName(displayName(node.id, maxDirSegments))}" as ${alias}`);
+    });
+    for (const edge of graph.edges) {
+        const source = aliasOf.get(edge.from);
+        const target = aliasOf.get(edge.to);
+        if (source === undefined || target === undefined)
+            continue;
+        const mapping = ARCHGUARD_RELATION_ARROWS[edge.relationType] ?? { arrow: '-->' };
+        const suffix = mapping.label ? ` : ${mapping.label}` : '';
+        lines.push(`${source} ${mapping.arrow} ${target}${suffix}`);
+    }
+    lines.push('@enduml');
+    return { puml: lines.join('\n'), aliasOf };
+}

package/dist/core.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @yalehwang/plantuml-js — viz-free core (the `./elk` subpath export).
+ *
+ * Everything a caller needs to parse, transform and render class diagrams with
+ * the ELK engine, without pulling in `@viz-js/viz` (which ships a ~1MB WASM).
+ * `src/index.ts` is the full build: it re-exports this core and adds the viz
+ * engine + `renderDot`.
+ */
+import { PlantUmlModel } from './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 { 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 interface RendererOptions {
+    /**
+     * `'elk'` (default) | a custom `LayoutEngine` instance. `'viz'` is only
+     * accepted by the full build (`@yalehwang/plantuml-js`); this core entry
+     * fails closed on it.
+     */
+    layout?: 'elk' | 'viz' | LayoutEngine;
+    /** Collapse/expand the diagram before layout (overview, single package, …). */
+    view?: ViewSpec;
+    /** Extra model transforms applied on top of the view (aggregation, cycles, …). */
+    transform?: TransformOptions;
+}
+export interface RenderResult {
+    svg: string;
+    diagramType: string;
+    warnings: string[];
+}
+export interface Renderer {
+    render(puml: string): Promise<RenderResult>;
+}
+/** One structured syntax finding produced by {@link checkSyntax}. */
+export interface SyntaxDiagnostic {
+    /** 1-based line number in the source. */
+    line: number;
+    message: string;
+    severity: 'error' | 'warning';
+}
+/** Result of {@link checkSyntax}: diagnostics, never a thrown exception. */
+export interface SyntaxCheckResult {
+    /** True when no `error`-severity diagnostics were found. */
+    ok: boolean;
+    errors: SyntaxDiagnostic[];
+    warnings: SyntaxDiagnostic[];
+}
+/** Error thrown by {@link createRenderer}'s `render` on structurally invalid puml. */
+export declare class RenderError extends Error {
+    readonly diagnostics: SyntaxDiagnostic[];
+    constructor(diagnostics: SyntaxDiagnostic[]);
+}
+export declare function createRenderer(options?: RendererOptions): Renderer;
+/**
+ * Entity count at or above which the default full-graph render enables hub
+ * summarization. Smaller models stay untouched so a hand-authored diagram is
+ * drawn exactly as written.
+ */
+export declare const FULL_GRAPH_HUB_NODE_THRESHOLD = 40;
+/**
+ * Distinct-source in-degree above which a node's incoming edges are summarized
+ * into a `usageCount` badge in the default full-graph render. 6 summarizes the
+ * archguard package diagram's shared-infrastructure hubs (`src/types`,
+ * `src/types/extensions`, `src/core/interfaces`, plus the other nodes with 8+
+ * distinct dependents) while leaving ordinary modules drawn edge-by-edge.
+ */
+export declare const FULL_GRAPH_HUB_IN_DEGREE_THRESHOLD = 6;
+/**
+ * The transform pipeline the renderer applies to a full (unviewed) model by
+ * default: aggregate parallel edges, summarize hubs on large graphs, and mark
+ * cycle feedback arcs. `overrides` (a caller-supplied `transform` option) wins
+ * over the defaults, so `{ hubThreshold: undefined }` re-enables per-edge
+ * drawing of the hub's incoming edges.
+ */
+export declare function transformFullGraph(model: PlantUmlModel, overrides?: TransformOptions): PlantUmlModel;
+/**
+ * Validate a puml string without throwing. Returns structured diagnostics for
+ * structurally invalid input (content outside a diagram, unbalanced
+ * `@startuml`/`@enduml`, malformed entity declarations), so callers can surface
+ * line-accurate messages instead of catching an exception.
+ */
+export declare function checkSyntax(puml: string): SyntaxCheckResult;
+/** One per-line explanation produced by {@link explain}. */
+export interface LineExplanation {
+    /** 1-based line number. */
+    line: number;
+    /** The raw source text of the line. */
+    text: string;
+    kind: 'directive' | 'entity' | 'member' | 'relation' | 'package' | 'comment' | 'blank' | 'unknown';
+    /** A human-readable description of what the line means. */
+    explanation: string;
+}
+/**
+ * Explain a puml string line by line, classifying each line (directive, entity,
+ * member, relation, package, comment, blank, or unknown) with a short
+ * 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 { 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';
+export type { ArchguardNode, ArchguardEdge, ArchguardGraph, ArchguardBridgeOptions, ArchguardPlantUml, } from './archguard.js';