@explorer02/cfm-survey-sdk 0.2.0 → 0.2.2

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

@@ -0,0 +1,50 @@
+# Answer Logic and Navigation
+
+> Integrator-facing behavior contract. Answer logic evaluation is handled inside the SDK — use exported visibility helpers; do not import internal `surveyLogic` paths directly.
+
+## Distinction from display logic
+
+Skip logic, display logic, and answer logic share the **same condition tree** and **same evaluator** (`evaluateCondition`). They differ by **what** the condition gates:
+
+| Kind | API attachment | SDK field | When true |
+|------|----------------|-----------|-----------|
+| `SKIP` | Question `controlConfig.skipLogics` | `question.skipLogics` | Navigate to skip target or end of survey |
+| `DISPLAY` | Question `controlConfig.displayLogic` | `question.displayLogic` | Show the whole question (dynamic or page-level) |
+| `ANSWER` | Sub-entity `controlConfig.displayLogic` | `answerLogic` on options / rows / columns | Show that option, statement row, or scale column |
+
+The API uses `displayLogic` on sub-entities (MCQ `answerDetails`, matrix `childSurveyQuestions`, scale `answerDetails` / `matrixColumnQuestions`). The SDK maps these to `answerLogic` to avoid confusion with question-level display logic.
+
+## Supported question types
+
+| Type | Answer logic on | Not supported |
+|------|-----------------|---------------|
+| MCQ | Each option | — |
+| SLIDER_MATRIX | Each statement row | Scale columns |
+| CSAT_MATRIX | Each statement row + each scale column | — |
+| RATING_MATRIX | Each statement row only | Scale columns |
+| CFM_MATRIX | Each statement row + each scale column | — |
+| RANK_ORDER | Each option | — |
+| NPS_SCALE, TEXTFIELD, FILE_UPLOAD, TEXT_AND_MEDIA | — | No answer logic |
+
+## Page breaks
+
+Adding answer logic in the survey builder creates a **page break before that question** (backend page structure). The SDK does not split pages at runtime; it filters visible items within the current page.
+
+If **every** answer item is hidden (all options, all rows, or all scale columns), the question is treated as not answerable and may disappear from `state.currentQuestions` (same pattern as display logic empty pages).
+
+## Client responsibilities
+
+1. Use `state.currentQuestions` from `useSurveySDK` — question-level display logic is already applied.
+2. **MCQ:** Filter options with `getVisibleMcqOptionsForAnswers(question, answers, allQuestions, customFieldValues?)`.
+3. **Rank order:** Filter options with `getVisibleRankOrderOptionsForAnswers(question, answers, allQuestions, customFieldValues?)`.
+4. **Matrix (CSAT, CFM, RATING, SLIDER):** Filter rows and (for CSAT/CFM) columns with `getVisibleMatrixItemsForAnswers(question, answers, allQuestions, customFieldValues?)`.
+5. Pass the same `customFieldValues` map used in `useSurveySDK` options when logic rules reference `CUSTOM_FIELD` entities — see [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
+6. Wire `onAction({ type: 'CHANGE' })` so answer logic re-evaluates when prior answers change.
+
+## Progress and validation
+
+- Progress and validation count only **visible** options, statement rows, and scale columns.
+- Hidden selections are stripped automatically on answer change via SDK sanitization.
+- Required questions with zero visible options are not blocked (treated as answered).
+
+See also: [`display-logic-and-navigation.md`](display-logic-and-navigation.md), [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md), [`progress.md`](progress.md).

package/templates/docs/00-integration/aws-deploy.md

@@ -0,0 +1,281 @@
+# AWS Deploy (EC2 Middle API → S3 → CloudFront)
+
+> Deploy a **static** survey UI to Sprinklr AWS using the hosted EC2 deploy API.
+> **Do not** embed AWS credentials in client code — the API uses IAM roles on EC2 to presign S3 URLs.
+
+Use this doc when the client prompt mentions **AWS**, **CloudFront**, **S3**, **EC2**, or **Sprinklr hosting**.
+For Vercel deploy, use `npx cfm-sdk deploy` instead (see `index.md` Phase 7).
+
+---
+
+## Architecture — Three-Channel Flow
+
+```mermaid
+sequenceDiagram
+  participant Dev as Agent_DevMachine
+  participant API as EC2_Deploy_API
+  participant S3 as Hosting_Bucket
+  participant CF as CloudFront
+
+  Dev->>Dev: yarn build or npm run build
+  Dev->>API: POST /deploy/start + JWT + file manifest
+  API-->>Dev: deployId + presigned PUT URLs
+  loop each file in out/
+    Dev->>S3: PUT file direct
+  end
+  Dev->>API: POST /deploy/complete
+  API->>S3: HeadObject index.html
+  API->>CF: CreateInvalidation
+  API-->>Dev: public HTTPS URL
+```
+
+| Channel | Direction | Action |
+|---------|-----------|--------|
+| 1 Control | Dev → EC2 API | `POST /deploy/start` with JWT + file manifest |
+| 2 Data | Dev → S3 direct | `PUT` each static file to presigned URLs |
+| 3 Finalize | Dev → EC2 API | `POST /deploy/complete` → CloudFront URL |
+
+S3 path shape: `sites/{surveyId}/{deployId}/` — extracted from JWT at deploy time.
+
+---
+
+## Prerequisites (verify before deploy)
+
+1. **Phase 6 passed** — `npm run build` / `yarn build` exits 0
+2. **JWT alignment** — deploy JWT **must equal** `SURVEY_INSTANCE_ID` in `SurveyPage.tsx`
+3. **Static output exists** — Next.js: `out/index.html`; Vite: `dist/index.html`
+4. **File count ≤ 500** (API limit)
+
+### Environment variables (dev machine)
+
+```bash
+export CFM_INSTANCE_ID="<same JWT as SurveyPage SURVEY_INSTANCE_ID>"
+export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+export OUT_DIR="<absolute path to static output folder>"
+# Next.js example:
+# export OUT_DIR="/path/to/project/out"
+# Vite example:
+# export OUT_DIR="/path/to/project/dist"
+```
+
+### Health check
+
+```bash
+curl -s "$CFM_DEPLOY_API_BASE/health"
+# Expected: {"ok":true,"service":"sprinklr-deploy-api"}
+```
+
+---
+
+## Build Config (apply during Phase 5 BUILD)
+
+### Next.js — static export (required for AWS)
+
+See also [`setup.md#nextjs-aws-static-export`](setup.md#nextjs-aws-static-export).
+
+**`next.config.js`:**
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  transpilePackages: ['@explorer02/cfm-survey-sdk'], // or '@repo/sdk'
+  output: 'export',
+  assetPrefix: './', // required for nested CloudFront path
+  images: { unoptimized: true },
+};
+module.exports = nextConfig;
+```
+
+**`package.json` build script** — copy RSC payload for `index.html` URLs:
+
+```json
+"build": "next build && cp out/index.txt out/index.html.txt"
+```
+
+| Setting | Why |
+|---------|-----|
+| `output: 'export'` | Produces uploadable `out/` folder (no Node server) |
+| `assetPrefix: './'` | Assets resolve under `/sites/{surveyId}/{deployId}/`, not CloudFront root |
+| `images.unoptimized` | Image optimization needs a server; static export does not |
+| `index.html.txt` copy | Fixes 403 on `index.html.txt?_rsc` when page URL ends with `index.html` |
+
+### Vite
+
+Set `OUT_DIR` to `dist/`. Ensure asset paths in built HTML are **relative** (no leading `/`). See Vite `base: './'` if needed.
+
+---
+
+## Static Asset Rules (apply during BUILD)
+
+| Rule | Detail |
+|------|--------|
+| Public logos | Use relative paths (`logo.svg`), not `/logo.svg` |
+| Rank-order images | Prefer `option.imageUrl` over `option.previewImageUrl` — preview `*_p.*` URLs often return 403 |
+| Footer hash links | Use plain `<a href="#">`, not `next/link` — avoids RSC prefetch on static export |
+| No AWS keys in code | JWT only in `Authorization: Bearer` header at deploy time |
+
+---
+
+## Deploy Procedure (agent executes in order)
+
+### Step 0 — Build
+
+```bash
+cd <project-root>
+yarn build   # or npm run build
+test -f "$OUT_DIR/index.html" || { echo "Missing index.html"; exit 1; }
+find "$OUT_DIR" -type f | wc -l   # must be ≤ 500
+```
+
+### Step 1 — Channel 1: manifest + start
+
+```bash
+python3 <<'PY' > /tmp/deploy-manifest.json
+import json, os, mimetypes
+from pathlib import Path
+out = Path(os.environ["OUT_DIR"])
+files = []
+for path in sorted(out.rglob("*")):
+    if not path.is_file():
+        continue
+    rel = path.relative_to(out).as_posix()
+    mime, _ = mimetypes.guess_type(rel)
+    files.append({
+        "path": rel,
+        "contentType": mime or "application/octet-stream",
+        "sizeBytes": path.stat().st_size,
+    })
+print(json.dumps({"files": files}))
+print(f"files: {len(files)}", file=__import__('sys').stderr)
+PY
+
+curl -s -X POST "$CFM_DEPLOY_API_BASE/deploy/start" \
+  -H "Authorization: Bearer $CFM_INSTANCE_ID" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/deploy-manifest.json \
+  | tee /tmp/deploy-start.json
+```
+
+**Success:** JSON with `deployId`, `s3Prefix`, `uploads[]`.
+
+| Error | Fix |
+|-------|-----|
+| `401 TOKEN_EXPIRED` | Ask client for fresh instanceId JWT |
+| `503 DEPLOY_UNAVAILABLE` | EC2 hosting env misconfigured — report to operator |
+| `400 files must not exceed 500` | Reduce build output |
+
+### Step 2 — Channel 2: upload every file to S3
+
+```bash
+python3 <<'PY'
+import json, os, subprocess
+from pathlib import Path
+
+out = Path(os.environ["OUT_DIR"])
+start = json.load(open("/tmp/deploy-start.json"))
+manifest = {f["path"]: f["contentType"] for f in json.load(open("/tmp/deploy-manifest.json"))["files"]}
+failed = []
+
+for item in start["uploads"]:
+    path = item["path"]
+    url = item["uploadUrl"]
+    mime = manifest.get(path, "application/octet-stream")
+    proc = subprocess.run(
+        ["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}",
+         "-X", "PUT", url, "-H", f"Content-Type: {mime}",
+         "--data-binary", f"@{out / path}"],
+        capture_output=True, text=True,
+    )
+    code = proc.stdout.strip()
+    mark = "OK" if code == "200" else "FAIL"
+    print(f"{mark} {code} {path}")
+    if code != "200":
+        failed.append(path)
+
+if failed:
+    print(f"\n{len(failed)} failed — rerun from Step 1 (presigned URLs expire)")
+    raise SystemExit(1)
+print("\nAll uploads succeeded")
+PY
+```
+
+**Success:** every line shows `OK 200`.
+
+### Step 3 — Channel 3: complete + live URL
+
+```bash
+DEPLOY_ID=$(python3 -c "import json; print(json.load(open('/tmp/deploy-start.json'))['deployId'])")
+
+curl -s -X POST "$CFM_DEPLOY_API_BASE/deploy/complete" \
+  -H "Authorization: Bearer $CFM_INSTANCE_ID" \
+  -H "Content-Type: application/json" \
+  -d "{\"deployId\":\"$DEPLOY_ID\"}" \
+  | tee /tmp/deploy-complete.json
+
+python3 -c "import json; print('\nLive URL:\n' + json.load(open('/tmp/deploy-complete.json'))['url'])"
+```
+
+**Success:**
+
+```json
+{
+  "url": "https://<cloudfront-domain>/sites/{surveyId}/{deployId}/index.html",
+  "deployId": "...",
+  "surveyId": "..."
+}
+```
+
+### Step 4 — Verify
+
+```bash
+LIVE_URL=$(python3 -c "import json; print(json.load(open('/tmp/deploy-complete.json'))['url'])")
+curl -s -o /dev/null -w "index.html: %{http_code}\n" "$LIVE_URL"
+# Optional: grep one CSS href from HTML and curl it under the deploy prefix — expect 200
+```
+
+Tell the client to open the printed URL in a browser.
+
+---
+
+## One-Command Wrapper (optional)
+
+After build, from project root:
+
+```bash
+export CFM_INSTANCE_ID="<JWT>"
+export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+export OUT_DIR="<absolute path to out/ or dist/>"
+
+bash templates/deploy-to-aws.sh
+# or: bash node_modules/@explorer02/cfm-survey-sdk/templates/docs/templates/deploy-to-aws.sh
+```
+
+---
+
+## Repeat Deploys
+
+Each deploy creates a **new** `deployId` folder under `sites/{surveyId}/`. Old deploys remain in S3.
+
+After UI changes: rebuild → re-run Steps 1–3 (same `CFM_INSTANCE_ID` if same survey).
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Agent fix |
+|---------|-------|-----------|
+| 403 on `/_next/static/...` | Absolute asset paths | Add `assetPrefix: "./"`, rebuild |
+| 403 on `index.html.txt?_rsc` | Missing RSC payload file | Add `cp out/index.txt out/index.html.txt` to build script |
+| 403 on `*_p.png` / `*_p.jpg` images | Preview URL used | Use `option.imageUrl \|\| option.previewImageUrl` in RankOrderScale |
+| 401 `TOKEN_EXPIRED` | JWT expired | Ask client for new instanceId |
+| 503 `DEPLOY_UNAVAILABLE` | EC2 CloudFront/S3 env wrong | Report to operator |
+| Some PUTs 403 | Presigned URLs expired (default 5 min) | Restart from Step 1; complete within window |
+| Blank page, HTML 200 | JS/CSS not uploaded or wrong paths | Re-check Channel 2 logs |
+| Survey API errors in browser | Deploy JWT ≠ SurveyPage JWT | Align `SURVEY_INSTANCE_ID` |
+
+---
+
+## Future: CLI automation (Phase 7b)
+
+`npx cfm-sdk deploy --aws` is **not implemented yet**. Use the manual flow above or `templates/deploy-to-aws.sh` until the CLI ships.

package/templates/docs/00-integration/client-integration-guide.md

@@ -0,0 +1,351 @@
+# Client Integration Guide
+
+> **Start here** after Phase 2 (instanceId). Single map of everything the client must wire to integrate all SDK features correctly.
+
+Import only from the package root (`@explorer02/cfm-survey-sdk` or `@repo/sdk`). Never from `/src/` paths.
+
+## Architecture
+
+```mermaid
+flowchart TB
+  subgraph page [SurveyPage orchestrator]
+    Hook["useSurveySDK"]
+    PhaseRouter["Phase router\nloading / intro / content / end"]
+    Lifecycle["SCROLL + RECORD_QUESTION_VIEW effects"]
+  end
+  subgraph question [Question.tsx dispatcher]
+    Dispatch["QUESTION_TYPE switch"]
+    Visibility["getVisible*ForAnswers helpers"]
+    Placeholders["resolveSurveyQuestionPlaceholders"]
+  end
+  subgraph scales [Scale components]
+    Matrix["LikertMatrixScale / CsatMatrixScale / …"]
+    NPS["RatingScale / FileUploadScale / …"]
+  end
+  Hook --> PhaseRouter
+  PhaseRouter --> question
+  Dispatch --> scales
+  Visibility --> Dispatch
+```
+
+| Layer | File | Responsibility |
+|-------|------|----------------|
+| Orchestrator | `SurveyPage.tsx` | Hook, phase routing, nav buttons, lifecycle effects, pass props to `Question` |
+| Dispatcher | `Question.tsx` | Route on `question.type`; filter options/rows via visibility helpers; placeholder text |
+| Scales | `*Scale.tsx` | Render one question type; store answers via `onSelect` callback |
+
+Reference implementation: `apps/client/src/components/SurveyPage.tsx`.
+
+---
+
+## Feature matrix — who wires what
+
+| Feature | Client wires | SDK handles |
+|---------|--------------|-------------|
+| Fetch survey | `instanceId`, loading/error UI | `useFetchSurvey`, survey mapping |
+| Submit | `onAction(NEXT/SUBMIT)`, submit loading UI | Validation, API submit, phase → `end`, end-page selection |
+| End page logic | Render `state.specialPage`; pass `customFieldValues` when end pages reference CRM fields | Display-logic evaluation at submit; see [`end-page-logic.md`](end-page-logic.md) |
+| Answers | `onAction(CHANGE)` with `payload.answerValue` | `state.answers`, sanitization on logic change |
+| Skip logic | Nothing (read doc for UX expectations) | Path simulation, skip jumps, answer clearing |
+| Display logic | Use `state.currentQuestions` (pre-filtered) | Question-level visibility, empty-page skip |
+| Question display variants | Render `question.questionText` from `currentQuestions` (no client variant logic) | Conditional variant text via same logic engine |
+| Answer logic UI | `getVisible*ForAnswers` + pass `customFieldValues` | Condition evaluation engine |
+| Custom fields | Stable `customFieldValues` → hook **and** `Question` | Skip/display/validation/progress evaluation |
+| Progress | Bind `state.progressPercentage` | Active-path denominator + earned credits |
+| Question numbering | Render `question.questionNumber` from `currentQuestions` | Active-path ordinals (same denominator as progress); see [`question-numbering.md`](question-numbering.md) |
+| Placeholders | Stable `placeholders` ref + `language` option | Token replacement at map time |
+| Mark as started | `onAction(SCROLL)` once on first scroll | One-time API call (also fires on CHANGE) |
+| Question activity | `onAction(RECORD_QUESTION_VIEW)` via IntersectionObserver | Deduped VIEWED API calls |
+| Partial save | `savePartialResponse: true` option | Debounced partial POST after user interaction — see [`partial-save-and-recovery.md`](partial-save-and-recovery.md) |
+| Placeholders (detail) | Stable ref + `resolveSurveyQuestionPlaceholders` | CRM tokens at map time; answer tokens at render — see [`placeholders-and-tokens.md`](placeholders-and-tokens.md) |
+| Per-type integration | Read [`question-type-sdk-matrix.md`](question-type-sdk-matrix.md) before building scales | Answer shapes, visibility helpers, performance notes per type |
+| Validation scroll | `id={question.id}` on question wrapper | Scroll-to-first-error on failed NEXT/SUBMIT |
+
+Deep dives: [`useSurveySDK.md`](useSurveySDK.md) · [`question-type-sdk-matrix.md`](question-type-sdk-matrix.md) · [`placeholders-and-tokens.md`](placeholders-and-tokens.md) · [`partial-save-and-recovery.md`](partial-save-and-recovery.md) · [`survey-lifecycle-analytics.md`](survey-lifecycle-analytics.md) · [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md) · [`display-logic-and-navigation.md`](display-logic-and-navigation.md) · [`question-display-variants.md`](question-display-variants.md) · [`question-numbering.md`](question-numbering.md) · [`end-page-logic.md`](end-page-logic.md) · [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md) · [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) · [`progress.md`](progress.md) · [`constraints.md`](constraints.md)
+
+---
+
+## Stable references (CRITICAL)
+
+Inline option objects cause infinite re-fetch loops and React hook dependency churn. Define **outside** the component and wrap hook options in `useMemo`:
+
+```typescript
+const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'Customer' };
+
+const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {
+  '_c_abc123': 'value',
+};
+
+export default function SurveyPage() {
+  const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>();
+
+  const surveyOptions = useMemo(
+    () => ({
+      instanceId: 'YOUR_JWT_HERE',
+      language: selectedLanguage,
+      placeholders: SURVEY_PLACEHOLDERS,
+      customFieldValues: CUSTOM_FIELD_VALUES,
+      savePartialResponse: false as const,
+      debug: false,
+    }),
+    [selectedLanguage]
+  );
+
+  const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
+    options: surveyOptions,
+  });
+  // ...
+}
+```
+
+---
+
+## Minimal SurveyPage skeleton
+
+```tsx
+'use client';
+
+import { useState, useMemo, useEffect } from 'react';
+import {
+  useSurveySDK,
+  type CustomFieldValueMap,
+  type Survey,
+} from '@explorer02/cfm-survey-sdk';
+import Question from './Question';
+
+const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'Customer' };
+const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {}; // fill from CRM when survey uses custom-field logic
+
+function SurveyContent({
+  survey,
+  allQuestions,
+  customFieldValues,
+  state,
+  submitSurveyResults,
+  onAction,
+}: {
+  survey: Survey;
+  allQuestions: Survey['pages'][number]['questions'];
+  customFieldValues: CustomFieldValueMap;
+  state: ReturnType<typeof useSurveySDK>['state'];
+  submitSurveyResults: ReturnType<typeof useSurveySDK>['submitSurveyResults'];
+  onAction: ReturnType<typeof useSurveySDK>['onAction'];
+}) {
+  // Mark as started on first scroll
+  useEffect(() => {
+    const onScroll = () => onAction({ type: 'SCROLL' });
+    window.addEventListener('scroll', onScroll, { passive: true, once: true });
+    return () => window.removeEventListener('scroll', onScroll);
+  }, [onAction]);
+
+  // Question activity (VIEWED)
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      entries => {
+        for (const entry of entries) {
+          if (entry.isIntersecting && entry.target.id) {
+            onAction({
+              type: '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]);
+
+  return (
+    <main>
+      <ProgressBar progressPercentage={state.progressPercentage} />
+
+      {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={customFieldValues}
+          onSelect={answerValue =>
+            onAction({ type: 'CHANGE', payload: { questionId: question.id, answerValue } })
+          }
+        />
+      ))}
+
+      {state.canGoBack && (
+        <button type="button" onClick={() => onAction({ type: 'PREVIOUS' })}>Back</button>
+      )}
+      <button
+        type="button"
+        onClick={() => onAction({ type: 'NEXT' })}
+        disabled={submitSurveyResults.isLoading}
+      >
+        {state.primaryButtonType === 'submit' ? 'Submit' : 'Next'}
+      </button>
+    </main>
+  );
+}
+
+export default function SurveyPage() {
+  const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>();
+
+  const surveyOptions = useMemo(
+    () => ({
+      instanceId: 'YOUR_JWT_HERE',
+      language: selectedLanguage,
+      placeholders: SURVEY_PLACEHOLDERS,
+      customFieldValues: CUSTOM_FIELD_VALUES,
+    }),
+    [selectedLanguage]
+  );
+
+  const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
+    options: surveyOptions,
+  });
+
+  const survey = surveyQueryResults.data;
+  const allQuestions = useMemo(
+    () => survey?.pages.flatMap(page => page.questions) ?? [],
+    [survey]
+  );
+
+  if (surveyQueryResults.isLoading) return <div>Loading…</div>;
+  if (surveyQueryResults.error) return <div>Error: {surveyQueryResults.error.message}</div>;
+  if (!survey) return <div>No survey data</div>;
+
+  // Phase router — handle intro / paused / end / terminal before content
+  if (state.phase.kind === 'intro') return <IntroPage onStart={() => onAction({ type: 'START' })} />;
+  if (state.phase.kind === 'end') return <EndPage page={state.specialPage} />;
+  // … paused, submitted, expired, quota_fulfilled
+
+  if (state.phase.kind === 'content') {
+    return (
+      <SurveyContent
+        survey={survey}
+        allQuestions={allQuestions}
+        customFieldValues={CUSTOM_FIELD_VALUES}
+        state={state}
+        submitSurveyResults={submitSurveyResults}
+        onAction={onAction}
+      />
+    );
+  }
+
+  return null;
+}
+```
+
+See [`01-components/01-survey-page.md`](../01-components/01-survey-page.md) for full phase routing.
+
+---
+
+## Question dispatcher essentials
+
+Copy [`templates/Question.tsx`](../templates/Question.tsx). Dispatch on flat `question.type` — **11** `QUESTION_TYPE` literals, no `subType`.
+
+See [`question-type-sdk-matrix.md`](question-type-sdk-matrix.md) for per-type answer shapes, visibility helpers, and `onAction` patterns.
+
+| Type literal | Component | Visibility helper |
+|--------------|-----------|-------------------|
+| `MCQ` | Inline | `getVisibleMcqOptionsForAnswers` |
+| `TEXTFIELD` | Inline | — |
+| `NPS_SCALE` | `RatingScale` | `getVisibleScaleColumnsForAnswers` |
+| `CFM_MATRIX` | `LikertMatrixScale` | `getVisibleMatrixItemsForAnswers` |
+| `CSAT_MATRIX`, `RATING_MATRIX` | `CsatMatrixScale` | `getVisibleMatrixItemsForAnswers` |
+| `SLIDER_MATRIX` | `SliderMatrixScale` | `getVisibleStatementRowsForAnswers` |
+| `FILE_UPLOAD` | `FileUploadScale` | — |
+| `TEXT_AND_MEDIA` | Inline media | — |
+| `HEATMAP` | `HeatmapScale` | — |
+| `RANK_ORDER` | `RankOrderScale` | `getVisibleRankOrderOptionsForAnswers` |
+
+**Answer logic:** filter before render:
+
+```typescript
+getVisibleMcqOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues);
+getVisibleMatrixItemsForAnswers(question, allAnswers, allQuestions, customFieldValues);
+```
+
+**Placeholders:** stable `SURVEY_PLACEHOLDERS` ref + `resolveSurveyQuestionPlaceholders(text, allAnswers, questionsById)`. See [`placeholders-and-tokens.md`](placeholders-and-tokens.md).
+
+**Wrapper:** every question `<section id={question.id}>` for scroll-to-error.
+
+See [`component-checklist.md`](component-checklist.md) and [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md).
+
+---
+
+## Custom fields — two wiring points
+
+When survey logic references `conditionEntity.entityType: 'CUSTOM_FIELD'`:
+
+1. **`useSurveySDK` options** — `customFieldValues` map keyed by `_c_…` ids (skip, display, validation, progress).
+2. **`Question.tsx` visibility helpers** — pass the **same map** as the 4th argument to `getVisible*ForAnswers` (answer-logic UI on options/rows/columns).
+
+See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
+
+---
+
+## Monorepo build prerequisite
+
+When using `@repo/sdk` from the monorepo, build the SDK before running the client dev server:
+
+```bash
+cd packages/sdk && npm run build
+```
+
+Without a built `dist/`, the client fails with missing module errors. Rebuild after SDK changes.
+
+---
+
+## Debug logging and analytics
+
+Enable debug console logs with `useSurveySDK({ options: { debug: true } })`. Logic match logs appear as `[SDK:INFO]` when conditions **newly become true** on answer change:
+
+| Log message | When |
+|-------------|------|
+| `Display logic matched` | A gated question becomes visible |
+| `Answer logic matched` | An option / row / column becomes visible via answer logic |
+| `Question variant matched` | A display variant’s condition matches |
+| `End page logic matched` | The winning end page changes (preview before submit) |
+| `Skip logic matched` | Skip logic newly activates on the current question |
+
+Analytics events (`[SDK:ANALYTICS]`) fire **always**, even without `debug: true`:
+
+| Event | When |
+|-------|------|
+| `display_logic_matched` | Display logic condition newly true |
+| `answer_logic_matched` | Answer-logic sub-entity newly visible |
+| `question_variant_matched` | Variant text switches to a matching variant |
+| `end_page_logic_matched` | Resolved end page changes |
+| `question_viewed` | Question enters viewport (`RECORD_QUESTION_VIEW`) |
+| `skip_logic_triggered` | Skip logic newly activates on answer change |
+| `logic_session_summary` | On successful submit — rollup table + chronological timeline |
+
+The submit-time `logic_session_summary` includes counts per logic kind, viewed vs on-path-not-viewed questions, final end page resolution, and a `logicEventTimeline` audit. It prints via `console.table` alongside `survey_session_summary`.
+
+---
+
+## Pre-flight checklist
+
+Before `npm run build`:
+
+- [ ] Import from package root only — no `@repo/sdk/src/…` paths
+- [ ] `SURVEY_PLACEHOLDERS` and `CUSTOM_FIELD_VALUES` defined outside component
+- [ ] `surveyOptions` wrapped in `useMemo` (depends on `selectedLanguage` etc.)
+- [ ] `Question.tsx` copied from `docs/templates/Question.tsx` — all **11** type branches, no stub text
+- [ ] `SURVEY_PLACEHOLDERS` defined outside component; `surveyOptions` in `useMemo` (see [`placeholders-and-tokens.md`](placeholders-and-tokens.md))
+- [ ] `id={question.id}` on every question wrapper
+- [ ] `customFieldValues` passed to hook **and** `Question` (when survey uses custom-field logic)
+- [ ] Answer logic: `getVisible*ForAnswers` receives `customFieldValues` 4th arg
+- [ ] `SCROLL` + `RECORD_QUESTION_VIEW` lifecycle effects wired (see [`survey-lifecycle-analytics.md`](survey-lifecycle-analytics.md))
+- [ ] `state.canGoBack` / `state.primaryButtonType` used for nav (not raw page index)
+- [ ] Monorepo: SDK built (`packages/sdk/dist/` exists)
+- [ ] `grep -r "not yet implemented" src/ components/ app/` → zero matches
+
+Run `bash templates/verify-agent-build.sh` from project root after Phase 5.