# chat-home.screen

Single-screen breakdown for the **chat-home** surface — Quinn's daily-driver landing screen. Anchors briefs A (chat surface), H1 (fleet status strip), L (specialist mentions), M (degradation banners), I (digest entry on first-of-day open).

## Layout (iPhone 17 logical 393×852)

```
┌─────────────────────────────────────────────────┐
│ ◄ status bar (system)                           │ 47pt
├─────────────────────────────────────────────────┤
│ [≡]  ai-copilot ▼      [🔍]  [⌥]               │ 56pt — top bar
│        ↑ specialist switcher                    │
├─────────────────────────────────────────────────┤
│ [ai-copilot 12·🟢] [triage 47·🟡] [bookings-... │ 36pt — fleet status strip (H/L)
│  · 6·🟢] [content-of 3·🟢]              [⊞]   │   horizontal scroll; ⊞ = "all"
├─────────────────────────────────────────────────┤
│                                                 │
│ ┌───────────────────────────────────────────┐   │ ambient receipt
│ │ Bumped Tryst at 11:02. Next at 3:02.  ↶  │   │ (hearth voice, swipe-undo)
│ └───────────────────────────────────────────┘   │
│                                                 │
│ ┌───────────────────────────────────────────┐   │ approval card inline
│ │ ▢ New about-me for Tryst                  │   │ (working voice)
│ │   "—corporate" line removed               │   │
│ │   [Edit] [Approve] [Set aside]            │   │ swipe-right = approve
│ └───────────────────────────────────────────┘   │
│                                                 │
│ Quinn: pause tryst for an hour                  │ user bubble (right-aligned)
│                                                 │
│ Cocotte: Paused til 12:43.                     │ ai bubble (left-aligned)
│   On the back burner.                          │
│                                                 │
├─────────────────────────────────────────────────┤
│ ╭─────────────────────────────╮ [🎤] [📷]      │ 56pt — composer
│ │ Tell Cocotte…                │                │
│ ╰─────────────────────────────╯ long-press = ☎ │
└─────────────────────────────────────────────────┘
                                                  │ 34pt — home indicator
```

## Components (in z-order, top to bottom)

| Component | Brief ref | Notes |
|---|---|---|
| Top-bar | A §navigation | `[≡]` opens drawers (B); active-specialist label is tappable dropdown (L §L2d) opening recent-specialists scroller; `[🔍]` = global search across threads + audit; `[⌥]` = overflow (settings, coop drawer N, kill switch K) |
| Fleet status strip | L §L2c, H §H1 | One pill per active specialist with 24h-activity count + color dot (🟢 idle, 🟡 working, 🔴 needs attention). Horizontal scroll. `[⊞]` end-cap opens full fleet drawer (B6). |
| Degradation banner (conditional, full-width) | M §M2b, M §M2c | Above receipts when offline / backend-degraded / SSO-expired. Plain register copy. Tap = action (re-auth, retry, view audit). |
| Receipt bubble | H §H1, voice §V2a hearth | Past auto-action; left-aligned, no avatar, italic-ish weight, swipe-right = undo, swipe-left = view detail. |
| Approval card inline | A §approval, H §H2/H4, voice §V2b working | Stakes color band on left edge per F §F1. Body has primary content + 3 actions. Right-swipe to approve (haptic on threshold per F §F4). Left-swipe to set aside. Long-press = card detail sheet. |
| User bubble | A §states | Right-aligned, accent-tinted, plain text. Editable for 30s after send (long-press → edit). |
| AI bubble | A §states | Left-aligned, no tint, with specialist signature footer when specialist ≠ ai-copilot ("— the strategist"). Streaming token reveal per F §F4. |
| Composer | A §multimodal | Text field with placeholder rotating per state (per States below). `[🎤]` short-tap = voice input (push-to-talk); long-press `[🎤]` = hands-free cook-mode. `[📷]` opens camera-or-library picker; drag-drop into field also accepted. |
| Home indicator | system | Native iOS bottom safe area. |

## States

