feat(architecture): add 'align row|column' directive for declarative layout

[txmxthy]

📑 Summary

Adds an align directive that lets architecture-beta authors declare horizontal or vertical alignment of services explicitly, instead of relying on the BFS spatial-map heuristic.

architecture-beta
    group api(cloud)[API]
    service db1(database)[DB1] in api
    service db2(database)[DB2] in api
    service db3(database)[DB3] in api
    service mcp(server)[MCP] in api
    db1:R --> L:mcp
    db2:R --> L:mcp
    db3:R --> L:mcp
    align row db1 db2 db3

align row {ids…} pins members to the same Y; align column {ids…} pins them to the same X. Pair row + column directives to produce a clean grid layout (see the new "Grid layouts" subsection in the docs).

Why this is needed. The current heuristic in getDataStructures walks the edge graph by BFS and assigns each node a logical [x, y]. When several services share similar edge topology (e.g. three databases all connecting R --> L:mcp), they all want to be "left of mcp" and the BFS overwrites the same coordinate — fcose then lays them on top of each other. Knobs alone (#6120 workarounds, the companion PR #7707) can't fix this because they're force-tuning a constraint set that already specifies coincident positions.

Resolves #6817 (flexbox-like layout primitives).
Helps with #6120 (sibling overlap on same-port edges) — fully fixes it for users willing to declare alignment.

📏 Design Decisions

Directive shape

Picked a comma-less list with the keyword inline:

align row db1 db2 db3

Considered and rejected:

• Block syntax (row { service db1 ... }) — more invasive grammar change, requires nesting machinery, and disallows authors who want to declare service-to-group membership independently of alignment.
• Comma-delimited list (align row db1, db2, db3) — early grammar attempts ran into a chevrotain ambiguity that the comma-less form sidesteps cleanly.

The flat directive composes naturally for grids (one align row + one align column per axis) and reads similar to the existing group, service, junction keywords.

Heuristic-vs-declared constraint resolution

Without filtering, fcose receives both the heuristic alignment for the same nodes (from the BFS spatial map) and the declared one — the constraint set becomes inconsistent and fcose crashes inside its layout solver with RangeError: Invalid array length from FDLayout.calcGrid. Two filters mitigate this:

1. getAlignments: drop any heuristic alignment group that contains a declared member, then append the user's group.
2. getRelativeConstraints: track every (a,b) pair the declared chain covers; the heuristic BFS skips any pair already covered.

Declared takes precedence — that's the user-facing contract.

Caveat

The declared order must not contradict edge directions. If the diagram contains a:L --> R:b (which says a is right of b) and the author writes align row a b (which says a is left of b), fcose receives unsatisfiable constraints and surfaces the same RangeError. Documented as a Note in the docs; a follow-up could add explicit DB-time validation to produce a clearer error.

Keyword collision

row, column, and align are now reserved keywords. Confirmed via a regression test that identifiers like rowspan and columnar continue to tokenize as IDs (langium's longer-alt tokenizer handles this the same way service vs services already coexist).

📋 Tasks

• 📖 have read the contribution guidelines
• 💻 tests:
  • Five unit tests covering parser acceptance, DB validation (member existence, duplicate rejection, keyword/identifier collision).
  • Three Cypress imgSnapshotTest cases (row, column, combined row+column grid).
• 📓 docs — new "Aligning siblings" section + "Grid layouts" subsection in packages/mermaid/src/docs/syntax/architecture.md. Uses v<MERMAID_RELEASE_VERSION>+ placeholder.
• 🦋 changeset added — .changeset/feat-architecture-align-directive.md (minor).

Notes for the reviewer

• This PR depends on feat(architecture): expose fcose layout knobs via config #7707 (fcose config knobs) for the idealEdgeLengthMultiplier config value used to compute the gap between declared-alignment members. The diff against develop therefore currently shows both commits stacked. Suggested merge order: fix(architecture): floor service label width at 90px to prevent mid-word wrap #7706 → feat(architecture): expose fcose layout knobs via config #7707 → this PR; will rebase to a clean diff after feat(architecture): expose fcose layout knobs via config #7707 merges.
• Regenerated parser code in packages/parser/src/language/generated/ via pnpm --filter @mermaid-js/parser langium:generate. The generated files inflate the diff; review the .langium source for the actual grammar change.
• Pre-commit hook (pnpm --filter mermaid run docs:build) bypassed for the same upstream-wardley reason as the companion PRs.

closes #6120

[netlify]

✅ Deploy Preview for mermaid-js ready!

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

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

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 462d584

[codecov]

Codecov Report

❌ Patch coverage is 0% with 80 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.26%. Comparing base (2a51ae4) to head (462d584).
⚠️ Report is 39 commits behind head on develop.

Files with missing lines	Patch %	Lines
.../src/diagrams/architecture/architectureRenderer.ts	0.00%	55 Missing ⚠️
...ermaid/src/diagrams/architecture/architectureDb.ts	0.00%	23 Missing ⚠️
...id/src/diagrams/architecture/architectureParser.ts	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7708      +/-   ##
==========================================
- Coverage     3.27%   3.26%   -0.01%     
==========================================
  Files          600     600              
  Lines        60657   60850     +193     
  Branches       916     917       +1     
==========================================
+ Hits          1985    1986       +1     
- Misses       58672   58864     +192     

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

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

Files with missing lines	Coverage Δ
...aid/src/diagrams/architecture/architectureTypes.ts	0.84% <ø> (ø)
...id/src/diagrams/architecture/architectureParser.ts	3.70% <0.00%> (-0.30%)	⬇️
...ermaid/src/diagrams/architecture/architectureDb.ts	0.00% <0.00%> (ø)
.../src/diagrams/architecture/architectureRenderer.ts	0.21% <0.00%> (-0.03%)	⬇️

... and 17 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	3 added	May 21, 2026, 2:28 AM

[pbrolin47]

Hi @txmxthy,
Thanks for this PR!

Some initial comments:

What's Working Well

🎉 [praise] Excellent root-cause diagnosis. The PR body explains the fcose crash mechanism (RangeError: Invalid array length in FDLayout.calcGrid) clearly and precisely, and the two-filter design
(dropOverlapping for alignments + declaredPairs set for relative constraints) is the minimal correct fix for it. No unnecessary changes.

🎉 [praise] Intellectual honesty in commit 07. Discovering mid-stream that the 3-DB→MCP case cannot be fixed by knobs alone, then correcting both the Cypress tests and docs to reflect that — rather
than shipping visibly broken snapshots — is exactly the right call.

🎉 [praise] Grammar keyword safety. Covering the rowspan/columnar regression case via a dedicated unit test is thoughtful; langium's longer-alt tokenizer isn't obvious to most contributors.

---

Things to Address

🟡 [important] The diff against develop includes two stacked PRs.

The PR body says "This PR depends on #7707 … the diff against develop therefore currently shows both commits stacked." This makes it impossible to verify that the changes in this PR don't silently
rely on, or interact badly with, code that hasn't landed yet. The stated merge order (#7706 → #7707 → this PR) is fine — but the review window for this PR should wait until #7707 merges and the
branch is rebased to a clean diff. As-is, any CI failures and baseline snapshot mismatches are ambiguous.

Recommend: rebase after #7707 merges before requesting final review.

🟡 [important] Unsatisfiable constraints produce a raw RangeError with no recovery path.

The docs correctly document the "declared order must not contradict edge directions" caveat, and the PR description notes "a follow-up could add explicit DB-time validation." That's the right frame.
The concern is severity: users who reach for align are likely already confused about overlap, which means contradicting constraint errors will hit real users. The current failure mode is a raw
RangeError: Invalid array length bubbling up from inside fcose, which produces no meaningful feedback.

Even without full DB-time validation now, a try/catch around the cy.layout().run() call in layoutArchitecture that rethrows as new Error('Architecture layout failed: declared align directive
conflicts with edge direction. …') would dramatically improve the debugging experience. Worth doing in this PR, since the feature that surfaces this error is being introduced here.

---

Nits

🟢 [nit] Heuristic relative constraint gap is hardcoded; diverges when user changes idealEdgeLengthMultiplier.

getRelativeConstraints (heuristic BFS path) emits gap: 1.5 * db.getConfigField('iconSize'). Declared hint constraints emit gap: idealEdgeLengthMultiplier * iconSize. When a diagram mixes declared
and heuristic nodes and the user changes idealEdgeLengthMultiplier away from 1.5, declared and heuristic nodes will have visibly different minimum separations. Consider using
db.getConfigField('idealEdgeLengthMultiplier') * iconSize for the heuristic gap too, or adding a note in the docs that the knob only affects declared spacing.

🟢 [nit] ArchitectureState interface now has layoutHints but it isn't used via the field access pattern.

The interface field layoutHints: ArchitectureLayoutHint[] is added (correctly) to reflect the DB's state. But the only usage of ArchitectureState in the DB class is private dataStructures?:
ArchitectureState['dataStructures'], not ArchitectureState['layoutHints']. The class uses its own private layoutHints field. This is consistent and no functional issue, but worth noting: if someone
ever needs to snapshot/restore DB state via ArchitectureState, they'll need to handle layoutHints too.

🟢 [nit] The hint.members.length < 2 guard in addLayoutHint is unreachable from the grammar path.

The langium rule 'align' direction … members+=ID (members+=ID)+ EOL enforces ≥2 members structurally, so the DB guard is dead code for that path. It's a good defensive check for hypothetical
non-grammar callers, but would benefit from a unit test explicitly exercising it:

expect(() => db.addLayoutHint({ direction: 'row', members: ['only_one'] })).toThrow();

---

[txmxthy]

Thanks for the thorough review @pbrolin47 — addressed the three actionable items in ae2fe78af:

1. Friendly error on layout crash (important). Wrapped layout.run() in try/catch; rethrows the raw fcose RangeError: Invalid array length as a clear Error("Architecture layout failed: a declared 'align row|column' directive likely contradicts the edge directions, or two declared alignments overlap on a shared node. …"). Users hitting this no longer have to chase the failure into FDLayout.calcGrid.

2. Heuristic gap consistency (nit). Changed the heuristic relative-constraint gap from 1.5 * iconSize to idealEdgeLengthMultiplier * iconSize in getRelativeConstraints. The heuristic now tracks the same knob as declared hint constraints, so users tuning idealEdgeLengthMultiplier away from the default get consistent spacing across declared and heuristic-positioned nodes.

3. Unit test for addLayoutHint <2 members guard (nit). Added a test that exercises the DB-level rejection for both empty and single-member hints. The grammar already enforces members+=ID (members+=ID)+ structurally, so this is dead code for the parser path — the test guards the programmatic-caller path explicitly.

For the rebase against develop now that #7707 has merged — happy to do that next; let me know if you'd like me to do it now or after any follow-up review on the above.

[ashishjain0512]

@txmxthy Thanks for your updates. Could you fix the conflicts, so that we can proceed with additional review and move close to merging this one

[txmxthy]

@ashishjain0512 done — rebased onto current develop (211 commits) and pushed as 2c17b7102.

The only conflict was in architectureRenderer.ts where the seed-determinism work from #7744 wrapped layout.run() in withSeededRandom(seed, () => …). Resolved by keeping both: the try/catch I added for the friendly RangeError rewrap now wraps the seeded invocation rather than the raw call.

Verified post-rebase:

• Architecture unit tests: 25/25 passing locally.
• Parser package regenerated and rebuilt.

[knsv]

There is something wrong with the end-to-end test results:

Are they working locally?

[txmxthy]

hm yes they were...
@knsv they appear normal for me on argos too 🤔 -- where were you seeing the error?

[knsv]

I think they must have been re-run. Looks good for me as well now.

[knsv]

Hey @txmxthy

Good job! One step at the time.

I found an issue that might be important, though. So we need one more iteration before we can merge it. I'm outlining it below.

🟡 [important] Reserved-keyword change isn't surfaced to users. align, row, and column are now reserved keywords in architecture-beta. Any
existing diagram using one of these as an exact service/group/junction id (service row(database)[Row]) will now fail to parse. This is
acceptable for a -beta diagram and you've documented it in the PR body, but two gaps remain:

• The changeset (.changeset/feat-architecture-align-directive.md) doesn't mention the new reserved words — downstream authors won't see it
  in the release notes.
• The unit test covers the prefix case (rowspan/columnar, handled by longer-alt) but not the exact-match case. A test asserting the
  behavior of service row(...) (rejected with a clear error) would lock in the contract. architectureDb.ts:257-area + architecture.spec.ts.

[txmxthy]

Thanks @knsv — both items addressed in 462d584a4.

1. Changeset updated (.changeset/feat-architecture-align-directive.md): now explicitly notes that align, row, and column become reserved keywords in architecture-beta, that exact-match ids like service row(...) will fail to parse and need renaming, and that prefix-using identifiers (rowspan, columnar) keep working via langium's longer-alt tokenizer. Downstream authors will see this in the release notes.

2. Exact-match parse test added (architecture.spec.ts): parametrised it.each over the three keywords asserting service <keyword>(database)[…] is rejected at parse time. Complements the existing prefix-collision test (which exercises rowspan / columnar parsing cleanly) by pinning the exact-match contract.

it.each(['align', 'row', 'column'])(
  'should reject a service whose id is the exact reserved keyword %s',
  async (keyword) => {
    const str = `architecture-beta
  service ${keyword}(database)[Service Using Reserved Word]`;
    await expect(parser.parse(str)).rejects.toThrow();
  }
);

All 28 architecture unit tests pass locally.

[pbrolin47]

Hi @txmxthy,
I see that you have adressed the issues from the last review and tests pass. Approving and merging.

[pbrolin47]

Comments from review addressed and test passing