fix(architecture): make fcose layout deterministic via architecture.seed

[ashishjain0512]

Summary

Resolves #7729. Re-enables the architecture visual test that #7728 disabled pending this fix.

The cytoscape-fcose layout calls Math.random() internally in its constraint solver, so randomize: false alone never produced a fully deterministic render — coordinates drifted by a few pixels every run and Argos failed every CI run on the complex deeply-nested test.

• Adds an architecture.seed config option (default 1). The renderer temporarily seeds Math.random with a mulberry32 generator around the two layout.run() invocations and restores it in a finally block.
• seed: 0 opts out of the swap and recovers the pre-fix non-deterministic behavior for callers who actively want layout variety per render.
• Cypress helper injects architecture: { seed: 1 } alongside the existing handDrawnSeed = 1, locking baselines for every architecture test.
• Removes it.skip from the previously disabled should render a deterministic layout for a complex deeply-nested diagram test and adds an explicit seed: 42 override test that proves the config knob reaches the RNG.
• Updates randomize documentation to correct the previous (misleading) claim that randomize: false guarantees identical renders.

Classification

• Change type: config schema + renderer (architecture only)
• Breaking change: non-breaking API; visible behavioral default change — existing architecture diagrams now render fully-deterministically (was: slight jitter every render). Documented in the changeset; opt-out via architecture.seed: 0.
• Shared code touched: no (no rendering-util/)

Verification

• TDD: the spec couldn't even import withSeededRandom before the helper existed; 7/7 helper tests pass after.
• Lint: `pnpm lint` clean (eslint + jison + prettier + cspell).
• Unit tests: 27/27 pass (`pnpm vitest run packages/mermaid/src/diagrams/architecture/`).
• E2E snapshot test: re-enabled the original test (line 245) + added one explicit seed-override test (line 287).
• comp-review-changes: PASSED.
• Visual spot-check: with default `seed: 1`, three consecutive renders produced byte-identical PNGs (sha256 `1332ebc4…`, 51,911 bytes each). `seed: 0` produced two different hashes across two renders, proving the opt-out path. `seed: 42` produced a third distinct hash, proving the knob reaches the layout.
• Full Cypress e2e: not run locally — Argos will lock the new architecture baselines on the first CI run. This is the intended behavior of the fix.
• Changeset: `.changeset/architecture-seed.md` (`mermaid` patch, `fix:` prefix).

Notes for reviewers

• All existing architecture baselines on Argos will need to be re-approved on first CI run because the layout has shifted from "near-deterministic with sub-pixel drift" to "fully deterministic at seed=1". The visual content is the same — only sub-pixel positions change.
• The stub scope is narrow on purpose: only the two `layout.run()` calls inside `layoutArchitecture` are wrapped, and `Math.random` is restored even if the layout throws (verified by spec test).

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for mermaid-js ready!

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

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

This PR includes changesets to release 1 package

Name	Type
mermaid	Patch

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

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: ffa6c85

[codecov]

Codecov Report

❌ Patch coverage is 4.16667% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.26%. Comparing base (8e7a0c6) to head (ffa6c85).

Files with missing lines	Patch %	Lines
...maid/src/diagrams/architecture/architectureSeed.ts	5.00%	19 Missing ⚠️
.../src/diagrams/architecture/architectureRenderer.ts	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7744      +/-   ##
==========================================
- Coverage     3.26%   3.26%   -0.01%     
==========================================
  Files          598     600       +2     
  Lines        60610   60643      +33     
  Branches       914     915       +1     
==========================================
+ Hits          1981    1982       +1     
- Misses       58629   58661      +32     

Flag	Coverage Δ
unit	3.26% <4.16%> (-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/config.type.ts	100.00% <ø> (ø)
.../src/diagrams/architecture/architectureRenderer.ts	0.23% <0.00%> (-0.01%)	⬇️
...maid/src/diagrams/architecture/architectureSeed.ts	5.00% <5.00%> (ø)

... 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.

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	👍 Changes approved	2 added	May 12, 2026, 1:14 PM