libpetri 0.4.0 → 0.4.1

package/dist/{chunk-ZE6RR3R4.js → chunk-MJPQNC5D.js}

@@ -409,4 +409,4 @@ export {
   renderDot,
   dotExport
 };
-//# sourceMappingURL=chunk-ZE6RR3R4.js.map
+//# sourceMappingURL=chunk-MJPQNC5D.js.map

package/dist/debug/index.js

@@ -1,7 +1,7 @@
 import {
   dotExport,
   sanitize
-} from "../chunk-ZE6RR3R4.js";
+} from "../chunk-MJPQNC5D.js";
 import "../chunk-FN773SSE.js";
 
 // src/debug/debug-command.ts

package/dist/doclet/index.d.ts

@@ -0,0 +1,108 @@
+import { Application } from 'typedoc';
+import { a as PetriNet } from '../petri-net-C3Jy5HCt.js';
+
+/**
+ * TypeDoc plugin for `@petrinet` tag — auto-generates interactive SVG diagrams
+ * from PetriNet definitions and embeds them in TypeDoc output.
+ *
+ * Mirrors: `org.libpetri.doclet.PetriNetTaglet`
+ *
+ * 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
+ *
+ * @module doclet/petri-net-plugin
+ */
+
+/**
+ * Loads the petri-net plugin into the TypeDoc application.
+ *
+ * @param app - the TypeDoc Application instance
+ */
+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`.
+ *
+ * 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.
+ *
+ * Mirrors: `org.libpetri.doclet.DiagramRenderer`
+ *
+ * @module doclet/diagram-renderer
+ */
+/**
+ * Escapes HTML special characters for safe embedding.
+ */
+declare function escapeHtml(text: string): string;
+/**
+ * Renders a pre-built SVG diagram with an optional title.
+ *
+ * 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.
+ *
+ * @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
+ * @returns HTML markup with diagram controls
+ */
+declare function renderSvg(title: string | null | undefined, svgContent: string, dotSource: string): string;
+
+/**
+ * SVG renderer using `@viz-js/viz` (Graphviz WASM).
+ *
+ * Pure WASM — zero external dependencies. No system `dot` binary required.
+ *
+ * Mirrors: Java's `PetriNetTaglet.dotToSvg()` (which uses `dot -Tsvg` subprocess)
+ *
+ * @module doclet/svg-renderer
+ */
+/**
+ * Renders a DOT string to SVG using the `@viz-js/viz` WASM engine.
+ *
+ * Strips the XML prolog/DOCTYPE and explicit width/height attributes so the SVG
+ * scales via viewBox + CSS instead of overriding with fixed pt sizes.
+ *
+ * @param dot - the DOT source string
+ * @returns SVG markup string
+ * @throws if `@viz-js/viz` is not installed or DOT parsing fails
+ */
+declare function dotToSvg(dot: string): Promise<string>;
+
+/**
+ * Dynamic import-based PetriNet resolver for TypeDoc.
+ *
+ * TypeScript cannot use reflection like Java — modules must be importable
+ * at doc time (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 #localExport                     — resolve from same file
+ * ```
+ *
+ * Mirrors: `org.libpetri.doclet.PetriNetTaglet.resolvePetriNet()`
+ *
+ * @module doclet/net-resolver
+ */
+
+interface ResolvedNet {
+    readonly net: PetriNet;
+    readonly title: string;
+}
+/**
+ * Parses a `@petrinet` reference and resolves the PetriNet via dynamic import.
+ *
+ * @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 };

package/dist/doclet/index.js

@@ -0,0 +1,215 @@
+// src/doclet/petri-net-plugin.ts
+import {
+  JSX
+} from "typedoc";
+
+// src/doclet/net-resolver.ts
+import { resolve, dirname } from "path";
+import { pathToFileURL } from "url";
+async function resolveNet(reference, sourceFilePath) {
+  const trimmed = reference.trim().split(/\s+/)[0] ?? "";
+  if (!trimmed) return null;
+  const hashIndex = trimmed.indexOf("#");
+  if (hashIndex === -1) return null;
+  const modulePath = trimmed.substring(0, hashIndex);
+  const exportRef = trimmed.substring(hashIndex + 1);
+  if (!exportRef) return null;
+  const isCall = exportRef.endsWith("()");
+  const exportName = isCall ? exportRef.slice(0, -2) : exportRef;
+  let absolutePath;
+  if (modulePath) {
+    absolutePath = resolve(dirname(sourceFilePath), modulePath);
+  } else {
+    absolutePath = sourceFilePath;
+  }
+  const candidates = [
+    absolutePath,
+    absolutePath + ".js",
+    absolutePath + ".ts",
+    absolutePath.replace(/\.ts$/, ".js")
+  ];
+  let mod;
+  for (const candidate of candidates) {
+    try {
+      mod = await import(pathToFileURL(candidate).href);
+      break;
+    } catch {
+    }
+  }
+  if (!mod) return null;
+  const exported = mod[exportName];
+  if (exported == null) return null;
+  let net;
+  if (isCall) {
+    if (typeof exported !== "function") return null;
+    const result = exported();
+    net = "net" in result ? result.net : result;
+  } else {
+    net = exported;
+  }
+  if (typeof net?.name !== "string" || !(net?.transitions instanceof Set)) {
+    return null;
+  }
+  return { net, title: net.name };
+}
+
+// src/doclet/svg-renderer.ts
+async function dotToSvg(dot) {
+  const { instance } = await import("@viz-js/viz");
+  const viz = await instance();
+  let svg = viz.renderString(dot, { format: "svg", engine: "dot" });
+  const svgStart = svg.indexOf("<svg");
+  if (svgStart > 0) svg = svg.substring(svgStart);
+  svg = svg.replace(/\s+(?:width|height)="[^"]*"/g, "");
+  return svg;
+}
+
+// src/doclet/diagram-renderer.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname as dirname2, join } from "path";
+var __dirname = dirname2(fileURLToPath(import.meta.url));
+function loadResource(filename) {
+  return readFileSync(join(__dirname, "resources", filename), "utf-8");
+}
+var inlineCss;
+var inlineJs;
+function css() {
+  return inlineCss ??= loadResource("petrinet-diagrams.css");
+}
+function js() {
+  return inlineJs ??= loadResource("petrinet-diagrams.js");
+}
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderSvg(title, svgContent, dotSource) {
+  const titleHtml = title ? `<h4>${escapeHtml(title)}</h4>
+` : "";
+  const summaryText = title ? "View DOT Source" : "View Source";
+  return `<style>${css()}</style>
+<script>if(!window._petriNetDiagramsInit){window._petriNetDiagramsInit=true;
+${js()}
+}</script>
+<div class="petrinet-diagram">
+${titleHtml}<div class="diagram-container">
+<div class="diagram-controls">
+<button class="diagram-btn btn-reset" title="Reset zoom">Reset</button>
+<button class="diagram-btn btn-fullscreen" onclick="PetriNetDiagrams.toggleFullscreen(this)">Fullscreen</button>
+</div>
+${svgContent}
+</div>
+<details>
+<summary>${summaryText}</summary>
+<pre><code>${escapeHtml(dotSource)}</code></pre>
+</details>
+</div>`;
+}
+
+// src/doclet/petri-net-plugin.ts
+async function getDotExport() {
+  const mod = await import("../dot-exporter-U6BRCQNK.js");
+  return mod.dotExport;
+}
+var TAG_NAME = "@petrinet";
+var htmlCache = /* @__PURE__ */ new Map();
+function load(app) {
+  app.on("bootstrapEnd", () => {
+    const blockTags = app.options.getValue("blockTags");
+    if (!blockTags.includes(TAG_NAME)) {
+      app.options.setValue("blockTags", [...blockTags, TAG_NAME]);
+    }
+  });
+  app.renderer.preRenderAsyncJobs.push(async (output) => {
+    htmlCache.clear();
+    await processProject(app, output.project);
+  });
+  app.renderer.hooks.on("comment.beforeTags", (_context, comment, reflection) => {
+    const cached = htmlCache.get(reflection.id);
+    if (!cached) return JSX.createElement(JSX.Raw, { html: "" });
+    for (const tag of comment.blockTags) {
+      if (tag.tag === TAG_NAME) {
+        tag.skipRendering = true;
+      }
+    }
+    return JSX.createElement(JSX.Raw, { html: cached });
+  });
+}
+async function processProject(app, project) {
+  const reflections = Object.values(project.reflections);
+  for (const reflection of reflections) {
+    const comment = reflection.comment;
+    if (!comment) continue;
+    const petrinetTags = comment.blockTags.filter(
+      (tag) => tag.tag === TAG_NAME
+    );
+    if (petrinetTags.length === 0) continue;
+    for (const tag of petrinetTags) {
+      const reference = tagContent(tag);
+      try {
+        const html = await generateDiagram(reference, reflection, app);
+        const existing = htmlCache.get(reflection.id) ?? "";
+        htmlCache.set(reflection.id, existing + html);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        app.logger.warn(`@petrinet error for ${reflection.getFriendlyFullName()}: ${msg}`);
+        const html = errorHtml(`Error generating diagram for '${reference}': ${msg}`);
+        const existing = htmlCache.get(reflection.id) ?? "";
+        htmlCache.set(reflection.id, existing + html);
+      }
+    }
+  }
+}
+async function generateDiagram(reference, reflection, app) {
+  const trimmed = reference.trim();
+  if (!trimmed) {
+    return errorHtml(`Empty @petrinet reference on ${reflection.getFriendlyFullName()}`);
+  }
+  const sourceFile = getSourceFilePath(reflection);
+  if (!sourceFile) {
+    return errorHtml(`Cannot determine source file for ${reflection.getFriendlyFullName()}`);
+  }
+  const resolved = await resolveNet(trimmed, sourceFile);
+  if (!resolved) {
+    return errorHtml(`Cannot resolve PetriNet: ${trimmed}`);
+  }
+  const dotExport = await getDotExport();
+  const dot = dotExport(resolved.net);
+  try {
+    const svg = await dotToSvg(dot);
+    return renderSvg(resolved.title, svg, dot);
+  } catch (e) {
+    app.logger.warn(`SVG rendering failed, falling back to DOT source: ${e}`);
+    return renderSvg(
+      resolved.title,
+      `<pre><code>${escapeHtml(dot)}</code></pre>`,
+      dot
+    );
+  }
+}
+function tagContent(tag) {
+  return tag.content.map((part) => part.text).join("").trim();
+}
+function getSourceFilePath(reflection) {
+  const decl = reflection;
+  if (decl.sources && decl.sources.length > 0) {
+    return decl.sources[0].fullFileName;
+  }
+  if (reflection.parent) {
+    return getSourceFilePath(reflection.parent);
+  }
+  return null;
+}
+function errorHtml(message) {
+  return `<div class="petrinet-error" style="color: #dc3545; border: 1px solid #dc3545; padding: 10px; border-radius: 4px;">
+<strong>@petrinet Error:</strong> ${escapeHtml(message)}
+</div>`;
+}
+export {
+  dotToSvg,
+  escapeHtml,
+  load,
+  renderSvg,
+  resolveNet
+};
+//# sourceMappingURL=index.js.map

