Make the Brain the Chat's living background; float components on legibility-floored Glass

[kateebonner]

Important

Problem

The amico Brain — the live, data-true map of a session's thought — renders today as one strip inside the message timeline: a single row among many, easy to scroll past, competing with messages instead of framing them. It should be the room, not a row.

Approach

Promote the Brain to the permanent full-bleed background of the Chat (Landing, conversation, composer), with every chat component floating on frosted Glass. Legibility is guaranteed by construction — a high constant blur for calm plus a contrast-floored tint for readability — so "movement comes through" and "highly legible" both hold. Reuse the de-risked native Brain engine + glass-token plumbing; build the design fresh.

Approaches Considered

• Inline strip (today) — Brain as a timeline row. Rejected: one element among many, not the room.
• One calm reading lane — Brain only in the margins, conversation on a single sheet. Rejected: motion in the gaps between floating cards already delivers "movement comes through" without costing legibility.
• Everything floats on Glass (chosen) — per-component frosted cards over a full-bleed Brain; motion shows in every gap.
• Dynamic contrast glass — per-frame backdrop sampling to adapt tint. Rejected: biggest perf risk; AA hard to prove per frame.
• Quiet zone behind cards — per-card masking to dim the Brain under each card. Rejected: engine complexity for translucency the gaps already give.
• Breathing skeleton atlas at rest — full latent graph, dim. Rejected for the sparse seed: calmer, more literal.

Scope

