@explorer02/cfm-survey-sdk 0.2.0 → 0.2.2

package/templates/docs/00-integration/component-checklist.md

@@ -0,0 +1,84 @@
+# Required Component Files Checklist
+
+> **Blocking gate before Phase 5 (BUILD).** After fetching the survey with `instanceId`, list every `question.type` and ensure all required files exist.
+
+## Step 1: Inventory Question Types
+
+From `survey.pages`, collect unique `question.type` values — see `MANIFEST.json` `typeLiterals`:
+
+| questionId | type |
+|------------|------|
+| | |
+
+## Step 2: Create Required Files
+
+| If survey contains | Agent MUST create before `npm run build` | UI spec |
+|--------------------|------------------------------------------|---------|
+| `NPS_SCALE` | `RatingScale.tsx` | `03-ui-specs/01-rating.md` |
+| `CFM_MATRIX` | `LikertMatrixScale.tsx`, `MatrixDropdown.tsx` | `03-ui-specs/07-matrix-cfm.md` |
+| `CSAT_MATRIX` | `CsatMatrixScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx` | `03-ui-specs/04-csat.md` |
+| `RATING_MATRIX` | `CsatMatrixScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx` | `03-ui-specs/08-matrix-csat-rating.md` |
+| `SLIDER_MATRIX` | `SliderMatrixScale.tsx`, `CustomSliderTrack.tsx` | `03-ui-specs/09-slider-matrix.md` |
+| `FILE_UPLOAD` | `FileUploadScale.tsx` | `03-ui-specs/10-file-upload.md` |
+| `MCQ`, `TEXTFIELD`, `TEXT_AND_MEDIA` | Inline in `Question.tsx` | `03-ui-specs/02-radio.md`, `03-text.md`, `11-text-and-media.md` |
+| `RANK_ORDER` | `RankOrderScale.tsx` (+ `@dnd-kit/*`) | `03-ui-specs/14-rank-order.md` |
+| `HEATMAP` | `HeatmapScale.tsx`, `lib/heatmapCoords.ts` (copy from `templates/heatmapCoords.ts`) | `03-ui-specs/13-heatmap.md` |
+
+**Survey chrome (when applicable):**
+
+| Component | When |
+|-----------|------|
+| `IntroPage.tsx` | `survey.introPage` |
+| `EndPage.tsx` | `survey.endPages` |
+| `PausedPage.tsx` | `survey.phaseFlags.paused` |
+
+Always create **`Question.tsx`** from [`templates/Question.tsx`](../templates/Question.tsx).
+
+## Flat Type Routing (CRITICAL)
+
+Use `QUESTION_TYPE` — **no `subType`**:
+
+```tsx
+import { QUESTION_TYPE } from '@explorer02/cfm-survey-sdk';
+
+{question.type === QUESTION_TYPE.CFM_MATRIX && (
+  <LikertMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
+)}
+
+{(question.type === QUESTION_TYPE.CSAT_MATRIX ||
+  question.type === QUESTION_TYPE.RATING_MATRIX) && (
+  <CsatMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
+)}
+```
+
+## Shared Primitives
+
+| File | Used by |
+|------|---------|
+| `CustomSliderTrack.tsx` | `SLIDER_MATRIX`, matrix `displayStyle: graphics` |
+| `MatrixDropdown.tsx` | `CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX` dropdown/selectbox modes |
+
+Store matrix values as column **`id`** — `matrixColumnStoredValue(col)` from SDK.
+
+## Answer logic (when survey has gated options / rows / columns)
+
+- [ ] MCQ: filter options with `getVisibleMcqOptionsForAnswers(question, answers, allQuestions, customFieldValues)`
+- [ ] Matrix (CSAT/CFM/RATING/SLIDER): filter rows (and CSAT/CFM columns) with `getVisibleMatrixItemsForAnswers(question, answers, allQuestions, customFieldValues)`
+- [ ] Pass `customFieldValues` from `SurveyPage` → `Question` when survey logic references `CUSTOM_FIELD` entities
+- [ ] Wire `onAction({ type: 'CHANGE' })` so answer logic re-evaluates when prior answers change
+
+See [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md) and [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
+
+## Step 3: Verify Before Build
+
+- [ ] Every type in the survey inventory has a matching component file
+- [ ] `Question.tsx` copied from `docs/templates/Question.tsx` with all **11** type branches wired
+- [ ] `SurveyPage` handles all `state.phase` values
+- [ ] No `default` fallback rendering stub text (see `constraints.md` §7)
+- [ ] RANK_ORDER: `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities` in `package.json`
+- [ ] Per-type wiring verified against `question-type-sdk-matrix.md`
+- [ ] Grep project: `not yet implemented` → **zero matches**
+
+```bash
+grep -r "not yet implemented" src/ components/ app/ 2>/dev/null || true
+```

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

@@ -36,9 +36,64 @@ Required for scroll-to-error when validation fails.
 
 Survey UI files importing the SDK must be client components. Next.js: `'use client'` at top of file.
 
-## 6. Stable Placeholder References
+## 6. Stable Placeholder and Custom Field References
 
-Define `SURVEY_PLACEHOLDERS` outside the component — inline objects cause infinite re-fetch.
+Define `SURVEY_PLACEHOLDERS` and `CUSTOM_FIELD_VALUES` **outside** the component — inline objects cause infinite re-fetch and unstable hook dependency arrays.
+
+Wrap hook `options` in `useMemo`:
+
+```typescript
+const surveyOptions = useMemo(
+  () => ({
+    instanceId,
+    language: selectedLanguage,
+    placeholders: SURVEY_PLACEHOLDERS,
+    customFieldValues: CUSTOM_FIELD_VALUES,
+  }),
+  [selectedLanguage]
+);
+```
+
+See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) when the survey uses custom-field logic.
+
+## 7. No Stub Placeholders (CRITICAL)
+
+**FORBIDDEN** in `Question.tsx` or any scale component:
+
+- Text like `"not yet implemented"`, `"coming soon"`, or any placeholder error message
+- `default` / `else` branches in the dispatcher that render stub UI instead of the real component
+- Empty `<div>` where an interactive scale component should be
+
+If a question type appears in the fetched survey, its component **must** be fully implemented before shipping. Read the matching `03-ui-specs/` doc and create the required files listed in `component-checklist.md`.
+
+**Phase 6 verification:** grep the project for stub text — must return zero matches:
+
+```bash
+grep -r "not yet implemented" src/ components/ app/ 2>/dev/null || true
+```
+
+---
+
+## 8. Deploy Constraints
+
+- **Never embed AWS credentials** in client code — JWT goes in `Authorization: Bearer` header at deploy time only
+- **Deploy JWT must match** `SURVEY_INSTANCE_ID` in `SurveyPage.tsx` (surveyId drives S3 prefix)
+- **Next.js AWS deploy requires static export** — no server-only APIs (`getServerSideProps`, etc.)
+- **Max 500 files** per deploy (EC2 API limit)
+- **No absolute `/`-root asset paths** when deploying to nested CloudFront prefix — use `assetPrefix: "./"` and relative public assets
+
+See [`aws-deploy.md`](aws-deploy.md) for the full AWS deploy procedure and troubleshooting.
+
+---
+
+## 9. SDK Integration Constraints
+
+- **Never import internal evaluators** from `@explorer02/cfm-survey-sdk/src/**` or `@repo/sdk/src/**`
+- **Always use public `getVisible*ForAnswers` helpers** for answer-logic UI filtering — never reimplement condition evaluation
+- **Matrix cell values:** always store column **`id`** via `matrixColumnStoredValue(column)` — never raw label text
+- **Rank order:** use SDK rank helpers (`assignRankWithoutDuplicates`, `normalizeRankOrderAnswers`, etc.) — do not hand-roll rank maps
+- **CSAT emoji/star UI:** implement client-side with `react-icons` — no phantom SDK emoji exports
+- **Read [`question-type-sdk-matrix.md`](question-type-sdk-matrix.md)** before building any scale component
 
 ---
 
