refactor!: remove layout internal exports

[aloisklink]

📑 Summary

Note

This PR targets the release/12.0.0 branch

Remove the clearLayoutRenderState, createCommonLayoutRenderer, defaultMeasureLayout, paintLayoutData functions, and the CommonLayout* types from Mermaid's public API.

📏 Design Decisions

These functions were only used by the @mermaid-js/layout-elk package, which now bundles them. Removing them makes it easier to avoid new major versions of mermaid.

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
  • Should be covered by existing unit 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:.
  • This would a breaking change in Mermaid.

[changeset-bot]

🦋 Changeset detected

Latest commit: cadd87f

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

This PR includes changesets to release 1 package

Name	Type
mermaid	Major

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: d719e38c-5563-471c-846d-7e320e2c9c76

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[ashishjain0512]

I had started the same change in #8222 (behind an __internalsDoNotUse export) and have now reverted it — this PR owns it. Two things I found while looking at it that may be useful here.

Downstream consumers are clear. I checked the fork and the project that consumes it:

• alana-mermaid — 52 hits, but all four files are inside its own packages/mermaid/src/, using relative imports (from '../../rendering-elements/lineJump.js'). Its mermaid.ts barrel doesn't export these at all — it's pulled in up to v11.16.1, which predates the export block. Its mermaid-layout-elk and mermaid-layout-tidy-tree packages import only types from @mermaid-chart/mermaid.
• collab (consumes the fork) — zero hits. It imports mermaid, MermaidConfig, ParseResult, RenderResult, ElementMapping, SequenceAST, calcIntersect, calcIntersections, calcNodeIntersections. None of those are touched here.

So nothing downstream needs migrating, which supports removing rather than hiding.

One gap: community/layout-makers-guide.md still advertises this API. Its Shipping as a separate package section says:

An external layout uses the same render signature and the same createCommonLayoutRenderer.

After this PR that sentence documents something an external package can no longer call. Worth correcting in this PR so the guide doesn't outlive the API.

For what it's worth, external layouts still work without it — @mermaid-js/layout-tidy-tree implements render directly against InternalHelpers, LayoutData, RenderOptions and SVG, all of which stay exported. So the fix is probably to point that section at the tidy-tree shape rather than delete it.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.26%. Comparing base (fe0e237) to head (cadd87f).
⚠️ Report is 26 commits behind head on release/12.0.0.

Additional details and impacted files

@@                Coverage Diff                 @@
##           release/12.0.0    #8223      +/-   ##
==================================================
+ Coverage           80.13%   80.26%   +0.12%     
==================================================
  Files                 624      618       -6     
  Lines               85311    84834     -477     
  Branches            16183    18514    +2331     
==================================================
- Hits                68366    68090     -276     
+ Misses              15909    15705     -204     
- Partials             1036     1039       +3     

Flag	Coverage Δ
e2e	73.10% <ø> (-0.80%)	⬇️
unit	78.30% <ø> (+0.39%)	⬆️

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

Files with missing lines	Coverage Δ
packages/mermaid/src/mermaid.ts	74.04% <ø> (-0.22%)	⬇️

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

[aloisklink]

One gap: community/layout-makers-guide.md still advertises this API. Its Shipping as a separate package section says:

An external layout uses the same render signature and the same createCommonLayoutRenderer.

Thanks! I didn't spot that. I've removed it in cadd87f. I've tried to keep my changes minimal, since I'm not entirely sure when and how we'd fix it (maybe we can move createCommonLayoutRenderer to a separate @mermaid-js/common package or just adjust the TypeScript types slightly).

[ashishjain0512]

[sisyphus-bot]

Reviewed against origin/release/12.0.0. This is a clean removal — I checked the breaking-change classification, the in-repo consumers, and the build wiring rather than taking the summary at face value, and it all holds up. One documentation gap is worth closing before merge.

What's working well

🎉 The changeset classification is exactly right, including the subtle half. I checked each removed symbol against the mermaid@11.17.2 tag:

symbol	in 11.17.2?
createCommonLayoutRenderer, paintLayoutData, defaultMeasureLayout, clearLayoutRenderState, CommonLayout*	yes — genuinely breaking
applyLineJumpsToSvg, EdgeGeom, LineJumpConfig	no — added by the pending export-line-jumps.md

So major is correct for the first group, and deleting .changeset/export-line-jumps.md outright rather than writing "removed X" is the right call for the second — that export never shipped, so there is nothing to announce and the two changesets net to zero. That's the kind of thing that's easy to get wrong in the noisy direction, and getting it right keeps the 12.0.0 changelog honest.

🎉 noEmit: true fixes a real leak, whether or not that was the intent. With the old rootDir: ./src + outDir: ./dist, tsc was emitting compiled specs into dist — packages/mermaid-layout-elk/dist/__tests__/common-renderer-import.spec.d.ts is sitting on disk in my checkout right now — and package.json ships files: ["dist"], so that was going into the published tarball. Good catch.

