cocottetech/@platform/codebase/@features/ai-copilot/docs/chat-home.screen.md

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 — 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 — surface-level spec (this is the implementation-level companion).
• Brief H §H1 — fleet status + receipt patterns.
• Brief L §L2 — specialist switching, mentions, fleet strip.
• Brief M §M2 — degradation banners.
• Brief F — color, motion, haptic specs.
• voice.brief.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).