@@ -47,8 +102,15 @@ Define `SURVEY_PLACEHOLDERS` outside the component — inline objects cause infi
 | Symptom | Fix |
 |---------|-----|
 | `Cannot use import statement outside a module` | Add SDK to `transpilePackages` in `next.config.js` |
-| Infinite API requests | Move `placeholders` object outside component |
+| Infinite API requests | Move `placeholders` / `customFieldValues` outside component; wrap options in `useMemo` |
+| `useEffect` dependency array size changed | Unstable inline `options` object — use `useMemo` for hook options |
+| Missing `dist/index.mjs` (monorepo) | Run `npm run build` in `packages/sdk` before client dev |
 | `window is not defined` | Add `'use client'` to SDK-consuming files |
 | Validation errors but no scroll | Add `id={question.id}` to question wrapper |
 | Survey data is null, no error | Invalid/expired `instanceId` — ask client for fresh JWT |
 | CSAT emojis missing | `npm install react-icons` |
+| Grey "not yet implemented" text on questions | Copy `docs/templates/Question.tsx`; create scale components per `component-checklist.md`; route each matrix variant by flat `question.type` |
+| 403 on `/_next/static/...` after AWS deploy | Add `assetPrefix: "./"` to `next.config.js`, rebuild — see `aws-deploy.md` |
+| 403 on survey images `*_p.png` | Use `option.imageUrl` before `option.previewImageUrl` in RankOrderScale |
+| 403 on `index.html.txt?_rsc` | Add `cp out/index.txt out/index.html.txt` to build script |
+| AWS deploy PUT failures | Presigned URLs expired — restart from `/deploy/start` within 5–15 min |

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

