@explorer02/cfm-survey-sdk 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorer02/cfm-survey-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/postinstall.js

@@ -53,8 +53,13 @@ Do NOT run `cfm-sdk init`, read `survey-config.json`, or use any setup wizard.
 
 RULE 2 — DEEP CONTEXT BEFORE CODE:
 Before writing React code, read EVERY file in `node_modules/@explorer02/cfm-survey-sdk/docs/01-components/`.
+Read `docs/00-integration/component-checklist.md` and `docs/03-ui-specs/` for EVERY question type in the fetched survey (blocking for matrix, slider_matrix, file_upload).
+Copy `docs/templates/Question.tsx` as your Question dispatcher — do NOT use stub/default fallback branches.
 Copy `node_modules/@explorer02/cfm-survey-sdk/docs/templates/implementation_plan.md` to project root and fill it in.
 
+RULE 2b — NO STUB PLACEHOLDERS:
+Never render "not yet implemented" or similar placeholder text. If a type is in the survey, implement its scale component.
+
 RULE 3 — AUTO-PROCEED:
 After the implementation plan is complete, proceed to build without waiting for approval.
 The workflow requires 3 client inputs: Prompt/Mockup, Instance ID (JWT), Deploy Confirmation.

package/templates/AGENT.md

@@ -21,11 +21,13 @@ Import from whatever appears in `package.json`:
 | 1 | Scaffold React app — `00-integration/setup.md` |
 | 2 | Ask client for instanceId JWT |
 | 3 | Read `useSurveySDK.md` — hook contract |
-| 4 | Read all `01-components/`; copy `templates/implementation_plan.md` → project root |
-| 5 | Build UI per blueprints + `constraints.md` |
+| 4 | Read all `01-components/`; inventory survey types; read `03-ui-specs/` per type; copy `templates/Question.tsx` + `implementation_plan.md` |
+| 5 | Build UI — create all scale files from `component-checklist.md`; no stub placeholders |
 | 6 | Verify build checklist |
 | 7 | Deploy on client confirmation |
 
 **Do NOT** run `cfm-sdk init`, read `survey-config.json`, or use any setup wizard.
 
+**Do NOT** render `"not yet implemented"` or default fallback stubs in `Question.tsx`. Copy `docs/templates/Question.tsx` and create all required scale components.
+
 Follow the master index strictly. Do not guess SDK internals. Do not import from `/src/` paths.

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

@@ -0,0 +1,61 @@
+# Required Component Files Checklist
+
+> **Blocking gate before Phase 5 (BUILD).** After fetching the survey with `instanceId`, list every `(type, subType)` pair and ensure all required files exist.
+
+## Step 1: Inventory Question Types
+
+From `survey.pages`, collect unique combinations:
+
+| questionId | type | subType (if matrix) |
+|------------|------|---------------------|
+| | | |
+
+## Step 2: Create Required Files
+
+| If survey contains | Agent MUST create before `npm run build` | UI spec |
+|--------------------|------------------------------------------|---------|
+| `rating` | `RatingScale.tsx` | `03-ui-specs/01-rating.md` |
+| `csat` | `CsatScale.tsx` | `03-ui-specs/04-csat.md` |
+| `rating_scale` | Reuse `CsatScale.tsx` or dedicated component | `03-ui-specs/05-rating-scale.md` |
+| `slider` | `CustomSliderTrack.tsx` + wrapper | `03-ui-specs/06-slider.md` |
+| `matrix` + `CFM_MATRIX` | `LikertMatrixScale.tsx`, `MatrixDropdown.tsx` | `03-ui-specs/07-matrix-cfm.md` |
+| `matrix` + `CSAT_MATRIX` or `RATING_MATRIX` | `CsatMatrixScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx` | `03-ui-specs/08-matrix-csat-rating.md` |
+| `slider_matrix` | `SliderMatrixScale.tsx`, `CustomSliderTrack.tsx` | `03-ui-specs/09-slider-matrix.md` |
+| `file_upload` | `FileUploadScale.tsx` | `03-ui-specs/10-file-upload.md` |
+| `radio`, `text`, `text_and_media` | Inline in `Question.tsx` | `03-ui-specs/02-radio.md`, `03-text.md`, `11-text-and-media.md` |
+
+Always create **`Question.tsx`** from [`templates/Question.tsx`](../templates/Question.tsx).
+
+## Matrix subType Routing (CRITICAL)
+
+`question.type === 'matrix'` alone renders **nothing**. You MUST branch on `subType`:
+
+```tsx
+{question.type === 'matrix' && question.subType === 'CFM_MATRIX' && (
+  <LikertMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
+)}
+
+{question.type === 'matrix' && (question.subType === 'CSAT_MATRIX' || question.subType === 'RATING_MATRIX') && (
+  <CsatMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
+)}
+```
+
+## Shared Primitives
+
+| File | Used by |
+|------|---------|
+| `CustomSliderTrack.tsx` | `slider_matrix`, CSAT matrix `graphics`, standalone `slider` |
+| `MatrixDropdown.tsx` | `LikertMatrixScale`, `CsatMatrixScale` vertical/dropdown modes |
+
+Specs: `03-ui-specs/shared/custom-slider-track.md`, `03-ui-specs/shared/matrix-dropdown.md`
+
+## Step 3: Verify Before Build
+
+- [ ] Every type in the survey inventory has a matching component file
+- [ ] `Question.tsx` copied from `docs/templates/Question.tsx` with all branches wired
+- [ ] No `default` fallback rendering stub text (see `constraints.md` §7)
+- [ ] Grep project: `not yet implemented` → **zero matches**
+
+```bash
+grep -r "not yet implemented" src/ components/ app/ 2>/dev/null || true
+```

