@explorer02/cfm-survey-sdk 0.2.1 → 0.2.2

package/templates/docs/index.md

@@ -4,23 +4,36 @@
 
 Master guide for AI coding agents. Machine-readable index: `MANIFEST.json`.
 
+**Installed package path:** `node_modules/@explorer02/cfm-survey-sdk/templates/docs/` (docs ship inside `templates/` — no postinstall copy needed).
+
 ## Documentation Layout
 
 ```
-docs/
+templates/docs/              ← installed npm package layout
+packages/sdk/templates/docs/ ← monorepo layout
 ├── index.md                 ← YOU ARE HERE
 ├── MANIFEST.json            ← Phase + question-type routing (for tooling)
 ├── 00-integration/          ← Setup, hook contract, constraints
-├── 01-components/           ← Wiring blueprints (read ALL before coding)
-├── 02-reference/            ← Routing table + config-field-index (on demand)
-├── 03-ui-specs/             ← Authoritative UI specs (reference-client driven)
+├── 01-components/           ← Wiring blueprints (read per type from MANIFEST)
+├── 02-reference/            ← Routing table, exports, config-field-index
+├── 03-ui-specs/             ← Authoritative UI specs
 └── templates/
     ├── implementation_plan.md
+    ├── survey-inventory.schema.json
+    ├── verify-agent-build.sh
+    ├── deploy-to-aws.sh
+    ├── heatmapCoords.ts
     └── 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`).
 
+## Do Not Read
+
+- Internal SDK mapper/source paths (`packages/sdk/src/**` or `node_modules/.../src/**`)
+- `cfm-sdk init`, `survey-config.json`, or any setup wizard
+- Stale `apps/client` code without verifying type literals against `MANIFEST.json` `typeLiterals`
+
 ---
 
 ## Client Inputs (3 only)
@@ -37,7 +50,9 @@ docs/
 
 ### PHASE 0: ORIENT
 
-- Read this file and `AGENT.md`
+- Read this file and `AGENT.md`:
+  - **Monorepo:** `packages/sdk/templates/AGENT.md`
+  - **Installed npm:** `node_modules/@explorer02/cfm-survey-sdk/templates/AGENT.md`
 - Detect framework: read `package.json` — Next.js / Vite / CRA (see `00-integration/setup.md`)
 - Extract branding and layout from client prompt
 - For existing apps: read project structure; do not blindly scaffold
@@ -56,60 +71,93 @@ Ask: *"Please provide your survey instance ID (JWT token)."*
 
 ### PHASE 3: SDK CONTRACT
 
-Read: `00-integration/useSurveySDK.md`
+Read: `00-integration/client-integration-guide.md` (start here), `00-integration/question-type-sdk-matrix.md`, `00-integration/useSurveySDK.md`, `02-reference/exports.md`, `00-integration/skip-logic-and-navigation.md`, `00-integration/display-logic-and-navigation.md`, `00-integration/question-display-variants.md`, `00-integration/question-numbering.md`, `00-integration/placeholders-and-tokens.md`, `00-integration/partial-save-and-recovery.md`, `00-integration/survey-lifecycle-analytics.md`, `00-integration/end-page-logic.md`, `00-integration/answer-logic-and-navigation.md`, `00-integration/custom-field-logic-and-navigation.md`, `00-integration/progress.md`, `02-reference/value-derivation.md`
 
-Understand `useSurveySDK`, `onAction`, states. Do **not** read internal mapper/source paths.
+Understand `useSurveySDK`, `onAction`, `state.answers`. Do **not** read internal mapper/source paths.
 
 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. 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
+1. Fetch survey with `instanceId`; extract unique `question.type` values from `survey.pages`
+2. Write inventory to `implementation_plan.md` §3b (validate against `templates/survey-inventory.schema.json`)
+3. Read **always**: `component-checklist.md`, `00-integration/question-type-sdk-matrix.md`, `03-ui-specs/00-question-shell.md`, `03-ui-specs/12-survey-chrome.md`, `01-components/01-survey-page.md`, `01-components/02-question.md`, `01-components/14-intro-page.md`, `01-components/15-end-page.md`, `01-components/16-paused-page.md`
+4. For **each type in the survey**, read MANIFEST `questionTypes.{type}` → blueprint + reference + uiSpec; cross-check the matching row in `question-type-sdk-matrix.md`
+5. When config flags match MANIFEST `sharedUiSpecTriggers` (e.g. `gridLayout:dropdown`, `displayStyle:graphics`) → read matching `03-ui-specs/shared/` specs
+6. Copy `docs/templates/implementation_plan.md` → `./implementation_plan.md` and fill every section
+7. Copy `docs/templates/Question.tsx` as the dispatcher starting point
+8. **Auto-proceed to Phase 5** — do not wait for approval
+
+**Fallback:** If survey fetch fails, read all `01-components/*.md` blueprints before coding.
 
 ### PHASE 5: BUILD
 
