@explorer02/cfm-survey-sdk 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorer02/cfm-survey-sdk",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/templates/AGENT.md

@@ -20,20 +20,24 @@ Import from whatever appears in `package.json`:
 | 0 | Detect framework; extract branding from client prompt |
 | 1 | Scaffold React app — `00-integration/setup.md` |
 | 2 | Ask client for instanceId JWT |
-| 3 | Read `client-integration-guide.md` + `question-type-sdk-matrix.md` + hook/logic/lifecycle docs — full SDK contract |
-| 4 | Fetch survey; inventory types; read MANIFEST-driven docs per type + matrix row; copy `templates/Question.tsx` + `implementation_plan.md` |
-| 5 | Build UI — read matrix before any scale component; create files from `component-checklist.md`; dispatch on **11** flat `QUESTION_TYPE` literals; apply AWS static export if prompt requires |
+| 3 | Read `client-integration-guide.md` + `question-type-sdk-matrix.md` + hook/logic/lifecycle/analytics docs — full SDK contract |
+| 4 | Fetch survey; inventory types; read MANIFEST-driven docs per type; copy `templates/Question.tsx` + scale templates + `implementation_plan.md` |
+| 5 | Build UI — copy templates from `docs/templates/`; read ui-spec Implementation Recipes; dispatch on **11** flat `QUESTION_TYPE` literals |
 | 6 | Run `templates/verify-agent-build.sh` |
-| 7 | On confirmation: **AWS prompt** → `00-integration/aws-deploy.md` + EC2 3-channel deploy; **Vercel prompt** → `npx cfm-sdk deploy` |
+| 7 | On confirmation: **AWS prompt** → `aws-deploy.md`; **Vercel prompt** → `npx cfm-sdk deploy` |
 
 **Do NOT** run `cfm-sdk init`, read `survey-config.json`, or use any setup wizard.
 
 **Do NOT** render `"not yet implemented"` or default fallback stubs in `Question.tsx`. Copy `templates/docs/templates/Question.tsx` and create all required scale components.
 
+**Copy scale templates from `docs/templates/`** before implementing from ui-spec recipes: `RankOrderScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx`, `surveyUiIcons.tsx`, `heatmapCoords.ts`.
+
 **Do NOT** route matrix questions by `subType` — use flat types: `CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX`, `SLIDER_MATRIX`.
 
 **Read `question-type-sdk-matrix.md` before building any scale component** — it defines answer shapes, visibility helpers, and performance expectations for all 11 types.
 
+**FILE_UPLOAD:** wire presigned upload per `00-integration/file-upload-aws.md` — raw `File[]` does not submit.
+
 **Monorepo:** run `npm run build` in `packages/sdk` before starting the client dev server.
 
 Follow the master index strictly. Do not guess SDK internals. Do not import from `/src/` paths.

package/templates/docs/00-integration/analytics-events-catalog.md

