@explorer02/cfm-survey-sdk 0.2.0 → 0.2.2

package/templates/docs/index.md

@@ -4,22 +4,36 @@
 
 Master guide for AI coding agents. Machine-readable index: `MANIFEST.json`.
 
+**Installed package path:** `node_modules/@explorer02/cfm-survey-sdk/templates/docs/` (docs ship inside `templates/` — no postinstall copy needed).
+
 ## Documentation Layout
 
 ```
-docs/
+templates/docs/              ← installed npm package layout
+packages/sdk/templates/docs/ ← monorepo layout
 ├── index.md                 ← YOU ARE HERE
 ├── MANIFEST.json            ← Phase + question-type routing (for tooling)
 ├── 00-integration/          ← Setup, hook contract, constraints
-├── 01-components/           ← Wiring blueprints (read ALL before coding)
-├── 02-reference/            ← Routing table + config-field-index (on demand)
-├── 03-ui-specs/             ← Authoritative UI specs (reference-client driven)
+├── 01-components/           ← Wiring blueprints (read per type from MANIFEST)
+├── 02-reference/            ← Routing table, exports, config-field-index
+├── 03-ui-specs/             ← Authoritative UI specs
 └── templates/
-    └── implementation_plan.md
+    ├── implementation_plan.md
+    ├── survey-inventory.schema.json
+    ├── verify-agent-build.sh
+    ├── deploy-to-aws.sh
+    ├── heatmapCoords.ts
+    └── Question.tsx           ← Canonical dispatcher (copy before building)
 ```
 
 **Import rule:** Use whatever package name appears in the project's `package.json` (`@explorer02/cfm-survey-sdk` or `@repo/sdk`).
 
+## Do Not Read
+
+- Internal SDK mapper/source paths (`packages/sdk/src/**` or `node_modules/.../src/**`)
+- `cfm-sdk init`, `survey-config.json`, or any setup wizard
+- Stale `apps/client` code without verifying type literals against `MANIFEST.json` `typeLiterals`
+
 ---
 
 ## Client Inputs (3 only)
@@ -36,7 +50,9 @@ docs/
 
 ### PHASE 0: ORIENT
 
-- Read this file and `AGENT.md`
+- Read this file and `AGENT.md`:
+  - **Monorepo:** `packages/sdk/templates/AGENT.md`
+  - **Installed npm:** `node_modules/@explorer02/cfm-survey-sdk/templates/AGENT.md`
 - Detect framework: read `package.json` — Next.js / Vite / CRA (see `00-integration/setup.md`)
 - Extract branding and layout from client prompt
 - For existing apps: read project structure; do not blindly scaffold
@@ -55,56 +71,93 @@ Ask: *"Please provide your survey instance ID (JWT token)."*
 
 ### PHASE 3: SDK CONTRACT
 
-Read: `00-integration/useSurveySDK.md`
+Read: `00-integration/client-integration-guide.md` (start here), `00-integration/question-type-sdk-matrix.md`, `00-integration/useSurveySDK.md`, `02-reference/exports.md`, `00-integration/skip-logic-and-navigation.md`, `00-integration/display-logic-and-navigation.md`, `00-integration/question-display-variants.md`, `00-integration/question-numbering.md`, `00-integration/placeholders-and-tokens.md`, `00-integration/partial-save-and-recovery.md`, `00-integration/survey-lifecycle-analytics.md`, `00-integration/end-page-logic.md`, `00-integration/answer-logic-and-navigation.md`, `00-integration/custom-field-logic-and-navigation.md`, `00-integration/progress.md`, `02-reference/value-derivation.md`
 
-Understand `useSurveySDK`, `onAction`, states. Do **not** read internal mapper/source paths.
+Understand `useSurveySDK`, `onAction`, `state.answers`. Do **not** read internal mapper/source paths.
 
 Optional: read `02-reference/routing-table.md` for type overview.
 
 ### PHASE 4: PLAN + INGEST (CRITICAL)
 
