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).