feat(wardley): opt-in automatic label placement (autoPlaceLabels)

[tractorjuice]

Summary

Adds an opt-in autoPlaceLabels config flag to the wardley-beta diagram — off by default, so existing maps render unchanged.

When enabled, component, anchor, link and annotation labels are repositioned to avoid overlapping each other, node markers, pipeline boxes, the chart boundary and link lines:

• Labels moved far from their node get a thin leader line.
• A collision-free manual label [x, y] is kept exactly as authored; a colliding one is re-placed but biased toward the authored position.
• Pipeline child components prefer their label underneath.
• The algorithm is a new pure, deterministic, unit-tested module (wardleyLabelPlacement.ts). The renderer path is unchanged when the flag is off.

Enable via config:

mermaid.initialize({ 'wardley-beta': { autoPlaceLabels: true } });

⚠️ Stacked on #7696

This is built on top of #7696 (wardley (ecosystem) decorator + attitude zones). Until #7696 merges, the diff here also shows #7696's commits — please review #7696 first. The net-new change in this PR is the autoplacement work, 8 files: wardleyLabelPlacement.ts + .spec.ts, wardleyRenderer.ts, styles.ts, config.schema.yaml, config.type.ts, the Cypress wardley spec, and a changeset. I'll rebase onto develop once #7696 merges.

Test Plan

• 73 wardley unit tests pass (packages/mermaid/src/diagrams/wardley).
• tsc --noEmit is clean.
• New Cypress visual tests in cypress/integration/rendering/wardley/wardley.spec.js: dense map, kept vs re-placed manual labels, pipeline-child placement.
• Spot-checked by rendering real-world Wardley maps with the flag on and off.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	57797f9
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6a0f0d2dde94cc000835603e
😎 Deploy Preview	https://deploy-preview-7767--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: 57797f9

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@7767

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 57797f9

[codecov]

Codecov Report

❌ Patch coverage is 0.13175% with 758 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.22%. Comparing base (92dc556) to head (57797f9).
⚠️ Report is 266 commits behind head on develop.

Files with missing lines	Patch %	Lines
...es/mermaid/src/diagrams/wardley/wardleyRenderer.ts	0.00%	394 Missing ⚠️
...maid/src/diagrams/wardley/wardleyLabelPlacement.ts	0.30%	326 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 ⚠️
packages/mermaid/src/diagrams/wardley/styles.ts	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7767      +/-   ##
==========================================
- Coverage     3.33%   3.22%   -0.12%     
==========================================
  Files          542     600      +58     
  Lines        56881   61564    +4683     
  Branches       839     918      +79     
==========================================
+ Hits          1899    1987      +88     
- Misses       54982   59577    +4595     

Flag	Coverage Δ
unit	3.22% <0.13%> (-0.12%)	⬇️

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

Files with missing lines	Coverage Δ
packages/mermaid/src/config.type.ts	100.00% <ø> (ø)
packages/mermaid/src/diagrams/wardley/styles.ts	2.85% <0.00%> (-0.09%)	⬇️
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%)	⬇️
...maid/src/diagrams/wardley/wardleyLabelPlacement.ts	0.30% <0.30%> (ø)
...es/mermaid/src/diagrams/wardley/wardleyRenderer.ts	0.08% <0.00%> (-0.04%)	⬇️

... and 107 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 detected (Review)	5 added	May 21, 2026, 2:07 PM