perf(rendering): batch node-label measurement + construction

[knsv-bot]

Summary

The steady-state (warm) win: batch the two most expensive per-node operations in
the measure phase — size measurement and label DOM construction — plus the
profiling that pinpointed them. No visual change (cypress snapshots clean).
Stacked on the surgical-reflow PR.

Validated results (dagre folder benchmark, trimmed mean)

	baseline	this PR	gain
set measure	3010 ms	2491 ms	−17%
huge1 measure	190 ms	104 ms	−45%
huge1 total render	427 ms	~340 ms	~−20%

Flat / label-heavy flowcharts (the common case) gain −39 to −49% of measure.
Subgraph-heavy diagrams gain less — they're bound by nested dagre layout, not DOM.

Changes

1. Batched measurement (prebuildNodeLabels in shapes/util.ts, wired into the
   common createGraphWithElements and dagre measureDagreGraph): build every label
   first (deferring its getBoundingClientRect), then read all sizes back-to-back so
   only the first forces a reflow.
2. Batched construction (createText.ts htmlLabelMarkup + util.ts
buildNodeLabelsBatched): assemble the markup for all HTML labels into one string
   and parse it with a single insertAdjacentHTML — the HTML parser builds the
   foreignObject/div/span sub-trees ~2× faster than per-element createElement
   (measured: labelBuild −33% set, −49% on flat diagrams).
   • Safety: a one-time probe + per-render structure check; if SVG-markup parsing
     ever misbehaves (e.g. jsdom), it falls back to per-element construction, so
     correctness never depends on the parser.
3. Measure-phase profiling buckets (sanitize/markdown/decode/labelBuild)
   that decompose the phase — how each win above was found and proven. Guarded by
   injected.profiling, tree-shaken from production.

Note on the dagre→common-pipeline migration

This rebases cleanly onto that migration: the dagre measure span is dropped
(redundant — the common renderer's measure span now wraps measureDagreLayout),
while the dagre batching stays and runs inside that measure phase via the new
measureDagreGraph.

Testing

Unit tests pass (the probe + fallback keep jsdom green); cypress visual snapshots
clean; zero new type errors.

[changeset-bot]

🦋 Changeset detected

Latest commit: 48b82a9

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

[codecov]

Codecov Report

❌ Patch coverage is 84.64730% with 37 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.81%. Comparing base (388ccd0) to head (48b82a9).
⚠️ Report is 110 commits behind head on develop.

Files with missing lines	Patch %	Lines
...c/rendering-util/rendering-elements/shapes/util.ts	81.45%	6 Missing and 17 partials ⚠️
packages/mermaid/src/rendering-util/createText.ts	86.79%	1 Missing and 6 partials ⚠️
packages/mermaid/src/rendering-util/createGraph.ts	73.33%	0 Missing and 4 partials ⚠️
packages/mermaid/src/diagrams/common/common.ts	75.00%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #7872      +/-   ##
===========================================
+ Coverage    67.78%   67.81%   +0.02%     
===========================================
  Files          429      429              
  Lines        38648    38893     +245     
  Branches      6380     6435      +55     
===========================================
+ Hits         26199    26376     +177     
- Misses        9675     9724      +49     
- Partials      2774     2793      +19     

Flag	Coverage Δ
e2e	70.35% <84.18%> (+0.08%)	⬆️
unit	24.35% <75.00%> (-0.01%)	⬇️

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

Files with missing lines	Coverage Δ
...rc/rendering-util/layout-algorithms/dagre/index.js	92.97% <100.00%> (+0.13%)	⬆️
.../rendering-elements/shapes/handDrawnShapeStyles.ts	95.00% <100.00%> (+0.17%)	⬆️
packages/mermaid/src/diagrams/common/common.ts	57.20% <75.00%> (-0.13%)	⬇️
packages/mermaid/src/rendering-util/createGraph.ts	77.77% <73.33%> (-1.39%)	⬇️
packages/mermaid/src/rendering-util/createText.ts	91.35% <86.79%> (-2.45%)	⬇️
...c/rendering-util/rendering-elements/shapes/util.ts	82.83% <81.45%> (-0.77%)	⬇️

... and 6 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)	✅ No changes detected	-	Jun 22, 2026, 11:51 AM

[netlify]

✅ Deploy Preview for mermaid-js ready!

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

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

npm i https://pkg.pr.new/@mermaid-js/examples@7872

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 48b82a9

[knsv-bot]

[sisyphus-bot]