1. **First-run / empty** — A §empty. No receipts, no cards, no fleet activity. Centered prompt: "Welcome. Tell Cocotte what you tend to." Composer placeholder: "Try: tell me about yourself." Routes to D persona-seed interview.
2. **Quiet morning** — fleet idle, 0–1 receipts, no pending approvals. Composer placeholder: "Ready when you are." Daily-digest entry pinned at top per I §morning-digest (collapsible card summarizing yesterday).
3. **Active day** — multiple receipts + 1–3 inline approvals + ongoing conversation. Default state.
3a. **Multi-message turn assembling** (A §state 2b) — Quinn just sent N messages within the silence window (2.5s text / 1.5s voice). Visual: thin pulsing dot under the last user bubble ("· composing turn…"). "Send now" `↗` affordance appears next to composer; tap fires the turn immediately. Multi-message bubbles render visually grouped (no avatar between, tighter vertical spacing) so the reader sees them as one thought.
4. **Streaming reply** — Cocotte bubble currently being written; tokens stagger-fade per F §F4. Composer disabled during stream; allow interrupt via top-right `✕` mini-button.
4a. **Interrupted streaming reply** (A §state 2c) — Quinn sent a new message mid-stream. Existing partial reply gets a small "ai-copilot stopped here · your turn" marker (plain register per voice §V2c — never talk over the user). New turn assembles per state 3a if multi-message; otherwise streams normally after the debounce window.
5. **Awaiting approval** — ≥1 high-stakes approval card pinned to bottom-above-composer until acted. Subtle pulse on left-edge stakes band.
6. **Pending count overflow** — ≥6 pending approvals: top banner "6 things waiting" → tap routes to pending-approvals drawer (B inbox). Inline shows only the top 3.
7. **Cook-mode active (voice-led)** — A §voice. Composer collapses to a single mic-pulse; chat continues; voice input is the primary interaction. Tap mic to exit.
8. **Direct specialist conversation** — L §L2b. Top-bar specialist label shows specialist + back-chevron to `ai-copilot`. AI bubbles styled with specialist's voice lean badge. History scoped to this specialist.
9. **Soft degradation** — M §M2a. Affected specialist pill is red-dot; opening that specialist's drawer shows the inline banner. Other surfaces unaffected.
10. **Backend degradation** — M §M2b. Top banner (yellow): "Cocotte can't reach her memory. Drafts you make will save when she's back." Composer remains usable; mutations queue.
11. **Device offline** — M §M2c. Top banner (grey): "Offline. Drafts sync when you're back." System offline indicator shows too.
12. **Kill-switch engaged** — K §kill-switch. Full-screen takeover with confirmation; cannot return to chat-home until release.

## Interactions / gestures

- **Top-bar specialist label** — single tap toggles dropdown; horizontal swipe on avatar = quick-cycle through recent specialists (L §L2d).
- **Pull-to-refresh** — re-pulls pending state from `platform.api`; surfaces newly-arrived approvals at the top.
- **Long-press on receipt bubble** — opens row-detail sheet (per I §3 audit detail). Tap is no-op (receipts are passive).
- **Right-swipe on approval card** — approve with haptic threshold and success haptic on commit. Animation: card slides off-right, replaced by "✓ approved" receipt bubble that itself can be swiped-undo for 30s.
- **Left-swipe on approval card** — set aside (moves to pending-approvals drawer). No animation off; small "set aside" toast.
- **Pinch-zoom anywhere on chat-home** — opens audit drawer (I) zoom-out view of the last 24h. Custom gesture; not standard iOS but well-affordable per F §F4.
- **3-finger tap (accessibility)** — reads current screen state aloud via VoiceOver.

## Edge cases

- **Conflict on resume from offline** — M §M7. A 3-way diff sheet replaces the bottom approval area until conflict resolved. Cannot send new messages while conflict pending (composer disabled with explanation).
- **Specialist mentioned in AI bubble but specialist is currently degraded** — specialist name renders normally; tap shows the specialist drawer in degraded state with M §M2a banner, not an error.
- **Approval card whose target was already actioned by another device** — M §M7 conflict resolution applies; card animates to "✓ already done elsewhere" receipt.
- **VoiceOver active + cook-mode requested** — accessibility wins: cook-mode opens but VoiceOver continues; spoken output uses VoiceOver path, not TTS, to avoid double-narration.
- **Reduced motion on** — replace stream-fade with cross-fade; remove pulse on stakes band; haptic-only feedback on approval swipe.
- **Dynamic Type at XXL** — fleet status strip pills truncate counts to dot-only; receipt bubbles wrap and truncate at 4 lines with "…more"; composer becomes 2-line.
- **Right-to-left locale (future)** — mirror the swipe semantics: left-swipe approves, right-swipe sets aside. Per [Brief AD §AD-Q4](./AD-multilingual-opaque.brief.md) — P5+ ship; forward-compat now.
- **Quinn dictates a phone number into the composer** — A §multimodal post-processing detects PII; offers "save as a private fact" affordance per voice §V6 ("algorithm" is banned-loose; "fact" is favored).
- **An auto-action receipt arrives WHILE user is editing the composer** — receipt inserts above composer with subtle haptic; doesn't steal focus; composer text preserved.
- **Multi-message turn cap reached** (A §state 2b) — Quinn typed continuously for 30s. Composer accepts; ai-copilot fires the turn with what it has at that mark; Quinn's later messages become a new turn. No dropped messages, but the boundary may surprise her. Small "starting turn now" toast on commit.
- **Cards from a coalesced multi-message turn arrive together** — ai-copilot may emit N approval cards from one debounced turn. They render as a tight stack (per `approval-card.screen` interaction model) with a single "starting from your last 3 messages" intro from Cocotte to make the grouping visible.

## Related
- [Brief A](./A-chat-surface.brief.md) — surface-level spec (this is the implementation-level companion).
- [Brief H §H1](./H-recurring-chores.brief.md) — fleet status + receipt patterns.
- [Brief L §L2](./L-specialists-fleet.brief.md) — specialist switching, mentions, fleet strip.
- [Brief M §M2](./M-error-degraded-modes.brief.md) — degradation banners.
- [Brief F](./00-system-visual-system.md) — color, motion, haptic specs.
- [`voice.brief.md`](./00-system-voice.md) — placeholder copy, receipt copy, banner copy.

## Out of scope
- Visual mockup (this is a layout + behavior spec; mockup happens in Figma when the prototype starts).
- iPad / web variants (Brief E covers cross-platform).
- Drawer interior layouts (each drawer gets its own `.screen.md`).