feat(wardley): add (ecosystem) decorator and PST attitude zones

[tractorjuice]

Summary

Extends the wardley-beta diagram to match more of the OWM (OnlineWardleyMaps) syntax:

• (ecosystem) source-strategy decorator — drawn as concentric circles with a diagonal-hatch ring, matching the OWM ecosystem-play symbol.
• Attitude zones using OWM's canonical 4-coordinate form keyword [v1, e1, v2, e2] (top-left and bottom-right corners). Renders as a translucent labelled rectangle in OWM's colour palette:
  • pioneers — light blue
  • settlers — medium blue
  • townplanners — purple
• Aliases: explorers → pioneers, villagers → settlers.

Example:

wardley-beta
component Developer Marketplace [0.26, 0.85] (ecosystem)
pioneers [0.95, 0.05, 0.55, 0.30]
settlers [0.95, 0.35, 0.55, 0.65]
townplanners [0.95, 0.70, 0.55, 0.95]

Also corrects misleading shape descriptions in the existing Sourcing Strategy docs section (build/buy/outsource/market were described as "Triangle/Diamond/Square/Circle" but render as differentiated overlay circles), and adds create.wardleymaps.ai to the Resources list (the active OWM-successor mapping tool) alongside the existing entries.

Review follow-ups (5ab7454)

• All new colors (PST stroke+fill, ecosystem outer/middle/inner) wired through themeVariables.wardley?.X defaults so users can override per theme.
• Use "evolution" consistently throughout the docs (replaces stray "maturity").
• Clamp attitude-zone label Y so the label cannot escape a very thin rectangle.
• Restored learnwardleymapping.com to Resources (the original PR description incorrectly described it as a dead link — it is live).

Test plan

• Parser-package unit tests (packages/parser/tests/wardley.test.ts): 18 tests covering all 5 strategy decorators, alias normalization, multi-zone parsing, reverse-corner ordering, malformed-attitude rejection
• Mermaid-package integration tests (wardleyParser.spec.ts, wardleyBuilder.spec.ts): 27 tests covering coord conversion, alias normalization, builder/build/clear cycle for attitudes
• Cypress visual fixtures: sourcing strategies (build/buy/outsource/market/ecosystem) + PST attitude zones
• All 45 unit tests pass
• Lint clean (cspell dictionary updated with townplanners)
• Argos visual snapshots (will run in CI)

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	5ed4ea6
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/69f83ea866b096000803a856
😎 Deploy Preview	https://deploy-preview-7696--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 5ed4ea6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
mermaid	Minor

Not sure what this means? Click here to learn what changesets are.

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

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

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

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 5ed4ea6

[codecov]

Codecov Report

❌ Patch coverage is 0% with 146 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.33%. Comparing base (92dc556) to head (5ed4ea6).

Files with missing lines	Patch %	Lines
...es/mermaid/src/diagrams/wardley/wardleyRenderer.ts	0.00%	109 Missing ⚠️
...ages/mermaid/src/diagrams/wardley/wardleyParser.ts	0.00%	17 Missing ⚠️
packages/parser/tests/test-util.ts	0.00%	9 Missing ⚠️
...ges/mermaid/src/diagrams/wardley/wardleyBuilder.ts	0.00%	6 Missing ⚠️
packages/mermaid/src/diagrams/wardley/wardleyDb.ts	0.00%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7696      +/-   ##
==========================================
- Coverage     3.33%   3.33%   -0.01%     
==========================================
  Files          542     541       -1     
  Lines        56881   57014     +133     
  Branches       839     839              
==========================================
  Hits          1899    1899              
- Misses       54982   55115     +133     

Flag	Coverage Δ
unit	3.33% <0.00%> (-0.01%)	⬇️

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

Files with missing lines	Coverage Δ
packages/mermaid/src/diagrams/wardley/wardleyDb.ts	0.00% <0.00%> (ø)
...ges/mermaid/src/diagrams/wardley/wardleyBuilder.ts	0.81% <0.00%> (-0.05%)	⬇️
packages/parser/tests/test-util.ts	1.08% <0.00%> (-0.12%)	⬇️
...ages/mermaid/src/diagrams/wardley/wardleyParser.ts	0.50% <0.00%> (-0.05%)	⬇️
...es/mermaid/src/diagrams/wardley/wardleyRenderer.ts	0.10% <0.00%> (-0.02%)	⬇️

... and 1 file 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.

[knsv-bot]

[sisyphus-bot]

Thanks for this, @tractorjuice — really thoughtful extension to wardley-beta. The OWM ecosystem decorator and PST attitude zones are a natural fit, and the test coverage you've put in across parser, builder, db, and Cypress is genuinely above-bar. A few small things below, mostly around theming and a couple of docs claims to double-check. 🙏

What's working well

