Bpmn Package Explorer

BPMN Package Explorer

Generate and view BPMN 2.0 process packages: a process plus the decisions its rule tasks evaluate, the forms its user tasks present, and a manifest binding them — kept as plain, vendor-neutral BPMN 2.0. Buildless and offline: it vendors pre-built viewers and a self-contained Node layout bundle; generating or rendering a package needs no npm install, no bundler and no network. Requires Node ≥ 20.12 and a browser.

When to use

Model a business process from a prose description; make/view a BPMN diagram or a DMN decision table; build a cross-linked process package. Hungarian triggers: „csinálj egy folyamatábrát”, „rajzold meg a folyamatot”, „döntési tábla”, „nézd meg ezt a .bpmn fájlt”.

The two guarantees

• Never a corrupt diagram. A language model can author correct BPMN semantics but not a readable coordinate set. bpmn-auto-layout fills that gap but fails silently on sub-processes, pools and lanes (all outputs stay schema-valid). A layout guard verifies every laid-out diagram against its own semantics and aborts on any corruption, in strict mode.
• Vendor-neutral. The .bpmn/.dmn/.form files carry no engine extension. A sidecar package.yaml holds the link graph (bindings, roles), so a package opens in Camunda Modeler, Signavio or any conformant tool.

Generation workflow

The agent authors the artifacts (guided by the references); the pipeline runs the mechanical steps, each failing loudly:

1. Author semantics — one or more semantics-only .bpmn (no geometry), applying the authoring envelope and identifier rules. Emit <bpmn:incoming>/<bpmn:outgoing> on every connected flow node.
2. Author artifacts — the .dmn decisions and .form schemas.
3. Write package.yaml — the bindings and roles.
4. Validate the manifest — node scripts/generate-cli.mjs <packageDir> runs the envelope check, manifest validation, layout + guard, and assembles a render root; it stops before serving on any error.
5. Serve + canvas — serve the printed render-root path with node scripts/serve.mjs <renderRoot> [port] (CORS-enabled) and open the printed URL on the canvas (never file://). Do not use serve_mockup for canvas display: it omits Access-Control-Allow-Origin, so the viewer's fetch('package-data.json') fails in the opaque-origin sandbox (“Failed to fetch” → blank diagram).

Display / view workflow

• Package: node scripts/generate-cli.mjs <packageDir> → node scripts/serve.mjs <renderRoot> → canvas.
• Standalone file (no manifest): node scripts/view-cli.mjs <file.bpmn|.dmn>. A file with DI renders as authored; a semantics-only .bpmn is laid out into a separate render artifact (the source is never overwritten). A DI-less file containing a rejected construct is refused with that construct's diagnostic.

Canvas / sandboxed-iframe rendering (if the viewer shows blank)

The dashboard opens a loopback canvas(kind:"url") target inside a sandbox="allow-scripts" iframe with no allow-same-origin (opaque origin), proxied under /live/<id>/. The vendored bpmn-js / dmn-js viewers are buildless and offline, so they usually render fine — but if the canvas comes up blank or 404s, it is almost always one of these, not a viewer bug:

• Absolute asset paths. Anything the served page references with a leading-slash path (/vendor/..., /main.js) resolves to the dashboard root under the /live/<id>/ prefix → 404. Keep every path in the render root relative (./vendor/...). Serve the render root with serve_mockup (never file://) and open the returned URL on the canvas.
• Missing CORS on the static server → “Failed to load package: Failed to fetch”. In the opaque-origin iframe every runtime request carries Origin: null: the viewer's fetch('package-data.json') (and any <script type="module">) is rejected unless the server answers with Access-Control-Allow-Origin: *. serve_mockup does NOT set it, so serve canvas render roots with node scripts/serve.mjs <renderRoot> (this skill's CORS server) rather than serve_mockup.
• Self-verify by iframing your served render root with sandbox="allow-scripts" and screenshotting before trusting the canvas — that reproduces the exact dashboard sandbox.

Full rationale, the CORS static-server pattern, and adjacent pitfalls (IPv6-only dev binds → ECONNREFUSED, kill %1 not persisting across tool calls) are in the canvas-webapp skill (bundled with the pi-dashboard extension).

Rejected constructs → manifest substitutions

Inline subProcess → callActivity + separate .bpmn + kind: process (drill-down). Pools (collaboration) → one .bpmn per participant + kind: participant (switcher). laneSet → manifest roles (markers + legend). messageFlow → unrepresentable (rejected). ≥2 boundary events on one activity → rejected. See references/authoring-envelope.md.

Verify the toolchain

• node scripts/fixtures.mjs — layout regression suite (catches upstream drift).
• node scripts/selftest.mjs — envelope / identifier / manifest / guard / workflow unit tests.
• node scripts/vendor.mjs — verify vendored bundle hashes (--rebuild re-vendors from pinned inputs).

References

• references/authoring-envelope.md — generation contract + rejected constructs.
• references/identifiers.md — deterministic ids, Hungarian deburring, uniqueness errors, authoring-vs-ingestion.
• references/package-manifest.md — the package.yaml contract, reconciliation.
• references/layout-envelope.md — the measured fixtures and outcomes.
• references/licensing.md — the bpmn.io watermark obligation and Apache 2.0.
• assets/VENDORED.md — pinned versions, hashes, the Node floor (20.12).