Merge pull request #53 from programmerShinobi/feat/phase2g-advisor-export-footer-polish

[feat](advisor): Master Blueprint — Scenario Gallery + Custom Wizard + honest Step-3 stepper + UI polish + README

Author: programmerShinobi

DECISIONS.md

@@ -317,3 +317,36 @@ below is content or presentation, never scoring.
   the light theme (elegant), automatically light in dark contexts via `currentColor` (in-app) and
   an SVG-embedded `prefers-color-scheme` rule (favicon), so it is never invisible. PWA PNG icons
   keep a solid tile (maskable requirement): black compass on a soft white tile.
+
+## Custom Architecture Wizard + honest Step-3 analysis stepper (Master Blueprint, 2026-07-18)
+
+Two decisions taken with the owner (AskUserQuestion) while executing the "Master Blueprint" overhaul.
+Both are chosen precisely to preserve the Zero-Mismatch invariant.
+
+- **The Custom Wizard maps onto the FROZEN engine — one scoring model, not two.** The guided builder
+  captures four universal variables (Primary System Goal · Domain/Industry · Hard Constraints
+  [budget/team/timeline] · prioritized NFRs) but does **not** score them itself. A pure, unit-tested
+  bridge (`src/lib/customWizard.ts` → `wizardToLevels`) derives the frozen model's 14 factor levels
+  from the answers; the same `rank()` does the scoring. A **parallel 4-variable model was rejected**
+  — it would duplicate decision logic, sit outside the frozen guards, and create two sources of truth
+  to keep in sync (the exact long-term debt the blueprint forbids). The wizard **schema is typed,
+  injectable config** (`src/config/customWizard.ts`): new options/questions inject there and the UI
+  + mapping iterate it — no component edits (Blueprint Phase 1.1). Combine rule: ordered override
+  from a **moderate baseline** (all factors = 1), Goal → Domain → NFRs → Constraints, so an explicit
+  hard constraint always wins and a vague/empty wizard still yields a valid, balanced recommendation
+  (Phase 3.2 resilience). Every nudge is validated against the model by a unit test.
+- **The Step-3 "processing" state is HONEST — it never fakes latency.** The blueprint asked for a
+  "Progressive Terminal Readout"; the engine computes in <1 ms, and this file already records that
+  the prototype's *artificial* skeleton-on-recompute was omitted as misleading. Reconciliation
+  (`AnalysisStepper.tsx`): on an **explicit analyze action** (applying a preset card or the wizard)
+  it briefly surfaces the **real** pipeline stages the engine actually runs — *derive QA weights →
+  score 21 options → check anti-patterns → rank dimensions* — as a developer-centric terminal
+  readout, then reveals the result. It is **skippable**, and under `prefers-reduced-motion` it
+  renders nothing (instant). **Live factor edits stay instant** (no stepper) — the reveal is reserved
+  for the "run a scenario" gesture. So this *extends* the honesty stance (real stages, real values)
+  rather than reversing it; a full theatrical delay was explicitly declined.
+- **The Scenario Card Gallery supersedes the preset dropdown** (Blueprint Phase 1.3): searchable,
+  tag-filterable cards with a **dominant, dashed, terminal-styled "Build custom system"** card.
+  Preset tags (`src/config/presetTags.ts`) are **pure UI metadata** kept out of `presets.ts`, so the
+  frozen preset-level guards are untouched. The wizard modal is **lazy-loaded**, keeping the initial
+  Advisor bundle under budget.

README.md

@@ -44,22 +44,32 @@ managed — is decided early, hard to reverse, and disproportionately shapes the
 quality. In practice these decisions are too often made by trend rather than by an explicit
 trade-off analysis.
 