@@ -0,0 +1,174 @@
+# Custom Field Logic and Navigation
+
+> Integrator-facing contract for CRM/transaction custom fields used in skip, display, and answer logic. Evaluation runs inside the SDK — pass values via hook options; do not import internal `surveyLogic` paths.
+
+## When this applies
+
+Survey logic rules may reference **custom fields** instead of survey questions:
+
+```json
+{
+  "conditionEntity": {
+    "id": "_c_6a436c1244764c9d4a6ce2fc",
+    "entityType": "CUSTOM_FIELD",
+    "fieldType": "TEXT"
+  }
+}
+```
+
+Inspect fetched survey data: any `skipLogics`, `displayLogic`, or `answerLogic` with `entityType: 'CUSTOM_FIELD'` requires client-supplied values.
+
+---
+
+## Client value map
+
+Pass via `useSurveySDK({ options: { customFieldValues } })`. Keys are the `_c_…` ids from logic rules.
+
+```typescript
+import type { CustomFieldValueMap } from '@explorer02/cfm-survey-sdk';
+
+const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {
+  '_c_6a436c1244764c9d4a6ce2fc': 'q5',              // TEXT
+  '_c_6a436c3644764c9d4a6ce3f5': 2,                  // NUMBER
+  '_c_6a436c9e44764c9d4a6ce717': 'option-id-uuid',   // PICKLIST
+  '_c_6a436cbb44764c9d4a6ce7e5': ['opt-a', 'opt-b'], // PICKLIST_MULTISELECT
+  '_c_6a4386dc44208eb8b08a9056': 1781029800000,       // DATETIME (epoch ms)
+};
+```
+
+Define **outside** the component (stable ref — same rule as `placeholders`). Wrap hook `options` in `useMemo`.
+
+| Custom field type (`fieldType`) | Client value shape |
+|--------------------------------|-------------------|
+| TEXT / TEXT_MULTI / TEXTAREA | `string` |
+| NUMBER | `number` or numeric string (`0` is valid, not empty) |
+| PICKLIST | `string` (option id) |
+| PICKLIST_MULTISELECT | `string[]` (option ids) |
+| DATETIME | epoch ms (`number` or numeric string); ISO date strings also accepted |
+
+Missing keys in the map are treated as **empty** for logic evaluation.
+
+---
+
+## Operator contract
+
+| fieldType | Logic `field` | Operators |
+|-----------|---------------|-----------|
+| TEXT / TEXT_MULTI / TEXTAREA | `TEXT` or `CASE_SENSITIVE_TEXT` | EQUALS, NOT_EQUALS, CONTAINS, DOES_NOT_CONTAIN, MISSING, EXISTS |
+| NUMBER | `NUMBER` | LT, LTE, GT, GTE, EQUALS, NOT_EQUALS, MISSING, EXISTS |
+| PICKLIST / PICKLIST_MULTISELECT | `SELECTED_OPTIONS` | CONTAINS, DOES_NOT_CONTAIN, MISSING, EXISTS |
+| DATETIME | `SELECTED_DATETIME` | LT, LTE, GT, GTE, EQUALS, NOT_EQUALS |
+
+Filter `values` in API rules use strings (e.g. `'1781029800000'` for datetime). The SDK normalizes client datetime values to epoch ms for comparison.
+
+Datetime filters may include `valueAdditional.timezone` (e.g. `"Asia/Kolkata"`) — reserved for future timezone-aware parsing; comparisons currently use epoch ms numbers.
+
+---
+
+## Two wiring points (CRITICAL)
+
+Custom field values must reach **both** the hook and the question dispatcher:
+
+```mermaid
+flowchart LR
+  CRM["CRM / transaction payload"]
+  Map["CUSTOM_FIELD_VALUES map"]
+  Hook["useSurveySDK options"]
+  Question["Question.tsx"]
+  Nav["Skip / display / validation / progress"]
+  AnswerUI["Answer-logic option/row filtering"]
+
+  CRM --> Map
+  Map --> Hook --> Nav
+  Map --> Question --> AnswerUI
+```
+
+### 1. Hook options (navigation layer)
+
+```typescript
+useSurveySDK({
+  options: {
+    customFieldValues: CUSTOM_FIELD_VALUES,
+  },
+});
+```
+
+SDK uses this for:
+
+- Skip logic path simulation and jumps
+- Question-level display logic (`state.currentQuestions`)
+- Submit / Next validation on the active path
+- Progress bar denominator
+
+### 2. Question visibility helpers (answer-logic UI)
+
+When answer logic conditions reference custom fields, pass the **same map** to exported helpers:
+
+```typescript
+import {
+  getVisibleMcqOptionsForAnswers,
+  getVisibleMatrixItemsForAnswers,
+  getVisibleStatementRowsForAnswers,
+  getVisibleScaleColumnsForAnswers,
+} from '@explorer02/cfm-survey-sdk';
+
+getVisibleMcqOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues);
+getVisibleMatrixItemsForAnswers(question, allAnswers, allQuestions, customFieldValues);
+```
+
+Without the 4th argument, answer-logic UI defaults to an empty custom-field map — options/rows gated on CRM data may render incorrectly even though navigation logic works.
+
+**SurveyPage → Question prop threading:**
+
+```tsx
+<Question
+  customFieldValues={CUSTOM_FIELD_VALUES}
+  allAnswers={state.answers}
+  allQuestions={allQuestions}
+  // ...
+/>
+```
+
+---
+
+## Discovering field ids
+
+After fetching the survey with `instanceId`, search logic payloads for `_c_` ids:
+
+- `question.skipLogics[].condition.filters`
+- `question.displayLogic.condition.filters`
+- `question.options[].answerLogic` / matrix row `answerLogic` / column `answerLogic`
+
+Record each id in `implementation_plan.md` §3c and populate `CUSTOM_FIELD_VALUES` from your CRM/transaction API.
+
+---
+
+## Example — skip rule on custom field
+
+Rule: if TEXT custom field `_c_abc` equals `"premium"`, skip to Q6.
+
+```typescript
+const CUSTOM_FIELD_VALUES = { '_c_abc': 'premium' };
+
+useSurveySDK({ options: { instanceId, customFieldValues: CUSTOM_FIELD_VALUES } });
+```
+
+User clicks Next on page 1 → SDK evaluates condition → jumps to Q6's page. No extra client code per question.
+
+If the user later changes a CRM field value at runtime, update `customFieldValues` via a new stable map and remount or pass updated options through `useMemo` deps.
+
+---
+
+## Multiple skip logic blocks
+
+When a question has several `skipLogics[]` entries (including custom-field rules), the SDK evaluates them **top-to-bottom** and applies the **first match**. See [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md).
+
+---
+
+## Related docs
+
+- [`useSurveySDK.md`](useSurveySDK.md) — hook options and stable refs
+- [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md) — skip behavior with custom fields
+- [`display-logic-and-navigation.md`](display-logic-and-navigation.md) — question-level gating
+- [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md) — option/row/column gating + visibility helpers
+- [`client-integration-guide.md`](client-integration-guide.md) — full wiring map

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

@@ -0,0 +1,49 @@
+# Display Logic and Navigation
+
+> Integrator-facing behavior contract. Display evaluation is handled inside the SDK — do not import internal `surveyLogic` paths directly unless using exported helpers.
+
+## Shared engine with skip logic
+
+Skip logic, display logic, and answer logic use the **same condition tree** (`LogicFilterGroup` with nested `AND` / `OR` groups) and the **same evaluator** (`evaluateCondition`). The SDK distinguishes them with `LOGIC_KIND`:
+
+| Kind | When true |
+|------|-----------|
+| `SKIP` | Navigate to skip target or end of survey |
+| `DISPLAY` | Show the gated **question** (whole question / page-level) |
+| `ANSWER` | Show a gated **option, statement row, or scale column** within a question |
+
+> **Note:** Statement-row and scale-column filtering is **answer logic**, not display logic. See [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md).
+
+## Dynamic vs non-dynamic
+
+| Mode | API flag | Behavior |
+|------|----------|----------|
+| **Dynamic** | `isDynamicAppearanceEnabled: true` | Gated question stays on the **same page** as trigger questions. Hidden until condition is true. Page stays on active path; hidden questions are excluded from progress denominator. |
+| **Non-dynamic** | `isDynamicAppearanceEnabled: false` | Gated question is on a **separate page**. When condition is false, that page is skipped in navigation and excluded from active path. |
+
+## Nested conditions
+
+Both skip and display support nested AND/OR groups from the API. Flat skip rows (`Q3 = 1 OR Q3 = 2 OR Q3 > 6`) and nested display condition groups map to the same recursive tree.
+
+## Client responsibilities
+
+- Use `state.currentQuestions` from `useSurveySDK` — the SDK filters hidden questions automatically.
+- Matrix UIs must filter statement rows with `getVisibleStatementRowsForAnswers(question, answers, allQuestions)` (or `getVisibleMatrixItemsForAnswers` for rows + scale columns).
+- Wire `onAction({ type: 'CHANGE' })` so display conditions re-evaluate when answers change.
+
+## Progress bar
+
+Progress counts **visible answerable questions on the active path**. When display logic hides a question:
+
+- **Dynamic:** page remains on path; hidden question excluded from total until visible.
+- **Non-dynamic:** gated page excluded from path until condition is true.
+
+## Custom field conditions
+
+Display logic may gate questions on **custom field** values (`conditionEntity.entityType: 'CUSTOM_FIELD'`). See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) for the full integration contract.
+
+## Question display variants (distinct from show/hide)
+
+Alternate question wording (`questionDisplayVariants`) uses the same condition engine but **does not hide** the question — the SDK resolves `questionText` on `state.currentQuestions`. See [`question-display-variants.md`](question-display-variants.md).
+
+See also: [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md), [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md), [`progress.md`](progress.md).