package/dist/doclet/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/doclet/petri-net-plugin.ts","../../src/doclet/net-resolver.ts","../../src/doclet/svg-renderer.ts","../../src/doclet/diagram-renderer.ts"],"sourcesContent":["/**\n * TypeDoc plugin for `@petrinet` tag — auto-generates interactive SVG diagrams\n * from PetriNet definitions and embeds them in TypeDoc output.\n *\n * Mirrors: `org.libpetri.doclet.PetriNetTaglet`\n *\n * Plugin lifecycle (TypeDoc hooks):\n * 1. `bootstrapEnd` → register `@petrinet` as known block tag\n * 2. `preRenderAsyncJobs` → walk reflections, resolve nets, generate SVGs, cache HTML\n * 3. `comment.beforeTags` → inject cached HTML via JSX.Raw, skip default rendering\n *\n * @module doclet/petri-net-plugin\n */\n\nimport {\n  type Application,\n  type CommentTag,\n  type DeclarationReflection,\n  type ProjectReflection,\n  type Reflection,\n  JSX,\n} from 'typedoc';\nimport { resolveNet } from './net-resolver.js';\nimport { dotToSvg } from './svg-renderer.js';\nimport { renderSvg, escapeHtml } from './diagram-renderer.js';\n\n// Lazy import to avoid requiring libpetri/export at module level\nasync function getDotExport(): Promise<typeof import('../export/dot-exporter.js').dotExport> {\n  const mod = await import('../export/dot-exporter.js');\n  return mod.dotExport;\n}\n\n/** Tag name including @ prefix. */\nconst TAG_NAME = '@petrinet' as `@${string}`;\n\n/** Cache: reflection ID → rendered HTML string */\nconst htmlCache = new Map<number, string>();\n\n/**\n * Loads the petri-net plugin into the TypeDoc application.\n *\n * @param app - the TypeDoc Application instance\n */\nexport function load(app: Application): void {\n  // 1. Register @petrinet as a known block tag at bootstrap time\n  app.on('bootstrapEnd', () => {\n    const blockTags = app.options.getValue('blockTags') as string[];\n    if (!blockTags.includes(TAG_NAME)) {\n      app.options.setValue('blockTags', [...blockTags, TAG_NAME]);\n    }\n  });\n\n  // 2. Resolve nets and generate SVG during pre-render async phase\n  app.renderer.preRenderAsyncJobs.push(async (output) => {\n    htmlCache.clear();\n    await processProject(app, output.project);\n  });\n\n  // 3. Inject cached HTML into comment output, suppress default tag rendering\n  app.renderer.hooks.on('comment.beforeTags', (_context, comment, reflection) => {\n    const cached = htmlCache.get(reflection.id);\n    if (!cached) return JSX.createElement(JSX.Raw, { html: '' });\n\n    // Mark @petrinet tags as skip so TypeDoc doesn't render them as plain text\n    for (const tag of comment.blockTags) {\n      if (tag.tag === TAG_NAME) {\n        tag.skipRendering = true;\n      }\n    }\n\n    // Inject raw HTML using TypeDoc's JSX\n    return JSX.createElement(JSX.Raw, { html: cached });\n  });\n}\n\n/**\n * Walks all reflections in the project and processes `@petrinet` tags.\n */\nasync function processProject(app: Application, project: ProjectReflection): Promise<void> {\n  const reflections = Object.values(project.reflections);\n\n  for (const reflection of reflections) {\n    const comment = reflection.comment;\n    if (!comment) continue;\n\n    const petrinetTags = comment.blockTags.filter(\n      (tag: CommentTag) => tag.tag === TAG_NAME,\n    );\n    if (petrinetTags.length === 0) continue;\n\n    for (const tag of petrinetTags) {\n      const reference = tagContent(tag);\n      try {\n        const html = await generateDiagram(reference, reflection, app);\n        const existing = htmlCache.get(reflection.id) ?? '';\n        htmlCache.set(reflection.id, existing + html);\n      } catch (e) {\n        const msg = e instanceof Error ? e.message : String(e);\n        app.logger.warn(`@petrinet error for ${reflection.getFriendlyFullName()}: ${msg}`);\n        const html = errorHtml(`Error generating diagram for '${reference}': ${msg}`);\n        const existing = htmlCache.get(reflection.id) ?? '';\n        htmlCache.set(reflection.id, existing + html);\n      }\n    }\n  }\n}\n\n/**\n * Generates a diagram HTML string for a single `@petrinet` reference.\n */\nasync function generateDiagram(\n  reference: string,\n  reflection: Reflection,\n  app: Application,\n): Promise<string> {\n  const trimmed = reference.trim();\n  if (!trimmed) {\n    return errorHtml(`Empty @petrinet reference on ${reflection.getFriendlyFullName()}`);\n  }\n\n  const sourceFile = getSourceFilePath(reflection);\n  if (!sourceFile) {\n    return errorHtml(`Cannot determine source file for ${reflection.getFriendlyFullName()}`);\n  }\n\n  const resolved = await resolveNet(trimmed, sourceFile);\n  if (!resolved) {\n    return errorHtml(`Cannot resolve PetriNet: ${trimmed}`);\n  }\n\n  const dotExport = await getDotExport();\n  const dot = dotExport(resolved.net);\n\n  try {\n    const svg = await dotToSvg(dot);\n    return renderSvg(resolved.title, svg, dot);\n  } catch (e) {\n    app.logger.warn(`SVG rendering failed, falling back to DOT source: ${e}`);\n    return renderSvg(\n      resolved.title,\n      `<pre><code>${escapeHtml(dot)}</code></pre>`,\n      dot,\n    );\n  }\n}\n\n/**\n * Extracts text content from a CommentTag.\n */\nfunction tagContent(tag: CommentTag): string {\n  return tag.content\n    .map((part) => part.text)\n    .join('')\n    .trim();\n}\n\n/**\n * Gets the source file path from a reflection.\n */\nfunction getSourceFilePath(reflection: Reflection): string | null {\n  const decl = reflection as DeclarationReflection;\n  if (decl.sources && decl.sources.length > 0) {\n    return decl.sources[0]!.fullFileName;\n  }\n  if (reflection.parent) {\n    return getSourceFilePath(reflection.parent);\n  }\n  return null;\n}\n\n/**\n * Renders an error message as styled HTML.\n */\nfunction errorHtml(message: string): string {\n  return `<div class=\"petrinet-error\" style=\"color: #dc3545; border: 1px solid #dc3545; padding: 10px; border-radius: 4px;\">\n<strong>@petrinet Error:</strong> ${escapeHtml(message)}\n</div>`;\n}\n","/**\n * Dynamic import-based PetriNet resolver for TypeDoc.\n *\n * TypeScript cannot use reflection like Java — modules must be importable\n * at doc time (from `dist/` after `npm run build`).\n *\n * Tag format:\n * ```\n * @petrinet ./path/to/module#exportName      — access a PetriNet constant\n * @petrinet ./path/to/module#functionName()  — call a function returning PetriNet\n * @petrinet #localExport                     — resolve from same file\n * ```\n *\n * Mirrors: `org.libpetri.doclet.PetriNetTaglet.resolvePetriNet()`\n *\n * @module doclet/net-resolver\n */\n\nimport { resolve, dirname } from 'node:path';\nimport { pathToFileURL } from 'node:url';\nimport type { PetriNet } from '../core/petri-net.js';\n\nexport interface ResolvedNet {\n  readonly net: PetriNet;\n  readonly title: string;\n}\n\n/**\n * Parses a `@petrinet` reference and resolves the PetriNet via dynamic import.\n *\n * @param reference - the tag content, e.g. `./definition#buildDebugNet()`\n * @param sourceFilePath - absolute path to the source file containing the tag\n * @returns the resolved PetriNet with title, or null on failure\n */\nexport async function resolveNet(\n  reference: string,\n  sourceFilePath: string,\n): Promise<ResolvedNet | null> {\n  const trimmed = reference.trim().split(/\\s+/)[0] ?? '';\n  if (!trimmed) return null;\n\n  const hashIndex = trimmed.indexOf('#');\n  if (hashIndex === -1) return null;\n\n  const modulePath = trimmed.substring(0, hashIndex);\n  const exportRef = trimmed.substring(hashIndex + 1);\n  if (!exportRef) return null;\n\n  const isCall = exportRef.endsWith('()');\n  const exportName = isCall ? exportRef.slice(0, -2) : exportRef;\n\n  // Resolve module path relative to the source file\n  let absolutePath: string;\n  if (modulePath) {\n    absolutePath = resolve(dirname(sourceFilePath), modulePath);\n  } else {\n    // #localExport — resolve from same file's compiled output\n    absolutePath = sourceFilePath;\n  }\n\n  // Try .js extension for compiled output, then .ts for ts-node scenarios\n  const candidates = [\n    absolutePath,\n    absolutePath + '.js',\n    absolutePath + '.ts',\n    absolutePath.replace(/\\.ts$/, '.js'),\n  ];\n\n  let mod: Record<string, unknown> | undefined;\n  for (const candidate of candidates) {\n    try {\n      mod = await import(pathToFileURL(candidate).href) as Record<string, unknown>;\n      break;\n    } catch {\n      // Try next candidate\n    }\n  }\n\n  if (!mod) return null;\n\n  const exported = mod[exportName];\n  if (exported == null) return null;\n\n  let net: PetriNet;\n  if (isCall) {\n    if (typeof exported !== 'function') return null;\n    const result = exported() as PetriNet | { net: PetriNet };\n    // Support functions that return { net: PetriNet, ... }\n    net = 'net' in result ? result.net : result;\n  } else {\n    net = exported as PetriNet;\n  }\n\n  // Validate it looks like a PetriNet (has name and transitions)\n  if (typeof net?.name !== 'string' || !(net?.transitions instanceof Set)) {\n    return null;\n  }\n\n  return { net, title: net.name };\n}\n","/**\n * SVG renderer using `@viz-js/viz` (Graphviz WASM).\n *\n * Pure WASM — zero external dependencies. No system `dot` binary required.\n *\n * Mirrors: Java's `PetriNetTaglet.dotToSvg()` (which uses `dot -Tsvg` subprocess)\n *\n * @module doclet/svg-renderer\n */\n\n/**\n * Renders a DOT string to SVG using the `@viz-js/viz` WASM engine.\n *\n * Strips the XML prolog/DOCTYPE and explicit width/height attributes so the SVG\n * scales via viewBox + CSS instead of overriding with fixed pt sizes.\n *\n * @param dot - the DOT source string\n * @returns SVG markup string\n * @throws if `@viz-js/viz` is not installed or DOT parsing fails\n */\nexport async function dotToSvg(dot: string): Promise<string> {\n  // Dynamic import — @viz-js/viz is an optional peer dependency\n  const { instance } = await import('@viz-js/viz');\n  const viz = await instance();\n  let svg = viz.renderString(dot, { format: 'svg', engine: 'dot' });\n\n  // Strip XML prolog and DOCTYPE — invalid inside HTML5\n  const svgStart = svg.indexOf('<svg');\n  if (svgStart > 0) svg = svg.substring(svgStart);\n\n  // Strip explicit width/height attributes (e.g. \"1942pt\") so the SVG\n  // scales via viewBox + CSS instead of overriding with fixed pt sizes\n  svg = svg.replace(/\\s+(?:width|height)=\"[^\"]*\"/g, '');\n\n  return svg;\n}\n","/**\n * Shared HTML renderer for Petri Net diagrams in TypeDoc.\n *\n * Generates consistent HTML markup with interactive controls for zoom, pan,\n * and fullscreen functionality. Accepts pre-rendered SVG from `@viz-js/viz`.\n *\n * CSS and JS are loaded from bundled resources and inlined into the generated\n * HTML, making the plugin fully self-contained with no external file dependencies.\n *\n * Mirrors: `org.libpetri.doclet.DiagramRenderer`\n *\n * @module doclet/diagram-renderer\n */\n\nimport { readFileSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport { dirname, join } from 'node:path';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\nfunction loadResource(filename: string): string {\n  return readFileSync(join(__dirname, 'resources', filename), 'utf-8');\n}\n\nlet inlineCss: string | undefined;\nlet inlineJs: string | undefined;\n\nfunction css(): string {\n  return (inlineCss ??= loadResource('petrinet-diagrams.css'));\n}\n\nfunction js(): string {\n  return (inlineJs ??= loadResource('petrinet-diagrams.js'));\n}\n\n/**\n * Escapes HTML special characters for safe embedding.\n */\nexport function escapeHtml(text: string): string {\n  return text\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;');\n}\n\n/**\n * Renders a pre-built SVG diagram with an optional title.\n *\n * Inlines CSS and JS from bundled resources. The JS is guarded by an\n * idempotency check so it only executes once per page, even when multiple\n * `@petrinet` tags appear.\n *\n * @param title - optional title (null/undefined for no title)\n * @param svgContent - the SVG markup\n * @param dotSource - the DOT source code for display in a collapsible block\n * @returns HTML markup with diagram controls\n */\nexport function renderSvg(\n  title: string | null | undefined,\n  svgContent: string,\n  dotSource: string,\n): string {\n  const titleHtml = title ? `<h4>${escapeHtml(title)}</h4>\\n` : '';\n  const summaryText = title ? 'View DOT Source' : 'View Source';\n\n  return `<style>${css()}</style>\n<script>if(!window._petriNetDiagramsInit){window._petriNetDiagramsInit=true;\n${js()}\n}</script>\n<div class=\"petrinet-diagram\">\n${titleHtml}<div class=\"diagram-container\">\n<div class=\"diagram-controls\">\n<button class=\"diagram-btn btn-reset\" title=\"Reset zoom\">Reset</button>\n<button class=\"diagram-btn btn-fullscreen\" onclick=\"PetriNetDiagrams.toggleFullscreen(this)\">Fullscreen</button>\n</div>\n${svgContent}\n</div>\n<details>\n<summary>${summaryText}</summary>\n<pre><code>${escapeHtml(dotSource)}</code></pre>\n</details>\n</div>`;\n}\n"],"mappings":"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","names":["dirname"]}

