libpetri 3.0.0 → 4.0.0

package/README.md

@@ -59,13 +59,61 @@ Use places and transitions for coordination rather than hiding concurrency insid
 |---|---|
 | `libpetri` | Core model, runtime, events, and composition |
 | `libpetri/export` | DOT mapping and rendering |
-| `libpetri/verification` | Structural analysis, state classes, and Z3-backed SMT verification |
+| `libpetri/verification` | Structural analysis, state classes, and SMT verification through the `z3` executable |
 | `libpetri/debug` | Debug protocol and session archives |
-| `libpetri/viewer` | Interactive DOT/SVG viewer |
+| `libpetri/viewer` | Interactive DOT/SVG viewer, the canonical renderer |
+| `libpetri/render-dom` | Thin compatibility wrapper over `libpetri/viewer` |
 | `libpetri/doclet` | TypeDoc integration |
 
 The model supports input, output, read, inhibitor, and reset arcs; immediate, deadline, delayed, window, and exact timing; AND/XOR/timeout routing; environment places; reusable subnets; place fusion; and ν-net identity correlation.
 
+## Visualization
+
+`libpetri/viewer` is the canonical renderer. It lays nodes out with ELK, routes edges orthogonally, and draws the result through Graphviz `nop2`, then adds pan/zoom, cluster collapse, subnet toggling, and filtering. Every first-party surface uses it: the debug UI, the TypeDoc plugin here, the Java javadoc taglet, and the Rust docgen all embed the same bundle, so a net looks the same whichever port documented it.
+
+```typescript
+import { dotExport } from 'libpetri/export';
+import { mount } from 'libpetri/viewer';
+
+const handle = await mount(dotExport(net), document.getElementById('diagram')!, {
+  chrome: true,
+});
+handle.fit();
+```
+
+The viewer is browser-only and declares `@viz-js/viz`, `panzoom`, and `elkjs` as optional peer dependencies, so a headless runtime install does not pull in a rendering stack. Install all three wherever you mount it:
+
+```bash
+npm install @viz-js/viz panzoom elkjs
+```
+
+Without `elkjs` the default layout throws and names the missing peer; `mount(dot, el, { layout: 'graphviz' })` falls back to stock Graphviz layout, which is the one supported way to render without it.
+
+Not every path through the package produces the same picture:
+
+| Path | Layout | Edges |
+|---|---|---|
+| `mount()` from `libpetri/viewer` | ELK placement, ELK routes via `nop2` | orthogonal |
+| `renderDotToContainer()` from `libpetri/render-dom` | delegates to `mount()` | orthogonal |
+| the TypeDoc plugin | embeds the viewer, mounts client-side | orthogonal |
+| `dotToSvg()` from `libpetri/doclet` | stock Graphviz `dot` | diagonal splines |
+| `dotExport()` piped to your own `dot -Tsvg` | stock Graphviz `dot` | diagonal splines |
+
+If a diagram renders with diagonal edges where you expected right angles, it went through one of the bottom two rows, or through a viewer bundle older than 2.10.5. Generated doc pages record which one drew them in `data-libpetri-viewer` on the diagram container.
+
+### TypeDoc plugin
+
+Register the plugin and declare the block tag it reads:
+
+```json
+{
+  "plugin": ["libpetri/doclet"],
+  "blockTags": ["@petrinet"]
+}
+```
+
+An `@petrinet` tag on a symbol that builds or exposes a net renders that net as a diagram in the generated page, with the DOT source in a collapsible block underneath. The viewer bundle is inlined into the HTML, so the output is self-contained and works offline with no `dot` binary and no network access.
+
 ## Build and test
 
 ```bash
@@ -75,6 +123,10 @@ npm run check
 npm test
 ```
 
+## SMT verification needs a `z3` executable
+
+The package does not bundle a solver. `SmtVerifier` runs the `z3` executable found on `PATH` (or named by `LIBPETRI_Z3`), version 4.8.0 or newer, one process per query, so the event loop stays free while it solves; `z3Available()` from `libpetri/verification` tells you whether one resolves, and without it every verification returns `unknown` with a reason naming the command. Set `LIBPETRI_SMT_DUMP` to a directory to keep every SMT-LIB2 script and solver reply. The timeout is per solver invocation. The verification entry is Node-only.
+
 ## Project links
 
 - [Language-agnostic specification](https://github.com/debe/libpetri/blob/main/spec/00-index.md)