Repository navigation
Make the Brain the Chat's living background; float components on legibility-floored Glass #56
Description
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-atmospherebranch 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
#fff676on dark; peak#8f8000on 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-backgroundofflocal/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;
#fff676reserved for live thought). - Browser-first iteration (vite dev on
packages/app), not VSIX rebuilds. npm run lintclean + 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 inpackages/app/CONTEXT.md(Brain, Glass). - Supersedes the design direction of the unpushed
kate/chat-brain-atmospherebranch (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.
Activity
kateebonner commentedon Jul 25, 2026
Decomposed into vertical slices (tracer bullets), TDD-ready:
afk)afk)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)afk, blocked by Mount the Brain chat-wide and absorb the inline brain strip #59)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
#fff676dark /#8f8000light) — AC above and ADR wording reconciled to match.🤖 Generated with Claude Code
feat(amicode): single-tier frost glass, narrower floating cards, glas…
feat(amicode): Latent Constellation — the landing's rotating 3D at-re…
feat(amicode): live design tuning — max-transparent glass, bottom-doc…