fix(wardley): review follow-ups — pipeline links, theme, type safety, label sanitisation

[tractorjuice]

Summary

Post-merge follow-ups for the Wardley Maps diagram type (#7147). Two commits:

1. Review feedback from @knsv (non-blocking at merge time):

   • Sanitize link labels through textSanitizer() for defense-in-depth
   • Add feat: prefix to the changeset description
   • Remove auto-generated docs files accidentally committed to the source tree
   • Document the handdrawn/rough (look: handDrawn) mode limitation in wardley.md
   • Add a required array to WardleyDiagramConfig JSON schema

2. Real behaviour fixes:

   • Pipeline link resolution: links targeting components inside a pipeline now resolve correctly via a new resolveNodeId() that falls back to label-based matching when the synthetic-ID lookup misses.
   • Theme integration: add Wardley theme variables to all five theme files (base, default, dark, forest, neutral) so non-default themes render Wardley maps correctly. New styles.ts wires CSS rules to those variables; wardleyDiagram.ts uses the new styles function (previously empty).
   • Type safety: replace an incorrect Required<WardleyNode> cast with a narrowed WardleyNode & { x; y } type, and replace any[] with the proper d3.Selection type for text elements.

Test plan

• pnpm --filter mermaid test src/diagrams/wardley/ passes
• Manually verify dark, forest, and neutral themes render a Wardley map correctly in the browser
• Manually verify a diagram with links targeting a pipeline child component renders the link

[changeset-bot]

⚠️ No Changeset found

Latest commit: 288a6b3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes changesets to release 1 package

Name	Type
mermaid	Minor

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	288a6b3
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/69ec685dafbc8d00087da3f9
😎 Deploy Preview	https://deploy-preview-7641--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

npm i https://pkg.pr.new/@mermaid-js/examples@7641

mermaid

npm i https://pkg.pr.new/mermaid@7641

@mermaid-js/layout-elk

npm i https://pkg.pr.new/@mermaid-js/layout-elk@7641

@mermaid-js/layout-tidy-tree

npm i https://pkg.pr.new/@mermaid-js/layout-tidy-tree@7641

@mermaid-js/mermaid-zenuml

npm i https://pkg.pr.new/@mermaid-js/mermaid-zenuml@7641

@mermaid-js/parser

npm i https://pkg.pr.new/@mermaid-js/parser@7641

@mermaid-js/tiny

npm i https://pkg.pr.new/@mermaid-js/tiny@7641

commit: 288a6b3

[codecov]

Codecov Report

❌ Patch coverage is 12.58741% with 125 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.33%. Comparing base (2fe6e55) to head (288a6b3).
⚠️ Report is 36 commits behind head on develop.

Files with missing lines	Patch %	Lines
packages/mermaid/src/diagrams/wardley/styles.ts	2.94%	33 Missing ⚠️
packages/mermaid/src/themes/theme-base.js	0.00%	16 Missing ⚠️
packages/mermaid/src/themes/theme-dark.js	0.00%	16 Missing ⚠️
packages/mermaid/src/themes/theme-forest.js	0.00%	16 Missing ⚠️
packages/mermaid/src/themes/theme-neutral.js	0.00%	16 Missing ⚠️
...ges/mermaid/src/diagrams/wardley/wardleyBuilder.ts	0.00%	12 Missing ⚠️
packages/mermaid/src/diagrams/wardley/wardleyDb.ts	0.00%	11 Missing ⚠️
...ges/mermaid/src/diagrams/wardley/wardleyDiagram.ts	0.00%	2 Missing ⚠️
...es/mermaid/src/diagrams/wardley/wardleyRenderer.ts	33.33%	2 Missing ⚠️
...ages/mermaid/src/diagrams/wardley/wardleyParser.ts	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7641      +/-   ##
==========================================
+ Coverage     3.31%   3.33%   +0.02%     
==========================================
  Files          539     541       +2     
  Lines        56688   56867     +179     
  Branches       824     838      +14     
==========================================
+ Hits          1880    1898      +18     
- Misses       54808   54969     +161     

Flag	Coverage Δ
unit	3.33% <12.58%> (+0.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/mermaid/src/themes/theme-default.js	95.70% <100.00%> (+0.16%)	⬆️
...ages/mermaid/src/diagrams/wardley/wardleyParser.ts	0.54% <0.00%> (ø)
...ges/mermaid/src/diagrams/wardley/wardleyDiagram.ts	10.00% <0.00%> (-1.12%)	⬇️
...es/mermaid/src/diagrams/wardley/wardleyRenderer.ts	0.11% <33.33%> (+0.11%)	⬆️
packages/mermaid/src/diagrams/wardley/wardleyDb.ts	0.00% <0.00%> (ø)
...ges/mermaid/src/diagrams/wardley/wardleyBuilder.ts	0.86% <0.00%> (-0.10%)	⬇️
packages/mermaid/src/themes/theme-base.js	2.21% <0.00%> (-0.10%)	⬇️
packages/mermaid/src/themes/theme-dark.js	1.99% <0.00%> (-0.09%)	⬇️
packages/mermaid/src/themes/theme-forest.js	2.20% <0.00%> (-0.10%)	⬇️
packages/mermaid/src/themes/theme-neutral.js	2.77% <0.00%> (-0.12%)	⬇️
... and 1 more

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	👍 Changes approved	7 changed, 4 added	Apr 25, 2026, 7:20 AM

[knsv-bot]

[sisyphus-bot]

Thanks for the thorough follow-up @tractorjuice — this is exactly the kind of post-merge cleanup we love to see. Every review item from #7147 is addressed, and you've quietly folded in a legitimate pipeline-link bug fix and a nice type-safety pass alongside it.

What's working well

• 🎉 Theme integration is done right. styles.ts:38-87 pulls everything through theme variables, and the parallel wardley blocks in theme-base.js:266, theme-dark.js:327, theme-default.js:333, theme-forest.js:305, theme-neutral.js:339 keep the shape consistent across all five themes.
• 🎉 Pipeline link fix is surgical. WardleyBuilder.resolveNodeId (wardleyBuilder.ts:175) plus the call sites in wardleyParser.ts:186 cleanly handle the synthetic-ID case for pipeline components without leaking into other code paths. The doc comment explains the why — thank you.
• 🎉 Type safety upgrade. Replacing any[] with d3.Selection<SVGTextElement, ...>[] in wardleyRenderer.ts:892 and dropping the as SVGTextElement cast in favour of ! is a small but meaningful improvement.
• 🎉 Label sanitisation in wardleyDb.ts:60 closes the last gap — now every user-provided text field goes through textSanitizer consistently.
• 🎉 Handdrawn limitation documented in packages/mermaid/src/docs/syntax/wardley.md:444-447. That's precisely the kind of explicit acknowledgement we asked for.

Things to consider

• 🟡 [important] Missing unit test for resolveNodeId. The fallback-to-label-match logic is new behaviour and the only non-trivial code added in this PR. A small spec — either a new wardleyBuilder.spec.ts or an addition to wardleyParser.spec.ts — covering (a) the exact-ID match, (b) the label-fallback match (the pipeline Parent_Child case), and (c) the "returns input unchanged when nothing matches" case would lock this in against regressions.

• 🟡 [important] Hardcoded colour defaults in theme files. A few values are hex/rgba literals rather than derivations from existing theme variables: gridColor: 'rgba(100, 100, 100, 0.2)' (theme-base.js, theme-default.js, theme-forest.js, theme-neutral.js), gridColor: 'rgba(200, 200, 200, 0.15)' (theme-dark.js), and evolutionStroke: '#dc3545' / '#ff6b6b'. Users can override via themeVariables.wardley.*, but it would be cleaner if the defaults tracked the theme's palette — e.g., lineColor with an alpha for the grid, or an existing accent colour for evolutionStroke. Happy to defer if you have a specific reason these were picked.

• 🟢 [nit] resolveNodeId does an O(n) scan on fallback (wardleyBuilder.ts:184-188). Not a concern at realistic map sizes, but a secondary labelToId map would make it O(1) if you wanted. Only worth doing if it's trivial.

• 💡 [suggestion] Nothing structural — the only tiny thing is that the textElements type annotation in wardleyRenderer.ts:892 is fairly long. A local type alias (type WardleyText = d3.Selection<SVGTextElement, unknown, Element | null, unknown>) could keep the signature tidy if you end up reusing it.

Security

No XSS or injection concerns introduced by this PR. The textSanitizer addition strengthens the sanitisation boundary, the styles template literals follow the same pattern every other diagram's styles.ts uses, and no new innerHTML / foreignObject / event-handler sinks are introduced.

Summary

Tally: 🔴 0 · 🟡 2 · 🟢 1 · 💡 1 · 🎉 5

Nothing blocking. A small unit test for resolveNodeId would be really nice to have before merge; the hardcoded colour defaults are worth a second thought but I'm happy to defer. Let's get this across the line.

[tractorjuice]

Thanks for the thorough review!

Pushed f70916710 addressing the feedback:

• resolveNodeId unit test — new wardleyBuilder.spec.ts with the three cases you suggested (exact-id, label-fallback, unknown-input passthrough) plus an id-wins-over-label case for disambiguation.
• Theme-derived gridColor — switched all 5 themes from hardcoded rgba(…) to this.gridColor, which is already defined by each theme for gantt/other grid-drawing diagrams. Grid lines now track the palette consistently.
• Type alias — extracted type WardleyText = d3.Selection<SVGTextElement, unknown, Element | null, unknown> at the top of wardleyRenderer.ts and applied it to the textElements declaration.

On evolutionStroke staying hardcoded — deferring this one: the red is a semantic Wardley/OWM convention for evolution arrows (Simon Wardley's original maps and onlinewardleymaps.com both use red regardless of background), so it doesn't really want to track a palette accent. I kept #dc3545 for light themes and #ff6b6b for dark (better contrast on dark backgrounds), and users can still override via themeVariables.wardley.evolutionStroke. Happy to revisit if you'd rather tie it to a theme variable after all.

On the O(n) scan nit — left as is; a labelToId map would need to stay in sync with addNode deletions and the extra state isn't worth it at realistic map sizes.

[knsv-bot]

[sisyphus-bot]

Thanks for turning the review feedback around quickly — this is a well-scoped follow-up that mixes real bug fixes with the hygiene items from the original review. Nice work threading all of it into a focused PR.

What's working well

• 🎉 The resolveNodeId unit tests in wardleyBuilder.spec.ts are clean and deliberately cover the subtle "exact id wins over label match" case — that's the one that would have bitten someone later when a user picked a component name that collided with a synthetic pipeline id.
• 🎉 Theme integration is applied consistently across all five themes with the same overrideable variables and sensible fallbacks pointing at shared theme tokens.
• 🎉 styles.ts mirrors the radar diagram pattern idiomatically (cleanAndMerge over themeVariables.wardley, subfield-destructured argument) — good consistency with the existing codebase conventions.

Things to address

🟡 [important] — Missing E2E visual test for theme integration

packages/mermaid/src/diagrams/wardley/styles.ts and the five theme files introduce substantive new visual behaviour, but cypress/integration/rendering/wardley/wardley.spec.js has zero theme coverage today. Per CLAUDE.md, renderer/style changes need E2E visual regression tests using imgSnapshotTest(). A single test that renders a Wardley diagram under theme: dark (ideally forest and neutral too) would lock this in.

The test plan line "Manually verify dark, forest, and neutral themes render a Wardley map correctly" is still unchecked — would be great to convert that into a Cypress test rather than a manual step.

🟡 [important] — No E2E test for the pipeline-link fix

wardleyParser.ts:186 changes real rendering behaviour, but the existing test #3 ("should render Pipelines") uses pipeline children as link sources (Campfire Kettle -> Kettle), not as targets. The bug you're fixing is links targeting a pipeline child, where the synthetic Parent_Child id lookup previously missed.

A one-line addition to that test fixture — something like User -> Electric Kettle where Electric Kettle lives inside a pipeline — would exercise the newly-fixed path end-to-end. The unit tests cover resolveNodeId in isolation, but the integration through addLink + renderer isn't visually verified.

💡 [suggestion] — Hardcoded evolutionStroke fallback colours

In theme-base.js, theme-default.js, theme-forest.js, theme-neutral.js the evolutionStroke fallback is #dc3545, and in theme-dark.js it's #ff6b6b. Every other Wardley fallback in the same blocks points at a shared theme token (this.lineColor, this.primaryTextColor, this.background), so this one stands out.

If the design intent is "always red to signal evolution/movement", fine — but pointing at something like this.errorBkgColor (or introducing a dedicated wardleyEvolutionColor top-level variable) would integrate cleanly with user-customised palettes. Non-blocking for a -beta diagram type.

Security

No XSS or injection issues identified. textSanitizer is correctly applied to link labels in wardleyDb.ts; styles.ts only interpolates theme-config values (not user-controlled parser output); the rendering pipeline continues to terminate at DOMPurify. The <foreignObject> / <script> / event-handler surface is unchanged by this PR.

---

Overall: the behavioural fixes and type cleanup all look correct; the main ask is converting the two manual verification steps into Cypress tests so we don't regress on themes or pipeline targets. Happy to help with those if useful.

[tractorjuice]

Round-two review tackled in 288a6b3a4:

• E2E theme coverage — added a parameterised it() rendering the same Wardley diagram under base, dark, forest, and neutral themes via imgSnapshotTest. Locks in the styles.ts / theme-block integration visually so any regression on a non-default theme will show up in argos.
• Pipeline-link-target E2E — added User -> Electric Kettle to the pipelines test fixture so resolveNodeId's label-fallback is exercised end-to-end (link targeting a pipeline child, which is the path the unit-tests-only previously left uncovered).
• wardleyEvolutionColor theme variable — introduced a top-level this.wardleyEvolutionColor in all 5 themes (default #dc3545 light / #ff6b6b dark). The wardley block's evolutionStroke now defaults to it, so users can override at the palette level via themeVariables.wardleyEvolutionColor without reaching into themeVariables.wardley.evolutionStroke. Keeps the Wardley-red default but integrates cleanly with custom palettes.

Both manual verification steps from the original test plan are now Cypress tests.

[knsv-bot]

[sisyphus-bot]

Round 3 — quick one. Both rounds of feedback are now addressed cleanly and Argos has approved the visual diffs. From a re-read of the current diff (288a6b3) against the prior ask list, every item lands.

Round-2 asks → all addressed

• 🎉 E2E theme coverage — cypress/integration/rendering/wardley/wardley.spec.js:142-167 is exactly the parameterised pattern requested. One snapshot per theme (base, dark, forest, neutral), shared fixture, drops into Argos cleanly. The "7 changed, 4 added — Changes approved" from Argos confirms maintainer sign-off on the visuals.
• 🎉 Pipeline-link-target E2E — adding component User [0.95, 0.50] and User -> Electric Kettle to test #3 (wardley.spec.js:75-78) is the right surgery: User is top-level, Electric Kettle lives inside the Kettle pipeline as the synthetic Kettle_Electric Kettle, so the link target now exercises the resolveNodeId label fallback through the parser. Unit + E2E coverage now mirror each other.
• 🎉 wardleyEvolutionColor as palette-level variable — clean implementation across all five themes (#dc3545 for light, #ff6b6b for dark), with the wardley block defaulting evolutionStroke to it. Users can now override at the palette level via themeVariables.wardleyEvolutionColor or per-property via themeVariables.wardley.evolutionStroke. Exactly the pattern asked for.

Other quality calls re-verified

• 🎉 styles.ts mirrors radar/styles.ts nearly line-for-line in shape — same getThemeVariables() + getConfigAPI() + cleanAndMerge pattern, same destructured signature. Idiomatic with the existing codebase.
• 🎉 wardleyBuilder.spec.ts covers the subtle "exact id wins over label match" disambiguation case — that's the one that would have bitten someone later if a user named a top-level component the same as a pipeline child's label.
• 🎉 The 6-field required array on WardleyDiagramConfig is the right scope — only the layout-essential fields (width, height, padding, nodeRadius, labelFontSize, axisFontSize), leaving nodeLabelOffset and showGrid correctly optional. Defaults already present in the schema mean this can't break existing user configs.

Security

No new XSS or injection surface. textSanitizer continues to wrap user-provided link labels in wardleyDb.ts:60; styles.ts only interpolates already-validated theme values into CSS template literals (no parser-derived strings); the rendering pipeline still terminates at DOMPurify.

Tiny nit (deferrable)

• 🟢 [nit] The new theme tests use the description string should render under the ${theme} theme while the surrounding tests use a numeric prefix ('1: should render Onset Map', '3: should render Pipelines', etc.). Not worth re-pushing for, but if you ever touch this file again, threading a number through (6a/6b/6c/6d or similar) would keep the convention consistent.

Summary

Severity	Count
🔴 blocking	0
🟡 important	0
🟢 nit	1
💡 suggestion	0
🎉 praise	6

Thanks for the patience across two rounds @tractorjuice — this is in good shape now. The pipeline-link bug fix alone justified the follow-up, and the theme integration + type cleanup were genuinely valuable additions on top. Approving.

[knsv]

@tractorjuice Merging this! Thanks for the contribution

[aloisklink]

Hi @tractorjuice,

Just to let you know, we reverted and undid your textSanitizer() change in #7726. It broke some of the labels in wardley maps.

The rest of your changes in this PR have gone out in today's Mermaid v11.15.0 release, see https://github.com/mermaid-js/mermaid/releases/tag/mermaid%4011.15.0! Thanks for your contribution!