Summary
Complex Mermaid flowcharts in bb currently use Mermaid's default layout engine. For wider or denser dependency diagrams, the result can be difficult to scan because ranks, node spacing, and edge routing are less suitable for large graphs.
I propose registering Mermaid's official ELK layout package and selecting elk as the default layout for bb-rendered Mermaid diagrams. This is a narrowly scoped renderer change: it preserves bb's existing theme and strict security configuration while improving layout quality for complex flowcharts.
Proposed change
- Add
@mermaid-js/layout-elk as an app dependency.
- Load it alongside Mermaid and register its layout loader exactly once before sharing the Mermaid instance.
- Set the existing Mermaid configuration's layout to
elk.
- Keep
securityLevel: "strict", existing theme variables, and the current lazy-loading behavior unchanged.
Prototype
The implementation is available on the public fork branch hxy91819/bb@feature/mermaid-elk-layout, commit dfa62783f.
The relevant prototype evidence is commit-pinned:
Validation
On the prototype branch:
pnpm exec turbo run test --filter=@bb/app --only -- --run src/components/ui/markdown-mermaid-diagram.render.test.tsx src/components/ui/markdown-mermaid-loader.test.ts — 2 files, 5 tests passed.pnpm exec turbo run typecheck --filter=@bb/app — passed.
The render test asserts that the existing strict Mermaid configuration selects ELK; the loader test asserts registration occurs once even with concurrent loads.
Screenshot status
No product screenshot is attached yet. The available local visual is a non-product proof of concept with non-English annotations, so it would not be appropriate upstream evidence. A direct bb rendering capture can be attached in a follow-up once produced.
Scope and trade-offs
This intentionally changes only the layout engine. It does not change diagram source, visual theme, HTML-label policy, security boundary, or add a user-facing layout selector in this iteration. ELK increases the client-side renderer payload, so bundle impact and real-world rendering performance should be considered during review.
AGENT GENERATED
Summary
Complex Mermaid flowcharts in bb currently use Mermaid's default layout engine. For wider or denser dependency diagrams, the result can be difficult to scan because ranks, node spacing, and edge routing are less suitable for large graphs.
I propose registering Mermaid's official ELK layout package and selecting
elkas the default layout for bb-rendered Mermaid diagrams. This is a narrowly scoped renderer change: it preserves bb's existing theme and strict security configuration while improving layout quality for complex flowcharts.Proposed change
@mermaid-js/layout-elkas an app dependency.elk.securityLevel: "strict", existing theme variables, and the current lazy-loading behavior unchanged.Prototype
The implementation is available on the public fork branch hxy91819/bb@feature/mermaid-elk-layout, commit
dfa62783f.The relevant prototype evidence is commit-pinned:
layout: "elk"Validation
On the prototype branch:
pnpm exec turbo run test --filter=@bb/app --only -- --run src/components/ui/markdown-mermaid-diagram.render.test.tsx src/components/ui/markdown-mermaid-loader.test.ts— 2 files, 5 tests passed.pnpm exec turbo run typecheck --filter=@bb/app— passed.The render test asserts that the existing strict Mermaid configuration selects ELK; the loader test asserts registration occurs once even with concurrent loads.
Screenshot status
No product screenshot is attached yet. The available local visual is a non-product proof of concept with non-English annotations, so it would not be appropriate upstream evidence. A direct bb rendering capture can be attached in a follow-up once produced.
Scope and trade-offs
This intentionally changes only the layout engine. It does not change diagram source, visual theme, HTML-label policy, security boundary, or add a user-facing layout selector in this iteration. ELK increases the client-side renderer payload, so bundle impact and real-world rendering performance should be considered during review.