feat(elk): add keepEntryNodeOnTop option to keep a recursive flow's entry node on top

[knsv-bot]

Summary

Adds an opt-in ELK config option, elk.keepEntryNodeOnTop (default false), that keeps the entry node of a recursive flow at the top of the layered layout. This generalizes a fix prototyped internally so that any ELK-laid-out diagram can use it via configuration, rather than being tied to one diagram type.

Resolves #7827.

Problem

elk.layered must break cycles before it can assign layers, and its degree-based cycle-breaking has no notion of an "entry point". When a flow loops back on itself (a back-edge to an earlier node), ELK reverses an arbitrary loop edge and can rank the first-declared node in the middle of the layout — scrambling the reading order and hiding where the flow starts.

Approach

• Detection — findCyclicEntryNodes (pure, unit-tested) groups nodes by parentId (so a cycle inside a subgraph is scoped to that subgraph), looks only at internal edges, ignores self-loops, and finds the weakly-connected components. A component with no in-degree-0 node necessarily contains a cycle, so its first node in declaration order is nominated as the entry.
• Application — each nominee gets elk.layered.layering.layerConstraint = FIRST, pinning it to the first layer of its container's layered layout.
• Config plumbing — added to config.schema.yaml, regenerated config.type.ts, and added to the hand-maintained elk block in defaultConfig.ts (nested object defaults aren't auto-extracted from the schema, so the key must be listed there for a frontmatter value to survive config merge).

Default off → acyclic flows and all existing ELK diagrams (e.g. flowchart-elk) are unchanged.

Why not forceNodeModelOrder?

forceNodeModelOrder (and the model-order cycle-breaking strategies) only reorder nodes within a layer during crossing minimization — they never reassign which layer a node lands in. Verified empirically on the recursion case in both INCLUDE_CHILDREN (flattened) and SEPARATE_CHILDREN (independent sub-layout) subgraphs: the layout came out identical to baseline, with the entry still stranded mid-graph. Only layerConstraint = FIRST lifts the entry to the top.

Tests

• Unit (render.spec.ts): findCyclicEntryNodes — acyclic no-op, pure cycle, the reported recursion case (incl. orphan exclusion), per-parentId scoping, self-loop handling; plus application gating on/off through buildElkGraphFromLayoutData.
• E2E (flowchart-elk.spec.js): option off, option on, and a recursion nested inside a subgraph.

Verification

Confirmed live via agent-browser: with the option on, the entry node brief moves to the top of its (sub)graph and the flow reads top-to-bottom; with it off, the layout is unchanged. Subgraph scoping verified — the entry is pinned to the top of its own subgraph, not the whole diagram (start → research → done stays intact with brief at the top of research).

[changeset-bot]

🦋 Changeset detected

Latest commit: 04e120a

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

This PR includes changesets to release 2 packages

Name	Type
@mermaid-js/layout-elk	Minor
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@7828

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 04e120a

[codecov]

Codecov Report

❌ Patch coverage is 1.16279% with 85 lines in your changes missing coverage. Please review.
✅ Project coverage is 2.82%. Comparing base (180b383) to head (04e120a).
⚠️ Report is 6 commits behind head on develop.

Files with missing lines	Patch %	Lines
packages/mermaid-layout-elk/src/render.ts	0.00%	85 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7828      +/-   ##
==========================================
- Coverage     2.82%   2.82%   -0.01%     
==========================================
  Files          669     668       -1     
  Lines        72527   72602      +75     
  Branches       990     990              
==========================================
+ Hits          2048    2049       +1     
- Misses       70479   70553      +74     

Flag	Coverage Δ
unit	2.82% <1.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% <ø> (ø)
packages/mermaid/src/defaultConfig.ts	49.18% <100.00%> (+0.20%)	⬆️
packages/mermaid-layout-elk/src/render.ts	0.00% <0.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	3 added	Jun 10, 2026, 8:16 AM

[netlify]

✅ Deploy Preview for mermaid-js ready!

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

[knsv-bot]

[sisyphus-bot]

Thanks for this one — it's a model PR for an ELK behavior change. The description alone (problem, approach, and especially the "Why not forceNodeModelOrder?" section with empirical verification of the alternatives) makes this a pleasure to review. Let's get it across the finish line.

What's working well

• 🎉 [praise] findCyclicEntryNodes is a pure, exported, thoroughly documented helper (packages/mermaid-layout-elk/src/render.ts:168) — the "no in-degree-0 node ⇒ cycle" invariant is explained right in the doc comment, and the per-parentId scoping keeps subgraph cycles local. This is exactly the DOM-decoupled style the repo encourages for layout logic.
• 🎉 [praise] Test coverage matches the acceptance criteria in #7827 point for point: acyclic no-op, pure cycle, the reported recursion case with orphan exclusion, per-container scoping, self-loop handling, plus gating on/off through buildElkGraphFromLayoutData. E2E covers off, on, and subgraph nesting. All 27 unit tests pass locally.
• 🎉 [praise] Opt-in with default: false and applied as the last step of graph building via a spread that preserves existing layoutOptions (render.ts:271) — zero behavior change for existing ELK diagrams.
• 🎉 [praise] Generated-file hygiene is correct: I ran types:verify-config and config.type.ts is in sync with the schema; the docs/config/setup/ changes are pure regeneration churn.

Things to address

• 🟡 [important] Changeset bump level (.changeset/elk-keep-entry-node-on-top.md): both packages are bumped as patch, but this is a new feature (the description is even prefixed feat:). Repo convention is minor for features, patch for fixes — would be great to bump both @mermaid-js/layout-elk and mermaid to minor.
• 💡 [suggestion] The heuristic only fires when a cyclic component has no natural source. If a user feeds the loop from outside it (e.g. adds start --> brief at the same nesting level), the component gains an in-degree-0 node, nothing is nominated, and the option silently does nothing — even though ELK may still rank brief mid-graph. That's a reasonable design choice, but worth a sentence in the config.schema.yaml description (e.g. "only applies when the cyclic flow has no node without incoming edges") so users aren't surprised. Same for cycles that span container boundaries, which the per-parentId scoping intentionally ignores.
• 🟢 [nit] In findCyclicEntryNodes, the edge loop runs once per container group (O(groups × edges)). Completely fine at realistic diagram sizes and gated behind the flag — just noting it in case container counts ever grow; a single pre-pass bucketing edges by container would make it linear.

Security

A dedicated XSS/injection review found no issues: the option value is only used as a boolean gate, and node ids flow only into Map/Set structures and a constant-valued layoutOptions entry consumed by elkjs — nothing reaches a DOM sink.

One out-of-scope observation for a future follow-up (pre-existing, not this PR): nodeDb is a plain object keyed by user-controlled node ids (render.ts:496), so an id like __proto__ hits the prototype setter. Harmless on the path added here, but Object.create(null) or a Map would be sturdier if that file is touched again.

---

Verdict: comment — one important item (changeset bump) and a couple of optional polish ideas; nothing blocking. 👍

[knsv-bot]

[sisyphus-bot]

Re-reviewed at 04e120a5b — both items from the previous round are resolved. Nice turnaround; this is ready from my side.

What's working well

• 🎉 [praise] The changeset now bumps both @mermaid-js/layout-elk and mermaid as minor, matching the repo convention for features.
• 🎉 [praise] The keepEntryNodeOnTop description in config.schema.yaml:176 now spells out both heuristic boundaries — loops fed from outside gain a natural source and aren't pinned, and detection is scoped per container so cross-subgraph cycles aren't detected. Users won't be surprised when the option is a no-op in those cases. config.type.ts and the docs were correctly regenerated (verified with types:verify-config — in sync).
• 🎉 [praise] Core implementation unchanged and still solid: pure, well-tested findCyclicEntryNodes, opt-in default: false, all 27 ELK unit tests passing, e2e coverage for off/on/subgraph-nested cases.

Remaining (non-blocking)

• 🟢 [nit] Carried over from last round, take it or leave it: the edge loop in findCyclicEntryNodes runs once per container group (O(groups × edges)). Negligible at realistic sizes and gated behind the flag — a pre-pass bucketing edges by container would make it linear if container counts ever grow.

Security

A fresh XSS/injection pass on the delta confirms it is documentation-only (changeset bump + description text in schema/types/docs) — no new code paths, DOM sinks, or sanitization changes. The prior full review's conclusion still holds at this head: the option value is only a boolean gate, and node ids never reach a DOM sink.

The out-of-scope follow-up from last round still stands for a future PR: pre-existing nodeDb plain-object keying (render.ts:496) is __proto__-susceptible; Object.create(null) or a Map would be sturdier.

Verdict: approve ✅