@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

package/templates/docs/00-integration/skip-logic-and-navigation.md

@@ -0,0 +1,80 @@
+# Skip Logic and Navigation
+
+> Integrator-facing behavior contract. Skip evaluation is handled inside the SDK — do not import internal `surveyLogic` paths.
+
+## When skip rules run
+
+- Skip rules live on individual questions (`question.skipLogics`).
+- When a question has **multiple skip logic blocks**, the SDK evaluates them **top-to-bottom (API order)** and applies the **first** whose condition is true.
+- On **Next**, the SDK evaluates skip logic on the **last question of the current page** only.
+- Skip targets:
+  - `QUESTION` — jump forward to another question's page
+  - `END_OF_SURVEY` — trigger submit flow (validation bypass for skipped pages)
+
+**Forward-only:** backward skip targets are rejected. The respondent cannot skip to an earlier page via skip logic.
+
+## Multiselect MCQ — count of choice
+
+Multiselect MCQ skip rules may use `field: 'NUM_OF_SELECTED_OPTIONS'` (**Count of Choice** in the builder). The SDK compares the number of selected option ids with numeric operators (`EQUALS`, `NOT_EQUALS`, `GT`, `GTE`, `LT`, `LTE`). Zero selections is treated as missing for `MISSING` / `EXISTS`.
+
+## Custom field conditions
+
+Skip rules may reference **custom fields** (`conditionEntity.entityType: 'CUSTOM_FIELD'`). See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) for value shapes, operator contract, and the two wiring points (hook options + visibility helpers).
+
+## Simple example
+
+| Page | Question | Rule |
+|------|----------|------|
+| 1 | Q1 (NPS) | If score > 7 → skip to Q4 |
+| 2 | Q2 | (middle) |
+| 3 | Q3 | (middle) |
+| 4 | Q4 | destination |
+
+1. User sets Q1 = **5** → path is pages 1 → 2 → 3 → 4 (sequential).
+2. User sets Q1 = **9** → simulated path becomes pages **1 → 4** (pages 2–3 skipped).
+3. User clicks **Next** from page 1 → lands on page 4.
+
+## Answer changes (`onChange`)
+
+When the edited question has skip logic, the SDK compares the route **before** and **after** the edit.
+
+| Check | Meaning | SDK action |
+|-------|---------|------------|
+| **Path changed** | Page route reshaped (e.g. sequential → skip) | Clear answers on all pages after current page; reset skip/visit tracking ahead; refresh progress |
+| **Pruned only** | Route unchanged but progress credits were stale | Remove off-path earned credits; refresh progress; **keep answers** |
+
+**Example — path changed:** User walked page 2, answered Q2, then on page 1 changes Q1 from 5 → 9. Q2 answer is cleared because page 2 is no longer on the active path.
+
+**Example — pruned only:** User already on skip path; edits Q1 from 8 → 9 (still skips). Route unchanged; stale progress credits for pages visited earlier may be removed without clearing answers.
+
+## Back navigation
+
+- Back uses **`pageHistory`**, not `currentPageIndex - 1`.
+- After a skip jump (e.g. page 1 → page 4), Back returns to the **skip origin** (page 1), not the sequential previous page.
+- **Answers are preserved on Back** — the SDK does not sanitize answers when going back.
+- Skip/visit tracking for pages ahead of the back target is reset.
+
+## Forward navigation (`onNext`)
+
+- Validates **current page only** before moving.
+- On skip: marks intermediate pages in `skippedPageIndices`; may sanitize answers on skipped pages.
+- Sequential Next skips empty pages automatically.
+
+## Submit validation
+
+- Submit validates **non-skipped pages** only (pages marked skipped via skip logic are excluded).
+- End-of-survey skip triggers submit with `skipValidation: true` for remaining pages.
+
+## Optional question telemetry
+
+When the user leaves a page (Next or Submit), the SDK logs analytics for **optional questions left blank** on that page. This does not block navigation or affect answers.
+
+Event: `optional_question_skipped` with `questionId` and `pageIndex`.
+
+## Client responsibilities
+
+- Wire `onAction({ type: 'NEXT' })`, `onAction({ type: 'PREVIOUS' })`, and `onAction({ type: 'CHANGE', payload: { questionId, answerValue } })`.
+- Use `state.canGoBack` for the Back button (not `currentPageIndex === 0`).
+- Use `state.primaryButtonType` for Next vs Submit label; SDK maps `NEXT` → `SUBMIT` on the last page when appropriate.
+
+See also: [`progress.md`](progress.md), [`useSurveySDK.md`](useSurveySDK.md), [`display-logic-and-navigation.md`](display-logic-and-navigation.md), [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md), [`logic-fields-catalog.md`](logic-fields-catalog.md).

