[feat](copilot): interactive guided tour + gate AI chat behind a flag (Phase 3)

Add a pluggable, 100% client-side Interactive Copilot (`src/features/copilot/`):
a "Guide me" launcher runs a bilingual, step-by-step walkthrough of the four-step
Advisor journey — spotlighting each target with Do/Don't guidance.

- Adapter Pattern (`getCopilotService()`), closed `data-tour-id` whitelist, typed
  leak-free event bus, React-portal overlay (spotlight + card) with live tracking
  (ResizeObserver + MutationObserver + scroll/resize/visualViewport). Missing target
  degrades to a silent fallback; every observer/listener/timer is cleaned up.
- Pre-Flight Check: navigate to the step's view, wait for paint, scroll the target
  BELOW the pinned chrome (app bar + step rail) so the spotlight is never hidden, and
  keep it ABOVE the mobile bottom-sheet card (pinned header/footer, scroll-only body)
  so a full step — title, body, Do/Don't — is never clipped. The app's sticky
  step-rail hides while the tour runs (the Copilot is the guide). Step 1 anchors the
  compact "Build custom system" card so the spotlight fits small screens.
- Dependency-free + XSS-safe-by-construction (reuses `lib/markdown`), lazy-loaded so
  the initial JS budget is untouched; engine is unit-tested, overlay verified in-browser.

Gate the AI Advisor chat OFF behind a single flag (`FEATURES.chat`,
`src/config/features.ts`) while its UX is finalized: App skips mounting the FAB and the
tour filters out its chat step, so nothing points at a control that isn't on screen.
Re-enabling is a one-line change. README + DECISIONS updated to reflect both.

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

Author: programmerShinobi

DECISIONS.md

@@ -383,6 +383,13 @@ Both are chosen precisely to preserve the Zero-Mismatch invariant.
 
 ## Phase 3 — "AI Advisor" chat (Context-Aware, Client-Side), 2026-07-19
 
+> **Update (2026-07-19): shipped OFF.** The chat is gated behind `FEATURES.chat`
+> (`src/config/features.ts`), currently `false`, while its UX is finalized — the deploy goes out
+> without it. Because the feature was already fully code-split, the gate is a single flag: `App`
+> skips mounting the FAB, and the Copilot tour filters out its chat step, so nothing points at a
+> control that isn't on screen. Flipping the flag to `true` restores everything with zero other
+> edits. The design below stands.
+
 Implements the Phase-3 blueprint while honoring two enforced invariants (building it literally
 would have tripped both — the very regressions the mandate forbids):
 
@@ -412,3 +419,36 @@ would have tripped both — the very regressions the mandate forbids):
   **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.