-1. Read **every** file in `01-components/` (all 14 blueprints)
-2. Copy `docs/templates/implementation_plan.md` → `./implementation_plan.md`
-3. Fill every section — do **not** invent a different structure
-4. **Auto-proceed to Phase 5** — do not wait for approval
+1. Fetch survey with `instanceId`; extract unique `question.type` values from `survey.pages`
+2. Write inventory to `implementation_plan.md` §3b (validate against `templates/survey-inventory.schema.json`)
+3. Read **always**: `component-checklist.md`, `00-integration/question-type-sdk-matrix.md`, `03-ui-specs/00-question-shell.md`, `03-ui-specs/12-survey-chrome.md`, `01-components/01-survey-page.md`, `01-components/02-question.md`, `01-components/14-intro-page.md`, `01-components/15-end-page.md`, `01-components/16-paused-page.md`
+4. For **each type in the survey**, read MANIFEST `questionTypes.{type}` → blueprint + reference + uiSpec; cross-check the matching row in `question-type-sdk-matrix.md`
+5. When config flags match MANIFEST `sharedUiSpecTriggers` (e.g. `gridLayout:dropdown`, `displayStyle:graphics`) → read matching `03-ui-specs/shared/` specs
+6. Copy `docs/templates/implementation_plan.md` → `./implementation_plan.md` and fill every section
+7. Copy `docs/templates/Question.tsx` as the dispatcher starting point
+8. **Auto-proceed to Phase 5** — do not wait for approval
 
-For each question type in the fetched survey, also read matching docs from `02-reference/question-types/` (see `MANIFEST.json` or `02-reference/routing-table.md`).
+**Fallback:** If survey fetch fails, read all `01-components/*.md` blueprints before coding.
 
 ### PHASE 5: BUILD
 
-Read: `00-integration/constraints.md`
+Read: `00-integration/constraints.md`, `00-integration/component-checklist.md`, `00-integration/question-type-sdk-matrix.md`
 
-For each question in `state.currentQuestions`:
+Create all required scale component files **before** wiring `Question.tsx`. For each question in the survey:
 
-1. Read `02-reference/question-types/{type}.md` for data shape
-2. Read `03-ui-specs/{NN}-{type}.md` (use `MANIFEST.json` `uiSpecs`; split matrix by `subType`)
-3. If `matrixFormat`, `buttonType`, or `sliderType` is present → read `03-ui-specs/shared/` specs
+1. Read the matching row in `question-type-sdk-matrix.md` (answer shape, visibility helper, performance)
+2. Read `02-reference/question-types/` doc for data shape (MANIFEST `reference`)
+2. Read matching `03-ui-specs/` (MANIFEST `uiSpec`)
+3. If `gridLayout`, `displayStyle`, or `statementLayout` triggers shared specs → read `03-ui-specs/shared/`
 4. Cross-check `02-reference/config-field-index.md` for every non-default field
-5. Match reference client behavior in `apps/client/src/components/` when available
+5. Implement per ui-spec — trust SDK Integration Checklist in blueprint/reference + `templates/Question.tsx` + exported SDK types + `02-reference/value-derivation.md`
 
 Implement components per blueprints + UI specs. Use exported types:
 
 ```typescript
-import { useSurveySDK, ACTIONS, type SurveyAction } from '@explorer02/cfm-survey-sdk';
+import { useSurveySDK, ACTIONS, QUESTION_TYPE, type SurveyAction } from '@explorer02/cfm-survey-sdk';
 ```
 
+**Dispatch on flat `question.type` only** — **11** `QUESTION_TYPE` literals, no `subType`. See `MANIFEST.json` `typeLiterals`.
+
+**AWS deploy prep (when client prompt mentions AWS / CloudFront / S3 / EC2 / Sprinklr):** apply Next.js static export config **during this phase**, not at deploy time. Read `00-integration/setup.md#nextjs-aws-static-export` and `00-integration/aws-deploy.md` § Build Config. Fill `implementation_plan.md` §8.
+
 ### PHASE 6: VERIFY
 
 Read: `00-integration/constraints.md` (troubleshooting)
 
+Run: `bash templates/verify-agent-build.sh` (from project root, after copying script if needed)
+
 Checklist:
 