package/templates/docs/00-integration/constraints.md

@@ -40,6 +40,22 @@ Survey UI files importing the SDK must be client components. Next.js: `'use clie
 
 Define `SURVEY_PLACEHOLDERS` outside the component — inline objects cause infinite re-fetch.
 
+## 7. No Stub Placeholders (CRITICAL)
+
+**FORBIDDEN** in `Question.tsx` or any scale component:
+
+- Text like `"not yet implemented"`, `"coming soon"`, or any placeholder error message
+- `default` / `else` branches in the dispatcher that render stub UI instead of the real component
+- Empty `<div>` where an interactive scale component should be
+
+If a question type appears in the fetched survey, its component **must** be fully implemented before shipping. Read the matching `03-ui-specs/` doc and create the required files listed in `component-checklist.md`.
+
+**Phase 6 verification:** grep the project for stub text — must return zero matches:
+
+```bash
+grep -r "not yet implemented" src/ components/ app/ 2>/dev/null || true
+```
+
 ---
 
 ## Troubleshooting
@@ -52,3 +68,4 @@ Define `SURVEY_PLACEHOLDERS` outside the component — inline objects cause infi
 | Validation errors but no scroll | Add `id={question.id}` to question wrapper |
 | Survey data is null, no error | Invalid/expired `instanceId` — ask client for fresh JWT |
 | CSAT emojis missing | `npm install react-icons` |
+| Grey "not yet implemented" text on questions | Copy `docs/templates/Question.tsx`; create scale components per `component-checklist.md`; route matrix by `subType` |

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

@@ -1,10 +1,19 @@
 # Question Dispatcher Architectural Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/00-question-shell.md`
-> **Reference implementation:** `apps/client/src/components/Question.tsx`
+> **Canonical template:** [`templates/Question.tsx`](../templates/Question.tsx) — copy verbatim, then create imported components
+> **Monorepo reference:** `apps/client/src/components/Question.tsx` (not available in npm installs)
 > **Target Component**: `Question`
 > **Role**: Wrapper card component that routes to the correct scale component based on `question.type`.
 
+## Start Here (CRITICAL)
+
+1. Copy [`docs/templates/Question.tsx`](../templates/Question.tsx) into your project.
+2. Create every imported scale component — see [`component-checklist.md`](../00-integration/component-checklist.md).
+3. Read `03-ui-specs/` for each type in your fetched survey **before** editing the dispatcher.
+
+**Do NOT** write a partial skeleton with `default` fallbacks or `"not yet implemented"` messages.
+
 ## Core Responsibility
 Render a visually separated container (card) for each question. Handle rich text parsing, required asterisks, description text, and error validation messages. Most importantly, it MUST act as an exhaustive switch statement dispatching to ALL supported question types.
 
@@ -12,17 +21,34 @@ Render a visually separated container (card) for each question. Handle rich text
 
 The agent MUST handle EVERY SINGLE ONE of these `question.type` values. Failure to handle them will result in blank UI or broken surveys.
 
-1. **`rating`**: Renders `RatingScale`. This covers NPS, Stars, Emoji, and generic numeric scales.
+1. **`rating`**: Renders `RatingScale`. This covers NPS scales.
 2. **`csat`**: Renders `CsatScale`. This covers CSAT specific faces/icons.
-3. **`radio`**: Renders inline MCQ radio buttons. (Can be implemented inside this file or separately).
+3. **`radio`**: Renders inline MCQ radio buttons.
 4. **`text`**: Renders an inline `<textarea>` or `<input>`.
-5. **`matrix`**: 
+5. **`matrix`** — **requires `subType`**:
    - If `subType === 'CFM_MATRIX'`, render `LikertMatrixScale`
    - If `subType === 'CSAT_MATRIX'` or `'RATING_MATRIX'`, render `CsatMatrixScale`
+   - Routing on `type === 'matrix'` alone renders **nothing**
 6. **`slider_matrix`**: Renders `SliderMatrixScale`
 7. **`file_upload`**: Renders `FileUploadScale`
-8. **`text_and_media`**: Renders inline `<video>` or `<img>` based on `question.mediaUrl`. 
-   - *Note: `text_and_media` questions may NOT have user input. Do not render a scale for them.*
+8. **`text_and_media`**: Renders inline `<video>` or `<img>` based on `question.mediaUrl`. No answer input.
+9. **`rating_scale`**: Star/emoji scale — see `03-ui-specs/05-rating-scale.md`
+10. **`slider`**: Standalone slider — see `03-ui-specs/06-slider.md`
+
+## Forbidden Anti-Patterns
+
+```tsx
+// ❌ FORBIDDEN — never ship this
+default:
+  return <p>Question type "{question.type}" is not yet implemented in this client.</p>;
+
+// ❌ FORBIDDEN — matrix without subType
+{question.type === 'matrix' && <SomeMatrix />}
+
+// ✅ REQUIRED — matrix with subType
+{question.type === 'matrix' && question.subType === 'CFM_MATRIX' && <LikertMatrixScale ... />}
+{question.type === 'matrix' && (question.subType === 'CSAT_MATRIX' || question.subType === 'RATING_MATRIX') && <CsatMatrixScale ... />}
+```
 
 ## Container UI Structure
 
@@ -47,61 +73,20 @@ Every question MUST be wrapped in a standard HTML `<section>` to visually separa
 
 4. **Validation Error Banner**:
    - If `validationError` prop is passed, render a highly visible banner below the scale.
-   - Example: Red border-left, red background, bold text.
 
 ## Hover Tooltips & Micro-interactions
 - Focus states on text inputs MUST use the brand primary color (e.g., magenta `#e20074` for Telekom).
 - Radio button wrappers should have a subtle background hover effect (e.g., `hover:bg-pink-50`).
 
-## Example Architectural Skeleton
+## Props Contract
 
