refactor: introduce internal extension mechanism for BPMN extensions

[tbouffard]

Overview

This PR introduces a generic mechanism for managing BPMN extensions in bpmn-visualization, validated by migrating the existing hardcoded BPMN in Color implementation. The scope is an internal refactoring to validate the extension mechanism: existing public interfaces of DiagramConverter, StyleComputer and BpmnVisualization are unchanged, the built-in extension is hardcoded in the components that consume it, and external injection (a public bpmnExtensions option) is deferred to follow-up work.

ADR

docs/contributors/adr/001-bpmn-extensions-management.md documents the design:

• Module augmentation of the JSON model (BPMNShape, BPMNEdge, BPMNLabel) and the internal model (ShapeExtensions, EdgeExtensions, LabelExtensions) — migrated from type aliases to empty interfaces.
• Two extension point interfaces called by the pipeline: ParsingExtensionPoint (onShapeDeserialized, onEdgeDeserialized, hasLabelExtensionData) and StyleExtensionPoint (enrichShapeStyle, enrichEdgeStyle, enrichMessageFlowIconStyle).
• Explicit "Refactoring scope vs. follow-up work" subsection: no BpmnExtension grouping interface, no public bpmnExtensions: [...] option, no RenderingExtensionPoint, no icon painter injection. These are listed as deferred and explain consequences such as the asymmetric ignoreBpmnColors gating (parsing always runs, only style is gated).
• Migration plan + Bonita Connector as a future validation target.
• Open questions tracked inline (label handling workaround, enrich naming, icon painter strategy).

Code

• New src/component/extension/extension-points.ts — the two interfaces above, marked @internal and @since 0.48.0.
• New src/component/extension/bpmn-in-color/ — 4 files: types.ts (module augmentations on JSON + internal models, using export {} so the file remains a module under verbatimModuleSyntax: true), parsing-extension.ts, style-extension.ts.
• Refactored DiagramConverter and StyleComputer to call registered extensions instead of containing BPMN in Color logic. The dedicated functions and color-specific branches are removed from the core, including the message flow icon stroke color which previously still read edge.extensions.strokeColor directly. An inline comment in each file explains why the extension list is hardcoded.
• ShapeExtensions / EdgeExtensions / LabelExtensions converted from type aliases to empty interfaces (allow module augmentation by extensions).

Test plan

• tsc --noEmit passes
• npm run lint-check clean
• npm run test:unit — 3152 unit tests pass (including the 30 new dedicated ones)
• Existing BPMN in Color integration test passes
• npm run all — to be confirmed by CI
• E2E visual regression — to be confirmed by CI

Out of scope (follow-up work)

• RenderingExtensionPoint and the Bonita Connector implementation as a validation target.
• BpmnExtension grouping interface and public bpmnExtensions: [...] registration API.
• Icon painter method injection mechanism (cf. "Open question" on multiple painters).
• Symmetric ignoreBpmnColors gating (currently the parsing extension always runs; only style is gated).

Bundle size comparison

NPM bundle size comparison between two commits on docs/adr_bpmn_extension_management (raw bytes).

• Before (master merged in): 80a7bdc94 (chore(deps): bump fast-xml-parser from 5.7.1 to 5.8.0)
• After (branch tip): c966a8d97 (Merge branch 'master' into docs/adr_bpmn_extension_management)

NPM package bundles

Source: npm run build-bundles + stat --format=%s on each bundle.

Bundle	80a7bdc	c966a8d	Delta (bytes)	Delta (%)
bpmn-visualization.min.js	1 004 618	1 005 723	+1 105	+0.11%
bpmn-visualization.js	1 755 458	1 757 337	+1 879	+0.11%
bpmn-visualization.esm.js	208 086	209 911	+1 825	+0.88%

Summary

All three bundles grow slightly. The minified and full bundles gain ~0.11% (a bit over 1 kB each),
while the ESM bundle gains +1 825 bytes (+0.88%) — proportionally the largest increase since the
ESM bundle is the smallest baseline.

[github-actions]

🎊 PR Preview c966a8d has been successfully built and deployed to https://process-analytics-bpmn-visualization-js-doc_preview-pr-3519.surge.sh

🕐 Build time: 0.012s

_{🤖 By surge-preview}

[github-actions]

🎊 PR Preview c966a8d has been successfully built and deployed to https://process-analytics-bpmn-visualization-js-demo_preview-pr-3519.surge.sh

🕐 Build time: 0.01s

_{🤖 By surge-preview}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
95.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud