> 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-session05-quest-board-and-war-room-parity/spec.md). # Session Specification **Session ID**: `phase21-session05-quest-board-and-war-room-parity` **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 completes the Quest Board and War Room side of the focused bottom-rail surface contract. Sessions 01 through 04 created transient expansion state, a shared same-instance host, the Orchestration focused Command Center path, and layer-aware shortcut and Escape behavior. The remaining parity work is to make Quest Board and War Room behave like focused working surfaces while keeping their existing detail popups as secondary state summaries. The user-facing outcome is that a user can focus Quest Board or War Room, continue using the actual mounted panel, close and reopen it without losing local panel state, and still use nested controls without accidentally triggering or dismissing the focused surface. Header/details affordances must no longer imply that a detail popup is the primary place to work. The implementation stays inside `apps/web`. It does not change Quest Board suggestion semantics, War Room Worker protocol, hosted collaboration claims, trusted erasure posture, backend execution, or documentation closeout. *** ## 2. Objectives 1. Make Quest Board's primary panel/header open path resolve to the shared focused surface instead of the detail popup. 2. Make War Room's primary panel/header open path resolve to the shared focused surface instead of the detail popup. 3. Keep Quest Board and War Room detail popups as clearly secondary state summaries with correct overlay-layer Escape ordering. 4. Prove local state and existing action controls survive focused close/reopen without duplicate panel trees or accidental expansion. *** ## 3. Prerequisites ### Required Sessions * [x] `phase21-session01-expansion-state-foundation` - Provides transient `expandedBottomRailSurfaceId` state. * [x] `phase21-session02-shared-expansion-host` - Provides `BottomRailExpansionHost`, same-instance promotion, guarded compact clicks, focus restore, and shared test ids. * [x] `phase21-session03-orchestration-command-center-expansion` - Proves the Orchestration primary focused-surface pattern. * [x] `phase21-session04-shortcut-and-overlay-layering` - Provides layer-aware Escape behavior and the `overlayLayers` helper. ### Required Tools Or Knowledge * React, TypeScript, Zustand, Testing Library, and Vitest in `apps/web`. * Current Quest Board local state and action controls in `apps/web/src/components/QuestBoard.tsx`. * Current War Room local/store-backed state and Worker-control boundaries in `apps/web/src/components/WarRoomPanel.tsx`. * Existing bottom-rail host behavior in `apps/web/src/components/BottomRailExpansionHost.tsx`. ### Environment Requirements * Local checkout with npm dependencies installed. * Happy DOM test environment used by `apps/web/tests`. * No hosted credentials, Worker deployment credentials, provider keys, local server token, or production environment are required. *** ## 4. Scope ### In Scope (MVP) * Quest Board users can click noninteractive panel/header space or the host focus button to open the full focused Quest Board working surface. * Quest Board local `replyDraft`, scan feedback, card actions, assign select state, and pending/feedback UI remain aligned because the mounted `QuestBoard` instance is preserved. * Quest Board detail popup is retained only as a secondary state summary, with product-facing label/copy that no longer reads as the primary focused-work path. * War Room users can click noninteractive panel/header space or the host focus button to open the full focused War Room working surface. * War Room local/store-backed room hints, room code, notice draft, approval rows, erasure preview/confirmation, diagnostics, fallback state, and Worker controls remain aligned because the mounted `WarRoomPanel` instance is preserved. * War Room detail popup is retained only as a secondary state summary, with product-facing label/copy that no longer reads as the primary focused-work path. * Quest Board and War Room retained summaries use overlay-layer markers so Escape closes the summary before the parent focused surface. * Nested Quest Board and War Room buttons, links, inputs, selects, textareas, approval controls, erasure controls, and notice controls keep their original actions and do not accidentally trigger focused expansion. ### Out Of Scope (Deferred) * New Quest Board suggestion features - Reason: this session changes presentation and recovery paths only. * War Room Worker protocol, Durable Object storage, or server route changes - Reason: the existing Worker lifecycle behavior remains the source of truth. * Trusted unified erasure, hosted identity, hosted collaboration safety, production-hosted validation, or formal accessibility certification claims - Reason: these remain explicit no-claims unless a future scoped session ships evidence. * Responsive viewport tuning and browser screenshot evidence - Reason: Session 06 owns desktop and small viewport layout verification. * Final documentation closeout - Reason: Session 07 owns stable docs and final regression evidence. *** ## 5. Technical Approach ### Architecture Continue using `BottomRailExpansionHost` as the only bottom-rail focused-surface host. The host already owns same-instance promotion, backdrop, close button, Escape, focus restore, one-at-a-time expansion, guarded compact clicks, and stable test ids. Do not render a duplicate `QuestBoard` or `WarRoomPanel`. Change each panel header from a full-width details button into a normal product header area plus a secondary inspector button. Because the host opens on noninteractive panel-background clicks, the non-button header becomes part of the primary focused-surface path. The secondary inspector button remains a normal guarded button and should be labeled as a state summary, not as the primary surface. Extend the shared overlay-layer helper with Quest Board and War Room state-summary layers. Mark `QuestBoardDetailPortal` and `WarRoomDetailPortal` with those layers and update their Escape handlers to close only when their summary is the top active layer. This matches the Session 04 Orchestration overlay model and prevents one Escape from closing both the summary and parent focused surface. ### Design Patterns * Same-instance focused surface: keep one mounted panel tree and switch only the wrapper presentation. * Secondary inspector naming: use state-summary language for retained detail popups. * Layered overlay recovery: use `data-overlay-layer` helpers instead of one-off parent Escape exceptions. * Product-facing copy: avoid debug, scaffold, raw payload, or implementation-only labels in primary UI. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---- | --------------------------------------------------------------------------------------------- | ---------- | | None | No new source file is required; this session extends existing panel, overlay, and test files. | 0 | ### Files To Modify | File | Changes | Est. Lines | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/src/lib/overlayLayers.ts` | Add Quest Board and War Room state-summary overlay layer constants, order, and z-index classes. | \~20 | | `apps/web/src/components/QuestBoard.tsx` | Refactor header/details affordance, relabel retained details as a secondary state summary, and mark the summary portal as a higher overlay layer. | \~80 | | `apps/web/src/components/WarRoomPanel.tsx` | Refactor header/details affordance, relabel retained details as a secondary state summary, and mark the summary portal as a higher overlay layer. | \~100 | | `apps/web/tests/QuestBoard.test.tsx` | Update secondary summary expectations and add Quest Board focused-surface/state-preservation regressions where component-local coverage is best. | \~140 | | `apps/web/tests/WarRoomPanel.test.tsx` | Update secondary summary expectations and add War Room focused-surface/control-preservation regressions where component-local coverage is best. | \~180 | | `apps/web/tests/CockpitShell.test.tsx` | Add real-shell regressions for Quest Board and War Room focused open/close, state preservation, and nested Escape order. | \~180 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Quest Board focused open from the host button and noninteractive panel/header area sets `expandedBottomRailSurfaceId` to `"quest-board"`. * [ ] Quest Board secondary summary remains available through a clearly secondary button and no longer uses details-primary product copy. * [ ] Quest Board reply draft and action feedback remain visible after focused close/reopen. * [ ] Quest Board scan, accept, dismiss, assign, select, and reply controls keep their original behavior and do not accidentally expand the panel. * [ ] War Room focused open from the host button and noninteractive panel/header area sets `expandedBottomRailSurfaceId` to `"war-room"`. * [ ] War Room secondary summary remains available through a clearly secondary button and no longer uses details-primary product copy. * [ ] War Room room hints, room code, notice draft, erasure preview/confirmation, approval rows, and diagnostics remain visible after focused close/reopen where those states are present. * [ ] War Room save, create, join, connect, retry, disconnect, leave, reset, approval, notice, diagnostics, and erasure controls keep their original behavior and do not accidentally expand the panel. * [ ] Escape closes Quest Board and War Room secondary summaries before closing the parent focused bottom-rail surface. ### Testing Requirements * [ ] Quest Board component and shell tests cover secondary summary labels, overlay layer marker, state preservation, and guarded controls. * [ ] War Room component and shell tests cover secondary summary labels, overlay layer marker, state preservation, and guarded controls. * [ ] Focused bottom-rail host behavior remains covered by existing host tests and new real-shell regressions. * [ ] Focused web tests and web typecheck complete. ### Non-Functional Requirements * [ ] No duplicate `QuestBoard` or `WarRoomPanel` tree is rendered for focused mode. * [ ] No hosted identity, hosted collaboration, trusted erasure, remote execution, or production-hosted claim is introduced. * [ ] Broad UI rows and summaries do not expose raw prompts, command bodies, terminal output, file contents, diffs, Worker authority tokens, request bodies, secrets, replay buffers, exports, scan payloads, or broad absolute paths. ### 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 analyzer marks Session 05 as `apps/web`, and all source evidence for Quest Board, War Room, bottom-rail expansion, and related tests lives under `apps/web`. * The shared host already provides the primary focused-surface mechanism: `App.tsx` wraps Quest Board and War Room in `BottomRailExpansionHost`, and host tests already prove same-instance promotion, one-at-a-time expansion, guarded compact clicks, backdrop/Escape close, and focus restore. * The existing Quest Board and War Room detail portals should be retained as secondary summaries rather than deleted, because their current tests verify useful bounded summary content and the phase PRD permits secondary inspectors. ### Conflict Resolutions * The analyzer and `completed_sessions` mark `phase21-session04-shortcut-and-overlay-layering` complete, while `.spec_system/PRD/phase_21/session_04_shortcut_and_overlay_layering.md` still says `Status: Not Started`. The chosen interpretation is to trust the analyzer and Session 04 validation artifact, which reports PASS, 21/21 tasks complete, and completed history in state. * Session 02 already made Quest Board and War Room expandable through the shared host, while Session 05 still names routing as in scope. The chosen interpretation is that Session 05 must complete parity by removing details-primary header behavior, adding panel-specific state preservation tests, and proving nested controls do not steal or trigger expansion. ### Key Considerations * Header content should become noninteractive so host background-click expansion can be the primary panel/header path. The secondary state-summary button must remain a normal guarded control. * Existing Quest Board actions call local server routes and must keep duplicate-trigger/pending state handling from the store. * Existing War Room actions are optional external transfer through a configured Worker URL and must preserve redacted, disabled, unavailable, and no-overclaim copy. * The overlay-layer update should preserve Session 04 behavior for Orchestration drawers and should not lower existing z-indexes. ### Potential Challenges * Changing a full-width header button can affect accessible names and tests that click header text. Tests should assert the new primary behavior and update detail-summary expectations deliberately. * Quest Board card action state is a mix of component-local select state and store-backed pending/feedback. Tests should exercise both without depending on duplicate renders. * War Room has many store-backed controls and an unmount disconnect effect. Focused close/reopen must not unmount the panel, while final test cleanup still disconnects normally. ### Relevant Considerations * \[P20] **Release evidence is the execution claim source**: Claim parity only after tests prove visible focused behavior, state preservation, and recovery paths. * \[P20] **Do not add action verbs before evidence**: Keep labels tied to implemented Quest Board and War Room controls. * \[P20] **Broad privacy gates are release-critical**: Do not expose raw command, output, diff, file content, Worker authority token, webhook body, provider payload, Docker detail, secret, or broad path data in broad UI. * \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: Focused War Room remains optional Worker transfer and must not imply hosted identity, public collaboration safety, production auditability, certification, or full erasure. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * A header click still opens a secondary summary instead of the full focused working surface. * Focused close/reopen accidentally remounts a panel and loses local form, draft, or pending state. * Nested buttons and forms either trigger panel expansion or get blocked from their original actions. * Escape closes the parent focused surface while a secondary summary is still open. *** ## 9. Testing Strategy ### Unit Tests * Update `apps/web/tests/QuestBoard.test.tsx` for secondary summary labels, overlay markers, summary content, Escape close, and existing action behavior. * Update `apps/web/tests/WarRoomPanel.test.tsx` for secondary summary labels, overlay markers, summary content, no store action mutation from summary open, and existing Worker-control behavior. ### Integration Tests * Update `apps/web/tests/CockpitShell.test.tsx` to prove Quest Board and War Room open through the shared host, preserve a single mounted panel instance, retain local/store-backed state after close/reopen, and keep nested controls guarded. * Use existing `apps/web/tests/BottomRailExpansionHost.test.tsx` as the generic host contract and add shell-specific coverage only for panel parity. ### Runtime Verification * Run focused web tests for Cockpit shell, Quest Board, War Room, and the host. * Run web typecheck for `@factionos/web`. ### Edge Cases * Quest Board secondary summary open while the Quest Board focused surface is active, then Escape closes only the summary first. * War Room secondary summary open while the War Room focused surface is active, then Escape closes only the summary first. * Quest Board accept/dismiss/assign/select/reply/scan controls are clicked in compact and focused modes without triggering focus state changes. * War Room save/create/join/approval/notice/erasure/diagnostics controls are clicked in compact and focused modes without triggering focus state changes. * Sensitive War Room and Quest Board fields remain redacted from broad rows and summaries. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase21-session01-expansion-state-foundation`, `phase21-session02-shared-expansion-host`, `phase21-session03-orchestration-command-center-expansion`, `phase21-session04-shortcut-and-overlay-layering` * Depended by: `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-session05-quest-board-and-war-room-parity/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.