Story
As a keyboard user of the XMD REPL, I want every surface, historical checkpoint and contextual drawer represented by a deterministic route and focus order, so I can navigate the complete experience without background work moving me somewhere else.
The experiment begins at the empty REPL, submits fixture state, opens nested drawers, pauses at the live head, inspects earlier markers, returns to the paused head and resumes ordinary navigation. The same semantic routes work as composed panes in a wide terminal and as full-screen surfaces in a narrow terminal.
Current gap
The approved focus study specifies observable transitions, but the repository has no terminal router or route-owned application model. Rendering individual frames cannot establish that Back, Escape, Tab, history movement and responsive layout all preserve one coherent location.
A flat focus registry also cannot represent the terminal UI's real targeting paths. It requires traversal order, ownership and branch removal to be reconstructed manually beside the rendered hierarchy. When a subpanel appears or disappears, that parallel model can retain stale targets or route input through the wrong ancestors.
Contract
This is a bounded routing and focus experiment under #827.
- The current URL identifies the REPL execution, selected surface, entry or scope, journal checkpoint and nested drawer stack.
- REPL draft text is URL state. Editing it replaces the current URL state instead of adding navigation history, and route changes preserve it without writing it to the journal.
- Journal plus URL data is sufficient to hydrate equivalent semantic application state; this experiment may use journal fixtures rather than a real journal.
- Hydration rebuilds the StarFX application model. Rendering that model rebuilds an equivalent Freedom tree; the exact focused leaf is ephemeral UI state and is not persisted in the URL or journal.
- Wide and narrow layouts render the same routes through different compositions.
- The rendered Freedom tree is the authoritative focus topology and input-targeting hierarchy. A focus registry or focus-map overlay is only a read-only projection of that tree.
- Visible, enabled controls join the Freedom branch of their rendered parent. Tab and Shift+Tab traverse the active Freedom subtree in tree order.
- Keyboard input is dispatched through the currently focused Freedom node's scope so middleware on its live ancestor path participates.
- Rendering a new subpanel adds its Freedom branch. Closing it tears down that branch, removing its focusable descendants and scoped input behavior without manually reconciling a parallel list.
- Contextual drawers are nested routes and nested Freedom focus roots. Only the top drawer is visible and interactive; popping it restores its invoking node when that node survives and otherwise chooses a valid target in the enclosing active root.
- Stable semantic identities may annotate Freedom nodes for routing, diagnostics and restoration, but they do not define ancestry, traversal order or input targeting.
- Background session updates never change the route, selection, scroll owner or focused node.
- Escape navigates non-destructively.
Ctrl+C interrupts an active entry, clears an idle non-empty draft, or exits an idle empty REPL.
- Scrubber Left and Right move chronologically among semantic markers; structural navigation reaches parent, child and sibling visible scopes.
The experiment owns navigation behavior and the terminal focus topology, not production rendering, execution or persistence.
Architecture reference
Use Bombshell playground's Freedom focus-stack implementation at the pinned commit, not the manual focusIndex example on the playground's main branch:
@bomb.sh/freedom is private and unpublished at this reference. The experiment may pin or incorporate the referenced source; publishing or stabilizing that package is not part of this Story.
Acceptance
- Headless tests cover every state in the approved focus study in both forward and reverse traversal through Freedom's focus operations.
- The same URL and journal fixture hydrate equivalent semantic application state and render an equivalent Freedom topology after both the in-memory store and UI tree are discarded.
- Opening a subpanel inserts its focusable controls at their tree-defined positions. Closing it destroys the complete branch; none of its removed controls or middleware can receive later input.
- Input sent to a nested focused control passes through the middleware of its live panel and drawer ancestors.
- Opening and closing nested drawers confines traversal to the top focus root, restores first to the enclosing drawer and finally to the original invoking control, with a valid enclosing-root fallback when an invoking node disappeared.
- Historical inspection disables mutations, keeps future markers visible but dimmed, and requires returning to the paused head before Continue is available.
- Switching between wide and narrow compositions preserves route, selected marker, selected scope and draft while rebuilding the corresponding Freedom topology.
- Hidden and disabled controls cannot receive focus; a negative fixture fails if either enters Freedom's focus chain.
- Background updates and removal of the focused component exercise the accepted no-focus-steal and surviving-target behavior.
- The focus-map overlay is derived by walking the live Freedom tree; a negative control fails if a parallel flat registry diverges from it.
- The conclusion records the URL schema, route hierarchy, Freedom tree mapping, focus-root behavior, unresolved renderer constraints, and retain, revise or discard decision.
Evidence
Attach the exact commit, one documented command, the headless transition suite, and terminal captures for representative wide and narrow paths. Include the URL before and after draft editing, drawer navigation and historical inspection to demonstrate push-versus-replace behavior.
The evidence must also show a nested input event taking the focused Freedom node's ancestor path, a mounted subpanel joining traversal, and the same branch becoming unreachable immediately after teardown.
Dependencies
Out of scope
- Real journal storage or replay.
- Effection subtree observation and pause.
- Production component APIs.
- Publishing or stabilizing
@bomb.sh/freedom.
- Persistence of focused leaf, hover, animation, exact scroll offsets, cursor position or other disposable UI state.
Story
As a keyboard user of the XMD REPL, I want every surface, historical checkpoint and contextual drawer represented by a deterministic route and focus order, so I can navigate the complete experience without background work moving me somewhere else.
The experiment begins at the empty REPL, submits fixture state, opens nested drawers, pauses at the live head, inspects earlier markers, returns to the paused head and resumes ordinary navigation. The same semantic routes work as composed panes in a wide terminal and as full-screen surfaces in a narrow terminal.
Current gap
The approved focus study specifies observable transitions, but the repository has no terminal router or route-owned application model. Rendering individual frames cannot establish that Back, Escape, Tab, history movement and responsive layout all preserve one coherent location.
A flat focus registry also cannot represent the terminal UI's real targeting paths. It requires traversal order, ownership and branch removal to be reconstructed manually beside the rendered hierarchy. When a subpanel appears or disappears, that parallel model can retain stale targets or route input through the wrong ancestors.
Contract
This is a bounded routing and focus experiment under #827.
Ctrl+Cinterrupts an active entry, clears an idle non-empty draft, or exits an idle empty REPL.The experiment owns navigation behavior and the terminal focus topology, not production rendering, execution or persistence.
Architecture reference
Use Bombshell playground's Freedom focus-stack implementation at the pinned commit, not the manual
focusIndexexample on the playground's main branch:@bomb.sh/freedomis private and unpublished at this reference. The experiment may pin or incorporate the referenced source; publishing or stabilizing that package is not part of this Story.Acceptance
Evidence
Attach the exact commit, one documented command, the headless transition suite, and terminal captures for representative wide and narrow paths. Include the URL before and after draft editing, drawer navigation and historical inspection to demonstrate push-versus-replace behavior.
The evidence must also show a nested input event taking the focused Freedom node's ancestor path, a mounted subpanel joining traversal, and the same branch becoming unreachable immediately after teardown.
Dependencies
Out of scope
@bomb.sh/freedom.