-**Architecture Advisor** is a planned, fully client-side web app that turns that decision into
-a transparent pipeline:
-
-```
-PROJECT FACTORS  ─►  QUALITY-ATTRIBUTE PRIORITIES  ─►  ARCHITECTURE FIT  ─►  ANALYSIS
-(drivers &           (a weighted "utility tree" of      (how well each option   (trade-offs, risks,
- constraints)         quality attributes, grounded       satisfies the           sensitivity, fitness
-                      in ISO/IEC 25010:2023)             prioritized QAs across   functions, ADR/report)
-                                                         5 orthogonal dimensions)
+**Architecture Advisor** is a fully client-side web app that turns that decision into a
+transparent pipeline:
+
+```mermaid
+flowchart LR
+  F["PROJECT FACTORS<br/><i>drivers &amp; constraints</i>"]
+  --> Q["QUALITY-ATTRIBUTE PRIORITIES<br/><i>weighted utility tree,<br/>ISO/IEC 25010:2023</i>"]
+  --> A["ARCHITECTURE FIT<br/><i>how well each option satisfies<br/>the priorities, across 5 dimensions</i>"]
+  --> O["ANALYSIS &amp; OUTPUT<br/><i>trade-offs, risks, sensitivity,<br/>fitness functions, ADR / report</i>"]
 ```
 
 You answer a handful of questions about your project; the tool recommends an architecture
 across five dimensions, ranks the alternatives, and — critically — **shows the full
 calculation**: which factor raised which quality attribute, and how that produced the score.
 Experts get auditable numbers and editable weights; newcomers get plain-language explanations.
 
+**Two ways in.** Start from a **Scenario Card Gallery** — searchable, tag-filterable cards for
+ten pre-built scenarios (startup MVP, regulated fintech, high-traffic e-commerce, IoT streaming,
+legacy modernization, …) — or open the **Custom Architecture Wizard** (the dominant dashed
+"Build custom system" card): a foolproof guided builder that captures four universal variables
+(Primary System Goal · Domain/Industry · Hard Constraints · prioritized NFRs) and maps them onto
+the **same frozen scoring engine** — there is exactly one scoring model, never a parallel one.
+Running a scenario briefly surfaces the engine's **real** analysis stages as a developer terminal
+readout (weights → score 21 options → anti-patterns → rank), then reveals the result — no fake
+latency, and instant under `prefers-reduced-motion`.
+
 It adapts established methods — **ISO/IEC 25010:2023**, **ATAM**, **Attribute-Driven Design**,
 and **evolutionary-architecture fitness functions** — into an interactive tool, and is honest
 about uncertainty: scores are *tunable heuristics, not facts*.
@@ -100,6 +110,42 @@ see the [content rollout plan](docs/03-blueprint/content-rollout-plan.md).
 > [evolution roadmap](docs/01-discovery-and-planning/discovery-and-planning.md#15-versioning-policy--evolution-roadmap)
 > for what's deferred beyond v1.0.
 
+## Workflow — the immutable four-step journey
+
+Every scenario flows through the same four steps; **Step 3 is the engine** (the "professional
+analysis"). The flow never changes — only the inputs do.
+
+```mermaid
+flowchart LR
+  subgraph S1["① Scenario &amp; factors"]
+    G["Scenario Card Gallery<br/>(search · tags)"]
+    W["Custom Wizard<br/>(4 variables)"]
+    F["14 project factors"]
+    G --> F
+    W -->|"wizardToLevels()"| F
+  end
+  subgraph S2["② Quality priorities"]
+    QA["Derived ISO/IEC 25010<br/>weights (editable)"]
+  end
+  subgraph S3["③ Professional analysis"]
+    E["Frozen scoring engine<br/>+ honest analysis stepper"]
+  end
+  subgraph S4["④ Strategic output"]
+    R["Recommendation · radar ·<br/>sensitivity · ADR / report / share"]
+  end
+  S1 --> S2 --> S3 --> S4
+```
+
+- **① Scenario & factors** — pick a preset card, build a custom system with the wizard, or set the
+  14 factors directly. The wizard and presets both resolve to the same 14 factor levels.
+- **② Quality priorities** — the engine derives the twelve ISO/IEC 25010 quality-attribute weights;
+  experts can pin/override any weight (the rest re-balance around it).
+- **③ Professional analysis** — the frozen engine scores all 21 architectures across the five
+  dimensions. A brief, skippable terminal stepper surfaces the real pipeline stages, then the
+  ranked result appears. **Live factor edits recompute instantly** (no stepper).
+- **④ 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.
+
 ## Run it locally
 
 > **Prerequisite:** Node **24** (LTS) — the version is pinned in [`.nvmrc`](.nvmrc) and used by all
@@ -128,7 +174,7 @@ traceable:
 | 2 | [Requirement Analysis](docs/02-requirement-analysis/) | [SRS](docs/02-requirement-analysis/software-requirements-specification.md) | 🔬 In progress |
 | 3 | [Blueprint (Design)](docs/03-blueprint/) | [Design spec](docs/03-blueprint/design-specification.md) + [Model Data Sheet](docs/03-blueprint/model-data-sheet.md) + [Architecture Reader](docs/03-blueprint/architecture-reader.md) + [Content Rollout Plan](docs/03-blueprint/content-rollout-plan.md) + [UI prototype](docs/03-blueprint/prototype/index.html) | 🔬 In progress |
 | 4 | [Development](docs/04-development/) | Source code (`src/`, scoring engine, components) | ✅ v1.0 implemented |
-| 5 | [Testing / QA](docs/05-testing-qa/) | [Test plan](docs/05-testing-qa/test-plan.md) — 99 Vitest + Playwright E2E + 3 model guards + content guard; CI gates size/audit; 14/16 AC automated | 🔬 In progress |
+| 5 | [Testing / QA](docs/05-testing-qa/) | [Test plan](docs/05-testing-qa/test-plan.md) — 127 Vitest + 14 Playwright E2E + 6 guards (model / docs / app-config / content / bundle-size / SEO); CI gates size/axe; 14/16 AC automated | 🔬 In progress |
 | 6 | [Deployment / Release](docs/06-deployment/) | [Live on GitHub Pages](https://programmershinobi.github.io/architecture-advisor/) via `deploy.yml` (CI/CD) | ✅ Live |
 | 7 | [Maintenance & Iteration](docs/07-maintenance/) | [Changelog](CHANGELOG.md), Dependabot, issue/PR templates, [security policy](SECURITY.md) | 🔄 Ongoing |
 
@@ -169,6 +215,82 @@ The canonical statement is [SRS §2.3 — Operating Environment](docs/02-require
 5. **Actionable & shareable** — export an ADR (MADR) and a full report; share via URL.
 6. **Open & evolving** — community-built, improving across versions.
 
+## Extending — scenarios, the Custom Wizard & the Step-3 UI
+
+Everything below is **typed, injectable config** — you add data, not logic. The frozen scoring
+model (`src/config/{factors,dimensions,qualityAttributes,factorQaMatrix}.ts`) is verified by
+`npm run verify:model` and must not change; new *scenarios* never touch it.
+
+### Add a preset scenario
+
+Presets are strictly-typed `Preset[]`. Append one to [`src/config/presets.ts`](src/config/presets.ts)
+and give it filter tags in [`src/config/presetTags.ts`](src/config/presetTags.ts) — the Card Gallery
+picks it up automatically. Helper presets are `calibrated: false`; the five ratified ones stay
+`true` and are bit-pinned by the guards.
+
+```ts
+// src/config/presets.ts
+{
+  id: 'edge-cdn',
+  label: { en: 'Edge / CDN app', id: 'Aplikasi edge / CDN' },
+  description: { en: 'Globally distributed, latency-critical, cache-heavy.', id: '…' },
+  levels: levels([1, 2, 1, 1, 2, 2, 1, 1, 2, 1, 0, 1, 0, 2]), // 14 factors, values 0–2
+  calibrated: false,
+},
+
+// src/config/presetTags.ts
+export const PRESET_TAGS = { /* … */ 'edge-cdn': ['high-scale', 'realtime'] };
+```
+
+A unit test (`src/config/presets.test.ts`) pins each helper preset's engine outcome, so a bad
+scenario fails the build rather than silently drifting.
+
+### Add / modify a Custom Wizard question
+
+The wizard is driven entirely by [`src/config/customWizard.ts`](src/config/customWizard.ts). Each
+option declares the factor **nudges** it applies; the pure bridge
+[`src/lib/customWizard.ts`](src/lib/customWizard.ts) combines them (ordered override from a moderate
+baseline, hard constraints last) into the 14 factor levels the frozen engine scores. **No component
+edits are needed** — `CustomWizard.tsx` iterates this config.
+
+```ts
+// src/config/customWizard.ts → add an option to the "goal" question
+{
+  id: 'batch-etl',
+  label: { en: 'Run heavy batch / ETL', id: 'Jalankan batch / ETL berat' },
+  hint:  { en: 'Scheduled data pipelines at volume', id: '…' },
+  levels: { dataVolume: 2, async: 2, scale: 2, realtime: 0 }, // only real factor ids, 0–2
+},
+```
+
+`wizardToLevels()` is unit-tested (`src/lib/customWizard.test.ts`): every nudge must reference a
+real factor id at a valid level, and the output is always a complete, valid `Levels` object — even
+when the user answers nothing (it falls back to a balanced baseline; the engine can never crash).
+
+### Modify the Step-3 terminal UI (analysis stepper)
+
+The developer-centric readout lives in
+[`src/components/advisor/AnalysisStepper.tsx`](src/components/advisor/AnalysisStepper.tsx). The
+stages are dict keys — edit the `STAGES` array and their strings in
+[`src/i18n/dict.ts`](src/i18n/dict.ts) (`analysis.run.*`). Keep the stages **honest** (they name
+real pipeline steps) and the total duration short; the component already renders nothing under
+`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.
+
+### 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 |
+| 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 |
+| ② Quality priorities + adjuster | [`components/advisor/PrioritiesCard.tsx`](src/components/advisor/PrioritiesCard.tsx) · `QaOverridePanel.tsx` | derived + editable weights |
+| ③ Analysis stepper | [`components/advisor/AnalysisStepper.tsx`](src/components/advisor/AnalysisStepper.tsx) | honest terminal readout |
+| ③ Recommendation | `DimensionCards.tsx` · `DimensionDetail.tsx` · `RadarPanel.tsx` | ranked result + radar |
+| ④ Export / share | [`components/chrome/Toolbar.tsx`](src/components/chrome/Toolbar.tsx) | ADR / report / CSV / JSON / share |
+| Pure scoring engine (frozen) | [`lib/scoring.ts`](src/lib/scoring.ts) | `rank()` — the single source of truth |
+
 ## Contributing
 
 Contributions are welcome — code, documentation, translations, and model review. Start with