-- [ ] `Question.tsx` switch covers all 12 `question.type` values
+- [ ] `Question.tsx` copied from `docs/templates/Question.tsx` — covers all **11** `question.type` values
+- [ ] Each matrix variant routes by its own type literal (`CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX`) — **no `subType`**
+- [ ] All scale components from `component-checklist.md` exist for types in survey
+- [ ] **Zero stub text:** `grep -r "not yet implemented" src/ components/ app/` returns no matches
 - [ ] Every question wrapper has `id={question.id}`
-- [ ] No imports from `@explorer02/cfm-survey-sdk/src/...`
-- [ ] `SurveyPage` handles loading / error / empty / submitted / active
+- [ ] No imports from `@explorer02/cfm-survey-sdk/src/...` or `@repo/sdk/src/...`
+- [ ] `SurveyPage` handles loading / error / empty / all `state.phase` values / active content
+- [ ] Hook uses `state.answers`, `state.canGoBack`, `state.primaryButtonType`, and `payload.answerValue`
+- [ ] Stable `customFieldValues` ref when survey uses custom-field logic; passed to hook and `Question` visibility helpers
+- [ ] `SURVEY_PLACEHOLDERS` stable ref; `surveyOptions` in `useMemo` (see `placeholders-and-tokens.md`)
+- [ ] `SCROLL` + `RECORD_QUESTION_VIEW` lifecycle effects wired (see `survey-lifecycle-analytics.md`)
+- [ ] Monorepo: `packages/sdk` built before client dev (`npm run build`)
 - [ ] `npm run build` exits 0
+- [ ] **AWS intent:** `out/index.html` exists; file count ≤ 500; Next.js static export configured (`output: export`, `assetPrefix: "./"`)
 
 ### PHASE 7: DEPLOY (INPUT 3)
 
 Ask: *"Your survey is built and verified. Ready to deploy?"*
 
-If yes: `npx cfm-sdk deploy` (preferred) or `npx vercel --prod --yes`
+**Route by client prompt** (see MANIFEST `deployTargets` and `phases[7].selectTargetFromPrompt`):
+
+| Prompt mentions | Target | Action |
+|-----------------|--------|--------|
+| AWS, CloudFront, S3, EC2, Sprinklr | **AWS** | Read `00-integration/aws-deploy.md`; set env vars; run 3-channel deploy or `bash templates/deploy-to-aws.sh` |
+| Vercel or unspecified (default) | **Vercel** | `npx cfm-sdk deploy` (requires `VERCEL_TOKEN` or Vercel CLI) |
+
+**AWS env vars (dev machine):**
+
+```bash
+export CFM_INSTANCE_ID="<same JWT as SurveyPage>"
+export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+export OUT_DIR="<absolute path to out/ or dist/>"
+```
+
+**AWS success:** print live CloudFront HTTPS URL from `/deploy/complete`; ask client to open in browser.
+
+**Vercel success:** CLI prints production URL.
 
 ---
 
@@ -112,9 +165,11 @@ If yes: `npx cfm-sdk deploy` (preferred) or `npx vercel --prod --yes`
 
 | When | Read |
 |------|------|
-| Always first | `index.md`, `00-integration/setup.md`, `00-integration/useSurveySDK.md`, `00-integration/constraints.md` |
-| Before any React code | All `01-components/*.md` |
-| On demand | `02-reference/question-types/<type>.md` for types in survey |
-| Before building each question | `03-ui-specs/` per `MANIFEST.uiSpecs` |
+| Always first | `index.md`, `00-integration/client-integration-guide.md`, `00-integration/question-type-sdk-matrix.md`, `00-integration/setup.md`, `00-integration/useSurveySDK.md`, `00-integration/constraints.md` |
+| Lifecycle & placeholders | `00-integration/survey-lifecycle-analytics.md`, `00-integration/placeholders-and-tokens.md`, `00-integration/partial-save-and-recovery.md` |
+| Skip logic & progress | `00-integration/skip-logic-and-navigation.md`, `00-integration/display-logic-and-navigation.md`, `00-integration/question-display-variants.md`, `00-integration/question-numbering.md`, `00-integration/end-page-logic.md`, `00-integration/answer-logic-and-navigation.md`, `00-integration/custom-field-logic-and-navigation.md`, `00-integration/progress.md` |
+| Before any React code | `component-checklist.md`, `templates/Question.tsx`, MANIFEST `readAlways` docs |
+| After instanceId fetch | Per-type docs from MANIFEST `questionTypes` (blocking: `CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX`, `SLIDER_MATRIX`, `FILE_UPLOAD`) |
 | Config audit | `02-reference/config-field-index.md` |