Thanks for this — the build-all-then-measure-all batching is a genuinely smart attack on the per-node forced-reflow cost, and the engineering care shows. Since it's a draft, this is early-direction feedback, not a merge gate; nothing below is blocking. I read the full diff at head 501fb49, traced the new string-HTML path, ran an XSS pass, and read the regression-fixtures README. (Heads-up: the pre-fetch flagged this as a "new diagram" — false positive; it's a perf refactor, so the new-diagram checklist doesn't apply.)

What's working well

• 🎉 The batching architecture is the right shape. Splitting labelHelper into buildNodeLabel (writes) → measureNodeLabel (the single forced read) → finalizeNodeLabel (writes), so a batch runs every read back-to-back, is exactly how you collapse the reflow storm. The validated numbers (−17% / −45% measure) back it up.
• 🎉 The correctness guards are thoughtful, not hand-wavy. The labelSignature fingerprint to detect post-prebuild node mutation (hourglass blanking the label, erBox rewriting width, classDef-derived labelStyle) and fall back to the exact inline path; the canBatchSvgHtml() probe with per-element fallback so correctness never depends on the parser; clearPrebuiltLabels(nodes) scoped to avoid clobbering concurrent nested subgraph renders; the raise() to preserve paint order; and the degenerate-bounds guard in updateNodeBounds — these are the subtle pitfalls of caching+reordering DOM, and you've handled each. The commit history (icon/image padding, post-prebuild rebuild, paint order) shows they were found and fixed deliberately.
• 🎉 regexes.spec.ts is a model equivalence test — keeping the legacy pattern as a byte-for-byte oracle over a whitespace-edge corpus plus a backtracking-perf assertion is exactly how to make a regex micro-opt reviewable.
• 🎉 The render-regressions README is honest and useful — mapping each repro to the specific Cypress/Argos test that catches it is great traceability.

Things to consider (for when you take it out of draft)

🟡 "No visual change" vs. a folder of 8 known regressions — please confirm each is resolved on head

This is the whole correctness bar for the PR, so it's worth being explicit. The README documents 8 rendering regressions this perf work introduced (note text wrapping differently, hourglass rendering a label it shouldn't, ER entity titles vanishing, <img> icons not showing, box-label alignment flips, SVG markdown wrapping at different words). The commits fix several — but the README frames them as "compare against develop to confirm the regression," which reads as open. Before un-drafting, it'd be great to confirm every listed Argos test is green on head (especially imageshape-markdown-svg-wrap and class-notes-simple-alignment, which are wrap/alignment shifts the batched-markup path can reintroduce), and reword the README so it's clear these are fixed repros, not outstanding ones.

🟡 Scope: two unrelated perf concerns are bundled

The headline (label batching) and the flowchart parser O(n²) fix (flow.jison SPACE token + anyCommentRegex, with the flowchart-deep-indent-parse-perf changeset and regexes.spec.ts) are independent — different subsystem, different changeset, different tests. The parser fix is cleanly separable and would be much easier to land and bisect on its own. Worth splitting it into its own PR (it also looks ready/lower-risk than the batching, so it could land first).

🟡 The jison SPACE change needs the full flowchart parser suite green

\s → [^\S\n\r]+ (one token per whitespace run instead of per char) is a lexer grammar change. The "grammar only uses SPACE as a separator, so parsing is unchanged" claim is plausible, but jison changes are regression-prone and don't hot-reload (dev server restart needed). Please confirm the flowchart .spec suite passes. One edge to sanity-check: a lone \r not followed by \n used to match \s as SPACE and now matches nothing in that rule — almost certainly irrelevant, but worth a thought.

💡 Changeset coverage

The only changeset is for the bundled parser fix. The headline label-batching change has none — for a user-affecting perf improvement touching shared rendering-util/ I'd add a patch changeset (or, if you split per the point above, one per PR).

🟢 anyCommentRegex lookbehind

(?:^|(?<=\S)) uses a lookbehind — fine on current Node/browsers, just confirm it clears the project's minimum-supported-runtime matrix.

Security

Ran a dedicated XSS pass over the new string-built HTML path. No XSS or injection issues identified. htmlLabelMarkup routes all attribute values through escapeAttr (sufficient for the double-quoted attrs used) and all label content through sanitizeText/renderKatexSanitized — the same sanitization the inline addHtmlSpan path already applied (the "double sanitize" is pre-existing and harmless). The canBatchSvgHtml() probe verifies namespace resolution and bails to per-element construction otherwise, so insertAdjacentHTML adds no mXSS surface, and the final DOMPurify.sanitize in mermaidAPI is untouched. The sanitizeText refactor preserves the exact DOMPurify config branches.

