Chat window UX (scrolling, gestures, search, mic) — MVP workstream

[lalalune]

This is the coordination thread for the chat-window UX workstream of the LifeOps Personal Assistant MVP (GitHub project 15). Chat is the MVP's primary surface — every LifeOps flow (reminders, goals, todos, scheduling, coordination, elderly check-ins) is driven through the continuous chat overlay. Its scrolling, gesture, search, and voice affordances have to be solid for every kind of user (children, adults with ADHD/ADD/Asperger's/autism, neurotypical adults, business users, elderly people) with no therapy language and no special rails — just a chat window that never fights the hand that drives it.

Research doc (read it in full before claiming work): packages/docs/ongoing-development/research/05-chat-window-ux.md.

Headline: this is fix-and-verify, not build

The gesture/detent system the brief asks for is already built, documented, and CI-gated:

• Pull-to-maximize landed in chat: single infinite thread — remove chat-to-chat swipe, new-chat/reset & maximize buttons; pull-up-to-maximize / top-20%-pull-down-to-restore #13531 — the maximize button is already gone; pulling the sheet above ~80% of viewport maximizes it, and a downward pull starting in the top 20% restores it. Do not reintroduce a maximize button.
• Detent physics are the spec: HALF at 0.46×vh, FULL at ~0.9×vh (inset), release-within-64px magnet-snaps to a detent else free-rests, 120px pill→input morph, sheet spring (stiffness 320 / damping 34 / mass 0.9), pill-open spring (300/26/0.85), Capacitor light-impact haptic per detent cross. Smoothness is lerp-on-drag + spring-on-release; the live drag writes flexBasis directly with no per-frame React re-render.
• Pill/grabber already pulse when the mic is hot; scroll chain, iOS momentum, and WebKit bounded-height are all e2e-gated.

So the job is: protect the gesture system, and fix the narrow set of things that are actually missing or broken. Prefer deleting/wiring/repairing what exists over adding.

Doctrine & decisions adopted

• One infinite thread. No conversation switcher, no clear/new-chat, no swipe-to-clear (all removed in chat: single infinite thread — remove chat-to-chat swipe, new-chat/reset & maximize buttons; pull-up-to-maximize / top-20%-pull-down-to-restore #13531). Search becomes the sanctioned way to reach an older thread.
• No side panels, no suggestion chips, uniform top bar. Search therefore lives inside the sheet (a header affordance visible at half+), not as a sidebar. SHOW_PROMPT_SUGGESTIONS stays off.
• Never fight the scroll. The transcript is vertical-only; wide content scrolls inside its own row (overflow-x-auto overscroll-x-contain), never by turning the thread into a two-axis scroller.
• Minimal UI, no card chrome. Orange accent only, no blue anywhere. Pulse animations reuse the existing animate-pulse + motion-reduce:animate-none pattern.
• Fail fast, no fallback sludge. "Not loaded" must never render as "empty": loading / designed-empty / error are three distinguishable states. No caught-error-returns-default. Logger not console; strong types.
• Pull-gesture mechanics constraint (important for anyone touching scroller gestures): a pull gesture attached to a touch-action: pan-y scroller must use touch events + a non-passive preventDefault, because compositor scrolling pointercancels pointer-based gestures on such an element. The grabber stays the single drag authority — do not add a new pull gesture on the transcript itself for MVP.
• Out of scope: ChatSurface/kiosk/detached-window feature work (parity contract only — do not consolidate the three render paths), thread virtualization, framer-motion replacement, cross-conversation UI beyond search-jump, semantic/vector search (keyword ILIKE + BM25 is enough).

Issues (most important first)

1. [chat-ux] Lock the chat transcript to vertical-only scrolling (P0) — add overflow-x-hidden to #continuous-thread; audit overflowing children; wheel/deltaX regression e2e.
2. [chat-ux] Infinite scroll up: async history pagination in the continuous chat overlay (P0) — ?before=<id> server cursor, client prepend with manual scroll-anchor, sliding render window, perf-gate verified.
3. [chat-ux] Wire message search into the primary chat surface (P1) — header affordance reusing the already-injectable MessageSearchPanel + around-window jump; active-thread scope first.
4. [chat-ux] Mic button pulses while recording; normalize composer icon optics (P1) — pulse the overlay mic on the recording predicate; balance 26/30px icon optics; keep 44×44 targets; add the missing pill-pulse regression test.
5. [chat-ux] Remove stale gesture specs and dead gesture options left behind by the one-infinite-thread change (P1) — delete/rewrite chat-full-clear/chat-full-maximize consumers, the dead verticalScrollPriority option, and filler class strings.
6. [chat-ux] Triage the perf-gate CLS failure and guard long-thread scroll performance (P2) — root-cause the 0.80 CLS red honestly; add row containment only if pagination regresses the budget.

Suggested order: land #1 (smallest change, biggest feel win) and #2 together (both P0, and #2's render windowing depends on the scroller being axis-locked). #3/#4/#5 are independent and parallelizable. #6 pairs with #2 — do the CLS triage, and only reach for containment if #2's longer threads regress the frame budget.

How to claim work

1. Comment on the issue you're taking (one issue per agent; call it out here too so we don't collide).
2. Move the issue's card to In Progress on project 15.
3. Branch fix/<slug> or feat/<slug> off develop; sync before opening/updating the PR (git fetch origin && git rebase origin/develop, resolve every conflict, bun install, bun run verify).
4. Every behavior change ships a regression test — that is a hard requirement for this workstream (the gesture system is fragile and CI-gated; new work must ride the existing chat-shell-gestures.yml gates so nothing slows the drag path).

Evidence rules (post INLINE in the GitHub issue/PR — the committed .github/issue-evidence approach is retired)

• MP4 walkthrough of the whole flow (MP4 renders inline in GitHub; use it, not a link to elsewhere).
• JPG before + after full-page screenshots, desktop AND mobile — and for a bug, the before shot must show the WRONG behavior (sideways-panning thread, static mic while recording, scroll-up dead-end).
• Backend structured logs ([ClassName] …) and frontend console + network logs showing the real code path firing.
• Real-LLM / real-server trajectory where agent/route behavior is exercised (search route, pagination cursor); mark N/A with a reason where it genuinely does not apply (pure cleanup/CI issues).
• Prefer JPG over PNG for screenshots; MP4 for video. No mock-mounted smoke — drive the real path.

Filed issues

• [chat-ux] Lock the chat transcript to vertical-only scrolling #14328 — P0 [chat-ux] Lock the chat transcript to vertical-only scrolling
• [chat-ux] Infinite scroll up: async history pagination in the continuous chat overlay #14329 — P0 [chat-ux] Infinite scroll up: async history pagination in the continuous chat overlay
• [chat-ux] Wire message search into the primary chat surface #14330 — P1 [chat-ux] Wire message search into the primary chat surface
• [chat-ux] Mic button pulses while recording; normalize composer icon optics #14331 — P1 [chat-ux] Mic button pulses while recording; normalize composer icon optics
• [chat-ux] Remove stale gesture specs and dead gesture options left behind by the one-infinite-thread change #14332 — P1 [chat-ux] Remove stale gesture specs and dead gesture options left behind by the one-infinite-thread change
• [chat-ux] Triage the perf-gate CLS failure and guard long-thread scroll performance #14333 — P2 [chat-ux] Triage the perf-gate CLS failure and guard long-thread scroll performance

---

Design doc · MVP board