#8159·mermaid

Unify per-diagram-type default layout selection

Author: ashishjain0512Created Aug 28, 2026Updated Sep 10, 2026
LabelsStatus: Triage

Problem

Three different mechanisms currently answer the same question — "what layout does this diagram type use when the user hasn't asked for one?"

diagram mechanism where
mindmap getUserDefinedConfig().layout === undefined → stamp cose-bilkent onto the config mindmapDb.getData()
swimlanes createFlowDiagram({ defaultLayout: 'swimlane' }) flowDiagram.init
flowchart-elk / graph-elk detector mutates config.layout = 'elk' flowDetector-v2.ts, flowchart/elk/detector.ts

defaultLayout already exists, but only as a private option of createFlowDiagram rather than part of DiagramDefinition.

This scattering has caused two real bugs while making ELK the default in #8155:

  • Mindmap's default was missed entirely, because only the renderer was read and the decision lives in the db. Mindmaps silently switched from cose-bilkent to dagre.
  • The e2e suite's layout pin silently overrode swimlanes' defaultLayout, so the whole swimlanes suite rendered without lanes — and the swimlanes fixtures that run through the screenshot-only runner would have been baselined that way rather than failing.

There is also no way for a user to override the layout for one diagram type while leaving the rest on the global default.

Proposal

1. defaultLayout on DiagramDefinition — promote the existing createFlowDiagram option to the general diagram API so any diagram can declare its own default:

export const diagram: DiagramDefinition = {
  db, renderer, parser, styles,
  defaultLayout: 'cose-bilkent',
};

2. A per-diagram user override<diagramType>.layout, e.g. mindmap.layout, flowchart.layout.

[!IMPORTANT] This key must have no default in the config schema. Once it has one, a schema default is indistinguishable from a user's choice, so a user setting the global layout could not override it — which is precisely the bug fixed in #8155. The diagram's own default belongs in code (point 1), not in the schema.

3. Resolve in one place, with this precedence:

  1. <diagramType>.layout — user, per diagram type
  2. layout — user, global
  3. definition.defaultLayout — the diagram's own default
  4. the global schema default (elk)

Outcome

  • Retires all three ad-hoc mechanisms; mindmap, swimlanes and the ELK detectors migrate onto one path.
  • "Which layout runs, and why?" becomes answerable in a single function.
  • Removes the precedence trap where a diagram-type default silently loses to a user-supplied global value, which is what made the e2e pin dangerous.

Notes

  • Worth keeping a test that asserts each diagram type's resolved default, so a change to the global default cannot silently move one of them — that is how the mindmap regression escaped review.
  • Split out of #8155 to keep that PR reviewable; it is a diagram-API change and does not need to ship with the default switch.