---

Really strong work — the hard part (making batched DOM caching correct) is well handled, and the perf payoff is real. The main ask before this leaves draft is nailing down that "no visual change" claim against those 8 repros; splitting out the parser fix would make both halves easier to land. Happy to re-review. 🙏

_{Severity tally: 🔴 0 · 🟡 3 · 💡 1 · 🟢 1 · 🎉 4 — draft PR, posted as COMMENT. Reviewed the full diff at head 501fb49; XSS pass clean; did not run the suites locally (working tree is on an unrelated branch).}

[knsv-bot]

Thanks for the thorough pass — agreed it's non-blocking, but here's where each point landed.

Keeping the two perf fixes in one PR (intentionally). The label batching and the parser O(n²) fix came out of the same large-diagram profiling effort and are validated against the same Argos baseline; they're reviewed together and bisect together against that baseline. Splitting now would add rebase/CI churn without changing what a reviewer needs to read. They have separate changesets and separate tests, so they remain individually traceable within the one PR.

Changeset — added a patch changeset for the label-batching change (the parser fix already had one).

Parser suite — flowchart parser specs are green locally (962 passing; the lone skip is the intentional flow-huge case). The SPACE run-match only affects separator tokenization; the lone-\r edge you flagged isn't reachable as a meaningful token.

The 8 repros / "no visual change" — these are now fixed repros, not outstanding ones; reworded the README to say so. The Argos diff count tracked 120 → 17 → 0 across the fix commits, each round validated locally against develop. I'll confirm the final Argos build is fully green before taking it out of draft.

anyCommentRegex lookbehind — it is newly introduced. It's supported on Node 18+ and all evergreen browsers (Safari ≥ 16.4). If Mermaid's support floor predates that, the same guard has a lookbehind-free formulation and I'll switch to it — let me know the target matrix.

[pbrolin47]

Hi @knsv-bot ,
Some things to address:

[sisyphos-bot]

---

What's Working Well

🎉 labelSignature() cache-invalidation — the JSON fingerprint of [label, width, isMarkdown, labelStyle, useHtmlLabels, centerLabel, icon, img] elegantly handles the "shape
mutates node after prebuild" edge case. Using it to detect stale cache entries at labelHelper call time is the right design.

🎉 canBatchSvgHtml() probe + structure-validation fallback — the one-time environment probe that tests whether insertAdjacentHTML assigns the correct SVG namespace, combined
with post-insertion child-count validation, is production-grade defensive coding. The fallback to per-element construction is seamless.

🎉 .raise() for paint order — a concise, correct fix. Appending a pre-built via insertAdjacentHTML deposits it at the end of the parent (correct order), then .raise() brings
it to the correct visual layer. Clean.

🎉 Regression fixture suite in cypress/platform/dev-diagrams/render-regressions/ — documenting the specific visual regressions (with Argos links) that this PR fixes is excellent
engineering. Future maintainers have a clear record of what to protect.

🎉 anyCommentRegex O(n²)→O(n) — the lookbehind (?:^|(?<=\S)) prevents catastrophic backtracking on deeply-indented diagrams. The accompanying regexes.spec.ts with an equivalence
oracle test and a regression guard for the perf case is exactly the right level of test coverage.

🎉 flowchart SPACE token — changing \s → [^\S\n\r]+ to match runs instead of single chars eliminates O(n·k) parse overhead on k leading spaces. Small but correct.

---

Things to Address

🟡 [important] — clearPrebuiltLabels() not in try/finally in createGraph.ts

packages/mermaid/src/rendering-util/createGraph.ts

The call sequence is:
await prebuildNodeLabels(nodesGroup, data4Layout.nodes.filter(...));
await Promise.all([insertNodes(...), insertEdges(...)]);
clearPrebuiltLabels();

If Promise.all rejects (e.g. a node shape renderer throws), clearPrebuiltLabels() never runs. This leaves stale entries in the prebuiltLabels Map and orphaned elements in
the SVG DOM. On the next render of the same diagram instance these orphans will be .raise()-d without re-measurement, and subsequent renders may see incorrect layout.

Suggested fix:
await prebuildNodeLabels(nodesGroup, filteredNodes);
try {
await Promise.all([insertNodes(...), insertEdges(...)]);
} finally {
clearPrebuiltLabels();
}

---

🟡 [important] — escapeAttr does not escape single quotes

packages/mermaid/src/rendering-util/createText.ts — escapeAttr function