package/templates/docs/00-integration/survey-lifecycle-analytics.md

@@ -0,0 +1,94 @@
+# Survey Lifecycle and Analytics
+
+> Covers `sdkFeatures.markAsStarted` and `sdkFeatures.questionActivity` — first-interaction tracking and per-question view telemetry.
+
+---
+
+## Mark as started
+
+The SDK automatically marks the survey as started on the **first `CHANGE` action** (any answer update). No separate client call is required when using `useSurveySDK`.
+
+Additionally, fire **`SCROLL`** once on the user's first scroll to capture engagement before first answer:
+
+```typescript
+useEffect(() => {
+  let scrolled = false;
+  const onScroll = () => {
+    if (!scrolled) {
+      scrolled = true;
+      onAction({ type: 'SCROLL' });
+    }
+  };
+  window.addEventListener('scroll', onScroll, { passive: true });
+  return () => window.removeEventListener('scroll', onScroll);
+}, [onAction]);
+```
+
+Attach to the survey container scroll root if the page uses an inner scroll area instead of `window`.
+
+---
+
+## Question activity (`RECORD_QUESTION_VIEW`)
+
+Fire when a question enters the viewport so the backend records view events. Use `IntersectionObserver`:
+
+```typescript
+useEffect(() => {
+  const seen = new Set<string>();
+  const observer = new IntersectionObserver(
+    (entries) => {
+      const ids: string[] = [];
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          const id = entry.target.id.replace(/^question-/, '');
+          if (!seen.has(id)) {
+            seen.add(id);
+            ids.push(id);
+          }
+        }
+      }
+      if (ids.length > 0) {
+        onAction({ type: 'RECORD_QUESTION_VIEW', payload: { questionIds: ids } });
+      }
+    },
+    { threshold: 0.5 }
+  );
+
+  for (const q of currentQuestions) {
+    const el = document.getElementById(`question-${q.id}`);
+    if (el) observer.observe(el);
+  }
+
+  return () => observer.disconnect();
+}, [currentQuestions, onAction]);
+```
+
+### Requirements
+
+- Every question wrapper must have `id={`question-${question.id}`}` (Phase 6 verify).
+- Re-run the effect when `currentQuestions` changes (multi-page surveys, display logic).
+- SDK **deduplicates** question IDs server-side per session — client `seen` set avoids duplicate actions in one mount.
+
+---
+
+## Batching
+
+`RECORD_QUESTION_VIEW` accepts `{ questionIds: string[] }`. Batch all newly visible IDs from one observer callback tick rather than one action per question when multiple enter view together.
+
+---
+
+## Debug: `logic_session_summary`
+
+When `debug: true` is set in hook options, the SDK emits structured console events including lifecycle transitions. Full event catalog: [`analytics-events-catalog.md`](analytics-events-catalog.md).
+
+---
+
+## Wiring checklist
+
+- [ ] `SCROLL` fired once on first scroll
+- [ ] First `CHANGE` left to SDK (auto mark-as-started)
+- [ ] `IntersectionObserver` on `#question-{id}` wrappers
+- [ ] Effect depends on `currentQuestions` — re-observe on page change
+- [ ] No duplicate `RECORD_QUESTION_VIEW` spam (client dedup + SDK dedup)
+
+See [`client-integration-guide.md`](client-integration-guide.md) and [`implementation_plan.md`](../templates/implementation_plan.md) §1b.

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

@@ -13,9 +13,7 @@ import {
   type UseSurveySDKReturn,
   type SurveyQuestion,
   type AnswerValue,
-  type MatrixAnswerMap,
-  CsatEmojiSet,
-  getEmojiForIndex,
+  type MatrixRowAnswers,
 } from '@explorer02/cfm-survey-sdk'; // or @repo/sdk in monorepo
 ```
 
@@ -28,12 +26,14 @@ Ask the client: *"Please provide your survey instance ID (JWT token)."*
 ## Hook Signature
 
 ```typescript
-const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
+const { surveyQueryResults, submitSurveyResults, partialSaveResults, state, onAction } = useSurveySDK({
   options: {
     instanceId: string,                    // JWT from client
     language: string | undefined,          // Active language code
     placeholders: Record<string, string>,  // Token replacements — MUST be stable ref
+    customFieldValues?: CustomFieldValueMap, // CRM/transaction custom field values — MUST be stable ref
     debug: boolean,                        // Console logging
+    savePartialResponse: boolean | { debounceMs?: number }, // Optional partial save (default 1500ms)
   },
 });
 ```
@@ -42,9 +42,52 @@ Define `placeholders` **outside** the component to avoid infinite re-fetch loops
 
 ```typescript
 const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'John' };
-// inside component: options: { placeholders: SURVEY_PLACEHOLDERS }
 ```
 
+Define `customFieldValues` **outside** the component (same stable-ref rule as `placeholders`):
+
+```typescript
+import type { CustomFieldValueMap } from '@explorer02/cfm-survey-sdk';
+
+const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {
+  '_c_6a436c1244764c9d4a6ce2fc': 'q5',           // TEXT — string
+  '_c_6a436c3644764c9d4a6ce3f5': 2,               // NUMBER — number or numeric string
+  '_c_6a436c9e44764c9d4a6ce717': 'option-id',   // PICKLIST — option id string
+  '_c_6a436cbb44764c9d4a6ce7e5': ['opt-a'],       // PICKLIST_MULTISELECT — option id array
+  '_c_6a4386dc44208eb8b08a9056': 1781029800000,  // DATETIME — epoch ms (recommended)
+};
+```
+
+Wrap hook options in `useMemo` inside the component:
+
+```typescript
+const surveyOptions = useMemo(
+  () => ({
+    instanceId,
+    language: selectedLanguage,
+    placeholders: SURVEY_PLACEHOLDERS,
+    customFieldValues: CUSTOM_FIELD_VALUES,
+  }),
+  [selectedLanguage]
+);
+
+useSurveySDK({ options: surveyOptions });
+```
+
+Keys are the `_c_…` custom field ids from survey logic rules (`conditionEntity.id` in skip/display/answer logic). The SDK evaluates skip, display, and answer logic against these values when passed via hook options.
+
+| Custom field type | Client value shape |
+|---|---|
+| TEXT / TEXT_MULTI / TEXTAREA | `string` |
+| NUMBER | `number` or numeric string (`0` is a valid value) |
+| PICKLIST | `string` (option id) |
+| PICKLIST_MULTISELECT | `string[]` (option ids) |
+| DATETIME | epoch ms (`number` or numeric string); ISO date strings also accepted |
+
+Missing ids in the map are treated as empty for logic evaluation.
+
+When the survey uses custom-field logic, also pass the same map into `Question.tsx` visibility helpers — see [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
+
 ## Return Shape
 
 | Namespace | Field | Type | Purpose |
@@ -55,42 +98,129 @@ const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'John' };
 | `submitSurveyResults` | `data` | `SubmitResult \| null` | Success payload |
 | | `error` | `Error \| null` | Submit failure |
 | | `isLoading` | `boolean` | Submit in progress |
-| `state` | `currentPageIndex` | `number` | 0-based page index |
-| | `currentQuestions` | `SurveyQuestion[]` | Questions on current page |
-| | `values` | `Record<string, AnswerValue>` | All answers so far |
+| `partialSaveResults` | `data` | `SubmitResult \| null` | Last partial save success payload (when enabled) |
+| | `error` | `Error \| null` | Partial save failure |
+| | `isLoading` | `boolean` | Partial save in progress |
+| `state` | `phase` | `SurveyPhase` | Survey flow phase (see below) |
+| | `currentPageIndex` | `number` | 0-based page index (when `phase.kind === 'content'`) |
+| | `currentQuestions` | `SurveyQuestion[]` | Questions on current page; `questionText` and `questionNumber` resolved by SDK |
+| | `answers` | `SurveyAnswers` | All answers so far |
 | | `validationErrors` | `Record<string, string>` | Per-question error messages |
-| | `progressPercentage` | `number` | 0–100 completion |
+| | `progressPercentage` | `number` | 0–100 path-scoped completion (see `progress.md`) |
+| | `totalQuestionsCount` | `number` | Answerable questions on active path (progress denominator) |
+| | `answeredQuestionsCount` | `number` | Earned credits on active path (progress numerator) |
+| | `canGoBack` | `boolean` | Show Back button |
+| | `primaryButtonType` | `'next' \| 'submit'` | Primary nav label; SDK maps `NEXT` → `SUBMIT` when `'submit'` |
+| | `specialPage` | `SpecialPage \| undefined` | Intro / end / paused page content when applicable |
 | `onAction` | — | `(action: SurveyAction) => void` | **Only** way to mutate state |
 
+### Survey phases (`state.phase.kind`)
+
+| Phase | When | UI |
+|-------|------|-----|
+| `intro` | Survey has intro page | Render intro; dispatch `START` |
+| `content` | Active questions | Question map + nav |
+| `end` | Successful submit | End/thank-you page from `specialPage` |
+| `paused` | Survey paused flag | Paused message (read-only) |
+| `submitted` | Already filled | Terminal message |
+| `expired` | Survey expired | Terminal message |
+| `quota_fulfilled` | Quota reached | Terminal message |
+
 ## Action Dispatching
 
 Never mutate `state` directly. Use `onAction`:
 
 ```typescript
 // Answer a question
-onAction({ type: ACTIONS.CHANGE, payload: { questionId: 'q1', value: 4 } });
+onAction({ type: ACTIONS.CHANGE, payload: { questionId: 'q1', answerValue: 4 } });
 
 // Matrix answer
-onAction({ type: ACTIONS.CHANGE, payload: { questionId: 'q2', value: { row1: 5, row2: 2 } } });
+onAction({ type: ACTIONS.CHANGE, payload: { questionId: 'q2', answerValue: { row1: 5, row2: 2 } } });
+
+// Intro → content
+onAction({ type: ACTIONS.START });
 
 // Navigate
-onAction({ type: ACTIONS.NEXT });      // Validates current page; auto-SUBMIT on last page
-onAction({ type: ACTIONS.PREVIOUS });
-onAction({ type: ACTIONS.SUBMIT });    // Validates ALL pages, then submits
+onAction({ type: ACTIONS.NEXT });      // Validates current page; maps to SUBMIT when primaryButtonType is 'submit'
+onAction({ type: ACTIONS.PREVIOUS });    // Uses pageHistory (skip-aware Back)
+onAction({ type: ACTIONS.SUBMIT });    // Validates non-skipped pages, then submits
+
+// Lifecycle (client detects scroll / visibility, SDK handles API calls)
+onAction({ type: ACTIONS.SCROLL });    // First scroll — marks instance as started (once)
+onAction({
+  type: ACTIONS.RECORD_QUESTION_VIEW,
+  payload: { questionIds: ['q1'] },     // Question entered viewport
+});
 ```
 
-String literals also work: `'NEXT'`, `'PREVIOUS'`, `'SUBMIT'`, `'CHANGE'`.
+String literals also work: `'START'`, `'NEXT'`, `'PREVIOUS'`, `'SUBMIT'`, `'CHANGE'`, `'SCROLL'`, `'RECORD_QUESTION_VIEW'`.
 
 ## Validation
 
-- Required questions must be answered before `NEXT` or `SUBMIT`
+- Required questions must be answered before `NEXT` or `SUBMIT` on the **current page**
+- `NEXT` validates current page only; skip logic may bypass intermediate pages
+- `SUBMIT` validates **non-skipped pages** only (pages bypassed by skip logic are excluded)
 - `null` is a valid answer (N/A option)
-- `text_and_media` is display-only — always skipped
+- `TEXT_AND_MEDIA` is display-only — always skipped for validation
 - On failure, SDK scrolls to first error via `document.getElementById(questionId)` — **requires `id={question.id}` on question wrappers**
 
+See [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md) for skip, Back, and answer-sanitize behavior.
+
 ## Submission
 
-Triggered by `onAction({ type: ACTIONS.SUBMIT })` or `NEXT` on the last page. While submitting, `submitSurveyResults.isLoading` is `true`. On success, show thank-you UI when `submitSurveyResults.data` is set.
+Triggered by `onAction({ type: ACTIONS.SUBMIT })` or `NEXT` when `primaryButtonType === 'submit'`. While submitting, `submitSurveyResults.isLoading` is `true`. On success, render end UI when `state.phase.kind === 'end'` (and `state.specialPage` for content). `submitSurveyResults.data` confirms API success.
+
+## Mark as Started
+
+On the **first scroll or answer change**, the client should dispatch `onAction({ type: ACTIONS.SCROLL })` (once, on first scroll) and/or the SDK fires automatically on `CHANGE`. Both call a one-time GET to `markResponseInstanceAsStarted`. Fire-and-forget — errors do not block the UI.
+
+```typescript
+useEffect(() => {
+  const onScroll = () => onAction({ type: ACTIONS.SCROLL });
+  window.addEventListener('scroll', onScroll, { passive: true, once: true });
+  return () => window.removeEventListener('scroll', onScroll);
+}, [onAction]);
+```
+
+## Question Activity (VIEWED)
+
+When a question enters the viewport, dispatch `RECORD_QUESTION_VIEW` with its id(s). The SDK POSTs to `recordQuestionActivityV2` with deduplication (each question recorded once). Requires `id={question.id}` on question wrappers.
+
+```typescript
+useEffect(() => {
+  const observer = new IntersectionObserver(entries => {
+    for (const entry of entries) {
+      if (entry.isIntersecting && entry.target.id) {
+        onAction({
+          type: ACTIONS.RECORD_QUESTION_VIEW,
+          payload: { questionIds: [entry.target.id] },
+        });
+      }
+    }
+  }, { threshold: 0.5 });
+
+  state.currentQuestions.forEach(q => {
+    const el = document.getElementById(q.id);
+    if (el) observer.observe(el);
+  });
+
+  return () => observer.disconnect();
+}, [state.currentQuestions, onAction]);
+```
+
+## Partial Save
+
+When `savePartialResponse: true` (or `{ debounceMs: 1500 }`) is passed in options, the SDK debounces answer changes and POSTs partial responses with `surveySubmitted=false`. Partial saves begin only after the first user interaction (not MCQ default seeding). Monitor `partialSaveResults.isLoading` / `partialSaveResults.error` if you need UI feedback.
+
+```typescript
+useSurveySDK({
+  options: {
+    instanceId,
+    savePartialResponse: true,
+    // or: savePartialResponse: { debounceMs: 2000 },
+  },
+});
+```
 
 ## Language & Placeholders
 
@@ -98,10 +228,8 @@ Triggered by `onAction({ type: ACTIONS.SUBMIT })` or `NEXT` on the last page. Wh
 - `survey.languages` lists available languages for `LanguageSelector`
 - Placeholders replace `{{FIRST_NAME}}` tokens in question text at map time
 
-## CSAT Icons (from package)
+## CSAT / rating emoji UI (client-implemented)
 
-```typescript
-import { CsatEmojiSet, getEmojiForIndex, CsatStarIcons } from '@explorer02/cfm-survey-sdk';
-```
+CSAT emoji and star icons are **not** exported from the SDK. Implement client-side with `react-icons` (or your icon library). Map column index to sentiment icons proportionally for non-5-point scales.
 
-Use `getEmojiForIndex(index, totalOptions)` for proportional emoji mapping on non-5-point scales. Install `react-icons` in the client project.
+See `03-ui-specs/04-csat.md` and [`question-type-sdk-matrix.md#csat_matrix`](question-type-sdk-matrix.md#csat_matrix).

package/templates/docs/01-components/01-survey-page.md

@@ -3,91 +3,113 @@
 > **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
 > **Reference implementation:** `apps/client/src/components/SurveyPage.tsx`
 > **Target Component**: `SurveyPage`
-> **Role**: The main entry point that wires the UI to the `useSurveySDK` hook, manages loading/error states, orchestrates pagination, and controls submission.
+> **Role**: Wires `useSurveySDK` to the UI — loading/error states, phase routing, pagination, submission.
 
 ## Core Responsibility
-This component MUST act as the state machine for the entire survey flow. It should never render questions directly—it delegates that to `Question.tsx`.
 
-## Setup & Wiring (CRITICAL)
+Act as the **phase state machine** for the survey. Never render questions directly — delegate to `Question.tsx`.
 
-The component MUST invoke `useSurveySDK`, passing the **instanceId** from the client prompt.
+## Setup & Wiring (CRITICAL)
 
 ```tsx
+import type { CustomFieldValueMap } from '@explorer02/cfm-survey-sdk';
+
 const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'Customer' }; // Must be outside component!
+const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {}; // Populate when survey uses custom-field logic
 
 export default function SurveyPage() {
-  const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>("");
+  const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>();
 
-  const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
-    options: {
-      instanceId: 'YOUR_INSTANCE_ID_HERE', // From client prompt
+  const surveyOptions = useMemo(
+    () => ({
+      instanceId: 'YOUR_INSTANCE_ID_HERE',
       language: selectedLanguage,
       placeholders: SURVEY_PLACEHOLDERS,
+      customFieldValues: CUSTOM_FIELD_VALUES,
       debug: true,
-    }
+    }),
+    [selectedLanguage]
+  );
+
+  const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
+    options: surveyOptions,
   });
-  
+
   const survey = surveyQueryResults.data;
-  
-  // ... state machine rendering
+  const allQuestions = useMemo(
+    () => survey?.pages.flatMap(page => page.questions) ?? [],
+    [survey]
+  );
+  // ... phase routing below
 }
 ```
 
-## The 5 State Machine Renders (MANDATORY)
+See [`client-integration-guide.md`](../00-integration/client-integration-guide.md) for lifecycle effects (`SCROLL`, `RECORD_QUESTION_VIEW`).
 
-You MUST structure your render logic to strictly handle these 5 states in order to avoid UI crashes when data is not yet available.
+## Render Order (MANDATORY)
 
-### 1. Loading State
-If `surveyQueryResults.isLoading` is true, render a Skeleton or Spinner.
-*Include your CSS-only Header and Footer around the spinner.*
+Handle in this order:
 
-### 2. Error State
-If `surveyQueryResults.error` is true, render a red Error banner containing `surveyQueryResults.error.message`.
+### 1. Loading / Error / Empty
 
-### 3. Empty State
-If `!survey`, render a generic "Survey not found" message.
+| Condition | UI |
+|-----------|-----|
+| `surveyQueryResults.isLoading` | Spinner + Header/Footer |
+| `surveyQueryResults.error` | Error message |
+| `!survey` | "No survey data" |
 
-### 4. Submitted State
-If `submitSurveyResults.data` exists, the survey is complete.
-*Render the Thank You Screen (e.g., "Thank you for your feedback!"). Do not render the question list.*
+### 2. Special phases (`state.phase`)
 
-### 5. Active Survey State
-If the above 4 conditions are met, render the active survey page:
-1. `Header` (Logo)
-2. `ProgressBar` (Pass `state.progressPercentage`)
-3. `LanguageSelector` (Pass `survey.languages`, `survey.language`, `setSelectedLanguage`)
-4. **The Question Map** (See below)
-5. **Navigation Buttons** (See below)
+| `phase.kind` | Component | Action |
+|--------------|-----------|--------|
+| `intro` | `IntroPage` | `onAction({ type: 'START' })` |
+| `paused` | `PausedPage` | Read-only |
+| `end` | `EndPage` | Thank-you from `state.specialPage` |
+| `submitted` | Terminal message | Already filled |
+| `expired` | Terminal message | Survey expired |
+| `quota_fulfilled` | Terminal message | Quota reached |
+
+See `14-intro-page.md`, `15-end-page.md`, `16-paused-page.md`.
+
+### 3. Active content (`phase.kind === 'content'`)
+
+1. `Header`
+2. `ProgressBar` (`state.progressPercentage`) — see `00-integration/progress.md`
+3. `LanguageSelector`
+4. Question map (below)
+5. Navigation buttons (below)
 6. `Footer`
 
 ## The Question Map
 
-You MUST iterate over `state.currentQuestions` and dispatch to `Question.tsx`.
+Pass **all answers and questions** for placeholder resolution (`{{SURVEY_QUESTION-:-qId}}`):
 
 ```tsx
-<div className="space-y-12">
-  {state.currentQuestions.map(question => (
-    <Question
-      key={question.id}
-      question={question}
-      selectedValue={state.values[question.id]}
-      validationError={state.validationErrors[question.id]}
-      onSelect={value => onAction({ 
-        type: 'CHANGE', 
-        payload: { questionId: question.id, value } 
-      })}
-    />
-  ))}
-</div>
+{state.currentQuestions.map(question => (
+  <Question
+    key={question.id}
+    question={question}
+    selectedValue={state.answers[question.id]}
+    validationError={state.validationErrors[question.id]}
+    allAnswers={state.answers}
+    allQuestions={allQuestions}
+    customFieldValues={CUSTOM_FIELD_VALUES}
+    onSelect={answerValue =>
+      onAction({ type: 'CHANGE', payload: { questionId: question.id, answerValue } })
+    }
+  />
+))}
 ```
 
-## Navigation Buttons Logic
+## Navigation Buttons
 
-You MUST conditionally render "Back" and "Next/Submit" buttons. 
-
-- **Back Button**: Hide if `state.currentPageIndex === 0`.
-  - `onClick={() => onAction({ type: 'PREVIOUS' })}`
-- **Next/Submit Button**:
+- **Back:** Render when `state.canGoBack` — `onAction({ type: 'PREVIOUS' })`
+- **Primary:** Label from `state.primaryButtonType` (`'next'` | `'submit'`)
+  - Always dispatch `onAction({ type: 'NEXT' })` — SDK maps to submit when `primaryButtonType === 'submit'`
   - `disabled={submitSurveyResults.isLoading}`
-  - If `state.currentPageIndex < survey.pages.length - 1`, label is "Next", action is `type: 'NEXT'`.
-  - If on the last page, label is "Submit", action is `type: 'NEXT'` (the SDK intercepts NEXT on the last page to trigger submission automatically!).
+
+Do **not** use `currentPageIndex === 0` alone to hide Back — intro page and skip-aware history use `canGoBack`.
+
+## Scroll & question activity
+
+Wire `SCROLL` (once) and `RECORD_QUESTION_VIEW` as documented in `useSurveySDK.md`.