ai/byre
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 15 Wiki Activity

Add nested diagrams with drill-down and cross-edge arrows

Browse Source
This commit is contained in:
Ian Gulliver
2026-10-23 09:57:58 -07:00
parent 2bc462ada6
commit 68e0cc3063
5 changed files with 592 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/agents/kb/diagrams.md
+35 -3
View File
@@ -30,8 +30,40 @@ highlight "Event loop" store server coord
- `highlight "Name" id id ...` names a set of boxes to light up together, with the arrows between them.
- Lines starting with `#` are comments. A mistake shows the source with the reason it wasn't drawn.
Keep each box to a title and one or two short detail lines, and draw only the arrows the reader needs; a picture with every dependency in it reads worse than prose.
## Nested diagrams
Check a diagram before you send it: `render_diagram` takes the block's body and returns a PNG of what the app draws, or the reason it can't. Look for crossing or overlapping arrows and labels sitting on top of each other, and adjust the rows, `aside` or arrows until it reads cleanly.
When a box hides a whole diagram of its own, give it an `inside` section instead of children. A top-level line `inside <id>` starts that box's diagram; the `row`s, arrows and highlights after it belong to it, up to the next `inside`. The box gets a mark, and in the full-size view selecting it shows an **Open** button; a breadcrumb leads back up.
To hand a diagram over as a file, `export_diagram` writes it as one self-contained HTML page with the app's exact layout and its full-size view's interactivity (click to highlight, highlight buttons, zoom and pan, light and dark mode); show it with `show_page`. The full-size view in the app has the same export as its Export HTML button.
```diagram
row
app "Byre.app"
row
server "internal/server" blue
aside store "internal/store" green
row
manager "agents.Manager" amber
app -> server
server -> manager "start · message"
store ..> coord "poke"
workers -> store "snapshots"
inside manager
row
coord "coordinator" "level-triggered"
live "live sessions"
row
workers "workers" "push · snapshot"
coord -> workers "start"
live -> workers "turn end"
```
- Ids are unique across the whole block, so an arrow or highlight anywhere can name a box at any level. Write each arrow once, between the boxes it really joins.
- Each level draws an arrow at the deepest boxes it can show: at the top, `store ..> coord` ends on `manager`; inside `manager`, `store` shows as a dashed ghost outside the frame, on the side where it sits above, and the arrow crosses the frame to `coord`. Clicking a ghost goes back up to it. Arrows that end up with the same ends merge into one.
- An `inside` can name a box from another `inside`, to any depth.
- A box can have both indented children and an `inside`: the children show inline as a preview, and when it's opened they form its diagram's first row, above the `inside` rows.
Keep each box to a title and one or two short detail lines, and draw only the arrows the reader needs; a picture with every dependency in it reads worse than prose. When a level grows past that, move a cluster into an `inside`.
Check a diagram before you send it: `render_diagram` takes the block's body and returns a PNG of what the app draws, every level stacked under its breadcrumb, or the reason it can't. Look for crossing or overlapping arrows and labels sitting on top of each other, and adjust the rows, `aside` or arrows until it reads cleanly.
To hand a diagram over as a file, `export_diagram` writes it as one self-contained HTML page with the app's exact layout and its full-size view's interactivity (click to highlight, highlight buttons, opening nested diagrams, zoom and pan, light and dark mode); show it with `show_page`. The full-size view in the app has the same export as its Export HTML button.