In: Brain as the Chat background (Landing + conversation + composer); two-tint AA-floored Glass on all chat components; data-true adaptive-heartbeat motion with a sparse-seed at-rest state; both themes; retiring the inline brain strip; laptop-webview 60fps perf gate with a motion-ease fallback.
Out: Rail / titlebar / Panels (stay solid — nav chrome must be rock-solid, dense lists shouldn't fight a moving background); cross-session Brain persistence (a fresh session opens nearly empty); the home dashboard (already retired, ADR 0001).

Assumptions / Open Qs

• The native Brain engine + glass-token generator + mount wiring from the unpushed kate/chat-brain-atmosphere branch are reusable as-is (design-neutral). To confirm on first slice.
• The "hold merges" freeze tied to the 2026-07-16 client demo is clear (8+ days past) — confirm before opening the PR.
• Exact blur radius and the two tint opacities are derived, not guessed — set to clear AA with a small safety margin over the reference frame during implementation.

---

Acceptance Criteria

• On the Landing and in-session, the Brain fills the entire Chat behind every component; the Rail, titlebar, and Panels stay solid. Switching the titlebar session tab swaps the Brain to that session's graph.
• Every chat component (bubbles, prose, composer, code, diffs, run-plots) floats on Glass; there is exactly one Brain render loop. The inline timeline strip is gone (its expand/collapse toggle obviated — no node interactivity existed); the timeline keeps its existing working-indicator shimmer (cycling gerund + live elapsed).
• Contrast, standard tint: body text clears ≥4.5:1 with a small safety margin over the reference frame — a synthetic Brain at peak bloom whose sampled backdrop is the brightest palette value the Brain actually paints in that theme (peak #fff676 on dark; peak #8f8000 on light — the light Brain never paints #fff676, so validating against it there would derive a near-transparent tint that silently fails over the real light frame) — in each shipped chat theme (light + dark ship day one). Measured against that fixture, not eyeballed.
• Contrast, dense tint: code/diff text clears ≥4.5:1 and graphical marks (syntax colors, diff fills, plot lines) clear ≥3:1 (WCAG 1.4.11) over the reference frame, each shipped chat theme.
• Theme switch: changing the chat theme mid-session re-keys the Glass to that theme's pinned tint set and re-satisfies both contrast criteria. The tint follows the chat theme (default oc-2), not the app-shell theme.
• The Brain is data-true (nodes light up on real file/tool/vault activity) with an adaptive heartbeat: lively when working, ~8fps breathing at rest, hard-pause when hidden or under prefers-reduced-motion. It densifies in place within the fixed viewport, bounded by a node cap / recency window so a long thread grows neither the graph nor per-frame cost without limit.
• At rest the Brain shows a sparse seed; a fresh session opens nearly empty and grows only from that session's activity (no cross-session persistence).
• Perf gate: on the reference laptop VS Code webview (battery-powered, pinned before the gate runs), p95 frame time ≤ 16.7 ms with zero frames > 33 ms, over a ≥10 s continuous scroll of a long thread (≥40 cards) at full Brain tempo, in both themes. Verified by manual sign-off on that machine; a headless-Chromium rAF trace is a pre-gate proxy only. When the gate can't hold, the motion-ease fallback engages (see Key Decisions) and blur fidelity is preserved.

Key Decisions

• Blur vs. tint split: blur is high + constant (calm, cheap); the tint carries contrast, opacity pinned to clear the AA floor with a small safety margin over the reference frame. Blur alone never guarantees legibility.
• Two tints, chat-theme-keyed: standard (prose, bubbles, composer) and dense (code, diffs, run-plots, more opaque). The set follows the chat's own theme (default oc-2), independent of the app-shell theme.
• Perf priority (pre-agreed, non-negotiable mid-build): protect the frosted look. A frame-time monitor eases Brain motion when p95 stays over budget for a sustained window (with hysteresis before restoring, to avoid oscillation); the terminal valve — if easing motion to a full stop still misses budget — is a hard-pause to a static blurred field. Blur fidelity is never degraded; full blur + full motion always at rest.
• Build by reuse on a fresh branch (kate/chat-brain-background off local/amicode): reuse the native engine + token generator + mount wiring, fresh design layer, no iframe.
• Fixed backdrop, bounded growth: the Brain is viewport-anchored (cards scroll over a stationary Brain); the session graph densifies in place, bounded by a node cap / recency window.

Constraints & Invariants

• The standard tint cannot be made ultra-transparent — its opacity is bounded below by the contrast floor (the exact failure the earlier build hit); muted/secondary text rides the dense tint or a locally-dimmed zone.
• Amicode design-system law still applies to the chrome (single yellow, black-on-yellow / yellow-on-dark, geometry tokens). The Brain graph itself is exempt (it may use its categorical palette; #fff676 reserved for live thought).
• Browser-first iteration (vite dev on packages/app), not VSIX rebuilds.
• npm run lint clean + app typechecks before the PR.

Risks

• Perf (primary): high-radius backdrop-blur recomputed per frame over an animating canvas, across many cards, while scrolling, is the expensive combination and exceeds what the earlier build measured (moderate blur). Mitigation: the pre-agreed motion-ease fallback + a real laptop-webview gate (headless Chromium is only a proxy).
• Legibility regression: derived tints must be re-validated against the reference frame in each shipped chat theme; a too-transparent tint silently fails AA. Mitigation: contrast is a tested acceptance criterion, not a visual judgment.

Prior Art / Patterns

- The unpushed `kate/chat-brain-atmosphere` branch (6 commits) is the reference build: native Brain engine port, glass-token generator, chat-wide mount, and a passing headless perf gate. Reuse its plumbing; discard its design layer (per-bubble tiers, breathing skeleton atlas). - The shipped native Brain engine already lives on `local/amicode` (the `/brain.html` iframe was retired). - Follow the chat-first shell (Landing/Chat/Rail/Panel vocabulary) and the amicode design-system tokens for all chrome.

Source

• Durable record: ADR packages/app/docs/adr/0002-brain-as-chat-background.md (this issue implements it); shell vocabulary in packages/app/CONTEXT.md (Brain, Glass).
• Supersedes the design direction of the unpushed kate/chat-brain-atmosphere branch (per-bubble tiers + skeleton atlas).

Notes

Large enough to decompose into vertical slices (mount → glass tokens → float components → motion/at-rest → perf gate → lint/PR) via break-into-subissues once published.

[kateebonner]

Decomposed into vertical slices (tracer bullets), TDD-ready:

• Mount the Brain chat-wide and absorb the inline brain strip #59 — Mount the Brain chat-wide and absorb the inline brain strip (afk)
• Derive two AA-floored, chat-theme-keyed Glass tint tiers with a contrast test #60 — Derive two AA-floored, chat-theme-keyed Glass tint tiers with a contrast test (afk)
• Float chat components on the two Glass tiers (standard prose/bubbles/composer, dense code/diffs/plots/tools) #61 — Float chat components on the two Glass tiers (afk, blocked by Mount the Brain chat-wide and absorb the inline brain strip #59 Derive two AA-floored, chat-theme-keyed Glass tint tiers with a contrast test #60)
• Drive the Brain by session activity: adaptive heartbeat, sparse-seed rest, bounded in-place growth #62 — Drive the Brain by session activity: adaptive heartbeat, sparse-seed rest, bounded growth (afk, blocked by Mount the Brain chat-wide and absorb the inline brain strip #59)
• Add the perf governor (ease motion, never blur) and gate 60fps on the reference laptop #63 — Add the perf governor (ease motion, never blur) + 60fps gate on the reference laptop (hitl, blocked by Float chat components on the two Glass tiers (standard prose/bubbles/composer, dense code/diffs/plots/tools) #61 Drive the Brain by session activity: adaptive heartbeat, sparse-seed rest, bounded in-place growth #62)

DAG: #59 and #60 are independent roots → #61 ← {#59, #60}; #62 ← #59; #63 ← {#61, #62}. Durable record: ADR 0002 (PR #58). Note: the contrast reference frame is per-theme (peak #fff676 dark / #8f8000 light) — AC above and ADR wording reconciled to match.

🤖 Generated with Claude Code