@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

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

@@ -1,34 +1,34 @@
-# UI Spec: CFM Matrix (`type: 'matrix'`, `subType: 'CFM_MATRIX'`)
+# UI Spec: CFM Matrix (`type: 'CFM_MATRIX'`)
 
 > **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/LikertMatrixScale.tsx`
-> **SDK type:** `MatrixQuestion` — `fetchSurvey/types/matrix.ts`
+> **SDK type:** `CfmMatrixQuestion` — `fetchSurvey/types/cfmMatrix.ts`
 > **Component blueprint:** `01-components/06-likert-matrix-scale.md`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `rows[]`, `columns[]` | ✅ | Grid / carousel / dropdown data |
-| `matrixFormat` | ✅ | Orchestrator routing |
-| `answerType` | ✅ | `'multiple'` → checkboxes |
-| `matrixType: 'bipolar'` | ✅ | 25% left + 25% right columns |
-| `labels[]` | ✅ | Anchor labels above scale |
+| `statementRows[]`, `scaleColumns[]` | ✅ | Grid / carousel / dropdown data |
+| `gridLayout` | ✅ | Orchestrator routing |
+| `selectionMode` | ✅ | `'multiple'` → checkboxes |
+| `statementLayout: 'bipolar'` | ✅ | 25% left + 25% right columns |
+| `scaleAnchorLabels[]` | ✅ | Anchor labels above scale |
 | `transposeTable` | ✅ | Swap row/col iteration |
-| `repeatScale` | ✅ | Re-render header per row |
-| `enableScale` | ✅ | Show/hide column header row |
-| `hasNotApplicable` | ✅ | N/A column with mutex |
+| `repeatColumnHeaders` | ✅ | Re-render header per row |
+| `showColumnHeaders` | ✅ | Show/hide column header row |
+| `hasNotApplicableOption` | ✅ | N/A column with mutex |
 
 ## Config Decision Tree
 
 ```
 CFM_MATRIX
-├── matrixFormat === 'dropdown' → LikertMatrixDropdownLayout (MatrixDropdown per row)
-├── matrixFormat === 'carousel' → LikertMatrixCarouselLayout (one row, prev/next, blue dots)
+├── gridLayout === 'dropdown' → LikertMatrixDropdownLayout (MatrixDropdown per row)
+├── gridLayout === 'carousel' → LikertMatrixCarouselLayout (one row, prev/next, blue dots)
 └── else → LikertMatrixGridLayout
     ├── transposeTable ? columns×rows : rows×columns
-    ├── repeatScale ? header per row : single header
-    ├── enableScale ? column headers : hidden
-    └── matrixType === 'bipolar' ? 25% | scale | 25% layout
+    ├── repeatColumnHeaders ? header per row : single header
+    ├── showColumnHeaders ? column headers : hidden
+    └── statementLayout === 'bipolar' ? 25% | scale | 25% layout
 ```
 
 ## Interactive Behaviors
@@ -37,8 +37,8 @@ CFM_MATRIX
 |----------|-----------|--------|
 | Click selected radio again | single-select grid/carousel | Clear row (`undefined`) |
 | N/A selected | any | Other cols opacity 0.4, disabled |
-| Multi N/A | answerType multiple | Sets `[null]` exclusively |
-| Multi toggle | answerType multiple | Add/remove from array |
+| Multi N/A | selectionMode multiple | Sets `[null]` exclusively |
+| Multi toggle | selectionMode multiple | Add/remove from array |
 
 ## Grid Layout
 
@@ -46,21 +46,40 @@ CFM_MATRIX
 - Zebra rows: even rows `rgba(249,250,251,0.8)`
 - Native inputs: `accentColor: #e20074`, 18×18px
 
-## Carousel
+## Carousel — Implementation Recipe
 
-- Blue active dot: `#2563eb` (Likert only)
-- Card: white, border, shadow, centered row text
+| Rule | Behavior |
+|------|----------|
+| Prev button | Disabled when `currentRowIndex === 0` |
+| Next button | Disabled when on last visible row |
+| Dot indicators | Click dot → jump to that row index |
+| On answer | **Do not** auto-advance to next row |
+| Keyboard | Optional Left/Right for prev/next |
+| Active dot (Likert) | `#2563eb`, expanded pill `20×8px` vs `8×8px` inactive |
 
-## Answer Mutation
+One statement row visible at a time; column headers below cells when `showColumnHeaders`.
+
+## N/A mutex (all layouts)
+
+| Action | Result |
+|--------|--------|
+| Select N/A | Clear other column values for row; other inputs opacity 0.4 + disabled |
+| Select column after N/A | Clear N/A first |
+| Multi-select + N/A | N/A sets `[null]` exclusively |
+
+## Implementation Recipe
+
+Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
 
 ```typescript
-onSelect(MatrixAnswerMap) // Record<rowId, value | value[] | null>
+onSelect(MatrixRowAnswers) // Record<statementRows[].id, value | value[] | null>
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } })
 ```
 
 ## Agent Checklist
 
-- [ ] All three matrixFormat branches
-- [ ] transposeTable + repeatScale + enableScale
-- [ ] Bipolar 25/50/25 layout with rightText
+- [ ] All three gridLayout branches
+- [ ] transposeTable + repeatColumnHeaders + showColumnHeaders
+- [ ] Bipolar 25/50/25 layout with oppositeStatementText
 - [ ] Single-select deselect on re-click
 - [ ] N/A mutex with opacity 0.4

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

@@ -1,65 +1,41 @@
-# UI Spec: CSAT / Rating Matrix (`subType: 'CSAT_MATRIX' | 'RATING_MATRIX'`)
+# UI Spec: Rating Matrix Grid (`type: 'RATING_MATRIX'`)
 
 > **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CsatMatrixScale.tsx`
-> **SDK type:** `MatrixQuestion` — `fetchSurvey/types/matrix.ts`
+> **SDK type:** `RatingMatrixQuestion` — `fetchSurvey/types/ratingMatrix.ts`
 > **Component blueprint:** `01-components/05-csat-matrix-scale.md`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `buttonType` | ✅ | Grid vs vertical list routing |
-| `matrixFormat` | ✅ | carousel vs standard |
-| `hasNotApplicable` | ✅ | Checkbox below row (vertical) or N/A column (grid) |
+| `statementRows[]`, `scaleColumns[]` | ✅ | Grid / carousel / dropdown data |
+| `displayStyle` | ✅ | Grid vs vertical list routing |
+| `gridLayout` | ✅ | carousel vs standard vs dropdown |
+| `hasNotApplicableOption` | ✅ | N/A column or checkbox |
 | `reverseScaleOrder` | ✅ | Flip emoji/star/number index |
-| `labels[]` | ✅ | Anchor row above columns |
-| `columns[].color` | ✅ | RATING_MATRIX badge colors |
+| `scaleAnchorLabels[]` | ✅ | Anchor row above columns |
+| `minLabel` / `maxLabel` | ✅ | Rendered in Question.tsx above scale |
+| `scaleColumns[].accentColor` | ✅ | NPS-style badge colors when numbered |
 
 ## Config Decision Tree
 
-```
-CSAT_MATRIX | RATING_MATRIX
-├── matrixFormat === 'carousel' → CsatMatrixCarousel
-├── buttonType in (dropdown, selectbox, radio) → CsatMatrixVerticalList
-│   ├── dropdown → MatrixDropdown placeholder "Select..."
-│   ├── selectbox → full-width cards #fdf2f8 selected
-│   └── else → card radio list
-└── else → CsatMatrixGrid
-    ├── emoji → getEmojiForIndex + hover scale + ring when selected
-    ├── star → opacity 0.5 unselected; filled/empty icons
-    ├── numbered → 40×40 badge; selected magenta fill
-    └── graphics → CustomSliderTrack per row (not in grid — carousel only)
-```
-
-## Grid Structure
-
-- Row label: `180px` fixed column
-- N/A column: `56px` when `hasNotApplicable`
-- Alternating row backgrounds
-- Column headers OR `labels[]` anchor row with percentage positioning
+Same as `CSAT_MATRIX` — reuse `CsatMatrixScale`. See [04-csat.md](04-csat.md) for emoji/star/carousel/N/A/graphics recipes.
 
-## Carousel
+## Carousel / N/A / scale labels
 
-- Pink active dot expands: `20px × 8px` vs `8px` inactive
-- Column labels below cells
-- Emoji tooltip via hover state (`hoveredCell`)
-- Graphics mode: slider maps column index
-
-## Tooltips
-
-`title={col.label}` recommended on grid cells (emoji hover uses scale transform).
+Follow CSAT Implementation Recipes in [04-csat.md](04-csat.md): pink carousel dots, N/A mutex, `tickLabels` from `scaleColumns[].label` on graphics sliders.
 
 ## Answer Mutation
 
+Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+
 ```typescript
-onSelect(MatrixAnswerMap)
-// hasNotApplicable: null for N/A; undefined clears
+onSelect(MatrixRowAnswers)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } })
 ```
 
 ## Agent Checklist
 
-- [ ] scaleColumns = columns.filter(c => c.value !== null)
-- [ ] All buttonType × matrixFormat branches
-- [ ] reverseScaleOrder on emoji/star/numbered
-- [ ] Carousel pink dot indicators
-- [ ] Vertical selectbox cards match standalone radio styling
+- [ ] Reuse CsatMatrixScale with `RATING_MATRIX` type
+- [ ] Apply accentColor on numbered badges when present
+- [ ] minLabel / maxLabel above grid when set

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

@@ -1,4 +1,4 @@
-# UI Spec: Slider Matrix (`type: 'slider_matrix'`)
+# UI Spec: Slider Matrix (`type: 'SLIDER_MATRIX'`)
 
 > **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/SliderMatrixScale.tsx`
 > **SDK type:** `SliderMatrixQuestion` — `fetchSurvey/types/sliderMatrix.ts`
@@ -36,6 +36,23 @@ sliceWidth = tickValues.length > 1 ? 100 / (tickValues.length - 1) : 100
 // graphics: plain text label instead of colored badge
 ```
 
+## CustomSliderTrack per row — scale labels
+
+```typescript
+<CustomSliderTrack
+  min={row.min}
+  max={row.max}
+  htmlStep={row.htmlStep}
+  value={rowVal as number}
+  tickLabels={row.tickLabels ?? scaleColumns.map(c => c.label)}
+  ticks={row.ticks}
+  sliderType={question.sliderStyle === 'graphics' ? 'graphics' : undefined}
+  onChange={v => updateRow(row.id, v)}
+/>
+```
+
+Pass **`scaleColumns[].label`** (or row tick labels) as `tickLabels` — required for correct tooltip text (Day 19 fix).
+
 ## N/A Behavior
 
 - Checked → `rowVal === 'N/A'`; slider disabled, input grayed

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

@@ -1,18 +1,18 @@
-# UI Spec: File Upload (`type: 'file_upload'`)
+# UI Spec: File Upload (`type: 'FILE_UPLOAD'`)
 
-> **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`
+> **Upload API:** [`00-integration/file-upload-aws.md`](../00-integration/file-upload-aws.md)
 
 ## Config Inventory
 
-| Field | Implemented | UI impact |
-|-------|-------------|-----------|
-| `uploadMessage` | ✅ | HTML in dropzone (bold 16px) |
-| `supportedFileFormats` | ✅ | Validation + accept attribute |
-| `maxFileCount` | ✅ | Total file limit |
-| `fileSizeLimit` | ✅ | MB limit |
-| `fileSizeLimitType` | ✅ | `PER_FILE` or `IN_TOTAL` |
+| Field | UI impact |
+|-------|-----------|
+| `uploadMessage` | HTML in dropzone (bold 16px) |
+| `supportedFileFormats` | Validation + accept attribute |
+| `maxFileCount` | Total file limit |
+| `fileSizeLimit` | MB limit |
+| `fileSizeLimitType` | `PER_FILE` or `IN_TOTAL` |
 
 ## Layout Anatomy
 
@@ -20,7 +20,7 @@
 [uploadMessage HTML in dashed dropzone]
   File limit: N; File size limit: XMB/file|in total; Supports: ...
 [local error banner — red if validation fails]
-[file list cards: icon, name, size, remove ×]
+[file list cards: icon, name, size, uploading…, remove ×]
 ```
 
 ## Interactive States
@@ -31,24 +31,45 @@
 | Hover | `#e20074` | `#fdf2f8` |
 | Drag active | `#e20074` | `#fdf2f8` |
 
-## Local Validation (before SDK)
+## Implementation Recipe
 
-1. Max file count exceeded
-2. Unsupported extension
-3. PER_FILE size exceeded
-4. IN_TOTAL cumulative size exceeded
+### Phase 1 — Local pick + validate
 
-Error banner: `#fee2e2` bg, `#b91c1c` text.
+1. Hidden `<input type="file" multiple={maxFileCount > 1}>`
+2. Drag enter/over/leave/drop on dropzone
+3. Reject: wrong extension, count exceeded, size exceeded
+
+### Phase 2 — Upload (required for submit)
+
+```
+User picks File
+  → POST {uploadApi}/get-upload-url { fileName, contentType, questionId }
+  ← { uploadUrl, fileId, mediaUrl }
+  → PUT uploadUrl (binary body, file Content-Type)
+  → onSelect([...existing, { id: fileId, mediaUrl, name, mimeType, size }])
+  → onAction(CHANGE)
+```
+
+See [`file-upload-aws.md`](../00-integration/file-upload-aws.md).
+
+### Phase 3 — Remove
+
+Remove from list → `onSelect(undefined)` when empty, else updated `UploadedFileAnswer[]`.
 
 ## Answer Mutation
 
 ```typescript
-onSelect(File[] | undefined) // undefined when all removed
+// After upload completes — NOT raw File[]
+onSelect: (value: UploadedFileAnswer[] | undefined) => void
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: UploadedFileAnswer[] } })
 ```
 
+**Non-submittable:** storing `File[]` only — SDK submit drops attachments.
+
 ## Agent Checklist
 
-- [ ] Hidden `<input type="file">` triggered by dropzone click
-- [ ] Drag enter/over/leave/drop handlers
-- [ ] Dynamic constraints line in dropzone
-- [ ] File list with remove button (hover red)
+- [ ] Local validation before upload
+- [ ] Presigned upload wired; progress/spinner per file
+- [ ] Final answer shape: `UploadedFileAnswer[]` with `id` + `mediaUrl`
+- [ ] Remove clears answer or passes updated array
+- [ ] Matrix row: [`question-type-sdk-matrix.md#file_upload`](../00-integration/question-type-sdk-matrix.md#file_upload)

package/templates/docs/03-ui-specs/11-text-and-media.md

@@ -1,4 +1,4 @@
-# UI Spec: Text and Media (`type: 'text_and_media'`)
+# UI Spec: Text and Media (`type: 'TEXT_AND_MEDIA'`)
 
 > **Reference:** `apps/client/src/components/Question.tsx` (inline)
 > **SDK type:** `TextAndMediaQuestion` — `fetchSurvey/types/textAndMedia.ts`
@@ -8,42 +8,42 @@
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `mediaUrl` | ✅ | Required to render media block |
-| `mediaMimeType` | ✅ | `video/` or `VIDEO` → `<video>`; else `<img>` |
-| `mediaTitle` | ✅ | Caption below media, centered gray text |
-| `mediaAlignment` | ✅ | Flex justify: CENTER / RIGHT / default left |
-| `mediaSize` | ✅ | Width `%` on media container; default 100% |
+| `media?.url` | ✅ | Required to render media block |
+| `media?.mimeType` | ✅ | `video/` or `VIDEO` → `<video>`; else `<img>` |
+| `media?.title` | ✅ | Caption below media, centered gray text |
+| `media?.alignment` | ✅ | Flex justify: CENTER / RIGHT / default left |
+| `media?.size` | ✅ | Width `%` on media container; default 100% |
 
 No answer input — display-only question.
 
-## Layout Anatomy
+## Media alignment anatomy
 
 ```
-[question title + description — standard shell]
-
-┌─ flex container (justify per mediaAlignment) ──────────────┐
-│  ┌─ media block (width: mediaSize%) ──────────────────┐   │
-│  │  <video controls> or <img>                          │   │
-│  │  [optional mediaTitle caption]                      │   │
-│  └─────────────────────────────────────────────────────┘   │
-└────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────┐
+│  questionText (HTML)                    │
+│  questionDescription (optional)         │
+├─────────────────────────────────────────┤
+│  [ media block — flex container ]       │
+│    alignment LEFT:   justify-start      │
+│    alignment CENTER: justify-center     │
+│    alignment RIGHT:  justify-end        │
+│    width: media.size % (default 100)    │
+│    <img> or <video> max-w-full          │
+│    caption: media.title (centered gray) │
+└─────────────────────────────────────────┘
 ```
 
-## Alignment Mapping
-
-| `mediaAlignment` | CSS |
-|------------------|-----|
-| `TOP_CENTER`, `BOTTOM_CENTER` | `justify-center` |
-| `TOP_RIGHT`, `BOTTOM_RIGHT` | `justify-end` |
-| default | `justify-start` |
-
-## Answer Mutation
-
-None — no `onSelect` payload for this type.
+Container-level media (survey chrome) is separate — see `03-ui-specs/12-survey-chrome.md`.
 
 ## Agent Checklist
 
-- [ ] Render only when `mediaUrl` is present
-- [ ] Video vs image from mime type
+- [ ] Render only when `question.media?.url` is present
+- [ ] Video vs image from `media.mimeType`
 - [ ] `max-w-full rounded-md shadow-sm` on media element
-- [ ] Optional centered caption for `mediaTitle`
+- [ ] Optional centered caption for `media.title`
+- [ ] Respect `media.alignment` (LEFT / CENTER / RIGHT) and `media.size` width %
+
+## SDK Integration Checklist (agent)
+
+- [ ] No CHANGE action — display-only
+- [ ] Matrix row: [`question-type-sdk-matrix.md#text_and_media`](../00-integration/question-type-sdk-matrix.md#text_and_media)

package/templates/docs/03-ui-specs/12-survey-chrome.md

@@ -1,17 +1,22 @@
 # UI Spec: Survey Chrome
 
-> **Reference:** `SurveyPage.tsx`, `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `LanguageSelector.tsx`
-> **Component blueprints:** `01-components/01-survey-page.md`, `10-header-footer.md`, `11-progress-bar.md`, `12-language-selector.md`
+> **Reference:** `SurveyPage.tsx`, `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `LanguageSelector.tsx`, `IntroPage.tsx`, `EndPage.tsx`, `PausedPage.tsx`
+> **Component blueprints:** `01-components/01-survey-page.md`, `10-header-footer.md`, `11-progress-bar.md`, `12-language-selector.md`, `14-intro-page.md`, `15-end-page.md`, `16-paused-page.md`
 
-## SurveyPage — 5-State Machine
+## SurveyPage — Phase Router
 
 | State | Condition | UI |
 |-------|-----------|-----|
 | Loading | `surveyQueryResults.isLoading` | Centered "Loading..." |
 | Error | `surveyQueryResults.error` | Red error message |
 | Empty | `!survey` | "No survey data" |
-| Submitted | `submitSurveyResults.data` | Thank you message |
-| Active | else | Questions + nav |
+| Intro | `state.phase.kind === 'intro'` | `IntroPage` + Start CTA |
+| Paused | `state.phase.kind === 'paused'` | `PausedPage` |
+| End | `state.phase.kind === 'end'` | `EndPage` |
+| Submitted | `state.phase.kind === 'submitted'` | Terminal message |
+| Expired | `state.phase.kind === 'expired'` | Terminal message |
+| Quota | `state.phase.kind === 'quota_fulfilled'` | Terminal message |
+| Active | `state.phase.kind === 'content'` | Questions + nav |
 
 ## Active Layout
 
@@ -22,7 +27,7 @@ main (max-w-4xl)
   LanguageSelector (hidden if ≤1 language)
   Questions (space-y-12)
   Submit error (if any)
-  Nav: Back (if page > 0) + Next/Submit
+  Nav: Back (if canGoBack) + Next/Submit (primaryButtonType)
 Footer
 ```
 
@@ -32,10 +37,10 @@ German when `survey.language.startsWith('de')`:
 
 | Action | EN | DE |
 |--------|----|----|
-| Back | Zurück | Back |
-| Next | Weiter | Next |
-| Submit | Absenden | Submit |
-| Submitting | Wird gesendet... | Submitting... |
+| Back | Back | Zurück |
+| Next | Next | Weiter |
+| Submit | Submit | Absenden |
+| Submitting | Submitting... | Wird gesendet... |
 
 ## Button Tokens
 
@@ -44,17 +49,56 @@ German when `survey.language.startsWith('de')`:
 
 ## ProgressBar
 
-Pink fill bar, `300ms` width transition on `progressPercentage`.
+Pink fill bar. Bound to `state.progressPercentage` (path-scoped — see `00-integration/progress.md`).
 
 ## LanguageSelector
 
 - Hidden when `languages.length <= 1`
 - Focus ring: `#2563eb`
+- Pass `language` in `useMemo` hook options — SDK remaps survey client-side (no refetch)
+
+## Question numbering
+
+Render ordinals from SDK on content pages:
+
+```tsx
+{question.questionNumber != null && (
+  <span className="mr-1 font-semibold">{question.questionNumber}.</span>
+)}
+```
+
+See [`question-numbering.md`](../00-integration/question-numbering.md).
+
+## Special pages
+
+| Phase | Component | Action |
+|-------|-----------|--------|
+| `intro` | `IntroPage` | `page={state.specialPage}` · `onStart={() => onAction({ type: 'START' })}` |
+| `paused` | `PausedPage` | `page={state.specialPage}` · read-only, no nav |
+| `end` | `EndPage` | `page={state.specialPage}` · terminal thank-you |
+
+## Terminal phases
+
+Render a simple message (no question nav) for:
+
+- `submitted` — already completed
+- `expired` — survey expired
+- `quota_fulfilled` — quota reached
+
+Keep Header/Footer chrome consistent across all phases.
+
+## Submit loading
+
+Disable primary Next/Submit when `submitSurveyResults.isLoading`; label "Submitting…" / "Wird gesendet…".
 
 ## Agent Checklist
 
-- [ ] All 5 states implemented
-- [ ] `onAction({ type: 'CHANGE' })` wired per question
-- [ ] PREVIOUS / NEXT actions on nav buttons
+- [ ] All phase branches implemented
+- [ ] `onAction({ type: 'START' })` on intro
+- [ ] `onAction({ type: 'CHANGE' })` wired per question with `allAnswers` / `allQuestions`
+- [ ] Back uses `state.canGoBack`; primary uses `state.primaryButtonType`
 - [ ] ProgressBar receives `state.progressPercentage`
 - [ ] Header/Footer on every state branch
+- [ ] `questionNumber` prefix when present on content questions
+- [ ] Intro / Paused / End / terminal phase branches
+- [ ] Submit button disabled while `submitSurveyResults.isLoading`

package/templates/docs/03-ui-specs/13-heatmap.md

@@ -0,0 +1,80 @@
+# UI Spec: Heatmap (`type: 'HEATMAP'`)
+
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/HeatmapScale.tsx`
+> **SDK type:** `HeatmapQuestion` — `fetchSurvey/types/heatmap.ts`
+> **Component blueprint:** `01-components/17-heatmap-scale.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `questionText` | ✅ (shell) | Bold title + required asterisk |
+| `questionDescription` | ✅ (shell) | Instruction text below title |
+| `required` | ✅ (shell + SDK) | Asterisk + validation on NEXT |
+| `imageUrl` | ✅ | Center-aligned interactive image |
+| `maxClicksAllowed` | ✅ | Footer hint count; blocks new clicks at limit |
+| `regions` | ❌ (respondent UI) | Logic only — not rendered on survey |
+
+## Layout Anatomy
+
+```
+[Question shell: title *, description]
+[Heatmap container — relative, inline-block, max-width 100%]
+  [<img> — object-contain, display block, crosshair cursor]
+  [Spot overlay — absolute inset-0, pointer-events-none]
+    [Orange circle markers at normalized x/y positions]
+[Footer hint — info icon + max spots text]
+[Validation error — from Question shell]
+```
+
+## Spot Marker Visual Spec
+
+| Property | Value |
+|----------|-------|
+| Shape | Circle |
+| Diameter | 16px |
+| Fill | `#F97316` |
+| Border | 2px solid `#FFFFFF` |
+| Shadow | `0 1px 3px rgba(0,0,0,0.25)` |
+| Position | `left: x * 100%`, `top: y * 100%`, `transform: translate(-50%, -50%)` |
+
+## Interactive States
+
+| State | Behavior |
+|-------|----------|
+| Image loading | Spinner overlay; clicks disabled |
+| Ready | `cursor: crosshair` on image |
+| At max clicks | Block new adds; allow remove |
+| Removing last spot | `onSelect(undefined)` |
+
+## Footer Hint Text
+
+```
+ⓘ You can select up to {maxClicksAllowed} spot(s). To change your selection, simply click on the same spot again to remove it.
+```
+
+Use singular "spot" when `maxClicksAllowed === 1`.
+
+## Answer Mutation
+
+```typescript
+onSelect(HeatmapClickPoint[] | undefined)
+// HeatmapClickPoint = { id: string; x: number; y: number }
+// x, y normalized 0–1 relative to rendered image bounds
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: spots } })
+```
+
+Copy coord helpers from [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts): `getNormalizedClickFromImage`, `findSpotNearClick` (14px remove radius), `createNewSpot`.
+
+## Logic fields
+
+`HEATMAP` and `HEATMAP_REGION` — see [`logic-fields-catalog.md`](../00-integration/logic-fields-catalog.md).
+
+## Agent Checklist
+
+- [ ] Click handler on `<img>` element (not overlay) for precise coordinates
+- [ ] `inline-block` wrapper so spots align with image bounds
+- [ ] Toggle-remove within 14px hit radius
+- [ ] Wait for `onLoad` before accepting clicks
+- [ ] Percentage-positioned spots (survives resize)
+- [ ] Do NOT render region overlays on respondent UI