@@ -0,0 +1,54 @@
+# Analytics Events Catalog
+
+> Consolidated SDK telemetry and client-wired lifecycle events. Most events log to console as `[SDK:ANALYTICS]` — **no client code required** unless noted.
+
+See also: [`survey-lifecycle-analytics.md`](survey-lifecycle-analytics.md) · [`client-integration-guide.md`](client-integration-guide.md) § Debug logging
+
+---
+
+## Client must wire
+
+| Event / action | How | When |
+|----------------|-----|------|
+| Mark as started | `onAction({ type: 'SCROLL' })` once on first window scroll | First content engagement |
+| Question viewed | `onAction({ type: 'RECORD_QUESTION_VIEW', payload: { questionId } })` via IntersectionObserver on `#question.id` | Question 50% visible |
+| Partial save feedback | Monitor `partialSaveResults.isLoading` / `.error` | When `savePartialResponse: true` |
+
+First `CHANGE` also triggers mark-as-started (SDK) — no extra client call.
+
+---
+
+## SDK-emitted (always — no `debug` flag required)
+
+| Event | When | Metadata highlights |
+|-------|------|---------------------|
+| `fetch_survey_latency` | Survey GET completes | durationMs, status, payloadSize (UTF-8 KB) |
+| `fetch_survey_error` | Survey GET fails | status, url, message |
+| `submit_survey_latency` | Submit POST completes | durationMs, status |
+| `submit_survey_error` | Submit fails | status, message |
+| `page_time_spent` | Leaving a content page | pageIndex, durationMs |
+| `optional_question_skipped` | Optional question left blank on forward nav | questionId, pageIndex |
+| `backtrack_revisited` | User returns to earlier page and changes answers | fromPage, toPage, changedAnswers |
+| `question_viewed` | After RECORD_QUESTION_VIEW deduped | questionId |
+| `display_logic_matched` | Display condition newly true | questionId, logic details |
+| `answer_logic_matched` | Answer-logic sub-entity newly visible | entity scope |
+| `question_variant_matched` | Variant text switches | variant id |
+| `end_page_logic_matched` | Resolved end page changes | endPageId |
+| `skip_logic_triggered` | Skip logic newly activates | skip target |
+
+---
+
+## Post-submit rollups
+
+| Event | When | Contents |
+|-------|------|----------|
+| `survey_session_summary` | Successful submit | `completed`, `maxVisitedPageIndex`, `totalDurationMs`, question counts (total/answered/skipped), `validationErrorsCount`, `backtrackCount`, `validationHistory` |
+| `logic_session_summary` | Successful submit | Per-logic-kind counts, viewed vs on-path-not-viewed, final end page, `logicEventTimeline` audit (console.table) |
+
+Enable `debug: true` in hook options for additional `[SDK:INFO]` transition logs (display/answer/variant/end/skip matches on answer change).
+
+---
+
+## Validation error tracking
+
+SDK increments validation error counts and records per-page error history in session summary. Client displays `state.validationErrors[questionId]` banners and uses `id={question.id}` for scroll-to-error.

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

@@ -61,7 +61,7 @@ Reference implementation: `apps/client/src/components/SurveyPage.tsx`.
 | 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)
+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) · [`analytics-events-catalog.md`](analytics-events-catalog.md) · [`logic-fields-catalog.md`](logic-fields-catalog.md) · [`file-upload-aws.md`](file-upload-aws.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)
 
 ---
 

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

@@ -12,6 +12,16 @@ From `survey.pages`, collect unique `question.type` values — see `MANIFEST.jso
 
 ## Step 2: Create Required Files
 
+**Copy portable templates from [`templates/`](../templates/) when available** — then customize branding. Otherwise implement from ui-spec Implementation Recipe.
+
+| Portable template | Copy to |
+|-------------------|---------|
+| `templates/Question.tsx` | `src/components/Question.tsx` |
+| `templates/RankOrderScale.tsx` | `src/components/RankOrderScale.tsx` |
+| `templates/MatrixDropdown.tsx` | `src/components/MatrixDropdown.tsx` |
+| `templates/CustomSliderTrack.tsx` + `surveyUiIcons.tsx` | same folder |
+| `templates/heatmapCoords.ts` | `src/lib/heatmapCoords.ts` |
+
 | If survey contains | Agent MUST create before `npm run build` | UI spec |
 |--------------------|------------------------------------------|---------|
 | `NPS_SCALE` | `RatingScale.tsx` | `03-ui-specs/01-rating.md` |

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

@@ -46,4 +46,19 @@ Display logic may gate questions on **custom field** values (`conditionEntity.en
 
 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).
+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/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

@@ -63,6 +63,30 @@ Do not block navigation (NEXT/PREVIOUS) on partial save failure unless product e
 
 ---
 
+## 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

package/templates/docs/00-integration/question-type-sdk-matrix.md