-| Tooling | `MANIFEST.json`, `templates/implementation_plan.md` |
+| AWS deploy | `00-integration/aws-deploy.md`, `setup.md#nextjs-aws-static-export`, `templates/deploy-to-aws.sh` |
+| Tooling | `MANIFEST.json`, `templates/implementation_plan.md`, `templates/survey-inventory.schema.json` |

package/templates/docs/templates/Question.tsx

@@ -0,0 +1,310 @@
+/**
+ * CANONICAL QUESTION DISPATCHER TEMPLATE
+ *
+ * Agents: copy this file to your project's components folder (e.g. src/components/Question.tsx).
+ * Covers all 11 QUESTION_TYPE literals — see question-type-sdk-matrix.md for per-type wiring.
+ * Route on `question.type` / `QUESTION_TYPE` only — no subType.
+ *
+ * Replace @explorer02/cfm-survey-sdk with your package.json import name if different.
+ */
+'use client';
+
+import React, { useMemo } from 'react';
+import type { SurveyQuestion, AnswerValue, SurveyAnswers, CustomFieldValueMap, HeatmapAnswer, HeatmapQuestion } from '@explorer02/cfm-survey-sdk';
+import { QUESTION_TYPE, resolveSurveyQuestionPlaceholders, getVisibleMatrixItemsForAnswers, getVisibleMcqOptionsForAnswers, getVisibleRankOrderOptionsForAnswers } from '@explorer02/cfm-survey-sdk';
+import { CsatMatrixScale } from './CsatMatrixScale';
+import { SliderMatrixScale } from './SliderMatrixScale';
+import { LikertMatrixScale } from './LikertMatrixScale';
+import { FileUploadScale } from './FileUploadScale';
+import { HeatmapScale } from './HeatmapScale';
+import { RankOrderScale } from './RankOrderScale';
+import RatingScale from './RatingScale';
+
+type QuestionProps = {
+  question: SurveyQuestion;
+  selectedValue?: AnswerValue;
+  validationError?: string;
+  allAnswers: SurveyAnswers;
+  allQuestions: SurveyQuestion[];
+  customFieldValues?: CustomFieldValueMap;
+  onSelect: (answerValue: AnswerValue) => void;
+};
+
+export default function Question({
+  question,
+  selectedValue,
+  validationError,
+  allAnswers,
+  allQuestions,
+  customFieldValues = {},
+  onSelect,
+}: QuestionProps) {
+  const questionsById = useMemo(
+    () => new Map(allQuestions.map(q => [q.id, q])),
+    [allQuestions]
+  );
+
+  const displayQuestionText = useMemo(
+    () => resolveSurveyQuestionPlaceholders(question.questionText, allAnswers, questionsById),
+    [question.questionText, allAnswers, questionsById]
+  );
+
+  const displayQuestionDescription = useMemo(
+    () =>
+      question.questionDescription
+        ? resolveSurveyQuestionPlaceholders(question.questionDescription, allAnswers, questionsById)
+        : undefined,
+    [question.questionDescription, allAnswers, questionsById]
+  );
+
+  const matrixQuestion = useMemo(() => {
+    const isMatrix =
+      question.type === QUESTION_TYPE.CFM_MATRIX ||
+      question.type === QUESTION_TYPE.CSAT_MATRIX ||
+      question.type === QUESTION_TYPE.RATING_MATRIX ||
+      question.type === QUESTION_TYPE.SLIDER_MATRIX;
+
+    if (!isMatrix) return question;
+
+    const { statementRows, scaleColumns } = getVisibleMatrixItemsForAnswers(
+      question,
+      allAnswers,
+      allQuestions,
+      customFieldValues
+    );
+
+    return {
+      ...question,
+      statementRows,
+      ...(question.type === QUESTION_TYPE.CSAT_MATRIX || question.type === QUESTION_TYPE.CFM_MATRIX
+        ? { scaleColumns }
+        : {}),
+    };
+  }, [question, allAnswers, allQuestions, customFieldValues]);
+
+  const visibleMcqOptions = useMemo(() => {
+    if (question.type !== QUESTION_TYPE.MCQ) return [];
+    return getVisibleMcqOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues);
+  }, [question, allAnswers, allQuestions, customFieldValues]);
+
+  const rankOrderQuestion = useMemo(() => {
+    if (question.type !== QUESTION_TYPE.RANK_ORDER) return null;
+    return {
+      ...question,
+      options: getVisibleRankOrderOptionsForAnswers(
+        question,
+        allAnswers,
+        allQuestions,
+        customFieldValues
+      ),
+    };
+  }, [question, allAnswers, allQuestions, customFieldValues]);
+
+  return (
+    <section id={question.id} className="space-y-4 rounded-xl border border-gray-200 bg-white p-6 shadow-sm">
+      <h2 className="text-lg font-medium leading-relaxed text-gray-900">
+        <span dangerouslySetInnerHTML={{ __html: displayQuestionText }} />
+        {question.required && <span className="text-red-500 ml-1">*</span>}
+      </h2>
+      {displayQuestionDescription && (
+        <div
+          className="text-sm text-gray-600 mt-2 leading-relaxed"
+          dangerouslySetInnerHTML={{ __html: displayQuestionDescription }}
+        />
+      )}
+
+      {question.type === QUESTION_TYPE.NPS_SCALE && (
+        <div className="space-y-3">
+          {(question.minLabel || question.midLabel || question.maxLabel) && (
+            <div className="relative w-full h-6 text-xs font-semibold text-gray-500">
+              <span
+                className="absolute left-0 top-0 max-w-[30%] text-left leading-tight"
+                dangerouslySetInnerHTML={{ __html: question.minLabel ?? '' }}
+              />
+              {question.midLabel && (
+                <span
+                  className="absolute top-0 -translate-x-1/2 text-center max-w-[40%] leading-tight"
+                  style={{
+                    left: `${question.midLabelIndex !== undefined && question.options.length > 1
+                      ? (question.midLabelIndex / (question.options.length - 1)) * 100
+                      : 50}%`,
+                  }}
+                  dangerouslySetInnerHTML={{ __html: question.midLabel }}
+                />
+              )}
+              <span
+                className="absolute right-0 top-0 max-w-[30%] text-right leading-tight"
+                dangerouslySetInnerHTML={{ __html: question.maxLabel ?? '' }}
+              />
+            </div>
+          )}
+          <RatingScale
+            questionId={question.id}
+            options={question.options}
+            selectedValue={selectedValue}
+            onSelect={onSelect}
+            variant="nps"
+            buttonStyle={question.buttonStyle}
+          />
+        </div>
+      )}
+
+      {question.type === QUESTION_TYPE.MCQ && (() => {
+        const effectiveValue =
+          selectedValue ??
+          (question.selectionMode === 'single'
+            ? question.defaultOptionIds?.[0]
+            : question.defaultOptionIds);
+
+        if (question.selectionMode === 'multiple') {
+          const selectedIds: string[] = Array.isArray(effectiveValue)
+            ? effectiveValue.filter((id): id is string => typeof id === 'string')
+            : typeof effectiveValue === 'string'
+              ? [effectiveValue]
+              : [];
+
+          const handleToggle = (optionId: string) => {
+            const next = selectedIds.includes(optionId)
+              ? selectedIds.filter(id => id !== optionId)
+              : question.maxSelections && selectedIds.length >= question.maxSelections
+                ? selectedIds
+                : [...selectedIds, optionId];
+            onSelect(next);
+          };
+
+          return (
+            <div className="space-y-3">
+              {visibleMcqOptions.map(option => {
+                const isSelected = selectedIds.includes(option.id);
+                return (
+                  <label
+                    key={option.id}
+                    className={`flex items-center gap-4 rounded-lg border py-4 px-5 cursor-pointer transition-all ${isSelected ? 'border-[#e20074] bg-[#fdf2f8]' : 'border-[#e5e5e5] bg-white hover:bg-gray-50/50'}`}
+                  >
+                    <input
+                      type="checkbox"
+                      name={question.id}
+                      checked={isSelected}
+                      onChange={() => handleToggle(option.id)}
+                      className="sr-only"
+                    />
+                    <span
+                      className="text-[15px] font-medium text-gray-900 leading-tight"
+                      dangerouslySetInnerHTML={{ __html: option.optionLabel }}
+                    />
+                  </label>
+                );
+              })}
+            </div>
+          );
+        }
+
+        const singleSelected = typeof effectiveValue === 'string' ? effectiveValue : undefined;
+
+        return (
+          <div className="space-y-3">
+            {visibleMcqOptions.map(option => {
+              const isSelected = singleSelected === option.id;
+              return (
+                <label
+                  key={option.id}
+                  className={`flex items-center gap-4 rounded-lg border py-4 px-5 cursor-pointer transition-all ${isSelected ? 'border-[#e20074] bg-[#fdf2f8]' : 'border-[#e5e5e5] bg-white hover:bg-gray-50/50'}`}
+                >
+                  <input
+                    type="radio"
+                    name={question.id}
+                    checked={isSelected}
+                    onChange={() => onSelect(option.id)}
+                    className="sr-only"
+                  />
+                  <span
+                    className="text-[15px] font-medium text-gray-900 leading-tight"
+                    dangerouslySetInnerHTML={{ __html: option.optionLabel }}
+                  />
+                </label>
+              );
+            })}
+          </div>
+        );
+      })()}
+
+      {question.type === QUESTION_TYPE.RANK_ORDER && rankOrderQuestion && (
+        <RankOrderScale
+          question={rankOrderQuestion}
+          selectedValue={
+            typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue)
+              ? selectedValue
+              : undefined
+          }
+          onSelect={onSelect}
+        />
+      )}
+
+      {question.type === QUESTION_TYPE.TEXTFIELD && (
+        <textarea
+          rows={question.inputVariant === 'long' ? 4 : 1}
+          value={(selectedValue as string) ?? ''}
+          onChange={e => onSelect(e.target.value)}
+          placeholder={question.placeholder || 'Type your response here...'}
+          className="w-full rounded border border-gray-300 p-4 text-sm outline-none focus:border-[#e20074]"
+        />
+      )}
+
+      {question.type === QUESTION_TYPE.CFM_MATRIX && (
+        <LikertMatrixScale
+          question={matrixQuestion as typeof question & { type: typeof QUESTION_TYPE.CFM_MATRIX }}
+          selectedValue={typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue) ? selectedValue : {}}
+          onSelect={onSelect}
+        />
+      )}
+
+      {(question.type === QUESTION_TYPE.CSAT_MATRIX ||
+        question.type === QUESTION_TYPE.RATING_MATRIX) && (
+        <CsatMatrixScale
+          question={matrixQuestion as Extract<SurveyQuestion, { type: typeof QUESTION_TYPE.CSAT_MATRIX | typeof QUESTION_TYPE.RATING_MATRIX }>}
+          selectedValue={typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue) ? selectedValue : {}}
+          onSelect={onSelect}
+        />
+      )}
+
+      {question.type === QUESTION_TYPE.SLIDER_MATRIX && (
+        <SliderMatrixScale
+          question={matrixQuestion as typeof question & { type: typeof QUESTION_TYPE.SLIDER_MATRIX }}
+          selectedValue={typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue) ? selectedValue : {}}
+          onSelect={onSelect}
+        />
+      )}
+
+      {question.type === QUESTION_TYPE.FILE_UPLOAD && (
+        <FileUploadScale question={question} selectedValue={selectedValue} onSelect={onSelect} />
+      )}
+
+      {question.type === QUESTION_TYPE.HEATMAP && (
+        <HeatmapScale
+          question={question as HeatmapQuestion}
+          selectedValue={Array.isArray(selectedValue) ? (selectedValue as HeatmapAnswer) : undefined}
+          onSelect={onSelect}
+        />
+      )}
+
+      {question.type === QUESTION_TYPE.TEXT_AND_MEDIA && question.media?.url && (
+        <div className={`mt-4 flex w-full ${question.media.alignment?.includes('CENTER') ? 'justify-center' : question.media.alignment?.includes('RIGHT') ? 'justify-end' : 'justify-start'}`}>
+          <div style={{ width: question.media.size ? `${question.media.size}%` : '100%' }}>
+            {question.media.mimeType?.startsWith('video/') || question.media.mimeType === 'VIDEO' ? (
+              <video controls src={question.media.url} className="max-w-full rounded-md" />
+            ) : (
+              <img src={question.media.url} alt={question.media.title || ''} className="max-w-full rounded-md" />
+            )}
+            {question.media.title && <p className="text-sm text-gray-500 text-center mt-2">{question.media.title}</p>}
+          </div>
+        </div>
+      )}
+
+      {validationError && (
+        <div className="mt-4 rounded border border-gray-800 bg-gray-200 py-3 px-4">
+          <p className="text-sm font-bold text-gray-900">{validationError}</p>
+        </div>
+      )}
+    </section>
+  );
+}