-```tsx
-<section id={question.id} className="space-y-6 rounded-xl border border-gray-200 bg-white p-6 md:p-8 shadow-sm transition-all hover:shadow-md">
-  
-  {/* HEADING */}
-  <h2 className="text-lg md:text-xl font-semibold leading-relaxed text-gray-900 flex items-start gap-1">
-    <span dangerouslySetInnerHTML={{ __html: question.text }} className="prose prose-sm max-w-none" />
-    {question.required && <span className="text-[#e20074] shrink-0">*</span>}
-  </h2>
-  
-  {/* DESCRIPTION */}
-  {question.description && (
-    <div className="text-sm text-gray-600 mt-2 leading-relaxed prose prose-sm max-w-none" dangerouslySetInnerHTML={{ __html: question.description }} />
-  )}
-  
-  {/* DISPATCHER */}
-  <div className="pt-4">
-    {question.type === 'rating' && <RatingScale ... />}
-    {question.type === 'csat' && <CsatScale ... />}
-    {question.type === 'slider_matrix' && <SliderMatrixScale ... />}
-    {question.type === 'file_upload' && <FileUploadScale ... />}
-    {question.type === 'matrix' && question.subType === 'CFM_MATRIX' && <LikertMatrixScale ... />}
-    {question.type === 'matrix' && (question.subType === 'CSAT_MATRIX' || question.subType === 'RATING_MATRIX') && <CsatMatrixScale ... />}
-    
-    {question.type === 'radio' && (
-       // Inline Radio implementation
-       // Make sure to match brand hover colors!
-    )}
-    
-    {question.type === 'text' && (
-       // Inline Textarea implementation
-       // Handle character limit `question.maxCharacterCount`
-    )}
-
-    {question.type === 'text_and_media' && (
-       // Display media (image/video) based on question properties
-       // This handles CONTENT blocks.
-    )}
-  </div>
-
-  {/* ERROR BANNER */}
-  {validationError && (
-    <div className="mt-6 rounded-lg border-l-4 border-l-[#e20074] bg-red-50 p-4">
-      <p className="text-sm font-bold text-gray-900 leading-tight flex items-center gap-2">
-        <span className="text-[#e20074]">⚠</span> {validationError}
-      </p>
-    </div>
-  )}
-
-</section>
+```typescript
+type QuestionProps = {
+  question: SurveyQuestion;
+  selectedValue?: AnswerValue;
+  validationError?: string;
+  onSelect: (value: AnswerValue) => void;
+};
 ```
+
+Wire `onSelect` → `onAction({ type: 'CHANGE', payload: { questionId, value } })`.

package/templates/docs/01-components/README.md

@@ -1,6 +1,8 @@
 # Client Components Overview
 
 > Wiring blueprints for React components. **Authoritative UI details** are in [`03-ui-specs/`](../03-ui-specs/README.md) (reference-client driven).
+> **Required files gate:** [`component-checklist.md`](../00-integration/component-checklist.md)
+> **Dispatcher template:** [`templates/Question.tsx`](../templates/Question.tsx)
 > This folder documents props, `onSelect` wiring, and dispatcher architecture.
 
 ## Component Architecture

package/templates/docs/03-ui-specs/00-question-shell.md

@@ -1,8 +1,19 @@
 # UI Spec: Question Shell (`Question.tsx`)
 
-> **Reference:** `apps/client/src/components/Question.tsx`
+> **Canonical template:** [`templates/Question.tsx`](../templates/Question.tsx) — copy this dispatcher verbatim
+> **Monorepo reference:** `apps/client/src/components/Question.tsx` (not available in npm installs — implement from this spec)
 > **SDK:** All types extend `QuestionBase` from `fetchSurvey/types/base.ts`
 > **Component blueprint:** `01-components/02-question.md`
+> **Required files:** `00-integration/component-checklist.md`
+
+## Matrix subType Warning (CRITICAL)
+
+Routing on `question.type === 'matrix'` **alone renders nothing**. You MUST branch on `subType`:
+
+- `CFM_MATRIX` → `LikertMatrixScale`
+- `CSAT_MATRIX` | `RATING_MATRIX` → `CsatMatrixScale`
+
+Never use a `default` fallback that shows `"not yet implemented"` — create the scale components listed in the checklist.
 
 ## Config Inventory (QuestionBase)
 
@@ -84,6 +95,8 @@ Wire `onSelect` → `onAction({ type: 'CHANGE', payload: { questionId, value } }
 
 - [ ] `id={question.id}` on outermost `<section>`
 - [ ] HTML rendering for text and description
-- [ ] Exhaustive type switch — all 12 types handled or explicitly noted as gap
+- [ ] Copied from `templates/Question.tsx` — no stub/default fallback branches
+- [ ] Matrix routes by `subType`, not type alone
+- [ ] `slider_matrix` → `SliderMatrixScale`; `file_upload` → `FileUploadScale`
 - [ ] Validation error banner below scale
 - [ ] Rating/csat endpoint labels positioned per formulas above

package/templates/docs/03-ui-specs/07-matrix-cfm.md

@@ -1,6 +1,6 @@
 # UI Spec: CFM Matrix (`type: 'matrix'`, `subType: 'CFM_MATRIX'`)
 
-> **Reference:** `apps/client/src/components/LikertMatrixScale.tsx`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/LikertMatrixScale.tsx`
 > **SDK type:** `MatrixQuestion` — `fetchSurvey/types/matrix.ts`
 > **Component blueprint:** `01-components/06-likert-matrix-scale.md`
 

package/templates/docs/03-ui-specs/08-matrix-csat-rating.md

@@ -1,6 +1,6 @@
 # UI Spec: CSAT / Rating Matrix (`subType: 'CSAT_MATRIX' | 'RATING_MATRIX'`)
 
-> **Reference:** `apps/client/src/components/CsatMatrixScale.tsx`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CsatMatrixScale.tsx`
 > **SDK type:** `MatrixQuestion` — `fetchSurvey/types/matrix.ts`
 > **Component blueprint:** `01-components/05-csat-matrix-scale.md`
 

package/templates/docs/03-ui-specs/09-slider-matrix.md

@@ -1,6 +1,6 @@
 # UI Spec: Slider Matrix (`type: 'slider_matrix'`)
 
-> **Reference:** `apps/client/src/components/SliderMatrixScale.tsx`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/SliderMatrixScale.tsx`
 > **SDK type:** `SliderMatrixQuestion` — `fetchSurvey/types/sliderMatrix.ts`
 > **Component blueprint:** `01-components/07-slider-matrix-scale.md`
 > **Shared:** [`shared/custom-slider-track.md`](shared/custom-slider-track.md)

package/templates/docs/03-ui-specs/10-file-upload.md

@@ -1,6 +1,6 @@
 # UI Spec: File Upload (`type: 'file_upload'`)
 
-> **Reference:** `apps/client/src/components/FileUploadScale.tsx`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/FileUploadScale.tsx`
 > **SDK type:** `FileUploadQuestion` — `fetchSurvey/types/fileUpload.ts`
 > **Component blueprint:** `01-components/08-file-upload-scale.md`
 

package/templates/docs/03-ui-specs/README.md

@@ -1,7 +1,8 @@
 # UI Specifications — Reference Implementation Guide
 
-> **Authoritative source:** [`apps/client/src/components/`](../../../../../../apps/client/src/components/) in the monorepo.
-> Agents must reproduce this UI when building survey apps. Read the spec for each question type present in the fetched survey.
+> **For npm installs:** implement from these specs + [`templates/Question.tsx`](../templates/Question.tsx). The monorepo path `apps/client/src/components/` is **not** available in client projects.
+> **For monorepo devs:** cross-check against [`apps/client/src/components/`](../../../../../../apps/client/src/components/).
+> Read the spec for **each question type present** in the fetched survey before writing React code.
 
 ## How to Read a UI Spec
 

package/templates/docs/03-ui-specs/shared/custom-slider-track.md

@@ -1,6 +1,6 @@
 # UI Spec: Custom Slider Track (shared primitive)
 
-> **Reference:** `apps/client/src/components/CustomSliderTrack.tsx`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CustomSliderTrack.tsx`
 > **Used by:** `SliderMatrixScale.tsx`, `CsatMatrixScale` (graphics), standalone `slider` (gap)
 
 ## Layer Architecture

package/templates/docs/03-ui-specs/shared/matrix-dropdown.md

@@ -1,6 +1,6 @@
 # UI Spec: Matrix Dropdown (shared primitive)
 
-> **Reference:** `apps/client/src/components/MatrixDropdown.tsx`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/MatrixDropdown.tsx`
 > **Used by:** `LikertMatrixScale`, `CsatMatrixScale` vertical list
 
 ## Modes

package/templates/docs/MANIFEST.json

@@ -33,6 +33,8 @@
       "id": 4,
       "name": "planAndIngest",
       "read": [
+        "00-integration/component-checklist.md",
+        "03-ui-specs/README.md",
         "01-components/README.md",
         "01-components/01-survey-page.md",
         "01-components/02-question.md",
@@ -49,6 +51,7 @@
         "01-components/13-matrix-dropdown.md"
       ],
       "template": "templates/implementation_plan.md",
+      "questionDispatcher": "templates/Question.tsx",
       "output": "implementation_plan.md"
     },
     {
@@ -63,6 +66,8 @@
       "read": ["00-integration/constraints.md"],
       "checklist": [
         "questionDispatcherCoversAll12Types",
+        "matrixRoutesBySubType",
+        "noStubPlaceholderText",
         "everyQuestionWrapperHasId",
         "noInternalSdkImports",
         "surveyPageFiveStates",

package/templates/docs/index.md

@@ -15,7 +15,8 @@ docs/
 ├── 02-reference/            ← Routing table + config-field-index (on demand)
 ├── 03-ui-specs/             ← Authoritative UI specs (reference-client driven)
 └── templates/
-    └── implementation_plan.md
+    ├── implementation_plan.md
+    └── Question.tsx           ← Canonical dispatcher (copy before building)
 ```
 
 **Import rule:** Use whatever package name appears in the project's `package.json` (`@explorer02/cfm-survey-sdk` or `@repo/sdk`).
@@ -64,23 +65,24 @@ Optional: read `02-reference/routing-table.md` for type overview.
 ### PHASE 4: PLAN + INGEST (CRITICAL)
 
 1. Read **every** file in `01-components/` (all 14 blueprints)
-2. Copy `docs/templates/implementation_plan.md` → `./implementation_plan.md`
-3. Fill every section — do **not** invent a different structure
-4. **Auto-proceed to Phase 5** — do not wait for approval
-
-For each question type in the fetched survey, also read matching docs from `02-reference/question-types/` (see `MANIFEST.json` or `02-reference/routing-table.md`).
+2. Read `00-integration/component-checklist.md` and `03-ui-specs/README.md`
+3. **Inventory** every `(type, subType)` in `survey.pages` after instanceId fetch
+4. For **each type in the survey**, read matching `03-ui-specs/` (use `MANIFEST.json` `uiSpecs`) and `02-reference/question-types/` — **blocking** for `matrix`, `slider_matrix`, `file_upload`
+5. Copy `docs/templates/implementation_plan.md` → `./implementation_plan.md` and fill every section
+6. Copy `docs/templates/Question.tsx` as the dispatcher starting point
+7. **Auto-proceed to Phase 5** — do not wait for approval
 
 ### PHASE 5: BUILD
 
-Read: `00-integration/constraints.md`
+Read: `00-integration/constraints.md`, `00-integration/component-checklist.md`
 
-For each question in `state.currentQuestions`:
+Create all required scale component files **before** wiring `Question.tsx`. For each question in the survey:
 
 1. Read `02-reference/question-types/{type}.md` for data shape
 2. Read `03-ui-specs/{NN}-{type}.md` (use `MANIFEST.json` `uiSpecs`; split matrix by `subType`)
 3. If `matrixFormat`, `buttonType`, or `sliderType` is present → read `03-ui-specs/shared/` specs
 4. Cross-check `02-reference/config-field-index.md` for every non-default field
-5. Match reference client behavior in `apps/client/src/components/` when available
+5. Implement per ui-spec — monorepo devs may consult `apps/client/src/components/`; npm installs use ui-specs only
 
 Implement components per blueprints + UI specs. Use exported types:
 
@@ -94,7 +96,10 @@ Read: `00-integration/constraints.md` (troubleshooting)
 
 Checklist:
 
-- [ ] `Question.tsx` switch covers all 12 `question.type` values
+- [ ] `Question.tsx` copied from `docs/templates/Question.tsx` — covers all 12 `question.type` values
+- [ ] Matrix routes by `subType` (`CFM_MATRIX` vs `CSAT_MATRIX` / `RATING_MATRIX`)
+- [ ] All scale components from `component-checklist.md` exist for types in survey
+- [ ] **Zero stub text:** `grep -r "not yet implemented" src/ components/ app/` returns no matches
 - [ ] Every question wrapper has `id={question.id}`
 - [ ] No imports from `@explorer02/cfm-survey-sdk/src/...`
 - [ ] `SurveyPage` handles loading / error / empty / submitted / active
@@ -113,8 +118,7 @@ If yes: `npx cfm-sdk deploy` (preferred) or `npx vercel --prod --yes`
 | When | Read |
 |------|------|
 | Always first | `index.md`, `00-integration/setup.md`, `00-integration/useSurveySDK.md`, `00-integration/constraints.md` |
-| Before any React code | All `01-components/*.md` |
-| On demand | `02-reference/question-types/<type>.md` for types in survey |
-| Before building each question | `03-ui-specs/` per `MANIFEST.uiSpecs` |
+| Before any React code | All `01-components/*.md`, `00-integration/component-checklist.md`, `templates/Question.tsx` |
+| After instanceId fetch | `03-ui-specs/` per type in survey (blocking for matrix / slider_matrix / file_upload) |
 | Config audit | `02-reference/config-field-index.md` |
 | Tooling | `MANIFEST.json`, `templates/implementation_plan.md` |

package/templates/docs/templates/Question.tsx

@@ -0,0 +1,243 @@
+/**
+ * CANONICAL QUESTION DISPATCHER TEMPLATE
+ *
+ * Agents: copy this file to your project's components folder (e.g. src/components/Question.tsx).
+ * Then create EVERY imported scale component listed below — see:
+ *   docs/00-integration/component-checklist.md
+ *   docs/03-ui-specs/00-question-shell.md
+ *
+ * RULES:
+ * - Do NOT add a default/fallback branch that renders "not yet implemented" or similar stub text.
+ * - matrix MUST route by question.subType — type alone is NOT enough.
+ * - If a question type appears in the fetched survey, its branch MUST render a real interactive component.
+ *
+ * Replace @explorer02/cfm-survey-sdk with your package.json import name if different.
+ */
+'use client';
+
+import React from 'react';
+import type { SurveyQuestion, AnswerValue } from '@explorer02/cfm-survey-sdk';
+import { CsatScale } from './CsatScale';
+import { CsatMatrixScale } from './CsatMatrixScale';
+import { SliderMatrixScale } from './SliderMatrixScale';
+import { LikertMatrixScale } from './LikertMatrixScale';
+import { FileUploadScale } from './FileUploadScale';
+import RatingScale from './RatingScale';
+// rating_scale / slider gaps — create these if survey contains those types:
+// import { CustomSliderTrack } from './CustomSliderTrack';
+
+type QuestionProps = {
+  question: SurveyQuestion;
+  selectedValue?: AnswerValue;
+  validationError?: string;
+  onSelect: (value: AnswerValue) => void;
+};
+
+export default function Question({ question, selectedValue, validationError, onSelect }: QuestionProps) {
+  return (
+    <section id={question.id} className="space-y-4 rounded-xl border border-gray-200 bg-white p-6 shadow-sm">
+      <h2 className="text-lg font-medium leading-relaxed text-gray-900">
+        <span dangerouslySetInnerHTML={{ __html: question.text }} />
+        {question.required && <span className="text-red-500 ml-1">*</span>}
+      </h2>
+      {question.description && (
+        <div
+          className="text-sm text-gray-600 mt-2 leading-relaxed"
+          dangerouslySetInnerHTML={{ __html: question.description }}
+        />
+      )}
+
+      {question.type === 'rating' && (
+        <div className="space-y-3">
+          {(question.minLabel || question.midLabel || question.maxLabel) && (
+            <div className="relative w-full h-6 text-xs font-semibold text-gray-500">
+              <span
+                className="absolute left-0 top-0 max-w-[30%] text-left leading-tight"
+                dangerouslySetInnerHTML={{ __html: question.minLabel ?? '' }}
+              />
+              {question.midLabel && (
+                <span
+                  className="absolute top-0 -translate-x-1/2 text-center max-w-[40%] leading-tight"
+                  style={{
+                    left: `${question.midLabelIndex !== undefined && question.options.length > 1
+                        ? (question.midLabelIndex / (question.options.length - 1)) * 100
+                        : 50
+                      }%`,
+                  }}
+                  dangerouslySetInnerHTML={{ __html: question.midLabel }}
+                />
+              )}
+              <span
+                className="absolute right-0 top-0 max-w-[30%] text-right leading-tight"
+                dangerouslySetInnerHTML={{ __html: question.maxLabel ?? '' }}
+              />
+            </div>
+          )}
+          <RatingScale
+            questionId={question.id}
+            options={question.options}
+            selectedValue={selectedValue}
+            onSelect={onSelect}
+          />
+        </div>
+      )}
+
+      {question.type === 'radio' && (
+        <div className="space-y-3">
+          {question.options.map(option => {
+            const isSelected = selectedValue === option.value;
+            return (
+              <label
+                key={String(option.value)}
+                className={`flex items-center gap-4 rounded-lg border py-4 px-5 cursor-pointer transition-all ${isSelected ? 'border-[#e20074] bg-[#fdf2f8]' : 'border-[#e5e5e5] bg-white hover:bg-gray-50/50'
+                  }`}
+              >
+                <input
+                  type="radio"
+                  name={question.id}
+                  value={option.value === null ? '' : option.value}
+                  checked={isSelected}
+                  onChange={() => onSelect(option.value)}
+                  className="sr-only"
+                />
+                <div
+                  className={`flex h-5 w-5 shrink-0 items-center justify-center rounded-full border transition-all ${isSelected ? 'border-2 border-[#e20074] bg-white' : 'border-gray-400 bg-white'
+                    }`}
+                >
+                  {isSelected && <div className="h-2.5 w-2.5 rounded-full bg-[#e20074]" />}
+                </div>
+                <span
+                  className="text-[15px] font-medium text-gray-900 leading-tight"
+                  dangerouslySetInnerHTML={{ __html: option.label }}
+                />
+              </label>
+            );
+          })}
+        </div>
+      )}
+
+      {question.type === 'text' && (
+        <div className="space-y-1.5">
+          <textarea
+            rows={4}
+            value={(selectedValue as string | number | null) ?? ''}
+            onChange={e => onSelect(e.target.value)}
+            placeholder={question.placeholder || 'Type your response here...'}
+            className="w-full rounded-[4px] border border-gray-300 p-4 text-sm outline-none transition-colors focus:border-[#e20074] focus:ring-1 focus:ring-[#e20074]"
+          />
+          <div className="text-right text-xs text-gray-500 pr-1">
+            {Math.max(
+              0,
+              (question.maxCharacterCount ?? 1000) - (typeof selectedValue === 'string' ? selectedValue.length : 0)
+            )}{' '}
+            Zeichen verbleiben.
+          </div>
+        </div>
+      )}
+
+      {question.type === 'csat' && (
+        <div className="space-y-3">
+          {(question.minLabel || question.maxLabel) && (
+            <div className="flex w-full justify-between text-xs font-semibold text-gray-500">
+              {question.minLabel && <span dangerouslySetInnerHTML={{ __html: question.minLabel }} />}
+              {question.maxLabel && <span dangerouslySetInnerHTML={{ __html: question.maxLabel }} />}
+            </div>
+          )}
+          <CsatScale
+            question={question}
+            selectedValue={selectedValue as string | number | null}
+            onSelect={onSelect}
+          />
+        </div>
+      )}
+
+      {/* matrix: subType is REQUIRED — never route on type alone */}
+      {question.type === 'matrix' && (question.subType === 'CSAT_MATRIX' || question.subType === 'RATING_MATRIX') && (
+        <div className="space-y-3">
+          <CsatMatrixScale
+            question={question}
+            selectedValue={typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue) ? selectedValue : {}}
+            onSelect={onSelect}
+          />
+        </div>
+      )}
+
+      {question.type === 'matrix' && question.subType === 'CFM_MATRIX' && (
+        <div className="space-y-3">
+          <LikertMatrixScale
+            question={question}
+            selectedValue={typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue) ? selectedValue : {}}
+            onSelect={onSelect}
+          />
+        </div>
+      )}
+
+      {question.type === 'slider_matrix' && (
+        <div className="space-y-3">
+          <SliderMatrixScale
+            question={question}
+            selectedValue={typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue) ? selectedValue : {}}
+            onSelect={onSelect}
+          />
+        </div>
+      )}
+
+      {question.type === 'file_upload' && (
+        <div className="space-y-3">
+          <FileUploadScale
+            question={question}
+            selectedValue={selectedValue}
+            onSelect={onSelect}
+          />
+        </div>
+      )}
+
+      {question.type === 'text_and_media' && question.mediaUrl && (
+        <div className={`mt-4 flex w-full ${
+          question.mediaAlignment === 'TOP_CENTER' || question.mediaAlignment === 'BOTTOM_CENTER'
+            ? 'justify-center'
+            : question.mediaAlignment === 'TOP_RIGHT' || question.mediaAlignment === 'BOTTOM_RIGHT'
+              ? 'justify-end'
+              : 'justify-start'
+        }`}>
+          <div
+            style={{ width: question.mediaSize ? `${question.mediaSize}%` : '100%' }}
+            className="flex flex-col gap-2"
+          >
+            {question.mediaMimeType?.startsWith('video/') || question.mediaMimeType === 'VIDEO' ? (
+              <video controls src={question.mediaUrl} className="max-w-full rounded-md shadow-sm" />
+            ) : (
+              <img src={question.mediaUrl} alt={question.mediaTitle || ''} className="max-w-full rounded-md shadow-sm" />
+            )}
+            {question.mediaTitle && (
+              <p className="text-sm text-gray-500 text-center">{question.mediaTitle}</p>
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* rating_scale / slider: implement per 03-ui-specs/05-rating-scale.md and 06-slider.md if present in survey */}
+      {question.type === 'rating_scale' && (
+        <div className="space-y-3">
+          <CsatScale
+            question={{ ...question, type: 'csat', buttonType: question.scaleStyle === 'star' ? 'star' : 'emoji' }}
+            selectedValue={selectedValue as number | null}
+            onSelect={onSelect}
+          />
+        </div>
+      )}
+
+      {question.type === 'slider' && (
+        <div className="space-y-3">
+          {/* Wire CustomSliderTrack — min/max/step from question; see 03-ui-specs/06-slider.md */}
+        </div>
+      )}
+
+      {validationError && (
+        <div className="mt-4 rounded-[4px] border border-[#333333] bg-[#d9d9d9] py-3.5 px-4 text-left">
+          <p className="text-[13px] sm:text-sm font-bold text-gray-900 leading-tight">{validationError}</p>
+        </div>
+      )}
+    </section>
+  );
+}

package/templates/docs/templates/implementation_plan.md

@@ -42,6 +42,20 @@ Exhaustive switch — check each:
 - [ ] `dangerouslySetInnerHTML` for `question.text` / `description`
 - [ ] `validationError` banner per question
 - [ ] `id={question.id}` on every question wrapper
+- [ ] Copied from `docs/templates/Question.tsx` — no stub/default fallback branches
+
+## 3b. Required Component Files (from fetched survey)
+
+Fill from `00-integration/component-checklist.md` — every file below that applies to your survey **must exist** before Phase 5:
+
+| Component file | Required if survey contains | Created? |
+|----------------|----------------------------|----------|
+| `LikertMatrixScale.tsx` | `matrix` + `CFM_MATRIX` | |
+| `CsatMatrixScale.tsx` | `matrix` + `CSAT_MATRIX` or `RATING_MATRIX` | |
+| `SliderMatrixScale.tsx` | `slider_matrix` | **blocking** |
+| `FileUploadScale.tsx` | `file_upload` | **blocking** |
+| `MatrixDropdown.tsx` | matrix with dropdown/selectbox modes | |
+| `CustomSliderTrack.tsx` | `slider_matrix` or CSAT matrix `graphics` | |
 
 ## 4. Component Architecture Checklist
 
@@ -69,8 +83,9 @@ Fill one row per question in the fetched survey:
 
 - **configs detected:** non-default fields from `02-reference/config-field-index.md` (e.g. `matrixFormat: carousel`, `buttonType: emoji`)
 - **uiSpec read:** path from `MANIFEST.json` `uiSpecs` (matrix: use `matrix_{subType}`)
-- **ref component:** `apps/client/src/components/{Component}.tsx`
+- **ref component:** monorepo: `apps/client/src/components/{Component}.tsx`; npm: implement from ui-spec only
 - **branches implemented:** list decision-tree branches from the ui-spec (e.g. dropdown vs grid vs carousel)
+- **blocking types:** `matrix`, `slider_matrix`, `file_upload` must show interactive UI, not placeholder text
 
 ## 5. Theme, Brand & Logo
 
@@ -89,3 +104,15 @@ Fill one row per question in the fetched survey:
 - [ ] No imports from `.../src/` internal paths
 - [ ] All mutations via `onAction` — no direct state mutation
 - [ ] `npm run build` passes
+
+## 7b. Stub-Free Verification
+
+Per question type in the fetched survey, confirm interactive UI renders (not grey placeholder text):
+
+| type | subType | Renders real component? | No "not yet implemented" text? |
+|------|---------|---------------------------|--------------------------------|
+| | | | |
+
+- [ ] `grep -r "not yet implemented" src/ components/ app/` returns **zero matches**
+- [ ] Matrix questions route by `subType` in `Question.tsx`
+- [ ] `slider_matrix` shows sliders; `file_upload` shows dropzone