@@ -38,7 +38,9 @@ Legend: **opt** = option-level; **row+col** = statement rows and scale columns;
 | **Value derivation** | Store `option.id`; SDK maps to API value at submit |
 | **Performance notes** | Filter options once per render via helper; avoid re-fetch on option click |
 | **Docs to read** | [`02-question.md`](../01-components/02-question.md) · [`question-types/README.md#mcq`](../02-reference/question-types/README.md#mcq) · [`02-radio.md`](../03-ui-specs/02-radio.md) |
-| **Known limitations** | Multi-select array shape is client responsibility; verify `selectionMode` from survey config |
+| **Default answers** | SDK `applyMcqDefaults` seeds `state.answers` from `defaultOptionIds` on load — client binds `selectedValue` only |
+| **Answer conditions** | SDK validates `minSelections` / `maxSelections` on NEXT; client blocks add at max + shows `validationError` |
+| **Known limitations** | Multi-select stores `string[]`; use `selectionMode` not `isMultiSelect` |
 
 ---
 
@@ -160,18 +162,18 @@ Legend: **opt** = option-level; **row+col** = statement rows and scale columns;
 
 | Column | Value |
 |--------|-------|
-| **SDK type + answer shape** | `FileUploadQuestion`; answer `UploadedFile[]` |
+| **SDK type + answer shape** | `FileUploadQuestion`; answer `UploadedFileAnswer[]` (`{ id, mediaUrl, name?, mimeType?, size? }`) |
 | **Component file(s)** | `FileUploadScale.tsx` |
 | **Dispatcher branch** | `QUESTION_TYPE.FILE_UPLOAD` / `'FILE_UPLOAD'` |
 | **Visibility helper** | None |
 | **Answer logic scope** | None |
 | **Skip / display / variants / numbering** | SDK auto |
 | **Custom field logic** | Skip/display only |
-| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: UploadedFile[] } }` after upload completes |
-| **Value derivation** | SDK submit maps file metadata to API |
-| **Performance notes** | Upload to presigned URL before CHANGE; show progress UI |
-| **Docs to read** | [`08-file-upload-scale.md`](../01-components/08-file-upload-scale.md) · [`11-file-upload.md`](../02-reference/question-types/11-file-upload.md) · [`10-file-upload.md`](../03-ui-specs/10-file-upload.md) |
-| **Known limitations** | Blocking question — validate file count/size client-side per config |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: UploadedFileAnswer[] } }` **after** presigned upload completes |
+| **Value derivation** | SDK submit maps to `quesIdVsAttachmentDetails` — raw `File[]` is **not submitted** |
+| **Performance notes** | Local validate → POST presigned URL → PUT file → then CHANGE; show progress UI |
+| **Docs to read** | [`file-upload-aws.md`](file-upload-aws.md) · [`08-file-upload-scale.md`](../01-components/08-file-upload-scale.md) · [`11-file-upload.md`](../02-reference/question-types/11-file-upload.md) · [`10-file-upload.md`](../03-ui-specs/10-file-upload.md) |
+| **Known limitations** | Must wire upload API; see [`file-upload-aws.md`](file-upload-aws.md) |
 
 ---
 
@@ -198,14 +200,14 @@ Legend: **opt** = option-level; **row+col** = statement rows and scale columns;
 
 | Column | Value |
 |--------|-------|
-| **SDK type + answer shape** | `HeatmapQuestion`; answer `HeatmapAnswer` (`{ clicks: HeatmapClickPoint[] }`) |
+| **SDK type + answer shape** | `HeatmapQuestion`; answer `HeatmapClickPoint[]` (array of `{ id, x, y }` normalized 0–1) |
 | **Component file(s)** | `HeatmapScale.tsx` + portable coord helper (see [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts)) |
 | **Dispatcher branch** | `QUESTION_TYPE.HEATMAP` / `'HEATMAP'` |
 | **Visibility helper** | None |
 | **Answer logic scope** | None |
 | **Skip / display / variants / numbering** | SDK auto |
 | **Custom field logic** | Skip/display only |
-| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: HeatmapAnswer } }` on each click add/remove |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: HeatmapClickPoint[] \| undefined } }` on each click add/remove |
 | **Value derivation** | Normalized 0–1 coordinates; respect `maxClicksAllowed` |
 | **Performance notes** | Normalize coords on image load; use `findSpotNearClick` for hit testing |
 | **Docs to read** | [`17-heatmap-scale.md`](../01-components/17-heatmap-scale.md) · [`12-heatmap.md`](../02-reference/question-types/12-heatmap.md) · [`13-heatmap.md`](../03-ui-specs/13-heatmap.md) |

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

