Architecture decision record
ADR-0007: Lay diagrams out in the browser, not with a graph-layout library
Context
Agents draw diagrams of the user's code. Coordinates that a model places by hand overlap once a graph passes about eight nodes. The VS Code preview renders artifacts from their text through srcdoc, so a relative <script src> never loads there. The extension avoids heavy runtime dependencies, and elkjs, the strongest layout library, is EPL-2.0 and about 1.5 MB.
Decision
We will lay diagrams out in the browser. The agent gives each node a data-rank (its step along the flow) and a data-lane (its position across it). CSS grid places the nodes, and a small dependency-free runtime, inlined in the artifact by add_open_design_diagram_runtime, draws right-angle connectors through the gaps between ranks and lanes.
Options considered
| Option | For | Against | Outcome |
|---|---|---|---|
| elkjs in Node, returning coordinates | Best compound layout and edge routing | EPL-2.0, ~1.5 MB, the agent still transcribes coordinates | Rejected |
| dagre in Node | MIT, small | Weak group layout, curved edges only | Rejected |
| Agent-placed SVG coordinates | No machinery | Degrades past ~8 nodes; several fix rounds | Rejected |
| CSS grid + inline runtime | Browser measures text; same render in preview, export and check; no dependency | The agent orders lanes; dense graphs can still cross | Chosen |
Consequences
Positive
- One HTML file renders identically in the preview, in exports and in any browser.
- Text edits and design-token tweaks re-flow the diagram for free.
Negative
- Crossing minimisation is left to how the agent orders lanes; the visual check flags links that pass through nodes.
- The runtime ships inside users' files, so it is versioned and upgraded in place by re-running the tool.
Neutral
- Diagrams need scripts to render; the PNG and PDF exports are the portable form.
Sources
openspec/changes/archive/2026-10-07-add-codebase-diagrams/design.mdpackages/core/src/generation/diagramRuntime.tspackages/vscode/src/extension/customEditors/artifactEditorProvider.ts