npm - @explorer02/cfm-survey-sdk - Versions diffs - 0.2.3 → 0.2.4 - Mend

@explorer02/cfm-survey-sdk 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (94) hide show

package/dist/cli/index.js +140 -33
package/dist/cli/index.mjs +140 -33
package/dist/index.js +1 -1
package/dist/index.mjs +1 -1
package/package.json +8 -1
package/postinstall.js +8 -5
package/templates/AGENT.md +60 -19
package/templates/deploy-wizard-to-s3.sh +52 -0
package/templates/docs/00-integration/agent-execution-flow.md +281 -0
package/templates/docs/00-integration/agent-operating-contract.md +260 -0
package/templates/docs/00-integration/apply-ui-config.md +365 -0
package/templates/docs/00-integration/canonical-survey-fixtures.md +94 -0
package/templates/docs/00-integration/client-integration-guide.md +9 -7
package/templates/docs/00-integration/client-lib-folder.md +115 -0
package/templates/docs/00-integration/component-checklist.md +88 -62
package/templates/docs/00-integration/constraints.md +13 -5
package/templates/docs/00-integration/custom-field-logic-and-navigation.md +56 -0
package/templates/docs/00-integration/progress.md +4 -2
package/templates/docs/00-integration/setup.md +12 -0
package/templates/docs/00-integration/ui-customization-wizard.md +144 -0
package/templates/docs/00-integration/useSurveySDK.md +35 -1
package/templates/docs/00-integration/wizard-api.md +134 -0
package/templates/docs/00-integration/wizard-config-handoff.md +246 -0
package/templates/docs/00-integration/wizard-preview-build-guide.md +400 -0
package/templates/docs/00-integration/wizard-question-type-styling.md +195 -0
package/templates/docs/01-components/01-survey-page.md +18 -8
package/templates/docs/01-components/02-question.md +2 -2
package/templates/docs/01-components/03-rating-scale.md +12 -18
package/templates/docs/01-components/05-csat-matrix-scale.md +18 -26
package/templates/docs/01-components/06-likert-matrix-scale.md +19 -39
package/templates/docs/01-components/07-slider-matrix-scale.md +48 -33
package/templates/docs/01-components/09-custom-slider-track.md +15 -25
package/templates/docs/01-components/10-header-footer.md +23 -4
package/templates/docs/01-components/11-progress-bar.md +14 -6
package/templates/docs/01-components/19-survey-sticky-chrome.md +79 -0
package/templates/docs/01-components/README.md +2 -2
package/templates/docs/02-reference/question-types/10-slider-matrix.md +38 -26
package/templates/docs/02-reference/routing-table.md +1 -0
package/templates/docs/02-reference/value-derivation.md +1 -1
package/templates/docs/03-ui-specs/00-question-shell.md +10 -0
package/templates/docs/03-ui-specs/01-rating.md +18 -0
package/templates/docs/03-ui-specs/02-radio.md +16 -1
package/templates/docs/03-ui-specs/03-text.md +12 -1
package/templates/docs/03-ui-specs/04-csat.md +84 -50
package/templates/docs/03-ui-specs/06-slider.md +3 -1
package/templates/docs/03-ui-specs/07-matrix-cfm.md +71 -48
package/templates/docs/03-ui-specs/08-matrix-csat-rating.md +48 -18
package/templates/docs/03-ui-specs/09-slider-matrix.md +59 -32
package/templates/docs/03-ui-specs/10-file-upload.md +11 -0
package/templates/docs/03-ui-specs/11-text-and-media.md +4 -0
package/templates/docs/03-ui-specs/12-survey-chrome.md +54 -5
package/templates/docs/03-ui-specs/13-heatmap.md +12 -1
package/templates/docs/03-ui-specs/14-rank-order.md +11 -0
package/templates/docs/03-ui-specs/README.md +4 -2
package/templates/docs/03-ui-specs/shared/matrix-dropdown.md +1 -1
package/templates/docs/MANIFEST.json +162 -6
package/templates/docs/index.md +116 -117
package/templates/docs/templates/CsatMatrixScale.tsx +637 -0
package/templates/docs/templates/FileUploadScale.tsx +262 -0
package/templates/docs/templates/HeatmapScale.tsx +114 -0
package/templates/docs/templates/LikertMatrixScale.tsx +414 -0
package/templates/docs/templates/Question.tsx +3 -0
package/templates/docs/templates/RatingScale.tsx +129 -0
package/templates/docs/templates/SliderMatrixScale.tsx +248 -0
package/templates/docs/templates/SurveyStickyChrome.tsx +24 -0
package/templates/docs/templates/customFieldValues.ts +36 -0
package/templates/docs/templates/implementation_plan.md +56 -9
package/templates/docs/templates/labelStyles.ts +33 -0
package/templates/docs/templates/selectionStyles.ts +100 -0
package/templates/docs/templates/surveyUiIcons.tsx +11 -0
package/templates/docs/templates/surveyUiScaleUtils.ts +51 -0
package/templates/docs/templates/verify-agent-build.sh +119 -0
package/templates/preview-harness/preview-bridge.inline.js +201 -0
package/templates/preview-harness/previewPages.js +108 -0
package/templates/preview-harness/previewPages.ts +298 -0
package/templates/preview-harness/vite-app/src/PreviewConfigContext.tsx +67 -0
package/templates/preview-harness/vite-app/src/QuestionPreview.tsx +122 -0
package/templates/preview-harness/vite-app/src/SurveyPagePreview.tsx +75 -0
package/templates/preview-harness/vite-app/src/fixtures/questions.ts +311 -0
package/templates/preview-harness/vite-app/src/globals.css +16 -0
package/templates/preview-harness/vite-app/src/mount.tsx +9 -0
package/templates/preview-harness/vite-app/src/preview-live-overrides.css +101 -0
package/templates/preview-harness/vite-app/stubs/next-dynamic.tsx +25 -0
package/templates/preview-harness/vite-app/stubs/next-image.tsx +29 -0
package/templates/previewBridge.ts +153 -0
package/templates/survey-theme.css +295 -0
package/templates/survey-ui-config.schema.json +213 -0
package/templates/wizard-dist/assets/PreviewMock-DgHfrVeb.js +1 -0
package/templates/wizard-dist/assets/TypePanel-CFVC3Ptn.js +1 -0
package/templates/wizard-dist/assets/index-BhWM50Yu.css +1 -0
package/templates/wizard-dist/assets/index-DYK3X1e5.js +34 -0
package/templates/wizard-dist/assets/vendor-BwkXDkd3.js +17 -0
package/templates/wizard-dist/index.html +20 -0
package/templates/wizard.html +13 -1129

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

