[feat](chat): AI Advisor — context-aware, client-side chatbot (Phase 3)

A grounded, offline, rule-based assistant built on the Adapter Pattern.

Engine/state (decoupled, src/lib/chat/):
- ChatAdapter contract + getChatAdapter() single swap-point; localAdvisorAdapter
  answers from the FROZEN engine + config (answerText() pure, unit-tested) so it
  can never contradict the model or fabricate. Network LLM = drop-in later, zero
  UI change. Streams via AsyncIterable under an AbortSignal.
- buildChatContext(): structuredClone deep-clone + dependency-free validation;
  invalid/partial input → complete moderate baseline (no undefined/crash).
- useChat: throttled submits + ignore-while-streaming (no spam), stop/regenerate/
  abort, hydration-safe persistence, cross-tab reset via BroadcastChannel.

UI (lazy, src/components/chat/):
- ChatFab (lazy) → ChatMount → ChatPanel; memoized bubbles render via the
  existing dependency-free XSS-safe-by-construction markdown renderer, each in a
  per-bubble ErrorBoundary. Smart-scroll (IntersectionObserver, pauses on manual
  scroll-up), streaming caret, Stop/Regenerate, suggestions, full a11y
  (labelled dialog, polite live region, keyboard), EN/ID.

Wiring (anti-regression): FAB mounted GLOBALLY so tab-switch closes the Guide but
never unmounts chat / disrupts a stream; "Start Over" wipes chat + broadcasts.
Bundle: FAB + all chat lazy → INITIAL budget untouched (119.9/120); total 260→268
(documented). Browser-verified: grounded /100 reply, survives nav, reset wipes, EN/ID.

145 unit (+17) + 14 e2e, tsc, lint, all 6 guards green. README Phase 3 section +
Mermaid + adapter integration snippet; DECISIONS records the two reconciliations.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: programmerShinobi

DECISIONS.md

@@ -380,3 +380,35 @@ Both are chosen precisely to preserve the Zero-Mismatch invariant.
   keep surfacing as individual PRs to be evaluated one at a time. This decision is the *evaluation
   outcome* ("not yet"); if Tailwind's footprint grows or a security need appears, revisit as a
   scoped migration (CSS-first config + a full visual/e2e/gate pass) rather than an auto-merge.
+
+## Phase 3 — "AI Advisor" chat (Context-Aware, Client-Side), 2026-07-19
+
+Implements the Phase-3 blueprint while honoring two enforced invariants (building it literally
+would have tripped both — the very regressions the mandate forbids):
+
+- **LLM-agnostic adapter, local implementation (no external API).** The `ChatService` is the
+  Adapter Pattern (`src/lib/chat/`): `getChatAdapter()` is the single swap-point. Today it returns
+  the **local, offline, rule-based `localAdvisorAdapter`** — grounded in the *frozen engine* + the
+  same config the app renders (`answerText()` is pure + unit-tested), so the chat can never
+  contradict the model or fabricate a fact. Keeps the product's core promise (100% client-side,
+  free, offline, no keys, no telemetry) intact. A network LLM is a drop-in: implement `ChatAdapter`
+  and return it from that one function — **zero** UI/hook/state changes. "AI Advisor" is the
+  product name; the UI says "computed from the model, not a language model."
+- **Dependency-free rich rendering (no react-markdown / DOMPurify / Mermaid / Zod).** Bubbles use
+  the existing `lib/markdown.tsx` (React elements, **never** `dangerouslySetInnerHTML`) — XSS-safe
+  *by construction*, a stronger guarantee than sanitizing an HTML string, and adds no dep. A
+  per-bubble `ChatErrorBoundary` is the belt-and-braces. Context is validated by a small runtime
+  guard (the repo's no-Zod stance), not a schema library.
+- **Bundle: initial budget UNTOUCHED.** The FAB **and** everything behind it are `lazy()` — initial
+  JS stays 119.9 kB / 120 kB. Only the lazy chunk grew the total; budget raised 260 → 268
+  (documented in `check-bundle-size.mjs`), well under the 300 kB NFR cap.
+- **State safety (Phase 3.1).** `buildChatContext()` **deep-clones** (`structuredClone`) the live
+  pipeline payload so chat can never mutate app state, and falls back to a complete moderate
+  baseline on invalid/partial input (no `undefined`/null-pointer). `useChat` **throttles** submits +
+  ignores sends while streaming (no compute/API spam), streams via an `AbortSignal`
+  (stop/regenerate/unmount cancel cleanly), and persists messages (hydration-safe: pure client SPA,
+  no SSR step to mismatch).
+- **Anti-contamination + harmony (Phase 2.2/3.1).** "Start Over" wipes chat state + persistence and
+  **BroadcastChannels a reset** so other tabs clear silently. The FAB mounts **globally** (never
+  per-view), so switching tabs closes the Guide but **never** unmounts the chat or disrupts an
+  active stream. Verified in-browser: reply grounded to `/100`, survives nav, reset wipes, EN/ID.

README.md

@@ -120,6 +120,40 @@ flowchart LR
 - **④ Strategic output** — the recommendation with a trade-off radar, sensitivity, anti-pattern
   warnings and migration paths; export an ADR (MADR), a full report, CSV/JSON, or a share link.
 
+## AI Advisor chat (Phase 3)
+
+A floating **AI Advisor** (bottom-right) answers questions grounded in *your* scenario —
+"what do you recommend?", "what is microservices?", "monolith vs microservices", "why?". It is a
+**client-side, offline, rule-based** assistant computed from the frozen engine + the same config
+the app renders, so it can never contradict the model or fabricate a fact (the UI says
+*"computed from the model, not a language model"*). It is built on the **Adapter Pattern**, so a
+network LLM is a drop-in later with zero UI changes.
+
+```mermaid
+flowchart LR
+  U["User message"] --> H["useChat hook<br/>(throttle · abort · persist)"]
+  CTX["Live pipeline state"] -->|"buildChatContext()<br/>deep-clone + validate"| H
+  H --> A["getChatAdapter()<br/><b>ChatService (Adapter)</b>"]
+  A --> L["localAdvisorAdapter<br/>(offline, rule-based)"]
+  L -->|"reads"| E["Frozen engine<br/>rank() · contributions()"]
+  L -->|"async stream"| H
+  H --> V["ChatPanel<br/>(memoized bubbles · smart-scroll · a11y)"]
+  R["Start Over"] -.->|"reset + BroadcastChannel"| H
+  A -. "future" .-> N["networkLlmAdapter<br/>(drop-in, same contract)"]
+```
+
+- **Zero-Mismatch handoff** — `buildChatContext()` deep-clones (`structuredClone`) the pipeline
+  payload, so the chat can never mutate the app's scenario; invalid input degrades to a moderate
+  baseline (no `undefined`/crash).
+- **No spam, clean cancel** — submissions are throttled and ignored while streaming; every turn
+  streams under an `AbortSignal` (stop / regenerate / unmount all cancel cleanly).
+- **Anti-contamination** — "Start Over" wipes chat state + persistence and broadcasts a reset so
+  other tabs clear silently. The launcher is mounted **globally**, so switching tabs closes the
+  Guide but never disrupts an active chat stream.
+- **Lean & safe** — the launcher **and** everything behind it are lazy-loaded (initial JS budget
+  untouched); bubbles render with the dependency-free, XSS-safe-by-construction Markdown renderer
+  (React elements, never `dangerouslySetInnerHTML`), each wrapped in a per-bubble error boundary.
+
 ## Run it locally
 
 > **Prerequisite:** Node **24** (LTS) — the version is pinned in [`.nvmrc`](.nvmrc) and used by all
@@ -251,11 +285,37 @@ real pipeline steps) and the total duration short; the component already renders
 `prefers-reduced-motion`. It is triggered by `analysisRun` in `App.tsx`, which increments on an
 explicit analyze action (preset/wizard apply) — never on a live factor edit.
 
+### Swap the chat AI backend (ChatService adapter)
+
+The chat depends only on the `ChatAdapter` contract, so the whole UI/state layer is backend-agnostic.
+`getChatAdapter()` in [`src/lib/chat/index.ts`](src/lib/chat/index.ts) is the **single** swap-point —
+return a different adapter and nothing else changes:
+
+```ts
+// src/lib/chat/types.ts (the contract every backend implements)
+export interface ChatAdapter {
+  readonly id: string;
+  readonly network: boolean; // drives offline UX + resiliency paths
+  reply(history: readonly ChatMessage[], context: ChatContext, signal: AbortSignal): AsyncIterable<ChatChunk>;
+}
+
+// src/lib/chat/index.ts — swap here, zero UI/hook changes:
+export function getChatAdapter(): ChatAdapter {
+  return localAdvisorAdapter;        // today: offline, rule-based, grounded in the frozen engine
+  // return networkLlmAdapter;       // future: a streaming LLM — same contract, drop-in
+}
+```
+
+`buildChatContext()` deep-clones + validates the pipeline payload before it reaches any adapter, so
+a new backend can never mutate app state or receive an `undefined`.
+
 ### Component map (Advisor tab)
 
 | Area | Component | Notes |
 |---|---|---|
 | Scenario gallery + wizard entry | [`components/advisor/PresetBar.tsx`](src/components/advisor/PresetBar.tsx) | search, tag filters, dominant custom card |
