> 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-session04-collaborative-cockpit-ux-and-remote-context/spec.md).

# Session Specification

**Session ID**: `phase06-session04-collaborative-cockpit-ux-and-remote-context` **Phase**: 06 - Collaboration, Isolation, and Mobile **Status**: Not Started **Created**: 2026-05-30 **Package**: apps/web **Package Stack**: TypeScript, React 18, Vite, Zustand, Tailwind, Vitest, Playwright

***

## 1. Session Overview

This session turns the Phase 06 authority and collaboration event contracts from Sessions 02 and 03 into understandable cockpit UX. The web app should make member, observer, leader, pending, rejected, unavailable, reconnecting, disconnected, left, authority-failed, remote-context, room-notice, and local-only states visible without blank panels or hosted-product implications.

The work stays inside the local-first browser cockpit. Optional Worker transfer remains clearly separate from local hero, mission, queue, guarded-action, replay, export, notification, settings, adapter, scan, archive, memory, media, diagnostic, log, backup, and localStorage truth. Participant names, colors, roles, and online state remain display metadata, not account-backed identity.

The session should also tighten duplicate-action handling and accessible feedback for approve, reject, reconnect, disconnect, leave, reset, room notice, and redacted federation flows. It should prepare the changed collaboration surfaces for the later mobile and accessibility hardening session without claiming mobile certification, hosted collaboration, remote execution, public replay hosting, analytics, production-hosted validation, or trusted erasure.

***

## 2. Objectives

