Make the graph readable on big codebases: run order, paths, fewer boxes

CHANGELOG.md

@@ -4,6 +4,24 @@ Every change a user would notice, newest first ([Keep a Changelog](https://keepa
 follow [Semantic Versioning](https://semver.org/); before 1.0, a minor version may change what a command does.
 ## [Unreleased]
 
+### Changed
+
+- A function's box in the graph lists what it does in the order its code does it: a numbered row for each call to
+  its own functions, each AWS or library call and each HTTP request, indented inside loops and ifs, marked ↻ in a
+  loop and "if" when it runs only sometimes. Each call's arrow leaves from its row, and the boxes it calls are stacked
+  in the same order, so the graph reads top to bottom. A call not drawn is a dimmed row; click it, or **Open its
+  calls ›**, to draw the graph from that function. Calls in a row to one service the same way are one row
+  ("SQLite SELECT (+2)"), and a box lists at most 6 rows besides the ones its arrows leave from.
+- Pointing at a box in the graph keeps every path through it in sight, not just the boxes next to it: what calls it
+  up to the entry point, and what it calls and reaches down to AWS, a database or the web. Pointing at a service
+  shows every path that reaches it. Clicking a box keeps its paths lit while its code is open.
+- The graph draws 14 functions by default, down from 24, so a big codebase opens on a picture you can take in.
+  `--functions` still sets your own limit, and a box's calls not drawn still open as a graph of their own.
+- A function that only passes on to one other no longer takes a box when the graph can't draw them all: the arrow
+  runs past it, dashed, and says which ("via load_config()").
+- On a graph of more than 10 functions, function boxes leave out their docstrings and when pills. Pointing at a box
+  shows all of it, and now also when it's called ("Called only when ...").
+
 ## [0.6.0] - 2026-10-20
 
 ### Changed

README.md

@@ -80,7 +80,7 @@ string is flagged.
 | `-e`, `--entry` | `module.function`, `module.Class.method`, `file.py[:function]`, or part of a name |
 | `-l`, `--list` | List entry points and stop |
 | `--plugins` | List platforms, libraries and deploy files and stop |
-| `--all` | Draw every function (default: 24 functions, 5 calls deep) |
+| `--all` | Draw every function (default: 14 functions, 5 calls deep) |
 | `--depth N`, `--functions N` | Your own limits |
 | `--serve`, `--port N` | Serve on localhost, redraw on change |
 | `--mermaid` | Print the graph as Mermaid |

docs/reading.md

@@ -24,6 +24,21 @@ Read it left to right.
 ![A code-node graph](images/graph-light.webp#only-light){ loading=lazy }
 ![A code-node graph](images/graph-dark.webp#only-dark){ loading=lazy }
 
+### Inside a function's box { #rows }
+
+A function's box lists what it does, top to bottom in the order its code does it: each call to your own functions,
+each AWS or library call, and each HTTP request, one numbered row each. The arrow for a call leaves from its row,
+and the boxes it calls are stacked in the same order, so you can read down the box and across to the next column.
+
+| In a row | Means |
+| --- | --- |
+| Indented | Inside a loop or an `if` in this function |
+| ↻ | In a loop: once per item |
+| if | Only sometimes: point at the row for the test |
+| Dimmed | A function not drawn here: click it to open the calls |
+| `SQLite SELECT (+2)` | Three calls in a row to one service, the same way |
+| +4 more | Calls left out of the box: **Open its calls ›** draws them all |
+
 ### Arrow colours { #arrows }
 
 | Arrow | Means |
@@ -37,7 +52,9 @@ Read it left to right.
 | <span style="color:#f59e0b">●</span> amber | a warning is about it, such as an HTTP request with no timeout |
 
 !!! tip "Worth knowing"
-    Point at a box and everything it isn't connected to fades out.
+    Point at a box and everything not on a path through it fades out: what calls it, all the way up to the entry
+    point, and what it calls and reaches, all the way down. Point at S3 or a database to see every path that gets
+    there. Click a box and its paths stay lit while its code is open.
 
 ??? more "Zoom, full screen and big graphs"
     The graph sits in a box of one size, about the window's height, and is drawn at its real size. **Auto** shrinks
@@ -57,11 +74,11 @@ Read it left to right.
     anywhere outside it, or the browser's Back button. Without JavaScript, × and Back still close it.
 
 ??? more "Open the calls a box leaves out"
-    A box whose calls aren't drawn says so in blue, "+12 calls not drawn". Click it and the graph starts from that
-    function, with every call it makes and whatever they reach. The line over the graph is the path down to it from
+    A box whose calls aren't drawn ends with **Open its calls ›** in blue, and its rows for them are dimmed. Click
+    either and the graph starts from that function, with every call it makes, in order, and whatever they reach. The line over the graph is the path down to it from
     the entry point: click a name in it to go back up, or the browser's Back button. **All** in the graph's bar draws
-    every function at once. This is the one part of the page that needs JavaScript; without it the line is plain
-    text, and the Step by step tab has every call.
+    every function at once. This is the one part of the page that needs JavaScript; without it the link isn't shown,
+    and the Step by step tab has every call.
 
 ## Step by step { #steps }
 

docs/usage.md

@@ -65,10 +65,13 @@ with the folder's name, so you can tell them apart.
 
 ## Large projects { #limits }
 
-The graph shows 24 functions, 5 calls deep: starting from the entry point, it keeps taking the function that leads to
+The graph shows 14 functions, 5 calls deep: starting from the entry point, it keeps taking the function that leads to
 the most code (and to AWS, the web and environment variables), so the boxes are the ones doing the work, not the
-nearest helpers. A box whose calls are left out says so ("+3 calls not drawn"): click that line and the graph starts
-from that function instead, with every call it makes, and a path above it back up to the whole graph. **All** in
+nearest helpers. A function that only passes on to another one doesn't take a box: the arrow goes past it, dashed, and
+says so ("via load_config()"). Each function's box lists up to 6 of its calls in the order they run; past 10
+functions the boxes drop their docstrings, which are in the card that shows when you point at a box. A call not drawn
+is dimmed in its box: click it, or **Open its calls ›**, and the graph starts from that function instead, with every
+call it makes, and a path above it back up to the whole graph. **All** in
 the graph's bar draws every function at once, for up to 150 of them. The step-by-step list always has all of them.
 
 ```bash
@@ -104,7 +107,7 @@ to see its commit. The gear in the panel's head turns that off. It's read with `
 | `--plugins` | List the plugins |
 | `--serve`, `--port` | Live page (8765, or the next free port) |
 | `--all` | Draw every function |
-| `--depth`, `--functions` | Graph limits (5, 24) |
+| `--depth`, `--functions` | Graph limits (5, 14) |
 | `--mermaid` | Print Mermaid |
 | `-o`, `--out` | Where to save |
 | `--no-open` | Don't open a browser |