FE-1509: Document the Notebook view and register it with the AI assistant

.changeset/notebook-view.md

@@ -0,0 +1,6 @@
+---
+"@hashintel/petrinaut": patch
+"@hashintel/petrinaut-core": patch
+---
+
+Add an experimental Notebook view (enabled via the viewport settings dialog): the net as a list of expandable cells editable in place, with keyboard navigation, fuzzy search, kind filters, document/topological ordering, dependency gutter lines, and a whole-net graph explorer with cycle detection, initial-place (siphon) analysis, and animated focus re-layout.

libs/@hashintel/petrinaut-core/src/ai.ts

@@ -95,6 +95,7 @@ export const petrinautDocNames = [
   "experiments",
   "optimization",
   "actual-mode",
+  "notebook-view",
   "ai-assistant",
   "visual-settings",
   "compilation-output",
@@ -122,6 +123,8 @@ export const petrinautDocSummaries: Record<PetrinautDocName, string> = {
     "Optuna search over a selected scenario's flat parameters: explicit scenario selection, fixed vs optimized parameters and typed domains, one saved or run-local custom-code metric with maximize/minimize direction (not Experiment metric shortcuts), streamed trials, cancellation, and results.",
   "actual-mode":
     "Actual mode: host-provided live execution view, Brunch stream URL route, read-only extension-free net, current limits.",
+  "notebook-view":
+    "Experimental notebook view (cells editable in place; adding/removing nodes stays in Edit mode): cells per place/transition/type/equation/parameter, expand/keyboard/search, document vs topological order, dependency gutters, whole-net graph explorer with cycles, initial (siphon) places, focus re-layout.",
   "ai-assistant":
     "In-app AI assistant: opening the panel, one text and Voice mode transcript/composer, waveform start, inline Voice state and provenance, typed handoff, consent/recovery, prompt chips, tool cards, read-only/simulate-mode rules, host configuration.",
   "visual-settings":

libs/@hashintel/petrinaut/docs/README.md

@@ -21,9 +21,10 @@ A quick map of the things you'll encounter:
 - **Optimization** -- a search over a flat set of scenario parameters,
   targeting one saved or run-local custom metric.
 
-Petrinaut has three global modes in the top bar, though **Actual** is only enabled when the host application provides a live execution source:
+Petrinaut has four global modes in the top bar, though **Notebook** is experimental and **Actual** is only enabled when the host application provides a live execution source:
 
 - **Edit** -- the drawing/configuration workspace plus single-run simulation playback.
+- **Notebook** -- the net as a list of cells editable in place, behind the Notebook view setting.
 - **Simulate** -- a separate management surface for scenarios and experiments,
   with optimizations when the host application provides an optimizer.
 - **Actual** -- a read-only live-execution view supplied by a host such as Brunch.
@@ -39,6 +40,7 @@ Petrinaut has three global modes in the top bar, though **Actual** is only enabl
 - [Experiments](experiments.md) -- Run Monte Carlo batches and inspect token-count distributions over time.
 - [Optimization](optimization.md) -- Search scenario parameter ranges to maximize or minimize a metric.
 - [Actual Mode](actual-mode.md) -- View a host-provided live Petri net execution, currently via Brunch.
+- [Notebook View](notebook-view.md) -- Read the net as a list of cells with dependency analysis (experimental).
 - [AI Assistant](ai-assistant.md) -- Build, review, and revise nets with text or inline Voice mode.
 - [Visual Settings](visual-settings.md) -- Configure the editor appearance and behavior.
 - [Compilation Output](compilation-output.md) -- Inspect how your net's code compiled, and what stops it running on the GPU.

libs/@hashintel/petrinaut/docs/notebook-view.md

@@ -0,0 +1,45 @@
+# Notebook View
+
+> **Experimental.** Enable **Notebook view** in the viewport settings dialog (the gear button in the canvas controls) to add a **Notebook** option to the mode selector in the top bar, right after **Edit**.
+
+The Notebook view shows your net as a list of one-line cells — one per place, transition, token type, differential equation, and parameter — so you can read a model like code instead of untangling a diagram. Everything an open cell shows is editable in place, exactly as in the properties panel: names, a parameter's variable name and default, a place's type and dynamics, a type's colour and fields, arc weights and kinds — and code, which saves as you type. Only adding and removing nodes, arcs, and fields needs **Edit** mode.
+
+## Cells
+
+Each row reads like a declaration: the kind keyword (`Place`, `Transition`, `Type`, `Equation`, `Parameter`), the name, and a one-line summary — a transition shows its flow (`WIPQueue, ChambersAvailable → InProcess`), a place shows its type and dynamics, a parameter shows its value.
+
+- Click the caret (or press **→** / **←**) to open or close a cell. Open cells show the full definition: a transition's inputs and outputs with weights and arc kinds, its firing-time and kernel code, an equation's code, a type's fields. Cells stay as you leave them; selecting a cell does not open it.
+- Click a row to select it. **↑** / **↓** move the selection, **Enter** or **Space** select the focused row. The list is one Tab stop: **Tab** enters it at the last row you were on.
+- While a cell is open, its parts join the keyboard flow: **↓** / **↑** walk from the row through its fields, inputs, outputs, and code. On a line with several values — an arc's place, weight, and kind, or a type field's name and type — **→** / **←** move between them one value at a time, and **↓** / **↑** keep your column when the next line has one. **Enter** acts on the selected value: buttons and checkboxes activate immediately (an arc's place name jumps to that place's cell), text fields and dropdowns step in for editing. **Escape** discards the draft and steps back out, and **Enter** in a text field saves.
+- Code blocks work like spreadsheet cells with an editor inside: **Enter** steps into the editor to edit the code (arrow keys then move the caret, not the list) and **Escape** steps back out. Edits save as you type; a running simulation or a read-only host locks the editors.
+- The end of each row shows how many things depend on it, as `direct → total`. `2 → 11` means two cells use it directly and eleven are affected in total downstream.
+
+Two badges can appear after a cell's name:
+
+- **`initial`** (blue) — this place must hold tokens in the initial state. Nothing in the net can produce its first token: either nothing feeds it at all, or it belongs to a pool that only circulates what it starts with (a resource pool such as a set of machines). If a scenario leaves every place of such a group empty, the transitions that need it can never fire.
+- **`↻N`** (tinted) — this node is part of cycle _N_. Hover the badge to light up the whole cycle in the list and the graph.
+
+## Toolbar
+
+- **Search** — type in the search box (or press **/**) to fuzzy-match cell names; matching characters are highlighted and other cells fade. **↑** / **↓** step through matches, **Enter** jumps to the first one, **Escape** clears.
+- **Document / Topological** — list cells in the order the net stores them, or in flow order where every type, equation, and parameter appears just before the first cell that uses it, and places that must be seeded come first.
+- **Kind filters** — toggle Places, Transitions, Types, Equations, and Parameters in and out of the list and the search.
+
+## Dependency lines
+
+Selecting a cell draws angled connector lines in the margins: the left gutter connects it to what it depends on, the right gutter to what depends on it.
+
+## Graph explorer
+
+The right-hand panel draws the whole net as a top-to-bottom flow graph of places (pills, with their token type's colour dot) and transitions (boxes) — laid out from the arc structure, ignoring canvas positions. Places that must hold initial tokens carry a hollow token marker, and cycle members carry a dashed ring.
+
+- Selecting a place or transition highlights it in the graph: dependencies in blue, dependents in orange, a node connected in both directions in purple. Clicking a node in the graph selects its cell.
+- The **target button** re-organizes the graph around the selected node: what it depends on stacks above it, what depends on it below, everything else settles underneath. The re-layout is animated. Toggle it off to return to the default flow layout.
+- Below the graph, the selected cell's dependencies and dependents are listed in full — including types, equations, and parameters, which the diagram itself leaves out.
+- Drag the panel's left edge to resize it, and the divider above the lists to trade space between the graph and the lists.
+
+## Limits
+
+- Cells edit what exists; adding or removing places, transitions, arcs, and type fields happens in Edit mode.
+- Subnets and component instances are not shown as cells yet.
+- A parameter counts as "used" by a transition or equation when its variable name appears in the code — comments included.

libs/@hashintel/petrinaut/docs/visual-settings.md

@@ -40,6 +40,10 @@ Controls selection box behavior in [Select mode](drawing-a-net.md#pan-and-select
 - **Enabled** -- nodes that are only partially inside the selection box are selected.
 - **Disabled** -- nodes must be fully enclosed to be selected.
 
+### Notebook view (experimental)
+
+Adds a **Notebook** option to the mode selector in the top bar, next to **Edit**: the net as a list of cells editable in place, for reviewing and debugging models. See [Notebook View](notebook-view.md).
+
 ### Entities tree view (experimental)
 
 Replaces the tabbed left sidebar with a unified **tree view** showing all entities (nodes, types, equations, parameters) in a single hierarchy.

libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/petrinaut-docs-content.ts

@@ -10,6 +10,7 @@ import compilationOutput from "../../../../../../docs/compilation-output.md?raw"
 import drawingANet from "../../../../../../docs/drawing-a-net.md?raw";
 import examples from "../../../../../../docs/examples.md?raw";
 import experiments from "../../../../../../docs/experiments.md?raw";
+import notebookView from "../../../../../../docs/notebook-view.md?raw";
 import optimization from "../../../../../../docs/optimization.md?raw";
 import petriNetExtensions from "../../../../../../docs/petri-net-extensions.md?raw";
 import scenarios from "../../../../../../docs/scenarios.md?raw";
@@ -39,6 +40,7 @@ const rawDocsByName: Record<PetrinautDocName, string> = {
   experiments,
   optimization,
   "actual-mode": actualMode,
+  "notebook-view": notebookView,
   "ai-assistant": aiAssistant,
   "visual-settings": visualSettings,
   "compilation-output": compilationOutput,