package/templates/docs/templates/deploy-to-aws.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Deploy static survey UI to AWS via EC2 middle API (S3 + CloudFront).
+# Prerequisites: CFM_INSTANCE_ID, CFM_DEPLOY_API_BASE, OUT_DIR set in environment.
+# Run from project root after a successful static build.
+set -euo pipefail
+
+: "${CFM_INSTANCE_ID:?Set CFM_INSTANCE_ID to the same JWT as SurveyPage SURVEY_INSTANCE_ID}"
+: "${CFM_DEPLOY_API_BASE:?Set CFM_DEPLOY_API_BASE (e.g. http://43.204.26.213:3000)}"
+: "${OUT_DIR:?Set OUT_DIR to absolute path of out/ (Next.js) or dist/ (Vite)}"
+
+if [ ! -f "$OUT_DIR/index.html" ]; then
+  echo "FAIL: $OUT_DIR/index.html not found — run build first"
+  exit 1
+fi
+
+FILE_COUNT=$(find "$OUT_DIR" -type f | wc -l | tr -d ' ')
+if [ "$FILE_COUNT" -gt 500 ]; then
+  echo "FAIL: $FILE_COUNT files exceeds API limit of 500"
+  exit 1
+fi
+
+echo "=== AWS Deploy ==="
+echo "API: $CFM_DEPLOY_API_BASE"
+echo "OUT: $OUT_DIR ($FILE_COUNT files)"
+echo
+
+HEALTH=$(curl -s "$CFM_DEPLOY_API_BASE/health")
+echo "Health: $HEALTH"
+echo
+
+python3 <<'PY' > /tmp/deploy-manifest.json
+import json, os, mimetypes
+from pathlib import Path
+out = Path(os.environ["OUT_DIR"])
+files = []
+for path in sorted(out.rglob("*")):
+    if not path.is_file():
+        continue
+    rel = path.relative_to(out).as_posix()
+    mime, _ = mimetypes.guess_type(rel)
+    files.append({
+        "path": rel,
+        "contentType": mime or "application/octet-stream",
+        "sizeBytes": path.stat().st_size,
+    })
+print(json.dumps({"files": files}))
+print(f"files: {len(files)}", file=__import__('sys').stderr)
+PY
+
+echo "Channel 1: deploy/start"
+curl -s -X POST "$CFM_DEPLOY_API_BASE/deploy/start" \
+  -H "Authorization: Bearer $CFM_INSTANCE_ID" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/deploy-manifest.json \
+  | tee /tmp/deploy-start.json
+echo
+
+if ! python3 -c "import json; json.load(open('/tmp/deploy-start.json'))['deployId']" 2>/dev/null; then
+  echo "FAIL: deploy/start did not return deployId"
+  exit 1
+fi
+
+echo "Channel 2: S3 uploads"
+python3 <<'PY'
+import json, os, subprocess
+from pathlib import Path
+
+out = Path(os.environ["OUT_DIR"])
+start = json.load(open("/tmp/deploy-start.json"))
+manifest = {f["path"]: f["contentType"] for f in json.load(open("/tmp/deploy-manifest.json"))["files"]}
+failed = []
+
+for item in start["uploads"]:
+    path = item["path"]
+    url = item["uploadUrl"]
+    mime = manifest.get(path, "application/octet-stream")
+    proc = subprocess.run(
+        ["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}",
+         "-X", "PUT", url, "-H", f"Content-Type: {mime}",
+         "--data-binary", f"@{out / path}"],
+        capture_output=True, text=True,
+    )
+    code = proc.stdout.strip()
+    mark = "OK" if code == "200" else "FAIL"
+    print(f"{mark} {code} {path}")
+    if code != "200":
+        failed.append(path)
+
+if failed:
+    print(f"\n{len(failed)} failed — rerun deploy (presigned URLs expire)")
+    raise SystemExit(1)
+print("\nAll uploads succeeded")
+PY
+
+echo
+echo "Channel 3: deploy/complete"
+DEPLOY_ID=$(python3 -c "import json; print(json.load(open('/tmp/deploy-start.json'))['deployId'])")
+curl -s -X POST "$CFM_DEPLOY_API_BASE/deploy/complete" \
+  -H "Authorization: Bearer $CFM_INSTANCE_ID" \
+  -H "Content-Type: application/json" \
+  -d "{\"deployId\":\"$DEPLOY_ID\"}" \
+  | tee /tmp/deploy-complete.json
+echo
+
+LIVE_URL=$(python3 -c "import json; print(json.load(open('/tmp/deploy-complete.json'))['url'])")
+echo "Live URL: $LIVE_URL"
+HTTP=$(curl -s -o /dev/null -w "%{http_code}" "$LIVE_URL")
+echo "Verify HTTP: $HTTP"
+if [ "$HTTP" != "200" ]; then
+  echo "WARN: index.html returned $HTTP — check CloudFront path or invalidation"
+  exit 1
+fi
+
+echo "=== Deploy complete ==="

