@explorer02/cfm-survey-sdk 0.2.0 → 0.2.2

package/templates/docs/03-ui-specs/02-radio.md

@@ -1,7 +1,6 @@
-# UI Spec: Radio MCQ (`type: 'radio'`)
+# UI Spec: MCQ (`type: 'MCQ'`)
 
-> **Reference:** `apps/client/src/components/Question.tsx` (inline)
-> **SDK type:** `RadioQuestion` — `fetchSurvey/types/radio.ts`
+> **SDK type:** `McqQuestion` — `fetchSurvey/types/mcq.ts`
 > **Component blueprint:** `01-components/02-question.md`
 
 ## Config Inventory
@@ -9,43 +8,26 @@
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
 | `options[]` | ✅ | One card per option |
-| `options[].label` | ✅ | HTML via `dangerouslySetInnerHTML` |
-| `options[].value` | ✅ | Selection value; `null` → empty string on input |
-| `isMultiSelect` | ❌ | SDK supports; client is single-select only |
+| `options[].optionLabel` | ✅ | HTML via `dangerouslySetInnerHTML` |
+| `options[].id` | ✅ | **Submit value** — selected answer is `option.id` |
+| `isMultiSelect` | ⚠️ | SDK supports multi-select; implement checkbox cards when `true` |
 
-## Layout Anatomy
+## Multi-select note
 
-```
-┌─ label (full-width card) ─────────────────────────────────────┐
-│  (●)  Option label HTML                                      │  selected
-└───────────────────────────────────────────────────────────────┘
-┌─ label ───────────────────────────────────────────────────────┐
-│  (○)  Option label HTML                                      │  unselected
-└───────────────────────────────────────────────────────────────┘
-```
+When `question.isMultiSelect === true`:
 
-## Interactive States
+- Answer shape is `string[]` (or `number[]`) of selected `option.id` values
+- Toggle options on click; do not replace the entire array with a single id
+- onAction CHANGE: `{ questionId, answerValue: selectedIds[] }`
+- Still filter via `getVisibleMcqOptionsForAnswers` before render
 
-| State | Border | Background | Radio |
-|-------|--------|------------|-------|
-| Unselected | `#e5e5e5` | `white` | `border-gray-400`, empty |
-| Unselected hover | `#e5e5e5` | `hover:bg-gray-50/50` | — |
-| Selected | `#e20074` | `#fdf2f8` | `border-2 border-[#e20074]` + inner dot `h-2.5 w-2.5 bg-[#e20074]` |
-
-## Structure
-
-```tsx
-<label className="flex items-center gap-4 rounded-lg border py-4 px-5 cursor-pointer">
-  <input type="radio" name={question.id} className="sr-only" />
-  <div className="h-5 w-5 rounded-full border ..."> {/* custom radio */} </div>
-  <span dangerouslySetInnerHTML={{ __html: option.label }} />
-</label>
-```
+When `false` (default), single-select radio behavior applies.
 
 ## Answer Mutation
 
 ```typescript
-onSelect(option.value) // string | number
+onSelect(option.id) // string
+// → onAction CHANGE { questionId, answerValue: string }
 ```
 
 ## Agent Checklist
@@ -54,4 +36,10 @@ onSelect(option.value) // string | number
 - [ ] Custom circular radio indicator (not browser default)
 - [ ] Selected: magenta border + pink background
 - [ ] HTML labels
-- [ ] If `isMultiSelect`: implement checkbox cards (SDK gap in reference)
+- [ ] If `isMultiSelect`: implement checkbox cards with array answer shape
+
+## SDK Integration Checklist (agent)
+
+- [ ] Visibility helper: `getVisibleMcqOptionsForAnswers`
+- [ ] Store `option.id` — never option label text
+- [ ] Matrix row: [`question-type-sdk-matrix.md#mcq`](../00-integration/question-type-sdk-matrix.md#mcq)

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

@@ -1,7 +1,7 @@
-# UI Spec: Text Field (`type: 'text'`)
+# UI Spec: Text Field (`type: 'TEXTFIELD'`)
 
 > **Reference:** `apps/client/src/components/Question.tsx` (inline)
-> **SDK type:** `TextQuestion` — `fetchSurvey/types/text.ts`
+> **SDK type:** `TextInputQuestion` — `fetchSurvey/types/text.ts`
 
 ## Config Inventory
 

package/templates/docs/03-ui-specs/04-csat.md

@@ -1,57 +1,62 @@
-# UI Spec: CSAT (`type: 'csat'`)
+# UI Spec: CSAT Matrix Grid (`type: 'CSAT_MATRIX'`)
 
-> **Reference:** `apps/client/src/components/CsatScale.tsx`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CsatMatrixScale.tsx`
 > **SDK type:** `CsatQuestion` — `fetchSurvey/types/csat.ts`
-> **Component blueprint:** `01-components/04-csat-scale.md`
+> **Component blueprint:** `01-components/05-csat-matrix-scale.md`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `options[]` | ✅ | Scale buttons or dropdown options |
-| `buttonType` | ✅ partial | Branches below |
-| `labelPosition` | ✅ | `'top'` → flex-col-reverse; `'hidden'` → no label |
-| `minLabel` / `maxLabel` | ✅ | Rendered in Question.tsx above scale |
-| `hasNotApplicable` | ❌ | N/A option in options array still renders |
-| `reverseScaleOrder` | ❌ | Document: reverse options before map |
+| `statementRows[]`, `scaleColumns[]` | ✅ | Grid / carousel / dropdown data |
+| `displayStyle` | ✅ | Grid vs vertical list routing |
+| `gridLayout` | ✅ | carousel vs standard vs dropdown |
+| `hasNotApplicableOption` | ✅ | Checkbox below row (vertical) or N/A column (grid) |
+| `reverseScaleOrder` | ✅ | Flip emoji/star/number index |
+| `scaleAnchorLabels[]` | ✅ | Anchor row above columns |
 
 ## Config Decision Tree
 
 ```
-csat
-├── buttonType === 'dropdown'
-│   └── Native <select>, placeholder "Select an option"
-│       └── Parse value 'null' → null
-└── else (emoji | star | numbered | number | default)
-    └── flex flex-wrap gap-3 buttons
-        ├── emoji → getEmojiForIndex(index, scaleLength)
-        ├── star → CsatStarIcons filled/empty; labels hidden
-        ├── numbered/number → mono font value
-        └── default → bold value or 'N/A' if null
+CSAT_MATRIX
+├── gridLayout === 'carousel' → CsatMatrixCarousel
+├── displayStyle in (dropdown, selectbox) → CsatMatrixVerticalList
+│   ├── dropdown → MatrixDropdown placeholder "Select..."
+│   ├── selectbox → full-width cards #fdf2f8 selected
+│   └── else → card radio list
+└── else → CsatMatrixGrid
+    ├── displayStyle === 'emoji' → client-side emoji icons (react-icons) + hover scale + ring when selected
+    ├── displayStyle === 'star' → opacity 0.5 unselected; filled/empty icons
+    ├── displayStyle === 'numbered' → 40×40 badge; selected magenta fill
+    └── displayStyle === 'graphics' → CustomSliderTrack per row (carousel)
 ```
 
-## Interactive States
+## Grid Structure
 
-| State | Border | Background | Transform |
-|-------|--------|------------|-----------|
-| Default | `border-gray-200` | `white` | scale-100 |
-| Hover | `border-gray-300` | `hover:bg-gray-50` | — |
-| Selected | `border-[#e20074]` | `#fdf2f8` | `scale-110` |
-| Star mode | transparent | transparent | no border/bg on button |
+- Row label: `180px` fixed column
+- N/A column: `56px` when `hasNotApplicableOption`
+- Alternating row backgrounds
+- Column headers OR `scaleAnchorLabels[]` anchor row with percentage positioning
 
-## Tooltips
+## Carousel
 
-Recommended: `title={option.label}` on each button. Not in reference client.
+- Pink active dot expands: `20px × 8px` vs `8px` inactive
+- Column labels below cells
+- Emoji tooltip via hover state
+- Graphics mode: slider maps column index
 
 ## Answer Mutation
 
+Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+
 ```typescript
-onSelect(string | number | null)
+onSelect(MatrixRowAnswers)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } })
 ```
 
 ## Agent Checklist
 
-- [ ] Dropdown branch with magenta focus ring
-- [ ] Emoji/star/numbered branches per decision tree
-- [ ] `labelPosition` controls label above/below/hidden
-- [ ] Implement `reverseScaleOrder` and standalone `hasNotApplicable` (SDK gaps)
+- [ ] All displayStyle × gridLayout branches
+- [ ] reverseScaleOrder on emoji/star/numbered
+- [ ] Carousel pink dot indicators
+- [ ] Vertical selectbox cards match MCQ card styling

package/templates/docs/03-ui-specs/05-rating-scale.md

@@ -1,49 +1,52 @@
-# UI Spec: Rating Scale (`type: 'rating_scale'`)
+# UI Spec: Star Rating (`type: 'star_rating'`)
 
-> **Reference:** ❌ Not routed in `Question.tsx` — reuse `CsatScale.tsx` patterns
-> **SDK type:** `RatingScaleQuestion` — `fetchSurvey/types/ratingScale.ts`
-> **Component blueprint:** `01-components/03-rating-scale.md`
+> **DEPRECATED:** Not in the current `SurveyQuestion` union. API RATING pages map to `NPS_SCALE` or CSAT/RATING matrix display styles. See `01-rating.md` and matrix specs instead.
+>
+> **SDK type:** `StarRatingQuestion` — `fetchSurvey/types/starRating.ts`
+> **Component blueprint:** `01-components/04-star-rating-scale.md`
+> **Routed in template:** `Question.tsx` → `RatingScale` for `star_rating`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `options[]` | ❌ gap | Star/emoji buttons (no NPS colors) |
-| `scaleStyle` | ❌ gap | `'star'` or `'emoji'` |
-| `minLabel` / `midLabel` / `maxLabel` | ❌ gap | Same formulas as NPS in Question shell |
-| `midLabelIndex` | ❌ gap | `(midLabelIndex / (options.length - 1)) * 100`% |
-| `reverseScaleOrder` | ❌ gap | Reverse options before render |
+| `options[]` | ✅ | Star/emoji buttons (no NPS traffic-light colors) |
+| `scaleStyle` | ✅ | `'star'` or `'emoji'` |
+| `minLabel` / `midLabel` / `maxLabel` | ✅ | Same formulas as NPS in Question shell |
+| `midLabelIndex` | ✅ | `(midLabelIndex / (options.length - 1)) * 100`% |
+| `reverseScaleOrder` | partial | Reverse options before render |
 
-## Expected UI (from CsatScale + rating labels)
+## Expected UI
 
 ```
 [minLabel]     [midLabel @ %]     [maxLabel]
 ┌────┬────┬────┬────┬────┐
 │ ★  │ ★  │ ★  │ ★  │ ★  │  scaleStyle: 'star'
 └────┴────┴────┴────┴────┘
-  OR emoji row from getEmojiForIndex when scaleStyle: 'emoji'
+  OR emoji row from client-side react-icons when scaleStyle: 'emoji'
 ```
 
-Reuse CsatScale selected styling: `border-[#e20074] bg-[#fdf2f8] scale-110`.
+Selected styling: `border-[#e20074] bg-[#fdf2f8] scale-110`.
 
 ## Config Decision Tree
 
 ```
-rating_scale
-├── scaleStyle === 'star' → CsatStarIcons per option
-├── scaleStyle === 'emoji' → getEmojiForIndex
-└── else → numbered badges (no option.color)
+star_rating
+├── scaleStyle === 'star' → client-side star icons (react-icons) per option
+├── scaleStyle === 'emoji' → client-side emoji icons (react-icons)
+└── else → numbered badges (no accentColor)
 ```
 
 ## Answer Mutation
 
 ```typescript
 onSelect(number)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: number } })
 ```
 
 ## Agent Checklist
 
-- [ ] Add dispatcher branch in Question for `rating_scale`
+- [ ] Dispatcher branch for `star_rating` in Question.tsx
 - [ ] No traffic-light NPS colors on options
 - [ ] min/mid/max labels with midLabelIndex formula
-- [ ] Match CsatScale interactive states
+- [ ] Match star/emoji bounding box rules from `04-star-rating-scale.md`

package/templates/docs/03-ui-specs/06-slider.md

@@ -1,6 +1,8 @@
 # UI Spec: Standalone Slider (`type: 'slider'`)
 
-> **Reference:** ❌ Not routed in `Question.tsx` — reuse `CustomSliderTrack.tsx`
+> **DEPRECATED:** Not in the current `SurveyQuestion` union. API SLIDER pages map to `SLIDER_MATRIX` or matrix `displayStyle: 'graphics'`. See `10-slider-matrix.md` and `CustomSliderTrack` specs.
+>
+> **Reference:** Standalone slider is not routed in current `Question.tsx`
 > **SDK type:** `SliderQuestion` — `fetchSurvey/types/slider.ts`
 > **Component blueprint:** `01-components/09-custom-slider-track.md`
 

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'`)
 
-> **Reference:** `apps/client/src/components/LikertMatrixScale.tsx`
-> **SDK type:** `MatrixQuestion` — `fetchSurvey/types/matrix.ts`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/LikertMatrixScale.tsx`
+> **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
 
@@ -53,14 +53,17 @@ CFM_MATRIX
 
 ## Answer Mutation
 
+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,37 @@
-# UI Spec: CSAT / Rating Matrix (`subType: 'CSAT_MATRIX' | 'RATING_MATRIX'`)
+# UI Spec: Rating Matrix Grid (`type: 'RATING_MATRIX'`)
 
-> **Reference:** `apps/client/src/components/CsatMatrixScale.tsx`
-> **SDK type:** `MatrixQuestion` — `fetchSurvey/types/matrix.ts`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CsatMatrixScale.tsx`
+> **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
-
-## Carousel
-
-- 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).
+Same as `CSAT_MATRIX` grid — reuse `CsatMatrixScale` component. See [04-csat.md](04-csat.md) decision tree with `type: 'RATING_MATRIX'`.
 
 ## 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,6 +1,6 @@
-# UI Spec: Slider Matrix (`type: 'slider_matrix'`)
+# 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'`)
+# 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/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,7 +49,7 @@ 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
 
@@ -53,8 +58,9 @@ Pink fill bar, `300ms` width transition on `progressPercentage`.
 
 ## 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