Purpose
Investigate the implementation differences between Wire Lang's DOM-independent SVG renderer and Mermaid's DOM-based rendering approach. Determine whether adopting any part of Mermaid's approach would deliver enough benefit to justify the cost.
This is exploratory work, not a required architecture change or a blocker for PR #82. Keeping the current implementation is a valid outcome.
Context
PR #82 adds asynchronous browser rendering and optional ahead-of-time Markdown/MDX rendering. Wire's browser integration discovers source blocks and inserts generated SVG into the DOM. Its core renderer remains synchronous and DOM-independent, reusable in Node, the CLI, builds, and browsers.
The static Markdown path parses generated SVG into structured HTML syntax-tree nodes. This is separate from browser DOM insertion. Compare equivalent layers when evaluating Mermaid, rather than treating its browser integration and our static integration as alternatives.
Questions to investigate
- How does Mermaid use DOM APIs, D3, and browser measurements across representative diagram renderers? Which responsibilities belong to its core renderer versus its integration wrappers?
- Does browser-based text and element measurement materially improve layout for Wire's labels, fonts, component symbols, or dense schematics? Identify concrete cases where the current approach falls short.
- How do the approaches compare in output consistency, font handling, rendering latency, main-thread blocking, memory use, and shipped JavaScript size?
- What would DOM dependencies mean for Node/CLI rendering, ahead-of-time builds, headless-browser requirements, testing, and maintenance?
- Are there useful improvements we can adopt while keeping the core DOM-independent, such as optional measurement inputs or changes confined to browser integration?
- Does SVG-to-HTML-tree conversion in static mode create a measurable problem worth addressing independently?
Investigation approach
Inspect current primary-source implementations and document the versions or commits examined. Use representative Wire fixtures, including long labels, different fonts, and dense pin banks. Measure the current implementation first; use a small throwaway prototype only where needed to test a specific hypothesis.
Compare viable alternatives against the same requirements and fixtures. Assess rendering quality separately from browser discovery, framework lifecycle handling, and static document insertion.
Expected outcome
A short evidence-backed report with:
- A comparison of renderer internals and integration responsibilities.
- Reproducible examples or measurements supporting any claimed benefits or costs.
- A recommendation to retain the current design, adopt selected improvements, or pursue a larger change.
- Separate follow-up proposals if changes are justified, with migration costs and unresolved questions.
No production renderer replacement or new runtime dependency is required to complete this issue.
References
Purpose
Investigate the implementation differences between Wire Lang's DOM-independent SVG renderer and Mermaid's DOM-based rendering approach. Determine whether adopting any part of Mermaid's approach would deliver enough benefit to justify the cost.
This is exploratory work, not a required architecture change or a blocker for PR #82. Keeping the current implementation is a valid outcome.
Context
PR #82 adds asynchronous browser rendering and optional ahead-of-time Markdown/MDX rendering. Wire's browser integration discovers source blocks and inserts generated SVG into the DOM. Its core renderer remains synchronous and DOM-independent, reusable in Node, the CLI, builds, and browsers.
The static Markdown path parses generated SVG into structured HTML syntax-tree nodes. This is separate from browser DOM insertion. Compare equivalent layers when evaluating Mermaid, rather than treating its browser integration and our static integration as alternatives.
Questions to investigate
Investigation approach
Inspect current primary-source implementations and document the versions or commits examined. Use representative Wire fixtures, including long labels, different fonts, and dense pin banks. Measure the current implementation first; use a small throwaway prototype only where needed to test a specific hypothesis.
Compare viable alternatives against the same requirements and fixtures. Assess rendering quality separately from browser discovery, framework lifecycle handling, and static document insertion.
Expected outcome
A short evidence-backed report with:
No production renderer replacement or new runtime dependency is required to complete this issue.
References
docs/adr/0020-browser-default-static-opt-in.mdpackages/core/src/render/render-svg.tspackages/browser/src/index.tspackages/markdown/src/render-wire.ts