@explorer02/cfm-survey-sdk 0.2.9 → 0.3.1

package/templates/docs/00-integration/ui-customization-wizard.md

@@ -2,6 +2,37 @@
 
 > Optional **run** after Phase 6 verify. **Wizard-ready build** is mandatory in Phase 5 — see [`agent-execution-flow.md`](agent-execution-flow.md).
 
+### Port selection (strict)
+
+The CLI calls `findPort(4200)` — tries **4200**, then **4201**, **4202**, … until a port is free.
+
+**Agent rules:**
+
+1. **Do not** hardcode `localhost:4200` if the CLI printed a different port.
+2. **Share only** the URL the CLI prints under `🔗 Client wizard link — share this URL only:`.
+3. **Do not** give the client a second link, a file path, or `out/previews/` paths.
+
+Example CLI output:
+
+```
+🔗 Client wizard link — share this URL only:
+   http://localhost:4201
+   Port 4201 (auto-selected if 4200 was in use)
+```
+
+### Client quit without save
+
+If the client clicks **Quit** (no Review & Build):
+
+- CLI runs preview GC (`out/previews/` deleted)
+- CLI exits without `survey-ui-config.json` update
+- **Agent must NOT** re-run `npx cfm-sdk customize` or send another wizard link
+- **Agent must** ask deploy confirmation (INPUT 4) using the **existing** build from Phase 6
+
+See [`wizard-config-handoff.md`](wizard-config-handoff.md) § Quit without save.
+
+---
+
 ## Default: local wizard (`customize`)
 
 When the client says **yes** to customization in agent chat, **always run:**
@@ -12,8 +43,7 @@ npx cfm-sdk customize
 
 This is the **recommended default** because it:
 
-- Probes the first free port from **4200** upward and starts the wizard there
-- Prints a machine-parseable line: **`WIZARD_LINK=http://localhost:{port}`** — agent shares **only** this URL with the client (never hardcode `:4200`)
+- Serves wizard + component previews from **one local server** (`localhost:4200`)
 - Auto-exports all **11** question-type previews from agent components
 - Writes `survey-ui-config.json` **directly** on save — no S3, no session polling
 - Cleans up local `out/previews/` when client quits without saving (`POST /api/wizard-quit`) or when CLI exits (Ctrl+C)
@@ -21,15 +51,9 @@ This is the **recommended default** because it:
 
 **Agent script after client says yes:**
 
-> *"I'll start the customization wizard. Use the link I share — complete all steps and click **Review & Build** when done."*
+> *"I'll open the customization wizard in your browser. Complete all steps and click **Review & Build** when done — I'll apply your changes automatically."*
 
-**Strict link handoff:**
-
-1. Run `npx cfm-sdk customize` and wait for `WIZARD_LINK=http://localhost:…` in CLI output
-2. Share **only** that URL with the client — do not guess port 4200
-3. Keep the terminal open until CLI exits
-
-**On successful save:**
+The CLI **blocks** until the client saves. Wait for:
 
 ```
 ✅ UI configuration saved to survey-ui-config.json
@@ -37,8 +61,6 @@ This is the **recommended default** because it:
 
 Then apply per [`apply-ui-config.md`](apply-ui-config.md).
 
-**If client quits without saving:** CLI exits 0 after GC (`out/previews/` removed). **Do not** re-run the wizard. Skip Phase 6c. Ask deploy confirmation (Phase 7 / INPUT 4) with the existing Phase 6 build.
-
 ### Who can use it
 
 | User | Can use `customize`? |
@@ -46,7 +68,7 @@ Then apply per [`apply-ui-config.md`](apply-ui-config.md).
 | Client on **same machine** as agent (Cursor chat on dev laptop) | **Yes — default** |
 | Client on **another device** | **No** — use EC2 fallback below |
 
-The wizard URL is **`WIZARD_LINK` from CLI output** — only reachable on the machine running the CLI (port may be 4201+ if 4200 is busy).
+`localhost:4200` is only reachable on the machine running the CLI.
 
 ---
 
@@ -60,7 +82,7 @@ npx cfm-sdk customize-ui
 ```
 
 - Uploads previews to EC2 disk (local-server model on remote host)
-- Prints **`WIZARD_LINK=…`** after previews upload — agent sends **only** that URL to client
+- Prints EC2 wizard link — agent sends link to client
 - CLI **polls** until client submits → writes `.final.json` + `.diff.md`
 - Requires deploy-api on EC2 + `CFM_INSTANCE_ID`
 
@@ -87,7 +109,7 @@ After Phase 6 verify + dev server:
 ```mermaid
 sequenceDiagram
   participant Agent as Agent CLI
-  participant Srv as localhost port from WIZARD_LINK
+  participant Srv as localhost:4200
   participant Wizard as Wizard SPA
   participant Prev as out/previews/
 
@@ -120,24 +142,11 @@ sequenceDiagram
 
 ---
 
-## Port probe + link-only handoff (mandatory)
-
-| Step | Agent action |
-|------|----------------|
-| 1 | Run `npx cfm-sdk customize` (or `customize-ui` for remote) |
-| 2 | Read `WIZARD_LINK=…` from CLI stdout — **never** assume `localhost:4200` |
-| 3 | Share **only** that URL with the client |
-| 4 | Wait until CLI exits (save → exit 0, quit → exit 0 with GC message) |
-
-Optional: set `CFM_WIZARD_OPEN_BROWSER=1` to auto-open the wizard in the agent's browser.
-
----
-
 ## Agent checklist
 
 - [ ] Phase 5: wizard-preview artifacts wired
 - [ ] Client opted in (INPUT 3)
-- [ ] Parsed `WIZARD_LINK` from CLI and shared only that URL with client
+- [ ] Ran **`npx cfm-sdk customize`** (default) and waited for CLI exit 0
 - [ ] Read `survey-ui-config.json` (or `.diff.md` if used EC2 fallback)
 - [ ] Phase 6c: applied per [`apply-ui-config.md`](apply-ui-config.md)
 - [ ] Re-ran verify + build

package/templates/docs/00-integration/wizard-chrome-contract.md

@@ -12,6 +12,7 @@ Pipeline: [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) · [`
 | Wizard control / symptom | Required fix |
 |--------------------------|--------------|
 | Logo not updating in Branding / Header preview | `data-cfm-logo` img + `data-cfm-logo-text` fallback in `Header.tsx` |
+| Logo shows colored pad behind image | Logo `<img>` must use `background: transparent` — **never** `var(--cfm-primary)` on logo box |
 | Company name not updating | `data-cfm-company` span in `Header.tsx` |
 | Show header works but progress bar toggle does nothing | Progress bar needs `data-cfm-progress` + class `cfm-progress`; header needs class `cfm-header` only — **not** on sticky wrapper |
 | Show footer toggle does nothing | `footer` + class `cfm-footer` |
