> 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/phase06-session06-mobile-cockpit-and-accessibility-hardening/spec.md). # Session Specification **Session ID**: `phase06-session06-mobile-cockpit-and-accessibility-hardening` **Phase**: 06 - Collaboration, Isolation, and Mobile **Status**: Complete **Created**: 2026-05-30 **Package**: apps/web **Package Stack**: TypeScript, React 18, Vite, Zustand, Tailwind, Vitest, Playwright *** ## 1. Session Overview This session hardens the web cockpit for supported mobile browser widths and accessibility paths after the Phase 06 collaboration and isolation work. It focuses on keeping the battlefield, mission list, roster, drawers, settings, replay, local orchestration, War Room collaboration controls, and remote context reachable without clipped labels, broken scroll regions, focus loss, or pointer-only behavior. The work matters because recent Phase 06 sessions added denser collaboration, authority, remote-context, and isolation diagnostic states to an already dense cockpit. Mobile users and keyboard or screen-reader users need stable dimensions, readable labels, visible focus, semantic controls, duplicate-action guards, reduced-motion equivalents, and clear unavailable states without the UI implying hosted collaboration, remote execution, production-hosted validation, mobile certification, or trusted erasure. This is a product-surface hardening session, not a broad redesign. It should preserve the existing operations-console layout, local-first boundary, optional Worker transfer copy, and synthetic local runtime behavior while adding focused component tests and retained Playwright evidence for the changed desktop and mobile states. *** ## 2. Objectives 1. Keep core cockpit and Phase 06 collaboration workflows reachable on supported mobile browser widths with stable scroll regions and no incoherent overlap. 2. Improve keyboard, pointer, screen-reader, visible focus, focus-return, and touch target behavior for changed shell, drawer, local orchestration, and War Room controls. 3. Preserve reduced-motion meaning for battlefield state, overlays, replay, achievements, collaboration context, reconnect, and status feedback. 4. Add focused tests and retained browser evidence for text fit, labels, focus, duplicate guards, reduced motion, and no-overlap behavior without claiming full WCAG or mobile certification. *** ## 3. Prerequisites ### Required Sessions * [x] `phase06-session01-collaboration-requirements-and-safety-baseline` - Provides the Phase 06 routing matrix and mobile/accessibility acceptance checklist. * [x] `phase06-session02-room-authority-and-participant-identity-contracts` - Provides participant role, authority, approval, reconnect, and duplicate-action contracts consumed by the web UI. * [x] `phase06-session03-shared-collaboration-event-contracts` - Provides safe remote-context frame families, blocked payload categories, and redacted summary rules. * [x] `phase06-session04-collaborative-cockpit-ux-and-remote-context` - Provides the current War Room collaboration UX and remote-context separation. * [x] `phase06-session05-isolation-boundary-and-sandbox-diagnostics` - Provides unavailable execution posture and diagnostics copy that must remain reachable. * [x] `phase02-session07-product-surface-validation-and-documentation-closeout` - Provides existing app desktop/mobile browser validation patterns. ### Required Tools/Knowledge * Node 20+ and npm workspaces. * React 18, TypeScript, Zustand, Tailwind, Testing Library, Vitest, and Playwright app desktop/mobile projects. * Existing app anchors: `Layout`, `TitleBar`, `Battlefield`, `MissionLog`, `HeroRoster`, `HeroDetailDrawer`, `MissionDetailDrawer`, `SettingsDrawer`, `ReplayPanel`, `OrchestrationPanel`, `WarRoomPanel`, `WarRoomRoster`, `WarRoomApprovalQueue`, and `RemoteParticipantOverlay`. * Phase 06 routing requirements P06-R024 through P06-R029. ### Environment Requirements * Local dependencies installed with `npm install`. * Browser evidence runs locally with mocked or local Worker paths only. * Cloudflare credentials, hosted accounts, analytics, Docker, remote runners, provider keys, and production-hosted deployments are not required. *** ## 4. Scope ### In Scope (MVP) * Browser users can reach critical cockpit regions on mobile - Keep battlefield, mission list, roster, hero detail, mission detail, settings, replay, local orchestration, War Room, and shell controls reachable with stable scroll regions and explicit loading, empty, error, offline, and unavailable states. * Browser users can read and operate dense labels - Make long participant names, room codes, Worker URLs, diagnostics, state labels, buttons, badges, and error details wrap, truncate, or preserve layout intentionally without horizontal overflow. * Keyboard and screen-reader users can operate changed controls - Ensure accessible names, semantic roles, visible focus, native controls where possible, dialog labels, focus return, and disabled-state explanations for changed surfaces. * Pointer and touch users can operate state-changing actions - Keep create, join, approve, reject, connect, retry, disconnect, leave, reset, send, guarded-action, settings, replay, and overlay controls large enough and guarded against duplicate triggers while in flight. * Reduced-motion users retain meaning - Preserve static labels, badges, status copy, rings, and summaries when battlefield, overlay, replay, achievement, reconnect, toast, or remote-context motion is dampened. * Playwright and unit evidence cover changed behavior - Extend focused web tests and app desktop/mobile evidence for reachable controls, no overlap, focus, labels, reduced motion, and redacted collaboration copy. * Web docs capture validated behavior - Update README notes for mobile, accessibility, reduced-motion evidence, and explicit non-certification caveats. ### Out of Scope (Deferred) * Native mobile app, app-store packaging, or push/background sync - Reason: this session validates supported browser widths only. * Full WCAG certification or mobile certification - Reason: this session produces scoped local browser evidence, not a formal certification audit. * Hosted identity, hosted storage, analytics, public replay hosting, or production-hosted validation - Reason: Phase 07 and Phase 08 own those claims. * File, git, terminal, Docker, remote, Worker, or hosted command execution - Reason: current execution posture remains non-executing and unavailable. * Trusted unified erasure for Worker storage, browser hints, logs, archives, exports, replay buffers, backups, settings, memory, or future hosted data - Reason: Phase 08 owns release-grade erasure. * Public-demo redesign or new product media - Reason: public-demo changes are limited to parity or documentation if core app vocabulary changes. *** ## 5. Technical Approach ### Architecture `apps/web` remains the single package target. The implementation should start with shell and CSS foundations because mobile reachability depends on stable grid tracks, bounded scroll containers, consistent focus treatment, and minimum interactive target sizing. The cockpit should keep its current dense operations-console structure while ensuring bottom-rail panels, drawers, dialogs, and overlay surfaces do not trap or lose focus. Component work should then harden the surfaces most affected by Phase 06: local orchestration and War Room collaboration. These panels should preserve existing store-owned duplicate guards, explicit unavailable states, compact diagnostics, and redacted remote-context summaries while improving text fit, accessible labels, semantic grouping, and touch behavior. Battlefield and remote overlays should keep nonzero 16:9 dimensions and static state meaning when reduced motion is active. Testing should combine focused Vitest coverage for semantics and duplicate guards with Playwright evidence for mobile layout, reduced motion, focus, and no-overlap behavior. Browser evidence must remain labeled as local browser or mocked Worker evidence only. ### Design Patterns * Stable responsive containers: Use explicit min/max dimensions, aspect ratio, bounded overflow, and package-relative CSS utilities where layout stability matters. * Native semantic controls: Prefer buttons, inputs, forms, dialogs, fieldsets, lists, and labels over custom pointer handlers for changed interactions. * Bounded visible feedback: Loading, empty, error, offline, unavailable, denied, disabled, and in-flight states are visible and accessible. * State reset or revalidation on re-entry: Dialogs, drawers, room hints, Worker URL changes, leave/reset, reconnect, and replay/settings surfaces avoid stale state. * Reduced-motion equivalence: Static labels, badges, rings, counts, and copy convey state when motion is disabled. ### Technology Stack * TypeScript 5.9 in `apps/web`. * React 18.3 components and Testing Library coverage. * Zustand 4.5 stores for app, settings, audio, WebSocket, and War Room state. * Tailwind utility styling plus `apps/web/src/index.css` component utilities. * Vitest 4.1 focused web tests. * Playwright 1.60 app desktop/mobile projects with retained screenshots. * Biome, package typecheck, ASCII/LF, and `git diff --check` quality gates. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/tests/MobileAccessibility.test.tsx` | Focused component coverage for mobile shell reachability, labels, focus, dialog semantics, and reduced-motion affordances. | \~180 | | `.spec_system/specs/phase06-session06-mobile-cockpit-and-accessibility-hardening/implementation-notes.md` | Implementation evidence, command results, browser evidence paths, and residual risks. | \~120 | | `.spec_system/specs/phase06-session06-mobile-cockpit-and-accessibility-hardening/security-compliance.md` | Session security, privacy, accessibility, external-transfer, and non-certification review. | \~100 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/src/components/Layout.tsx` | Stabilize mobile grid, scroll regions, bottom rail reachability, and shell ordering. | \~80 | | `apps/web/src/index.css` | Add or refine focus, touch target, text-fit, reduced-motion, battlefield, and scroll utilities. | \~120 | | `apps/web/src/components/TitleBar.tsx` | Harden shell control wrapping, labels, focus, and mobile command reachability. | \~80 | | `apps/web/src/components/battlefield/Battlefield.tsx` | Preserve nonzero board dimensions, token labels, remote markers, and reduced-motion state meaning. | \~100 | | `apps/web/src/components/battlefield/RemoteParticipantOverlay.tsx` | Improve remote marker labels, text fit, reduced-motion-safe status, and no local state mutation. | \~70 | | `apps/web/src/components/MissionLog.tsx` | Harden mobile filters, rows, empty/error states, and label wrapping. | \~90 | | `apps/web/src/components/HeroRoster.tsx` | Harden mobile roster reachability, long-name behavior, keyboard paths, and accessible labels. | \~80 | | `apps/web/src/components/HeroCard.tsx` | Improve touch targets, text fit, state labels, and focus-visible behavior. | \~60 | | `apps/web/src/components/HeroDetailDrawer.tsx` | Improve dialog semantics, focus return, scroll behavior, and re-entry state. | \~80 | | `apps/web/src/components/MissionDetailDrawer.tsx` | Improve dialog semantics, long prompt wrapping, focus return, and scroll behavior. | \~80 | | `apps/web/src/components/SettingsDrawer.tsx` | Harden settings controls for labels, disabled states, reduced motion, and focus return. | \~100 | | `apps/web/src/components/ReplayPanel.tsx` | Harden replay panel reachability, reduced-motion copy, and local-only non-public-share wording. | \~70 | | `apps/web/src/components/CommandPalette.tsx` | Preserve keyboard focus and prevent global command conflicts while typing. | \~60 | | `apps/web/src/components/OrchestrationPanel.tsx` | Harden local orchestration mobile layout, filters, guarded-action controls, unavailable states, and duplicate guards. | \~140 | | `apps/web/src/components/WarRoomPanel.tsx` | Harden room hints, diagnostics, active room controls, remote context, room notices, in-flight states, and long text. | \~180 | | `apps/web/src/components/WarRoomApprovalQueue.tsx` | Harden pending decision controls, labels, touch targets, focus, and disabled reasons. | \~90 | | `apps/web/src/components/WarRoomRoster.tsx` | Harden participant names, roles, online/offline labels, local markers, and screen-reader text. | \~80 | | `apps/web/tests/CockpitShell.test.tsx` | Extend shell, dialog, and keyboard accessibility coverage. | \~120 | | `apps/web/tests/Battlefield.test.tsx` | Extend reduced-motion, label placement, focus, and no-clipping coverage. | \~100 | | `apps/web/tests/OrchestrationPanel.test.tsx` | Extend local orchestration mobile, unavailable-state, filter, and guarded-action accessibility coverage. | \~120 | | `apps/web/tests/WarRoomPanel.test.tsx` | Extend labels, disabled reasons, duplicate guards, long text, and focus coverage. | \~160 | | `apps/web/tests/WarRoomBattlefieldOverlay.test.tsx` | Extend remote marker accessibility, reduced-motion, and no local mutation coverage. | \~80 | | `tests/e2e/support/browserGuards.ts` | Add reusable mobile no-overflow, focus-visible, and no-overlap assertions if needed. | \~80 | | `tests/e2e/app.e2e.ts` | Extend app desktop/mobile evidence for changed cockpit, War Room, orchestration, drawers, focus, and reduced motion states. | \~180 | | `apps/web/README_web.md` | Document validated mobile/accessibility behavior, evidence scope, and non-certification caveats. | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Critical cockpit and collaboration workflows remain reachable on supported mobile browser widths. * [ ] Text, labels, buttons, panels, overlays, drawers, and battlefield elements do not overlap incoherently or force unintended horizontal scrolling. * [ ] Changed interactive controls expose accessible names, semantic roles, visible focus states, and keyboard or touch operation. * [ ] Dialogs, drawers, overlays, War Room panels, and replay/settings surfaces return focus or revalidate state on re-entry where feasible. * [ ] State-changing actions remain protected against duplicate triggers while in flight. * [ ] Reduced-motion mode preserves battlefield, overlay, replay, achievement, reconnect, remote-context, and toast meaning through static state. * [ ] UI and docs do not imply hosted collaboration, account proof, analytics, public replay hosting, remote execution, mobile certification, production-hosted validation, or trusted erasure. ### Testing Requirements * [ ] Component tests cover shell controls, drawers, labels, focus, reduced motion, duplicate guards, disabled states, and redacted collaboration copy. * [ ] Browser evidence covers app desktop and mobile cockpit, battlefield, local orchestration, War Room, drawer, focus, and reduced-motion states. * [ ] Screenshots are retained and reviewed for no blank panels, clipped controls, incoherent overlap, hidden primary controls, or unreadable errors. * [ ] Manual implementation notes record command results, evidence paths, and remaining non-certification caveats. ### Non-Functional Requirements * [ ] Core local cockpit workflows remain usable without Worker URL, Cloudflare credentials, hosted account, hosted storage, analytics, public replay hosting, Docker, remote runners, or provider keys. * [ ] Visible summaries remain compact, deterministic, and free of prompts, command bodies, terminal output, broad paths, tokens, exports, replay buffers, scans, diagnostics, logs, backups, and media drafts. * [ ] Mobile hardening does not introduce new runtime media, browser storage categories, external transfers, or hosted dependencies. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `npm --workspace @factionos/web run typecheck` passes. * [ ] Focused web Vitest coverage passes. * [ ] Relevant Playwright app desktop/mobile evidence is retained. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Key Considerations * Mobile evidence is scoped local browser validation, not mobile certification. * War Room Worker transfer remains optional, redacted, and separate from local cockpit truth. * Leave, reset, settings reset, diagnostics cleanup, and local recovery remain browser or local cleanup only, not trusted erasure. * The current app battlefield is a 2D DOM surface; do not introduce canvas, WebGL, Three.js, Phaser, PixiJS, or new media dependencies for this work. ### Potential Challenges * Dense panel layout: Use stable grid and scroll containers rather than hiding primary controls on mobile. * Text fit in collaboration states: Long room codes, participant names, Worker URLs, diagnostics, and errors need deliberate wrapping or truncation. * Focus return consistency: Existing drawers and overlays may have different close patterns; align only the changed surfaces without broad redesign. * Test flake risk: Keep Playwright assertions targeted, deterministic, and backed by mocked Worker or local runtime fixtures. ### Relevant Considerations * \[P02-apps/web] **Responsive and accessibility debt**: This session directly addresses mobile, focus return, dialog semantics, reduced motion, contrast, and browser validation for changed web surfaces. * \[P05-apps/warroom+apps/web] **War Room federation is optional and redacted**: Mobile collaboration controls must keep Worker transfer optional and avoid hosted identity or mobile certification claims. * \[P05] **Redaction is boundary-specific**: Browser evidence, helper tests, and UI copy must keep blocked payload categories out of visible collaboration context. * \[P03] **Real executors remain unimplemented by design**: Local orchestration and guarded-action controls must not imply approved actions execute. * \[P05] **Unified erasure still missing**: Leave, reset, settings reset, and recovery copy must avoid trusted deletion claims. * \[P03] **Local-first boundary is architectural**: The app must degrade cleanly when Cloudflare, hosted services, public tokens, provider credentials, and analytics are absent. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Mobile layout hides primary cockpit, War Room, orchestration, or drawer controls behind rails, overlays, modals, toasts, or browser edges. * Long room codes, participant names, diagnostics, prompts shown in details, errors, or status labels clip, overlap, or force unintended horizontal scrolling. * Keyboard or screen-reader users cannot understand or operate icon-only, disabled, in-flight, dialog, drawer, roster, approval, or guarded-action controls. * Reduced-motion users lose state meaning because animation was the only signal. * Browser evidence could be mislabeled as full WCAG, mobile certification, hosted collaboration validation, production-hosted validation, or trusted erasure. *** ## 9. Testing Strategy ### Unit Tests * Shell and layout tests for visible global controls, stable local-only status, drawer/dialog labels, and keyboard-safe global commands. * Battlefield tests for token labels, focus behavior, edge label placement, reduced-motion state equivalents, and remote marker separation. * War Room tests for long names, room codes, diagnostics, roster labels, approval labels, disabled reasons, duplicate guards, and no hosted-identity wording. * Local orchestration tests for guarded-action controls, filter labels, duplicate decision prevention, unavailable states, and keyboard operation. ### Integration Tests * Playwright app desktop and mobile tests for cockpit reachability, nonzero battlefield dimensions, no-overlap assertions, War Room states, local orchestration states, drawer reachability, focus visibility, reduced motion, and browser privacy guards. * Mocked Worker paths for War Room create, join, pending, approved, connected, reconnecting, unavailable, leave/reset, and redacted remote context. ### Manual Testing * Review retained desktop and mobile screenshots for clipped labels, overlapping panels, hidden primary controls, blank states, and unreadable errors. * Tab through changed shell, drawer, orchestration, War Room, battlefield, and overlay controls after implementation. * Verify reduced-motion mode keeps static state labels and does not rely on animation for meaning. ### Edge Cases * Very long participant names, room codes, Worker URLs, diagnostics, and error messages. * Worker URL missing, invalid, offline, timed out, rate-limited, bad response, unavailable, pending join, rejected join, reconnect failure, catch-up unavailable, and local-only fallback. * Server disconnected, auth-required, guarded action unavailable, and future executor unavailable states. * Dialogs and drawers closed with buttons, Escape, state resets, and re-entry. * Reduced-motion enabled through OS preference and stored app setting. *** ## 10. Dependencies ### External Libraries * No new external libraries planned. ### Internal Dependencies * `apps/web` component and store conventions. * `packages/protocol` participant, room, safe frame, queue, mission, and guarded-action types already consumed by the web package. * Existing Playwright app desktop/mobile projects and browser guard helpers. ### Other Sessions * **Depends on**: `phase06-session01-collaboration-requirements-and-safety-baseline`, `phase06-session02-room-authority-and-participant-identity-contracts`, `phase06-session03-shared-collaboration-event-contracts`, `phase06-session04-collaborative-cockpit-ux-and-remote-context`, `phase06-session05-isolation-boundary-and-sandbox-diagnostics` * **Depended by**: `phase06-session07-collaboration-isolation-and-mobile-validation-closeout` *** ## Next Steps Run the implement workflow step to begin AI-led 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/phase06-session06-mobile-cockpit-and-accessibility-hardening/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.