fix(core): handle subgraph nesting better in graph_mermaid

[jasonphillips]

Currently, graph_mermaid can throw an error when subgraphs are deeply nested, due to its way of tracking subgraph names and its order of processing edges. We encountered this in production with a large graph which had a couple of levels of subgraphs and many edges.

See the nodes/edges fixture added in graph_mermaid.test.ts, which is a minimal reproduction of one part of our graph, and will throw the following error on main branch:

Found duplicate subgraph 'fooGenericSearch' -- this likely means that you're reusing a subgraph node with the same name. Please adjust your graph to have subgraph nodes with unique names

The graph (and original langgraph code that generated it) is valid, and doesn't have a duplicate subgraph, but the subgraph/prefix handling misrecognizes it as duplicate when traversing and tracking the set of subgraphs.

This PR fixes that, and can now render the graph correctly; and also pre-orders the edges so that subgraphs will appear in their correct nesting, which wasn't necessarily the case before.

Without the additional edge reordering, the test graph here was not properly nested:

due to incorrect ordering of subgraphs (excerpt):

      subgraph fooTool
      subgraph fooGenericSearch
         ...
      end
      subgraph fooSearchSource
         ...
      end
        ...
      end

With the fix, it is, thanks to ordering edges by depth before traversal:

          subgraph fooTool
          subgraph fooSearchSource
          subgraph fooGenericSearch
              ...
          end
              ...
          end
              ...
          end

I was able to test this rendering on our very large application graph and there were no unintended side effects / regressions; would be happy to have even more test cases for example graphs if needed--this particular script had little in the way of existing tests.

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
langchainjs-docs	Ready	Preview		Sep 9, 2025 10:05pm

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
langchainjs-api-refs	Ignored			Sep 9, 2025 10:05pm

[jacoblee93]

Nice catch, thank you!

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: bd5edae73812f96e6ca6e63b48ace03706d07001

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[christian-bromann]

@jasonphillips thanks for your contribution 🙏 our team has been focused on working on LangChain v1 and unfortunately couldn't give PRs as much attention as they need. We are in an effort to picking up where we left off. I will take this PR and discuss it with the team. Please stay tuned!