FE-1557: Prototype notebook navigation and graph explorations

[kube]

Important

Experimental
Behind the Notebook view feature flag.

Summary

Before this PR, notebook navigation is arrow keys plus the search box. Following a reference teleports with no way back, reading what a reference points at means going there, and the whole-net diagram is a fixed-zoom pane that only scrolls.

Prototypes five navigation and graph ideas, one commit each so they can be judged and dropped independently. Each borrows a pattern proven elsewhere: Jupyter and Linear palettes, IDE jump lists and peek definition, Vimium hint labels, and overview-plus-detail graph cameras. Rationale, follow-up ideas and sources are recorded in a new arch-docs exploration page.

9452.mp4

Links

• Ticket FE-1557
• Docs Notebook navigation explorations
• Reference Vimium link hints
• Reference VS Code code navigation
• Reference Overview+detail and focus+context review

Changes

Navigation

• Command palette on ⌘K

  Fuzzy-matches every cell name plus view commands: cell order, kind filters, expand and collapse all, graph focus, search. Enter jumps or runs; jumping reveals a hidden kind.
  While the notebook is the active mode its palette takes ⌘K precedence over a host palette.

• Jump history with back and forward

  Reference jumps are remembered: arc place, explorer row, palette result. Toolbar arrows and ⌥←/⌥→ retrace them; a fresh jump forks the trail. Plain arrow moves are not recorded.

• Hint-jump on f

  Every visible row grows a home-row letter chip; typing a label jumps there. Labels are uniform length, so none is a prefix of another and no confirmation key is needed.

Reading and the graph

• Peek cards on references

  Hovering or focusing an arc place, explorer row or graph node previews the target cell without navigating: kind, summary, dependent counts. One data-peek-cell attribute makes any surface peekable.

• Graph camera with a minimap

  Wheel zooms toward the cursor, background drag pans, double-click refits, labels hide below half zoom. An aspect-correct minimap shows the camera window; press or drag it to re-centre.

• Viewport settings description drops the stale read-only wording

Next steps

• Fold the notebook palette into the FE-1560 command registry so one surface serves both
• Palette recents, hint labels on body parts, hover-neighbourhood dimming in the graph

  Listed with the rationale in the exploration page.

Test coverage

• use-jump-history.test.ts:

  Back and forward walking, trail forking, self-jump and empty-origin handling.

• hint-jump.test.ts:

  Label generation, prefix freedom, pending and dead-end matching.

• net-graph-viewport.test.ts:

  Fit, cursor-anchored zoom, scale clamps, minimap window round-trips.

• Browser verification:

  All five flows driven with synthetic keyboard and pointer input.

How to test

• Open Petrinaut preview on Vercel
• Viewport controls > Settings > Notebook view
• Menu > Examples > Supply Chain with Disruption
• Top bar > Notebook
• ⌘K, type a cell name, Enter
• ⌥← to come back, ⌥→ forward
• Press f, type a chip's letters
• Hover an arc's place name in an expanded transition
• Expect a peek card
• Graph: scroll to zoom, drag background, double-click to refit, drag minimap

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 3, 2026 11:48pm UTC
petrinaut	Ready	Preview	Sep 3, 2026 11:48pm UTC
petrinaut-docs	Ready	Preview	Sep 3, 2026 11:48pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 3, 2026 11:48pm UTC