@@ -0,0 +1,400 @@
+# Wizard Live Preview — Client Build Guide
+> **Read during Phase 5 (BUILD) — mandatory.** Wizard **run** (Phase 6b) is optional; this contract is required for every agent build.
+> Pipeline: [`agent-execution-flow.md`](agent-execution-flow.md).
+Related docs:
+- [`ui-customization-wizard.md`](ui-customization-wizard.md) — wizard flow and CLI
+- [`apply-ui-config.md`](apply-ui-config.md) — applying final `survey-ui-config.json` after wizard
+- [`wizard-api.md`](wizard-api.md) — EC2 `/wizard/*` API
+- [`03-ui-specs/12-survey-chrome.md`](../03-ui-specs/12-survey-chrome.md) — chrome layout spec
+---
+## Why client code matters for live preview
+The wizard does **not** re-render your React app. It loads **static preview pages** built from your real `src/components/` (`npx cfm-sdk export-previews`), then sends token updates into each preview iframe via `postMessage`.
+```mermaid
+sequenceDiagram
+  participant Agent as Agent_build
+  participant CLI as export_previews
+  participant S3 as S3_previews
+  participant Wizard as Wizard_SPA
+  participant Iframe as Preview_iframe
+  Agent->>Agent: Build components with token contract
+  Agent->>CLI: customize-ui / export-previews
+  CLI->>S3: Upload HTML + JS + CSS
+  Wizard->>Iframe: Load chrome / MCQ_single / etc.
+  Wizard->>Iframe: postMessage SNAPSHOT + DELTA
+  Iframe->>Iframe: Apply --cfm-* vars + content patches
+```
+If components use **hardcoded** colors (`bg-[#e20074]`) with no `var(--cfm-*)` hooks, the preview **looks correct initially** but **does not change** when the client drags color pickers or edits identity fields (unless a harness override happens to match your class names).
+**The same token contract is used after the wizard** when you apply `survey-ui-config.json` to production (Phase 6c). Building for live preview = building for accurate customization end-to-end.
+---
+## Two preview modes (know which you get)
+| Mode | CLI | Preview source | Live updates | Fidelity |
+|------|-----|----------------|--------------|----------|
+| **Agent components** (default) | `export-previews` | Copies your `src/components/` + Vite build | Full **only if** token contract below is followed | Matches real survey UI |
+| **Template harness only** | `export-previews --use-templates-only` | SDK static HTML harness | Always live | Generic SDK chrome — not your implementation |
+**Default for production wizard:** agent components. Use templates-only for SDK smoke tests, not client delivery.
+---
+## Required project artifacts (Phase 5)
+Create these **before** the client opens the wizard:
+| File | Purpose |
+|------|---------|
+| `src/styles/survey-theme.css` | All `--cfm-*` CSS custom properties (defaults from mockup) |
+| `survey-ui-config.json` (draft) | Seeds wizard form fields from agent branding |
+| `src/lib/previewBridge.ts` | Live bridge in **local dev** (`npx cfm-sdk customize`) — copy from `templates/previewBridge.ts` |
+| `src/components/PreviewBridgeInit.tsx` | Mount bridge once in `layout.tsx` (local dev only) |
+Import theme in `globals.css`:
+```css
+@import "tailwindcss";
+@import "../styles/survey-theme.css";
+```
+Wire bridge in root layout (client app only — not uploaded to wizard):
+```tsx
+import { PreviewBridgeInit } from '@/components/PreviewBridgeInit';
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <PreviewBridgeInit />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+**Wizard iframes** embed `preview-bridge.inline.js` at export time — you do not ship `previewBridge.ts` inside preview HTML.
+---
+## The token contract (two layers)
+### Layer 1 — CSS variables (`--cfm-*`)
+Wizard sends CSS custom properties on `:root` (SNAPSHOT on tab load, DELTA during drag).
+**Rule:** Any brand color, radius, spacing, or chrome dimension the client can edit in the wizard must be consumed via `var(--cfm-…)` in components or shared CSS — **not** hardcoded hex in Tailwind arbitrary values.
+Copy the full default set from [`templates/survey-theme.css`](../../survey-theme.css) and extend with per-type vars your survey uses.
+**Good — responds to wizard color changes:**
+```tsx
+<div
+  className="h-3 rounded-full transition-all"
+  style={{
+    width: `${progress}%`,
+    backgroundColor: 'var(--cfm-progress-fill, var(--cfm-primary))',
+  }}
+/>
+```
+**Avoid for wizard-controlled colors:**
+```tsx
+<div className="bg-[#e20074] h-3 rounded-full" />
+```
+**Tailwind + tokens pattern** (when you prefer classes):
+```tsx
+<button
+  className="rounded-md px-6 py-2 text-sm font-semibold hover:opacity-90"
+  style={{
+    backgroundColor: 'var(--cfm-primary)',
+    color: 'var(--cfm-button-text)',
+    borderRadius: 'var(--cfm-border-radius)',
+  }}
+>
+  {nextLabel}
+</button>
+```
+Or define utilities in `survey-theme.css`:
+```css
+.cfm-btn-primary {
+  background-color: var(--cfm-primary);
+  color: var(--cfm-button-text);
+  border-radius: var(--cfm-border-radius);
+}
+```
+### Layer 2 — Content hooks (`data-cfm-*`)
+Wizard sends a **content patch** for text, logo URL, layout toggles, and footer links. The preview bridge updates DOM nodes matching these attributes.
+| Attribute | Wizard source | Apply to |
+|-----------|---------------|----------|
+| `data-cfm-logo` | Logo step / `global.logo` | `<img>` in Header, Footer — **image logo mode** |
+| `data-cfm-logo-text` | Identity → company name (when no image) | Text fallback inside logo slot — **text logo mode** |
+| `data-cfm-company` | Identity → company name | Header company text (separate from logo slot) |
+| `data-cfm-survey-title` | Identity → survey title | Main heading, chrome preview |
+| `data-cfm-thank-you` | Identity → thank-you message | End page message |
+| `data-cfm-copyright` | Footer step | Footer copyright line |
+| `data-cfm-footer-links` | Footer step | Footer `<nav>` container (links injected) |
+| `data-cfm-btn-next` | Layout → button labels | Next / Submit button |
+| `data-cfm-btn-back` | Layout → button labels | Back button |
+| `data-cfm-progress` | Layout → show progress bar | Wrapper around `ProgressBar` |
+**Image logo (file in `public/`):**
+```tsx
+<div className="cfm-header-logo-slot flex shrink-0 items-center justify-center">
+  <img
+    data-cfm-logo
+    src="/telekom-logo.svg"
+    alt="Company"
+    className="object-contain"
+    style={{
+      padding: 'var(--cfm-header-logo-padding)',
+      width: '100%',
+      height: '100%',
+    }}
+  />
+  {/* Hidden until wizard has no uploaded image — bridge toggles visibility */}
+  <span data-cfm-logo-text className="hidden font-semibold">
+    Company Name
+  </span>
+</div>
+```
+**Text-only logo (CSS-built brand, no `public/` image):**
+```tsx
+<div className="cfm-header-logo-slot flex shrink-0 items-center justify-center">
+  <span
+    data-cfm-logo-text
+    className="font-semibold"
+    style={{
+      color: 'var(--cfm-header-company-color)',
+      fontSize: 'var(--cfm-header-company-size)',
+      fontWeight: 'var(--cfm-header-company-weight)',
+    }}
+  >
+    Company Name
+  </span>
+</div>
+```
+Do **not** add unrelated `public/logo_*` files during agent build — the CLI seeds the wizard from `Header.tsx` (`data-cfm-logo` src) or `data-cfm-logo-text`, not the newest file in `public/`. After the client uploads a logo in the wizard, `survey-ui-config.json` stores `global.logo.fileName`; the next wizard session uses **only that saved file**.
+**Example SurveyPage nav buttons:**
+```tsx
+<button data-cfm-btn-back type="button" onClick={onBack}>
+  Back
+</button>
+<button
+  data-cfm-btn-next
+  type="button"
+  style={{ backgroundColor: 'var(--cfm-primary)', color: 'var(--cfm-button-text)' }}
+  onClick={onNext}
+>
+  Next
+</button>
+```
+---
+## Per-component checklist
+### Chrome (always)
+| Component | CSS vars | data-cfm-* |
+|-----------|----------|------------|
+| `Header.tsx` | `--cfm-header-*`, `--cfm-primary` (logo box) | `data-cfm-logo`, `data-cfm-company` |
+| `Footer.tsx` | `--cfm-footer-*` | `data-cfm-logo`, `data-cfm-copyright`, `data-cfm-footer-links` |
+| `ProgressBar.tsx` | `--cfm-progress-*` | wrap parent with `data-cfm-progress` |
+| `SurveyStickyChrome.tsx` | header + progress vars | same as Header / progress |
+| `IntroPage.tsx` | page bg, card, primary button | `data-cfm-survey-title` on main heading |
+| `EndPage.tsx` | same | `data-cfm-thank-you` on thank-you copy |
+| `SurveyPage.tsx` | `--cfm-max-width`, layout toggles | `data-cfm-btn-next`, `data-cfm-btn-back`; conditional render for `showHeader`, `showFooter`, `showProgressBar` from config at apply time |
+### Question scales (per type in survey)
+Full per-type wizard control mapping: [`wizard-question-type-styling.md`](wizard-question-type-styling.md).
+Use vars from `survey-theme.css` for cosmetic tokens the wizard exposes per type. See [`apply-ui-config.md`](apply-ui-config.md) token → file mapping.
+| Type | Key vars | Component |
+|------|----------|-----------|
+| MCQ | `--cfm-mcq-*` | `Question.tsx` MCQ branch / `OptionItem` |
+| NPS_SCALE | `--cfm-nps-*` | `RatingScale.tsx` |
+| CFM_MATRIX | `--cfm-matrix-*` | `LikertMatrixScale.tsx` |
+| CSAT_MATRIX | `--cfm-csat-*` | `CsatMatrixScale.tsx` |
+| RATING_MATRIX | `--cfm-star-*`, `--cfm-badge-*` | `RatingScale.tsx` / `CsatMatrixScale.tsx` |
+| SLIDER_MATRIX | `--cfm-slider-*` | `SliderMatrixScale.tsx`, `CustomSliderTrack.tsx` |
+| FILE_UPLOAD | `--cfm-upload-*` | `FileUploadScale.tsx` |
+| HEATMAP | `--cfm-heatmap-*` | `HeatmapScale.tsx` |
+| RANK_ORDER | `--cfm-rank-*` | `RankOrderScale.tsx` |
+**Do not change** dispatch logic, answer shapes, or SDK visibility helpers for wizard compatibility.
+---
+## Draft `survey-ui-config.json` (wizard seed)
+After branding from the client prompt, write a **draft** `survey-ui-config.json` at project root so `customize-ui` seeds the wizard with your build — not generic Sprinklr defaults.
+CLI resolution order:
+1. `./survey-ui-config.json` — including wizard-saved `global.logo.fileName` (re-open uses uploaded logo only)
+2. Parsed `src/styles/survey-theme.css`
+3. `implementation_plan.md` branding hints
+4. `Header.tsx` — `data-cfm-logo` image `src` (e.g. `/telekom-logo.svg`) or `data-cfm-logo-text` for text-only builds
+5. SDK defaults
+**Logo seed rules for agents:**
+- **Image logo:** put file in `public/`, reference exact path on `<img data-cfm-logo src="/your-logo.svg" />`. CLI base64-encodes that file for the wizard preview.
+- **Text logo:** use `<span data-cfm-logo-text>` in the logo slot (CSS shapes optional). Omit `data-cfm-logo` img. Wizard shows company text until client uploads an image.
+- **After wizard upload:** `global.logo.fileName` in saved config takes precedence — do not fall back to `Header.tsx` or scan `public/logo_*`.
+Debug without opening wizard:
+```bash
+npx cfm-sdk resolve-ui-config --write
+```
+Keep draft JSON and `survey-theme.css` **in sync** (same primary color, title, company name).
+---
+## How `export-previews` uses your code
+When the client opts in, `customize-ui` runs `export-previews`:
+1. Copies `src/components/`, `src/lib/`, `public/`, `survey-theme.css` into a temp Vite harness
+2. Stubs `next/image` and `next/dynamic` for static build
+3. Builds one HTML page per preview key (`header`, `chrome`, `MCQ_single`, …) with canonical fixtures
+4. Injects `preview-bridge.inline.js` into each `index.html`
+5. Uploads each preview page to S3 via EC2 presigned PUTs
+6. Prints the **deployed wizard link** for the client:
+```
+http://43.204.26.213:3000/wizard-app/index.html?session=<uuid>&secret=<hex>
+```
+7. Wizard iframes load previews via EC2 proxy (`GET /wizard/preview/:sessionId/:component/...`)
+**Agent handoff:** after step 5–6, copy the printed link and send it to the client. The client customizes on EC2 only — not localhost.
+Preview keys match wizard steps — see [`ui-customization-wizard.md`](ui-customization-wizard.md) step table.
+**Implication:** Wizard previews are a **snapshot of your component source at export time**. Re-run `customize-ui` (or `export-previews` + re-upload) after you change component structure.
+---
+## Live update protocol (wizard ↔ iframe)
+| Message | When | Payload |
+|---------|------|---------|
+| `CFM_UI_CONFIG_SNAPSHOT` | Iframe load, tab change, text debounce | Full `cssVars` + `contentPatch` |
+| `CFM_UI_CONFIG_DELTA` | Color sliders, drag (~60fps) | Partial `cssVars` only |
+Content patches apply to `[data-cfm-*]` nodes. CSS vars apply to `:root`. Components must **read** those vars (Layer 1) for visual updates.
+---
+## Agent build checklist (blocking for full live preview)
+Add to `implementation_plan.md` §5 and verify before Phase 6b:
+- [ ] `src/styles/survey-theme.css` exists with full `--cfm-*` set for types in survey
+- [ ] Draft `survey-ui-config.json` matches theme + identity from mockup
+- [ ] `previewBridge.ts` + `PreviewBridgeInit` wired for local `customize` dev
+- [ ] **No hardcoded brand hex** in chrome or scale components for wizard-controlled tokens
+- [ ] Header: `data-cfm-logo`, `data-cfm-company` + header CSS vars
+- [ ] Footer: `data-cfm-copyright`, `data-cfm-footer-links`, footer CSS vars
+- [ ] ProgressBar: `--cfm-progress-fill` / `--cfm-progress-track`; parent `data-cfm-progress`
+- [ ] SurveyPage buttons: `data-cfm-btn-next`, `data-cfm-btn-back`
+- [ ] Intro/End: `data-cfm-survey-title`, `data-cfm-thank-you` where applicable
+- [ ] Per-type scale vars wired per `apply-ui-config.md` mapping
+- [ ] `npx cfm-sdk export-previews` succeeds from project root
+- [ ] Grep: no `not yet implemented` stubs
+Quick self-test (local):
+```bash
+npx cfm-sdk export-previews
+# Open out/previews/chrome/index.html in browser; in devtools console:
+# postMessage({ type: 'CFM_UI_CONFIG_SNAPSHOT', cssVars: { '--cfm-primary': '#0066cc' }, contentPatch: { surveyTitle: 'Test Title' }}, '*')
+# Title and primary-colored surfaces should update
+```
+---
+## Common mistakes
+| Mistake | Symptom in wizard | Fix |
+|---------|-------------------|-----|
+| Hardcoded `bg-[#brand]` everywhere | Preview frozen on theme step | Use `var(--cfm-primary)` or `.cfm-btn-primary` |
+| `survey-theme.css` missing or minimal | Seed config wrong; few vars update | Copy full template `survey-theme.css` |
+| No `data-cfm-survey-title` | Identity edits don't change preview text | Add attribute to visible headings |
+| Logo `<Image>` without `data-cfm-logo` | Logo step doesn't update preview | Add `data-cfm-logo` to img |
+| Only Phase 6c tokenization | Worked after wizard, not during | Tokenize in Phase 5 (this guide) |
+| Skipped `export-previews` after component edits | Wizard shows old UI | Re-run `customize-ui` |
+---
+## Phase flow summary
+| Phase | Agent action |
+|-------|----------------|
+| **5 BUILD** | Implement components per this guide + UI specs; draft config + theme |
+| **6 VERIFY** | `npm run build`, verify script, localhost preview |
+| **6b WIZARD** (optional) | Client says yes → `customize-ui` → **wait** for submit → read `.diff.md` |
+| **6c APPLY** | Apply **all** paths from `survey-ui-config.final.json` per [`wizard-config-handoff.md`](wizard-config-handoff.md) + [`apply-ui-config.md`](apply-ui-config.md) → `confirm-ui-config` |
+| **7 DEPLOY** | Full static build upload (separate from wizard preview files) |
+---
+## Copy-from-template shortcut
+Fastest path to full live preview: start from SDK portable templates in `templates/docs/templates/`, then customize branding using **tokens from day one** rather than hardcoded mockup hex. Extend tokens as you deviate from defaults.
+Templates to prioritize for token wiring:
+- `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `SurveyStickyChrome.tsx`
+- Scale components listed in [`component-checklist.md`](component-checklist.md)
+---
+## CLI reference
+```bash
+# Build preview pages only (from project root)
+npx cfm-sdk export-previews
+# Template harness smoke test (not client UI)
+npx cfm-sdk export-previews --use-templates-only
+# Full AWS wizard session
+export CFM_INSTANCE_ID="..." CFM_DEPLOY_API_BASE="http://your-ec2:3000"
+npx cfm-sdk customize-ui
+# Inspect seed config
+npx cfm-sdk resolve-ui-config --write
+```

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

@@ -0,0 +1,195 @@
+# Wizard Question-Type Styling
+> **Read during Phase 5 (BUILD) — mandatory.** Alongside [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) and [`apply-ui-config.md`](apply-ui-config.md).
+> Pipeline: [`agent-execution-flow.md`](agent-execution-flow.md).
+**Do not change** `Question.tsx` dispatch logic, answer shapes, SDK visibility helpers, or matrix routing algorithms — styling only.
+---
+## Shared selection pattern (Question card theme)
+Wizard **Theme & Colors → Question card** exposes two tokens used across radio/scale selections:
+| Wizard field | CSS variable | Visual role |
+|--------------|--------------|-------------|
+| **Cell selected color** | `--cfm-matrix-selected` | Fill **between** outer ring and inner dot (annulus); also solid numbered/star cell background when selected |
+| **Focus ring** | `--cfm-input-focus-ring` | Outer circle **border** + inner **dot** color |
+Also mapped (for MCQ compatibility): `--cfm-mcq-selected-accent` ← cell selected color.
+Copy [`templates/selectionStyles.ts`](../templates/selectionStyles.ts) → `src/lib/surveyUi/selectionStyles.ts` and use in scale components:
+```tsx
+import {
+  scaleRadioRingStyle,
+  scaleRadioDotStyle,
+  matrixRadioRingStyle,
+  matrixRadioDotStyle,
+  cellSelectedVar,
+  focusRingVar,
+} from '@/lib/surveyUi/selectionStyles';
+```
+**Selected radio cell structure:**
+```
+┌─ focus ring (border) ─────────┐
+│  cell selected (annulus)    │
+│       ● focus ring (dot)    │
+└─────────────────────────────┘
+```
+**Numbered badge when selected:** border = focus ring, background = cell selected, text = white.
+**Unselected numbered badges:** keep traffic-light / per-number colors from `--cfm-number-*` vars (do not override with theme tokens).
+---
+## Shared label helpers
+Copy [`templates/labelStyles.ts`](../templates/labelStyles.ts) → `src/lib/surveyUi/labelStyles.ts`.
+| Helper | CSS vars | Wizard control |
+|--------|----------|----------------|
+| `hintLabelStyle()` | `--cfm-hint-label-color`, `--cfm-hint-label-bg` | Hint labels (min/max anchors) |
+| `matrixColumnLabelStyle()` | `--cfm-matrix-column-label-*` | CFM matrix column header items |
+| `csatColumnLabelStyle()` | `--cfm-csat-column-label-*` | CSAT/Rating column header items |
+| `sliderTickLabelStyle()` | `--cfm-slider-tick-label-*` | Slider matrix tick label items |
+**CFM matrix:** column headers are **label items** only — not hint labels, not number labels.
+**CSAT/Rating:** per-format controls differ — see per-type table below.
+---
+## Per-type wizard controls → CSS vars → components
+### MCQ (`MCQ_single`, `MCQ_multiple`)
+| Wizard section | Config path | CSS vars | Apply in |
+|----------------|-------------|----------|----------|
+| Option style | `questionTypes.MCQ.optionStyle` | `data-cfm-mcq-style` on `:root` | `Question.tsx` MCQ branch |
+| Option gap / radius / padding | `questionTypes.MCQ.*` | `--cfm-mcq-option-gap`, `--cfm-mcq-border-radius`, `--cfm-mcq-card-padding` | MCQ option cards |
+| Selection | Theme → Question card | `--cfm-input-focus-ring`, `--cfm-matrix-selected`, `--cfm-mcq-selected-bg` | Radio: ring border + annulus + dot; checkbox: ring border + fill |
+Single-select radio: outer border = focus ring, annulus = cell selected, inner dot = focus ring.
+### TEXTFIELD (`TEXTFIELD_short`, `TEXTFIELD_long`)
+| Wizard section | CSS vars |
+|----------------|----------|
+| Input radius, border, placeholder | `--cfm-input-radius`, `--cfm-input-border`, `--cfm-input-placeholder` |
+| Focus | `--cfm-input-focus-ring` on focus outline |
+### NPS_SCALE (`NPS_SCALE`)
+| Wizard section | Config path | CSS vars | Apply in |
+|----------------|-------------|----------|----------|
+| Button style | `questionTypes.NPS_SCALE.buttonStyle` | `data-cfm-nps-button-style` | `RatingScale.tsx` |
+| Track | `selectedFill`, `trackBar`, `trackHighlight` | `--cfm-nps-selected-fill`, `--cfm-nps-track-bar`, `--cfm-nps-track-highlight` | Track bar background |
+| Hint labels | `hintMinText`, `hintMaxText` + hint colors | `--cfm-hint-label-*` | Min/max anchor row |
+| Number labels | `numberLabelMode`, per-index colors | `--cfm-number-label-mode`, `--cfm-number-mono-color`, `--cfm-number-color-{n}` | Badge row above radios |
+| Selection | Theme → Question card | `--cfm-matrix-selected`, `--cfm-input-focus-ring` | `scaleRadioRingStyle` + `scaleRadioDotStyle` |
+### CFM_MATRIX (`CFM_matrix`, `CFM_dropdown`, `CFM_transpose`, `CFM_likert`, `CFM_bipolar`)
+| Wizard section | CSS vars | Apply in |
+|----------------|----------|----------|
+| Row label width | `--cfm-matrix-row-width` | `LikertMatrixScale.tsx` |
+| Bipolar column width | `--cfm-matrix-bipolar-width` | Bipolar anchor column |
+| Label items | `--cfm-matrix-column-label-color`, `--cfm-matrix-column-label-bg` | Column header row only |
+| Selection | `--cfm-matrix-selected`, `--cfm-input-focus-ring` | `matrixRadioRingStyle` / custom cells; dropdown option ring |
+**No** per-type accent/ring overrides in CFM — use Question card tokens only.
+### CSAT_MATRIX (`CSAT_carousel`, `CSAT_dropdown`, `CSAT_emoji`, `CSAT_graphics`, `CSAT_numbered`, `CSAT_star`)
+| Format | Wizard sections | Key styling |
+|--------|-----------------|-------------|
+| **emoji** | Emoji size, unselected opacity, label items | `emojiSizeStyle()`, `unselectedOpacityStyle()`, emoji ring = focus ring on select |
+| **star** | Emoji size, unselected opacity, label items | Stars: selected color = `cellSelectedVar` |
+| **numbered** | Number labels, label items | Selected cell: border focus ring, fill cell selected |
+| **radio** (grid) | Label items | Horizontal radio grid; `matrixRadioRingStyle` |
+| **graphics** (slider) | Label items, tick labels | `CustomSliderTrack` thumb: ring + annulus + dot pattern |
+| **carousel** | Label items | Dot indicators: cell selected when active |
+| **dropdown / selectbox** | Label items | `MatrixDropdown` + list radio pattern |
+**Removed from wizard UI (do not wire):** per-type accent, selected ring, badge color, hint labels section on CSAT formats that use label items only.
+### RATING_MATRIX (`RATING_radio`, `RATING_emoji`, `RATING_graphics`, `RATING_slider`, `RATING_star`, `RATING_numbered`)
+Same CSAT patterns where formats overlap. **Radio format:** horizontal grid (not vertical list). Use CSAT matrix component paths with star/numbered/emoji/graphics variants.
+### SLIDER_MATRIX (`SLIDER_matrix`)
+| Wizard section | CSS vars | Apply in |
+|----------------|----------|----------|
+| Track / thumb / tick | `--cfm-slider-track`, `--cfm-slider-thumb`, `--cfm-slider-tick` | `SliderMatrixScale`, `CustomSliderTrack` |
+| Row band | `--cfm-slider-row-band` | Statement row background |
+| Tick label items | `--cfm-slider-tick-label-*` | Header tick labels |
+| Tick number labels | `--cfm-number-*` | Colored number badges |
+| Thumb selection | `--cfm-matrix-selected`, `--cfm-input-focus-ring` | Knob: border + annulus + center dot |
+**No** hint labels section in wizard for slider matrix — use tick label items.
+### FILE_UPLOAD (`FILE_UPLOAD`)
+| Wizard section | CSS vars | Apply in |
+|----------------|----------|----------|
+| Dropzone border style | `--cfm-upload-border-style`, `data-cfm-dropzone-style` | `FileUploadScale.tsx` |
+| Border color | `--cfm-upload-border-color` | Dropzone border (not hardcoded `#d1d5db`) |
+| Fill / padding | `--cfm-upload-fill`, `--cfm-upload-padding` | Dropzone background |
+| Focus/hover | `--cfm-input-focus-ring`, `--cfm-mcq-selected-bg` | Focus border + drag-active bg |
+### HEATMAP (`HEATMAP`)
+| Wizard section | CSS vars |
+|----------------|----------|
+| Pin color / border / size | `--cfm-heatmap-pin`, pin border config, `--cfm-heatmap-pin-size` |
+### RANK_ORDER (`RANK_drag`, `RANK_dropdown`)
+| Variant | Wizard controls | CSS vars |
+|---------|-----------------|----------|
+| Drag | Item bg, handle, badge, gap, padding | `--cfm-rank-item-bg`, `--cfm-rank-handle`, `--cfm-rank-badge`, `--cfm-rank-item-gap`, `--cfm-rank-item-padding` |
+| Dropdown | Item bg, select border, badge | `--cfm-rank-select-border`, etc. |
+| Focus on inputs | Theme focus ring | `--cfm-input-focus-ring` on focus |
+**Rank drag:** ensure `interactionMode: 'dragAndDrop'` in fixture/survey — do not change dispatch.
+### TEXT_AND_MEDIA
+Use `--cfm-media-max-width`, `--cfm-media-radius` from theme.
+---
+## Live preview re-render (export-previews harness)
+Components that read CSS vars at render time should import `useLiveThemeTick` from preview harness or bump state when wizard sends `CFM_UI_CONFIG_SNAPSHOT` / `DELTA`. The **export-previews** Vite harness includes this; production client apps only need it if running local `npx cfm-sdk customize`.
+For production builds after wizard: syncing `survey-theme.css` is sufficient — no `previewLiveTick` required.
+---
+## Agent checklist (per survey type)
+For each type in survey inventory:
+- [ ] Scale component uses `var(--cfm-*)` for every wizard-exposed token (no hardcoded brand hex)
+- [ ] Radio/scale selections use `selectionStyles.ts` pattern (focus ring + cell selected)
+- [ ] Matrix column headers use `labelStyles.ts` (label items — not conflated with hint/number labels)
+- [ ] NPS/numbered formats use `resolveNumberLabelColor` from `surveyUiScaleUtils.ts` for **unselected** badges only
+- [ ] File upload dropzone uses `--cfm-upload-border-color`
+- [ ] `Question.tsx` dispatch unchanged; cosmetic inline styles only
+- [ ] `npx cfm-sdk export-previews` succeeds after styling wiring
+---
+## Related files
+| File | Purpose |
+|------|---------|
+| [`templates/selectionStyles.ts`](../templates/selectionStyles.ts) | Copy to client `src/lib/surveyUi/` |
+| [`templates/labelStyles.ts`](../templates/labelStyles.ts) | Copy to client `src/lib/surveyUi/` |
+| [`templates/survey-theme.css`](../../survey-theme.css) | Full `--cfm-*` defaults |
+| [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) | Chrome + bridge contract |
+| [`apply-ui-config.md`](apply-ui-config.md) | Post-wizard apply workflow |

package/templates/docs/01-components/01-survey-page.md CHANGED Viewed

@@ -1,7 +1,8 @@
 # Survey Page Orchestrator Architectural Blueprint
 > **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
-> **Reference implementation:** `apps/client/src/components/SurveyPage.tsx`
+> **Portable template:** implement from `docs/templates/` + [`agent-execution-flow.md`](../00-integration/agent-execution-flow.md) Phase 5
+> **Monorepo snapshot (do not copy):** `apps/client/src/components/SurveyPage.tsx`
 > **Target Component**: `SurveyPage`
 > **Role**: Wires `useSurveySDK` to the UI — loading/error states, phase routing, pagination, submission.
@@ -13,9 +14,9 @@ Act as the **phase state machine** for the survey. Never render questions direct
 ```tsx
 import type { CustomFieldValueMap } from '@explorer02/cfm-survey-sdk';
+import { CUSTOM_FIELD_VALUES } from '@/lib/customFieldValues';
 const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'Customer' }; // Must be outside component!
-const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {}; // Populate when survey uses custom-field logic
 export default function SurveyPage() {
   const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>();
@@ -46,6 +47,14 @@ export default function SurveyPage() {
 See [`client-integration-guide.md`](../00-integration/client-integration-guide.md) for lifecycle effects (`SCROLL`, `RECORD_QUESTION_VIEW`).
+When fetched survey contains any `_c_…` custom field id in logic rules:
+- [ ] Copy [`templates/customFieldValues.ts`](../templates/customFieldValues.ts) → `src/lib/customFieldValues.ts`
+- [ ] Populate map from CRM/transaction payload
+- [ ] Import `CUSTOM_FIELD_VALUES` in `SurveyPage` (do not define inline empty `{}`)
+See [`client-lib-folder.md`](../00-integration/client-lib-folder.md) and [`custom-field-logic-and-navigation.md`](../00-integration/custom-field-logic-and-navigation.md).
 ## Render Order (MANDATORY)
 Handle in this order:
@@ -73,12 +82,13 @@ See `14-intro-page.md`, `15-end-page.md`, `16-paused-page.md`.
 ### 3. Active content (`phase.kind === 'content'`)
-1. `Header`
-2. `ProgressBar` (`state.progressPercentage`) — see `00-integration/progress.md`
-3. `LanguageSelector`
-4. Question map (below)
-5. Navigation buttons (below)
-6. `Footer`
+1. `SurveyStickyChrome` — sticky `Header` + `ProgressBar` (`state.progressPercentage`); see `19-survey-sticky-chrome.md` and `00-integration/progress.md`
+2. `main`: `LanguageSelector`
+3. Question map (below)
+4. Navigation buttons (below)
+5. `Footer`
+Use standalone `Header` (no sticky chrome) on intro, end, paused, loading, and terminal phases.
 ## The Question Map

package/templates/docs/01-components/02-question.md CHANGED Viewed

@@ -2,7 +2,7 @@
 > **UI spec (authoritative):** `03-ui-specs/00-question-shell.md`
 > **Canonical template:** [`templates/Question.tsx`](../templates/Question.tsx) — copy verbatim, then create imported components
-> **Monorepo reference:** `apps/client/src/components/Question.tsx`
+> **Monorepo snapshot (illustrative only):** `apps/client/src/components/Question.tsx`
 > **Target Component**: `Question`
 ## Start Here (CRITICAL)
@@ -77,7 +77,7 @@ Store matrix cell values as column **`id`** via `matrixColumnStoredValue(col)`
 ### MCQ (`QUESTION_TYPE.MCQ`)
 - [ ] Filter options with `getVisibleMcqOptionsForAnswers` before render
-- [ ] Store `option.id`; support `isMultiSelect` array shape when configured
+- [ ] Store `option.id`; use `selectionMode` (`single` | `multiple`) — not `isMultiSelect`
 - [ ] onAction CHANGE: `{ questionId, answerValue: optionId | optionId[] }`
 ### TEXTFIELD (`QUESTION_TYPE.TEXTFIELD`)