package/dist/doclet/resources/petrinet-diagrams.css

@@ -0,0 +1,126 @@
+.petrinet-diagram {
+  margin: 1.5em 0;
+  border: 1px solid #ddd;
+  border-radius: 8px;
+  background: #fafafa;
+}
+
+.petrinet-diagram h4 {
+  margin: 0;
+  padding: 12px 16px;
+  background: #f0f0f0;
+  border-bottom: 1px solid #ddd;
+  border-radius: 8px 8px 0 0;
+}
+
+.petrinet-diagram .diagram-container {
+  position: relative;
+  padding: 16px;
+  height: 70vh;
+  overflow: hidden;
+}
+
+.petrinet-diagram .diagram-viewport {
+  width: 100%;
+  height: 100%;
+  cursor: grab;
+}
+
+.petrinet-diagram .diagram-viewport:active {
+  cursor: grabbing;
+}
+
+.petrinet-diagram .diagram-container svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.petrinet-diagram .diagram-controls {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  display: flex;
+  gap: 4px;
+  z-index: 10;
+}
+
+.petrinet-diagram .diagram-btn {
+  padding: 6px 10px;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+  background: white;
+  cursor: pointer;
+  font-size: 14px;
+  min-width: 32px;
+}
+
+.petrinet-diagram .diagram-btn:hover {
+  background: #e8e8e8;
+}
+
+.petrinet-diagram details {
+  padding: 0 16px 16px;
+}
+
+.petrinet-diagram summary {
+  cursor: pointer;
+  font-weight: 500;
+  padding: 8px 0;
+}
+
+/* Fullscreen mode */
+.diagram-fullscreen {
+  position: fixed !important;
+  top: 0 !important;
+  left: 0 !important;
+  width: 100vw !important;
+  height: 100vh !important;
+  max-height: 100vh !important;
+  background: white !important;
+  z-index: 9999 !important;
+  margin: 0 !important;
+  border-radius: 0 !important;
+  overflow: hidden !important;
+  display: flex !important;
+  flex-direction: column !important;
+}
+
+.diagram-fullscreen .diagram-container {
+  flex: 1 !important;
+  min-height: 0 !important;
+  height: auto !important;
+}
+
+.diagram-fullscreen .diagram-controls {
+  position: fixed;
+  top: 16px;
+  right: 16px;
+}
+
+.diagram-fullscreen details {
+  display: none;
+}
+
+.diagram-fullscreen svg {
+  max-width: none;
+  max-height: none;
+}
+
+/* Zoom indicator */
+.zoom-indicator {
+  position: absolute;
+  bottom: 8px;
+  left: 8px;
+  background: rgba(0,0,0,0.6);
+  color: white;
+  padding: 4px 8px;
+  border-radius: 4px;
+  font-size: 12px;
+  opacity: 0;
+  transition: opacity 0.3s;
+}
+
+.zoom-indicator.visible {
+  opacity: 1;
+}

