> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase21-session04-shortcut-and-overlay-layering/spec.md). # Session Specification **Session ID**: `phase21-session04-shortcut-and-overlay-layering` **Phase**: 21 - Bottom Rail Focused Surface Expansion **Status**: Not Started **Created**: 2026-06-29 **Package**: apps/web **Package Stack**: TypeScript *** ## 1. Session Overview This session aligns keyboard access and nested overlay recovery with the focused bottom-rail surface contract. Sessions 01 and 02 created the transient expansion state and shared host, and Session 03 made the Orchestration header open the real Command Center focused surface. The remaining mismatch is that the `o d` shortcut and shortcut help still describe the secondary state summary instead of the primary Command Center path. The user-facing outcome is that keyboard users can open the same focused Command Center surface that pointer users open, then recover predictably from nested layers. If a state summary, command-center drawer, or terminal runtime drawer is open above expanded Orchestration, Escape should close that higher layer first and leave the focused surface open for the next action. The implementation should use a small shared overlay-layer convention rather than scattering one-off checks. The convention must be visible in tests, keep backdrop and inner-panel click behavior deterministic, and preserve the existing product-facing no-overclaim and privacy boundaries for Command Center surfaces. *** ## 2. Objectives 1. Repoint `o d` to open the focused Command Center surface. 2. Replace details-primary shortcut labels with Command Center working-surface labels. 3. Add a shared overlay-layer convention for focused surfaces, retained summaries, and Orchestration drawers. 4. Prove Escape, backdrop, and inner-panel behavior with focused component tests. *** ## 3. Prerequisites ### Required Sessions * [x] `phase21-session01-expansion-state-foundation` - Provides transient bottom-rail expansion state. * [x] `phase21-session02-shared-expansion-host` - Provides `BottomRailExpansionHost` with same-instance promotion. * [x] `phase21-session03-orchestration-command-center-expansion` - Provides the primary Orchestration header action that opens the focused Command Center surface. ### Required Tools Or Knowledge * Node 26.2.0+ and npm 11.16.0 workspace commands. * React effect ordering, portal behavior, and Testing Library keyboard tests. * Zustand access through `useSettingsStore` and `useGameStore`. * Existing Command Center shortcut metadata in `apps/web/src/lib/commandCenterShortcuts.ts`. ### Environment Requirements * Local repository checkout with npm dependencies installed. * Happy DOM test environment used by `apps/web/tests`. * No hosted account, Cloudflare credential, Worker credential, provider key, local server credential, or backend execution change is required. *** ## 4. Scope ### In Scope (MVP) * Web cockpit keyboard users can press `o d` to open the focused Command Center surface - implemented through Command Center shortcut metadata and `expandedBottomRailSurfaceId`. * The shortcut help modal describes `o d` as `Open Command Center.` instead of details or summary language. * The old details shortcut action is renamed or retired so retained state-summary behavior is clearly secondary. * Retained `OrchestrationDetailPortal`, `OrchestrationDrawer`, and `TerminalRuntimeDrawer` use a shared overlay-layer marker above the expanded bottom-rail surface. * `BottomRailExpansionHost` checks for higher active overlay layers before closing itself on Escape. * Escape closes the topmost relevant layer first: state summary, command-center drawer, or terminal runtime drawer before the expanded Orchestration surface. * Backdrop clicks close the expanded surface and inner-panel clicks do not close it. * Tests cover shortcut routing, shortcut help copy, runtime dispatch, nested Escape order, backdrop close, and inner-panel containment. ### Out Of Scope (Deferred) * Quest Board and War Room focused-surface parity - Reason: Session 05 owns panel-specific parity and local-state preservation for those panels. * Responsive viewport tuning and browser screenshot evidence - Reason: Session 06 owns desktop and small viewport verification. * Final documentation and phase closeout - Reason: Session 07 owns final docs and regression evidence. * Backend command execution, queue/campaign/file/Git/terminal/container semantics, hosted services, Worker protocol, remote execution, trusted erasure, or formal accessibility certification - Reason: this session changes `apps/web` shortcut and overlay presentation behavior only. * A new remappable or user-configurable global shortcut system - Reason: this session updates the existing fixed Command Center shortcut family. *** ## 5. Technical Approach ### Architecture Add a small overlay-layer helper in `apps/web/src/lib/overlayLayers.ts` with stable layer names, a `data-overlay-layer` attribute name, and a query helper that can tell whether a higher layer is currently active. Use this helper from `BottomRailExpansionHost` so its Escape listener skips closing when a higher Command Center layer exists. Mark the focused bottom-rail host as the bottom-rail layer and mark retained Orchestration overlays as higher layers. `OrchestrationDetailPortal`, `OrchestrationDrawer`, and `TerminalRuntimeDrawer` already own their own Escape listeners and close behavior, so the host only needs to defer while those layers are present. The next Escape after the higher layer closes should close the focused surface normally. Repoint the `o d` command path in `commandCenterShortcuts.ts` from details language to primary Command Center language. Prefer renaming the action to `command_center_open` so the code contract no longer says "details" for a primary working surface. `OrchestrationShell` should handle that action by calling the existing `openCommandCenterSurface` path and should keep the explicit `State summary` button as a secondary in-panel inspector. ### Design Patterns * Store-backed focused surface: Continue using `expandedBottomRailSurfaceId` as the only source of bottom-rail expansion state. * Layered overlay convention: Use stable `data-overlay-layer` values rather than component-specific Escape exceptions. * Same-instance preservation: Do not render another `OrchestrationPanel` or `OrchestrationShell` for shortcut-driven expansion. * Product-facing shortcut copy: Help rows and ARIA labels should describe the working Command Center path, not implementation details. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ----------------------------------- | --------------------------------------------------------------------------------- | ---------- | | `apps/web/src/lib/overlayLayers.ts` | Shared overlay layer names, data attribute helpers, and higher-layer query logic. | \~80 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/src/components/BottomRailExpansionHost.tsx` | Add bottom-rail layer marker and skip Escape close when a higher overlay layer is active. | \~45 | | `apps/web/src/components/orchestration/OrchestrationCurrentState.tsx` | Mark the retained state summary portal as a higher overlay layer. | \~10 | | `apps/web/src/components/orchestration/OrchestrationDrawer.tsx` | Mark the command-center record drawer as a higher overlay layer. | \~10 | | `apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx` | Mark the terminal runtime drawer as a higher overlay layer. | \~10 | | `apps/web/src/components/orchestration/ExecutorRunHistoryDrawer.tsx` | Mark the nested execution history drawer as a higher overlay layer if it shares the Orchestration drawer close path. | \~10 | | `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Route the primary Command Center shortcut action to `openCommandCenterSurface` and keep state summary as secondary. | \~40 | | `apps/web/src/lib/commandCenterShortcuts.ts` | Rename or replace the primary details shortcut action, repoint `o d`, update resolver labels, and keep metadata product-facing. | \~70 | | `apps/web/src/lib/useKeyboardShortcuts.ts` | Update global shortcut action cases for the renamed Command Center action. | \~25 | | `apps/web/src/components/KeyboardShortcutsModal.tsx` | Adjust only if shared ARIA label handling needs the updated Command Center copy. | \~10 | | `apps/web/tests/commandCenterShortcuts.test.ts` | Update pure shortcut route, resolver, help, and ARIA-label expectations. | \~80 | | `apps/web/tests/keyboardShortcuts.test.ts` | Update routeKey, DOM dispatch, and hook integration expectations for the primary Command Center shortcut. | \~80 | | `apps/web/tests/KeyboardShortcutsModal.test.tsx` | Update shortcut modal copy, accessible labels, and section count expectations. | \~40 | | `apps/web/tests/BottomRailExpansionHost.test.tsx` | Add higher-layer Escape guard, backdrop close, and inner-panel containment coverage. | \~90 | | `apps/web/tests/OrchestrationPanel.test.tsx` | Add runtime dispatch and nested Escape-order regressions for expanded Orchestration plus state summary, command-center drawer, and terminal drawer. | \~180 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `o d` opens the focused Command Center surface by setting `expandedBottomRailSurfaceId` to `"orchestration"`. * [ ] `COMMAND_CENTER_SHORTCUTS_HELP` describes `o d` as `Open Command Center.` or equivalent working-surface copy. * [ ] `KeyboardShortcutsModal` exposes the updated Orchestration row and accessible label. * [ ] Retained state-summary behavior remains available only as a clearly secondary in-panel control. * [ ] Expanded Orchestration remains open when Escape closes `OrchestrationDetailPortal`. * [ ] Expanded Orchestration remains open when Escape closes `OrchestrationDrawer`. * [ ] Expanded Orchestration remains open when Escape closes `TerminalRuntimeDrawer`. * [ ] The next Escape after higher layers are closed dismisses the expanded Orchestration surface. * [ ] Backdrop clicks close the expanded surface and inner-panel clicks do not. ### Testing Requirements * [ ] Pure shortcut tests cover the updated `o d` route and action label. * [ ] Hook integration tests prove the keyboard event dispatches the primary Command Center action. * [ ] Shortcut modal tests prove user-facing copy and ARIA labels match the new primary behavior. * [ ] Host and Orchestration tests prove nested overlay Escape order and click containment. * [ ] Focused web tests and web typecheck completed. ### Non-Functional Requirements * [ ] No backend execution, hosted service, Worker, remote execution, trusted erasure, or formal accessibility certification claim is introduced. * [ ] Command Center rows remain product-facing and do not expose raw commands, terminal output, diffs, file contents, provider payloads, tokens, secrets, or broad absolute paths. * [ ] Overlay-layer logic is deterministic, cleaned up on unmount, and does not rely on timing-sensitive duplicated component trees. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. *** ## 8. Implementation Notes ### Working Assumptions * `apps/web` is the package context: the analysis script marks the candidate session as `apps/web`, and all relevant source evidence lives in web shell, shortcut, Orchestration, and test files. * The primary pointer path is already corrected by Session 03: `OrchestrationHeader` exposes `Open Command Center` and `OrchestrationShell` can set `expandedBottomRailSurfaceId` to `"orchestration"`. * The retained state summary should stay as a secondary panel control, not as the `o d` shortcut target, because the Phase 21 PRD says the primary open action must expose the usable Command Center workbench. * A shared `data-overlay-layer` convention is sufficient for this session because all named higher layers already render mounted DOM while open and already own their close handlers. ### Conflict Resolutions * The historical `command_center_details_open` action name conflicts with Session 03's product behavior and Session 04's stub requirement to make `o d` open the focused Command Center. The chosen interpretation is to rename or replace that action for the primary shortcut and avoid retaining a details-primary shortcut. * Session 02 already implemented base host Escape behavior, while Session 04 owns nested overlay order. The chosen interpretation is to keep the base host listener but make it layer-aware so higher Orchestration overlays close first. ### Key Considerations * Window keydown listener registration order matters less if the host checks active higher layers before closing. * The host should ignore Escape when `event.defaultPrevented` is already true, preserving the existing keyboard help and command palette behavior. * Existing tests already prove same-instance Orchestration expansion and no duplicate hydration; this session should extend those tests for shortcut dispatch and nested layer close order rather than duplicating all Session 03 coverage. * `KeyboardShortcutsModal` builds accessible labels with `commandCenterShortcutAriaLabel`, so updating metadata may be enough for modal copy unless tests reveal a component-level adjustment. ### Potential Challenges * React state updates from a higher overlay close may not flush before the host listener runs in the same keydown event. Querying for a higher overlay before closing avoids depending on flush order. * `ExecutorRunHistoryDrawer` is nested behind `OrchestrationDrawer` for execution records; if it uses its own portal/backdrop, it should share the same higher-layer marker. * Retiring `command_center_details_open` may require updates across both pure shortcut tests and runtime Orchestration tests. ### Relevant Considerations * \[P20] **Release evidence is the execution claim source**: Shortcut and recovery behavior must be proven with tests before the surface is claimed complete. * \[P20] **Do not add action verbs before evidence**: Shortcut copy should say `Open Command Center` only because the implementation opens the existing focused Command Center workbench. * \[P20] **Broad privacy gates are release-critical**: Expanded and nested Command Center surfaces must keep raw command, output, diff, file-content, token, provider, webhook, Docker, and broad-path detail out of broad UI rows. * \[P03] **Stable docs are the current contract**: Stable documentation changes remain deferred to Session 07 after all focused-surface behavior is complete. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Keyboard users open the secondary state summary instead of the real Command Center. * Escape closes the parent focused surface while a nested drawer or summary is still open. * Overlay click handling accidentally closes focused work while the user interacts with Command Center controls. *** ## 9. Testing Strategy ### Unit Tests * Update `apps/web/tests/commandCenterShortcuts.test.ts` for the new primary action, `o d` route, resolver label, help row, uniqueness, and ARIA label. * Update `apps/web/tests/keyboardShortcuts.test.ts` for global `routeKey`, `defaultDispatchCommandCenterShortcut`, and hook-dispatched event behavior. * Add `apps/web/tests/BottomRailExpansionHost.test.tsx` coverage for higher-layer Escape suppression and continued backdrop/inner-panel click behavior. ### Integration Tests * Update `apps/web/tests/KeyboardShortcutsModal.test.tsx` to assert the Orchestration section shows Command Center copy and accessible labels. * Extend `apps/web/tests/OrchestrationPanel.test.tsx` so dispatching the primary Command Center shortcut opens `bottom-rail-expanded-orchestration` through the host. * Add nested Escape tests in `apps/web/tests/OrchestrationPanel.test.tsx` for state summary, command-center drawer, and terminal runtime drawer while the focused Orchestration surface remains open. ### Runtime Verification * No browser viewport pass is required in this session; Session 06 owns desktop and small viewport visual evidence after Quest Board and War Room parity are complete. ### Edge Cases * Pressing `o d` while Orchestration is already focused leaves the same focused surface active without remounting. * Pressing Escape with no higher overlay closes the expanded surface. * Pressing Escape with a higher overlay open closes only that overlay first. * Clicking inside the expanded panel, including tab controls and form controls, does not close the focused surface. * Clicking the backdrop closes the expanded surface after higher layers are absent. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase21-session01-expansion-state-foundation`, `phase21-session02-shared-expansion-host`, `phase21-session03-orchestration-command-center-expansion`. * Depended by: `phase21-session05-quest-board-and-war-room-parity`, `phase21-session06-responsive-layout-and-accessibility-pass`, `phase21-session07-final-regression-and-documentation`. *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase21-session04-shortcut-and-overlay-layering/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.