package/templates/docs/00-integration/end-page-logic.md

@@ -0,0 +1,64 @@
+# End Page Logic
+
+> Integrator-facing contract for surveys with **multiple end pages**. Selection runs inside the SDK at submit time — do not import internal `surveyLogic` paths.
+
+## When it runs
+
+After a **successful submit**, the SDK evaluates each end page's `displayLogic` (mapped from API `controlConfig.displayLogic`) and sets `state.phase` to `{ kind: 'end', endPageId }`. The client renders `state.specialPage` — no extra wiring.
+
+## Selection rules
+
+End pages are evaluated in **API order**:
+
+1. **Conditional pages** — pages with `displayLogic`: return the **first** whose condition is true (same evaluator as question display logic: nested AND/OR, question answers, custom fields).
+2. **Default page** — if no conditional page matches, use the **first page without** `displayLogic`.
+3. **Safety fallback** — if every page has logic and none match, use `endPages[0]`.
+
+`isDynamicAppearanceEnabled` on end pages is ignored (evaluation happens once at submit).
+
+## Default vs conditional pages
+
+Typical builder setup:
+
+| End page | `displayLogic` | Role |
+|----------|----------------|------|
+| End Page | none | Default thank-you screen |
+| End Page 2 | OR/AND conditions | Shown when rules match |
+
+Example: show **End Page 2** when multiselect MCQ **contains** Option 1 **and** Option 3 (both must be selected). Otherwise show the default end page.
+
+For `SELECTED_OPTIONS` / `CONTAINS`, multiple values in the rule mean **all** listed options must be selected (Sprinklr multiselect semantics). A single listed option still matches when only that option is selected.
+
+## Custom fields
+
+When end-page rules reference `conditionEntity.entityType: 'CUSTOM_FIELD'`, pass the same `options.customFieldValues` map used for skip/display logic:
+
+```typescript
+useSurveySDK(instanceId, {
+  customFieldValues: {
+    '_c_6a436c1244764c9d4a6ce2fc': 'end2',
+    '_c_6a436c3644764c9d4a6ce3f5': 2,
+  },
+});
+```
+
+Without this map, custom-field branches evaluate as empty/missing.
+
+### OR branches and static mock values
+
+Conditional end pages often use **OR** groups (any branch true → show that page). If `customFieldValues` includes a value that satisfies one branch unconditionally—e.g. number field `= 2` while the survey has `NUMBER EQUALS 2` in an OR branch—that end page will **always** win at submit, even when MCQ/NPS answers would otherwise show the default page.
+
+When testing answer-driven branches, omit unrelated custom-field keys or set them to values that do not match other OR branches.
+
+## Client responsibilities
+
+- Render `<EndPage page={state.specialPage} />` when `state.phase.kind === 'end'`.
+- Use `state.phase.endPageId` (and `options.debug`) during development to verify selection when headers match.
+- Pass `customFieldValues` via hook options when the survey's end pages reference custom fields.
+- No logic evaluation in the client — the SDK resolves `endPageId` before setting phase.
+
+## Supported condition fields
+
+Same as skip/display logic: `SELECTED_OPTIONS`, `NUM_OF_SELECTED_OPTIONS`, `TEN_POINT_SCALE`, `TEXT`, `CASE_SENSITIVE_TEXT`, custom-field `NUMBER`, `PICKLIST`, `DATETIME`, etc.
+
+See also: [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md), [`display-logic-and-navigation.md`](display-logic-and-navigation.md), [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md), [`01-components/15-end-page.md`](../01-components/15-end-page.md).