+
+## Phase 3 — Interactive Copilot & guided tour, 2026-07-19
+
+A pluggable **"Guide me" walkthrough** (`src/features/copilot/`) that spotlights each of the four
+steps with Do/Don't guidance. Built to the Copilot blueprint while honoring the same invariants the
+chat did — the maximalist form would have tripped them:
+
+- **Local structured-command service, Adapter Pattern (no external LLM).** `CopilotService` behind
+  `getCopilotService()` is the single swap-point. Today it returns the **offline `localCopilotService`**
+  — bilingual step content that weaves in the *live top pick* from the frozen engine (pure +
+  unit-tested). A generated/LLM guide is a drop-in with **zero** UI changes. Keeps the 100%
+  client-side / offline / no-keys / no-telemetry promise intact.
+- **Closed `data-tour-id` whitelist (no arbitrary selectors, no DOMPurify).** Targets are addressed
+  only through `TOUR_IDS` + the type-safe `tourId()` helper; `isTourId()` rejects anything else and
+  a unit test enforces every tour step maps to a whitelisted id. A missing target degrades to a
+  **silent fallback** (centered card + "not on screen" note) — never hangs or throws. No
+  `dangerouslySetInnerHTML`; step bodies use the same XSS-safe `lib/markdown.tsx` renderer.
+- **Portal overlay + live tracking (escapes every stacking context).** `CopilotOverlay` renders via
+  `createPortal` to `document.body`; a box-shadow spotlight rings the target, tracked by
+  `ResizeObserver` + `MutationObserver` + `scroll`/`resize`/`visualViewport` (all cleaned up — zero
+  leaks). Z-index strategy: primary `z10` < utility `z20` < copilot overlay `z9999`.
+- **Goes to the location, never covers it (Pre-Flight Check + responsive card).** `useCopilot`
+  navigates to the step's view, waits for the target to mount+paint (`waitForTarget` = MutationObserver
+  bounded by a timeout), scrolls it to the **upper third** (`scrollBy … − vh*0.20`) and waits a
+  paint before the first draw. On phones the card is a **bottom sheet** (`min(68vh, 100dvh−84px)`)
+  with **pinned header/footer + a scroll-only body**, so a full step — title, body, **and** both
+  Do/Don't cards — is always readable and **never clipped** (verified iPhone-SE 375×667: DON'T text
+  fully visible, spotlight above the sheet). Bottom controls (launcher · action bar · chat FAB) are
+  lifted on the Advisor view (`body.aa-view-advisor`) with `flex-shrink:0`/`nowrap` to prevent overlap.
+- **Nav-harmony, Start-Over, lean.** Switching tabs mid-tour stops it; "Start Over" resets the tour
+  next to the chat (`registerReset`); the launcher **and** the whole overlay are `lazy()` — initial
+  JS budget untouched. Engine (bus/whitelist/service/tour config) is unit-tested; the DOM overlay is
+  verified in-browser.

README.md

@@ -122,6 +122,12 @@ flowchart LR
 
 ## AI Advisor chat (Phase 3)
 
+> **Status: temporarily disabled.** The chat is gated **off** behind a single flag
+> (`FEATURES.chat` in [`src/config/features.ts`](src/config/features.ts)) while its UX is being
+> finalized, so the deployed build ships without it. The code is complete and code-split; flip the
+> flag to `true` to bring it back (the FAB mounts, "Start Over" resets it, and the Copilot tour
+> restores its chat step — no other change). The rest of this section describes it as designed.
+
 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
@@ -154,6 +160,44 @@ flowchart LR
   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.
 
+## Interactive Copilot & guided tour (Phase 3)
+
+A **"Guide me" launcher** (bottom-right, Advisor tab) starts a step-by-step walkthrough of the
+four-step journey. Each step **navigates to the right view, scrolls its target into the upper
+third, and rings it with a spotlight** while a card explains what the step does — with concrete
+**Do / Don't** guidance. Like the chat, it is **100% client-side, offline, and dependency-free**:
+no external tour library, no `dangerouslySetInnerHTML`, and targets are addressed through a
+**closed `data-tour-id` whitelist** (a command can never point the overlay at an arbitrary
+selector). It ships as a **pluggable `src/features/copilot/` module** behind a service adapter, so
+a smarter (even LLM-driven) guide is a drop-in later with zero UI changes.
+
+```mermaid
+flowchart LR
+  B["Guide me"] --> HK["useCopilot engine<br/>(step index · run token)"]
+  HK -->|"describe(step, ctx)"| SVC["getCopilotService()<br/><b>CopilotService (Adapter)</b>"]
+  SVC --> LOC["localCopilotService<br/>(bilingual · live top-pick)"]
+  HK -->|"nav to step.view"| NAV["App view"]
+  HK -->|"waitForTarget()<br/>MutationObserver + timeout"| DOM["data-tour-id target<br/>(closed whitelist)"]
+  HK -->|"highlight | dismiss | stop"| BUS["Event Bus<br/>(typed · leak-free)"]
+  BUS --> OV["CopilotOverlay (portal → body)"]
+  DOM -->|"ResizeObserver · MutationObserver<br/>scroll · resize · visualViewport"| OV
+  OV --> SPOT["Spotlight ring + Do/Don't card<br/>(pinned head/foot · scroll body)"]
+  SVC -. "future" .-> LLM["llmCopilotService<br/>(drop-in, same contract)"]
+```
+
+- **Goes to the location, never covers it** — a Pre-Flight Check scrolls the target to the upper
+  third and waits a paint before the first draw; the ring then tracks it live via
+  `ResizeObserver` + `MutationObserver` + `scroll`/`resize`/`visualViewport`. On phones the card is
+  a **bottom sheet** (pinned header/footer, only the body scrolls) so a full step — title, body,
+  **and** both Do/Don't cards — is always readable and **never clipped**.
+- **Safe by construction** — only whitelisted `data-tour-id`s can be highlighted; a missing target
+  degrades to a **silent fallback** (card centers, "this control isn't on screen" note) instead of
+  hanging or throwing. The overlay renders through a **React portal** to `document.body`, escaping
+  every `z-index` stacking context (primary `z10` < utility `z20` < copilot overlay `z9999`).
+- **Nav-harmony & clean teardown** — switching tabs mid-tour stops it; "Start Over" resets the tour
+  alongside the chat; every observer/listener/timer is cleaned up (zero leaks). The launcher and
+  the whole overlay are **lazy-loaded**, so the initial JS budget is untouched.
+
 ## Run it locally
 
 > **Prerequisite:** Node **24** (LTS) — the version is pinned in [`.nvmrc`](.nvmrc) and used by all
