feat(swimlanes): add swimlanes as a standalone diagram type with a layered orthogonal layout (#2028)

[knsv-bot]

Summary

Adds swimlanes — a layered diagram type for visualising a flow across lanes/roles — implementing #2028. It introduces the swimlanes keyword, a dedicated layered-orthogonal layout pipeline, a new SwimlanesDiagramConfig, and a DOM-decoupled layout-testing (DDLT) framework for fast headless layout regression testing.

swimlanes LR
  subgraph Intake
    A[Request] --> B{Triage}
  end
  subgraph Delivery
    C[Build] --> D[Ship]
  end
  B -->|accept| C

Design — a standalone diagram type

Swimlanes is a standalone diagram type: it owns the swimlanes keyword, its own detector, SwimlanesDiagramConfig, documentation, and a dedicated layout pipeline. Users select it directly with swimlanes — it is not a flowchart mode or option.

Because a swimlanes diagram body uses the same node/edge syntax and shape vocabulary as a flowchart, the implementation reuses the mature flowchart parser, DB, and renderer through a createFlowDiagram({ defaultLayout: 'swimlanes' }) factory rather than re-implementing them. Two deliberate implementation choices follow from that reuse:

• The swimlanes keyword extends the existing flowchart JISON grammar — the diagram body is that grammar, so a separate one would only duplicate it.
• The diagram module composes the flowchart factory internally. This is an implementation dependency behind the diagram's own plugin contract, not user-visible coupling.

Layout pipeline

The swimlanes layout (rendering-util/layout-algorithms/swimlanes/) runs entirely on the parser-produced LayoutData, independent of the DOM:

1. Lane-aware layering — Sugiyama-style rank assignment with a multitree subtree-ordering pass for crossing reduction.
2. Orthogonal edge routing — bimodal port assignment on node borders + Manhattan routing, with line-hop crossings.
3. Direction transform — a single left-to-right pipeline reused for all four directions via a coordinate transform.

DDLT — DOM-decoupled layout testing

rendering-util/layout-algorithms/ddlt/ parses a .mmd fixture, applies node sizes captured from a real browser render (.sizes.json, freshness-pinned to the source), runs the layout in Node, and scores the result with validateLayout() (a 0–1000 score plus structured issues). This lets layout regressions be caught in fast headless unit tests, with a global fixture sweep as the safety net. The browser-side size-capture hook is loaded lazily and never ships in the production render path.

Config

New SwimlanesDiagramConfig (config.swimlanes.*): lineHops, ignoreCrossLaneEdges, optimizeRanksByCrossings, isLabelNode. Everything shared with flowcharts (curve, htmlLabels, spacing, theming, …) is still read from the flowchart config.

Test plan

• Unit: 45 spec files across the layout phases and the DDLT framework, including a global fixture sweep over the 16 layout-test fixtures.
• e2e: cypress/integration/rendering/swimlanes/ renders all 16 fixtures through imgSnapshotTest (Argos visual baselines) plus a handdrawn/rough-mode subset, and asserts theme / style / classDef behaviour.

Review feedback addressed

First pass:

• Removed a leftover BUILD_NUMBER flowchart debug log; reverted an incidental shared labelHelper change (now byte-identical to develop).
• Extracted the DDLT size-capture machinery out of the production render path (lazy dynamic import).
• Moved the swimlane-only options out of FlowchartDiagramConfig into SwimlanesDiagramConfig.
• Added imgSnapshotTest visual coverage and handdrawn snapshots to the cypress suite.
• Removed the bundled academic reference paper from the source tree.

Second pass:

• Scoped the swimlanes orthogonal edge-port clipping behind layout === 'swimlanes', restoring develop's exact endpoint clipping for ELK / dagre / every other layout (fixes the ELK edge-port Argos diff).
• Removed three redundant no-op appendChild calls from insertEdgeLabel (createLabel already inserts each label into its parent).
• Un-exported the swimlanes-only orthogonalizeToLabelClippedPoints helper from shared edges.js.
• Confirmed lineJump.ts is wired into the swimlanes render path — adjustLayout.ts imports and calls applyLineJumpsToSvg for the lineHops post-processing.
• Verified handdrawn/rough rendering and kept its e2e subset enabled — the assertion just needed to also match the rough-node class mermaid uses for nodes in handdrawn mode (confirmed in real Chromium).

Third pass:

• Isolation (🟡): documented a "layout-variant diagram" exception in diagrams/CLAUDE.md — a diagram that reuses a parent's parser/DB/renderer wholesale and only swaps the layout engine may import the parent's public entry points only, with pinned criteria and a closed, enumerated list (swimlanes → flowchart). Added inline rationale at both import sites. Pushed back on relocating createFlowDiagram to common/: it would invert the dependency (common/ → flowchart/) for no real decoupling.
• Dead code (🟡): removed phase4.mergeDummies.ts (−517) — it only emitted edge routing that routeEdgesOrthogonal immediately discards (node x/y were passthrough). Behaviour-preserving; all pipeline/LR specs pass.
• Public type — Positions (🟡): this PR threads a new Positions type (nodes/edges position maps) through DrawDefinition. This is intentional and forward-looking — Positions is meant to become the shared output type for all layout engines, not just swimlanes. The unified flowchart renderer is typed as its first consumer (positions?: Positions); future engines will populate the same structure.
• Geometry duplication (🟡): split to follow-up Swimlanes: consolidate or formally separate the two geometry modules (different epsilons) #7800 — the two epsilons are intentional (1px validation vs 1e-3 routing precision) but the concept duplication needs DDLT + e2e verification on its own.
• Docs (🟡): added the Available since MERMAID_RELEASE_VERSION availability placeholder.
• Smaller: documented symmetryScore as unimplemented/NaN (not symmetry-aware); explained the intentional double anchorLabelsToPolyline (anchor → reshape → re-anchor); removed the unused ValidationIssue re-export; typed flowRenderer's positions param.

Resolves #2028

[knsv-bot]

Thanks for the depth here — this was a genuinely useful pass. Status on the 🟡 stack:

🟡3 dead phase-4 routing — fixed. You were right. mergeDummies only produced edgePoints; node x/y were spread through from assignCoordinates untouched, and layoutCore deletes every edge's points before routeEdgesOrthogonal re-routes. So the corridor/obstacle/track machinery was never rendered. Removed the file (−517) and its test; node positions and routed edges are unchanged (pipeline/LR specs still pass). Net −536 across the branch.

🟡1 isolation — documented the exception (option 2). Fair call that this needed a name. I've added a "layout-variant diagram" category to diagrams/CLAUDE.md: a diagram that reuses a parent's parser/DB/renderer wholesale and only swaps the layout engine may import the parent's public entry points only, with three pinned criteria and a closed, enumerated table (swimlanes → flowchart is the sole entry; new ones need maintainer sign-off). Inline rationale added at both import sites in the PR.

I'd push back on option 1 (move createFlowDiagram to common/): common/ is currently a true leaf (imports no diagram), and createFlowDiagram hard-imports FlowDB/flowRenderer/flowParser/flowStyles. Relocating it inverts the dependency — common/ → flowchart/ — for zero real decoupling. The imports already target flowchart's public exports (createFlowDiagram, getFlowchartStyles), never internals, so the coupling is already at the right granularity; this makes it explicit and bounded rather than relocating it.

🟡4 Positions type — owned as public. Decision: Positions is the forward-looking public output type for all layout engines, not swimlanes-only. Typed the first consumer accordingly (flowRenderer positions?: Positions, was any) and called this out in the PR description.

🟡2 duplicate geometry — split to a follow-up: #7800. The two epsilons look intentional (1px validation tolerance vs 1e-3 routing precision), so a naive unify would be wrong, but the concept duplication is real. Since it's edge-routing math shared by all swimlanes rendering, it needs DDLT + e2e verification on its own, so I've filed #7800 to decide consolidate-vs-extract-shared-core-vs-document.

🟡5 release-version placeholder — fixed. Added Available since MERMAID_RELEASE_VERSION and regenerated the published doc.

Smaller items: symmetry TODO — documented symmetryScore as unimplemented/NaN and not symmetry-aware (both field + assignment). Double anchorLabelsToPolyline — intentional (anchor → passes reshape → re-anchor); commented. ValidationIssue re-export — removed. flowRenderer positions: any — done with 🟡4.

The larger suggestions (router.ts split, PostProcessContext, SwimlaneLayoutData view type for the as any casts, direction/ → routing/ reorg, phase2.options.ts rename) I agree with as roadmap follow-ups rather than blockers for this PR — happy to track them as issues if you'd like. The flow.jison swimlanes-keyword note is noted as an open question for the eventual Langium migration.

[ashishjain0512]

[sisyphus-bot]

Thanks for the quick turnaround, Knut — five focused follow-up commits land cleanly. Walking through them in order:

What's resolved since the last round

• 🎉 [praise] 735b66f48 — Phase 4 dead routing removed cleanly: 517 lines gone from phase4.mergeDummies.ts, assignCoordinates inlined into the pipeline, and the corresponding test deleted. Behavior unchanged. That's exactly the right outcome — net negative diff, no behavioral regression.
• 🎉 [praise] 3529a85b0 — flowRenderer-v3-unified.ts:21 now uses positions?: Positions instead of any. The first consumer of the new public type is now properly typed.
• 🎉 [praise] 3c5ac304b — MERMAID_RELEASE_VERSION placeholder added to the syntax doc as a top-of-page "Available since" note. Release tooling will stamp it on publish.
• 🎉 [praise] 6358293ad — anchorLabelsToPolyline double-call now documented inline (anchor → cleanup → re-anchor), symmetryScore is explicitly marked as unimplemented/NaN at both the interface and the assignment so the aggregate score isn't mistaken for symmetry-aware, and the unused ValidationIssue re-export is gone. All exactly what was asked for, no excess.
• 🎉 [praise] 1d6fa8eb6 — Inline rationale at both swimlanes ↔ flowchart import sites. As you noted in your earlier reply, this is a deliberate layout-variant design — I'm not pressing further on the architectural shape.
• 🎉 [praise] Reduced as any count from 42 → 19 (~55% drop, mostly via the phase 4 deletion). Healthy direction even without a dedicated typing pass.

Things still worth resolving

🟡 [important] Duplicate geometry modules with different epsilons (carry-over)

Both files are still present and still disagree on EPS:

• rendering-util/layout-algorithms/layout-utils/geometry.ts:14 — export const EPS = 1
• rendering-util/layout-algorithms/swimlanes/direction/geometry.ts:1 — const EPS = 1e-3

I noted this last round and didn't see it addressed in the five follow-up commits. It's the single largest unresolved correctness-drift risk in the PR — the two modules implement overlapping primitives (segmentOrientation/segmentsCross/normalizePolyline style helpers, polyline simplification, orthogonal-segment derivation) at three orders of magnitude apart in tolerance, with incompatible segment shapes.

Even if a full consolidation is too much surgery for this PR, two cheaper interim moves would help: (1) re-export EPS from a single source and pick one value (or document why the two are not unifiable), and (2) leave a TODO comment in each module pointing at the other so the next person to touch it sees the duplication. Happy to keep this as a follow-up issue if you'd rather land swimlanes first and consolidate after — just want to make sure it's tracked somewhere durable.

🟡 [important] CI dependency-review is failing — high-severity vuln introduced by lockfile bump

The dependency-review check on 3c5ac304b is red on GHSA-7h2j-956f-4vf2 ("Uncontrolled Resource Consumption" in @isaacs/brace-expansion, high severity). Source:

• Develop pins dependency-tree@11.4.3.
• This PR's pnpm-lock.yaml bumps it to 11.5.0 (transitive, via spec-change@1.11.21), and the new version pulls in the vulnerable @isaacs/brace-expansion.
• spec-change itself is unchanged at 1.11.21 — the bump is just lockfile churn.

It's almost certainly incidental to swimlanes (your branch was last rebased and pnpm refreshed the transitive). But CI is gating on it, so the PR can't merge clean as-is. Options:

1. pnpm install --frozen-lockfile=false and pin dependency-tree back to 11.4.3 via pnpm.overrides until the upstream fix lands.
2. Add a dependency-review.yml allowlist entry for GHSA-7h2j-956f-4vf2 with a date-bounded comment.
3. Wait for an upstream spec-change patch.

If (1) feels too heavy, a quick lockfile re-roll matching develop's transitive set would likely also work.

Smaller items

• 🟢 [nit] The inline comments in swimlanesDiagram.ts:1-7 and styles.ts:5-9 now point readers to a "sanctioned 'layout-variant diagram' exception in diagrams/CLAUDE.md" — but packages/mermaid/src/diagrams/CLAUDE.md doesn't yet contain that section. Either add a short "Layout-variant diagrams" subsection there (5-10 lines: definition, criteria, swimlanes as the first sanctioned example) or rephrase the inline comments so they don't promise a doc that isn't there. Five-minute fix either way; not worth blocking on.
• 🟢 [nit] helpers.ts:209-279 — the lane-width tridiagonal-style solver is still uncommented. The recurrence u[i+1] = 2*d[i] - u[i] at line 268 and the lower/upper bound walk below it are doing real math without a docstring or isolated test. A 4-5 line comment explaining what u, d, and the constraint loop solve would make this maintainable for the next person; bonus points for a small focused unit test that pins a 3-lane case to expected widths.
• 🟢 [nit] as any is down to 19, but the underlying pattern (swimlane-only properties — direction, swimlaneContentTop — smuggled onto canonical LayoutData/Node via casts) is unchanged. The biggest concentrations are still direction/materializedGeometry.ts, phase4.coordinates.ts, and helpers.ts. A SwimlaneLayoutData = LayoutData & { ... swimlane-specific fields ... } view type at the swimlane boundary would let almost all of them drop and would document, in the type system, exactly which extra fields the pipeline expects.

Architectural follow-ups (not for this PR — issues worth filing)

• 💡 [suggestion] orthogonalRouter/router.ts is still 2,242 lines for a single exported function. Worth a tracking issue for "split into pipe construction / track allocation / segment emission" — it doesn't have to land before swimlanes ships, but the moment a real edge-routing bug surfaces, the lack of internal seams will hurt.
• 💡 [suggestion] direction/ is still doing double duty as both the LR/BT transform and a catch-all for geometry/label-anchoring/endpoint-clipping/terminal-stub/shared-track/nudging/crossing-resolution. The non-lrTransform.ts files in there really belong in a sibling routing/ or postPasses/ folder. Same story: file an issue, do it as a follow-up rename PR.
• 💡 [suggestion] phase2.options.ts is consumed by phases 2, 3, and 4 — the phase2 prefix is misleading. Rename to laneResolver.ts or fold into helpers.ts.

Test coverage

For completeness: 40 unit specs under swimlanes/__tests__/ + DDLT spec sweep + 5 DDLT-framework specs + cypress visual + handdrawn snapshots. That's strong coverage for a fresh diagram type, and the DDLT sweep over the 16 layout fixtures is exactly the right safety net for an algorithm-heavy module.

Security & isolation

No new XSS or injection surface introduced by the follow-up commits. Algorithm code in swimlanes/ and layout-utils/ continues to be cleanly isolated from diagram folders — the documented flowchart reuse is the only cross-diagram edge.

Verdict

Switching to comment-only this round. The substantive 🟡 stack from last review is mostly gone — what remains is one carry-over (geometry consolidation), one CI quirk on a transitive bump that may or may not be yours to fix, and a small set of nits that would be nice to address before merge.

Once the dependency-review CI is green and you've made a call on the geometry consolidation (do it here or file a follow-up issue), I'm happy to take another pass. Nice work tightening this up.

[ashishjain0512]

[sisyphus-bot]

CI is clean and the 🟡 stack from rounds 1+2 has either landed or been properly deferred. Walking through the round-3 commits:

What landed since round 2

• 🎉 [praise] c9f57cd92 + e74bd62ba + e9a735d76 + d36791524 — the dependency-review fix is a textbook response. Lockfile resynced to develop's base (dropped ~1835 lines of incidental churn), dependency-tree pinned to 11.4.3, @isaacs/brace-expansion and minimatch overridden as a backstop with dev-only scope called out in each commit message. CI is now CLEAN.
• 🎉 [praise] 4bfdbce66 + 850bfdc85 — singular swimlane rename done thoroughly: grammar keyword, schema property (SwimlanesDiagramConfig → SwimlaneDiagramConfig), regenerated config.type.ts, every layout-test .mmd + refreshed sourceSha256, layout-algorithm name, detector id, aria-roledescription, dev-explorer dropdown. 1306 unit tests + types:verify-config + tsc + DDLT sweep all green per the commit notes. Disciplined cleanup; reads as a single atomic rename.
• 🎉 [praise] 38df567a7 — swimlane.cluster rect border now uses options.clusterBorder instead of options.clusterBkg. That's the semantically correct theme variable for a border — clusterBkg was always a workaround for "match background so the border disappears." The new neo-look cluster rules in the same commit are a nice consistency win.
• 🎉 [praise] The reply on round 1 was substantive: #7800 filed as a tracking issue for the geometry consolidation with the technical justification (1px validation tolerance vs 1e-3 routing precision — two epsilons that serve different purposes, so a naive unify would be wrong). That's exactly the right way to defer; the issue carries the context forward.
• 🎉 [praise] Inline rationale at both swimlanesDiagram.ts and styles.ts import sites makes the "layout-variant exception" readable in the code itself. The canonical CLAUDE.md update has to happen upstream in mermaid-ops (the file is synced, "Do not edit directly in the submodule") — that's an out-of-band step but the in-code rationale is the part that matters for future contributors reading the diff.

Small items worth mentioning (none blocking)

• 🟢 [nit] helpers.ts:209-279 — the lane-width tridiagonal-style solver still has no docstring. The u[i+1] = 2*d[i] - u[i] recurrence and the lower/upper-bound walk are doing meaningful math without a 4-5 line comment explaining what they solve. Not blocking — flag for a follow-up cleanup PR, or take it whenever someone next touches that block.
• 🟢 [nit] src/styles.ts:124-126 — the new [data-look="neo"].swimlane.cluster rect { filter: none; } rule is swimlane-specific but lives in the shared styles.ts. It could equivalently live in diagrams/swimlanes/styles.ts where the rest of the swimlane CSS rules already are; the pattern guidance in CLAUDE.md (don't add diagram-specific logic to shared rendering code) lines up here. Pure cleanup — the behavior is correct.
• 🟢 [nit] as any count is unchanged at 19 (was 42 before the phase-4 deletion). The underlying pattern — smuggling swimlane-only fields (direction, swimlaneContentTop, etc.) onto canonical LayoutData/Node via casts — is the real thing to retire eventually. A type SwimlaneLayoutData = LayoutData & { ... } view at the swimlane boundary would let almost all of them drop and would document exactly which extra fields the pipeline relies on. Worth a follow-up issue alongside #7800.

Deferred architectural follow-ups (tracking, not for this PR)

• 💡 [suggestion] orthogonalRouter/router.ts — 2,242 lines for one exported function, all routing state in one closure. Splitting along pipe construction / track allocation / segment emission would make internal seams testable. File an issue.
• 💡 [suggestion] direction/ folder is doing double duty (LR/BT transform + catch-all for geometry / label anchoring / endpoint clipping / shared-track nudging / crossing resolution). The non-lrTransform.ts files belong in a sibling routing/ or postPasses/ folder. File an issue.
• 💡 [suggestion] phase2.options.ts is consumed by phases 2, 3, and 4 — the phase2. prefix is misleading. Rename to laneResolver.ts or fold into helpers.ts in a follow-up.

Verdict

Approving. The 🟡 stack is resolved or has a tracked follow-up (#7800), CI is green, the renames and theme-variable fixes are clean, and the dependency response was as careful as it gets. Nice landing.

Suggested follow-up issues you may want to file alongside #7800 so the architectural items don't get lost:

1. orthogonalRouter/router.ts split
2. direction/ folder reorganization
3. SwimlaneLayoutData view type to retire the remaining as any casts
4. Tridiagonal solver docstring + isolated test

Thanks for the careful work across all three rounds — and let's get this in. 🚀