@@ -138,15 +138,15 @@ For **existing apps**, read `package.json` and project structure — do not scaf
 
 After fetching the survey, install extra packages only when those types appear:
 
-### RANK_ORDER — drag-and-drop mode
+### RANK_ORDER — dnd-kit (required when survey contains RANK_ORDER)
 
-When the survey contains `RANK_ORDER` with `interactionMode: 'dragAndDrop'` (or you implement drag UI):
+Install whenever the survey inventory includes **`RANK_ORDER`** — the portable template supports both dropdown and drag-and-drop modes:
 
 ```bash
 npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
 ```
 
-See [`18-rank-order-scale.md`](../01-components/18-rank-order-scale.md) and [`question-type-sdk-matrix.md#rank_order`](question-type-sdk-matrix.md#rank_order).
+Copy [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx) before building. See [`18-rank-order-scale.md`](../01-components/18-rank-order-scale.md).
 
 ### HEATMAP — coordinate normalization
 

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

@@ -77,4 +77,4 @@ Event: `optional_question_skipped` with `questionId` and `pageIndex`.
 - 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).
+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

@@ -79,7 +79,7 @@ useEffect(() => {
 
 ## Debug: `logic_session_summary`
 
-When `debug: true` is set in hook options, the SDK emits structured console events including lifecycle transitions. Cross-reference event names in [`useSurveySDK.md`](useSurveySDK.md) during integration testing.
+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).
 
 ---
 

package/templates/docs/01-components/06-likert-matrix-scale.md

@@ -23,9 +23,10 @@ If `true`, the standard Row-by-Column matrix is inverted:
 - **Architectural Requirement**: Your `<tbody>` map must iterate over `question.columns` first, and render `<td>` cells mapped from `question.rows`.
 - Ensure `onSelect` still correctly pairs the original `row.id` with the original `col.value`.
 
-### 2. `repeatScale`
+### 2. `repeatColumnHeaders`
 If `true`, the `<thead>` containing column labels must be re-injected periodically to prevent users from losing track of columns on long matrices.
 - **Implementation Strategy**: In your row `map()`, if `index > 0 && index % 5 === 0`, return a React Fragment containing a cloned `<tr>` header row followed by the actual data `<tr>`.
+- **Note:** API/config field is `repeatColumnHeaders` (not `repeatScale`).
 
 ### 3. `matrixType === 'bipolar'`
 Standard matrices (`'likert'`) only show statement text on the left. Bipolar scales show text on BOTH sides of the radio buttons.

package/templates/docs/01-components/08-file-upload-scale.md

@@ -1,67 +1,30 @@
 # File Upload Architectural Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/10-file-upload.md`
-> **Reference implementation:** `apps/client/src/components/FileUploadScale.tsx`
-> **Target Component**: `FileUploadScale`
-> **Handles**: `type: 'FILE_UPLOAD'`
+> **Upload API:** [`00-integration/file-upload-aws.md`](../00-integration/file-upload-aws.md)
+> **Portable template:** implement per ui-spec (upload wiring is project-specific)
+> **Target Component:** `FileUploadScale`
+> **Handles:** `type: 'FILE_UPLOAD'`
 
 ## Core Responsibility
-Render a robust drag-and-drop zone and enforce complex file size, type limits, and maximum file count constraints BEFORE updating the state.
 
-## State Management
-- `selectedValue`: Expects an array of native `File` objects (or serialized equivalents).
-- **Mutation Pattern**: 
-  1. The user selects files.
-  2. The component intercepts the files.
-  3. The component validates them against ALL limits.
-  4. If valid, append the new files to `selectedValue` (handling it as an array).
-  5. Call `onSelect(updatedFilesArray)`.
-
-## Configuration Matrix (CRITICAL FOR PLANNING)
-
-Before calling `onSelect`, your component MUST validate against these properties:
-
-### 1. `supportedFileFormats`
-- Extracted from `question.supportedFileFormats` (e.g. `['PDF', 'PNG', 'JPG']`).
-- Use this to build the `accept` attribute string for the hidden input: `question.supportedFileFormats?.map(f => \`.\${f.toLowerCase()}\`).join(',')`.
-- You MUST reject files with extensions that are not in this list.
+Render drag-and-drop zone, validate files locally, **upload via presigned URL**, then bubble `UploadedFileAnswer[]` via `onSelect`.
 
-### 2. `maxFileCount`
-- Prevent uploads if `currentFiles.length + newFiles.length > maxFileCount`.
-- Provide a clear local error message indicating the max limit.
-
-### 3. `fileSizeLimit` & `fileSizeLimitType`
-- `fileSizeLimit` is a number representing megabytes (MB).
-- If `fileSizeLimitType === 'PER_FILE'`, validate that EVERY incoming file's `size` (in bytes) is `<= fileSizeLimit * 1024 * 1024`.
-- If `fileSizeLimitType === 'IN_TOTAL'`, validate that the combined sum of all existing `selectedValue` sizes plus the incoming files' sizes is `<= fileSizeLimit * 1024 * 1024`.
-
-## UI/UX Specifications
-
-1. **Dropzone**:
-   - Wrap the main area with `onDragEnter`, `onDragOver`, `onDragLeave`, `onDrop`.
-   - **Inactive State**: `border-2 border-dashed border-gray-300 rounded-xl bg-gray-50 p-8 text-center cursor-pointer transition-all`.
-   - **Drag/Hover State**: `border-[#e20074] bg-[#fdf2f8]` (Using the brand primary color).
-   - Display a Cloud SVG icon (use gray, switch to magenta on hover).
-   - Render `question.uploadMessage` (which can contain HTML, so use `dangerouslySetInnerHTML`).
-   - Dynamically render the limits text (e.g., "Max 3 files, 10MB per file").
+## State Management
 
-2. **File List**:
-   - Render existing files as distinct cards underneath the dropzone.
-   - Styling: `flex items-center justify-between p-3 mt-3 border border-gray-200 rounded-lg bg-white shadow-sm`.
-   - Display the filename (truncated if long) and the formatted file size (e.g., "1.2 MB").
-   - Include a distinct, circular Trash/Remove button that removes the file from the state and calls `onSelect` with the updated array.
+- `selectedValue`: `UploadedFileAnswer[] | undefined` — **not** raw `File[]` after upload completes
+- **Mutation pattern:**
+  1. User selects files → local validation
+  2. For each file: request presigned URL → PUT to S3 → append `{ id, mediaUrl, name, mimeType, size }`
+  3. `onSelect(uploadedAnswers)` → `onAction(CHANGE)`
 
-3. **Validation Errors**:
-   - Local validation errors (e.g. "File too large") must be displayed in a highly visible red banner (`bg-red-50 text-red-700 p-3 rounded-md`) right below the dropzone.
+## Local validation (before upload)
 
-## Hidden Input
-- Include a hidden `<input type="file" multiple={question.maxFileCount > 1} accept={...} />` that is triggered via a `useRef` when the dropzone is clicked.
+Same as ui-spec: `supportedFileFormats`, `maxFileCount`, `fileSizeLimit` + `fileSizeLimitType`.
 
 ## SDK Integration Checklist (agent)
 
 - [ ] Type literal: `QUESTION_TYPE.FILE_UPLOAD`
-- [ ] Answer stored as: `UploadedFile[]`
-- [ ] onAction CHANGE: `{ questionId, answerValue: UploadedFile[] }` after upload
-- [ ] Visibility helper: N/A
-- [ ] Enforce `maxFileCount` and `fileSizeLimit` client-side
+- [ ] Final answer: `UploadedFileAnswer[]` with `id` + `mediaUrl`
+- [ ] Wire upload API per [`file-upload-aws.md`](../00-integration/file-upload-aws.md)
 - [ ] Matrix row: [`question-type-sdk-matrix.md#file_upload`](../00-integration/question-type-sdk-matrix.md#file_upload)