+| AI Advisor chat (lazy) | [`components/chat/ChatFab.tsx`](src/components/chat/ChatFab.tsx) · `ChatPanel.tsx` · [`hooks/useChat.ts`](src/hooks/useChat.ts) | launcher + panel + state bridge |
+| Chat service (Adapter) | [`lib/chat/`](src/lib/chat/) | `getChatAdapter()` · `localAdvisorAdapter` · `buildChatContext()` |
 | Custom wizard (lazy modal) | [`components/advisor/CustomWizard.tsx`](src/components/advisor/CustomWizard.tsx) | iterates the wizard config |
 | Wizard → engine bridge (pure) | [`lib/customWizard.ts`](src/lib/customWizard.ts) | `wizardToLevels()` — the only mapping |
 | ① Project factors | [`components/advisor/FactorInputs.tsx`](src/components/advisor/FactorInputs.tsx) · `FactorField.tsx` | 14 factors, per-level examples |

scripts/check-bundle-size.mjs

@@ -17,7 +17,7 @@ import { gzipSync } from 'node:zlib';
 // shared async chunk can't silently be mis-counted. Headroom catches a real regression; raise the
 // budgets deliberately (with a note) if the app grows.
 const JS_INITIAL_BUDGET_KB = 120;
-const JS_TOTAL_BUDGET_KB = 260; // raised 200→260 for full Insights bilingualisation 2026-07-15 (6 datasets + 18 article bodies now carry EN+ID; all in the lazy content chunk — initial budget untouched; NFR cap is 300)
+const JS_TOTAL_BUDGET_KB = 268; // raised 200→260 (Insights bilingualisation 2026-07-15); 260→268 for the Phase 3 AI Advisor chat 2026-07-19 (adapter + hook + panel, all in a LAZY chunk — the FAB is lazy too, so the initial budget is untouched; NFR cap is 300)
 const CSS_BUDGET_KB = 27; // raised 25→27 for Fase 2g UI/UX polish 2026-07-18 (preset dropdown, uniform export buttons, 2×2 step-rail wrap grid, footer stacking, modern app-bar controls); still well under the ~30kB NFR ceiling
 
 const dir = 'dist/assets';

src/App.tsx

@@ -2,6 +2,7 @@ import { lazy, Suspense, useEffect, useMemo, useRef, useState } from 'react';
 import { IconBulb, IconCompass, IconHome } from '@tabler/icons-react';
 import { BrandMark } from './components/chrome/BrandMark';
 import { AuroraBackground } from './components/chrome/AuroraBackground';
+import { resetChatPersistence } from './lib/chat/persist';
 import { MobileChrome } from './components/chrome/MobileChrome';
 import { AdvisorMobileBar } from './components/chrome/AdvisorMobileBar';
 import { LandingView } from './components/landing/LandingView';
@@ -57,6 +58,11 @@ const ManualBook = lazy(() => import('./components/overlays/ManualBook'));
 // the Advisor's initial bundle. The Advisor remains the default view.
 const LearnView = lazy(() => import('./components/insights/LearnView'));
 