docs/05-testing-qa/test-plan.md

@@ -241,8 +241,8 @@ Pure client-side, no backend/accounts/secrets — the surface is the browser and
 ## 9. Performance verification (L7)
 
 - [x] **Bundle budget:** **CI-gated** — `npm run size` ([`scripts/check-bundle-size.mjs`](../../scripts/check-bundle-size.mjs))
-      asserts gzip **initial JS ≤120kB** (first load) and **total JS ≤260kB** (raised 200→260 for full Insights bilingualisation 2026-07-15 — EN+ID content is lazy; NFR cap 300) / CSS ≤25kB (currently ~114 initial /
-      ~237 total / ~23 CSS with React 19 on Vite 8). The guard reads the **real initial set from `dist/index.html`** (entry
+      asserts gzip **initial JS ≤120kB** (first load) and **total JS ≤260kB** (raised 200→260 for full Insights bilingualisation 2026-07-15 — EN+ID content is lazy; NFR cap 300) / **CSS ≤27kB** (raised 25→27 for Fase 2g UI/UX polish 2026-07-18; NFR ceiling ~30kB) (currently ~117 initial /
+      ~250 total / ~25 CSS with React 19 on Vite 8). The guard reads the **real initial set from `dist/index.html`** (entry
       script + modulepreloads), so lazy views (Manual/Guide, Insights) **and their shared async chunks** (e.g.
       `readerContent`, which powers the data-driven Catalog) are correctly excluded from the first load — none can be
       silently mis-counted. No chart/diagram/markdown library ships — all visuals are hand-built SVG and Markdown is

e2e/a11y.spec.ts

@@ -80,5 +80,5 @@ test('controls are keyboard-operable', async ({ page }) => {
   await page.getByRole('button', { name: 'EN', exact: true }).focus();
   await page.keyboard.press('Enter');
   await page.getByRole('button', { name: 'Advisor', exact: true }).click(); // default view is now Home
-  await expect(page.getByRole('button', { name: 'Busy online shop' })).toBeVisible();
+  await expect(page.getByRole('button', { name: /Busy online shop/ })).toBeVisible();
 });

e2e/share.spec.ts

@@ -11,7 +11,7 @@ test('share link round-trips the scenario via a deep link', async ({ page, conte
   await page.goto(APP);
   await page.getByRole('button', { name: 'EN', exact: true }).click();
   await page.getByRole('button', { name: 'Advisor', exact: true }).click(); // default view is now Home
-  await page.getByRole('button', { name: 'Busy online shop' }).click();
+  await page.getByRole('button', { name: /Busy online shop/ }).click();
   const shared = (await page.getByText(VERDICT).textContent())?.trim();
 
   // Share copies the deep link to the clipboard

e2e/smoke.spec.ts

@@ -22,8 +22,9 @@ test('the four-step flow loads and the recommendation recomputes on a preset', a
   await expect(verdict).toBeVisible();
   const before = (await verdict.textContent())?.trim();
 
-  // applying a preset instantly recomputes the recommendation (AC-2, real browser)
-  await page.getByRole('button', { name: 'Busy online shop' }).click();
+  // applying a preset instantly recomputes the recommendation (AC-2, real browser).
+  // Presets are cards in the Scenario Card Gallery (Blueprint Phase 1.3) — clicked directly.
+  await page.getByRole('button', { name: /Busy online shop/ }).click();
   await expect(page.getByText(VERDICT)).not.toHaveText(before ?? '');
 });
 

scripts/check-bundle-size.mjs

@@ -18,7 +18,7 @@ import { gzipSync } from 'node:zlib';
 // 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 CSS_BUDGET_KB = 25;
+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';
 if (!existsSync(dir)) {

src/App.test.tsx

@@ -19,7 +19,8 @@ describe('App integration', () => {
   it('AC-2: applying a preset instantly recomputes the recommendation', () => {
     renderWithI18n(<App />, 'en');
     const before = screen.getByText(VERDICT).textContent;
-    fireEvent.click(screen.getByRole('button', { name: 'Busy online shop' }));
+    // Presets are cards in the Scenario Card Gallery (Blueprint Phase 1.3) — clicked directly.
+    fireEvent.click(screen.getByRole('button', { name: /Busy online shop/ }));
     expect(screen.getByText(VERDICT).textContent).not.toBe(before);
   });