1. Make all current War Room lifecycle, authority, role, and remote-context states visible, bounded, and understandable in the web cockpit.
2. Keep remote collaboration context visually and structurally separate from local source-of-truth cockpit state.
3. Guard duplicate state-changing collaboration actions while in flight and revalidate room state on re-entry, reconnect, Worker URL changes, leave, and reset.
4. Add focused web tests and browser evidence coverage for role states, failure paths, safe summaries, accessibility labels, and local-only fallbacks.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase06-session01-collaboration-requirements-and-safety-baseline` - Provides the Phase 06 routing matrix, collaboration boundary, and mobile/accessibility acceptance checklist.
* [x] `phase06-session02-room-authority-and-participant-identity-contracts` - Provides authority, role, stale-state, duplicate-decision, reconnect, and failure contracts consumed by the web UI.
* [x] `phase06-session03-shared-collaboration-event-contracts` - Provides safe remote-context frame families, summaries, catch-up bounds, and blocked payload rules.
* [x] `phase05-session07-war-room-validation-and-documentation-closeout` - Provides the shipped optional Worker UX baseline and local browser evidence pattern.

### Required Tools/Knowledge

* Node 20+ and npm workspaces.
* React 18, TypeScript, Zustand, Tailwind, Vitest, Testing Library, and the existing Playwright app projects.
* Existing web War Room files: `WarRoomPanel`, `WarRoomRoster`, `WarRoomApprovalQueue`, `useWarRoomStore`, `warRoomUi`, `warRoomPresence`, `warRoomFederation`, and `RemoteParticipantOverlay`.
* Phase 06 routing requirements P06-R007, P06-R008, and P06-R015 through P06-R017.

### Environment Requirements

* Cloudflare credentials are optional and must not be required for tests.
* Browser evidence must use local or mocked Worker paths.
* No prompts, file contents, command bodies, terminal output, transcripts, tokens, broad paths, exports, replay buffers, scan payloads, diagnostics, logs, backups, media drafts, or `EXAMPLES/` content may be added as fixtures.

***

## 4. Scope

### In Scope (MVP)

* Browser users can understand collaboration state - Render local-only, disabled, invalid URL, unavailable, timeout, rate-limited, malformed, healthy, connected, reconnecting, caught-up, disconnected, left, pending, approved, rejected, authority-failed, leader, member, observer, and remote context states with explicit loading, empty, error, and offline states.
* Browser users can distinguish roles and authority - Surface leader, member, observer, pending, online, offline, local participant, issued, expired, mismatch, stale, and missing-authority status without implying hosted identity or account proof.
* Browser users can inspect safe remote context - Present participant count, safe family labels, room notices, remote focus, hero hints, mission hints, catch-up summaries, and unavailable send states without raw local payloads.
* Browser actions remain guarded - Approve, reject, reconnect, disconnect, leave, reset, room notice, and federation-send controls prevent duplicate triggers while in flight and revalidate state on re-entry.
* Remote context remains separate from local truth - Remote overlays and summaries cannot mutate local hero selection, mission selection, queues, guarded actions, replay, exports, notifications, settings, adapters, scans, archives, memory, media records, diagnostics, logs, backups, or persisted identity hints.
* Web docs capture shipped UX boundaries - Update package README notes for current collaboration UX, safe remote context, duplicate guards, and deferrals.

### Out of Scope (Deferred)

* Hosted account profiles, OAuth, organization membership, team management, or account-backed participant identity - Reason: Phase 07 owns hosted services and identity guardrails.
* Hosted storage, analytics dashboards, public replay hosting, push notifications, production-hosted validation, or mobile certification - Reason: later phases and closeout own these claims.
* File, git, terminal, Docker, remote, Worker, or hosted command execution - Reason: Session 05 owns isolation diagnostics only; real executors remain deferred.
* 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.
* Broad cockpit redesign or native mobile UI - Reason: this session targets collaboration UX state clarity; Session 06 owns mobile hardening.

***

## 5. Technical Approach

### Architecture

`apps/web` remains the owner of user-facing collaboration context. The store should keep authority state, lifecycle state, room snapshots, decision in-flight state, catch-up summaries, and remote contexts explicit and separate. Store actions should clear or revalidate state when the Worker URL, participant hint, room snapshot, reconnect result, leave action, reset action, or authority status changes.

The War Room panel should be organized around predictable status regions: current lifecycle and authority, room hints, diagnostics, active room controls, safe remote context, approval queue, roster, and local-only boundary copy. Remote-context summaries should show counts and allowed family labels rather than raw frame payloads.

The battlefield remote overlay can continue to show remote participant hints, but it must remain visually marked as remote Worker context and must not alter local selection or source-of-truth hero state. Component and helper tests should prove this boundary, while Playwright app evidence should retain desktop and mobile screenshots for key collaboration states.

### Design Patterns

* Store-owned state boundaries: Remote context stays in War Room store fields dedicated to collaboration overlay behavior.
* Bounded visible feedback: Error copy maps failure categories to safe user messages without echoing raw URLs, tokens, paths, requests, prompts, or payloads.
* In-flight guards: State-changing actions return early or disable controls while a matching operation is pending.
* Revalidation on re-entry: Reconnect, Worker URL changes, room changes, hydration, leave, and reset clear stale room, authority, and remote context.
* Accessible status regions: Status, alert, roster, approval, diagnostics, and remote-context regions expose labels and visible text.

### Technology Stack

* TypeScript 5.9 in `apps/web`.
* React 18.3 components and Testing Library coverage.
* Zustand 4.5 store actions and selectors.
* Tailwind utility styling through existing app conventions.
* Vitest 4.1 focused web tests.
* Playwright app desktop and mobile projects for retained browser evidence.
* Biome and `npm --workspace @factionos/web run typecheck` for quality gates.

***

## 6. Deliverables

### Files to Create

| File                                                                                                       | Purpose                                                                    | Est. Lines |
| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase06-session04-collaborative-cockpit-ux-and-remote-context/implementation-notes.md` | Implementation evidence, command results, UX decisions, and residual risks | \~120      |
| `.spec_system/specs/phase06-session04-collaborative-cockpit-ux-and-remote-context/security-compliance.md`  | Session security, privacy, accessibility, and external-transfer review     | \~100      |

### Files to Modify