package/templates/docs/00-integration/partial-save-and-recovery.md

@@ -0,0 +1,74 @@
+# Partial Save and Recovery
+
+> Covers `sdkFeatures.partialSave` — debounced autosave of in-progress responses.
+
+---
+
+## When to enable
+
+Pass in `useSurveySDK` options:
+
+```typescript
+useSurveySDK({
+  ...surveyOptions,
+  savePartialResponse: true,           // default debounce
+  // or
+  savePartialResponse: { debounceMs: 1500 },
+});
+```
+
+Enable when the survey config or client prompt requires resume/recovery UX. If not requested, omit the option.
+
+---
+
+## `partialSaveResults` shape
+
+Same surface as submit results (type inferred from hook return):
+
+| Field | Meaning |
+|-------|---------|
+| `partialSaveResults.data` | Last successful partial save payload (`SubmitResult \| null`) |
+| `partialSaveResults.isLoading` | POST in flight |
+| `partialSaveResults.error` | Last failure |
+
+Monitor these for optional "Saving…" / error toasts. Do **not** reimplement the POST endpoint logic client-side.
+
+---
+
+## Interaction with skip / display logic
+
+When skip or display logic hides a question, the SDK **sanitizes** answers for questions no longer on the active path before partial save. Client components should not manually delete hidden answers — the SDK handles consistency on path changes.
+
+After a partial save succeeds, reloading the survey instance may restore prior answers depending on backend behavior (outside SDK scope).
+
+---
+
+## When partial save starts
+
+Partial saves begin only after the **first user interaction** (a real `CHANGE` action). MCQ default seeding or programmatic answer init does not trigger an immediate save.
+
+Each subsequent debounced answer change triggers another partial save with `surveySubmitted: false`.
+
+---
+
+## Error UX patterns
+
+| Scenario | Recommended UX |
+|----------|----------------|
+| Transient network error | Silent retry on next debounced change; optional subtle indicator |
+| Persistent error | Non-blocking banner: "Unable to save progress" |
+| Success | Usually no UI — optional checkmark on footer |
+
+Do not block navigation (NEXT/PREVIOUS) on partial save failure unless product explicitly requires it.
+
+---
+
+## Verify checklist
+
+- [ ] `savePartialResponse` only set when required
+- [ ] No duplicate fetch/submit logic outside SDK
+- [ ] `TEXT_AND_MEDIA` questions produce no CHANGE (correct — no answer to save)
+- [ ] Hidden-path answers not manually managed in client state
+- [ ] Optional UI wired to `partialSaveResults.isLoading` / `.error`
+
+See [`useSurveySDK.md`](useSurveySDK.md) for hook signature and [`client-integration-guide.md`](client-integration-guide.md) for full wiring map.

package/templates/docs/00-integration/placeholders-and-tokens.md

