@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

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,64 @@
+# 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), [`logic-fields-catalog.md`](logic-fields-catalog.md).
+
+---
+
+## Worked example — dynamic display on same page
+
+**Setup:** Page 1 has Q1 (MCQ trigger) and Q2 (display-gated, `isDynamicAppearanceEnabled: true`). Q2 hidden until Q1 selects option A.
+
+1. User loads page → `currentQuestions` = [Q1] only; progress denominator excludes Q2.
+2. User selects A → SDK evaluates display logic → `currentQuestions` = [Q1, Q2]; Q2 animates in; progress total increases.
+3. User answers Q2 → normal CHANGE flow.
+4. User changes Q1 away from A → SDK sanitizes Q2 answer; Q2 hidden again; progress credits adjust.
+
+**Client:** render `state.currentQuestions` only — no manual show/hide. Re-run IntersectionObserver effect when `currentQuestions` changes.
+
+**Back navigation:** if display logic hides all questions on a page, SDK skips empty pages — user never sees a blank screen (see skip/display integration tests).

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/file-upload-aws.md

@@ -0,0 +1,116 @@
+# File Upload — Presigned S3 Flow
+
+> Required for **submittable** file-upload answers. Raw `File[]` in `state.answers` is **dropped** at submit — SDK expects `UploadedFileAnswer[]` with `id` and `mediaUrl`.
+
+Related: [`03-ui-specs/10-file-upload.md`](../03-ui-specs/10-file-upload.md) · [`02-reference/question-types/11-file-upload.md`](../02-reference/question-types/11-file-upload.md)
+
+---
+
+## Answer contract
+
+```typescript
+type UploadedFileAnswer = {
+  id: string;
+  mediaUrl: string;
+  name?: string;
+  mimeType?: string;
+  size?: number;
+};
+
+onAction({
+  type: 'CHANGE',
+  payload: { questionId, answerValue: UploadedFileAnswer[] },
+});
+```
+
+Submit formatter maps to `quesIdVsAttachmentDetails[questionId]`.
+
+---
+
+## Upload API (EC2 reference — Day 22)
+
+**Base URL:** configure via env (example: `http://43.204.26.213:3000` or project-specific upload service).
+
+### Step 1 — Request presigned URL
+
+```http
+POST /get-upload-url
+Content-Type: application/json
+
+{
+  "fileName": "report.pdf",
+  "contentType": "application/pdf",
+  "questionId": "<question.id>"
+}
+```
+
+**Response:**
+
+```json
+{
+  "uploadUrl": "https://s3.amazonaws.com/...",
+  "fileId": "generated-id",
+  "mediaUrl": "https://cdn.../path/to/file"
+}
+```
+
+### Step 2 — PUT file to S3
+
+```http
+PUT {uploadUrl}
+Content-Type: application/pdf
+Body: <file binary>
+```
+
+### Step 3 — Update SDK state
+
+Append to answer array and call `onAction(CHANGE)` with `{ id: fileId, mediaUrl, name, mimeType, size }`.
+
+---
+
+## Client implementation sketch
+
+```typescript
+async function uploadFile(file: File, questionId: string): Promise<UploadedFileAnswer> {
+  const res = await fetch(`${UPLOAD_API_BASE}/get-upload-url`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      fileName: file.name,
+      contentType: file.type,
+      questionId,
+    }),
+  });
+  const { uploadUrl, fileId, mediaUrl } = await res.json();
+  await fetch(uploadUrl, { method: 'PUT', body: file, headers: { 'Content-Type': file.type } });
+  return { id: fileId, mediaUrl, name: file.name, mimeType: file.type, size: file.size };
+}
+```
+
+Wire `UPLOAD_API_BASE` from env — **never** embed AWS credentials in client code.
+
+---
+
+## UI states
+
+| State | UX |
+|-------|-----|
+| Uploading | Spinner on file row; disable dropzone |
+| Success | Show file in list; call `onAction(CHANGE)` |
+| Failure | Red banner; keep local file uncommitted |
+| Remove | Update array; `undefined` when empty |
+
+---
+
+## Partial save
+
+Only call `onAction(CHANGE)` after upload completes — partial save should not POST raw `File` blobs.
+
+---
+
+## Agent checklist
+
+- [ ] Local validation before upload (format, count, size)
+- [ ] Presigned PUT wired per file
+- [ ] Final answer is `UploadedFileAnswer[]` with `id` + `mediaUrl`
+- [ ] Submit body includes attachments (verify in network tab)

package/templates/docs/00-integration/logic-fields-catalog.md