| File                                                               | Changes                                                                                                                              | Est. Lines |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `apps/web/src/lib/warRoomUi.ts`                                    | Refine lifecycle, authority, role, notice, remote-context, and failure copy                                                          | \~120      |
| `apps/web/src/lib/warRoomPresence.ts`                              | Refine roster and approval rows for role labels, disabled reasons, accessible labels, and deterministic ordering                     | \~120      |
| `apps/web/src/lib/warRoomFederation.ts`                            | Refine safe summary descriptions, room-notice affordance helpers, and remote context pruning labels                                  | \~120      |
| `apps/web/src/store/useWarRoomStore.ts`                            | Harden duplicate guards, revalidation, authority failure handling, remote-context clearing, notice sends, and leave/reset boundaries | \~220      |
| `apps/web/src/components/WarRoomPanel.tsx`                         | Render clearer lifecycle, authority, remote-context, diagnostics, approval, roster, reconnect, leave, and reset UX                   | \~260      |
| `apps/web/src/components/WarRoomApprovalQueue.tsx`                 | Tighten decision failure copy, in-flight states, disabled state labels, and focus-safe controls                                      | \~100      |
| `apps/web/src/components/WarRoomRoster.tsx`                        | Tighten participant role/status display and accessible labels without color-only meaning                                             | \~100      |
| `apps/web/src/components/battlefield/RemoteParticipantOverlay.tsx` | Keep remote participant markers visually separate and accessible without mutating local selection                                    | \~100      |
| `apps/web/tests/warRoomPresence.test.ts`                           | Cover roster, approval, role, disabled, local marker, and reconnect copy behavior                                                    | \~120      |
| `apps/web/tests/warRoomFederation.test.ts`                         | Cover remote summary, notice helper, pruning, and no sensitive copy behavior                                                         | \~140      |
| `apps/web/tests/warRoomStore.test.ts`                              | Cover duplicate guards, revalidation, authority failures, notice sends, leave/reset cleanup, and remote-context isolation            | \~220      |
| `apps/web/tests/WarRoomPanel.test.tsx`                             | Cover visible collaboration states, safe summaries, accessibility labels, and no hosted-identity wording                             | \~220      |
| `apps/web/tests/WarRoomBattlefieldOverlay.test.tsx`                | Cover remote overlay separation from local hero selection, replay, and export state                                                  | \~100      |
| `tests/e2e/app.e2e.ts`                                             | Extend retained desktop/mobile app evidence for role, remote-context, reconnect, unavailable, and leave states                       | \~120      |
| `apps/web/README_web.md`                                           | Document shipped Session 04 collaboration UX, remote-context separation, duplicate guards, and deferrals                             | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Users can understand who is connected, what role they have, what remote context is visible, and what remains local-only.
* [ ] Collaboration controls are reachable and understandable for keyboard, pointer, and screen-reader workflows.
* [ ] Remote context is visibly collaborative but does not mutate local hero, mission, queue, guarded-action, replay, export, notification, settings, adapter, scan, archive, memory, media, diagnostic, log, backup, or identity state.
* [ ] Approve, reject, reconnect, disconnect, leave, reset, room notice, and federation-send actions guard duplicate triggers while in flight.
* [ ] Error, unavailable, rejected, stale, duplicate, non-leader, authority, reconnect, catch-up, and Worker diagnostic states show bounded feedback without raw payloads.
* [ ] UI and docs do not imply hosted identity, hosted storage, analytics, public replay hosting, remote execution, mobile certification, production-hosted validation, or trusted erasure.

### Testing Requirements

* [ ] Unit tests cover helper copy, remote summaries, roster rows, approval rows, and no sensitive payload wording.
* [ ] Store tests cover duplicate guards, stale-state revalidation, authority failures, leave/reset cleanup, remote-context isolation, and safe notice send behavior.
* [ ] Component tests cover visible lifecycle, role, remote-context, diagnostics, approval, roster, reconnect, leave, and unavailable states.
* [ ] Browser evidence covers desktop and mobile app War Room states changed by this session.
* [ ] Manual implementation notes record command results and residual risks.

### Non-Functional Requirements

* [ ] Core local cockpit workflows remain usable without a Worker URL, Cloudflare credentials, hosted account, hosted storage, analytics, or public replay hosting.
* [ ] Visible summaries remain compact, deterministic, and free of raw local data categories blocked by the Phase 06 baseline.
* [ ] Changed UI regions avoid clipped labels, color-only meaning, focus traps, blank panels, and incoherent overlap on supported desktop and mobile browser widths.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] `npm --workspace @factionos/web run typecheck` passes.
* [ ] Focused web War Room Vitest coverage passes.
* [ ] Relevant Playwright app evidence is retained.
* [ ] `git diff --check` passes.

***

## 8. Implementation Notes

### Key Considerations

* Treat participant names, colors, roles, and online flags as display metadata, not hosted identity or account proof.
* Keep safe remote context useful but constrained to allowed summaries and overlays. Do not expose raw event payloads.
* Keep leave and reset language precise: they clear this browser's room context only.
* Use existing component and store patterns instead of adding a new state management layer.

