Roadmap
What it does today
Section titled “What it does today”| Area | Shipped |
|---|---|
| Format | diagram.yaml with nodes, groups, edges, views, scenarios, custom kinds and edge kinds. Shorthand for edges and steps. Node docs from Markdown files. Long scenarios from their own files. A JSON Schema for editors. |
| Compiler | YAML to a validated, JSON-serialisable model. Errors with file:line:col and “did you mean” hints. Icons bundled at build time. Markdown rendered at build time. |
| Layout | Group by group, bottom up. ELK for flow groups, author-written rows, packed rows and grids, an obstacle-avoiding router for the edges between zones, and an automatic choice of direction. |
| Renderer | Pan, zoom, fit and full screen. Cards with icons, status, chips and badges. Entity cards with fields and relations. Zones and frames. Edge kinds with a generated legend, letter keys, hover focus and a planned-items toggle. A detail drawer. An interfaces table. Nested diagrams: a node can open another diagram, with a trail back. Light and dark. |
| Scenarios | Several per diagram. Phases, self steps, parallel steps, automatic multi-hop routing, five packet kinds, notes, hidden edges. A player with play, pause, step, scrub and speed. Flow, sequence and swimlane story presentations. A follow camera. Deep links. |
| Site | Astro and Starlight, <Diagram>, a GitHub Pages workflow and CI. |
| Playground | Live YAML preview, visual editing of nodes, groups and connections, local drafts, undo/redo, examples and YAML import/export. Open the playground. |
| Tooling | idocs check, list, schema, icons and new. Stale refs: warnings. An agent skill installable with npx skills add. |
Ideas under consideration
Section titled “Ideas under consideration”These are directions, in no particular order. Open an issue on GitHub if one matters to you.
More view types
Section titled “More view types”State diagrams, and relation lines that end on the field’s row of an entity card instead of on the card. The format reserves type: on views for this. The swimlane story is already done, as a presentation of a scenario rather than a view type.
Forked scenarios
Section titled “Forked scenarios”A variant such as “device offline at step 6” that shares the happy path up to a step and then branches, instead of repeating the first steps.
Export
Section titled “Export”SVG, PNG and GIF of a scenario, for READMEs and slides.
Layout in a worker, and at build time
Section titled “Layout in a worker, and at build time”ELK runs on the main thread, so a very large diagram pauses briefly the first time it appears. A worker would remove the pause, and build-time layout would remove ELK from the client entirely for diagrams that do not depend on measured text.
Visual regression
Section titled “Visual regression”Playwright screenshots of the examples in both themes, to catch layout changes that unit tests cannot.
Imports
Section titled “Imports”Mermaid and OpenAPI, so an existing diagram or API description is a starting point rather than a rewrite.
An MCP server
Section titled “An MCP server”Exposing check, list and icons as tools, so an agent does not need a shell.