@@ -21,25 +22,15 @@ Pipeline: [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) · [`
 | Scale selection colors not updating | Import `selectionStyles.ts`; use `var(--cfm-matrix-selected)` / `var(--cfm-input-focus-ring)` |
 | Company name not showing after logo | Copy `Header.tsx` template — brand row is `[logo][data-cfm-company]` in one flex container |
 | Company shows when empty | Bridge clears `[data-cfm-company]` when `companyName` is `""` — do not hardcode "Company Name" as visible default |
-| NPS colors / rings not updating | Copy `RatingScale.tsx` + `selectionStyles.ts` — no hardcoded `#e20074` |
+| NPS clicks do nothing / no visible selection before wizard | Copy latest `RatingScale.tsx` + `selectionStyles.ts` + `surveyUiScaleUtils.ts`; use `isScaleAnswerSelected()`; radio track row must use `label` + `onChange` → `onSelect(number)` — see `03-ui-specs/01-rating.md` |
+| NPS colors / rings not updating | Copy `RatingScale.tsx` + `selectionStyles.ts` — hex fallbacks in `selectionStyles.ts` for pre-theme builds |
 | Text placeholder color not updating | `data-cfm-textfield` + `--cfm-input-placeholder` in CSS / `::placeholder` rule |
 | Matrix 2nd row toggle | Harness adds row via `previewMultiStatement` — `LikertMatrixScale` must render all `statementRows` from props |
 | Blank page after deploy | **Never** reference `UI_CONFIG` without import — use `src/lib/uiConfig.ts` |
-| Logo pink/colored box behind image | Logo `background: var(--cfm-header-logo-bg, transparent)` — never `var(--cfm-primary)` on logo img |
-| Logo + company placement | Locked: logo left, company name after logo in `.cfm-header-brand` flex row — no grid placement templates |
-| Logo size | `--cfm-header-logo-width/height` from wizard max-dimension slider; `object-contain` |
 | Logo wrong on CloudFront | Never change `global.logo.fileName` manually — use wizard file in `public/` |
 
 ---
 
-## Agent link handoff (strict)
-
-1. Run `npx cfm-sdk customize` — read **`WIZARD_LINK=http://localhost:{port}`** from CLI (port may be 4201+)
-2. Share **only** that URL with the client
-3. On quit without save: CLI exits 0, GC `out/previews/` — **do not** re-run wizard; ask deploy (Phase 7)
-
----
-
 ## Copy order (agents — do this in Phase 5)
 
 ```bash

package/templates/docs/00-integration/wizard-config-handoff.md

@@ -30,18 +30,16 @@ npx cfm-sdk customize
 The CLI will:
 
 1. Export all 11 component preview pages (`export-previews` if needed)
-2. Probe first free port from 4200 and start wizard — CLI prints **`WIZARD_LINK=http://localhost:{port}`**
-3. **Block** until client clicks **Review & Build** or quits
-4. On save: write `survey-ui-config.json` and exit 0
-5. On quit: GC `out/previews/` and exit 0 — **do not re-run wizard**; ask deploy (Phase 7)
+2. Start wizard at `http://localhost:4200`
+3. Open browser on the **agent machine**
+4. **Block** until client clicks **Review & Build**
+5. Write `survey-ui-config.json` and exit 0
 
 **Agent must:**
 
-- [ ] Parse `WIZARD_LINK` from CLI and share **only** that URL with client (never hardcode `:4200`)
-- [ ] Client is on the **same machine** (can open the `WIZARD_LINK` host)
-- [ ] Keep terminal open until CLI exits
-- [ ] On save: apply per Phase 6c from `survey-ui-config.json`
-- [ ] On quit: skip Phase 6c; ask deploy confirmation with existing Phase 6 build
+- [ ] Client is on the **same machine** (can see `localhost:4200`)
+- [ ] Keep terminal open until `✅ UI configuration saved`
+- [ ] Apply per Phase 6c from `survey-ui-config.json`
 
 **Artifact:** `survey-ui-config.json` — apply source for local flow.
 
@@ -56,10 +54,20 @@ When the client uploads a logo in the local wizard:
 
 The logo is **not** fetched from wizard memory on CloudFront — only from the deploy bundle. See [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
 
-**Local quit (preview GC):** If the client exits without saving, wizard calls `POST /api/wizard-quit` → CLI deletes `out/previews/` → exits 0. Agent **must not** re-run the wizard or share a new link — proceed to Phase 7 deploy ask.
+**Local quit (preview GC):** If the client exits without saving, wizard calls `POST /api/wizard-quit` → CLI deletes `out/previews/`.
 
 **After save:** `POST /api/save-config` also deletes `out/previews/` before CLI exits (preview garbage collection).
 
+**Quit without save (no second wizard run):**
+
+| Event | Agent action |
+|-------|----------------|
+| Client clicks **Quit** in wizard | Wait for CLI exit; previews GC'd automatically |
+| CLI exits without `✅ UI configuration saved` | **Do not** run `customize` again or share another wizard URL |
+| Build still valid from Phase 6 | Ask deploy confirmation (INPUT 4) — use existing `out/` from prior `npm run build` |
+
+The agent does **not** re-open the wizard after quit. Garbage collection removes preview artifacts only; the production build in `out/` from Phase 6 remains unless the client requests a rebuild.
+
 ---
 
 ## Remote client flow — `customize-ui` (fallback only)
@@ -278,7 +286,7 @@ npx cfm-sdk fetch-ui-config
 | Mistake | Fix |
 |---------|-----|
 | Killed CLI during poll | Re-run `customize-ui`; client re-submits |
-| Client quit wizard | CLI exits 0; GC done (`out/previews/` removed). **Do not** re-run wizard — skip Phase 6c, ask deploy (INPUT 4) |
+| Client quit wizard | CLI exits with abandon message; S3 GC done — re-run `customize-ui` for new session |
 | Applied from `survey-ui-config.json` while still seed | Use `.final.json` or run `confirm-ui-config` after apply |
 | Only changed primary color, ignored diff | Read **entire** `diff.md` — clients often change 20+ paths |
 | Skipped `confirm-ui-config` | Active JSON stays seed; next wizard re-open is wrong |

package/templates/docs/00-integration/wizard-post-customize-build.md

@@ -121,12 +121,6 @@ Only after H passes → ask deploy (INPUT 4). See [`aws-deploy.md`](aws-deploy.m
 
 **Do not re-run** `npx cfm-sdk export-previews` after wizard save — previews were deleted on purpose (GC). Export-previews is for **component structure changes** during Phase 5, not for applying saved config.
 
-### If client quit without saving
-
-CLI exits 0 with GC message. **Do not** re-run wizard or share a new link. Skip this runbook (no Phase 6c). Ask deploy (INPUT 4) with the Phase 6 build.
-
-**Wizard link:** parse `WIZARD_LINK=…` from CLI — never hardcode `localhost:4200`.
-
 ---
 
 ## Wizard steps → live preview keys

package/templates/docs/00-integration/wizard-preview-build-guide.md

@@ -50,6 +50,23 @@ If components use **hardcoded** colors (`bg-[#e20074]`) with no `var(--cfm-*)` h
 
 **Default for production wizard:** agent components. Use templates-only for SDK smoke tests, not client delivery.
 
+### Wizard static preview vs production survey
+
+During `npx cfm-sdk customize`, the right panel loads **SDK static HTML** from `preview-harness/previewPages.js` — not your React tree. Layout matches the original survey-page mock; **customization** is driven by `--cfm-*` CSS vars + `preview-bridge.inline.js`.
+
+| Wizard control | Static preview (iframe) | Production survey (after Phase 6c) |
+|----------------|-------------------------|-------------------------------------|
+| NPS hints + number labels | Hint text + badge colors via bridge | Copy `RatingScale.tsx` + `Question.tsx` hint row |
+| Matrix multi-row toggle | Shows/hides `[data-cfm-matrix-row-extra]` | `LikertMatrixScale` maps all `statementRows` |
+| Matrix row width + label items | `--cfm-matrix-row-width`, column label vars | `LikertMatrixScale` + `labelStyles.ts` |
+| CSAT/Rating star/numbered/radio | Theme focus ring + cell selected on mock cells | `CsatMatrixScale.tsx` + `selectionStyles.ts` |
+| Slider track + tick labels | `--cfm-slider-*` on static slider mock | `SliderMatrixScale` + `CustomSliderTrack` |
+| File upload dropzone | `--cfm-upload-*` on `.cfm-dropzone` | `FileUploadScale.tsx` |
+| Rank / heatmap | `--cfm-rank-*` / `--cfm-heatmap-pin-*` | `RankOrderScale.tsx` / `HeatmapScale.tsx` |
+| Logo size slider | `--cfm-header-logo-width/height` + `max-height` in header | `Header.tsx` via `uiConfig.ts` |
+
+**Rule:** If a wizard control updates the static preview but not localhost dev, the agent has not copied the matching template from `docs/templates/` — see [`wizard-chrome-contract.md`](wizard-chrome-contract.md).
+
 ---
 
 ## Required project artifacts (Phase 5)

package/templates/docs/00-integration/wizard-question-type-styling.md

@@ -102,11 +102,11 @@ Single-select radio: outer border = focus ring, annulus = cell selected, inner d
 | Wizard section | Config path | CSS vars | Apply in |
 |----------------|-------------|----------|----------|
 | Button style | `questionTypes.NPS_SCALE.buttonStyle` | `data-cfm-nps-button-style` | `RatingScale.tsx` |
-| Hint labels | `hintMinText`, `hintMaxText` + hint colors | `--cfm-hint-label-*` | `hintLabelStyle()` on min/max anchor row |
-| Number labels | `numberLabelMode`, per-index colors | `--cfm-number-label-mode`, `--cfm-number-mono-color`, `--cfm-number-color-{n}` | Badge row; `resolveNumberLabelColor()` for unselected |
+| Hint labels | `hintMinText`, `hintMaxText` + hint colors | `--cfm-hint-label-*` | `hintLabelStyle()` on anchor row in `Question.tsx` |
+| Number labels | `numberLabelMode`, per-index colors | `--cfm-number-*` | `resolveNumberLabelColor()` / badge row in `RatingScale.tsx` |
 | Selection | Theme → Question card | `--cfm-matrix-selected`, `--cfm-input-focus-ring` | `scaleRadioRingStyle` + `scaleRadioDotStyle` |
 
-**Removed from wizard UI:** NPS selected fill, track bar, track highlight — use Theme → Question card tokens only.
+**Removed from wizard UI:** selected fill, track bar, track highlight — NPS selection uses Theme → Question card tokens only.
 
 ### CFM_MATRIX (`CFM_matrix`, `CFM_dropdown`, `CFM_transpose`, `CFM_likert`, `CFM_bipolar`)
 

package/templates/docs/00-integration/wizard-troubleshooting.md

@@ -9,7 +9,7 @@
 | | `customize` **(default)** | `customize-ui` **(fallback)** |
 |--|---------------------------|--------------------------------|
 | **When** | Client on same machine as agent | Client on different device |
-| **URL** | `WIZARD_LINK` from CLI (dynamic port) | `WIZARD_LINK` from CLI (EC2) |
+| **URL** | `localhost:4200` | EC2 link with `session` + `secret` |
 | **Previews** | `out/previews/` on agent disk | EC2 disk |
 | **Save** | `survey-ui-config.json` immediately | Poll → `.final.json` + `.diff.md` |
 | **GC** | CLI stops → no orphans | Session cleanup on EC2 |
@@ -34,7 +34,7 @@ Footer: **"Mock preview — run customize or customize-ui…"**
 
 ### Symptom
 
-Client cannot open the `WIZARD_LINK` URL (wrong port or wrong machine)
+Client cannot open `http://localhost:4200`
 
 ### Fix
 
@@ -46,7 +46,7 @@ export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
 npx cfm-sdk customize-ui
 ```
 
-Send **only** the `WIZARD_LINK=…` line from CLI output.
+Send **only the EC2 link** from CLI output.
 
 ---
 
@@ -72,25 +72,9 @@ Wire `data-cfm-*` hooks and `--cfm-*` CSS vars per [`wizard-preview-build-guide.
 
 ---
 
-## Client quit without saving
-
-### Symptom
-
-CLI prints quit message and exits 0; `out/previews/` removed.
-
-### Agent action (mandatory)
-
-- **Do not** re-run `customize` or `customize-ui`
-- **Do not** share a new wizard link
-- Skip Phase 6c (no `survey-ui-config.json` update)
-- Ask deploy confirmation (Phase 7 / INPUT 4) with the existing Phase 6 build
-
----
-
 ## Checklist
 
 - [ ] Used **`customize`** as default when client said yes
-- [ ] Parsed **`WIZARD_LINK`** from CLI and shared only that URL
-- [ ] Waited for CLI exit 0 (save or quit)
+- [ ] Waited for `✅ UI configuration saved`
 - [ ] Phase 5 preview bridge + `data-cfm-*` wired
 - [ ] EC2 only if client on remote device

package/templates/docs/01-components/03-rating-scale.md

@@ -21,9 +21,14 @@ Render a horizontal sequence of numbered badges with traffic-light colors (NPS 0
 ## UI/UX Rules (CRITICAL)
 
 1. **Shape**: Square badges with rounded corners — not full circles
-2. **Unselected State**: Dim unselected when any item selected (`opacity-30`)
-3. **Selected State**: `border-2 border-[#e20074] shadow-md scale-105`
-4. **Tooltips**: `title={option.label}` on every badge
+2. **Interactive row**: Only the **radio track row** accepts clicks (`label` + hidden `input type="radio"`)
+3. **Selection compare**: Use `isScaleAnswerSelected(selectedValue, optionValue)` — store/compare **numbers**, not option ids
+4. **Unselected State**: Gray ring (`#d1d5db`) + white fill on track row
+5. **Selected State**: Focus ring `#e20074` (or `--cfm-input-focus-ring`) + annulus `#fbe8f3` (or `--cfm-matrix-selected`) + filled dot
+6. **Tooltips**: `title={option.label}` on every clickable cell
+7. **`buttonStyle: 'standard'`**: Radio track only — omit numbered badge row
+
+Reference implementation: [`apps/client/src/components/RatingScale.tsx`](../../../../apps/client/src/components/RatingScale.tsx)
 
 ## SDK Integration Checklist (agent)
 

package/templates/docs/02-reference/value-derivation.md

@@ -39,6 +39,8 @@ function npsValueFromOption(option: NpsScalePoint, index: number): number {
 
 NPS questions use `question.type === 'NPS_SCALE'`. Store a **number** in `SurveyAnswers`. Badge colors: traffic-light table keyed by numeric value (0–10).
 
+Compare selection with `isScaleAnswerSelected(selectedValue, npsValueFromOption(option, index))` — do not compare to `option.id`.
+
 ## MCQ
 
 - Selected answer: **`option.id`** (string), not a separate `optionValue` field

package/templates/docs/03-ui-specs/01-rating.md

@@ -31,11 +31,22 @@ When `reverseScaleOrder === true`, map visual index `i` to stored index `options
 ## Answer Mutation
 
 ```typescript
+import { isScaleAnswerSelected, npsValueFromOption } from '@/lib/surveyUiScaleUtils';
+
 const value = npsValueFromOption(option, index);
-onSelect(value) // number
+onSelect(value); // number — never option.id
 // → onAction CHANGE { questionId, answerValue: number }
+
+// Compare stored answer to option value (handles string/number drift):
+const isSelected = isScaleAnswerSelected(selectedValue, value);
 ```
 
+**Selection row (required):** Only the **radio track row** is interactive — use `<label>` + hidden `<input type="radio">` + `onChange={() => onSelect(option.value)}`. Mirror [`apps/client/src/components/RatingScale.tsx`](../../../../apps/client/src/components/RatingScale.tsx) (reference monorepo).
+
+**Pre-customization defaults:** Copy `selectionStyles.ts` with `#e20074` / `#fbe8f3` hex fallbacks so selected rings are visible before `survey-theme.css` loads. Import `survey-theme.css` in `globals.css` for full wizard tokens.
+
+**`buttonStyle`:** `standard` = radio track only (no numbered badge row). `numbered` = badge row + track. `emoji` = emoji cells.
+
 See [`02-reference/value-derivation.md`](../02-reference/value-derivation.md).
 
 ## Agent Checklist
@@ -59,6 +70,9 @@ See [`02-reference/value-derivation.md`](../02-reference/value-derivation.md).
 ### Wizard checklist
 
 - [ ] `selectionStyles.ts` imported in `RatingScale.tsx`
+- [ ] `isScaleAnswerSelected()` used for `checked` state — not raw `===` on `selectedValue`
+- [ ] Radio track: `label` + `sr-only` radio + `onChange` → `onSelect(number)` (see client `RatingScale.tsx`)
 - [ ] Selected radio: outer border + dot = focus ring; annulus = cell selected
 - [ ] Selected numbered badge: border = focus ring, fill = cell selected, text white
 - [ ] Unselected badges keep traffic-light / per-number `--cfm-number-*` colors
+- [ ] `buttonStyle: 'standard'` hides badge row; track row remains clickable

package/templates/docs/index.md

@@ -131,7 +131,7 @@ Run: `bash templates/verify-agent-build.sh`
 Only after Phase 6 passes and client says **yes**:
 
 ```bash
-npx cfm-sdk customize   # DEFAULT — prints WIZARD_LINK, WAITS until client saves or quits
+npx cfm-sdk customize   # DEFAULT — opens localhost:4200, WAITS until client saves
 ```
 
 **Phase 6b:** Client on same machine → `customize` writes `survey-ui-config.json` directly. Remote client → `customize-ui` + EC2 link (see `wizard-troubleshooting.md`). Apply per `apply-ui-config.md`.