• 🎉 [praise] Test coverage is excellent — 18 parser tests in packages/parser/tests/wardley.test.ts covering all five strategy decorators, alias normalization, multi-zone parsing, reverse-corner ordering, and three malformed-input rejection cases, plus 27 integration tests at the db/builder layer and two Cypress visual scenarios. This is the kind of layered testing the new-diagram checklist asks for.
• 🎉 [praise] wardleyRenderer.ts:147 scopes the diagonal-hatch pattern with diagonalHatch-${id} so multiple wardley diagrams on a single page won't collide on <defs> IDs. Easy thing to miss; nice catch.
• 🎉 [praise] Render order is correct — attitudes are drawn before axes/grid/components (wardleyRenderer.ts:179-222), so they correctly sit as background regions.
• 🎉 [praise] Defensive handling of attitude geometry — Math.min/Math.abs to normalize corners (wardleyRenderer.ts:198-201) plus the "accepts attitude corners in reverse order" parser test means users can write either corner first without breakage.
• 🎉 [praise] Aliasing (explorers → pioneers, villagers → settlers) is handled in wardleyParser.ts:240-245 after parsing rather than in the grammar, which keeps the AST surface consistent with the canonical kinds. Good separation.
• 🎉 [praise] Both source docs (packages/mermaid/src/docs/syntax/wardley.md) and the generated top-level docs/syntax/wardley.md are updated together, which suggests the docs build was run.

Things to address

🟡 [important] Hardcoded colors bypass the existing wardley theming pattern

The existing wardley renderer follows themeVariables.wardley?.<key> ?? '<default>' (see wardleyRenderer.ts:28-42 for backgroundColor, componentStroke, linkStroke, etc.). The new code introduces hardcoded hex values that won't react to user theme overrides:

• Attitude zones (wardleyRenderer.ts:184-189): pioneers: { stroke: '#3490dd', fill: '#3ccaf8', … }, same for settlers and townplanners
• Ecosystem decorator (wardleyRenderer.ts:802-845): outer '#d7d7d7', middle/inner 'white'

The OWM palette is canonical for PST, which is a perfectly valid reason to keep these as defaults — but ideally as theme variables that users can override (e.g., for dark-mode compositions, or accessibility-tweaked palettes). Could you wire them through the same themeVariables.wardley?.X pattern? Something like:

pioneers: {
  stroke: themeVariables.wardley?.pioneersStroke ?? '#3490dd',
  fill:   themeVariables.wardley?.pioneersFill   ?? '#3ccaf8',
  label:  'Pioneers',
},

Same shape for settlers, townplanners, and the ecosystem outer/middle/inner fills. The hatch stroke already uses theme.componentStroke — that's the model.

🟡 [important] The "drops a dead link" claim doesn't hold — learnwardleymapping.com is live

The PR removes https://learnwardleymapping.com/ from the Resources section in both docs/syntax/wardley.md and packages/mermaid/src/docs/syntax/wardley.md, and the PR description says this drops "a dead link". I checked the URL just now and the site is reachable, serves a valid page (title "Learn Wardley Mapping"), and looks actively maintained. Could you either restore it or share the evidence that it's broken (intermittent outage? geo-block? deprecation announcement?) so we can keep the PR description accurate?

🟢 [nit] OWM URL change — onlinewardleymaps.com → create.wardleymaps.ai

Both URLs currently load (the original responds, just with a SPA loading shell). If create.wardleymaps.ai is the new home of the same OWM project under a different domain, totally fine — could you add a note to the PR description confirming the migration? If they are different tools, "Create Wardley Maps" should probably sit alongside "OnlineWardleyMaps" rather than replace it. You're closer to that ecosystem than I am, so I'll defer to your call — just want to make sure the rename is intentional.

🟢 [nit] "Maturity" vs "evolution" terminology inconsistency in docs

The Coordinate System section in packages/mermaid/src/docs/syntax/wardley.md:59-65 describes the X-axis as "Evolution", but the new Attitude Zones section at packages/mermaid/src/docs/syntax/wardley.md:172 describes corners as [visibility1, maturity1, visibility2, maturity2]. The grammar uses evolution/evolution2. They're synonyms in Wardley parlance, but for someone reading the docs front-to-back the switch is jarring. Worth picking one term and using it everywhere.

🟢 [nit] Attitude label vertical positioning

wardleyRenderer.ts:213 places the zone label at rectY + 16 (a fixed offset from the top of the rect). For very thin vertical zones this will land outside or below the rect. Not blocking — the example zones have plenty of room — but a Math.min(rectY + 16, rectY + rectH - someMargin) clamp would future-proof the layout if anyone defines a tall but short zone. Optional.

Notes / verifications

• Generated parser files (packages/parser/src/language/generated/*) are gitignored, so the langium grammar change in wardley.langium will be regenerated by pnpm --filter parser langium:generate at build time — that's correct, no drift to worry about.
• No cross-diagram imports introduced; isolation rules are respected.
• No XSS surface in the new code: all SVG attributes are set via D3 .attr() with numbers from coordinate conversion or labels from the hardcoded attitudeStyles record. attitude.kind is constrained to enum values via the grammar.
• Changeset (mermaid minor) and version bump look correct for a feature add to a beta diagram.

Summary

This is close — the main ask is wiring the new colors through the existing themeVariables.wardley?.X pattern, and double-checking the two doc-link claims. Happy to re-review as soon as those are addressed.

---

Severity tally: 🔴 0 · 🟡 2 · 🟢 3 · 🎉 6

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	1 changed, 2 added	May 4, 2026, 6:49 AM