@explorer02/cfm-survey-sdk 0.2.1 → 0.2.2

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.

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

@@ -1,41 +1,52 @@
 # Required Component Files Checklist
 
-> **Blocking gate before Phase 5 (BUILD).** After fetching the survey with `instanceId`, list every `(type, subType)` pair and ensure all required files exist.
+> **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 combinations:
+From `survey.pages`, collect unique `question.type` values — see `MANIFEST.json` `typeLiterals`:
 
-| questionId | type | subType (if matrix) |
-|------------|------|---------------------|
-| | | |
+| questionId | type |
+|------------|------|
+| | |
 
 ## Step 2: Create Required Files
 
 | If survey contains | Agent MUST create before `npm run build` | UI spec |
 |--------------------|------------------------------------------|---------|
-| `rating` | `RatingScale.tsx` | `03-ui-specs/01-rating.md` |
-| `csat` | `CsatScale.tsx` | `03-ui-specs/04-csat.md` |
-| `rating_scale` | Reuse `CsatScale.tsx` or dedicated component | `03-ui-specs/05-rating-scale.md` |
-| `slider` | `CustomSliderTrack.tsx` + wrapper | `03-ui-specs/06-slider.md` |
-| `matrix` + `CFM_MATRIX` | `LikertMatrixScale.tsx`, `MatrixDropdown.tsx` | `03-ui-specs/07-matrix-cfm.md` |
-| `matrix` + `CSAT_MATRIX` or `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` |
-| `radio`, `text`, `text_and_media` | Inline in `Question.tsx` | `03-ui-specs/02-radio.md`, `03-text.md`, `11-text-and-media.md` |
+| `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).
 
-## Matrix subType Routing (CRITICAL)
+## Flat Type Routing (CRITICAL)
 
-`question.type === 'matrix'` alone renders **nothing**. You MUST branch on `subType`:
+Use `QUESTION_TYPE` — **no `subType`**:
 
 ```tsx
-{question.type === 'matrix' && question.subType === 'CFM_MATRIX' && (
+import { QUESTION_TYPE } from '@explorer02/cfm-survey-sdk';
+
+{question.type === QUESTION_TYPE.CFM_MATRIX && (
   <LikertMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
 )}
 
-{question.type === 'matrix' && (question.subType === 'CSAT_MATRIX' || question.subType === 'RATING_MATRIX') && (
+{(question.type === QUESTION_TYPE.CSAT_MATRIX ||
+  question.type === QUESTION_TYPE.RATING_MATRIX) && (
   <CsatMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
 )}
 ```
@@ -44,16 +55,28 @@ Always create **`Question.tsx`** from [`templates/Question.tsx`](../templates/Qu
 
 | File | Used by |
 |------|---------|
-| `CustomSliderTrack.tsx` | `slider_matrix`, CSAT matrix `graphics`, standalone `slider` |
-| `MatrixDropdown.tsx` | `LikertMatrixScale`, `CsatMatrixScale` vertical/dropdown modes |
+| `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
 
-Specs: `03-ui-specs/shared/custom-slider-track.md`, `03-ui-specs/shared/matrix-dropdown.md`
+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 branches wired
+- [ ] `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

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

@@ -36,9 +36,25 @@ 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)
 
@@ -58,14 +74,43 @@ 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
+
+---
+
 ## Troubleshooting
 
 | 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 matrix by `subType` |
+| 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 |