fix(flowchart): respect per-subgraph direction keyword in Dagre layout

[sjackson0109]

Summary

This PR fixes a long-standing bug (#4648, #6785) where subgraphs with an explicit direction keyword were silently ignored when those subgraphs had external connections.

What changed

packages/mermaid/src/rendering-util/layout-algorithms/dagre/mermaid-graphlib.js

The cluster-extraction predicate was changed from:

if (!externalConnections && ...)

to:

if (clusterData?.explicitDir && ...)

The old check (!externalConnections) meant that any subgraph with an edge to/from a node outside its boundary would never get its own cluster sub-layout — so the user's direction keyword was silently discarded. The new check uses the explicitDir flag (set only when the user wrote an explicit direction X keyword) as the trigger, which is the correct and intentional signal from the user.

packages/mermaid/src/diagrams/flowchart/flowDb.ts

• addSubGraph now captures hasExplicitDir = rawDir !== undefined before any inherited-direction fallback, ensuring the flag is true only when the user wrote an explicit direction keyword.
• getData maps explicitDir: subGraph.hasExplicitDir and normalises direction TD → TB, mirroring the existing normalisation in setDirection for the top-level graph.

packages/mermaid/src/diagrams/flowchart/types.ts

Added hasExplicitDir: boolean to the FlowSubGraph interface to carry the parse-time flag through to layout.

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

Added explicitDir?: boolean to the BaseNode interface so the flag is visible to mermaid-graphlib.js.

Behavior change

Scenario	Old behavior	New behavior
Subgraph with explicit direction, no external edges	Separate cluster sub-layout	Separate cluster sub-layout ✅ (unchanged)
Subgraph with explicit direction, has external edges	Inherits parent rankdir ❌	Separate cluster sub-layout ✅ (fixed)
Subgraph with no explicit direction	Separate cluster sub-layout, defaults to opposite of parent rankdir	Inherits parent rankdir (no separate cluster)

⚠️ The third row is a visible default-behavior change. Subgraphs without an explicit direction keyword previously received a separate cluster graph (defaulting to the opposite rankdir of the parent). They now simply inherit the parent direction. The full e2e Argos run will show the visual impact of this change.

Tests

• Two new regression tests added to cypress/integration/rendering/flowchart/flowchart-v2.spec.js:

  • Sibling subgraphs with different explicit directions and external connections (pattern from Direction in subgraphs inconsistent #4648)
  • Nested subgraph with an external connection

• Manual visual test page added at cypress/platform/regression/issue-4648.html

• Unit tests in mermaid-graphlib.spec.js: all 19 tests pass ✅ including 4 new GLB-DIR tests that specifically exercise the explicitDir → separate-cluster code path.

Fixes #4648
See also #6785

[changeset-bot]

🦋 Changeset detected

Latest commit: d619b19

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

[netlify]

✅ Deploy Preview for mermaid-js ready!

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

[sjackson0109]

#4648 should be fixed

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

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

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: d619b19

[sjackson0109]

The unit tests are failing with errors such as:

Error: TypeError: Cannot read properties of undefined (reading 'isDirected')
 ❯ Module.write node_modules/.pnpm/dagre-d3-es@7.0.14/node_modules/dagre-d3-es/src/graphlib/json.js:64:19
 ❯ packages/mermaid/src/rendering-util/layout-algorithms/dagre/mermaid-graphlib.spec.js:341:44

and

Error: TypeError: Cannot read properties of undefined (reading 'node')
 ❯ packages/mermaid/src/rendering-util/layout-algorithms/dagre/mermaid-graphlib.spec.js:366:29

and

Error: TypeError: Cannot read properties of undefined (reading 'node')
 ❯ packages/mermaid/src/rendering-util/layout-algorithms/dagre/mermaid-graphlib.spec.js:396:27

These failures are expected, for now.

This PR depends on a new release of Dagre JS, specifically the changes in this PR I submitted here: dagrejs/dagre#511

That update provides the layout engine with the additional attributes required for these tests to pass.

[knsv-bot]

[sisyphus-bot]

Thanks for taking on #4648 @sjackson0109 — this is one of the longest-standing layout bugs in the project, and the angle you've gone for (gate on explicit direction rather than on !externalConnections) is genuinely more principled than the existing logic. That said, before this can land I think it needs more guardrails and a couple of fixes, given how broadly mermaid-graphlib.js reaches.

What's promising

• 🎉 The core conceptual change in mermaid-graphlib.js:327-330 — switching the cluster-extraction predicate from !externalConnections to clusterData?.dir — is the right shape of fix. The old check was the actual root cause of the "external edge into a subgraph node leaks direction" behavior reported in #4648 and #6785. Treating "user explicitly said direction X" as the trigger for a separate sub-layout is much more intentional.
• 🎉 The TD → TB normalisation in flowDb.ts:703-706 (inside addSubGraph) plugs a real gap — setDirection() already normalises this for the top-level direction (flowDb.ts:451-453), but subgraph directions previously didn't, which is exactly the "direction TD doesn't work, you have to use direction TB" complaint in the issue thread. Mirroring the existing normalisation here is the right call.

Things to address

🔴 [blocking] No automated tests for a shared-layout change

packages/mermaid/src/rendering-util/layout-algorithms/dagre/mermaid-graphlib.js is used by every Dagre-based diagram type (flowchart, class, state, etc.). CLAUDE.md is explicit on this:

rendering-util/ is shared by all diagram types. Changes here can regress any diagram. Always run full e2e tests (pnpm e2e) after modifying shared rendering code — unit tests alone are insufficient.

The existing Cypress suite already has extensive subgraph-direction coverage in cypress/integration/rendering/flowchart/flowchart-v2.spec.js (around lines 696, 814, 1014+ — multiple test cases mixing top-level and subgraph directions, nested subgraphs, etc.). Two things needed:

1. Run those existing tests against the change and post the Argos diff — that's the only way to know whether the new condition regresses existing flowchart layouts. Subgraphs without an explicit direction keyword no longer get a separate cluster graph under the new logic (old code: separate graph if !externalConnections; new code: separate graph only if clusterData?.dir), so default-direction subgraphs may shift visually.
2. Add a new test in that same file specifically targeting #4648's two patterns: (a) external edge into a subgraph internal node where the subgraph has its own direction, (b) sibling subgraphs with different directions connected via subgraph-to-subgraph edges. A side-by-side that locks in the fixed behavior would also serve as the long-term regression guard the issue thread has been asking for.

🔴 [blocking] The manual test in test/4648.html won't parse

The mermaid source in the <div class="mermaid"> block has no newlines between top-level statements:

flowchart TD subgraph Group1 direction TB A1 --> A2 A2 --> A3 end subgraph Group2 direction LR
B1 --> B2 B2 --> B3 end subgraph Group3 direction LR C1 --> C2 C2 --> C3 end %% External
connections between subgraphs A3 --- B1 B3 --- C1 %% Wrapper workaround subgraph Wrapper
direction LR subgraph Inner D1 --> D2 D2 --> D3 end end

Mermaid's flowchart parser uses newlines/semicolons as statement separators — flowchart TD subgraph Group1 direction TB A1 --> A2 on a single line is a parse error, not a rendered diagram. Looks like the file was reflowed by an editor at some point. Each statement (flowchart TD, subgraph X, direction Y, each edge, each end) needs its own line. There's also a B1 B3 token sequence in A3 --- B1 B3 --- C1 that won't parse even with newlines — looks like that should be two separate edges (A3 --- B1 and B3 --- C1).

Worth opening this file in the dev server (pnpm dev) and confirming it actually renders before relying on it as the visual proof.

🟡 [important] Test file location

test/ isn't an established directory in this repo — manual test pages live in cypress/platform/ (e.g., cypress/platform/subgraph.html already exists for similar purposes), and automated visual tests live in cypress/integration/rendering/. The new test/4648.html won't be picked up by any tooling and will likely confuse future contributors. Suggest:

• Move the manual page to cypress/platform/4648.html (or merge it into the existing subgraph.html), and
• Add the automated coverage as a Cypress test in flowchart-v2.spec.js.

🟡 [important] Missing changeset

This is a user-visible layout-behavior change, so it needs a .changeset/*.md entry. pnpm changeset → patch for mermaid with a fix: description should do it.

🟡 [important] PR description is contradictory

The title says "fix(flowchart): improve subgraph direction handling" and the body says "This PR does not attempt to fix Dagre, but provides a clear test and documentation of the issue." The diff clearly does attempt a fix — both mermaid-graphlib.js and flowDb.ts change runtime layout behavior. Worth rewriting the description to reflect what's actually being changed (which condition, which code path, and what the expected behavior shift is) — that helps future maintainers reading git blame.

Behavioral question worth flagging in the description

Worth being explicit about how the new logic handles subgraphs without an explicit direction keyword:

• Old behavior: !externalConnections && hasChildren → create a separate cluster graph, defaulting to the opposite of the parent's rankdir. So a subgraph in a TB flowchart (with no direction) would lay out internally as LR by default.
• New behavior: only clusterData?.dir && hasChildren triggers a separate cluster graph. Default-direction subgraphs now inherit the parent's rankdir.

That's a defensible direction (no pun intended), but it's a visible default-behavior change that could shift many existing flowcharts. The full e2e Argos run is the only way to know how broad the impact is — and if the change is intentional, the changeset should call it out so users know what's coming.

Security

No XSS or injection concerns — the layout-algorithm changes don't touch DOM sinks or user-facing string interpolation, and the new manual HTML page is a standard mermaid-init page (not loaded by the published library).

Summary

Severity	Count
🔴 blocking	2
🟡 important	3
🟢 nit	0
💡 suggestion	0
🎉 praise	2

The conceptual fix is the right shape — please don't take the volume of feedback as discouragement. The combination of "shared layout code with broad blast radius" + "no automated tests" + "broken manual repro" is what's pushing this to changes-requested rather than just comments. With the Cypress coverage in place and an Argos diff to look at, this could land cleanly. Happy to help if any of the above is unclear.

[argos-ci]

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

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

[codecov]

Codecov Report

❌ Patch coverage is 0% with 75 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.26%. Comparing base (8e7a0c6) to head (d619b19).
⚠️ Report is 11 commits behind head on develop.

Files with missing lines	Patch %	Lines
...g-util/layout-algorithms/dagre/mermaid-graphlib.js	0.00%	67 Missing ⚠️
packages/mermaid/src/diagrams/flowchart/flowDb.ts	0.00%	7 Missing ⚠️
packages/mermaid/src/diagrams/state/dataFetcher.ts	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7672      +/-   ##
==========================================
- Coverage     3.26%   3.26%   -0.01%     
==========================================
  Files          598     598              
  Lines        60610   60676      +66     
  Branches       914     914              
==========================================
  Hits          1981    1981              
- Misses       58629   58695      +66     

Flag	Coverage Δ
unit	3.26% <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/diagrams/flowchart/types.ts	100.00% <ø> (ø)
packages/mermaid/src/diagrams/state/stateDb.ts	0.00% <ø> (ø)
packages/mermaid/src/rendering-util/types.ts	100.00% <ø> (ø)
packages/mermaid/src/diagrams/state/dataFetcher.ts	0.35% <0.00%> (-0.01%)	⬇️
packages/mermaid/src/diagrams/flowchart/flowDb.ts	0.00% <0.00%> (ø)
...g-util/layout-algorithms/dagre/mermaid-graphlib.js	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.

[sjackson0109]

The ci items of concern now are the argos-ci tests.

Category	Count	Caused by this PR
Unchanged diagrams	2794	NO IMPACT
Added (new tests)	2	Intended diagrams created > our new test screenshots (expeced)
Changed: architecture flaky test	1	❌ NO NEW IMPACT > pre-existing situation 0% stability for 2 months on develop itself

[sjackson0109]

Any chance one of you can review and consider approving?
@ashishjain0512 @pbrolin47 @knsv @lee-treehouse
I would appreciate a review when you have a moment. This fixes a 2-year-old issue (#4648) where subgraph direction keywords were silently discarded whenever a subgraph had external connections. Argos shows 2794 unchanged + 2 new test screenshots + 1 pre-existing flaky architecture test (0% stability on develop itself for 2 months, unrelated to this PR).

[sjackson0109]

CI status — unit-test failure is pre-existing, not introduced by this PR

The unit-test job is failing due to pre-existing test failures that exist identically on upstream/develop HEAD (8b52e5378):

Failing test file	Failures	Root cause
packages/parser/tests/treeView.test.ts	19	incomplete treeView parser feature (merged in #7527)
packages/mermaid/src/diagrams/treeView/parser.spec.ts	27	same
packages/mermaid/src/diagrams/cynefin/cynefin.integration.spec.ts	15	@mermaid-js/parser missing DomainBlock/Transition/Cynefin exports (merged in #7535)
packages/mermaid/src/diagrams/wardley/wardleyParser.spec.ts	7	pre-existing
packages/mermaid/src/diagrams/architecture/svgDraw.spec.ts	1	canvas unavailable in jsdom (pre-existing)
packages/mermaid/src/mermaidAPI.spec.ts	1	same canvas issue
2 others	2	canvas issue

Verified locally against upstream/develop: both branches produce 8 failed | 129 passed, 72 individual test failures — identical counts, identical test names.

This PR introduces zero new test failures. All flowchart and graphlib tests pass:

• mermaid-graphlib.spec.js → 19/19 passed ✅ (including 4 new GLB-DIR tests)
• All flowchart diagram tests → 971 passed, 3 skipped ✅

[knsv]

I could rerun the unit test, and then it worked. GitHub had a network glitch.

[knsv]

Thanks for tackling this one, @sjackson0109 — #4648 has been open since 2023 and the diagnosis here is exactly right. The cluster-extraction predicate using !externalConnections was the wrong signal; pivoting to explicitDir cleanly separates the fix from the legacy default-behavior path. Really nice work, and the writeup in the PR description, (especially the behavior-change matrix) made this a much faster read.