@@ -309,13 +353,45 @@ export function getChatAdapter(): ChatAdapter {
 `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`.
 
+### Add a Copilot step (or swap the guide backend)
+
+The tour is data: add a step to `MAIN_TOUR` in
+[`src/features/copilot/tourConfig.ts`](src/features/copilot/tourConfig.ts). `target` must be one of
+the whitelisted `data-tour-id`s in [`dataTourId.ts`](src/features/copilot/dataTourId.ts) — tag the
+element with the type-safe `tourId()` helper and the test suite enforces the pairing:
+
+```ts
+// 1) tag the element (closed whitelist — the only ids the overlay can point at)
+<section {...tourId('recommendation')}> … </section>
+
+// 2) add a bilingual step with concrete Do / Don't guidance
+{ id: 'result', view: 'advisor', target: 'recommendation', placement: 'top',
+  title: { en: 'Your recommended plan', id: 'Rencana yang disarankan' },
+  body:  { en: 'Ranked per dimension…', id: 'Diperingkat per dimensi…' },
+  dos:   [{ en: 'Read the "why"', id: 'Baca alasannya' }],
+  donts: [{ en: 'Chase a single number', id: 'Mengejar satu angka' }] }
+```
+
+The overlay depends only on the `CopilotService` contract;
+`getCopilotService()` in [`copilotService.ts`](src/features/copilot/copilotService.ts) is the
+**single** swap-point — return a smarter (even LLM-driven) service and nothing else changes:
+
+```ts
+export function getCopilotService(): CopilotService {
+  return localCopilotService;   // today: offline, bilingual, weaves in your live top pick
+  // return llmCopilotService;  // future: a generated walkthrough — same contract, drop-in
+}
+```
+
 ### 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 |
+| AI Advisor chat (lazy, flag-gated) | [`components/chat/ChatFab.tsx`](src/components/chat/ChatFab.tsx) · `ChatPanel.tsx` · [`hooks/useChat.ts`](src/hooks/useChat.ts) | launcher + panel + state bridge — off via `FEATURES.chat` |
 | Chat service (Adapter) | [`lib/chat/`](src/lib/chat/) | `getChatAdapter()` · `localAdvisorAdapter` · `buildChatContext()` |
+| Copilot tour (lazy, pluggable) | [`features/copilot/Copilot.tsx`](src/features/copilot/Copilot.tsx) · `useCopilot.ts` · `components/CopilotOverlay.tsx` | launcher + engine + portal overlay |
+| Copilot service (Adapter) | [`features/copilot/`](src/features/copilot/) | `getCopilotService()` · `MAIN_TOUR` · `tourId()` whitelist · event bus |
 | 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

@@ -16,9 +16,9 @@ import { gzipSync } from 'node:zlib';
 // This reads the real initial set from index.html rather than guessing by filename, so a new lazy or
 // 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_INITIAL_BUDGET_KB = 121; // 120→121 for Phase 3 (chat + copilot) 2026-07-19: both features are LAZY chunks; the only initial delta is their dynamic-import stubs + a few refs of wiring (~0.3kB gzip, negligible FCP). NFR ceiling is far higher.
 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 CSS_BUDGET_KB = 29; // 25→27 (Fase 2g polish 2026-07-18); 27→29 for Phase 3 2026-07-19 (chat panel + copilot overlay/launcher/Dos-Don'ts cards); still under the ~30kB NFR ceiling
 
 const dir = 'dist/assets';
 if (!existsSync(dir)) {

src/App.tsx

@@ -39,6 +39,7 @@ import { usePersistedState } from './hooks/usePersistedState';
 import { useTheme } from './hooks/useTheme';
 import { useExportActions } from './hooks/useExportActions';
 import { DEFAULT_LEVELS } from './config/defaults';
+import { FEATURES } from './config/features';
 import { PRESETS } from './config/presets';
 import type { MigrationKey } from './config/migrationPaths';
 import { DIMENSION_ORDER } from './config/dimensions';
@@ -63,6 +64,10 @@ const LearnView = lazy(() => import('./components/insights/LearnView'));
 // is imported eagerly, for "Start Over".
 const ChatFab = lazy(() => import('./components/chat/ChatFab'));
 
+// Interactive Copilot / guided tutorial (Phase 3) — the whole feature is a lazy plugin; only the
+// tiny `tourId()` helper is imported eagerly (to tag targets non-invasively).
+const Copilot = lazy(() => import('./features/copilot/Copilot'));
+
 type Selections = Partial<Record<DimensionId, string>>;
 
 export default function App() {
@@ -119,6 +124,8 @@ export default function App() {
   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);
+  // Registered by the Copilot so "Start Over" hard-resets the guided tour (anti-contamination).
+  const copilotResetRef = useRef<(() => void) | null>(null);
 
   const scenario: ScenarioState = { v: 1, mode, lang, levels, selections, overrides };
   const exportInput: ExportInput = { levels, overrides, selections: effective, lang };
@@ -141,6 +148,8 @@ export default function App() {
     // reset if the panel was opened, else just the persistence + cross-tab broadcast.
     if (chatResetRef.current) chatResetRef.current();
     else resetChatPersistence();
+    // ...and hard-resets the Copilot tour (anti-contamination, Phase 3.3).
+    copilotResetRef.current?.();
   };
   const undoReset = () => {
     const snap = undoRef.current;
@@ -229,13 +238,33 @@ export default function App() {
     };
   }, []);
 
+  // Flag the Advisor view on <body> so the floating controls (chat FAB + copilot launcher) can lift
+  // ABOVE the mobile action bar there — preventing the bottom-controls overlap (owner revision).
+  useEffect(() => {
+    document.body.classList.toggle('aa-view-advisor', mainView === 'advisor');
+    return () => document.body.classList.remove('aa-view-advisor');
+  }, [mainView]);
+
   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). */}
