Skip to content

fix(viewer): make the explorer, shell, popover and export states explicit - #79

Merged
hyamero merged 4 commits into
stagingfrom
refactor/viewer-state-machines
Nov 19, 2026
Merged

hyamero merged 4 commits into
stagingfrom
refactor/viewer-state-machines

Conversation

@hyamero

@hyamero hyamero commented Nov 19, 2026

Copy link
Copy Markdown
Member

Summary

Four pieces of viewer state were implicit state machines: separate flags whose valid combinations were kept only by scattered guards. Each one is now explicit. Two of them were hiding bugs.

Explorer mode: trace and route picking excluded each other only through reducer guards, and 8 call sites (viewer and site) repeated !!state.route || !!state.routing.

 interface ExploreState {
-  trace: boolean;
-  route: { from; to } | null;
-  routing: { next: 'from' } | { next: 'to'; start } | null;
+  mode:
+    | { kind: 'neighbours' }                 // default
+    | { kind: 'trace' }
+    | { kind: 'pickStart' }                  // R
+    | { kind: 'pickEnd'; from }
+    | { kind: 'route'; from; to };           // the only one in the hash
 }
+isRouting(mode)   // pickStart | pickEnd | route
+routeOf(mode)     // the route mode itself (stable identity for deps), else null

The hash format is unchanged.

Shell: focus (Z), presentation (F) and the hidden toolbar (H) were four useStates plus a ref mirror. The rules now live in a pure reducer:

shell(state, action)               chrome/shell.ts
  present on|off                   sits over focus or not, hands back what it found
  focus on|off                     ignored while presenting; leaving it shows the toolbar
  toolbar hidden|shown             ignored while presenting
ViewerShell                        keeps only the full screen side effects (the quick F, F fix unchanged)

Toolbar popovers (fix): search and the type filter were kept apart only by click handlers. The website's "Find" try button opens search through the explorer, so opening the filter from the keyboard and then pressing Find stacked both popovers. Now lensShown = lensOpen && !searchOpen: search wins, in one place.

Export status (fix): idle → busy → done | error never returned to idle, so a failed export's note stayed indefinitely and the reopened menu was drawn on top of it. Opening the menu now resets the status.

Evidence

  • Before: with each fix undone, its new test fails:
    × shows one popover at a time, even when search is opened from outside the toolbar
    × clears a failed export once the menu opens again, so the menu never opens over the error
    × ends a route at any stage of picking, and trace waits through it
    
    After: all pass. Viewer unit tests: 169 → 181.
  • Unit tests: all packages pass; the site's 116 pass.
  • Typecheck and build: both pass.
  • End-to-end: viewer 101 passed (14 skipped, the Linux-only visual tests), CLI 9 passed, site 85 passed (covers useTry on the new mode).

Merge Danger

Door: two-way

The state shape is internal to @stackmap/viewer, and the only consumer outside it is the site's useTry, updated here. Nothing persisted or published changes shape: the URL hash and the CLI are untouched.

Blast Radius: viewer-interactions

If something regressed, it would show in trace and route picking, presentation, focus and hidden-toolbar keys, or the export menu. Rendering and layout aren't touched, and no visual baselines changed.

@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
stackmap-site Ready Ready Preview Nov 19, 2026 5:49am UTC

@hyamero
hyamero merged commit 1acdb24 into staging Nov 19, 2026
8 checks passed
@hyamero
hyamero deleted the refactor/viewer-state-machines branch November 19, 2026 06:55
@github-actions

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 0.7.0-rc.3 🎉

The release is available on:

Your semantic-release bot 📦🚀

@github-actions

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 0.7.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

This branch was successfully deployed

1 active deployment
Preview — 7ae90b31 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant