@explorer02/cfm-survey-sdk 0.2.5 → 0.2.7

package/templates/docs/00-integration/component-checklist.md

@@ -2,7 +2,7 @@
 
 > **Blocking gate before Phase 5 (BUILD).** Read [`agent-operating-contract.md`](agent-operating-contract.md) §2–§3 first — do not invent files or paths from memory.
 >
-> **Wizard-ready build (Phase 5 — mandatory):** Every agent build wires live-preview contract per [`agent-execution-flow.md`](agent-execution-flow.md), [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md), and [`wizard-question-type-styling.md`](wizard-question-type-styling.md) — `var(--cfm-*)`, `data-cfm-*` hooks, `selectionStyles.ts`, `labelStyles.ts`, draft `survey-ui-config.json`. Running the wizard (Phase 6b) is optional; wizard-ready artifacts are not.
+> **Wizard-ready build (Phase 5 — mandatory):** Copy chrome templates from [`wizard-chrome-contract.md`](wizard-chrome-contract.md) (`Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `SurveyStickyChrome.tsx`, etc.) and wire live-preview contract per [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) and [`wizard-question-type-styling.md`](wizard-question-type-styling.md) — `var(--cfm-*)`, `data-cfm-*` hooks, `selectionStyles.ts`, `labelStyles.ts`, draft `survey-ui-config.json`. Running the wizard (Phase 6b) is optional; wizard-ready artifacts are not.
 >
 > Read [`canonical-survey-fixtures.md`](canonical-survey-fixtures.md) when matrix/slider labels are missing.
 
@@ -108,7 +108,9 @@ bash templates/verify-agent-build.sh
 
 ## Step 4: Wizard-ready build (Phase 5 — mandatory)
 
-Read: [`agent-execution-flow.md`](agent-execution-flow.md), [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md), [`wizard-question-type-styling.md`](wizard-question-type-styling.md)
+Read: [`wizard-chrome-contract.md`](wizard-chrome-contract.md), [`agent-execution-flow.md`](agent-execution-flow.md), [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md), [`wizard-question-type-styling.md`](wizard-question-type-styling.md)
+
+- [ ] **Copied** `templates/docs/templates/Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `SurveyStickyChrome.tsx`, `LanguageSelector.tsx`, `PreviewBridgeInit.tsx` (do not use `apps/client` as reference)
 
 - [ ] `src/styles/survey-theme.css` with full `--cfm-*` set (copy from `templates/survey-theme.css`)
 - [ ] `selectionStyles.ts` + `labelStyles.ts` in `src/lib/surveyUi/`
@@ -116,7 +118,7 @@ Read: [`agent-execution-flow.md`](agent-execution-flow.md), [`wizard-preview-bui
 - [ ] `previewBridge.ts` + `PreviewBridgeInit` in root layout
 - [ ] Header/Footer/ProgressBar/SurveyPage use `var(--cfm-*)` — no hardcoded brand hex for wizard-controlled tokens
 - [ ] `data-cfm-logo` / `data-cfm-logo-text`, `data-cfm-company`, `data-cfm-survey-title`, `data-cfm-btn-next`, `data-cfm-btn-back`, `data-cfm-thank-you` on chrome
-- [ ] **Layout toggles:** `data-cfm-progress`, `[data-cfm-question-number]`, `[data-cfm-required]`, `.cfm-footer` — see `wizard-troubleshooting.md` §3
+- [ ] **Layout toggles:** `data-cfm-progress`, `data-cfm-question-number`, `data-cfm-required`, `cfm-footer`, `cfm-header` — see [`wizard-chrome-contract.md`](wizard-chrome-contract.md)
 - [ ] Per-type scale vars per `wizard-question-type-styling.md` for **all 11 types** (wizard exports all; survey inventory may be smaller)
 - [ ] Selection pattern: focus ring = outer border + inner dot; cell selected = annulus fill
 - [ ] `npx cfm-sdk export-previews` succeeds from project root (when previews needed for AWS wizard)

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

@@ -15,7 +15,7 @@ This is the **recommended default** because it:
 - 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 automatically when the CLI exits (no orphan S3 garbage)
+- Cleans up local `out/previews/` when client quits without saving (`POST /api/wizard-quit`) or when CLI exits (Ctrl+C)
 - Updates live previews via the same iframe + preview bridge as production
 
 **Agent script after client says yes:**

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

@@ -0,0 +1,284 @@
+# Wizard Chrome Contract — Required DOM + CSS Hooks
+
+> **Mandatory Phase 5.** If any hook is missing, wizard live preview fails for that control — even though the survey may look fine in localhost dev without the wizard open.  
+> **Copy-first templates:** [`templates/Header.tsx`](../templates/Header.tsx), [`Footer.tsx`](../templates/Footer.tsx), [`ProgressBar.tsx`](../templates/ProgressBar.tsx), [`SurveyStickyChrome.tsx`](../templates/SurveyStickyChrome.tsx), [`LanguageSelector.tsx`](../templates/LanguageSelector.tsx), [`PreviewBridgeInit.tsx`](../templates/PreviewBridgeInit.tsx), [`previewBridge.ts`](../../previewBridge.ts).
+
+Pipeline: [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) · [`apply-ui-config.md`](apply-ui-config.md)
+
+---
+
+## Symptom → missing hook (quick fix)
+
+| Wizard control / symptom | Required fix |
+|--------------------------|--------------|
+| Logo not updating in Branding / Header preview | `data-cfm-logo` img + `data-cfm-logo-text` fallback in `Header.tsx` |
+| 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` |
+| Question numbers / required asterisk toggles | `data-cfm-question-number` + `data-cfm-required` on every question title |
+| Question card padding/shadow/colors not live-updating | Question wrapper uses `var(--cfm-card-*)` — not hardcoded `bg-white shadow-sm` |
+| MCQ / NPS / dropzone style pickers | Root reads `html[data-cfm-mcq-style]`, `[data-cfm-nps-button-style]`, `[data-cfm-dropzone-style]` from bridge |
+| 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` |
+| 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 wrong on CloudFront | Never change `global.logo.fileName` manually — use wizard file in `public/` |
+
+---
+
+## Copy order (agents — do this in Phase 5)
+
+```bash
+# From SDK templates folder (monorepo or node_modules)
+cp templates/docs/templates/Header.tsx           src/components/Header.tsx
+cp templates/docs/templates/Footer.tsx           src/components/Footer.tsx
+cp templates/docs/templates/ProgressBar.tsx      src/components/ProgressBar.tsx
+cp templates/docs/templates/SurveyStickyChrome.tsx src/components/SurveyStickyChrome.tsx
+cp templates/docs/templates/LanguageSelector.tsx src/components/LanguageSelector.tsx
+cp templates/docs/templates/PreviewBridgeInit.tsx src/components/PreviewBridgeInit.tsx
+cp templates/previewBridge.ts                    src/lib/previewBridge.ts
+cp templates/survey-theme.css                    src/styles/survey-theme.css
+cp templates/docs/templates/uiConfig.ts              src/lib/uiConfig.ts
+cp templates/docs/templates/RatingScale.tsx        src/components/RatingScale.tsx
+cp templates/docs/templates/selectionStyles.ts    src/lib/surveyUi/selectionStyles.ts
+cp templates/docs/templates/labelStyles.ts        src/lib/surveyUi/labelStyles.ts
+```
+
+Wire `PreviewBridgeInit` in `layout.tsx` (local dev). Wizard iframes use injected `preview-bridge.inline.js` at export time.
+
+Run verification:
+
+```bash
+bash templates/verify-agent-build.sh
+```
+
+---
+
+## Layer 1 — CSS variables (`--cfm-*`)
+
+Wizard sends SNAPSHOT (full) + DELTA (partial) CSS vars to `:root`.
+
+**Rule:** Every color, radius, spacing, or chrome dimension editable in the wizard must be consumed via `var(--cfm-…)` — not hardcoded `#e20074` / `bg-[#e20074]`.
+
+Minimum files:
+
+| File | Role |
+|------|------|
+| `src/styles/survey-theme.css` | All default `--cfm-*` vars |
+| `globals.css` | `@import './styles/survey-theme.css'` |
+| Scale components | `selectionStyles.ts` + `labelStyles.ts` |
+
+---
+
+## Layer 2 — Content patches (`data-cfm-*` + layout flags)
+
+Wizard sends `contentPatch` on SNAPSHOT (not DELTA). Preview bridge applies patches to matching DOM nodes.
+
+### Branding & header
+
+| Patch field | DOM target | Template location |
+|-------------|------------|-------------------|
+| `logoUrl` | `[data-cfm-logo]` → sets `src`, shows img; hides `[data-cfm-logo-text]` | `Header.tsx` |
+| `companyName` | `[data-cfm-company]` text; fills logo-text when img hidden | `Header.tsx` |
+| `layoutFlags.showCompanyName` | `[data-cfm-company]` display | bridge |
+
+### Layout toggles (independent — critical)
+
+| `layoutFlags` key | Bridge selector | Component requirement |
+|-------------------|-----------------|----------------------|
+| `showHeader` | `.cfm-header`, `header.cfm-header` | Class on `<header>` only |
+| `showProgressBar` | `.cfm-progress`, `[data-cfm-progress]` | **Separate** from header — `ProgressBar.tsx` |
+| `showFooter` | `.cfm-footer`, `footer.cfm-footer` | Class on `<footer>` |
+| `showLanguageSwitcher` | `[data-cfm-language]` | `LanguageSelector.tsx` |
+| `showNextButton` | `[data-cfm-btn-next]` | `SurveyPage.tsx` nav |
+| `showBackButton` | `[data-cfm-btn-back]` | `SurveyPage.tsx` nav |
+| `showQuestionNumbers` | `[data-cfm-question-number]` | `Question.tsx` title |
+| `showRequiredAsterisk` | `[data-cfm-required]` | `Question.tsx` title |
+| `showFooterLogo` | `[data-cfm-footer-logo]` | `Footer.tsx` |
+
+**Anti-pattern:** Putting `sticky top-0` on the same element as `cfm-header` — bridge used to hide progress when toggling header. Templates use `cfm-sticky-chrome` wrapper without using it for `showHeader`.
+
+### Survey chrome content
+
+| Patch field | DOM target |
+|-------------|------------|
+| `surveyTitle` | `[data-cfm-survey-title]` |
+| `thankYouMessage` | `[data-cfm-thank-you]` |
+| `buttonLabels.next` / `.back` | `[data-cfm-btn-next]` / `[data-cfm-btn-back]` |
+| `copyrightText` | `[data-cfm-copyright]` |
+| `footerLinks[]` | `[data-cfm-footer-links]` innerHTML |
+
+### Question-type DOM attributes (on `<html>`)
+
+Set via `contentPatch.domAttributes`:
+
+| Attribute | Wizard source | Component reads |
+|-----------|---------------|-----------------|
+| `data-cfm-mcq-style` | `questionTypes.MCQ.optionStyle` | MCQ card classes / CSS |
+| `data-cfm-nps-button-style` | `questionTypes.NPS_SCALE.buttonStyle` | `RatingScale.tsx` |
+| `data-cfm-dropzone-style` | `questionTypes.FILE_UPLOAD.dropzoneStyle` | `FileUploadScale.tsx` |
+
+Vite preview harness also applies `previewState` via `PreviewConfigContext` for placeholders, NPS hints, rank variant, etc.
+
+---
+
+## Question card (Theme step)
+
+Question outer wrapper **must** use theme vars:
+
+```tsx
+<section
+  id={question.id}
+  className="cfm-question-card space-y-4"
+  style={{
+    background: 'var(--cfm-card-bg, #fff)',
+    borderColor: 'var(--cfm-card-border-color, #e5e7eb)',
+    padding: 'var(--cfm-card-padding, 24px)',
+    boxShadow: 'var(--cfm-card-shadow, 0 1px 3px rgba(0,0,0,0.1))',
+    borderRadius: 'var(--cfm-border-radius, 12px)',
+    borderWidth: 1,
+    borderStyle: 'solid',
+  }}
+>
+```
+
+Question title hooks:
+
+```tsx
+<h2>
+  {question.questionNumber != null && (
+    <span data-cfm-question-number className="mr-1 font-semibold">
+      {question.questionNumber}.
+    </span>
+  )}
+  <span dangerouslySetInnerHTML={{ __html: displayQuestionText }} />
+  {question.required && (
+    <span data-cfm-required className="ml-1 text-red-500">*</span>
+  )}
+</h2>
+```
+
+TEXTFIELD placeholder live preview: `data-cfm-textfield` on input/textarea.
+
+---
+
+### Branding & header — company name after logo
+
+**Layout rule:** Logo and company name share one flex row (`.cfm-header-brand`):
+
+```
+[ data-cfm-logo img ] [ data-cfm-company text ]
+```
+
+| State | What preview shows |
+|-------|-------------------|
+| No logo, no company | Empty header brand slot (no text) |
+| No logo, company set | `data-cfm-logo-text` shows company name |
+| Logo uploaded, company set | Image visible + `data-cfm-company` text **after** logo |
+| Logo uploaded, company empty | Image only; company span hidden |
+
+Wizard **Logo** step controls size via `global.header.logoBoxWidth`, `logoBoxHeight`, `logoPadding` → CSS vars `--cfm-header-logo-width/height/padding`.
+
+**Agent must copy** [`uiConfig.ts`](../templates/uiConfig.ts) — Header reads `survey-ui-config.json` at build time. **Never** use a global `UI_CONFIG` variable (causes `ReferenceError` blank page).
+
+### Logo pipeline (wizard → CloudFront) — all 4 steps must match
+
+```
+1. Wizard upload     → public/logo_{timestamp}_{name}.jpg
+2. save-config       → survey-ui-config.json global.logo.fileName (same name)
+3. Phase 6c apply    → Header img src="./{fileName}" via uiConfig.ts
+4. build + deploy    → out/{fileName} → S3 deploy prefix → CloudFront
+```
+
+**Forbidden during deploy troubleshooting:**
+- Changing `global.logo.fileName` to `telekom-logo.svg` because JPG "wasn't ready"
+- Using `global.logo.url` (data: or /assets/ URL) as img src
+
+If deploy preflight fails on missing logo: wait for wizard save (file lands in `public/`), then rebuild — do not substitute a different filename.
+
+See [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
+
+### Question card — cell selected + focus ring
+
+Theme → Question card exposes two tokens used on **every** radio/scale cell:
+
+| Token | CSS var | Visual |
+|-------|---------|--------|
+| Cell selected | `--cfm-matrix-selected` | **Fill** inside outer ring (annulus) |
+| Focus ring | `--cfm-input-focus-ring` | **Outer border** + **inner dot** |
+
+Copy [`selectionStyles.ts`](../templates/selectionStyles.ts) and use in `RatingScale.tsx`, `LikertMatrixScale.tsx`, `CsatMatrixScale.tsx`, MCQ options.
+
+### Per-type live preview (all 11 types)
+
+| Type | Required wiring |
+|------|-----------------|
+| MCQ | `var(--cfm-mcq-*)` on option cards; `html[data-cfm-mcq-style]` |
+| TEXTFIELD | `data-cfm-textfield` + `--cfm-input-placeholder` on `::placeholder` |
+| NPS_SCALE | Copy wizard `RatingScale.tsx`; `selectionStyles` on radio rings |
+| CFM_MATRIX | `matrixRadioRingStyle`; render **all** `statementRows` (wizard multi-row toggle adds 2nd row in harness) |
+| CSAT/RATING_MATRIX | `CsatMatrixScale.tsx` + `labelStyles.ts` |
+| SLIDER_MATRIX | `CustomSliderTrack.tsx` + slider tick vars |
+| FILE_UPLOAD | `data-cfm-dropzone-style` + `--cfm-upload-border-color` |
+| HEATMAP | `--cfm-heatmap-pin*` |
+| RANK_ORDER | `--cfm-rank-*` |
+| TEXT_AND_MEDIA | `--cfm-media-*` |
+
+Full table: [`wizard-question-type-styling.md`](wizard-question-type-styling.md).
+
+---
+
+## SurveyPage wiring (content phase)
+
+```tsx
+<div className="flex min-h-screen flex-col" style={{ background: 'var(--cfm-background)' }}>
+  <SurveyStickyChrome progressPercentage={state.progressPercentage} />
+  <main style={{ maxWidth: 'var(--cfm-max-width)' }}>...</main>
+  <Footer />
+</div>
+```
+
+Intro / end / paused: standalone `<Header />` (not sticky chrome). Footer still uses `cfm-footer`.
+
+---
+
+## Local wizard — preview garbage collection
+
+| Event | Action |
+|-------|--------|
+| Client **saves** (Review & Build) | `POST /api/save-config` → writes config → **deletes `out/previews/`** → CLI exits |
+| Client **quits** without saving | `POST /api/wizard-quit` → deletes `out/previews/` → CLI exits |
+| Agent **Ctrl+C** on customize CLI | Same cleanup on shutdown |
+
+EC2 `customize-ui`: quit/save uses disk session GC — see [`wizard-config-handoff.md`](wizard-config-handoff.md).
+
+**Note:** GC removes **preview export cache** (`out/previews/`), not your `src/` or production `out/` build. Re-run `export-previews` on next wizard session.
+
+---
+
+## Verification checklist (blocking before Phase 6b)
+
+- [ ] Copied all templates from § Copy order
+- [ ] `grep -r data-cfm-logo src/components/Header.tsx` — match
+- [ ] `grep -r data-cfm-progress src/components/ProgressBar.tsx` — match
+- [ ] `grep -r cfm-footer src/components/Footer.tsx` — match
+- [ ] `grep -r data-cfm-question-number src/components/Question.tsx` — match
+- [ ] `grep -rE 'var\\(--cfm-' src/components/` — no wizard colors as hardcoded hex only
+- [ ] `bash templates/verify-agent-build.sh` exit 0
+- [ ] `npx cfm-sdk export-previews` exit 0
+
+---
+
+## Related
+
+| Doc | Role |
+|-----|------|
+| [`wizard-customization-catalog.md`](wizard-customization-catalog.md) | Every wizard control → CSS var → component |
+| [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) | Full build guide |
+| [`wizard-post-customize-build.md`](wizard-post-customize-build.md) | After wizard save — apply all formats + build |
+| [`wizard-question-type-styling.md`](wizard-question-type-styling.md) | Per-type CSS vars |
+| [`10-header-footer.md`](../01-components/10-header-footer.md) | Branding patterns |
+| [`12-survey-chrome.md`](../03-ui-specs/12-survey-chrome.md) | Chrome layout spec |

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

@@ -1,6 +1,7 @@
 # Wizard Config Handoff — Wait, Capture, Apply
 
 > **Phase 6b → 6c.** Read with [`ui-customization-wizard.md`](ui-customization-wizard.md) and [`apply-ui-config.md`](apply-ui-config.md).  
+> **Phase 6c runbook (all formats + build):** [`wizard-post-customize-build.md`](wizard-post-customize-build.md).  
 > Pipeline: [`agent-execution-flow.md`](agent-execution-flow.md).
 
 This doc tells the agent **exactly** how to wait for the client to finish the wizard, capture the JSON output, and apply **every** change without omission.
@@ -53,6 +54,10 @@ 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/`.
+
+**After save:** `POST /api/save-config` also deletes `out/previews/` before CLI exits (preview garbage collection).
+
 ---
 
 ## Remote client flow — `customize-ui` (fallback only)
@@ -139,7 +144,7 @@ For **every** section in the diff (`Changed`, `Added`, `Removed`):
 
 ### Step 4 — Apply to codebase (Phase 6c)
 
-Follow [`apply-ui-config.md`](apply-ui-config.md) using **`survey-ui-config.final.json`** as input.
+Follow [`wizard-post-customize-build.md`](wizard-post-customize-build.md) (ordered checklist + format matrix), then [`apply-ui-config.md`](apply-ui-config.md) path tables using **`survey-ui-config.final.json`** (EC2) or **`survey-ui-config.json`** (local) as input.
 
 Order:
 
@@ -286,6 +291,7 @@ npx cfm-sdk fetch-ui-config
 
 | Doc | Role |
 |-----|------|
+| [`wizard-post-customize-build.md`](wizard-post-customize-build.md) | Phase 6c runbook — all question formats + verify/build |
 | [`apply-ui-config.md`](apply-ui-config.md) | Complete config path → file mapping |
 | [`wizard-api.md`](wizard-api.md) | Poll endpoint, complete payload |
 | [`wizard-question-type-styling.md`](wizard-question-type-styling.md) | Per-type CSS vars |