Simplifying and documenting the browser navigation architecture.
Status: open; part 1 is built (2026-11-19, see One navigation entry point). Order: (1) one navigation entry point, (2) a compaction coordinator with a written protocol, (3) composable breadcrumbs, (4) the auxiliary view, which needs 2 and 3. Tile Container Views waited on 2; its first grid no longer does (2026-11-20), and the navigation announcements in Accessibility Testing & Tuning wait on 1. The compaction notes from Cleanup Notes are merged in below.
The browser is built from four cooperating classes that implement a recursive Miller column navigation pattern:
The top-level container. Extends SvStackView and adds application-level concerns: listening for onRequestNavigateToNode notifications, handling keyboard shortcuts, and managing the root node hierarchy (app root, settings, breadcrumbs). On startup it schedules moveToBase() to set the initial navigation state.
The core navigation primitive. Each stack view is a pair: a nav view on the left (or top) showing the selected node's subnodes as selectable tiles, and an other view on the right (or bottom) that contains the next SvStackView for deeper navigation. This recursive nesting is what produces the Miller column layout.
Key responsibilities:
selectNodePathArray(pathArray) walks an array of nodes, selecting one at each level and recursing into the next stack view.selectedNodePathArray() and selectedPathTitlesString() return the current selection path by walking up or down the stack chain.direction slot ("right" or "down") controls whether subnodes lay out as side-by-side columns or stacked rows. Nodes set this via setNodeIsVertical() -- the stack view reads it and adjusts its flex direction accordingly. The recursive combination of different directions at each level is what distinguishes STRVCT's navigation from a standard Miller column browser.updateCompactionChain() automatically collapses columns that don't fit the available width, showing them as expandable when space is available again.didChangeNavSelection() propagates up to the root, which posts onStackViewPathChangeNote for breadcrumbs and other observers.An individual navigation column within a stack view. Contains a header, a scrollable tile container (SvTilesView), and a footer. When assigned a node via setNode(), it populates the tiles view with that node's subnodes.
Additional features:
nodeMinTileWidth / nodeMinTileHeight), so it persists across navigation.Displays the current navigation path as a row of clickable buttons. Coordinates with the stack view entirely through notifications:
onStackViewPathChangeNote from the root stack view.targetStackView().selectedNodePathArray() to get the current path..info().targetStackView().selectNodePathArray() with the stored path to navigate back.The breadcrumbs also compact: when the path is too long to fit, earlier crumbs are hidden and a back arrow appears that navigates to the most recent hidden crumb.
When the user clicks a tile:
SvTilesView selects the tile and notifies its SvNavView.SvStackView calls didChangeNavSelection().onStackViewPathChangeNote.SvBreadCrumbsTile receives the notification and rebuilds its path buttons.SvStackView in the chain receives the selected node and populates its nav view.When the user clicks a breadcrumb:
browser.navigate(SvNavigationRequest.toPath(path).setCause("user")).onStackViewPathChangeNote, and breadcrumbs update.The browser navigation works well but has accumulated complexity over time. Areas to consider:
SvStackView handles direction, compaction, path selection, and notification broadcasting. Some of these could be factored into smaller, more focused collaborators -- for example, a compaction manager or a path selection coordinator.
The column compaction system (updateCompactionChain() on SvStackView, collapse() / uncollapse() on SvNavView) spans both classes with mutual callbacks. It works, but the protocol between them is implicit.
A recommendation for this part is written up in Compaction Coordinator (the plan as of 2026-11-20, not yet built): small fixes first, then a measurement, then claims stated by the views and one function, SvLayerAllocation, that allocates.
SvStackView and SvNavView.SvStackView.cachedRootWidth() does), then write; never measure after writing in the same pass. Verify with ?thrash=count before and after.Built 2026-11-19. selectNodePathArray(), navigateToNode(), selectNodePathString(), selectPathWithRetry() and moveToBase() all navigated, through different code, and none said who asked. Now there is one way in:
browser.navigate(SvNavigationRequest.toPath([a, b]).setCause("user"));An SvNavigationRequest says where and who.
| Where | Made with |
|---|---|
| A path of nodes (a leading browser root is skipped) | toPath(nodes) |
| A node, by its parent chain | toNode(aNode) |
| A slash-separated title path, as a URL holds it | toPathString("A/B") |
| The browser's base state | toBaseState() |
| Cause | Meaning |
|---|---|
"user" | The user's own act: a tile, a breadcrumb, a link in the content, a tab tapped again. |
"url" | The address changed, or the page was opened at one. |
"program" | Code moved the user without their asking for that place (the default). |
"base" | A browser nobody has navigated settling into its base state. |
What it does and what it replaced:
browser.lastNavigationRequest() is the request behind the latest path change. A listener to onBrowserViewPathChange asks it for the cause; this is what the navigation announcements in Accessibility Testing & Tuning need.onRequestNavigateToNode or onRequestSelectNodePath. The browser turns each into a request with the cause "program".continuingRequestToPath(), so the pane's request carries the cause of the whole navigation.navigateToNode, selectNodePathString, selectPathWithRetry and the unused setSelectedPathTitlesArray / setSelectedPathTitlesString. The stack's selectNodePathArray() stays as the walk itself, called only by the browser.TestNavigationEntryPoint fails when anything but the browser calls the stack's walk, or when a retired method returns. tests/e2e/navigation-entry-point.spec.js (in the app repo) checks each route and its cause in a browser.Three decisions (Steve, 2026-11-19):
postShouldFocusAndExpandSubnode and postShouldFocusSubnode ("show this child of where I am", about 16 call sites, most of them in the app) still select in the columns directly, so the path change they cause is recorded as the user's. Until the second pass, an announcement keyed on the cause will miss them.navigate() as a request that names a child of the current place, with the cause "program", or "user" when the user's own add caused it.nodeBecameOrphan), and a selected tile rebinding to a new instance.The compaction system provides basic responsive behavior, but a dedicated mobile navigation mode (e.g., single-column with swipe gestures) could replace the current approach of compacting columns until they fit.
Breadcrumbs are not built into the browser view — they're a regular node (SvBreadCrumbsTile) added to the node tree. But the tile currently finds its target by walking up to the root SvStackView, so only one set of breadcrumbs can exist per browser. This breaks down when a split view or inspector pane contains its own nested stack view that the user navigates independently. That inner pane needs its own breadcrumbs tracking its own path, not the root's.
A concrete example: during a game narration conversation, a side panel could let the player inspect their character sheet — drilling into inventory, spells, ability scores — without navigating away from the conversation. That panel would be its own stack view with its own breadcrumbs, independent of the main browser path.
The fix is to make breadcrumbs composable: instead of always targeting the root stack view, the breadcrumbs node should target the nearest ancestor stack view (or a specifically assigned one). This would let any stack view — whether it's the top-level browser, one side of a split view, or a deep inspector panel — have its own independent navigation context with its own breadcrumb trail.
A node could declare an auxiliary node that the view system renders as a side panel with its own independent navigation context. The auxiliary panel would be a full stack view — the user can drill into nested content within it — but scoped and constrained by hints from the primary node.
this.setNodeAuxiliaryNode(this.characterSheet());
this.setNodeAuxiliaryPosition("right"); // or "bottom"
this.setNodeAuxiliaryDefaultState("expanded"); // or "collapsed"
this.setNodeAuxiliaryCompactsFirst(true); // collapse auxiliary before main columns
this.setNodeAuxiliaryMaxColumns(2); // cap drill-in depth within the panelThis stays declarative — the node says what it wants, the view system handles layout. The auxiliary side is a fully independent navigation context with its own breadcrumbs (once breadcrumbs are composable), its own selection, and its own internal compaction. No changes to the main selection model.
The maxColumns hint is important for space management. A conversation node knows it only needs a narrow inspector — one or two columns to peek at the character sheet. Once the user drills past the limit, deeper navigation replaces the last column rather than adding a new one.
The current compaction algorithm walks the stack chain and collapses columns that don't fit the available width. Auxiliary views add a new dimension to this because column compaction (horizontal, across navigation levels) and auxiliary compaction (within a single level's content area) are orthogonal.
The compaction sequence would become:
Expanding works in reverse: as width becomes available, the main columns uncollapse first, then the auxiliary panel reappears, then the auxiliary's internal columns expand.
Node hints control priority: auxiliaryCompactsFirst (default true) means the auxiliary gives up space before any main columns. A node could set this to false if the auxiliary content is more important than the surrounding navigation context — though that would be unusual.
This approach requires no fundamental changes to the compaction algorithm itself. The auxiliary panel's internal compaction is just a smaller instance of the same algorithm running on a scoped stack view. The new work is the coordination layer that decides the order of compaction across the two contexts.