export function escapeAttr(value: string): string {
return value
.replace(/&/g, '&')
.replace(/"/g, '"')
.replace(/</g, '<')
.replace(/>/g, '>');
}

All generated attributes use double-quote delimiters so a literal ' in a value doesn't break quoting today. However node.labelStyle is sourced from user-authored classDef
declarations and goes through this function into style="…" attributes. If any future change introduces single-quoted attribute delimiters, or if a style value is used in another
context, the missing escape becomes a live injection point.

' → ' is standard defence-in-depth for escapeAttr:
.replace(/'/g, ''')

---

🟢 [nit] — svgHtmlBatchSupport probe result cached module-globally forever

packages/mermaid/src/rendering-util/rendering-elements/shapes/util.ts

canBatchSvgHtml() caches its result in a module-level variable after the first call. This is intentional — it's a per-page-load environment capability test. However jsdom (used
by Vitest) returns false for this probe, which means unit tests always exercise the fallback path. That means buildNodeLabelsBatched gets zero unit-test coverage. Not a bug, but
worth a comment explaining why the batched path is validated via Cypress only.

---

Security

The XSS sub-agent found no confirmed XSS vectors introduced by this PR.

The batched path's security model is sound: attribute values go through escapeAttr; label body content (sanitizedLabel) is DOMPurify-sanitised twice (once at the
buildNodeLabelsBatched call site, once inside htmlLabelMarkup); insertAdjacentHTML targets an SVG (not document.body); and the overall output goes through a final
DOMPurify.sanitize() pass in mermaidAPI.ts.

The missing ' in escapeAttr is the only security-adjacent finding (logged above as 🟡). Pre-existing risk: user-supplied dompurifyConfig from %%{init}%% directives is passed
as-is to DOMPurify.sanitize() in sanitizeText(), which means a crafted dompurifyConfig: { ALLOWED_TAGS: ['script'] } could weaken the inner guard. This is pre-existing and not
introduced by this PR, but the new batched path raises the consequence of any such bypass — worth a follow-up audit.

---

Tests

• Unit tests for labelSignature, escapeAttr, prebuildNodeLabels, and the regex equivalence oracle are present and appropriate.
• buildNodeLabelsBatched is not covered by unit tests (jsdom probe always returns false). Cypress visual regression tests via the fixture suite provide coverage here.
• Changesets present: batch-node-label-measurement.md (patch) and flowchart-deep-indent-parse-perf.md (patch) — both correct classifications.

---

[knsv-bot]

[sisyphus-bot]

This is excellent, careful performance work — the kind of shared-rendering-util change that's usually terrifying to review, made reviewable by how defensively it's built. I read the full diff at head (4b447b8) against develop, traced the batched-construction path for output-neutrality, ran an XSS pass over the new insertAdjacentHTML markup assembly, and validated the parser change against the full flowchart parser suite. The numbers are real and the safety net is genuinely good. A few things to discuss — one about scope, the rest small — but nothing blocking. Verdict: COMMENT.

What's working well

• 🎉 It degrades to the exact pre-perf path at every layer. The canBatchSvgHtml() probe → per-element fallback, buildNodeLabelsBatched returning null on any structural mismatch, and labelHelper re-validating each prebuilt label via labelSignature before reuse (else rebuild inline) means correctness never depends on the fast path. This is exactly how to land a measure-phase rewrite safely.
• 🎉 labelSignature is well-designed, and the reasoning for excluding labelStyle is the standout. The comment explaining that classDef colour doesn't affect text size, that the prebuild already stamps the final style, and that including it caused mass cache-misses on classDef-heavy diagrams — that's the detail that makes or breaks this optimization, and it's documented precisely.
• 🎉 The fiddly correctness details are handled. .raise() to restore paint order for prebuilt labels (so erBox's hand-drawn background doesn't paint over the entity), configureLabelImages awaited only when a label actually contains an <img> (no idle await on the common case), and the updateNodeBounds 0×0 guard. Someone clearly hit each of these and fixed them deliberately.
• 🎉 Output-neutrality is validated, not asserted. I checked htmlLabelMarkup against addHtmlSpan structurally (same foreignObject sizing, same div/span styles in the same order, labelStyle on both, same KaTeX branch); Argos is green ("approved") and all e2e pass. That's the right proof for a perf refactor.
• 🎉 The parser change ships with an equivalence oracle. regexes.spec.ts proves the new anyCommentRegex strips byte-identically to the legacy pattern across a 20-case corpus, plus an O(n) perf assertion. The full flowchart parser suite (1006 tests) stays green under the flow.jison SPACE-run change.

Things to address

🟡 [important] Two unrelated perf changes in one PR — consider splitting

This bundles the label batching (rendering-util: createText.ts, util.ts, createGraph.ts, dagre/index.js, common.ts) with a flowchart parse-perf change (regexes.ts, flow.jison, regexes.spec.ts) — two separate concerns with two separate changesets. They touch entirely different subsystems and have very different risk profiles: the rendering-util batching is a high-regression-risk rewrite, while the parser change is small and self-contained. Bundling them means a revert of one reverts both, and git bisect can't separate a measure-phase regression from a parser regression. The parse-perf part is cleanly liftable into its own PR. Not blocking — just cleaner history and safer revertability if they're separate.

Nits & notes

• 🟢 [nit] First lookbehind in the codebase. regexes.ts introduces (?<=\S) — a quick grep shows no other lookbehind anywhere in packages/mermaid/src. It's safe under the current effective targets (no explicit browserslist, so the default floor resolves to Safari/iOS 18+, well above the 16.4 where lookbehind landed). Worth a conscious note, though, because it sits in core preprocessing (anyCommentRegex runs for every diagram) and a lookbehind literal fails as a module-load SyntaxError on an unsupported engine — total breakage, not graceful degradation. If the team ever wants to keep the support floor low, an equivalent O(n) non-lookbehind pattern is achievable; if not, no action needed beyond awareness of the precedent.
• 🟢 [nit] Prebuild/clear isn't exception-safe. In createGraphWithElements and measureDagreGraph, prebuildNodeLabels(...) → insert loop → clearPrebuiltLabels(...) aren't wrapped in try/finally. If the insert loop throws, entries linger in the module-global prebuiltLabels map (and measureDagreGraph's scoped clear never runs, so those leak permanently). In a long-lived page that re-renders on every keystroke (the live editor) with intermittently-invalid input, that can accumulate. A try { … } finally { clearPrebuiltLabels(scoped) } would close it.
• 🟢 [nit] escapeAttr doesn't escape single quotes (createText.ts:126). Safe today since every attribute in the assembled markup is double-quoted, but a future single-quoted attribute would be exposed. A one-line comment ("double-quote-only") or adding ' to the set would harden it. (Surfaced by the XSS pass — see Security.)
• 🟢 [nit] labelSignature width default differs from the build path — signature uses node.width || getConfig().flowchart?.wrappingWidth (can be undefined→'') while buildNodeLabelsBatched uses ?? 200. Worst case is a spurious signature miss → inline rebuild (safe, just a perf miss). Aligning the defaults would keep the cache-hit rate up.
• 🟢 [note] The PR description carries a 🤖 Generated with Claude Code trailer. Per CLAUDE.md, AI-attribution trailers shouldn't appear in PR descriptions — worth trimming.

Security

Dedicated XSS/injection pass over the batched markup path — the obvious worry being raw label text reaching insertAdjacentHTML. No XSS regression. The string assembled for insertAdjacentHTML is built from DOMPurify-sanitized content at the same two sanitization layers as the old per-element path: the outer sanitizeText(decodeEntities(...)) in buildNodeLabelsBatched, and the inner hasKatex ? renderKatexSanitized : sanitizeText inside htmlLabelMarkup (mirroring addHtmlSpan's span.html(sanitizedLabel)). All attribute interpolations (getNodeClasses/cssClasses, domId/id, labelStyle) go through escapeAttr, every attribute is double-quoted, common.ts is a verbatim refactor (DOMPurify config byte-identical), and the terminal DOMPurify.sanitize() in mermaidAPI is untouched. The only finding is the single-quote nit above (not exploitable today).

Checks

• ✅ Argos visual snapshots green ("3 changed — approved") — the output-neutrality proof
• ✅ All e2e jobs pass; flowchart parser 1006 tests pass; regex equivalence + perf tests pass
• ✅ ESLint 0 errors (11 pre-existing ||-vs-?? warnings in the large createText.ts), Prettier clean
• ✅ deferMeasure defaults off, so every existing createText/addHtmlSpan caller is unchanged

---

Severity tally: 🔴 0 · 🟡 1 · 🟢 4 (+1 note) · 🎉 5. Genuinely impressive engineering — the safety architecture is what makes a change like this mergeable. The main ask is just deciding whether to split the parser change out; the rest is polish. 🚀

_{Reviewed the full diff at head 4b447b8 vs a freshly-fetched origin/develop, with structural parity checks on the batched-vs-inline label paths, the flowchart parser + regex suites run locally, and a dedicated XSS sub-review of the insertAdjacentHTML assembly.}