I also checked the obvious risk here: .build/types.ts runs tsc -p packages/mermaid-layout-elk/tsconfig.json --emitDeclarationOnly, and noEmit + emitDeclarationOnly used to be TS5053. On TS 5.8 it exits 0, so the types build is unaffected. Worth knowing it was checked.

🎉 The removal is genuinely safe in-repo. All four functions still exist in rendering-util/layout-algorithms/common/index.ts and are still called by dagre/index.js, swimlanes/index.ts and elk/render.ts — only the re-export alias went. Nothing anywhere in the repo imports these from the 'mermaid' package root any more. And line hops still ship in @mermaid-js/layout-elk, because .build/common.ts builds that package from packages/mermaid/src/.../elk/plugin.ts, so elk/lineHops.ts reaches lineJump.js by relative import. The changeset's "which now bundles them" is accurate.

🎉 The generated typedoc output is a true regeneration. RunOptions.md's mermaid.ts:63 → mermaid.ts:45 is exactly the 18-line drop in the source. No hand-editing.

🎉 plugin.spec.ts is a better test than the one it replaces. The old spec asserted "this symbol is exported and is a function", which is a tautology once the export exists. The new one exercises the actual plugin contract — name, loader, and that the loader resolves to something with render. Passes locally (3/3).

Security: full XSS/injection pass found nothing. The diff touches no runtime path, no sanitizer config, and adds no example code. Confirmed nothing that previously ran DOMPurify is now skipped — the re-export was a pure alias.

Things to address

🟡 [important] layout-makers-guide.md no longer hangs together for its external-package reader.

The edit removes a claim that had become false, which is right — but it leaves a hole rather than filling it. As the guide now reads:

• :53 — "Layouts are built by calling createCommonLayoutRenderer from rendering-util/layout-algorithms/common/index.ts", followed by ~500 lines building on that helper with in-repo relative imports ('../common/index.js').
• :565 — "Shipping as a separate package: An external layout uses the same render signature."

Someone who reads it front to back has just learned an API they now cannot import, and the shipping section doesn't say what to do instead. It'd be great to make the boundary explicit — one or two sentences saying the common renderer is internal and unsupported outside the repo, and then either:

• an external package implements render(data, svg, helpers, options) directly, or
• the supported path for a new layout is contributing it in-repo (which, given packages/mermaid-layout-elk/src/ now contains no implementation at all, may well be the project's actual position — in which case saying so is the whole fix).

Worth noting this is a documentation question rather than a capability one: mermaid's exports still carries "./*": "./*", so a determined third party can deep-import internals exactly as they could before. Nothing got harder; it just stopped being described.

Non-blocking

🟢 [nit] The PR body and changeset don't mention applyLineJumpsToSvg, EdgeGeom or LineJumpConfig. Omitting them from the changeset is correct, as above. But #8222 is on this same branch and its author reverted their version of this change specifically so #8223 could own it — a line in the PR body noting the pending changeset was withdrawn too would save the next reader the tag-by-tag check I just did.

🟢 [nit] packages/mermaid-layout-elk/tsconfig.json:4-7 — with noEmit: true, both rootDir and outDir are inert. The ./src → ./ change reads like it was needed at some intermediate point and is now dead weight. Dropping both would make the intent ("this tsconfig is for typechecking only") unambiguous.

💡 [suggestion] plugin.spec.ts:4 imports ../dist/mermaid-layout-elk.core.mjs, which couples a unit test to build state — a clean checkout that hasn't run pnpm build gets a module-not-found rather than a useful failure. I think it's the right call on balance, since this package is nothing but a bundle and testing dist is testing the actual deliverable. A one-line comment saying the spec needs a prior build would spare whoever hits it.

Verdict

The mechanics are right and I couldn't find anything wrong with the removal itself. The single 🟡 is a paragraph in the layout guide, not a code change — happy to see this land as soon as that's addressed or you've decided the in-repo-only story is the one you want to state.

[aloisklink]

🟡 [important] layout-makers-guide.md no longer hangs together for its external-package reader.

[...]. It'd be great to make the boundary explicit — one or two sentences saying the common renderer is internal and unsupported outside the repo, and then either:

• an external package implements render(data, svg, helpers, options) directly, or
• the supported path for a new layout is contributing it in-repo (which, given packages/mermaid-layout-elk/src/ now contains no implementation at all, may well be the project's actual position — in which case saying so is the whole fix).

Unfortunately, as mentioned above, I've tried to keep my changes minimal, since I'm not entirely sure when and how we'd fix it (maybe we can move createCommonLayoutRenderer to a separate @mermaid-js/common package or just adjust the TypeScript types slightly). Once we decide how to fix this, we can update the docs for this then.

[ashishjain0512]

LGTM