package/templates/docs/templates/heatmapCoords.ts

@@ -0,0 +1,58 @@
+/**
+ * Portable heatmap coordinate helpers for agent projects.
+ *
+ * Copy to e.g. src/lib/heatmapCoords.ts — do not import from monorepo-only paths.
+ * See 01-components/17-heatmap-scale.md and question-type-sdk-matrix.md#heatmap.
+ */
+import type { MouseEvent } from 'react';
+import type { HeatmapClickPoint } from '@explorer02/cfm-survey-sdk';
+
+export const SPOT_HIT_RADIUS_PX = 14;
+
+export function roundCoordinate(value: number): number {
+  return Math.round(value * 100000) / 100000;
+}
+
+export function getNormalizedClickFromImage(
+  event: MouseEvent,
+  imageElement: HTMLImageElement
+): { x: number; y: number } {
+  const rect = imageElement.getBoundingClientRect();
+  if (rect.width === 0 || rect.height === 0) {
+    return { x: 0, y: 0 };
+  }
+
+  const x = (event.clientX - rect.left) / rect.width;
+  const y = (event.clientY - rect.top) / rect.height;
+
+  return {
+    x: roundCoordinate(Math.min(1, Math.max(0, x))),
+    y: roundCoordinate(Math.min(1, Math.max(0, y))),
+  };
+}
+
+export function findSpotNearClick(
+  clickX: number,
+  clickY: number,
+  spots: HeatmapClickPoint[],
+  imageRect: DOMRect
+): HeatmapClickPoint | undefined {
+  const clickPixelX = clickX * imageRect.width;
+  const clickPixelY = clickY * imageRect.height;
+
+  for (const spot of spots) {
+    const spotPixelX = spot.x * imageRect.width;
+    const spotPixelY = spot.y * imageRect.height;
+    const distance = Math.hypot(spotPixelX - clickPixelX, spotPixelY - clickPixelY);
+
+    if (distance <= SPOT_HIT_RADIUS_PX) {
+      return spot;
+    }
+  }
+
+  return undefined;
+}
+
+export function createNewSpot(x: number, y: number): HeatmapClickPoint {
+  return { id: crypto.randomUUID(), x, y };
+}