@explorer02/cfm-survey-sdk 0.2.5 → 0.2.6

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

@@ -0,0 +1,210 @@
+# 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)` |
+| Nothing updates except static harness | Agent build missing token contract — re-copy templates above |
+
+---
+
+## 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/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.
+
+---
+
+## 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 quit — preview garbage collection
+
+When the client **quits** local wizard (`npx cfm-sdk customize`) without saving:
+
+1. Wizard SPA calls `POST /api/wizard-quit` on the customize server
+2. CLI deletes `out/previews/` on agent disk
+3. CLI exits; no orphan preview folders
+
+When client **saves**: config written; previews remain until CLI exits (then server stops).
+
+When CLI is **Ctrl+C**'d: customize server runs the same preview cleanup on shutdown.
+
+EC2 `customize-ui`: quit calls `POST /wizard/session/quit` — disk session folder deleted (see [`wizard-config-handoff.md`](wizard-config-handoff.md)).
+
+---
+
+## 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-preview-build-guide.md`](wizard-preview-build-guide.md) | Full build guide |
+| [`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

@@ -53,6 +53,8 @@ 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/` on agent disk. Ctrl+C on customize CLI runs the same cleanup.
+
 ---
 
 ## Remote client flow — `customize-ui` (fallback only)

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

@@ -1,10 +1,13 @@
 # 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.  
+> **Authoritative hook list + copy commands:** [`wizard-chrome-contract.md`](wizard-chrome-contract.md) — fixes logo, layout toggles, question card, and per-type preview issues.  
 > Pipeline: [`agent-execution-flow.md`](agent-execution-flow.md).
 
 Related docs:
 
+- [`wizard-chrome-contract.md`](wizard-chrome-contract.md) — **copy-first templates** + symptom → fix table
+
 - [`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
@@ -51,14 +54,25 @@ If components use **hardcoded** colors (`bg-[#e20074]`) with no `var(--cfm-*)` h
 
 ## Required project artifacts (Phase 5)
 
-Create these **before** the client opens the wizard:
+**Copy wizard-ready templates first** (do not hand-write chrome from `apps/client`):
+
+| Template (SDK) | Copy to |
+|----------------|---------|
+| `templates/docs/templates/Header.tsx` | `src/components/Header.tsx` |
+| `templates/docs/templates/Footer.tsx` | `src/components/Footer.tsx` |
+| `templates/docs/templates/ProgressBar.tsx` | `src/components/ProgressBar.tsx` |
+| `templates/docs/templates/SurveyStickyChrome.tsx` | `src/components/SurveyStickyChrome.tsx` |
+| `templates/docs/templates/LanguageSelector.tsx` | `src/components/LanguageSelector.tsx` |
+| `templates/docs/templates/PreviewBridgeInit.tsx` | `src/components/PreviewBridgeInit.tsx` |
+| `templates/previewBridge.ts` | `src/lib/previewBridge.ts` |
+| `templates/survey-theme.css` | `src/styles/survey-theme.css` |
+| `templates/docs/templates/Question.tsx` | `src/components/Question.tsx` (dispatcher base) |
+
+Full symptom → fix table: [`wizard-chrome-contract.md`](wizard-chrome-contract.md).
 
 | 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`:
 

package/templates/docs/01-components/19-survey-sticky-chrome.md

@@ -1,30 +1,28 @@
 # Survey Sticky Chrome
 
-> **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
-> **Reference implementation:** `apps/client/src/components/SurveyStickyChrome.tsx`
+> **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`  
+> **Wizard contract:** [`wizard-chrome-contract.md`](../00-integration/wizard-chrome-contract.md) — header and progress are **separate** toggle targets  
 > **Template:** [`templates/SurveyStickyChrome.tsx`](../templates/SurveyStickyChrome.tsx)
-> **Component**: `SurveyStickyChrome`
 
 ## Purpose
 
-Wrap **Header + ProgressBar** in a single `sticky top-0` container so the progress bar stays visible when the respondent scrolls to answer questions lower on the page (especially the last question on a multi-question page).
+Wrap **Header + ProgressBar** in a sticky container. The wizard toggles them **independently**:
 
-## Props
+| Toggle | Target |
+|--------|--------|
+| `showHeader` | `.cfm-header` on `<header>` only |
+| `showProgressBar` | `[data-cfm-progress]` / `.cfm-progress` only |
 
-```typescript
-type SurveyStickyChromeProps = {
-  progressPercentage: number; // from state.progressPercentage
-};
-```
+Do **not** put class `cfm-header` on the sticky wrapper.
 
-## Implementation
+## Implementation (wizard-ready)
 
 ```tsx
 export default function SurveyStickyChrome({ progressPercentage }: SurveyStickyChromeProps) {
   return (
-    <div className="sticky top-0 z-30 bg-white shadow-[0_2px_8px_rgba(0,0,0,0.06)]">
+    <div className="cfm-sticky-chrome sticky top-0 z-30" style={{ background: 'var(--cfm-header-bg)' }}>
       <Header embedded />
-      <div className="mx-auto w-full max-w-4xl px-4 pb-5 pt-4 sm:px-6 lg:px-8">
+      <div className="mx-auto w-full px-4" style={{ maxWidth: 'var(--cfm-max-width)' }}>
         <ProgressBar progressPercentage={progressPercentage} />
       </div>
     </div>
@@ -32,48 +30,11 @@ export default function SurveyStickyChrome({ progressPercentage }: SurveyStickyC
 }
 ```
 
-## Spacing (logo → progress bar)
-
-Keep a visible gap between the logo block and the progress track — do **not** flush them together.
-
-| Token | Tailwind | Purpose |
-|-------|----------|---------|
-| Top inset | `pt-4` | 16px gap below logo / header row |
-| Bottom inset | `pb-5` | 20px gap above scrollable question content |
-| Horizontal | `px-4 sm:px-6 lg:px-8` | Align track with `main` content column (`max-w-4xl`) |
-
-## Header `embedded` prop
-
-When `Header` is inside sticky chrome, pass `embedded` to avoid a double shadow:
-
-```tsx
-<header className={`relative h-[120px] w-full bg-white ${embedded ? '' : 'z-10 shadow-[0_2px_8px_rgba(0,0,0,0.06)]'}`}>
-```
-
-Use the standalone `Header` (no `embedded`) on intro, end, loading, and terminal pages.
-
-## SurveyPage wiring (content phase only)
-
-```tsx
-<div className="flex min-h-screen flex-col bg-white">
-  <SurveyStickyChrome progressPercentage={state.progressPercentage} />
-
-  <main className="mx-auto w-full max-w-4xl flex-1 px-4 py-10 sm:px-6 lg:px-8">
-    <LanguageSelector ... />
-    {/* questions + nav */}
-  </main>
-
-  <Footer />
-</div>
-```
-
-Do **not** render a separate `ProgressBar` inside `<main>` — it belongs in sticky chrome only.
+Copy full file from [`templates/SurveyStickyChrome.tsx`](../templates/SurveyStickyChrome.tsx).
 
 ## Agent checklist
 
-- [ ] `SurveyStickyChrome` (or equivalent sticky wrapper) on `phase.kind === 'content'`
-- [ ] `ProgressBar` bound to `state.progressPercentage`
-- [ ] `sticky top-0 z-30 bg-white` on wrapper; single shadow on wrapper, not Header
-- [ ] `pt-4` gap between logo and progress track; `pb-5` below track
-- [ ] Progress track aligned to same `max-w-4xl` as question content
-- [ ] Standalone `Header` on intro / end / loading / terminal branches
+- [ ] `Header.tsx` has class `cfm-header` + `data-cfm-logo` + `data-cfm-company`
+- [ ] `ProgressBar.tsx` has `data-cfm-progress` + class `cfm-progress`
+- [ ] Sticky wrapper uses `cfm-sticky-chrome` — not `cfm-header`
+- [ ] `pt`/`pb` spacing via `--cfm-sticky-pt` / `--cfm-sticky-pb`

package/templates/docs/MANIFEST.json

@@ -156,6 +156,10 @@
       "path": "00-integration/client-lib-folder.md",
       "purpose": "src/lib layout — customFieldValues + surveyUi portable templates"
     },
+    {
+      "path": "00-integration/wizard-chrome-contract.md",
+      "purpose": "Wizard DOM/CSS hook contract — copy-first Header/Footer/ProgressBar templates (Phase 5)"
+    },
     {
       "path": "00-integration/wizard-preview-build-guide.md",
       "purpose": "Build client components for wizard live preview — --cfm-* vars and data-cfm-* hooks (Phase 5)"

package/templates/docs/index.md

@@ -77,7 +77,7 @@ Full step-by-step: [`agent-execution-flow.md`](00-integration/agent-execution-fl
 | **2** Instance ID | Get JWT | `useSurveySDK.md` — **ask client** |
 | **3** SDK contract | Hook + logic | `client-integration-guide.md`, `question-type-sdk-matrix.md`, logic docs |
 | **4** Plan | Inventory + copy dispatcher | `component-checklist.md`, per-type MANIFEST docs, `implementation_plan.md` |
-| **5** Build | Wizard-ready UI | `constraints.md`, `wizard-preview-build-guide.md`, `wizard-question-type-styling.md`, `03-ui-specs/*` |
+| **5** Build | Wizard-ready UI | `wizard-chrome-contract.md`, `wizard-preview-build-guide.md`, `wizard-question-type-styling.md`, `03-ui-specs/*` |
 | **6** Verify | Build + dev server | `verify-agent-build.sh` — **ask wizard** |
 | **6b** Wizard | Optional customize | **`npx cfm-sdk customize`** (default) — EC2 `customize-ui` only if client on another device |
 | **6c** Apply | Sync final config | `apply-ui-config.md` |
@@ -101,7 +101,7 @@ Every agent build includes these even if the client later skips the wizard:
 | Scale components | `templates/*Scale*.tsx` etc. | `src/components/` per inventory |
 | Draft config | agent-written | `./survey-ui-config.json` |
 
-**Chrome:** `data-cfm-logo` / `data-cfm-logo-text`, `data-cfm-company`, `data-cfm-btn-next`, `data-cfm-btn-back`, `data-cfm-survey-title`, `data-cfm-thank-you` — see `wizard-preview-build-guide.md`.
+**Chrome:** copy `templates/docs/templates/Header.tsx` etc. — see `wizard-chrome-contract.md` for full hook list.
 
 **Selection pattern:** focus ring = outer border + inner dot; cell selected = annulus fill — see `wizard-question-type-styling.md`.
 

package/templates/docs/templates/Footer.tsx

@@ -0,0 +1,72 @@
+/**
+ * Wizard-ready Footer — copy to src/components/Footer.tsx
+ * Required: footer.cfm-footer, data-cfm-copyright, data-cfm-footer-links, data-cfm-footer-logo
+ */
+'use client';
+
+export default function Footer() {
+  return (
+    <footer
+      className="cfm-footer w-full"
+      style={{
+        background: 'var(--cfm-footer-bg, #262626)',
+        color: 'var(--cfm-footer-text, #9ca3af)',
+        padding: 'var(--cfm-footer-padding-y, 24px) var(--cfm-footer-padding-x, 40px)',
+      }}
+    >
+      <div
+        className="cfm-footer-inner mx-auto grid w-full max-w-4xl items-end gap-6"
+        style={{
+          display: 'var(--cfm-footer-inner-display, grid)',
+          flexDirection: 'var(--cfm-footer-inner-direction, row)' as React.CSSProperties['flexDirection'],
+          gridTemplateColumns: '1fr 1fr 1fr',
+        }}
+      >
+        <div
+          className="space-y-3"
+          style={{
+            gridColumn: 'var(--cfm-footer-logo-col, 1)',
+            justifySelf: 'var(--cfm-footer-logo-justify, start)',
+          }}
+        >
+          <img
+            data-cfm-footer-logo
+            data-cfm-logo
+            src="./logo.svg"
+            alt=""
+            style={{
+              display: 'none',
+              width: 'var(--cfm-footer-logo-width, 120px)',
+              height: 'var(--cfm-footer-logo-height, 32px)',
+              objectFit: 'contain',
+            }}
+          />
+          <p
+            data-cfm-copyright
+            className="text-xs"
+            style={{ color: 'var(--cfm-footer-text, #9ca3af)' }}
+          >
+            © Company
+          </p>
+        </div>
+
+        <nav
+          data-cfm-footer-links
+          className="flex flex-wrap gap-x-6 gap-y-2 text-xs"
+          style={{
+            gridColumn: 'var(--cfm-footer-links-col, 3)',
+            justifySelf: 'var(--cfm-footer-links-justify, end)',
+          }}
+        >
+          <a
+            href="#"
+            className="transition-colors hover:opacity-80"
+            style={{ color: 'var(--cfm-footer-link, #9ca3af)' }}
+          >
+            Privacy
+          </a>
+        </nav>
+      </div>
+    </footer>
+  );
+}

package/templates/docs/templates/Header.tsx

@@ -0,0 +1,84 @@
+/**
+ * Wizard-ready Header — copy to src/components/Header.tsx
+ * Required hooks: data-cfm-logo, data-cfm-logo-text, data-cfm-company
+ * Required class: cfm-header (layout toggles target header only — not progress bar)
+ */
+'use client';
+
+type HeaderProps = {
+  /** When true, omits outer shadow — use inside SurveyStickyChrome */
+  embedded?: boolean;
+};
+
+export default function Header({ embedded = false }: HeaderProps) {
+  return (
+    <header
+      className={`cfm-header relative w-full ${embedded ? '' : 'z-10 shadow-[0_2px_8px_rgba(0,0,0,0.06)]'}`}
+      style={{
+        height: 'var(--cfm-header-height, 120px)',
+        background: 'var(--cfm-header-bg, #fff)',
+        borderBottom: '1px solid var(--cfm-header-border, #e5e7eb)',
+        boxShadow: embedded ? undefined : 'var(--cfm-header-shadow, 0 2px 8px rgba(0,0,0,0.06))',
+      }}
+    >
+      <div
+        className="cfm-header-inner grid h-full w-full items-center"
+        style={{
+          gridTemplateColumns: '1fr 1fr 1fr',
+          padding: `0 var(--cfm-header-padding-x, 40px)`,
+          gap: 'var(--cfm-header-brand-gap, 16px)',
+        }}
+      >
+        <div
+          className="flex items-center"
+          style={{
+            gridColumn: 'var(--cfm-header-logo-col, 1)',
+            justifySelf: 'var(--cfm-header-logo-justify, start)',
+          }}
+        >
+          <img
+            data-cfm-logo
+            src="./logo.svg"
+            alt="Logo"
+            className="object-contain"
+            style={{
+              display: 'none',
+              width: 'var(--cfm-header-logo-width, 120px)',
+              height: 'var(--cfm-header-logo-height, 120px)',
+              padding: 'var(--cfm-header-logo-padding, 10px)',
+              background: 'var(--cfm-primary)',
+            }}
+          />
+          <span
+            data-cfm-logo-text
+            className="font-semibold"
+            style={{
+              color: 'var(--cfm-header-company-color, var(--cfm-text))',
+              fontSize: 'var(--cfm-header-company-size, 18px)',
+              fontWeight: 'var(--cfm-header-company-weight, 600)',
+            }}
+          >
+            Company
+          </span>
+        </div>
+
+        <span
+          data-cfm-company
+          className="font-semibold"
+          style={{
+            gridColumn: 'var(--cfm-header-company-col, 2)',
+            justifySelf: 'var(--cfm-header-company-justify, center)',
+            marginTop: 'var(--cfm-header-company-margin-top, 0)',
+            marginLeft: 'var(--cfm-header-company-margin-left, 0)',
+            marginRight: 'var(--cfm-header-company-margin-right, 0)',
+            color: 'var(--cfm-header-company-color, var(--cfm-text))',
+            fontSize: 'var(--cfm-header-company-size, 18px)',
+            fontWeight: 'var(--cfm-header-company-weight, 600)',
+          }}
+        >
+          Company Name
+        </span>
+      </div>
+    </header>
+  );
+}

package/templates/docs/templates/LanguageSelector.tsx

@@ -0,0 +1,40 @@
+'use client';
+
+import type { SurveyLanguage } from '@explorer02/cfm-survey-sdk';
+
+type LanguageSelectorProps = {
+  languages: SurveyLanguage[];
+  selectedLanguage: string;
+  onChange: (language: string) => void;
+};
+
+/** Wizard toggle showLanguageSwitcher targets [data-cfm-language] */
+export default function LanguageSelector({
+  languages,
+  selectedLanguage,
+  onChange,
+}: LanguageSelectorProps) {
+  if (languages.length <= 1) return null;
+
+  return (
+    <div data-cfm-language className="mb-6 flex justify-end">
+      <select
+        value={selectedLanguage}
+        onChange={(e) => onChange(e.target.value)}
+        className="rounded border px-3 py-1.5 text-sm outline-none"
+        style={{
+          background: 'var(--cfm-language-bg, #fff)',
+          color: 'var(--cfm-language-text, #2563eb)',
+          borderColor: 'var(--cfm-language-border, #2563eb)',
+          borderRadius: 'var(--cfm-border-radius, 8px)',
+        }}
+      >
+        {languages.map((lang) => (
+          <option key={lang.code} value={lang.code}>
+            {lang.label}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+}

package/templates/docs/templates/PreviewBridgeInit.tsx

@@ -0,0 +1,13 @@
+'use client';
+
+import { useEffect } from 'react';
+import { initPreviewBridge } from '@/lib/previewBridge';
+
+/** Mount once in root layout — enables localhost dev preview with npx cfm-sdk customize */
+export function PreviewBridgeInit() {
+  useEffect(() => {
+    const cleanup = initPreviewBridge();
+    return cleanup;
+  }, []);
+  return null;
+}

package/templates/docs/templates/ProgressBar.tsx

@@ -0,0 +1,33 @@
+/**
+ * Wizard-ready ProgressBar — copy to src/components/ProgressBar.tsx
+ * Required: data-cfm-progress + class cfm-progress (separate from header toggle)
+ */
+'use client';
+
+type ProgressBarProps = {
+  progressPercentage: number;
+};
+
+export default function ProgressBar({ progressPercentage }: ProgressBarProps) {
+  const width = Math.min(100, Math.max(0, progressPercentage));
+
+  return (
+    <div data-cfm-progress className="cfm-progress w-full">
+      <div
+        className="w-full overflow-hidden rounded-full"
+        style={{
+          height: 'var(--cfm-progress-height, 12px)',
+          background: 'var(--cfm-progress-track, #e5e7eb)',
+        }}
+      >
+        <div
+          className="h-full rounded-full transition-all duration-300 ease-out"
+          style={{
+            width: `${width}%`,
+            background: 'var(--cfm-progress-fill, var(--cfm-primary))',
+          }}
+        />
+      </div>
+    </div>
+  );
+}