package/dist/doclet/resources/petrinet-diagrams.js

@@ -0,0 +1,111 @@
+// Petri Net Diagram Viewer
+// Provides: zoom/pan and fullscreen for pre-rendered SVG diagrams
+
+(function() {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', enhanceDiagrams);
+  } else {
+    enhanceDiagrams();
+  }
+})();
+
+function enhanceDiagrams() {
+  document.querySelectorAll('.petrinet-diagram').forEach(function(diagram) {
+    var container = diagram.querySelector('.diagram-container');
+    var svg = container ? container.querySelector('svg') : null;
+    if (!svg) return;
+
+    var scale = 1, panX = 0, panY = 0;
+    var isPanning = false, startX, startY;
+
+    // Zoom indicator
+    var indicator = document.createElement('div');
+    indicator.className = 'zoom-indicator';
+    indicator.textContent = '100%';
+    container.appendChild(indicator);
+    var hideTimeout;
+
+    function applyTransform() {
+      svg.style.transform = 'translate(' + panX + 'px, ' + panY + 'px) scale(' + scale + ')';
+      svg.style.transformOrigin = 'center center';
+    }
+
+    function showZoom() {
+      indicator.textContent = Math.round(scale * 100) + '%';
+      indicator.classList.add('visible');
+      clearTimeout(hideTimeout);
+      hideTimeout = setTimeout(function() { indicator.classList.remove('visible'); }, 1000);
+    }
+
+    // Ctrl+wheel to zoom
+    container.addEventListener('wheel', function(e) {
+      if (!e.ctrlKey) return;
+      e.preventDefault();
+      var delta = e.deltaY > 0 ? 0.9 : 1.1;
+      var newScale = Math.max(0.1, Math.min(5, scale * delta));
+      var rect = container.getBoundingClientRect();
+      var mouseX = e.clientX - rect.left - rect.width / 2;
+      var mouseY = e.clientY - rect.top - rect.height / 2;
+      panX = mouseX - (mouseX - panX) * (newScale / scale);
+      panY = mouseY - (mouseY - panY) * (newScale / scale);
+      scale = newScale;
+      applyTransform();
+      showZoom();
+    }, { passive: false });
+
+    // Drag to pan
+    container.addEventListener('mousedown', function(e) {
+      if (e.button !== 0) return;
+      isPanning = true;
+      startX = e.clientX - panX;
+      startY = e.clientY - panY;
+      container.style.cursor = 'grabbing';
+    });
+
+    document.addEventListener('mousemove', function(e) {
+      if (!isPanning) return;
+      panX = e.clientX - startX;
+      panY = e.clientY - startY;
+      applyTransform();
+    });
+
+    document.addEventListener('mouseup', function() {
+      if (isPanning) {
+        isPanning = false;
+        container.style.cursor = 'grab';
+      }
+    });
+
+    // Reset button
+    var resetBtn = diagram.querySelector('.btn-reset');
+    if (resetBtn) {
+      resetBtn.addEventListener('click', function() {
+        scale = 1; panX = 0; panY = 0;
+        applyTransform();
+        showZoom();
+      });
+    }
+
+    container.style.cursor = 'grab';
+  });
+}
+
+// Fullscreen toggle (namespaced to avoid global pollution)
+window.PetriNetDiagrams = window.PetriNetDiagrams || {};
+PetriNetDiagrams.toggleFullscreen = function(btn) {
+  var diagram = btn.closest('.petrinet-diagram');
+  diagram.classList.toggle('diagram-fullscreen');
+  btn.textContent = diagram.classList.contains('diagram-fullscreen') ? 'Exit' : 'Fullscreen';
+  document.body.style.overflow = diagram.classList.contains('diagram-fullscreen') ? 'hidden' : '';
+};
+
+// ESC to exit fullscreen
+document.addEventListener('keydown', function(e) {
+  if (e.key === 'Escape') {
+    var fs = document.querySelector('.diagram-fullscreen');
+    if (fs) {
+      var btn = fs.querySelector('.btn-fullscreen');
+      if (btn) btn.click();
+    }
+  }
+});