@@ -0,0 +1,105 @@
+# Logic Fields Catalog
+
+> Central reference for skip, display, answer, variant, and end-page logic fields by question type. Agents do **not** implement evaluators — wire UI + hook; SDK evaluates conditions.
+
+Cross-links: [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md) · [`display-logic-and-navigation.md`](display-logic-and-navigation.md) · [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md) · [`end-page-logic.md`](end-page-logic.md)
+
+---
+
+## MCQ
+
+| Field | Used in | Operators | Notes |
+|-------|---------|-----------|-------|
+| `SELECTED_OPTIONS` / option id | skip, display, end | contains, does not contain, equals | Single or multi option ids |
+| `NUM_OF_SELECTED_OPTIONS` | skip, display, end | `EQUALS`, `GT`, `LT`, etc. | Count of selected option ids; zero = missing for EXISTS |
+| Option-level answer logic | answer (UI) | same engine | `getVisibleMcqOptionsForAnswers` |
+
+---
+
+## TEXTFIELD / TEXT_AND_MEDIA
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| `TEXT` / `CASE_SENSITIVE_TEXT` | skip, display, end | empty, contains, equals, etc. |
+| TEXT_AND_MEDIA | — | no answer stored |
+
+---
+
+## NPS_SCALE
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| `TEN_POINT_SCALE` / scale value | skip, display, end | numeric compare `<`, `>`, `==`, `!=` |
+| Scale point answer logic | answer (UI) | `getVisibleScaleColumnsForAnswers` |
+
+---
+
+## CFM_MATRIX / CSAT_MATRIX / RATING_MATRIX
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| Per-row composite keys | skip, display | per statement row + column id |
+| Matrix cell values | skip, display | numeric or column id match |
+| Row/column answer logic | answer (UI) | `getVisibleMatrixItemsForAnswers` |
+
+Store answers as column **`id`** via `matrixColumnStoredValue`.
+
+---
+
+## SLIDER_MATRIX
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| Row statement values | skip, display | numeric compare |
+| Row answer logic | answer (UI) | `getVisibleStatementRowsForAnswers` |
+
+---
+
+## FILE_UPLOAD
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| Presence only | skip, display | `EXISTS`, `MISSING` |
+| Evaluation | on page entry | no discrete value-change events |
+
+---
+
+## HEATMAP
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| `HEATMAP` | skip, display | spot count, presence |
+| `HEATMAP_REGION` | skip, display | region label match |
+
+Regions are **logic-only** — not rendered on respondent UI.
+
+---
+
+## RANK_ORDER
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| `RANK_ORDER` (per option) | skip, display, answer | ranked as (`EQUALS`), ranked more/less than (`GT`/`LT`), ranked above/below (`BEFORE`/`AFTER`) |
+| Whole question | skip, display | `EXISTS`, `MISSING` |
+
+See [`02-reference/question-types/13-rank-order.md`](../02-reference/question-types/13-rank-order.md).
+
+---
+
+## CUSTOM_FIELD (all types)
+
+| Field | Used in | Value shapes |
+|-------|---------|--------------|
+| `_c_*` entity ids | skip, display, end, answer | TEXT, NUMBER, PICKLIST, DATETIME, multiselect |
+
+Pass stable `customFieldValues` to hook **and** visibility helpers. See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
+
+---
+
+## Client wiring summary
+
+| Logic kind | Client action |
+|------------|---------------|
+| Skip / display / end / variants | Render `state.currentQuestions`; no client evaluators |
+| Answer logic | `getVisible*ForAnswers(..., customFieldValues?)` before render |
+| Custom fields | Two wiring points: hook options + Question visibility helpers |

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

@@ -0,0 +1,98 @@
+# 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.
+
+---
+
+## Per-type debounce guidance
+
+| Question type | Client UI note |
+|---------------|----------------|
+| TEXTFIELD (long) | Debounce `onAction(CHANGE)` 300–500 ms to reduce partial-save churn |
+| SLIDER_MATRIX / graphics | Debounce slider `onChange` or rely on SDK debounce |
+| FILE_UPLOAD | Call `CHANGE` only **after** presigned upload completes — see [`file-upload-aws.md`](file-upload-aws.md) |
+| MCQ / matrix | Immediate `CHANGE` on selection is fine |
+| TEXT_AND_MEDIA | No CHANGE — excluded from partial save payload |
+
+---
+
+## Recovery (honest scope)
+
+Reload behavior depends on **backend** + instance configuration — the SDK debounces POST to `responseV2` with `surveySubmitted: false` but does not implement client-side resume UI. If product requires resume:
+
+- Enable `savePartialResponse`
+- Optionally show `partialSaveResults` status
+- Confirm with backend team whether refetch restores `state.answers`
+
+Path-change sanitization (skip/display) clears off-path answers before partial save — see [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md).
+
+---
+
+## 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.