@@ -0,0 +1,116 @@
+# Placeholders and Tokens
+
+> Covers `sdkFeatures.placeholderResolution` — how CRM and dynamic answer tokens resolve in question text.
+
+---
+
+## Token formats
+
+| Token pattern | Example | Resolved by |
+|---------------|---------|-------------|
+| CRM / static placeholder | `{{FIRST_NAME}}`, `{{COMPANY}}` | SDK at map time via `options.placeholders` |
+| Survey question answer | `{{SURVEY_QUESTION-:-questionId}}` | Client at render time via `resolveSurveyQuestionPlaceholders` |
+| Display variant text | Variant bodies may contain both | SDK resolves static tokens on variants; client resolves answer tokens |
+
+Question IDs in answer tokens match the fetched survey's `question.id` (not display order).
+
+---
+
+## Stable `placeholders` ref
+
+Define placeholders **outside** the React component (module scope or parent file):
+
+```typescript
+const SURVEY_PLACEHOLDERS = {
+  FIRST_NAME: 'Alex',
+  COMPANY: 'Acme Corp',
+} as const;
+```
+
+Wrap hook options in `useMemo` so the SDK does not re-fetch on every render:
+
+```typescript
+const surveyOptions = useMemo(
+  () => ({
+    instanceId: SURVEY_INSTANCE_ID,
+    language: selectedLanguage,
+    placeholders: SURVEY_PLACEHOLDERS,
+    customFieldValues: SURVEY_CUSTOM_FIELDS,
+  }),
+  [selectedLanguage]
+);
+```
+
+**Failure mode:** Inline `placeholders={{ FIRST_NAME: '...' }}` inside the component causes infinite fetch loops.
+
+---
+
+## Where SDK resolves vs client responsibility
+
+| Stage | What happens |
+|-------|--------------|
+| **Fetch / map time** | SDK applies language translation + static CRM placeholders to question text and display variants |
+| **`currentQuestions`** | Each question's `questionText` is already variant-resolved for the active path |
+| **Render time (client)** | `Question.tsx` calls `resolveSurveyQuestionPlaceholders(text, answers, questionsById)` for `{{SURVEY_QUESTION-:-id}}` tokens |
+
+Do **not** reimplement CRM token substitution in components — only answer-reference tokens need client resolution.
+
+---
+
+## `resolveSurveyQuestionPlaceholders`
+
+Import from package root:
+
+```typescript
+import { resolveSurveyQuestionPlaceholders } from '@explorer02/cfm-survey-sdk';
+```
+
+Typical usage in `Question.tsx`:
+
+```typescript
+const resolvedText = resolveSurveyQuestionPlaceholders(
+  question.questionText,
+  allAnswers,
+  questionsById
+);
+```
+
+Pass **all** answers and a `questionsById` map built from the full survey (not just `currentQuestions`) so cross-page answer tokens resolve.
+
+---
+
+## `formatAnswerForDisplay`
+
+When a token references another question's answer, the SDK formats the stored answer for human-readable display:
+
+```typescript
+import { formatAnswerForDisplay } from '@explorer02/cfm-survey-sdk';
+
+// Used internally by resolveSurveyQuestionPlaceholders; call directly only for custom UI
+const label = formatAnswerForDisplay(question, answerValue);
+```
+
+Matrix answers format as row/column labels; MCQ as option text; rank order as ordered list.
+
+---
+
+## Wiring checklist
+
+- [ ] `SURVEY_PLACEHOLDERS` defined at module scope (stable ref)
+- [ ] `surveyOptions` wrapped in `useMemo`
+- [ ] `Question` receives `allAnswers` + `allQuestions` (or `questionsById`)
+- [ ] Question shell renders `resolveSurveyQuestionPlaceholders` output, not raw `questionText` when answer tokens may appear
+- [ ] Display variants: trust SDK-resolved text on `currentQuestions`; still run answer-token pass at render
+
+---
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Token shows literally `{{FIRST_NAME}}` | Missing key in `placeholders` map | Add key matching token name (without braces) |
+| Answer token empty | Referenced question unanswered or hidden | Expected until answered; hidden answers sanitized on skip path change |
+| Infinite API requests | Unstable `placeholders` ref | Move outside component; `useMemo` on options |
+| Expired JWT / fetch error | Instance ID invalid | Refresh token; placeholders unrelated |
+
+See also [`question-display-variants.md`](question-display-variants.md) and [`client-integration-guide.md`](client-integration-guide.md).