> 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/phases/phase_21/session_02_shared_expansion_host.md). # Session 02: Shared Expansion Host **Session ID**: `phase21-session02-shared-expansion-host` **Package**: apps/web **Status**: Complete **Completed**: 2026-06-29 **Estimated Tasks**: \~18-25 **Estimated Duration**: 2-4 hours *** ## Objective Build the common bottom-rail wrapper that can promote one mounted panel into a focused working surface. *** ## Scope ### In Scope (MVP) * Create a shared bottom-rail expansion host component near `apps/web/src/components/`. * Wire Quest Board, Orchestration, and War Room bottom cells through the host in `apps/web/src/App.tsx`. * Preserve existing `ShellSurface` and `SurfaceStateNote` behavior. * Add explicit open controls and guarded panel-background click expansion. * Implement backdrop, close button, Escape close, focus restore, ARIA labels, modal semantics while expanded, sizing, and stable test ids. * Prove only one bottom-rail surface can be expanded at a time. ### Out of Scope * Orchestration-specific label and shortcut changes. * Quest Board and War Room detail portal redesign. * Broad visual polish beyond making the shared host functional and testable. *** ## Prerequisites * [x] Session 01 completed. * [x] Existing App shell and Cockpit shell tests reviewed. * [x] Decision recorded if implementation uses fixed-position promotion or a portal. *** ## Deliverables 1. Shared expansion host used by all three bottom-rail panels. 2. Tests for open, close, backdrop, Escape, focus restore, one-at-a-time expansion, and guarded nested-control clicks. 3. Evidence that the host does not render duplicate panel implementations. *** ## Folded Source Details The source investigation found that `apps/web/src/App.tsx:156` renders the bottom rail as three `ShellSurface` columns and directly mounts `OrchestrationPanel` at `apps/web/src/App.tsx:161`. This session owns replacing those three independent shell cells with one shared expansion contract. Implementation details to preserve: * Create the host near `apps/web/src/components/` and wire it from `apps/web/src/App.tsx`. * Preserve the current `ShellSurface` and `SurfaceStateNote` behavior so loading, offline, and unavailable notes do not diverge between compact and expanded presentations. * Add stable test ids such as `bottom-rail-expand-orchestration` and `bottom-rail-expanded-orchestration`. * Add an explicit visible open affordance for each rail cell. * Allow panel-background clicks to open the surface, but guard interactive descendants: `button`, `a`, `input`, `textarea`, `select`, `[role="button"]`, `[role="tab"]`, `[contenteditable]`, and `[data-no-panel-expand]`. * Own common dialog behavior in the host: backdrop, close button, Escape, focus restore, `role="dialog"` while expanded, `aria-modal="true"`, `aria-labelledby`, `aria-controls`, labels, and focused sizing. * Only one bottom-rail surface may be expanded at a time. * Prefer same-instance promotion. The wrapper should keep the panel mounted once and switch the wrapper from rail layout to fixed focused layout when expanded. * Do not render a second panel tree in the host. If a portal is unavoidable, tests must prove switching compact/expanded targets does not unmount the child; otherwise the implementation must be changed before completion. End-to-end delivery bar for this session: * The product outcome is that the user can open and close any bottom panel as a focused working surface from the real cockpit shell. * Recovery paths must include backdrop close, close button, Escape close, and focus return to the opener. * Tests must execute the host behavior and prove nested controls do not get stolen by panel-background expansion. *** ## Success Criteria * [x] Quest Board, Orchestration, and War Room can each open through the shared host. * [x] Expanding one surface closes or replaces any other expanded bottom-rail surface. * [x] Clicks inside buttons, links, inputs, tabs, editable content, and `[data-no-panel-expand]` descendants do not trigger expansion. * [x] Close controls and Escape return focus to the opener. * [x] Tests prove the host preserves the mounted child instance or otherwise prove no remount/state fork. --- # 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/phases/phase_21/session_02_shared_expansion_host.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.