+// AI Advisor chat (Phase 3) — lazy so NOTHING chat-related (FAB, panel, hook, adapter, renderer)
+// touches the initial bundle; it loads on first idle. Only `resetChatPersistence` (tiny, engine-free)
+// is imported eagerly, for "Start Over".
+const ChatFab = lazy(() => import('./components/chat/ChatFab'));
+
 type Selections = Partial<Record<DimensionId, string>>;
 
 export default function App() {
@@ -111,6 +117,8 @@ export default function App() {
   const [currentDim, setCurrentDim] = useState<DimensionId>('D1');
   const [migKey, setMigKey] = useState<MigrationKey>('big');
   const undoRef = useRef<{ levels: Levels; selections: Selections; overrides: Overrides } | null>(null);
+  // Registered by the chat panel when open, so "Start Over" can reset it in the same tab.
+  const chatResetRef = useRef<(() => void) | null>(null);
 
   const scenario: ScenarioState = { v: 1, mode, lang, levels, selections, overrides };
   const exportInput: ExportInput = { levels, overrides, selections: effective, lang };
@@ -129,6 +137,10 @@ export default function App() {
   const resetAll = () => {
     undoRef.current = { levels, selections, overrides };
     applyPreset(DEFAULT_LEVELS);
+    // "Start Over" wipes the chat too (anti-contamination, Phase 3.1): in-tab via the registered
+    // reset if the panel was opened, else just the persistence + cross-tab broadcast.
+    if (chatResetRef.current) chatResetRef.current();
+    else resetChatPersistence();
   };
   const undoReset = () => {
     const snap = undoRef.current;
@@ -220,6 +232,11 @@ export default function App() {
   return (
     <>
     <AuroraBackground />
+    {/* AI Advisor chat (Phase 3) — mounted GLOBALLY (never per-view) so navigating tabs closes the
+        Guide but never unmounts the chat or disrupts an active stream (Phase 2.2 harmony). */}
+    <Suspense fallback={null}>
+      <ChatFab contextInput={{ levels, overrides, mode, lang }} registerReset={(fn) => (chatResetRef.current = fn)} />
+    </Suspense>
     <MobileChrome mainView={mainView} onNavigate={navigate} theme={theme} onToggleTheme={toggleTheme} mode={mode} onSetMode={setMode} />
     {mainView === 'advisor' && <AdvisorMobileBar />}
     <div className={'screen-only aa-page' + (mainView === 'advisor' ? ' has-actionbar' : '')}>

src/components/chat/ChatErrorBoundary.tsx

@@ -0,0 +1,33 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+
+// Per-bubble crash isolation (Blueprint Phase 2.2). If a single message fails to render (e.g. a
+// future LLM emits markup the renderer chokes on), THIS boundary shows a localized fallback in that
+// one bubble — the chat and the whole app keep running. Local markdown is React-elements-only so it
+// can't inject HTML; the boundary is the belt-and-braces for any future rich renderer.
+interface Props {
+  fallback: ReactNode;
+  children: ReactNode;
+}
+interface State {
+  failed: boolean;
+}
+
+export class ChatErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { failed: false };
+  }
+
+  static getDerivedStateFromError(): State {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    // Non-fatal: keep a console breadcrumb for debugging without surfacing a global crash.
+    if (import.meta.env.DEV) console.warn('[chat] message render failed', error, info);
+  }
+
+  render(): ReactNode {
+    return this.state.failed ? this.props.fallback : this.props.children;
+  }
+}

src/components/chat/ChatFab.tsx

@@ -0,0 +1,64 @@
+import { lazy, Suspense, useEffect, useRef, useState } from 'react';
+import { IconMessageChatbot, IconX } from '@tabler/icons-react';
+import { useI18n } from '../../i18n/I18nContext';
+import type { ChatContextInput } from '../../hooks/useChat';
+
+// Everything heavy (useChat + adapter + Markdown renderer) is behind this lazy import, so the FAB
+// is the ONLY chat code in the initial bundle (Blueprint Phase 2.1 — FCP protected).
+const ChatMount = lazy(() => import('./ChatMount'));
+
+interface Props {
+  contextInput: ChatContextInput;
+  /** App registers the mounted chat's reset() so "Start Over" wipes it in-tab. */
+  registerReset: (reset: (() => void) | null) => void;
+}
+
+// The floating chat launcher (Advisor "AI Advisor"). Toggles the lazy panel; keeps its own open
+// state. Esc closes. Opening never resets chat; closing keeps the session (persisted).
+export function ChatFab({ contextInput, registerReset }: Readonly<Props>) {
+  const { t } = useI18n();
+  const [open, setOpen] = useState(false);
+  const [everOpened, setEverOpened] = useState(false);
+  const btnRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: globalThis.KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false);
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [open]);
+
+  const toggle = () => {
+    setOpen((v) => !v);
+    setEverOpened(true);
+  };
+
+  return (
+    <div className="aa-chat-root screen-only">
+      {/* Mounted once opened, then kept mounted (display-toggled) so the session/stream survives
+          closing the panel — closing must not reset the chat (Blueprint Phase 2.2 harmony). */}
+      {everOpened && (
+        <div style={{ display: open ? 'block' : 'none' }}>
+          <Suspense fallback={null}>
+            <ChatMount contextInput={contextInput} onClose={() => setOpen(false)} registerReset={registerReset} />
+          </Suspense>
+        </div>
+      )}
+      <button
+        ref={btnRef}
+        type="button"
+        className={'aa-chat-fab' + (open ? ' open' : '')}
+        onClick={toggle}
+        aria-label={open ? t('chat.close') : t('chat.open')}
+        aria-expanded={open}
+        title={open ? t('chat.close') : t('chat.open')}
+      >
+        {open ? <IconX size={22} aria-hidden /> : <IconMessageChatbot size={22} aria-hidden />}
+      </button>
+    </div>
+  );
+}
+
+export default ChatFab;

src/components/chat/ChatMessageItem.tsx

@@ -0,0 +1,65 @@
+import { memo } from 'react';
+import { IconRefresh, IconAlertTriangle } from '@tabler/icons-react';
+import { renderMarkdown } from '../../lib/markdown';
+import { ChatErrorBoundary } from './ChatErrorBoundary';
+import type { ChatMessage } from '../../lib/chat';
+
+interface Props {
+  msg: ChatMessage;
+  /** Localized "Failed to render output" fallback text. */
+  renderErrorText: string;
+  /** Localized "Regenerate" label; shown on the last errored assistant turn. */
+  regenerateLabel: string;
+  onRegenerate: () => void;
+  showRegenerate: boolean;
+}
+
+// One chat bubble — MEMOIZED (Blueprint Phase 2.2: 60fps with 100+ messages; only the streaming
+// bubble re-renders because its `text` prop changes). Assistant markdown is rendered with the app's
+// dependency-free, XSS-safe-by-construction renderer (React elements, never dangerouslySetInnerHTML),
+// wrapped in a per-bubble ErrorBoundary.
+function ChatMessageItemBase({ msg, renderErrorText, regenerateLabel, onRegenerate, showRegenerate }: Readonly<Props>) {
+  const isUser = msg.role === 'user';
+  return (
+    <div className={`aa-chat-msg ${isUser ? 'user' : 'bot'}`}>
+      <div className="aa-chat-bubble">
+        {isUser ? (
+          msg.text
+        ) : msg.error ? (
+          <span className="aa-chat-error">
+            <IconAlertTriangle size={14} aria-hidden /> {renderErrorText}
+          </span>
+        ) : (
+          <ChatErrorBoundary
+            fallback={
+              <span className="aa-chat-error">
+                <IconAlertTriangle size={14} aria-hidden /> {renderErrorText}
+              </span>
+            }
+          >
+            <div className="learn-prose aa-chat-prose">{renderMarkdown(msg.text)}</div>
+          </ChatErrorBoundary>
+        )}
+        {msg.streaming && <span className="aa-chat-caret" aria-hidden />}
+      </div>
+      {!isUser && (msg.error || showRegenerate) && !msg.streaming && (
+        <button type="button" className="aa-chat-regen" onClick={onRegenerate}>
+          <IconRefresh size={13} aria-hidden />
+          {regenerateLabel}
+        </button>
+      )}
+    </div>
+  );
+}
+
+// Re-render only when the visible content/flags of THIS message change.
+export const ChatMessageItem = memo(
+  ChatMessageItemBase,
+  (a, b) =>
+    a.msg.text === b.msg.text &&
+    a.msg.streaming === b.msg.streaming &&
+    a.msg.error === b.msg.error &&
+    a.showRegenerate === b.showRegenerate &&
+    a.renderErrorText === b.renderErrorText &&
+    a.regenerateLabel === b.regenerateLabel,
+);

src/components/chat/ChatMount.tsx

@@ -0,0 +1,35 @@
+import { useEffect } from 'react';
+import { useChat, type ChatContextInput } from '../../hooks/useChat';
+import { ChatPanel } from './ChatPanel';
+
+interface Props {
+  contextInput: ChatContextInput;
+  onClose: () => void;
+  /** App registers the chat's reset() so "Start Over" can wipe it in the same tab (null on unmount). */
+  registerReset: (reset: (() => void) | null) => void;
+}
+
+// Owns the chat STATE (useChat) and renders the panel. Lives only in the lazy chunk, so useChat +
+// the adapter + the Markdown renderer never touch the initial bundle (Blueprint Phase 2.1 FCP).
+export function ChatMount({ contextInput, onClose, registerReset }: Readonly<Props>) {
+  const chat = useChat(contextInput);
+
+  useEffect(() => {
+    registerReset(chat.reset);
+    return () => registerReset(null);
+  }, [chat.reset, registerReset]);
+
+  return (
+    <ChatPanel
+      messages={chat.messages}
+      streaming={chat.streaming}
+      onSend={chat.send}
+      onStop={chat.stop}
+      onRegenerate={chat.regenerate}
+      onReset={chat.reset}
+      onClose={onClose}
+    />
+  );
+}
+
+export default ChatMount;