Go Back / Go Forward over the Explorer's navigation landings

[ericwinger]

Addresses #498.

This is up for review as an approach, not just an implementation. It deliberately
departs from what the issue proposed, and the departure is the thing worth arguing
about — see "The call I'd like reviewed" below.

What it does

Go Back and Go Forward walk the places the GemStone Explorer has taken you —
dictionary, class category, class, and method — one press per landing, with the forward
trail dropped when you go somewhere new. Browser semantics, which are also VS Code's.

A landing is a coordinate (session, dictionary, class, side, selector), not a handle.
It is recomputed against the stone on the way back, so a method that has since been
recompiled still resolves; the dictionary is re-resolved by name, because a commit
elsewhere can shift every symbol-list index. A landing that no longer resolves is reported
and dropped from the trail rather than erroring, so a second press moves on instead of
sticking. The last 50 are kept.

The trail is listed in a new Actions & Navigation pane at the top of the Explorer,
newest first, with the landing you are on marked; click any row to jump to it. The same
list is available from the keyboard as GemStone: Recent Locations….

The call I'd like reviewed

The issue's preferred approach was to push Jasper's landings onto VS Code's own
navigation history, so the native Go Back/Forward in the title bar would just work, and
to treat a Jasper-private stack as the fallback. This does the opposite: it builds a
private chain.

The reason is that VS Code's history is a history of editor documents. Most Explorer
landings are pane moves that open no document at all — selecting a dictionary, a class
category, or a class — and the ones that do open a document open it in a single reusable
preview tab, which VS Code's history does not track as distinct locations. Registering
landings with the native history would have meant opening a real editor for every pane
move, which is a bigger behavioural change than the feature is worth.

The cost of the private chain is a second set of Back/Forward controls next to the
native ones, which is a genuine wart. If the reviewer prefers the native route, the
recording points are all funnelled through one recordLanding call, so the destination
is swappable without touching the call sites.

Two smaller calls, both mine, both worth challenging:

• The buttons are in a new pane, not the System Browser title bar the issue asked for.
  Refresh/Commit/Abort moved onto the same row, since they act on the Explorer and its
  session rather than the dictionary list they used to sit above. A pane's title-bar
  actions are drawn only while the pane is expanded and hovered or focused, so they
  vanish exactly when the pane is small enough to be worth keeping; these do not.
• A drill-down is one landing, not three. Clicking a dictionary, then a class, then a
  method records a single entry, because the coarser two are the cascade passing through
  rather than places the user asked to be. Without this, leaving a method costs three
  presses of Back.

What is not recorded yet

The issue lists landings this does not cover, and it should not be read as complete:

• Debugger frame selection, and the jump the debugger makes when a session stops
• Go to Definition from a peek pane (a plain Go to Definition is covered)
• Test-failure navigation from the SUnit runner

Everything that opens a gemstone:// editor is covered, because that activation drives
the Explorer's own sync — so Implementors of, Senders of, GemStone Search, Find Method in
Class, the method-results picker, plain Go to Definition, and post-refactoring
repositioning all record landings without needing their own call sites. The three above
do not go through that path. Happy to add them here or in a follow-up, whichever the
reviewer prefers.

The issue's "with several System Browsers open, Back should act on the one that produced
the landing" is moot: the System Browser is frozen, so several open browsers is not a case
to design for. One global chain, owned by the Explorer.

Testing

Client-only diff, so the fast gate rather than the version matrix.

• lint, format:check, compile clean; client 448 files / 7197 tests, server 322,
  mcp-server 92 — all passing.
• The chain's rules are unit-tested against hand-built landings; a separate suite drives
  the real pane cascade and asserts the landings it actually produces, plus the way
  back (dictionary re-resolution, an unselected session declined rather than reconnected,
  a vanished dictionary, a removed method), the Recent Locations picker, and that the
  three commands have real handlers rather than only manifest entries.
• Those tests were mutation-checked rather than trusted for being green: ten mutations
  (removing each folding rule, the restore guard, the stale-entry prune, the dictionary
  re-resolution, the session guard, the method-gone report, the trail ordering, and the
  command registrations) were each verified to fail the suite.
• Manually F5-verified throughout by Eric; the design was driven by his live findings.

🤖 Generated with Claude Code