libpetri 1.8.4 → 2.0.0

package/dist/doclet/index.d.ts

@@ -1,16 +1,19 @@
 import { Application } from 'typedoc';
-import { a as PetriNet } from '../petri-net-D-GN9g_D.js';
+import { P as PetriNet, S as SubnetDef, o as Instance } from '../petri-net-BDrj4XZE.js';
 
 /**
- * TypeDoc plugin for `@petrinet` tag — auto-generates interactive SVG diagrams
- * from PetriNet definitions and embeds them in TypeDoc output.
+ * TypeDoc plugin for `@petrinet` and `@subnet` tags — auto-generates
+ * interactive SVG diagrams from PetriNet / SubnetDef / Instance definitions
+ * and embeds them in TypeDoc output.
  *
- * Mirrors: `org.libpetri.doclet.PetriNetTaglet`
+ * Mirrors: `org.libpetri.doclet.PetriNetTaglet` + `SubnetTaglet`
  *
  * Plugin lifecycle (TypeDoc hooks):
- * 1. `bootstrapEnd` → register `@petrinet` as known block tag
- * 2. `preRenderAsyncJobs` → walk reflections, resolve nets, generate SVGs, cache HTML
- * 3. `comment.beforeTags` → inject cached HTML via JSX.Raw, skip default rendering
+ * 1. `bootstrapEnd` → register `@petrinet` and `@subnet` as known block tags.
+ * 2. `preRenderAsyncJobs` → walk reflections, resolve references, generate
+ *    SVGs, cache HTML.
+ * 3. `comment.beforeTags` → inject cached HTML via `JSX.Raw`, skip default
+ *    rendering for the recognised tags.
  *
  * @module doclet/petri-net-plugin
  */
@@ -25,33 +28,52 @@ declare function load(app: Application): void;
 /**
  * Shared HTML renderer for Petri Net diagrams in TypeDoc.
  *
- * Generates consistent HTML markup with interactive controls for zoom, pan,
- * and fullscreen functionality. Accepts pre-rendered SVG from `@viz-js/viz`.
+ * Generates consistent HTML markup that mounts the canonical
+ * {@link https://libpetri.org | libpetri} viewer client-side. The viewer IIFE
+ * bundle (Graphviz WASM inlined, offline-safe) is inlined into the generated
+ * HTML, making the plugin fully self-contained with no external file
+ * dependencies.
  *
- * CSS and JS are loaded from bundled resources and inlined into the generated
- * HTML, making the plugin fully self-contained with no external file dependencies.
+ * Each diagram container carries its DOT source as a `data-dot` attribute. An
+ * init snippet reads the attribute and calls
+ * `window.LibpetriViewer.mount(dot, container, { chrome: true })` to render the
+ * SVG and wire pan/zoom + cluster legend/filter chrome.
  *
  * Mirrors: `org.libpetri.doclet.DiagramRenderer`
  *
  * @module doclet/diagram-renderer
  */
 /**
- * Escapes HTML special characters for safe embedding.
+ * Escapes HTML special characters for safe embedding as text content.
  */
 declare function escapeHtml(text: string): string;
 /**
- * Renders a pre-built SVG diagram with an optional title.
+ * Renders a diagram from a DOT source string. The viewer renders the SVG
+ * client-side via Graphviz-WASM; no server-side SVG is emitted on the
+ * embedded path.
  *
- * Inlines CSS and JS from bundled resources. The JS is guarded by an
- * idempotency check so it only executes once per page, even when multiple
- * `@petrinet` tags appear.
+ * Inlines CSS and the viewer IIFE from bundled resources. The IIFE is guarded
+ * by an idempotency check (`window._libpetriViewerInit`) so it only executes
+ * once per page even when multiple `@petrinet` tags appear.
  *
  * @param title - optional title (null/undefined for no title)
- * @param svgContent - the SVG markup
- * @param dotSource - the DOT source code for display in a collapsible block
+ * @param dotSource - the DOT source code; embedded as `data-dot` and shown in
+ *                    the collapsible "View DOT Source" block
  * @returns HTML markup with diagram controls
  */