### Potential Challenges

* Dense War Room controls can overflow on mobile: Use wrapping, stable control groups, and tests that verify labels remain readable.
* Remote context already appears in multiple surfaces: Keep the store, battlefield overlay, panel summary, replay, and export boundaries aligned.
* Authority failures can be subtle: Map each failure to visible status while preserving compact error copy and avoiding token or request echo.

### Relevant Considerations

* \[P05] **Unified erasure still missing**: Leave, reset, disconnect, and local cleanup must not claim trusted erasure for Worker storage, browser hints, archives, logs, exports, replay buffers, backups, settings, or future hosted data.
* \[P05-apps/warroom+apps/web] **War Room federation is optional and redacted**: The web UI must keep Worker transfer optional, bounded, and separate from local cockpit truth.
* \[P05] **Redaction is boundary-specific**: Worker-safe summaries must not be treated as safe for replay, export, archive, adapters, logs, backups, analytics, or public sharing.
* \[P02-apps/web] **Responsive and accessibility debt**: Changed controls need accessible labels, visible focus, reduced-motion-compatible feedback, text fit, and no-overlap behavior.
* \[P03] **Local-first boundary is architectural**: The cockpit must degrade cleanly without Worker URL, hosted services, public tokens, provider credentials, analytics, or remote relays.
* \[P05] **Do not call Worker leave or reset trusted erasure**: Browser leave and reset clear local room context only.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Remote context could accidentally mutate or appear equivalent to local hero, mission, queue, replay, export, notification, settings, adapter, scan, archive, memory, media, diagnostic, log, backup, or identity truth.
* Duplicate action clicks could approve, reject, reconnect, disconnect, leave, reset, or send room notices more than once while a request is pending.
* Failure copy could imply hosted identity, hosted storage, analytics, public replay hosting, remote execution, production-hosted validation, mobile certification, or trusted erasure.
* Dense collaboration UI could lose focus, clip labels, overlap controls, or hide critical states on narrow viewports.

***

## 9. Testing Strategy

### Unit Tests

* `warRoomUi`, `warRoomPresence`, and `warRoomFederation` tests for safe copy, role labels, disabled reasons, summary counts, notice helpers, and sensitive text exclusions.
* `useWarRoomStore` tests for duplicate guards, stale-state cleanup, authority failure handling, notice sends, reconnect, leave, reset, and remote-context isolation.

### Integration Tests

* `WarRoomPanel` component tests for local-only, diagnostics, authority, leader, member, observer, pending, rejected, unavailable, reconnecting, disconnected, left, caught-up, remote-context, approval, and roster states.
* `WarRoomBattlefieldOverlay` tests for visible remote markers that do not alter local selection, replay persistence, or export requests.

### Manual Testing

* Run focused web tests, package typecheck, and relevant app Playwright desktop and mobile projects with mocked Worker states.
* Review retained screenshots for visible state, label fit, no incoherent overlap, and no hosted/execution/erasure claims.

### Edge Cases

* Missing Worker URL, invalid URL, Worker offline, timeout, rate-limited, bad-response, malformed socket frame, failed socket upgrade, room not found, room full, stale approval, duplicate decision, non-leader decision, rejected join, expired authority, mismatched authority, replayed authority, reconnect exhaustion, catch-up unavailable, and safe notice send failure.
* Long participant names, long room codes, long error messages, reduced-motion settings, storage hydration, Worker URL change, browser refresh, leave, reset, and absent remote participants.

***

## 10. Dependencies

### External Libraries

* No new external libraries planned.
* Existing dependencies: React 18.3, Zustand 4.5, TypeScript 5.9, Vite 6.4, Tailwind, Vitest, Testing Library, and Playwright.

### 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`.
* **Depended by**: `phase06-session06-mobile-cockpit-and-accessibility-hardening`, `phase06-session07-collaboration-isolation-and-mobile-validation-closeout`.
* **Related**: `phase06-session05-isolation-boundary-and-sandbox-diagnostics` must preserve the same non-execution and unavailable-state boundaries.

***

## 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-session04-collaborative-cockpit-ux-and-remote-context/spec.md?ask=<question>&goal=<endgoal>
```

`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.