-Read: `00-integration/constraints.md`, `00-integration/component-checklist.md`
+Read: `00-integration/constraints.md`, `00-integration/component-checklist.md`, `00-integration/question-type-sdk-matrix.md`
 
 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
+1. Read the matching row in `question-type-sdk-matrix.md` (answer shape, visibility helper, performance)
+2. Read `02-reference/question-types/` doc for data shape (MANIFEST `reference`)
+2. Read matching `03-ui-specs/` (MANIFEST `uiSpec`)
+3. If `gridLayout`, `displayStyle`, or `statementLayout` triggers shared specs → read `03-ui-specs/shared/`
 4. Cross-check `02-reference/config-field-index.md` for every non-default field
-5. Implement per ui-spec — monorepo devs may consult `apps/client/src/components/`; npm installs use ui-specs only
+5. Implement per ui-spec — trust SDK Integration Checklist in blueprint/reference + `templates/Question.tsx` + exported SDK types + `02-reference/value-derivation.md`
 
 Implement components per blueprints + UI specs. Use exported types:
 
 ```typescript
-import { useSurveySDK, ACTIONS, type SurveyAction } from '@explorer02/cfm-survey-sdk';
+import { useSurveySDK, ACTIONS, QUESTION_TYPE, type SurveyAction } from '@explorer02/cfm-survey-sdk';
 ```
 
+**Dispatch on flat `question.type` only** — **11** `QUESTION_TYPE` literals, no `subType`. See `MANIFEST.json` `typeLiterals`.
+
+**AWS deploy prep (when client prompt mentions AWS / CloudFront / S3 / EC2 / Sprinklr):** apply Next.js static export config **during this phase**, not at deploy time. Read `00-integration/setup.md#nextjs-aws-static-export` and `00-integration/aws-deploy.md` § Build Config. Fill `implementation_plan.md` §8.
+
 ### PHASE 6: VERIFY
 
 Read: `00-integration/constraints.md` (troubleshooting)
 
+Run: `bash templates/verify-agent-build.sh` (from project root, after copying script if needed)
+
 Checklist:
 
-- [ ] `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`)
+- [ ] `Question.tsx` copied from `docs/templates/Question.tsx` — covers all **11** `question.type` values
+- [ ] Each matrix variant routes by its own type literal (`CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX`) — **no `subType`**
 - [ ] 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
+- [ ] No imports from `@explorer02/cfm-survey-sdk/src/...` or `@repo/sdk/src/...`
+- [ ] `SurveyPage` handles loading / error / empty / all `state.phase` values / active content
+- [ ] Hook uses `state.answers`, `state.canGoBack`, `state.primaryButtonType`, and `payload.answerValue`
+- [ ] Stable `customFieldValues` ref when survey uses custom-field logic; passed to hook and `Question` visibility helpers
+- [ ] `SURVEY_PLACEHOLDERS` stable ref; `surveyOptions` in `useMemo` (see `placeholders-and-tokens.md`)
+- [ ] `SCROLL` + `RECORD_QUESTION_VIEW` lifecycle effects wired (see `survey-lifecycle-analytics.md`)
+- [ ] Monorepo: `packages/sdk` built before client dev (`npm run build`)
 - [ ] `npm run build` exits 0
+- [ ] **AWS intent:** `out/index.html` exists; file count ≤ 500; Next.js static export configured (`output: export`, `assetPrefix: "./"`)
 
 ### PHASE 7: DEPLOY (INPUT 3)
 
 Ask: *"Your survey is built and verified. Ready to deploy?"*
 
-If yes: `npx cfm-sdk deploy` (preferred) or `npx vercel --prod --yes`
+**Route by client prompt** (see MANIFEST `deployTargets` and `phases[7].selectTargetFromPrompt`):
+
+| Prompt mentions | Target | Action |
+|-----------------|--------|--------|
+| AWS, CloudFront, S3, EC2, Sprinklr | **AWS** | Read `00-integration/aws-deploy.md`; set env vars; run 3-channel deploy or `bash templates/deploy-to-aws.sh` |
+| Vercel or unspecified (default) | **Vercel** | `npx cfm-sdk deploy` (requires `VERCEL_TOKEN` or Vercel CLI) |
+
+**AWS env vars (dev machine):**
+
+```bash
+export CFM_INSTANCE_ID="<same JWT as SurveyPage>"
+export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+export OUT_DIR="<absolute path to out/ or dist/>"
+```
+
+**AWS success:** print live CloudFront HTTPS URL from `/deploy/complete`; ask client to open in browser.
+
+**Vercel success:** CLI prints production URL.
 
 ---
 
@@ -117,8 +165,11 @@ 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`, `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) |
+| Always first | `index.md`, `00-integration/client-integration-guide.md`, `00-integration/question-type-sdk-matrix.md`, `00-integration/setup.md`, `00-integration/useSurveySDK.md`, `00-integration/constraints.md` |
+| Lifecycle & placeholders | `00-integration/survey-lifecycle-analytics.md`, `00-integration/placeholders-and-tokens.md`, `00-integration/partial-save-and-recovery.md` |
+| Skip logic & progress | `00-integration/skip-logic-and-navigation.md`, `00-integration/display-logic-and-navigation.md`, `00-integration/question-display-variants.md`, `00-integration/question-numbering.md`, `00-integration/end-page-logic.md`, `00-integration/answer-logic-and-navigation.md`, `00-integration/custom-field-logic-and-navigation.md`, `00-integration/progress.md` |
+| Before any React code | `component-checklist.md`, `templates/Question.tsx`, MANIFEST `readAlways` docs |
+| After instanceId fetch | Per-type docs from MANIFEST `questionTypes` (blocking: `CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX`, `SLIDER_MATRIX`, `FILE_UPLOAD`) |
 | Config audit | `02-reference/config-field-index.md` |
-| Tooling | `MANIFEST.json`, `templates/implementation_plan.md` |
+| AWS deploy | `00-integration/aws-deploy.md`, `setup.md#nextjs-aws-static-export`, `templates/deploy-to-aws.sh` |
+| Tooling | `MANIFEST.json`, `templates/implementation_plan.md`, `templates/survey-inventory.schema.json` |

package/templates/docs/templates/Question.tsx

@@ -2,52 +2,118 @@
  * 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.
+ * Covers all 11 QUESTION_TYPE literals — see question-type-sdk-matrix.md for per-type wiring.
+ * Route on `question.type` / `QUESTION_TYPE` only — no subType.
  *
  * 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 React, { useMemo } from 'react';
+import type { SurveyQuestion, AnswerValue, SurveyAnswers, CustomFieldValueMap, HeatmapAnswer, HeatmapQuestion } from '@explorer02/cfm-survey-sdk';
+import { QUESTION_TYPE, resolveSurveyQuestionPlaceholders, getVisibleMatrixItemsForAnswers, getVisibleMcqOptionsForAnswers, getVisibleRankOrderOptionsForAnswers } from '@explorer02/cfm-survey-sdk';
 import { CsatMatrixScale } from './CsatMatrixScale';
 import { SliderMatrixScale } from './SliderMatrixScale';
 import { LikertMatrixScale } from './LikertMatrixScale';
 import { FileUploadScale } from './FileUploadScale';
+import { HeatmapScale } from './HeatmapScale';
+import { RankOrderScale } from './RankOrderScale';
 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;
+  allAnswers: SurveyAnswers;
+  allQuestions: SurveyQuestion[];
+  customFieldValues?: CustomFieldValueMap;
+  onSelect: (answerValue: AnswerValue) => void;
 };
 
-export default function Question({ question, selectedValue, validationError, onSelect }: QuestionProps) {
+export default function Question({
+  question,
+  selectedValue,
+  validationError,
+  allAnswers,
+  allQuestions,
+  customFieldValues = {},
+  onSelect,
+}: QuestionProps) {
+  const questionsById = useMemo(
+    () => new Map(allQuestions.map(q => [q.id, q])),
+    [allQuestions]
+  );
+
+  const displayQuestionText = useMemo(
+    () => resolveSurveyQuestionPlaceholders(question.questionText, allAnswers, questionsById),
+    [question.questionText, allAnswers, questionsById]
+  );
+
+  const displayQuestionDescription = useMemo(
+    () =>
+      question.questionDescription
+        ? resolveSurveyQuestionPlaceholders(question.questionDescription, allAnswers, questionsById)
+        : undefined,
+    [question.questionDescription, allAnswers, questionsById]
+  );
+
+  const matrixQuestion = useMemo(() => {
+    const isMatrix =
+      question.type === QUESTION_TYPE.CFM_MATRIX ||
+      question.type === QUESTION_TYPE.CSAT_MATRIX ||
+      question.type === QUESTION_TYPE.RATING_MATRIX ||
+      question.type === QUESTION_TYPE.SLIDER_MATRIX;
+
+    if (!isMatrix) return question;
+
+    const { statementRows, scaleColumns } = getVisibleMatrixItemsForAnswers(
+      question,
+      allAnswers,
+      allQuestions,
+      customFieldValues
+    );
+
+    return {
+      ...question,
+      statementRows,
+      ...(question.type === QUESTION_TYPE.CSAT_MATRIX || question.type === QUESTION_TYPE.CFM_MATRIX
+        ? { scaleColumns }
+        : {}),
+    };
+  }, [question, allAnswers, allQuestions, customFieldValues]);
+
+  const visibleMcqOptions = useMemo(() => {
+    if (question.type !== QUESTION_TYPE.MCQ) return [];
+    return getVisibleMcqOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues);
+  }, [question, allAnswers, allQuestions, customFieldValues]);
+
+  const rankOrderQuestion = useMemo(() => {
+    if (question.type !== QUESTION_TYPE.RANK_ORDER) return null;
+    return {
+      ...question,
+      options: getVisibleRankOrderOptionsForAnswers(
+        question,
+        allAnswers,
+        allQuestions,
+        customFieldValues
+      ),
+    };
+  }, [question, allAnswers, allQuestions, customFieldValues]);
+
   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 }} />
+        <span dangerouslySetInnerHTML={{ __html: displayQuestionText }} />
         {question.required && <span className="text-red-500 ml-1">*</span>}
       </h2>
-      {question.description && (
+      {displayQuestionDescription && (
         <div
           className="text-sm text-gray-600 mt-2 leading-relaxed"
-          dangerouslySetInnerHTML={{ __html: question.description }}
+          dangerouslySetInnerHTML={{ __html: displayQuestionDescription }}
         />
       )}
 
-      {question.type === 'rating' && (
+      {question.type === QUESTION_TYPE.NPS_SCALE && (
         <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">
@@ -60,9 +126,8 @@ export default function Question({ question, selectedValue, validationError, onS
                   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
-                      }%`,
+                      ? (question.midLabelIndex / (question.options.length - 1)) * 100
+                      : 50}%`,
                   }}
                   dangerouslySetInnerHTML={{ __html: question.midLabel }}
                 />
@@ -78,164 +143,166 @@ export default function Question({ question, selectedValue, validationError, onS
             options={question.options}
             selectedValue={selectedValue}
             onSelect={onSelect}
+            variant="nps"
+            buttonStyle={question.buttonStyle}
           />
         </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'
-                    }`}
+      {question.type === QUESTION_TYPE.MCQ && (() => {
+        const effectiveValue =
+          selectedValue ??
+          (question.selectionMode === 'single'
+            ? question.defaultOptionIds?.[0]
+            : question.defaultOptionIds);
+
+        if (question.selectionMode === 'multiple') {
+          const selectedIds: string[] = Array.isArray(effectiveValue)
+            ? effectiveValue.filter((id): id is string => typeof id === 'string')
+            : typeof effectiveValue === 'string'
+              ? [effectiveValue]
+              : [];
+
+          const handleToggle = (optionId: string) => {
+            const next = selectedIds.includes(optionId)
+              ? selectedIds.filter(id => id !== optionId)
+              : question.maxSelections && selectedIds.length >= question.maxSelections
+                ? selectedIds
+                : [...selectedIds, optionId];
+            onSelect(next);
+          };
+
+          return (
+            <div className="space-y-3">
+              {visibleMcqOptions.map(option => {
+                const isSelected = selectedIds.includes(option.id);
+                return (
+                  <label
+                    key={option.id}
+                    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="checkbox"
+                      name={question.id}
+                      checked={isSelected}
+                      onChange={() => handleToggle(option.id)}
+                      className="sr-only"
+                    />
+                    <span
+                      className="text-[15px] font-medium text-gray-900 leading-tight"
+                      dangerouslySetInnerHTML={{ __html: option.optionLabel }}
+                    />
+                  </label>
+                );
+              })}
+            </div>
+          );
+        }
+
+        const singleSelected = typeof effectiveValue === 'string' ? effectiveValue : undefined;
+
+        return (
+          <div className="space-y-3">
+            {visibleMcqOptions.map(option => {
+              const isSelected = singleSelected === option.id;
+              return (
+                <label
+                  key={option.id}
+                  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'}`}
                 >
-                  {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>
+                  <input
+                    type="radio"
+                    name={question.id}
+                    checked={isSelected}
+                    onChange={() => onSelect(option.id)}
+                    className="sr-only"
+                  />
+                  <span
+                    className="text-[15px] font-medium text-gray-900 leading-tight"
+                    dangerouslySetInnerHTML={{ __html: option.optionLabel }}
+                  />
+                </label>
+              );
+            })}
+          </div>
+        );
+      })()}
+
+      {question.type === QUESTION_TYPE.RANK_ORDER && rankOrderQuestion && (
+        <RankOrderScale
+          question={rankOrderQuestion}
+          selectedValue={
+            typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue)
+              ? selectedValue
+              : undefined
+          }
+          onSelect={onSelect}
+        />
       )}
 
-      {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 === QUESTION_TYPE.TEXTFIELD && (
+        <textarea
+          rows={question.inputVariant === 'long' ? 4 : 1}
+          value={(selectedValue as string) ?? ''}
+          onChange={e => onSelect(e.target.value)}
+          placeholder={question.placeholder || 'Type your response here...'}
+          className="w-full rounded border border-gray-300 p-4 text-sm outline-none focus:border-[#e20074]"
+        />
       )}
 
-      {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>
+      {question.type === QUESTION_TYPE.CFM_MATRIX && (
+        <LikertMatrixScale
+          question={matrixQuestion as typeof question & { type: typeof QUESTION_TYPE.CFM_MATRIX }}
+          selectedValue={typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue) ? selectedValue : {}}
+          onSelect={onSelect}
+        />
       )}
 
-      {/* 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 === QUESTION_TYPE.CSAT_MATRIX ||
+        question.type === QUESTION_TYPE.RATING_MATRIX) && (
+        <CsatMatrixScale
+          question={matrixQuestion as Extract<SurveyQuestion, { type: typeof QUESTION_TYPE.CSAT_MATRIX | typeof QUESTION_TYPE.RATING_MATRIX }>}
+          selectedValue={typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue) ? selectedValue : {}}
+          onSelect={onSelect}
+        />
       )}
 
-      {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 === QUESTION_TYPE.SLIDER_MATRIX && (
+        <SliderMatrixScale
+          question={matrixQuestion as typeof question & { type: typeof QUESTION_TYPE.SLIDER_MATRIX }}
+          selectedValue={typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue) ? selectedValue : {}}
+          onSelect={onSelect}
+        />
       )}
 
-      {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 === QUESTION_TYPE.FILE_UPLOAD && (
+        <FileUploadScale question={question} selectedValue={selectedValue} onSelect={onSelect} />
       )}
 
-      {question.type === 'file_upload' && (
-        <div className="space-y-3">
-          <FileUploadScale
-            question={question}
-            selectedValue={selectedValue}
-            onSelect={onSelect}
-          />
-        </div>
+      {question.type === QUESTION_TYPE.HEATMAP && (
+        <HeatmapScale
+          question={question as HeatmapQuestion}
+          selectedValue={Array.isArray(selectedValue) ? (selectedValue as HeatmapAnswer) : undefined}
+          onSelect={onSelect}
+        />
       )}
 
-      {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" />
+      {question.type === QUESTION_TYPE.TEXT_AND_MEDIA && question.media?.url && (
+        <div className={`mt-4 flex w-full ${question.media.alignment?.includes('CENTER') ? 'justify-center' : question.media.alignment?.includes('RIGHT') ? 'justify-end' : 'justify-start'}`}>
+          <div style={{ width: question.media.size ? `${question.media.size}%` : '100%' }}>
+            {question.media.mimeType?.startsWith('video/') || question.media.mimeType === 'VIDEO' ? (
+              <video controls src={question.media.url} className="max-w-full rounded-md" />
             ) : (
-              <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>
+              <img src={question.media.url} alt={question.media.title || ''} className="max-w-full rounded-md" />
             )}
+            {question.media.title && <p className="text-sm text-gray-500 text-center mt-2">{question.media.title}</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 className="mt-4 rounded border border-gray-800 bg-gray-200 py-3 px-4">
+          <p className="text-sm font-bold text-gray-900">{validationError}</p>
         </div>
       )}
     </section>