-declare function renderSvg(title: string | null | undefined, svgContent: string, dotSource: string): string;
+declare function renderSvg(title: string | null | undefined, dotSource: string): string;
+/**
+ * Renders a subnet- or instance-aware diagram. Identical to {@link renderSvg}
+ * apart from an extra {@code headerHtml} block (the port/channel/params
+ * badge bar) prepended above the diagram, and the CSS class
+ * {@code subnet-diagram} on the wrapper.
+ *
+ * @param title       diagram title (e.g. "BoundedBuffer :: b1")
+ * @param headerHtml  the HTML produced by {@link import('./subnet-header.js')}
+ * @param dotSource   the DOT source code
+ * @returns HTML markup
+ */
+declare function renderSubnetSvg(title: string | null | undefined, headerHtml: string, dotSource: string): string;
 
 /**
  * SVG renderer using `@viz-js/viz` (Graphviz WASM).
@@ -75,34 +97,133 @@ declare function renderSvg(title: string | null | undefined, svgContent: string,
 declare function dotToSvg(dot: string): Promise<string>;
 
 /**
- * Dynamic import-based PetriNet resolver for TypeDoc.
+ * Dynamic import-based resolver for `@petrinet` / `@subnet` references.
  *
- * TypeScript cannot use reflection like Java — modules must be importable
- * at doc time (from `dist/` after `npm run build`).
+ * Resolves three kinds of static exports per Java's `PetriNetTaglet` design:
+ * 1. `PetriNet` — full body diagram (existing behaviour).
+ * 2. `SubnetDef<?>` — body diagram with interface ports highlighted, plus a
+ *    subnet header with port/channel badges.
+ * 3. `Instance<?>` — renamed body diagram (already prefix-clustered by the
+ *    DOT exporter), plus an instance header with prefix, def name, and
+ *    params summary.
+ *
+ * TypeScript cannot use reflection like Java — modules must be importable at
+ * doc time (typically from `dist/` after `npm run build`).
  *
  * Tag format:
  * ```
- * @petrinet ./path/to/module#exportName      — access a PetriNet constant
- * @petrinet ./path/to/module#functionName()  — call a function returning PetriNet
+ * @petrinet ./path/to/module#exportName      — access a static export
+ * @petrinet ./path/to/module#functionName()  — call a function returning one
  * @petrinet #localExport                     — resolve from same file
  * ```
  *
- * Mirrors: `org.libpetri.doclet.PetriNetTaglet.resolvePetriNet()`
+ * Mirrors: `org.libpetri.doclet.PetriNetTaglet.resolveReference`
  *
  * @module doclet/net-resolver
  */
 
-interface ResolvedNet {
-    readonly net: PetriNet;
+/**
+ * Discriminated-union result from {@link resolveNet}. Each variant carries
+ * the resolved value plus a display title.
+ */
+type ResolvedNet = {
+    readonly kind: 'net';
+    readonly value: PetriNet;
+    readonly title: string;
+} | {
+    readonly kind: 'subnet';
+    readonly value: SubnetDef<unknown>;
+    readonly title: string;
+} | {
+    readonly kind: 'instance';
+    readonly value: Instance<unknown>;
     readonly title: string;
-}
+};
 /**
- * Parses a `@petrinet` reference and resolves the PetriNet via dynamic import.
+ * Parses a `@petrinet` / `@subnet` reference and resolves it via dynamic
+ * import. Returns `null` when the reference cannot be parsed or imported, or
+ * when the resolved value is none of the three supported kinds.
  *
  * @param reference - the tag content, e.g. `./definition#buildDebugNet()`
  * @param sourceFilePath - absolute path to the source file containing the tag
- * @returns the resolved PetriNet with title, or null on failure
  */
 declare function resolveNet(reference: string, sourceFilePath: string): Promise<ResolvedNet | null>;
 
