Viewer M3: review walk, phase overview and Reveal in Diagram

README.md

@@ -53,9 +53,10 @@ in the runbook. Only install one copy of the skill in each discovery path.
 To refine a particular node, edge, or finding, select it and use **Refine →
 Copy prompt**. Choose an intent or enter a specific question, then paste the
 prompt into the same assistant. The header is one row: the title, the
-assistant and revision, search, the severity toggles, **N not observed**, a
-**⋯** menu (legend, flow animation, fit, exports, shortcuts) and **Refine…**.
-In a narrow panel, such as beside your code, search and the revision move
+assistant and revision, search, the severity toggles, **N not observed**,
+**Review**, a **⋯** menu (legend, flow animation, fit, exports, shortcuts) and
+**Refine…**.
+In a narrow panel, such as beside your code, search, the revision and **Review** move
 into the **⋯** menu, and a row that is still too full folds **N not
 observed** into it too, so **Refine…** stays in view. The status bar counts steps and connections, shows the
 coverage status with its limitations, and says whether the cited files are
@@ -82,6 +83,36 @@ narrower than about 1260 px the rail is a bottom sheet under the diagram: a
 tab strip until you select something, then about half the height, with the
 selected card kept in view above it; Escape collapses it.
 
+To check a diagram claim by claim, press `r` (or **Review**). The review walk
+starts on the claims marked inferred or unresolved, the header's **N not
+observed** count, and can also walk the findings, every claim, or, after a
+cited file changed, the claims citing it. Each step selects the claim, shows
+it in Selection and, after a short pause, opens its cited lines beside the
+diagram, highlighted, while the keyboard stays on the diagram: `j` / `k` (or
+↓ / ↑, or the walk bar's up and down buttons) move, `[` / `]` change quote,
+Enter opens again and Escape ends the walk. A quote whose file changed is not
+opened; the walk says why. The walk remembers its place for each revision and
+records nothing else.
+
+To see the whole workflow at once, press Shift+0 (or **Phase overview** in the
+**⋯** menu). The overview shows each phase as a block of its step titles, with
+inferred and unresolved marks and the F labels of findings. Arrows count the
+connections from one phase to the next, and brackets count those that skip
+ahead or go back. Arrow keys and Enter (or a click) go to a phase; Escape
+returns you to where you were. The phase index in the diagram's lower right
+corner lists every phase with its findings and step count and marks the ones
+in view. Beside the code it shrinks to one line such as "4/6 Objective,
+optimizer & scheduler".
+
+To go the other way, from the code to the diagram, right-click a line in the
+editor and choose **Reveal in Diagram** (also **MLView: Reveal in Diagram** in
+the Command Palette; there is no default keybinding). It is offered on a file
+an open diagram cites that has not changed since the revision was published.
+The claim citing that line, or the selected lines, is selected and
+shown in the diagram, and the keyboard moves there. When several claims cite
+the line, a list asks which; on a line no claim cites, it offers the nearest
+claims in the file. It works in notebook cells too.
+
 The workflow supports custom phases, nested groups, branches and cycles,
 notebook cell references, and findings with evidence and counter-evidence.
 Observed, inferred, and unresolved claims remain distinguishable: only the

docs/LLM_WORKFLOW.md

@@ -168,6 +168,107 @@ again keeps its tab, its selection and an open bottom panel. With VS Code's
 screen-reader optimisation on, a selection is announced by its claim and
 nothing animates.
 
+The review walk goes through the displayed revision claim by claim. Press `r`
+on the diagram, **Review** in the header or **Review the claims** in the **⋯**
+menu. It follows the diagram's order: phase by phase, each step, then its
+outgoing connections, then the findings whose first cited step it is;
+findings that cite no step (only connections, or the workflow as a whole) come
+last, in document order. It starts on **Not observed**, the claims marked
+inferred or unresolved, with the same count as the header's **N not
+observed**; **Findings**, **All claims** and, while VS Code reports changed or
+missing cited files, **Changed files** are the other filters, each with its
+count. `j` / `k` or ↓ / ↑ (or the walk bar's up and down buttons) go to the
+next or previous claim, `[` / `]` to the
+claim's other quotes, Enter opens the current quote again (Alt+Enter moves the
+focus to the editor), `n` / `p` go to the next or previous finding, `u` /
+Shift+U to the next or previous claim not observed (`u` also starts the walk
+there), and Escape or `r` ends the walk. ← and → still move to the nearest
+card. Each step selects the claim, brings it into view and shows it in the
+Selection tab; about 150 ms after you stop, its cited lines open in the editor
+beside the diagram with the range highlighted, and the keyboard stays on the
+diagram (starting the walk from **Review** or the **⋯** menu puts the keyboard
+on the diagram too). A claim with no quotes opens nothing and clears the
+previous highlight. A quote whose file changed or went missing, or whose
+unsaved edits no longer contain the cited lines, is not opened: the walk bar
+and the quote in the Selection tab say why, and no notification appears.
+When the walk ends, or a step opens nothing, the lines the walk selected in
+the editor are no longer selected, unless you changed the selection. A
+screen reader hears, for example, "Claim 3 of 16, not observed: Step Load
+batches, inferred." The walk bar sits under the diagram, above the bottom
+panel's tabs (with the side panel, along the bottom of the diagram), and shows
+the place and filter, up and down buttons for the previous and next claim, the
+filters, the keys, **Exit** and what the editor beside shows (after Alt+Enter,
+that the focus moved to the editor); below 620 px wide it is "3/16", the two
+buttons, the filters and **Exit**. The walk remembers its place for each
+revision in the panel's view state, so `r` resumes there; a new revision
+starts fresh. It marks nothing as checked and writes nothing to any file. When
+cited files change, the notice offers **Review affected claims**, which walks
+the claims citing them from the first one. If a file is fixed while the walk
+is on a claim that cites only that file, the walk shows the next affected
+claim and says so; Enter opens it.
+
+The phase overview shows the whole workflow at once. Press Shift+0 on the
+diagram, or choose **Phase overview** in the **⋯** menu. Each phase is a block
+with its number, name, step count (and how many steps are inferred or
+unresolved) and the findings that touch it. Under that come its step titles in
+the Outline's order, a group before its steps, with ◌ for inferred, ? for
+unresolved and the F labels of the findings on each step. An arrow between
+two neighbouring blocks says how many connections go from one phase to the
+next. A connection that skips a phase or goes back is a bracket on the right
+with its count, dashed when it goes back; a key under the header says so at
+every width. The header gives the counts as a
+sum, for example "6 phases · 31 steps · 41 connections: 19 inside a phase, 8
+to the next phase, 14 skip ahead or go back." A block with more titles than
+fit ends with "… N more steps", so every step is either listed or counted.
+Beside your code, a document with many phases scrolls a little rather than
+dropping the titles. ↑ / ↓ (or ← / →), Home and End move between blocks.
+Enter or a click goes to that phase at reading size; the move takes about a
+quarter of a second, or happens at once with Reduce Motion or a screen reader.
+The next arrow key then starts at the phase's first step. Escape, Shift+0 or
+**Back** returns to the diagram exactly as it was, with the keyboard where it
+was; a legend opened over the overview closes first. Any other key the diagram
+uses closes the overview first. A screen
+reader reads each block as a button named by its phase, counts and
+connections, with its titles as the description.
+
+The phase index sits in the lower right corner of the diagram. It lists every
+phase with its number, name, findings by severity (a finding on two phases
+counts in each, as on the lane headings) and step count, and it marks the
+phases in view. The list is wide enough for names up to about 360 px; a
+longer name is cut short, with the whole name in its tooltip. Clicking a row
+goes to that phase. In a panel under 1000 px
+wide, or on a diagram under 350 px tall, it is one line naming the phase most
+in view, such as "4/6 Objective, optimizer & scheduler"; clicking it opens the
+list above it. When wide, its chevron folds it to that line. It stays inside
+the diagram, above the bottom panel, and never hides the card you are on:
+arrows, search, the Outline, a finding, the review walk and VS Code's reveal
+all pan the card out from under it. **Phase index** in the **⋯** menu shows or
+hides it, and the panel remembers the choice.
+
+Reveal in Diagram goes from the code back to the diagram. Right-click a line
+in the editor and choose **Reveal in Diagram**, or run **MLView: Reveal in
+Diagram** from the Command Palette. There is no default keybinding. The item
+is offered on a file an open diagram cites, as long as VS Code has not
+reported it changed or missing since the revision was published. It is there
+on the first right-click, even straight after pressing Enter on a card in the
+diagram. If your unsaved edits have moved the quoted lines, the command says
+so in one line instead of guessing. The cursor's line, or the selected lines, decide
+the claim. When one claim cites them it is shown at once; when several do, a
+list names each one's kind, title, F label, severity, phase and cited lines,
+steps first, then connections, then findings; on a line no claim cites, the
+list offers the nearest claims in the file. The diagram selects the claim,
+unfolds its group, brings it into view and shows it in the Selection tab
+(opening a hidden side panel or a collapsed bottom panel), and the keyboard
+moves to the diagram. It is the one time the viewer moves the focus by
+itself, because you asked for the diagram; nothing is opened in the editor. A
+diagram hidden behind the code comes to the front. With several diagrams
+open, the one that cites the file is used, or a list asks which. It works in
+notebook cell editors. Run where it does not apply (from a keybinding of your
+own, or after the file changed), it says why, for example that the file
+changed after the revision was published and the assistant should publish a
+fresh one. The claims come from the displayed revision's
+evidence records; MLView reads no code to find them.
+
 On the diagram, observed claims carry no basis mark. An inferred step or
 connection has a dashed border or line and an `inferred` tag; an unresolved
 one has a dotted border or line and a `? unresolved` tag. Line style shows
@@ -191,23 +292,27 @@ The diagram opens readable: the whole document if it fits at 62% zoom or
 more, otherwise the first phase at 90% (or all of the first phase, when it
 fits at 75% or more). Reopening the same revision keeps where you were. Press
 `0` to return to that first view from any zoom; **Fit the whole diagram** in
-the header's **⋯** menu shows everything, and Shift+0 (Overview) also folds
-every group. Zoomed out below 62%, cards show only their titles, at about
+the header's **⋯** menu shows everything. Shift+0 opens the phase overview;
+it no longer folds every group (each group keeps its own chevron). Zoomed out below 62%, cards show only their titles, at about
 11 px on screen down to about 35% zoom; the full title is in the hover card.
 
 The header is one row: the title, the assistant and revision, search, the
-severity toggles (each with its count), **N not observed**, a **⋯** menu and
-**Refine…**. In a panel under 620 px wide, such as beside your code, search
-and the revision move into the **⋯** menu; a row still too full folds **N not
-observed** into it as well, so **Refine…** stays in view. The menu also holds the legend, the
-flow animation, the overview map, the side or bottom panel, **Fit the whole diagram**,
-zoom to the selection, the SVG and PNG exports and the shortcut sheet. The
-overview map item is disabled, with the reason, when the map is not drawn: in
-a panel 900 px wide or narrower, a diagram under 350 px tall, or with fewer
-than 30 cards. Ctrl+F (Cmd+F on macOS), or `/` on the diagram, focuses
+severity toggles (each with its count), **N not observed**, **Review**, a
+**⋯** menu and **Refine…**. In a panel under 620 px wide, such as beside your
+code, search, the revision and **Review** move into the **⋯** menu; a row still too full folds **N not
+observed** into it as well, so **Refine…** stays in view. The menu also holds the
+phase overview, the legend, the flow animation, the phase index, the side or
+bottom panel, **Fit the whole diagram**, zoom to the selection, the SVG and PNG
+exports and the shortcut sheet, and always **Review the claims**. The phase
+index item is disabled, with the reason, for a diagram with fewer than two
+phases. Ctrl+F (Cmd+F on macOS), or `/` on the diagram, focuses
 search; the viewer's other keys are single keys, so VS Code's own Ctrl and Cmd
 shortcuts keep working, and the shortcut sheet prints them for your platform.
-Each search result shows its
+Escape closes one thing at a time in the viewer (a menu or panel, the phase
+index's list, the phase overview, the review walk, the bottom sheet, focus mode, the selection, then the focus on the
+diagram) without VS
+Code also acting on it; after that it goes to VS Code, for example to hide a
+notification. Each search result shows its
 title and, under it, where it is cited. The status bar counts steps and
 connections, shows the coverage status with its limitations, and says
 whether the cited files are unchanged (muted text) or changed or missing (a
@@ -379,6 +484,8 @@ Codex, and Claude Code inside VS Code:
 - Discover and invoke the installed skill in the native assistant.
 - Have the model read source and author a diagram without the static analyzer.
 - Open the artifact, inspect node and edge evidence, and navigate to exact lines.
+- Right-click a cited line and choose Reveal in Diagram; verify that the claim
+  citing it is shown and that an uncited file does not offer the command.
 - Exercise a notebook cell and repeated/custom phase names.
 - Request a refinement; verify a new revision and stable unaffected node IDs.
 - Copy a Refine prompt for each intent; verify that Explain answers without

docs/PERFORMANCE.md

@@ -158,3 +158,42 @@ limits timing precision. Its different Chromium version, host capabilities and
 much narrower viewport mean these values and DOM counts cannot be compared
 directly with the standalone Chrome table. The heap samples are live JavaScript
 heap snapshots, not total or peak process memory.
+
+## Notebook cell jumps in VS Code (viewer M3, 2026-10-02)
+
+A synthetic notebook (200 cells, 171 of them code with outputs, 3,826,440
+bytes) and a diagram citing 60 of its cells were opened in an isolated VS Code
+1.139.0 Extension Development Host on macOS. A script sent 60 cell jumps
+through the viewer's bridge over the DevTools protocol, either one every
+150 ms ("paced") or all at once ("burst"), and recorded a CPU profile of the
+extension host and of the workbench renderer (0.5 ms sampling). These are
+single runs on one machine: read them as an attribution of costs, not as a
+budget.
+
+| Run | Extension host busy | MLView's own code | Hashing the notebook | Garbage collection |
+|---|---:|---:|---:|---:|
+| Paced, before the jump cache | 466 ms of 12.1 s | 36 ms | 93 ms (60 reads) | 45 ms |
+| Paced, with the jump cache | 310 ms of 12.1 s | 45 ms | 1.3 ms (1 read) | 11 ms |
+| Burst, before the jump cache | 206 ms of 3.2 s | 11 ms | 101 ms | 22 ms |
+| Burst, with the jump cache | 70 ms of 3.2 s | 13 ms | none sampled | under 1 ms |
+
+"Busy" is the profile's time not spent idle. Before the cache every jump
+hashed the whole notebook again to prove it unchanged; now the first jump
+hashes it once and later jumps compare the file's size, inode and times. In a burst the host opens only the last jump, and a jump a later one
+has overtaken now stops before it reads the file.
+
+The workbench renderer was busy for about 2.2 to 2.3 s of each 12 s paced run
+(VS Code's own notebook and editor code); MLView runs no code there outside
+its webview. Creating and then deleting 2,000 files in the workspace, in one
+profiled run with counting breakpoints on MLView's listener, called MLView's
+file-watcher listener 1,157 times, about 1 ms of MLView code and 5 ms of path
+handling in total. Unlike the table above, these figures cannot be re-derived:
+that run's output and profile were not kept. The watcher (`**/*`) shares VS Code's own workspace
+watching and adds no operating-system watcher, and it has to see every cited
+or inspected file, whatever its name, so it was left as it is.
+
+With Pylance 2026.4.1 installed and a Python language server running, the same
+paced run spent 42 ms in MLView's code and 528 ms busy in the extension host;
+the renderer was busy for 2.6 s. The extra time is outside MLView's code (in
+Pylance, VS Code's messaging and the workbench); these runs cannot divide it
+further. No freeze was reproduced.