package/dist/dot-exporter-U6BRCQNK.js

@@ -0,0 +1,8 @@
+import {
+  dotExport
+} from "./chunk-MJPQNC5D.js";
+import "./chunk-FN773SSE.js";
+export {
+  dotExport
+};
+//# sourceMappingURL=dot-exporter-U6BRCQNK.js.map

package/dist/dot-exporter-U6BRCQNK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/export/index.js

@@ -8,7 +8,7 @@ import {
   nodeStyle,
   renderDot,
   sanitize
-} from "../chunk-ZE6RR3R4.js";
+} from "../chunk-MJPQNC5D.js";
 import "../chunk-FN773SSE.js";
 export {
   DEFAULT_DOT_CONFIG,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libpetri",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Coloured Time Petri Net engine — TypeScript port",
   "homepage": "https://libpetri.org",
   "repository": {
@@ -36,6 +36,12 @@
         "import": "./dist/debug/index.js",
         "types": "./dist/debug/index.d.ts"
       }
+    },
+    "./doclet": {
+      "node": {
+        "import": "./dist/doclet/index.js",
+        "types": "./dist/doclet/index.d.ts"
+      }
     }
   },
   "scripts": {
@@ -43,13 +49,29 @@
     "check": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "bench": "vitest bench"
+    "bench": "vitest bench",
+    "docs": "typedoc"
   },
   "devDependencies": {
-    "typescript": "^5.7.0",
+    "@types/node": "^25.3.3",
+    "@viz-js/viz": "^3.24.0",
     "tsup": "^8.4.0",
+    "typedoc": "^0.28.17",
+    "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
+  "peerDependencies": {
+    "@viz-js/viz": ">=3.0.0",
+    "typedoc": ">=0.27.0"
+  },
+  "peerDependenciesMeta": {
+    "typedoc": {
+      "optional": true
+    },
+    "@viz-js/viz": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "z3-solver": "^4.13.4"
   }