-export { type ResolvedNet, dotToSvg, escapeHtml, load, renderSvg, resolveNet };
+/**
+ * HTML-fragment generator for the small "subnet header" badge bar that the
+ * {@link import('./diagram-renderer.js')} layers above subnet diagrams.
+ *
+ * For a {@link import('../core/subnet-def.js').SubnetDef} the header lists
+ * the subnet name, the parameter type (best-effort — TypeScript erases
+ * generics at runtime so the slot is shown as a placeholder), and one badge
+ * per port and channel — colour-coded by direction
+ * (`interface-port-input` / `-output` / `-inout` CSS classes, plus
+ * `interface-channel` for sync channels).
+ *
+ * For an {@link import('../core/instance.js').Instance} the header lists the
+ * instance prefix, the originating definition's name, and the {@link
+ * import('../core/instance.js').Instance#params} summary.
+ *
+ * Mirrors: `org.libpetri.doclet.SubnetHeader`
+ *
+ * @module doclet/subnet-header
+ */
+
+/**
+ * Builds the header HTML for a {@link SubnetDef} field.
+ *
+ * @param def           the subnet definition
+ * @param interfaceOnly when `true`, the header carries the "(interface only)"
+ *                      badge so the reader knows the body is intentionally
+ *                      omitted
+ */
+declare function forSubnetDef(def: SubnetDef<unknown>, interfaceOnly: boolean): string;
+/**
+ * Builds the header HTML for an {@link Instance} field.
+ */
+declare function forInstance(instance: Instance<unknown>): string;
+
+/**
+ * DOT generators for the subnet-aware diagrams the {@link
+ * import('./petri-net-plugin.js')} plugin draws.
+ *
+ * Two flavours:
+ * - {@link fullBody} — the subnet's complete body, but with its interface-port
+ *   places restyled with the `interface-port` category from
+ *   `petri-net-styles.json` so they read as boundary elements at a glance. A
+ *   small `subgraph cluster_iface_*` with label `"interface"` surrounds the
+ *   port places and channel transitions to advertise the subnet boundary
+ *   visually.
+ * - {@link interfaceOnly} — a tiny diagram of just the port places, the
+ *   channel transitions, and a single stub node indicating the body is
+ *   omitted. Used by the `@subnet` block tag.
+ *
+ * This module stays in the doclet directory (rather than living in
+ * `export/`) because it is a doclet-presentation concern — the production
+ * export pipeline never adds the `interface` cluster.
+ *
+ * Mirrors: `org.libpetri.doclet.SubnetDotExport`
+ *
+ * @module doclet/subnet-dot-export
+ */
+
+/**
+ * Renders the full body of a {@link SubnetDef} with the interface ports
+ * restyled. The output is a post-processed version of {@link dotExport}: the
+ * port-place node attribute lines are rewritten so the post-processor swaps in
+ * the {@code interface-port} category, channel-transition lines swap in
+ * {@code sync-channel}, and an extra {@code subgraph cluster_iface_<name>}
+ * block is appended that lists the port nodes by id — overriding their
+ * cluster membership without re-emitting them (DOT semantics: a node
+ * referenced inside a subgraph block by id alone is treated as a member of
+ * that cluster).
+ */
+declare function fullBody(def: SubnetDef<unknown>): string;
+/**
+ * Renders an interface-only diagram: just the port places + channel
+ * transitions + a single stub node labelled "(internals omitted)" so the
+ * reader knows the body has not been drawn.
+ */
+declare function interfaceOnly(def: SubnetDef<unknown>): string;
+
+export { type ResolvedNet, dotToSvg, escapeHtml, forInstance, forSubnetDef, load, renderSubnetSvg, renderSvg, resolveNet, fullBody as subnetFullBody, interfaceOnly as subnetInterfaceOnly };