+    {/* AI Advisor chat (Phase 3) — gated behind FEATURES.chat (owner: disabled until finalized).
+        When on, it mounts GLOBALLY (never per-view) so navigating tabs closes the Guide but never
+        unmounts the chat or disrupts an active stream (Phase 2.2 harmony). */}
+    {FEATURES.chat && (
+      <Suspense fallback={null}>
+        <ChatFab contextInput={{ levels, overrides, mode, lang }} registerReset={(fn) => (chatResetRef.current = fn)} />
+      </Suspense>
+    )}
+    {/* Interactive Copilot / guided tutorial (Phase 3) — a lazy, pluggable feature module. */}
     <Suspense fallback={null}>
-      <ChatFab contextInput={{ levels, overrides, mode, lang }} registerReset={(fn) => (chatResetRef.current = fn)} />
+      <Copilot
+        currentView={mainView}
+        onRequestView={navigate}
+        lang={lang}
+        topPick={rankings.D1[0]?.name}
+        registerReset={(fn) => (copilotResetRef.current = fn)}
+      />
     </Suspense>
     <MobileChrome mainView={mainView} onNavigate={navigate} theme={theme} onToggleTheme={toggleTheme} mode={mode} onSetMode={setMode} />
     {mainView === 'advisor' && <AdvisorMobileBar />}
