feat: add sandboxLinkBaseUrl for relative links in sandbox mode

[jmandel]

📑 Summary

Add sandboxLinkBaseUrl to resolve relative links when securityLevel: 'sandbox' renders diagrams inside a sandboxed data: iframe.

Relative links such as ./page.html and #section lose their base URL context in that environment. This PR adds an opt-in configuration option so Mermaid can resolve those links before embedding the SVG.

mermaid.initialize({
  securityLevel: 'sandbox',
  sandboxLinkBaseUrl: window.location.href,
});

📏 Design Decisions

• Keep the behavior opt-in through sandboxLinkBaseUrl; existing sandbox behavior stays unchanged unless the option is set.
• Rewrite only clickable anchor links (href and xlink:href on <a>) so Mermaid does not touch internal SVG references such as markers or symbols.
• Resolve links on the live SVG DOM before sandbox serialization rather than rewriting the serialized SVG string.
• Use a cross-realm-safe element guard so the link rewrite still runs for SVG elements created through the temporary iframe path used by sandbox rendering.

Verification

• Added unit tests for config handling, relative-link resolution, and the cross-realm element guard.
• Added user documentation with v<MERMAID_RELEASE_VERSION>+.
• Added a changeset (minor).
• Verified in Chromium that sandboxed ./details.html and #results links resolve correctly when sandboxLinkBaseUrl is set.

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🦋 If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6cfd2ae

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

[netlify]

✅ Deploy Preview for mermaid-js ready!

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

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 6cfd2ae

[codecov]

Codecov Report

❌ Patch coverage is 0% with 40 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.33%. Comparing base (7781d76) to head (6cfd2ae).
⚠️ Report is 8 commits behind head on develop.

Files with missing lines	Patch %	Lines
packages/mermaid/src/utils/sandboxLinks.ts	0.00%	26 Missing ⚠️
packages/mermaid/src/mermaidAPI.ts	0.00%	14 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7594      +/-   ##
==========================================
- Coverage     3.33%   3.33%   -0.01%     
==========================================
  Files          536     537       +1     
  Lines        56249   56287      +38     
  Branches       820     821       +1     
==========================================
  Hits          1876    1876              
- Misses       54373   54411      +38     

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/config.type.ts	100.00% <ø> (ø)
packages/mermaid/src/mermaidAPI.ts	0.28% <0.00%> (-0.02%)	⬇️
packages/mermaid/src/utils/sandboxLinks.ts	0.00% <0.00%> (ø)

🚀 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)	1 changed	Apr 8, 2026, 10:03 PM

[jmandel]

Superseded by #7595, which uses a Mermaid-convention branch name and updated PR metadata. Closing this draft to keep review on the replacement PR.