@@ -324,7 +353,7 @@ export default function App() {
 
         {/* Step 1 — project factors (its own dropdown section; owner feedback: factors and
             priorities must be SEPARATE so nobody gets confused). */}
-        <StepSection id="aa-sec-1" n="1" titleG="step1.g" titleE="step1.e">
+        <StepSection id="aa-sec-1" n="1" titleG="step1.g" titleE="step1.e" tourId="project-factors">
           <FactorInputs levels={levels} onChange={setLevels} />
         </StepSection>
 
@@ -333,7 +362,7 @@ export default function App() {
         {/* Step 2 — derived quality priorities; the adjust editor opens right underneath.
             Ungated (Fase 2d rev.3, owner): guided users can customise weights too — the
             plain-language adjuster is newcomer-safe. */}
-        <StepSection id="aa-sec-2" n="2" titleG="step2.g" titleE="step2.e">
+        <StepSection id="aa-sec-2" n="2" titleG="step2.g" titleE="step2.e" tourId="quality-priorities">
           <div style={{ display: 'grid', gap: '14px' }}>
             <PrioritiesCard weights={weights} onAdjust={() => setEditWeights((v) => !v)} editing={editWeights} />
             {editWeights && <QaOverridePanel weights={weights} overrides={overrides} onChange={setOverrides} />}
@@ -344,7 +373,7 @@ export default function App() {
 
         {/* Step 3 — recommendation across dimensions (collapsible card, Fase 2d). */}
         <div id="adv-plan" style={{ scrollMarginTop: '132px' }} />
-        <StepSection id="aa-sec-3" n="3" titleG="results.title.g" titleE="results.title.e">
+        <StepSection id="aa-sec-3" n="3" titleG="results.title.g" titleE="results.title.e" tourId="recommendation">
           <AnalysisStepper runKey={analysisRun} />
           <DimensionCards rankings={rankings} current={currentDim} onSelect={setCurrentDim} />
           <DimensionDetail dim={currentDim} ranked={rankings[currentDim]} weights={weights} />
@@ -361,7 +390,7 @@ export default function App() {
 
         <div id="adv-save" className="f-div" style={{ scrollMarginTop: '132px' }} />
         {/* Step 4 — save & share (collapsible card, Fase 2d). */}
-        <StepSection id="aa-sec-4" n="4" titleG="step4.g" titleE="step4.e">
+        <StepSection id="aa-sec-4" n="4" titleG="step4.g" titleE="step4.e" tourId="strategic-output">
           <Toolbar run={run} status={exportStatus} setStatus={setExportStatus} mode={mode} onImport={importScenario} />
         </StepSection>
 

src/components/advisor/PresetBar.tsx

@@ -81,7 +81,7 @@ export function PresetBar({ activeId, onApply, onReset, onUndo }: Readonly<Props
         {t('presets.fill')}
       </div>
 
-      {/* Search + tag filters */}
+      {/* Search + tag filters. */}
       <div className="aa-gallery-tools">
         <label className="aa-gallery-search">
           <IconSearch size={14} aria-hidden style={{ color: 'var(--color-text-tertiary)', flex: 'none' }} />
@@ -98,7 +98,9 @@ export function PresetBar({ activeId, onApply, onReset, onUndo }: Readonly<Props
 
       {/* Card gallery — dominant custom card first, then matching presets */}
       <div className="aa-gallery-grid">
-        <button type="button" className="aa-scard aa-scard-custom" onClick={() => setWizardOpen(true)}>
+        {/* Dominant "start here" card — also the compact Copilot anchor for the "pick a scenario"
+            step (a tight target that fits the spotlight band on small screens). */}
+        <button type="button" className="aa-scard aa-scard-custom" data-tour-id="scenario-gallery" onClick={() => setWizardOpen(true)}>
           <span className="aa-scard-head">
             <IconTerminal2 size={16} aria-hidden />
             {t('wizard.open')}