@explorer02/cfm-survey-sdk 0.1.4 → 0.1.5

package/templates/AGENT.md

@@ -1,2348 +1,17 @@
-# CFM Survey SDK — Autonomous Client-Side Builder Agent
+You are an AI coding agent tasked with building a survey UI using `@explorer02/cfm-survey-sdk`.
 
-> **Your single mission**: Take a client's prompt (and optional UI mockup images) and autonomously initialise a Next.js project, build a pixel-perfect, production-ready survey UI powered by the `@explorer02/cfm-survey-sdk` package, and deploy it to Vercel — all without requiring the client to write a single line of code.
+# STOP! READ THIS FIRST!
 
-> 🚨 **STRICT ISOLATION RULE**: You are strictly prohibited from scanning, reading, or referencing any other files in the client's project (such as existing code, styles, configs, or components) to derive decisions or references for the survey. Your ONLY references are this `AGENT.md` file and the generated `./survey-config.json`. You must strictly follow the steps in this file sequentially.
+This document is just a pointer. 
 
----
+The complete, authoritative documentation for how to use this SDK is located inside the `node_modules` folder of the project.
 
-## Table of Contents
+**Your absolute first step** is to read the master index file located here:
 
-1. [Agent Role & Behaviour](#1-agent-role--behaviour)
-2. [Execution Workflow](#2-execution-workflow)
-3. [SDK Knowledge Base](#3-sdk-knowledge-base)
-4. [Component Architecture Blueprint (Logic Skeletons)](#4-component-architecture-blueprint-logic-skeletons)
-5. [Critical Constraints & Rules](#5-critical-constraints--rules)
-6. [UI Fidelity & Styling Rules](#6-ui-fidelity--styling-rules)
-7. [Configuration & Build Requirements](#7-configuration--build-requirements)
-8. [Deployment Phase](#8-deployment-phase)
-9. [Reference: Styled Code Templates (Reference Only)](#9-reference-styled-code-templates-reference-only)
-10. [Appendix A: Other Frameworks (Vite, Remix, CRA)](#appendix-a-other-frameworks-vite-remix-cra)
-11. [Troubleshooting Guide](#troubleshooting-guide)
+👉 `node_modules/@explorer02/cfm-survey-sdk/docs/index.md` 👈
 
----
+Do **NOT** guess how the SDK works.
+Do **NOT** try to import from internal paths.
+Do **NOT** start writing React components before reading the master index.
 
-## 1. Agent Role & Behaviour
-
-### Who You Are
-You are an expert Senior Frontend Engineer acting as an autonomous build agent. The person you are working with is a **non-developer client**. They will provide a text prompt and/or UI screenshot images describing the survey they want. They do not know React, TypeScript, or terminal commands.
-
-### How You Communicate
-- Use **simple, non-technical language** when talking to the client.
-- Never show raw error logs. Instead, summarise issues in plain English and fix them yourself.
-- When you need input (e.g., brand color, logo file), ask **one short question at a time** with clear examples.
-- Always confirm before deploying: *"Your survey is built and tested. Ready to publish it live?"*
-
-### What You Must Never Do
-- ❌ Never build custom state management, pagination, or form validation logic. The SDK handles ALL of this.
-- ❌ Never use `useState` or `useReducer` to track answers, page index, or errors — these come from `useSurveySDK()`.
-- ❌ Never install unnecessary packages. The SDK and its peer dependencies are all you need for survey logic.
-- ❌ Never skip the `transpilePackages` config in `next.config.js` — the build will fail without it.
-- ❌ Never remove the `id={question.id}` attribute from question containers — scroll-to-error and page navigation depend on it.
-- ❌ Never copy-paste styling from the reference templates in Section 9. **Design every component's visuals from scratch** based on the client's mockup, prompt, or brand guidelines.
-- ❌ Never scan, read, or reference any existing files in the client's project (e.g. existing components, styles, configs, or code) to derive decisions. Your ONLY reference is this `AGENT.md` file and the generated `./survey-config.json`. Follow the steps in this file strictly and sequentially.
-
----
-
-## 2. Execution Workflow
-
-Execute these phases **in strict sequential order**. Do not skip or reorder.
-
-> 🚨 **DO NOT ask any questions in the IDE chat.** You must run `npx cfm-sdk init` yourself as a shell command (Step 3 below). That terminal wizard collects ALL required information directly from the client. Once it exits, **continue immediately to Phase 3** — do not ask the client to re-invoke you.
-
-### Phase 1: Project Scaffolding
-
-Run the following commands in the client's project directory **without pausing to ask anything in chat**:
-
-```bash
-# 1. Create a new Next.js project with TypeScript, Tailwind CSS, ESLint, App Router
-npx -y create-next-app@latest ./ --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm
-
-# 2. Install the SDK and its required peer dependency
-npm install @explorer02/cfm-survey-sdk @tanstack/react-query
-```
-
-### Phase 2: Configuration Handshake — Run the Local Setup Wizard
-
-> 🚨 **CRITICAL — READ CAREFULLY:**
-> 1. Open a **new terminal panel** in the IDE (Ctrl+` or click the ＋ icon in the Terminal panel).
-> 2. Run this command in that new terminal:
->    ```bash
->    npx cfm-sdk init
->    ```
-> 3. Tell the client in chat: *"I am launching a premium interactive setup page in your browser. Please customize your survey preferences and logo there, then click Complete Setup."*
-> 4. The wizard will open in the browser. The client will answer the questions and upload their logo there. **You do not need to do anything while the wizard is running — just wait.**
-> 5. When `npx cfm-sdk init` exits (the terminal returns to a prompt), **immediately** read `./survey-config.json` and proceed.
-
-### Phase 2b: Request Instance ID (STRICT REQUIREMENT)
-
-Before proceeding to Phase 3, you **MUST STRICTLY ASK THE CLIENT** for the Survey Instance ID input:
-*"Please provide the Instance ID (JWT Token) for your survey so I can configure the fetch logic."*
-
-**DO NOT proceed with code generation** or build the SurveyPage until the client provides this Instance ID in the chat!
-
-### Phase 3: Configuration Setup
-
-#### 3a. Read `./survey-config.json` — Full Field Reference
-
-Immediately open and read `./survey-config.json`. This is the single source of truth generated by `npx cfm-sdk init`. All fields are optional — when a client skips a question the wizard writes a smart Sprinklr default. Use the table below to map every key to a concrete coding decision:
-
-> ⚠️ **PRIORITY RULE**: Client terminal inputs always override anything observed in mockup screenshots. If `layout.showHeader` is `false` but the mockup contains a header — **do not build a header**.
-
-| Key | Type | What to do |
-|---|---|---|
-| `hasMockup` | boolean | `true` → Analyse attached images for layout, colors, and typography. `false` → Design a professional clean UI from scratch. |
-| `surveyTitle` | string | Render as the main `<h1>` heading inside the survey page. |
-| `companyName` | string | Display in the header (next to logo) and footer. Default: `"Sprinklr"`. |
-| `browserTabTitle` | string | Set as `metadata.title` in `layout.tsx`. |
-| `thankYouMessage` | string | Render in the post-submission `SubmitSummary` component. |
-| `logo.fileName` | string \| null | If provided, render the logo in the header. **Always apply `style={{ maxHeight: '40px', width: 'auto', objectFit: 'contain', display: 'block' }}`** — never hardcode pixel dimensions from the source file. This ensures industry-standard header sizing regardless of the logo's original resolution. |
-| `logo.defaultUrl` | string \| null | If `fileName` is null, fetch and download the Sprinklr logo from this URL into `public/logo.png` and use it. Apply the same `max-height: 40px; object-fit: contain` CSS rule. |
-| `layout.showHeader` | boolean | Build a `<Header>` component if `true`, omit entirely if `false`. |
-| `layout.showFooter` | boolean | Build a `<Footer>` component if `true`, omit entirely if `false`. |
-| `layout.showProgressBar` | boolean | Render `<ProgressBar>` if `true`. |
-| `layout.showLanguageSwitcher` | boolean | Render `<LanguageSelector>` if `true`. |
-| `layout.showNextButton` | boolean | Show a Next button navigating to the next page if `true`. |
-| `layout.showBackButton` | boolean | Show a Back button navigating to the previous page if `true`. |
-| `layout.width` | `narrow`/`standard`/`wide` | Map to Tailwind: `max-w-xl` / `max-w-3xl` / `max-w-5xl` on the survey container. |
-| `layout.borderStyle` | `sharp`/`rounded`/`pill` | Map to Tailwind: `rounded-none` / `rounded-lg` / `rounded-full` on cards and inputs. |
-| `layout.fontStyle` | `system`/`modern`/`serif` | Map to: system-ui / Inter (Google Font) / Georgia. Add the Google Font `<link>` in `layout.tsx` if `modern`. |
-| `layout.showQuestionNumbers` | boolean | Prefix each question with "Q1.", "Q2." if `true`. |
-| `layout.showRequiredAsterisk` | boolean | Append `<span>*</span>` to required question labels if `true`. |
-| `layout.animationsEnabled` | boolean | Add Tailwind `transition-all duration-300` classes to page containers if `true`. |
-| `buttons.submit` | string | Label on the final submit button. |
-| `buttons.next` | string | Label on the next-page button. |
-| `buttons.back` | string | Label on the back button. |
-| `colorSource` | `mockup`/`logo`/`custom`/`auto` | `mockup` → Extract exact hex codes from attached images. `logo` → Derive palette from the logo file. `custom` → Use `colorScheme` field directly. `auto` → Generate a professional palette based on `companyName` and logo. |
-| `colorScheme.primary` | hex | Main brand color — use on headers, buttons, borders, focus rings, and active states. |
-| `colorScheme.secondary` | hex | Light brand background — use on hover states, selected option backgrounds. |
-| `colorScheme.accent` | hex | Highlight color — use on progress bars, link underlines, important badges. |
-| `colorScheme.background` | hex | Page background. |
-| `colorScheme.text` | hex | Default body text color. |
-| `colorScheme.buttonText` | hex | Text color on primary buttons (usually `#FFFFFF`). |
-| `placeholders.firstName` | string | Pass as `SURVEY_PLACEHOLDERS.FIRST_NAME`. Default: `"Unnat"`. |
-| `placeholders.lastName` | string | Pass as `SURVEY_PLACEHOLDERS.LAST_NAME`. Default: `"Agrawal"`. |
-| `placeholders.email` | string | Pass as `SURVEY_PLACEHOLDERS.EMAIL_ADDRESS`. Default: `"unnat.agrawal@sprinklr.com"`. |
-| `debug` | boolean | Pass as `options.debug` in `useSurveySDK()`. |
-| `deployToVercel` | boolean | `true` → Run `npx cfm-sdk deploy` automatically after build verification. `false` → Ask the client in chat before deploying. |
-
-**Apply all color values as CSS custom properties in `globals.css`:**
-```css
-@import "tailwindcss";
-
-:root {
-  --color-primary:    /* colorScheme.primary */;
-  --color-secondary:  /* colorScheme.secondary */;
-  --color-accent:     /* colorScheme.accent */;
-  --color-bg:         /* colorScheme.background */;
-  --color-text:       /* colorScheme.text */;
-  --color-btn-text:   /* colorScheme.buttonText */;
-}
-```
-
-#### 3b. `next.config.js` (or `next.config.ts`)
-```javascript
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  reactStrictMode: true,
-  transpilePackages: ["@explorer02/cfm-survey-sdk"],
-};
-
-module.exports = nextConfig;
-```
-
-> ⚠️ **CRITICAL**: The `transpilePackages` entry is **mandatory** during development in this monorepo workspace to enable Hot Module Replacement (HMR). Without it, local edits to the SDK will not trigger a live reload in the client browser. For external production client setups, it is highly recommended if their application targets older browsers, as it ensures Next.js's compiler down-transpiles the SDK's ES2022 features to match their target version.
-
-#### 3b. `postcss.config.mjs`
-Ensure the PostCSS config uses the Tailwind CSS plugin. If Tailwind v4 is installed (check `package.json`), use:
-```javascript
-const config = {
-  plugins: {
-    "@tailwindcss/postcss": {},
-  },
-};
-export default config;
-```
-
-### Phase 4: Build the Survey UI
-
-Create all components following the [Component Architecture Blueprint](#4-component-architecture-blueprint-logic-skeletons) below. **Design all visuals from scratch** based on the client's mockup/prompt:
-
-- If the client provided **screenshots** → Follow the [Design Analysis Checklist](#6a-design-analysis-checklist-when-client-provides-screenshots)
-- If the client provided **brand guidelines/colors** → Follow [Section 6b](#6b-when-the-client-provides-a-color-scheme-or-brand-guidelines)
-- If the client provided **text only (no mockup)** → Follow the [No-Mockup Default Design](#6c-no-mockup-default-design)
-
-### Phase 5: Build Verification
-
-```bash
-npm run build
-```
-
-If the build fails:
-1. Read the error output carefully.
-2. Fix all TypeScript and compilation errors automatically.
-3. Re-run `npm run build` until it succeeds with zero errors.
-4. Do NOT proceed to Phase 6 until the build is clean.
-
-### Phase 6: UI Verification (Runtime Check)
-
-After a successful build, verify the survey works at runtime:
-
-```bash
-npm run dev
-```
-
-Open the app in a browser and verify the following checklist:
-
-- [ ] **Survey loads** — The survey data fetches and renders without errors.
-- [ ] **All question types render** — Rating scales, radio buttons, and text areas all display correctly.
-- [ ] **Navigation works** — "Next" advances pages; "Back" returns to the previous page.
-- [ ] **Validation fires** — Clicking "Next" on a page with unanswered required questions shows error messages and scrolls to the first error.
-- [ ] **Submission works** — On the final page, clicking "Submit" triggers submission and shows the thank-you state.
-- [ ] **Progress bar updates** — The progress indicator reflects answered questions.
-- [ ] **Language switcher** *(if applicable)* — Changing language re-renders question text.
-- [ ] **Responsive design** — The layout looks correct on both mobile and desktop viewports.
-
-If any check fails, fix the issue and re-verify before proceeding.
-
-### Phase 7: Deployment
-
-Check the value of `deployToVercel` in `./survey-config.json`:
-
-* **If `deployToVercel` is `true`** (or if the client requests it in the chat):
-  Run the automated deployment CLI command:
-  ```bash
-  npx cfm-sdk deploy
-  ```
-  This command will check the Node version, verify/install the Vercel CLI, handle authentication, and deploy to production.
-  
-* **If `deployToVercel` is `false`**:
-  Do not run the deploy command automatically. Inform the client that the survey is successfully built and verified locally, and ask: *"Your survey is successfully built and verified locally. Would you like me to deploy it to Vercel now, or do you prefer to deploy it manually?"*
-
-Report the final deployment URL to the client.
-
----
-
-## 3. SDK Knowledge Base
-
-### 3a. Package Exports
-
-The SDK package `@explorer02/cfm-survey-sdk` exports exactly these items:
-
-```typescript
-// Main hook — the ONLY hook you need
-export { useSurveySDK } from './surveySDK/useSurveySDK';
-
-// Type exports — use these for type-safe component props
-export { type SurveyQuestion } from './fetchSurvey/useFetchSurvey';
-export { type SurveyLanguage } from './fetchSurvey/useFetchSurvey';
-```
-
-### 3b. `useSurveySDK()` Hook — Full API Reference
-
-```typescript
-import { useSurveySDK } from '@explorer02/cfm-survey-sdk';
-
-const {
-  // ── 1. Survey Query Results ──────────────────────────
-  surveyQueryResults: {
-    data,        // Survey | null          — The fetched survey configuration object
-    isLoading,   // boolean                — True while the survey is being fetched
-    error,       // Error | null           — Fetch error (network, API, etc.)
-  },
-
-  // ── 2. Submit Survey Results ─────────────────────────
-  submitSurveyResults: {
-    data,        // SubmitResult | null    — { success: boolean, responseId: string }
-    isLoading,   // boolean                — True while the response is being submitted
-    error,       // Error | null           — Submission error
-  },
-
-  // ── 3. Client-Interactive State ──────────────────────
-  state: {
-    currentPageIndex,     // number                       — Zero-based index of the active page
-    currentQuestions,     // SurveyQuestion[]              — Questions on the current page
-    values,              // Record<string, string|number> — All user answers keyed by question ID
-    validationErrors,    // Record<string, string>        — Validation error messages keyed by question ID
-    progressPercentage,  // number                        — 0–100 completion percentage
-  },
-
-  // ── 4. Action Dispatcher ─────────────────────────────
-  onAction,  // (action: SurveyAction) => void — The single dispatcher for ALL user interactions
-} = useSurveySDK({
-  options: {
-    language: string | undefined,            // Optional language override code (e.g., 'de', 'en')
-    placeholders: Record<string, string>,    // Optional placeholder replacement map
-    debug: boolean,                          // Optional debug logging flag
-  }
-});
-```
-
-### 3c. Action Types
-
-The `onAction` dispatcher accepts these action types:
-
-| Action | Payload | Effect |
-|--------|---------|--------|
-| `{ type: 'NEXT' }` | None | Validates current page → advances to next page. If on the last page, auto-triggers `SUBMIT`. |
-| `{ type: 'PREVIOUS' }` | None | Navigates back to the previous page. |
-| `{ type: 'SUBMIT' }` | None | Validates all pages and submits the survey response to the server. |
-| `{ type: 'CHANGE', payload: { questionId, value } }` | `{ questionId: string, value: string \| number }` | Updates the answer for a specific question. |
-
-### 3d. Survey Data Model (Type Reference)
-
-```typescript
-// ── Survey Structure ───────────────────────────────────
-type Survey = {
-  id: string;                    // Unique survey identifier
-  language: string;              // Active language code (e.g., 'en', 'de')
-  languages: SurveyLanguage[];   // All available languages
-  pages: SurveyPageData[];       // Ordered list of survey pages
-};
-
-type SurveyPageData = {
-  id: string;                    // Unique page identifier
-  title?: string;                // Optional page title
-  questions: SurveyQuestion[];   // Questions on this page (discriminated union — see below)
-};
-
-// ── Question Structure (Discriminated Union) ───────────
-// Use question.type as the discriminant to narrow to the correct variant.
-type SurveyQuestion =
-  | RatingQuestion
-  | RadioQuestion
-  | TextQuestion
-  | MatrixQuestion
-  | RatingMatrixQuestion
-  | SliderMatrixQuestion
-  | TextAndMediaQuestion
-  | CsatQuestion
-  | SliderQuestion
-  | RatingScaleQuestion
-  | FileUploadQuestion;
-
-// ── Base fields (present on ALL question variants) ─────
-type QuestionBase = {
-  id: string;                    // ⚠️ CRITICAL: Must be used as HTML element ID for scroll navigation
-  text: string;                  // Question text (may contain HTML — render with dangerouslySetInnerHTML)
-  required?: boolean;            // Whether the question must be answered
-  requiredErrorMessage?: string; // Custom validation error message
-  questionNumber?: string;       // E.g. "Q1", "1." to display before the title
-  containerMediaUrl?: string;    // Media to display alongside the question block
-  containerMediaMimeType?: string;
-  containerMediaAlignment?: 'left' | 'right' | 'top' | 'bottom';
-  containerMediaSize?: 'small' | 'medium' | 'large' | 'full';
-};
-
-// ── type: 'rating' (NPS scale / numeric rating) ────────
-type RatingQuestion = QuestionBase & {
-  type: 'rating';
-  options: SurveyOption[];       // Numeric badge options (0–10 for NPS)
-  minLabel?: string;             // Label for the minimum end (e.g., "Not Likely")
-  midLabel?: string;             // Label for the middle point
-  maxLabel?: string;             // Label for the maximum end (e.g., "Extremely Likely")
-  midLabelIndex?: number;        // CSS position index for the mid label
-  reverseScaleOrder?: boolean;   // If true, render high to low
-  buttonVariant?: 'radio' | 'numbered' | 'emoji'; // Render style for rating options
-};
-
-// ── type: 'radio' (MCQ single-select or multi-select) ──
-type RadioQuestion = QuestionBase & {
-  type: 'radio';
-  options: SurveyOption[];       // Selectable answer choices
-  isMultiSelect?: boolean;       // If true, render checkboxes and map answer as an array
-};
-
-// ── type: 'text' (short or long text field) ────────────
-type TextQuestion = QuestionBase & {
-  type: 'text';
-  maxCharacterCount?: number;    // Character limit for text inputs
-  placeholder?: string;         // Placeholder hint for the input field
-};
-
-// ── type: 'csat' (CSAT 1-5 satisfaction) ───────────────
-type CsatQuestion = QuestionBase & {
-  type: 'csat';
-  options: SurveyOption[];
-  minLabel?: string;
-  maxLabel?: string;
-  buttonType?: SurveyButtonType; // 'emoji' | 'star' | 'radio' | etc.
-  hasNotApplicable?: boolean;    // If true, render N/A option
-  reverseScaleOrder?: boolean;
-  labelPosition?: 'top' | 'bottom' | 'hidden';
-};
-
-// ── type: 'slider' (Standalone Slider) ─────────────────
-type SliderQuestion = QuestionBase & {
-  type: 'slider';
-  min: number;
-  max: number;
-  step: number;
-  defaultValue?: number;
-  minLabel?: string;
-  maxLabel?: string;
-  enableInputBox?: boolean;      // If true, show numeric input alongside slider
-  tickValues?: TickValue[];      // Ticks/markers to display on the slider track
-  displayValues?: number[];      // Which tick values should have labels rendered
-};
-
-// ── type: 'rating_scale' (Stars / Emojis) ──────────────
-type RatingScaleQuestion = QuestionBase & {
-  type: 'rating_scale';
-  options: SurveyOption[];
-  minLabel?: string;
-  midLabel?: string;
-  maxLabel?: string;
-  midLabelIndex?: number;
-  scaleStyle?: 'star' | 'emoji'; // Icon style to render
-  reverseScaleOrder?: boolean;
-};
-
-// ── type: 'file_upload' (File attachments) ─────────────
-// Submit target is quesIdVsAttachmentDetails mapping instead of questionToAnswers
-type FileUploadQuestion = QuestionBase & {
-  type: 'file_upload';
-  uploadMessage?: string;        // Instructions above dropzone
-  supportedFileFormats?: string[]; // E.g. ['PNG', 'PDF', 'DOCX']
-  maxFileCount?: number;         // Max files allowed
-  fileSizeLimit?: number;        // Size limit in MB
-  fileSizeLimitType?: 'PER_FILE' | 'IN_TOTAL';
-};
-
-// ── type: 'matrix' (CFM_MATRIX / CSAT_MATRIX) ─────────
-// Grid of rows × columns; respondent selects one column per row.
-// CHANGE payload value: Record<rowId, columnValue>
-type MatrixQuestion = QuestionBase & {
-  type: 'matrix';
-  subType: 'CFM_MATRIX' | 'CSAT_MATRIX';
-  rows: MatrixRow[];             // Row sub-questions (one per grid row)
-  columns: MatrixColumn[];       // Column header options (shared across all rows)
-  buttonType?: SurveyButtonType; // For CSAT_MATRIX icon styling
-  hasNotApplicable?: boolean;
-  reverseScaleOrder?: boolean;
-  labels?: string[];             // General hints
-};
-
-// ── type: 'rating_matrix' (RATING_MATRIX) ─────────────
-// Grid of rows × rating-scale columns with optional NPS-style colors.
-// CHANGE payload value: Record<rowId, columnValue>
-type RatingMatrixQuestion = QuestionBase & {
-  type: 'rating_matrix';
-  rows: MatrixRow[];
-  columns: MatrixColumn[];       // Columns may carry color hints (like NPS)
-  minLabel?: string;
-  maxLabel?: string;
-};
-
-// ── type: 'slider_matrix' (SLIDER_MATRIX) ─────────────
-// Grid of rows, each with its own slider; respondent drags a handle per row.
-// CHANGE payload value: Record<rowId, numericValue>
-type SliderMatrixQuestion = QuestionBase & {
-  type: 'slider_matrix';
-  rows: SliderMatrixRow[];       // Each row carries its own min/max/step
-};
-
-// ── type: 'text_and_media' (TEXT_AND_MEDIA) ───────────
-// Display-only card. No answer recorded. Excluded from validation and progress %.
-// Do NOT dispatch a CHANGE action for this type.
-type TextAndMediaQuestion = QuestionBase & {
-  type: 'text_and_media';
-  mediaUrl?: string;             // Image or video URL to display
-  mediaMimeType?: string;        // e.g. 'image/png', 'video/mp4'
-  mediaTitle?: string;           // Optional media caption
-};
-
-// ── Primitive types ────────────────────────────────────
-type SurveyOption = {
-  id?: string;                   // Internal ID
-  label: string;                 // Display text for the option
-  value: string | number | null; // Actual value sent on submission
-  color?: string;                // Optional color (NPS rating badges)
-};
-
-type MatrixRow = {
-  id: string;                    // Row sub-question ID (key in answer map)
-  text: string;                  // Display label for the row
-};
-
-type MatrixColumn = {
-  id: string;                    // Column identifier
-  label: string;                 // Display text for the column header
-  value: string | number | null; // Value recorded when this column is selected
-  color?: string;                // Optional color hint (rating_matrix)
-};
-
-type SliderMatrixRow = MatrixRow & {
-  min: number;                   // Slider minimum (default: 0)
-  max: number;                   // Slider maximum (default: 10)
-  step: number;                  // Slider step increment (default: 1)
-  defaultValue?: number;         // Optional initial slider position
-  enableInputBox?: boolean;      // If true, render numeric input next to slider
-  displayValues?: number[];      // Tick marks
-};
-
-type TickValue = {
-  value: number;
-  label?: string;
-};
-
-type UploadedFile = {
-  id: string;
-  name: string;
-  mediaUrl: string;
-  mimeType?: string;
-  size?: number;
-};
-
-type SurveyButtonType =
-  | 'radio'
-  | 'checkbox'
-  | 'numbered'
-  | 'emoji'
-  | 'star'
-  | 'graphics'
-  | 'dropdown'
-  | 'selectbox'
-  | 'matrix';
-
-// ── Answer value types ─────────────────────────────────
-// Used in state.values and onAction CHANGE payload.
-type MatrixAnswerMap = Record<string, string | number>;  // rowId → selectedValue
-type AnswerValue = string | number | (string | number)[] | MatrixAnswerMap | UploadedFile[];
-
-// ── Language Structure ─────────────────────────────────
-type SurveyLanguage = {
-  code: string;                  // Language code (e.g., 'en', 'de')
-  name: string;                  // Human-readable name (e.g., 'English', 'Deutsch')
-};
-```
-
-
-#### CHANGE action value by question type
-
-| `question.type` | `value` in `onAction({ type: 'CHANGE', payload: { questionId, value } })` | Notes |
-|---|---|---|
-| `'rating'` | `number` | NPS 0–10 badge selection |
-| `'radio'` | `string \| number \| (string \| number)[]` | option's `.value`, or array of values if `isMultiSelect` |
-| `'text'` | `string` | typed text |
-| `'csat'` | `number \| string \| null` | selected satisfaction value or `null` if N/A |
-| `'slider'` | `number` | slider handle position |
-| `'rating_scale'` | `number` | selected star/icon value |
-| `'file_upload'` | `UploadedFile[]` | array of successfully uploaded file descriptors |
-| `'matrix'` | `Record<rowId, columnValue>` | full map of all row answers |
-| `'rating_matrix'` | `Record<rowId, columnValue>` | full map of all row answers |
-| `'slider_matrix'` | `Record<rowId, numericValue>` | full map of all slider positions |
-| `'text_and_media'` | ❌ **Do not dispatch CHANGE** | display-only, no answer |
-
-
-### 3e. How the SDK Works Internally (Context for the Agent)
-
-1. **Data Fetching**: The SDK uses `@tanstack/react-query` with an internal singleton `QueryClient`. The client does NOT need to wrap their app in a `QueryClientProvider` — the SDK manages this automatically.
-2. **Pagination**: The SDK tracks `currentPageIndex` internally. Calling `onAction({ type: 'NEXT' })` validates the current page, and if valid, increments the page index. On the last page, it auto-submits.
-3. **Validation**: When `NEXT` is dispatched, the SDK validates all required questions on the current page. If any are unanswered, it populates `state.validationErrors` and scrolls to the first error using `document.getElementById(questionId)`.
-4. **Scroll Navigation**: The SDK calls `document.getElementById(question.id)` and `.scrollIntoView()` for both validation error scrolling and page transition scrolling. This is why the client MUST set `id={question.id}` on question wrapper elements.
-5. **Progress Tracking**: `state.progressPercentage` is computed automatically based on answered questions across all pages.
-6. **Submission**: The SDK constructs the API payload and sends it to the Sprinklr CFM endpoint. The result is available in `submitSurveyResults.data`.
-7. **Language Switching**: Passing a different `language` option to `useSurveySDK()` triggers a re-mapping of the survey to the target locale. The raw API data is fetched once and translated client-side.
-8. **Placeholders**: Dynamic tokens like `{{FIRST_NAME}}` in question text are replaced at fetch time using the `placeholders` map.
-
----
-
-## 4. Component Architecture Blueprint (Logic Skeletons)
-
-> ⚠️ **IMPORTANT**: The code in this section shows **only the SDK data wiring and structural logic**. All styling has been intentionally stripped. You MUST design all visuals (colors, spacing, typography, layout, animations, hover states) from scratch based on the client's mockup or prompt. See [Section 6](#6-ui-fidelity--styling-rules) for styling guidance.
-
-### Recommended File Structure
-
-Create a modular, multi-file component structure. **Never write all code in a single file** — always refactor into well-separated components for maintainability. The structure below is a strong default; adapt it as needed to match the client's UI complexity:
-
-```
-src/
-├── app/
-│   ├── globals.css          # Tailwind import + brand CSS custom properties
-│   ├── layout.tsx           # Root HTML layout with metadata
-│   └── page.tsx             # Entry page with <Suspense> wrapper
-└── components/
-    ├── SurveyPage.tsx       # Main survey orchestrator (uses useSurveySDK) — REQUIRED
-    ├── Header.tsx           # Brand header with logo — adapt to mockup
-    ├── Footer.tsx           # Footer with optional links — adapt to mockup
-    ├── ProgressBar.tsx      # Visual progress indicator — adapt to mockup
-    ├── Question.tsx         # Question dispatcher (rating/radio/text) — REQUIRED
-    ├── RatingScale.tsx      # Rating scale input component — REQUIRED for rating questions
-    ├── LanguageSelector.tsx # Language dropdown — include if survey is multi-language
-    └── [Additional].tsx     # Add more components as the mockup demands (e.g., Sidebar, Stepper, ThankYou, etc.)
-```
-
-**Guidelines for component breakdown**:
-- `SurveyPage.tsx` and `Question.tsx` are always required — they contain critical SDK integration logic.
-- `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx` should exist as separate files unless the mockup clearly doesn't need them.
-- If the mockup shows a complex layout (sidebar navigation, stepper, multi-column), create additional components as needed.
-- If a component's JSX exceeds ~80 lines, extract sub-components.
-
----
-
-### Logic Skeleton: `page.tsx` — Entry Point
-
-```tsx
-import { Suspense } from "react";
-import SurveyPage from "@/components/SurveyPage";
-
-export default function Page() {
-  return (
-    <Suspense
-      fallback={
-        /* STYLE: Design a loading state that matches the client's brand.
-           This can be a spinner, skeleton screen, or branded loading message.
-           Must fill the viewport while survey data loads. */
-        <div>{/* Loading UI */}</div>
-      }
-    >
-      <SurveyPage />
-    </Suspense>
-  );
-}
-```
-
----
-
-### Logic Skeleton: `SurveyPage.tsx` — Main Orchestrator
-
-This is the **only component** that calls `useSurveySDK()`. The logic below is **mandatory** — implement all 5 render states exactly as shown. Style each state to match the client's mockup.
-
-```tsx
-'use client';
-
-import { useState } from 'react';
-import { useSurveySDK } from '@explorer02/cfm-survey-sdk';
-// Import your custom components — adjust names/paths to match your component structure
-import Header from '@/components/Header';
-import Footer from '@/components/Footer';
-import Question from '@/components/Question';
-import ProgressBar from '@/components/ProgressBar';
-import LanguageSelector from '@/components/LanguageSelector';
-
-// ⚠️ CRITICAL: Define placeholder values OUTSIDE the component body.
-// Defining inside creates a new object every render → infinite re-fetch loop.
-const SURVEY_PLACEHOLDERS = {
-  FIRST_NAME: 'Customer',   // Replace with client-provided test values
-  LAST_NAME: '',
-  EMAIL_ADDRESS: '',
-};
-
-export default function SurveyPage() {
-  const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>("");
-
-  // ⚠️ MANDATORY: Pass the exact Instance ID that the client provided to you in the chat!
-  // The SDK will only fetch the survey data once this valid instance ID is passed.
-  const INPUT_OPTIONS = {
-    instanceId: '<<REPLACE_WITH_CLIENT_PROVIDED_INSTANCE_ID>>',
-    language: selectedLanguage,
-    debug: false,
-    placeholders: SURVEY_PLACEHOLDERS,
-  };
-
-  const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
-    options: INPUT_OPTIONS
-  });
-
-  const survey = surveyQueryResults.data;
-
-  // ══════════════════════════════════════════════════════
-  // STATE 1: LOADING
-  // Show while survey data is being fetched from the API.
-  // ══════════════════════════════════════════════════════
-  if (surveyQueryResults.isLoading) {
-    return (
-      /* STYLE: Design a full-page loading state.
-         Can include: skeleton screens, spinner, brand animation, or simple text.
-         Should match the overall page layout (header + centered content + footer). */
-      <div>{/* Loading UI */}</div>
-    );
-  }
-
-  // ══════════════════════════════════════════════════════
-  // STATE 2: ERROR
-  // Show when the API fetch fails (network error, bad response, etc.)
-  // ══════════════════════════════════════════════════════
-  if (surveyQueryResults.error) {
-    return (
-      /* STYLE: Design a user-friendly error state.
-         Show a clear message (not raw error text).
-         Example: "Something went wrong. Please try again later." */
-      <div>{/* Error UI — display surveyQueryResults.error.message for debugging */}</div>
-    );
-  }
-
-  // ══════════════════════════════════════════════════════
-  // STATE 3: NO DATA
-  // Show when the API returns successfully but with no survey data.
-  // ══════════════════════════════════════════════════════
-  if (!survey) {
-    return (
-      /* STYLE: Design an empty state.
-         Example: "This survey is no longer available." */
-      <div>{/* Empty state UI */}</div>
-    );
-  }
-
-  // ══════════════════════════════════════════════════════
-  // STATE 4: SUBMITTED
-  // Show after the survey has been successfully submitted.
-  // ══════════════════════════════════════════════════════
-  if (submitSurveyResults.data) {
-    return (
-      /* STYLE: Design a thank-you / confirmation screen.
-         Use the client's thank-you message from Phase 1 requirements.
-         Can include: checkmark animation, brand graphics, redirect timer. */
-      <div>{/* Thank-you UI */}</div>
-    );
-  }
-
-  // ══════════════════════════════════════════════════════
-  // STATE 5: ACTIVE SURVEY
-  // The main survey view with questions, navigation, and progress.
-  // This is where all the visual design work happens.
-  // ══════════════════════════════════════════════════════
-  return (
-    <div>
-      {/* STYLE: Design the overall page layout to match the client's mockup. */}
-
-      {/* Header — pass brand data as needed */}
-      <Header />
-
-      {/* Progress Bar — receives percentage from SDK */}
-      <ProgressBar progressPercentage={state.progressPercentage} />
-
-      {/* Language Selector — only render if survey has multiple languages */}
-      {survey.languages.length > 1 && (
-        <LanguageSelector
-          languages={survey.languages}
-          selectedLanguage={survey.language}
-          onChange={setSelectedLanguage}
-        />
-      )}
-
-      {/* Questions — iterate over currentQuestions and render each one */}
-      <main>
-        {state.currentQuestions.map(question => (
-          <Question
-            key={question.id}
-            question={question}
-            selectedValue={state.values[question.id]}
-            validationError={state.validationErrors[question.id]}
-            onSelect={value =>
-              onAction({ type: 'CHANGE', payload: { questionId: question.id, value } })
-            }
-          />
-        ))}
-      </main>
-
-      {/* Submission Error — display if submission fails */}
-      {submitSurveyResults.error && (
-        /* STYLE: Design an inline error message for submission failures. */
-        <div>{submitSurveyResults.error.message}</div>
-      )}
-
-      {/* Navigation Buttons */}
-      <div className="mt-8 flex items-center justify-start gap-4">
-        {state.currentPageIndex > 0 && surveyConfig.layout.showBackButton && (
-          <button
-            type="button"
-            onClick={() => onAction({ type: 'PREVIOUS' })}
-            className="rounded-md border border-[#e20074] px-6 py-2 text-sm font-semibold text-[#e20074] transition-all hover:bg-[#fdf2f8]"
-          >
-            {survey.language?.startsWith('de') ? 'Zurück' : 'Back'}
-          </button>
-        )}
-
-        {/* Next / Submit Button */}
-        {(state.currentPageIndex < survey.pages.length - 1 ? surveyConfig.layout.showNextButton : true) && (
-          <button
-            type="button"
-            onClick={() => onAction({ type: 'NEXT' })}
-            disabled={submitSurveyResults.isLoading}
-            className="rounded-md bg-[#e20074] px-6 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-60"
-          >
-            {submitSurveyResults.isLoading
-              ? survey.language?.startsWith('de')
-                ? 'Wird gesendet...'
-                : 'Submitting...'
-              : state.currentPageIndex < survey.pages.length - 1
-                ? survey.language?.startsWith('de')
-                  ? 'Weiter'
-                  : 'Next'
-                : survey.language?.startsWith('de')
-                  ? 'Absenden'
-                  : 'Submit'}
-          </button>
-        )}
-      </div>
-
-      {/* Footer — pass links/data as needed */}
-      <Footer />
-    </div>
-  );
-}
-```
-
----
-
-### Logic Skeleton: `Question.tsx` — Question Renderer
-
-**⚠️ CRITICAL**: The outermost element MUST have `id={question.id}`. This enables the SDK's scroll-to-error and page-transition scroll features.
-
-```tsx
-import type { SurveyQuestion, AnswerValue, MatrixAnswerMap } from '@explorer02/cfm-survey-sdk';
-import RatingScale from './RatingScale';
-import CsatScale from './CsatScale';
-import LikertMatrixScale from './LikertMatrixScale';
-import CsatMatrixScale from './CsatMatrixScale';
-import SliderMatrixScale from './SliderMatrixScale';
-import FileUploadScale from './FileUploadScale';
-
-type QuestionProps = {
-  question: SurveyQuestion;
-  selectedValue?: AnswerValue;
-  validationError?: string;
-  onSelect: (value: AnswerValue) => void;
-};
-
-export default function Question({ question, selectedValue, validationError, onSelect }: QuestionProps) {
-  return (
-    // ⚠️ MANDATORY: id={question.id} — the SDK uses document.getElementById() for scroll navigation.
-    // Do NOT modify, prefix, or omit this ID.
-    <section id={question.id}>
-
-      {/* Question Title — skip for text_and_media (may be display-only card)
-          ⚠️ MANDATORY: Use dangerouslySetInnerHTML — question.text may contain HTML markup. */}
-      {question.type !== 'text_and_media' && (
-        <h2>
-          <span dangerouslySetInnerHTML={{ __html: question.text }} />
-          {question.required && (
-            /* STYLE: Design a required indicator (e.g., red asterisk, "(required)" label) */
-            <span>*</span>
-          )}
-        </h2>
-      )}
-
-      {/* ── RATING TYPE ─────────────────────────────────── */}
-      {question.type === 'rating' && (
-        <div>
-          {/* Scale Endpoint Labels — display min/mid/max labels if available */}
-          {(question.minLabel || question.midLabel || question.maxLabel) && (
-            <div>
-              {/* STYLE: Position these labels at the start, middle, and end of the scale.
-                  Use dangerouslySetInnerHTML for labels (may contain HTML).
-                  For midLabel positioning, use question.midLabelIndex:
-                    position = (midLabelIndex / (options.length - 1)) * 100  → percentage */}
-              {question.minLabel && (
-                <span dangerouslySetInnerHTML={{ __html: question.minLabel }} />
-              )}
-              {question.midLabel && (
-                <span
-                  dangerouslySetInnerHTML={{ __html: question.midLabel }}
-                  /* STYLE: Position at calculated percentage based on midLabelIndex */
-                />
-              )}
-              {question.maxLabel && (
-                <span dangerouslySetInnerHTML={{ __html: question.maxLabel }} />
-              )}
-            </div>
-          )}
-
-          {/* Rating Scale Component — handles the individual rating options */}
-          <RatingScale
-            questionId={question.id}
-            options={question.options}
-            selectedValue={typeof selectedValue === 'number' || typeof selectedValue === 'string' ? selectedValue : undefined}
-            onSelect={onSelect}
-          />
-        </div>
-      )}
-
-      {/* ── RADIO TYPE ──────────────────────────────────── */}
-      {question.type === 'radio' && (
-        <div>
-          {/* STYLE: Design radio option cards/buttons matching the mockup.
-              Each option should have: default, hover, and selected states. */}
-          {question.options.map(option => {
-            const isSelected = selectedValue === option.value;
-            return (
-              <label key={option.value}>
-                {/* Hidden native radio — use className="sr-only" for accessibility */}
-                <input
-                  type="radio"
-                  name={question.id}
-                  value={option.value}
-                  checked={isSelected}
-                  onChange={() => onSelect(option.value)}
-                  className="sr-only"
-                />
-
-                {/* STYLE: Design a custom radio indicator (circle, checkmark, etc.)
-                    Must visually differentiate selected vs. unselected state. */}
-                <div>{/* Custom radio indicator */}</div>
-
-                {/* Option Label — use dangerouslySetInnerHTML (may contain HTML) */}
-                <span dangerouslySetInnerHTML={{ __html: option.label }} />
-              </label>
-            );
-          })}
-        </div>
-      )}
-
-      {/* ── CSAT TYPE ────────────────────────────────────── */}
-      {question.type === 'csat' && (
-        <div>
-          {/* Scale Endpoint Labels */}
-          {(question.minLabel || question.maxLabel) && (
-            <div>
-              {question.minLabel && <span dangerouslySetInnerHTML={{ __html: question.minLabel }} />}
-              {question.maxLabel && <span dangerouslySetInnerHTML={{ __html: question.maxLabel }} />}
-            </div>
-          )}
-
-          {/* CsatScale Component is imported from @repo/sdk! */}
-          <CsatScale
-            question={question}
-            selectedValue={selectedValue as string | number | null}
-            onSelect={onSelect}
-          />
-        </div>
-      )}
-
-      {/* ── TEXT TYPE ────────────────────────────────────── */}
-      {question.type === 'text' && (
-        <div>
-          <textarea
-            rows={4}
-            value={typeof selectedValue === 'string' ? selectedValue : ''}
-            onChange={e => onSelect(e.target.value)}
-            placeholder={question.placeholder || 'Type your response here...'}
-            /* STYLE: Design the textarea to match the mockup.
-               Include focus state styling (border color, ring, etc.) */
-          />
-
-          {/* Character Counter — show remaining characters if maxCharacterCount is set */}
-          {question.maxCharacterCount && (
-            <div>
-              {/* STYLE: Design a character counter (e.g., "250 characters remaining") */}
-              {Math.max(
-                0,
-                question.maxCharacterCount - (typeof selectedValue === 'string' ? selectedValue.length : 0)
-              )}{' '}
-              characters remaining
-            </div>
-          )}
-        </div>
-      )}
-
-      {/* ── MATRIX TYPE (CFM_MATRIX / CSAT_MATRIX) ──────── */}
-      {question.type === 'matrix' && (
-        <CsatMatrixScale
-          question={question}
-          selectedValue={selectedValue as MatrixAnswerMap}
-          onSelect={onSelect}
-        />
-      )}
-
-      {/* ── RATING MATRIX TYPE ───────────────────────────── */}
-      {question.type === 'rating_matrix' && (
-        <LikertMatrixScale
-          question={question}
-          selectedValue={selectedValue as MatrixAnswerMap}
-          onSelect={onSelect}
-        />
-      )}
-
-      {/* ── SLIDER MATRIX TYPE ───────────────────────────── */}
-      {question.type === 'slider_matrix' && (
-        <SliderMatrixScale
-          question={question}
-          selectedValue={selectedValue as MatrixAnswerMap}
-          onSelect={onSelect}
-        />
-      )}
-
-      {/* ── FILE UPLOAD TYPE ─────────────────────────────── */}
-      {question.type === 'file_upload' && (
-        <FileUploadScale
-          question={question}
-          selectedValue={selectedValue}
-          onSelect={onSelect}
-        />
-      )}
-
-      {/* ── TEXT AND MEDIA TYPE ──────────────────────────── */}
-      {question.type === 'text_and_media' && (
-        <div>
-          {/* Question text (informational content) */}
-          {question.text && (
-            <div dangerouslySetInnerHTML={{ __html: question.text }} />
-          )}
-
-          {/* Media — render image or video based on mediaMimeType */}
-          {question.mediaUrl && (
-            question.mediaMimeType?.startsWith('video') ? (
-              <video
-                src={question.mediaUrl}
-                controls
-                /* STYLE: Constrain max width, add rounded corners, etc. */
-              />
-            ) : (
-              <img
-                src={question.mediaUrl}
-                alt={question.mediaTitle ?? ''}
-                /* STYLE: Responsive image sizing */
-              />
-            )
-          )}
-
-          {/* Optional caption */}
-          {question.mediaTitle && <p>{question.mediaTitle}</p>}
-          {/* NOTE: No onSelect call — this is display-only. The SDK skips this in validation. */}
-        </div>
-      )}
-
-      {/* Validation Error — display when the SDK flags a required question as unanswered */}
-      {validationError && (
-        /* STYLE: Design a visible error message.
-           Must be clearly noticeable (e.g., red text, bordered box, icon).
-           Do NOT use subtle styling — users must see this immediately. */
-        <div>
-          <p>{validationError}</p>
-        </div>
-      )}
-    </section>
-  );
-}
-```
-
-
-
----
-
-### Logic Skeleton: `RatingScale.tsx` — Rating Input
-
-```tsx
-import type { SurveyOption, AnswerValue } from '@explorer02/cfm-survey-sdk';
-
-type RatingScaleProps = {
-  questionId: string;
-  options: SurveyOption[];
-  selectedValue?: AnswerValue;
-  onSelect: (value: AnswerValue) => void;
-};
-
-export default function RatingScale({ questionId, options, selectedValue, onSelect }: RatingScaleProps) {
-  return (
-    <div role="radiogroup" className="w-full">
-      {/* Badges row */}
-      <div
-        className="grid gap-0.5 sm:gap-1 mb-3"
-        style={{ gridTemplateColumns: `repeat(${options.length}, minmax(0, 1fr))` }}
-      >
-        {options.map((option, index) => (
-          <div key={`${questionId}-badge-${option.value}`} className="flex justify-center">
-            <div
-              className="flex h-5 w-5 sm:h-6 sm:w-6 items-center justify-center rounded-[3px] text-[10px] sm:text-xs font-bold text-white shadow-sm"
-              style={{ backgroundColor: option.color ?? '#e20074' }}
-            >
-              {option.label}
-            </div>
-          </div>
-        ))}
-      </div>
-
-      {/* Track row */}
-      <div
-        className="grid bg-[#f2f2f2] rounded-md overflow-hidden h-11 sm:h-12 border border-gray-200/50"
-        style={{ gridTemplateColumns: `repeat(${options.length}, minmax(0, 1fr))` }}
-      >
-        {options.map((option, index) => {
-          const isSelected = selectedValue === option.value;
-          return (
-            <label
-              key={`${questionId}-track-${option.value}`}
-              className="flex items-center justify-center cursor-pointer transition-colors relative h-full w-full"
-            >
-              <input
-                type="radio"
-                name={questionId}
-                value={option.value === null ? '' : String(option.value)}
-                checked={isSelected}
-                onChange={() => onSelect(option.value)}
-                className="sr-only"
-              />
-              <div
-                className={`flex items-center justify-center w-[90%] h-[80%] rounded-[6px] transition-all ${
-                  isSelected ? 'bg-[#fbe8f3]' : 'hover:bg-gray-200/40'
-                }`}
-              >
-                {/* Custom Radio Button */}
-                <div
-                  className={`flex h-4.5 w-4.5 sm:h-5.5 sm:w-5.5 items-center justify-center rounded-full transition-all ${
-                    isSelected
-                      ? 'border-[4px] border-[#e20074] bg-white shadow-sm'
-                      : 'border-2 border-gray-300 bg-white'
-                  }`}
-                />
-              </div>
-            </label>
-          );
-        })}
-      </div>
-    </div>
-  );
-}
-```
-
----
-
-### Logic Skeleton: `CsatScale.tsx` — CSAT Satisfaction Input
-
-```tsx
-import type { CsatQuestion } from '@explorer02/cfm-survey-sdk';
-import { CsatEmojiMapping, CsatStarIcons, getEmojiForIndex } from '@explorer02/cfm-survey-sdk';
-
-type CsatScaleProps = {
-  question: CsatQuestion;
-  selectedValue?: string | number | null;
-  onSelect: (value: string | number | null) => void;
-};
-
-export default function CsatScale({ question, selectedValue, onSelect }: CsatScaleProps) {
-  const { buttonType, options, labelPosition } = question;
-
-  if (buttonType === 'dropdown') {
-    return (
-      <div className="w-full max-w-sm">
-        <select
-          className="w-full rounded-[4px] border border-gray-300 bg-white p-3 text-[15px] font-medium text-gray-900 outline-none transition-colors hover:border-gray-400 focus:border-[#e20074] focus:ring-1 focus:ring-[#e20074]"
-          value={selectedValue !== undefined ? String(selectedValue) : ''}
-          onChange={(e) => {
-            const val = e.target.value === 'null' ? null : e.target.value;
-            const numeric = Number(val);
-            onSelect(val !== null && !isNaN(numeric) ? numeric : val);
-          }}
-        >
-          <option value="" disabled>Select an option</option>
-          {options.map((opt, index) => (
-            <option key={`${String(opt.value)}-${index}`} value={String(opt.value)}>
-              {opt.label}
-            </option>
-          ))}
-        </select>
-      </div>
-    );
-  }
-
-  return (
-    <div className="flex flex-wrap items-center gap-3">
-      {options.map((option, index) => {
-        const isSelected = selectedValue === option.value;
-        const isNA = option.value === null;
-
-        // Emoji
-        const scaleOptionsLength = options.filter(o => o.value !== null).length;
-        const EmojiNode =
-          buttonType === 'emoji' && !isNA
-            ? getEmojiForIndex(index, scaleOptionsLength)
-            : null;
-
-        // Star
-        const StarNode =
-          buttonType === 'star' && !isNA
-            ? isSelected ? CsatStarIcons.filled : CsatStarIcons.empty
-            : null;
-
-        // Numbered Button
-        const isNumbered = buttonType === 'numbered' || buttonType === 'number';
-
-        return (
-          <button
-            key={`${String(option.value)}-${index}`}
-            type="button"
-            onClick={() => onSelect(option.value)}
-            className={`flex ${labelPosition === 'top' ? 'flex-col-reverse' : 'flex-col'} items-center justify-center gap-2 rounded-lg border px-5 py-4 transition-all ${
-              isSelected
-                ? 'border-[#e20074] bg-[#fdf2f8] shadow-sm'
-                : 'border-gray-200 bg-white hover:border-gray-300 hover:bg-gray-50'
-            } ${StarNode ? 'border-transparent bg-transparent hover:bg-transparent shadow-none px-2 py-2' : ''}`}
-          >
-            <div
-              className={`flex h-10 items-center justify-center text-3xl transition-transform ${
-                isSelected ? 'scale-110' : 'scale-100'
-              }`}
-            >
-              {(EmojiNode ?? StarNode ?? (
-                <span className={`text-lg ${isNumbered ? 'font-mono text-xl' : 'font-bold'} ${isSelected ? 'text-[#e20074]' : 'text-gray-700'}`}>
-                  {option.value !== null ? option.value : 'N/A'}
-                </span>
-              )) as React.ReactNode}
-            </div>
-
-            {labelPosition !== 'hidden' && !StarNode && (
-              <span
-                className={`text-[13px] font-medium leading-tight ${
-                  isSelected ? 'text-[#e20074]' : 'text-gray-600'
-                }`}
-                dangerouslySetInnerHTML={{ __html: option.label }}
-              />
-            )}
-          </button>
-        );
-      })}
-    </div>
-  );
-}
-```
-
----
-
-### Logic Skeleton: `CsatMatrixScale.tsx` — Responsive Grid
-
-```tsx
-import type { MatrixQuestion, MatrixAnswerMap } from '@explorer02/cfm-survey-sdk';
-
-type CsatMatrixScaleProps = {
-  question: MatrixQuestion;
-  selectedValue?: MatrixAnswerMap;
-  onSelect: (value: MatrixAnswerMap) => void;
-};
-
-export default function CsatMatrixScale({ question, selectedValue = {}, onSelect }: CsatMatrixScaleProps) {
-  const { rows, columns, hasNotApplicable } = question;
-
-  const handleCellSelect = (rowId: string, colValue: any) => {
-    onSelect({ ...selectedValue, [rowId]: colValue });
-  };
-
-  return (
-    <div>
-      {/* STYLE: Create a responsive layout.
-          On desktop, show a standard table/grid.
-          On mobile, stack the rows vertically and use a dropdown or list. */}
-          
-      {rows.map(row => (
-        <div key={row.id}>
-          <h3 dangerouslySetInnerHTML={{ __html: row.text }} />
-          
-          {/* Mobile view example: Dropdown */}
-          <div className="md:hidden">
-            <select
-              value={selectedValue[row.id] ?? ''}
-              onChange={(e) => handleCellSelect(row.id, e.target.value)}
-            >
-               <option value="" disabled>Select...</option>
-               {columns.map(col => (
-                 <option key={col.id} value={col.value}>{col.label}</option>
-               ))}
-            </select>
-          </div>
-
-          {/* Desktop view example: Row of buttons */}
-          <div className="hidden md:flex">
-            {columns.map(col => (
-               <button 
-                 key={col.id}
-                 type="button"
-                 onClick={() => handleCellSelect(row.id, col.value)}
-               >
-                 {col.label}
-               </button>
-            ))}
-          </div>
-
-          {hasNotApplicable && (
-            <label>
-              <input 
-                type="checkbox" 
-                checked={selectedValue[row.id] === null}
-                onChange={() => handleCellSelect(row.id, selectedValue[row.id] === null ? undefined : null)} 
-              />
-              N/A
-            </label>
-          )}
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
----
-
-### Logic Skeleton: `LikertMatrixScale.tsx`
-
-```tsx
-import type { MatrixQuestion, MatrixAnswerMap } from '@explorer02/cfm-survey-sdk';
-
-type LikertMatrixScaleProps = {
-  question: MatrixQuestion;
-  selectedValue?: MatrixAnswerMap;
-  onSelect: (value: MatrixAnswerMap) => void;
-};
-
-export default function LikertMatrixScale({ question, selectedValue = {}, onSelect }: LikertMatrixScaleProps) {
-  const { rows, columns } = question;
-
-  const handleCellSelect = (rowId: string, colValue: any) => {
-    onSelect({ ...selectedValue, [rowId]: colValue });
-  };
-
-  return (
-    <table>
-      <thead>
-        <tr>
-          <th />
-          {columns.map(col => (
-             <th key={col.id} style={{ color: col.color }}>{col.label}</th>
-          ))}
-        </tr>
-      </thead>
-      <tbody>
-        {rows.map(row => (
-          <tr key={row.id}>
-            <td><span dangerouslySetInnerHTML={{ __html: row.text }} /></td>
-            {columns.map(col => (
-              <td key={col.id}>
-                <button
-                  type="button"
-                  onClick={() => handleCellSelect(row.id, col.value)}
-                  style={{ backgroundColor: selectedValue[row.id] === col.value ? col.color : undefined }}
-                >
-                  {col.label}
-                </button>
-              </td>
-            ))}
-          </tr>
-        ))}
-      </tbody>
-    </table>
-  );
-}
-```
-
----
-
-### Logic Skeleton: `SliderMatrixScale.tsx`
-
-```tsx
-import React from 'react';
-import type { SliderMatrixQuestion } from '@explorer02/cfm-survey-sdk';
-import { CustomSliderTrack } from './CustomSliderTrack';
-
-type SliderMatrixScaleProps = {
-  question: SliderMatrixQuestion;
-  selectedValue?: Record<string, number | null | 'N/A'>;
-  onSelect: (value: Record<string, number | null | 'N/A'>) => void;
-};
-
-export function SliderMatrixScale({ question, selectedValue = {}, onSelect }: SliderMatrixScaleProps) {
-  const { rows, labels, ticks, tickValues, enableInputBox, displayValues, enableNotApplicable, sliderType } = question;
-
-  const handleSliderChange = (rowId: string, val: number | 'N/A') => {
-    onSelect({ ...selectedValue, [rowId]: val });
-  };
-
-  // Assume uniform min/max/step across rows for the header
-  const baseRow = rows[0];
-  const min = baseRow?.min ?? 0;
-  const max = baseRow?.max ?? 10;
-  const step = baseRow?.step ?? 1;
-
-  const marks: number[] = [];
-  if (ticks && ticks > 1) {
-    const markStep = (max - min) / (ticks - 1);
-    for (let i = 0; i < ticks; i++) {
-      marks.push(Number((min + i * markStep).toFixed(2))); // Round to 2 decimal digits
-    }
-  } else {
-    for (let i = min; i <= max; i += step) {
-      marks.push(Number(i.toFixed(2)));
-    }
-  }
-
-  const htmlStep = (ticks && ticks > 1) ? ((max - min) / (ticks - 1)) : step;
-
-  const hasRightText = rows.some(r => !!r.rightText);
-
-  const renderHeaderRow = () => {
-    if ((!labels || labels.length === 0) && (!tickValues || tickValues.length === 0) && hasRightText) {
-      return null;
-    }
-    return (
-      <div style={{ 
-        display: 'flex', width: '100%', marginBottom: '4px', alignItems: 'flex-end', 
-        padding: '0 16px', boxSizing: 'border-box' 
-      }}>
-        {/* Left spacer for statement text */}
-        <div style={{ flex: '0 0 25%', paddingRight: '16px' }} />
-        
-        {/* Slider track area header */}
-        <div style={{ flex: '1', position: 'relative' }}>
-          {/* Labels row */}
-          {labels && labels.length > 0 && (
-            <div style={{ 
-              position: 'relative', display: 'flex', justifyContent: 'space-between', 
-              margin: '0 16px', marginBottom: '16px', color: '#111827', fontSize: '14px', fontWeight: 500 
-            }}>
-              {labels.map((lbl, idx) => (
-                <div key={idx} style={{ width: 0, display: 'flex', justifyContent: 'center' }}>
-                  <span style={{ whiteSpace: 'nowrap' }}>{lbl}</span>
-                </div>
-              ))}
-            </div>
-          )}
-
-          {/* Numbers row */}
-          <div style={{ 
-            position: 'relative', margin: '0 16px', marginBottom: '8px', 
-            color: '#4b5563', fontSize: '14px', fontWeight: 400, height: '28px'
-          }}>
-            {tickValues && tickValues.length > 0 ? (
-              tickValues.map((tv, idx) => {
-                const percentage = max !== min ? ((tv.value - min) / (max - min)) * 100 : 0;
-                const sliceWidth = tickValues.length > 1 ? 100 / (tickValues.length - 1) : 100;
-                return (
-                  <div key={idx} style={{ 
-                    position: 'absolute', left: `${percentage}%`, transform: 'translateX(-50%)',
-                    width: `${sliceWidth}%`, display: 'flex', justifyContent: 'center'
-                  }}>
-                    {sliderType === 'graphics' ? (
-                      <div style={{ wordBreak: 'break-word', textAlign: 'center', lineHeight: '1.2', fontWeight: 500, color: '#4b5563', fontSize: '13px' }}>
-                        {tv.label}
-                      </div>
-                    ) : (
-                      <div style={{ 
-                        backgroundColor: tv.color, color: 'white', padding: '4px 8px', borderRadius: '4px',
-                        fontWeight: 600, wordBreak: 'break-word', textAlign: 'center', lineHeight: '1.2',
-                        boxShadow: '0 1px 2px rgba(0,0,0,0.1)'
-                      }}>
-                        {tv.label}
-                      </div>
-                    )}
-                  </div>
-                );
-              })
-            ) : (
-              marks.map((m, idx) => {
-                const percentage = max !== min ? ((m - min) / (max - min)) * 100 : 0;
-                const sliceWidth = marks.length > 1 ? 100 / (marks.length - 1) : 100;
-                return (
-                  <div key={idx} style={{ 
-                    position: 'absolute', left: `${percentage}%`, transform: 'translateX(-50%)',
-                    width: `${sliceWidth}%`, display: 'flex', justifyContent: 'center'
-                  }}>
-                    <span style={{ wordBreak: 'break-word', textAlign: 'center', lineHeight: '1.2' }}>{m}</span>
-                  </div>
-                );
-              })
-            )}
-          </div>
-        </div>
-
-        {/* Right Statement Header Spacer */}
-        {hasRightText && <div style={{ flex: '0 0 25%', paddingLeft: '16px' }} />}
-
-        {/* Right spacers for input box and N/A checkbox if enabled */}
-        {enableInputBox && <div style={{ width: '80px', marginLeft: '16px' }} />}
-        {enableNotApplicable && (
-          <div style={{ width: '40px', marginLeft: '16px', textAlign: 'center', fontSize: '13px', fontWeight: 600, color: '#4b5563', paddingBottom: '8px' }}>
-            N/A
-          </div>
-        )}
-      </div>
-    );
-  };
-
-  return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
-      {renderHeaderRow()}
-      
-      {rows.map((row) => {
-        const rowVal = selectedValue[row.id];
-        const isNa = rowVal === 'N/A';
-        const val = (typeof rowVal === 'number') ? rowVal : (isNa ? row.min : (row.defaultValue ?? row.min));
-        
-        return (
-          <div key={row.id} style={{ 
-            display: 'flex', width: '100%', alignItems: 'center', 
-            backgroundColor: '#f3f4f6', borderRadius: '12px', padding: '16px', boxSizing: 'border-box'
-          }}>
-            {/* Statement Text */}
-            <div style={{ flex: '0 0 25%', paddingRight: '16px', fontSize: '15px', color: '#111827', wordWrap: 'break-word', display: 'flex', alignItems: 'center' }}>
-              {row.text !== 'Question' && row.text !== '' ? (
-                 <span dangerouslySetInnerHTML={{ __html: row.text }} />
-              ) : null}
-            </div>
-            
-            {/* Slider */}
-            <div style={{ flex: '1' }}>
-              <CustomSliderTrack
-                min={row.min}
-                max={row.max}
-                htmlStep={htmlStep}
-                value={val}
-                disabled={isNa}
-                displayValues={displayValues}
-                hasSelectedValue={typeof rowVal === 'number'}
-                sliderType={sliderType}
-                ticks={ticks}
-                onChange={(v) => handleSliderChange(row.id, v)}
-              />
-            </div>
-
-            {/* Right Statement Text (Bipolar) */}
-            {row.rightText && (
-              <div style={{ flex: '0 0 25%', paddingLeft: '16px', fontSize: '15px', color: '#111827', wordWrap: 'break-word', display: 'flex', alignItems: 'center', textAlign: 'right', justifyContent: 'flex-end' }}>
-                <span dangerouslySetInnerHTML={{ __html: row.rightText }} />
-              </div>
-            )}
-
-            {/* Input Box */}
-            {enableInputBox && (
-              <div style={{ 
-                marginLeft: '16px', width: '80px', display: 'flex', alignItems: 'stretch',
-                border: '1px solid #d1d5db', borderRadius: '8px', overflow: 'hidden', 
-                backgroundColor: isNa ? '#e5e7eb' : '#fff', boxSizing: 'border-box'
-              }}>
-                <input 
-                  type="text"
-                  value={isNa ? '' : Math.round(Number(val))}
-                  disabled={isNa}
-                  onChange={(e) => {
-                    if (e.target.value === '') return;
-                    let num = Number(e.target.value);
-                    if (!isNaN(num)) {
-                       if (num < row.min) num = row.min;
-                       if (num > row.max) num = row.max;
-                       handleSliderChange(row.id, num);
-                    }
-                  }}
-                  style={{
-                    width: '50px', padding: '8px', border: 'none',
-                    fontSize: '14px', outline: 'none', backgroundColor: 'transparent', textAlign: 'center'
-                  }}
-                />
-                <div style={{ display: 'flex', flexDirection: 'column', borderLeft: '1px solid #d1d5db', backgroundColor: '#f9fafb', width: '30px' }}>
-                  <button 
-                    disabled={isNa}
-                    onClick={() => {
-                      const num = Number((Number(val) + htmlStep).toFixed(2));
-                      if (num <= row.max) handleSliderChange(row.id, num);
-                    }}
-                    style={{ flex: 1, border: 'none', background: 'none', cursor: isNa ? 'not-allowed' : 'pointer', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#4b5563' }}
-                  >
-                    <svg width="10" height="6" viewBox="0 0 10 6" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 5L5 1L9 5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/></svg>
-                  </button>
-                  <div style={{ height: '1px', backgroundColor: '#d1d5db', width: '100%' }} />
-                  <button 
-                    disabled={isNa}
-                    onClick={() => {
-                      const num = Number((Number(val) - htmlStep).toFixed(2));
-                      if (num >= row.min) handleSliderChange(row.id, num);
-                    }}
-                    style={{ flex: 1, border: 'none', background: 'none', cursor: isNa ? 'not-allowed' : 'pointer', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#4b5563' }}
-                  >
-                    <svg width="10" height="6" viewBox="0 0 10 6" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 1L5 5L9 1" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/></svg>
-                  </button>
-                </div>
-              </div>
-            )}
-
-            {/* N/A Checkbox */}
-            {enableNotApplicable && (
-              <div style={{ marginLeft: '16px', width: '40px', display: 'flex', justifyContent: 'center' }}>
-                <input 
-                  type="checkbox"
-                  checked={isNa}
-                  onChange={(e) => {
-                    if (e.target.checked) {
-                      handleSliderChange(row.id, 'N/A');
-                    } else {
-                      handleSliderChange(row.id, row.defaultValue ?? row.min);
-                    }
-                  }}
-                  style={{ width: '20px', height: '20px', cursor: 'pointer' }}
-                />
-              </div>
-            )}
-          </div>
-        );
-      })}
-    </div>
-  );
-}
-```
-
----
-
-### Logic Skeleton: `CustomSliderTrack.tsx`
-
-```tsx
-import React from 'react';
-import { getEmojiForIndex } from '@explorer02/cfm-survey-sdk';
-
-type CustomSliderTrackProps = {
-  min: number;
-  max: number;
-  htmlStep: number;
-  value: number;
-  disabled: boolean;
-  displayValues?: boolean;
-  hasSelectedValue: boolean;
-  sliderType?: 'graphics';
-  ticks?: number;
-  reverseScaleOrder?: boolean;
-  onChange: (v: number) => void;
-};
-
-export function CustomSliderTrack({
-  min,
-  max,
-  htmlStep,
-  value,
-  disabled,
-  displayValues,
-  hasSelectedValue,
-  sliderType,
-  ticks,
-  reverseScaleOrder,
-  onChange
-}: CustomSliderTrackProps) {
-  const [isHovered, setIsHovered] = React.useState(false);
-  const [isDragging, setIsDragging] = React.useState(false);
-  
-  const percentage = ((value - min) / (max - min)) * 100;
-  
-  // Use gray color if disabled, otherwise use pink/magenta theme color
-  const themeColor = disabled ? '#9ca3af' : '#e20074';
-  
-  return (
-    <div 
-      style={{ position: 'relative', height: '32px', display: 'flex', alignItems: 'center', margin: '0 16px', opacity: disabled ? 0.5 : 1 }}
-      onMouseEnter={() => !disabled && setIsHovered(true)}
-      onMouseLeave={() => { setIsHovered(false); setIsDragging(false); }}
-    >
-      <div style={{ 
-        position: 'absolute', top: '50%', left: 0, right: 0, transform: 'translateY(-50%)',
-        height: '4px', borderRadius: '2px', backgroundColor: '#e5e7eb' 
-      }} />
-      
-      <div style={{ 
-        position: 'absolute', top: '50%', left: 0, width: `${percentage}%`, transform: 'translateY(-50%)',
-        height: '4px', borderRadius: '2px', backgroundColor: themeColor,
-        transition: isDragging ? 'none' : 'width 0.15s ease-in-out'
-      }} />
-
-      {/* Ticks on track */}
-      {ticks && ticks > 1 && Array.from({ length: ticks }).map((_, idx) => {
-        const tickPct = (idx / (ticks - 1)) * 100;
-        return (
-          <div 
-            key={idx}
-            style={{
-              position: 'absolute',
-              top: '50%',
-              left: `${tickPct}%`,
-              transform: 'translate(-50%, -50%)',
-              width: '1px',
-              height: '8px',
-              backgroundColor: '#d1d5db',
-              pointerEvents: 'none'
-            }}
-          />
-        );
-      })}
-
-      <input
-        type="range"
-        min={min} max={max} step={htmlStep} value={value}
-        disabled={disabled}
-        onChange={(e) => onChange(Number(e.target.value))}
-        onMouseDown={() => !disabled && setIsDragging(true)}
-        onMouseUp={() => setIsDragging(false)}
-        onTouchStart={() => !disabled && setIsDragging(true)}
-        onTouchEnd={() => setIsDragging(false)}
-        style={{
-          position: 'absolute', top: '50%', left: '-16px', right: '-16px', width: 'calc(100% + 32px)', height: '100%',
-          transform: 'translateY(-50%)', opacity: 0, cursor: disabled ? 'not-allowed' : 'pointer', zIndex: 10, margin: 0,
-        }}
-      />
-
-      {sliderType === 'graphics' ? (
-        <div style={{
-          position: 'absolute', top: '50%', left: `${percentage}%`,
-          transform: 'translate(-50%, -50%)',
-          transition: isDragging ? 'none' : 'left 0.15s ease-in-out',
-          pointerEvents: 'none', zIndex: 11,
-          opacity: disabled ? 0.5 : 1
-        }}>
-          {getEmojiForIndex(
-            reverseScaleOrder
-              ? (ticks || 10) - 1 - Math.min((ticks || 10) - 1, Math.max(0, Math.round(((value - min) / (max - min)) * ((ticks || 10) - 1))))
-              : Math.min((ticks || 10) - 1, Math.max(0, Math.round(((value - min) / (max - min)) * ((ticks || 10) - 1)))), 
-            ticks || 10
-          ) as React.ReactNode}
-        </div>
-      ) : (
-        <div style={{
-          position: 'absolute', top: '50%', left: `${percentage}%`,
-          transform: 'translate(-50%, -50%)', 
-          width: '18px', 
-          height: '18px',
-          borderRadius: '50%', 
-          backgroundColor: '#ffffff',
-          border: `2.5px solid ${themeColor}`,
-          boxShadow: (isHovered || isDragging) && !disabled 
-            ? '0 0 0 6px rgba(226, 0, 116, 0.2), 0 1px 3px rgba(0,0,0,0.2)' 
-            : '0 1px 3px rgba(0,0,0,0.2)', 
-          pointerEvents: 'none',
-          transition: isDragging ? 'none' : 'left 0.15s ease-in-out, box-shadow 0.15s, border-color 0.2s',
-          boxSizing: 'border-box'
-        }} />
-      )}
-
-      {(isHovered || isDragging) && !disabled && (
-        <div style={{
-          position: 'absolute', bottom: '100%', left: `${percentage}%`,
-          transform: 'translate(-50%, -10px)',
-          backgroundColor: '#1f2937', color: '#fff', fontSize: '13px', fontWeight: 600,
-          padding: '4px 10px', borderRadius: '6px', pointerEvents: 'none',
-          boxShadow: '0 4px 6px -1px rgba(0, 0, 0, 0.1)',
-          zIndex: 20
-        }}>
-          {Math.round(value)}
-          <div style={{
-            position: 'absolute', top: '100%', left: '50%', transform: 'translateX(-50%)',
-            borderWidth: '5px', borderStyle: 'solid',
-            borderColor: '#1f2937 transparent transparent transparent'
-          }} />
-        </div>
-      )}
-    </div>
-  );
-}
-```
-
----
-
-### Logic Skeleton: `FileUploadScale.tsx`
-
-```tsx
-import { useState, useRef } from 'react';
-import type { FileUploadQuestion } from '@explorer02/cfm-survey-sdk';
-
-export default function FileUploadScale({ question, selectedValue, onSelect }: { question: FileUploadQuestion, selectedValue: any, onSelect: any }) {
-  const { maxFileCount = 1, fileSizeLimit = 10, fileSizeLimitType, supportedFileFormats = [], uploadMessage } = question;
-  const [isDragActive, setIsDragActive] = useState(false);
-  const [error, setError] = useState('');
-  const fileInputRef = useRef<HTMLInputElement>(null);
-
-  const currentFiles: File[] = Array.isArray(selectedValue) ? selectedValue : [];
-
-  const handleFiles = (files: FileList) => {
-    setError('');
-    const newFiles = Array.from(files);
-    
-    // Validate count
-    if (currentFiles.length + newFiles.length > maxFileCount) {
-      setError(`Maximum ${maxFileCount} files allowed.`);
-      return;
-    }
-    
-    // Validate extensions & size
-    for (const file of newFiles) {
-      const ext = file.name.split('.').pop()?.toUpperCase() || '';
-      if (supportedFileFormats.length > 0 && !supportedFileFormats.includes(ext)) {
-        setError(`File type .${ext} not supported.`);
-        return;
-      }
-      if (fileSizeLimitType === 'PER_FILE' && file.size > fileSizeLimit * 1024 * 1024) {
-        setError(`File exceeds limit of ${fileSizeLimit}MB.`);
-        return;
-      }
-    }
-    
-    onSelect([...currentFiles, ...newFiles]);
-  };
-
-  const handleDrop = (e: React.DragEvent) => {
-    e.preventDefault(); setIsDragActive(false);
-    if (e.dataTransfer.files) handleFiles(e.dataTransfer.files);
-  };
-
-  const handleDragOver = (e: React.DragEvent) => {
-    e.preventDefault(); setIsDragActive(true);
-  };
-
-  return (
-    <div>
-       <input 
-         type="file" 
-         hidden ref={fileInputRef} 
-         onChange={(e) => e.target.files && handleFiles(e.target.files)}
-         multiple={maxFileCount > 1}
-       />
-       
-       <div 
-         onDrop={handleDrop} 
-         onDragOver={handleDragOver} 
-         onDragLeave={() => setIsDragActive(false)}
-         onClick={() => fileInputRef.current?.click()}
-         /* STYLE: Apply dashed border, drag active state styles */
-       >
-         <span dangerouslySetInnerHTML={{ __html: uploadMessage || 'Drag and drop files here' }} />
-       </div>
-       
-       {error && <div /* STYLE: Error message styling */>{error}</div>}
-       
-       <div>
-         {currentFiles.map((f, i) => (
-           <div key={i}>
-             {f.name} ({(f.size / 1024 / 1024).toFixed(2)} MB)
-             <button type="button" onClick={() => onSelect(currentFiles.filter((_, idx) => idx !== i))}>Remove</button>
-           </div>
-         ))}
-       </div>
-    </div>
-  );
-}
-```
-
----
-
-### Logic Skeleton: `LanguageSelector.tsx`
-
-```tsx
-import type { SurveyLanguage } from '@explorer02/cfm-survey-sdk';
-
-type LanguageSelectorProps = {
-  languages: SurveyLanguage[];
-  selectedLanguage: string;
-  onChange: (languageCode: string) => void;
-};
-
-export default function LanguageSelector({
-  languages,
-  selectedLanguage,
-  onChange,
-}: LanguageSelectorProps) {
-  if (!languages || languages.length <= 1) {
-    return null;
-  }
-
-  return (
-    <div className="flex justify-end mb-6 mt-4">
-      <div className="relative">
-        <select
-          value={selectedLanguage}
-          onChange={(e) => onChange(e.target.value)}
-          className="appearance-none rounded-lg border border-[#2563eb] bg-white py-2 pl-4 pr-10 text-sm font-semibold text-[#2563eb] focus:outline-none focus:ring-2 focus:ring-[#2563eb] cursor-pointer"
-        >
-          {languages.map((lang) => (
-            <option key={lang.code} value={lang.code} className="text-gray-900">
-              {lang.name}
-            </option>
-          ))}
-        </select>
-        <div className="pointer-events-none absolute inset-y-0 right-0 flex items-center pr-3">
-          <svg className="h-4 w-4 text-[#2563eb]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M19 9l-7 7-7-7" />
-          </svg>
-        </div>
-      </div>
-    </div>
-  );
-}
-```
-
----
-
-### Logic Skeleton: `ProgressBar.tsx`
-
-```tsx
-type ProgressBarProps = {
-  progressPercentage: number;
-};
-
-export default function ProgressBar({ progressPercentage }: ProgressBarProps) {
-  return (
-    /* STYLE: Design a progress indicator matching the mockup.
-       Common patterns: horizontal bar, circular/radial progress, step indicator, percentage text.
-       Use progressPercentage (0–100) to control the fill width/amount.
-       Add a smooth transition animation for width changes. */
-    <div>
-      <div style={{ width: `${progressPercentage}%` }}>
-        {/* Progress fill */}
-      </div>
-    </div>
-  );
-}
-```
-
----
-
-### Logic Skeleton: `Header.tsx` and `Footer.tsx`
-
-These are **fully custom layout components** — there is no SDK logic here. Build them entirely from the client's mockup/brand:
-
-- **Header**: May include logo (use Next.js `<Image>` with `priority`), survey title, brand graphics.
-- **Footer**: May include legal links (Privacy Policy, Imprint), copyright text, brand logo.
-
-If the mockup doesn't show a header or footer, you may omit these components.
-
----
-
-## 5. Critical Constraints & Rules
-
-These are **non-negotiable** requirements that must be followed in every build:
-
-### 5a. HTML Element IDs for Scroll Navigation
-
-The SDK internally uses `document.getElementById(question.id)` to find question elements in the DOM for:
-- **Scroll-to-error**: When validation fails, the SDK scrolls to the first unanswered required question.
-- **Page transition scroll**: When navigating to a new page, the SDK scrolls to the first question.
-
-**Rule**: Every question wrapper element MUST have `id={question.id}`:
-```tsx
-// ✅ CORRECT — SDK can find this element
-<section id={question.id}>...</section>
-
-// ❌ WRONG — SDK cannot find the element, scroll will fail silently
-<section>...</section>
-<section id={`question-${question.id}`}>...</section>  // Modified ID, won't match
-```
-
-### 5b. Import Rules
-
-| Import | Source | Used In |
-|--------|--------|---------|
-| `useSurveySDK` | `@explorer02/cfm-survey-sdk` | `SurveyPage.tsx` only |
-| `type SurveyQuestion` | `@explorer02/cfm-survey-sdk` | `Question.tsx` component props |
-| `type SurveyLanguage` | `@explorer02/cfm-survey-sdk` | `LanguageSelector.tsx` component props |
-
-**Never import internal SDK modules**. Only use the public exports listed above.
-
-### 5c. `'use client'` Directive
-
-The `SurveyPage.tsx` component MUST have `'use client';` as the very first line. This is required because:
-- `useSurveySDK()` is a React hook (client-only).
-- `useState` for language selection is client-only.
-
-Child components (`Question`, `Header`, `Footer`, etc.) do NOT need `'use client'` because they receive data as props from the parent client component.
-
-### 5d. `<Suspense>` Boundary
-
-The main `page.tsx` must wrap `<SurveyPage />` in a `<Suspense>` boundary. This prevents hydration mismatches and provides a loading fallback while the client component initialises.
-
-### 5e. Placeholder Constants
-
-Define placeholder values as a **constant object outside the component** to avoid unnecessary re-renders:
-
-```tsx
-// ✅ CORRECT — stable reference, defined outside component
-const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'John', LAST_NAME: 'Doe' };
-
-export default function SurveyPage() {
-  const { ... } = useSurveySDK({ options: { placeholders: SURVEY_PLACEHOLDERS } });
-}
-
-// ❌ WRONG — new object created every render, triggers infinite re-fetch
-export default function SurveyPage() {
-  const { ... } = useSurveySDK({ options: { placeholders: { FIRST_NAME: 'John' } } });
-}
-```
-
-### 5f. Action Dispatching Pattern
-
-Always use `onAction()` for ALL user interactions. Never call internal SDK functions directly:
-
-```tsx
-// ✅ CORRECT
-onAction({ type: 'CHANGE', payload: { questionId: question.id, value: newValue } })
-onAction({ type: 'NEXT' })
-onAction({ type: 'PREVIOUS' })
-
-// ❌ WRONG — bypasses SDK validation, logging, and analytics
-setValues(prev => ({ ...prev, [question.id]: newValue }))
-setCurrentPageIndex(prev => prev + 1)
-```
-
----
-
-## 6. UI Fidelity & Styling Rules
-
-### Styling Framework
-
-**Default**: Use **Tailwind CSS** utility classes for all styling. The `create-next-app --tailwind` setup in Phase 2 configures this automatically.
-
-**Alternative**: If the client explicitly requests a different styling approach (vanilla CSS, CSS Modules, styled-components, etc.), you may use that instead. The SDK has **zero CSS dependencies** — it works with any styling solution.
-
----
-
-### 6a. Design Analysis Checklist (When Client Provides Screenshots)
-
-When the client shares UI mockup images, **systematically extract every design detail** before writing any code. Go through this checklist:
-
-#### Colors
-- [ ] **Primary brand color** — The dominant accent color (buttons, progress bar, selected states)
-- [ ] **Secondary color** — If used for secondary buttons, links, or accents
-- [ ] **Background color** — Page background (white, off-white, dark, gradient?)
-- [ ] **Card/surface color** — Background for question cards or content areas
-- [ ] **Text colors** — Primary text, secondary/muted text, heading text
-- [ ] **Border colors** — Default borders, active/selected borders
-- [ ] **Error color** — Validation error messages and indicators
-- [ ] **Selected state colors** — Background tint and border for selected options
-
-#### Typography
-- [ ] **Font family** — Identify the typeface (use Google Fonts if not a system font)
-- [ ] **Heading sizes** — H1, H2, question title sizes
-- [ ] **Body text size** — Default paragraph and option label sizes
-- [ ] **Font weights** — Regular, medium, semibold, bold usage
-- [ ] **Line heights** — Tight, normal, or relaxed spacing
-
-#### Layout & Spacing
-- [ ] **Page max-width** — Content area width (narrow, medium, wide, full-bleed)
-- [ ] **Header height and structure** — Fixed? Contains logo? Background color?
-- [ ] **Content padding** — Horizontal and vertical spacing around the main content
-- [ ] **Question spacing** — Gap between consecutive questions
-- [ ] **Option spacing** — Gap between radio options or rating badges
-- [ ] **Footer position** — Sticky? Fixed at bottom? Below content?
-
-#### Component Styles
-- [ ] **Card design** — Border radius, shadow, padding, background
-- [ ] **Button design** — Border radius, padding, font size, hover/active/disabled states
-- [ ] **Radio/option cards** — Shape, border style, selected highlight
-- [ ] **Rating scale style** — Badges, circles, numbered grid, stars?
-- [ ] **Progress bar style** — Bar thickness, border radius, animation
-- [ ] **Input field style** — Border, border radius, focus ring
-
-#### Interactive States
-- [ ] **Hover effects** — Color changes, shadows, scale transforms
-- [ ] **Selected state** — How selected options differ from unselected
-- [ ] **Disabled state** — How the submit button looks while submitting
-- [ ] **Error state** — How validation errors are displayed (inline, toast, bordered box)
-- [ ] **Transitions** — Smooth transitions on state changes (duration, easing)
-
-After completing this checklist, define the extracted values as **CSS custom properties** in `globals.css`:
-
-```css
-@import "tailwindcss";
-
-:root {
-  --brand-color: /* extracted primary color */;
-  --brand-bg-light: /* light tint of primary for selected backgrounds */;
-  --bg-page: /* page background */;
-  --bg-card: /* card/surface background */;
-  --text-primary: /* primary text color */;
-  --text-secondary: /* secondary/muted text */;
-  --border-default: /* default border color */;
-  --border-active: /* selected/active border color */;
-  --radius-card: /* card border radius */;
-  --radius-button: /* button border radius */;
-}
-```
-
----
-
-### 6b. When the Client Provides a Color Scheme or Brand Guidelines
-
-Apply the primary color to:
-- Progress bar fill
-- Selected radio button indicators
-- Selected rating scale highlights
-- Primary action button (Next/Submit) background
-- Focus ring on text inputs
-- Active border on radio option cards
-
-Apply a light tint of the primary color to:
-- Selected radio card backgrounds
-- Selected rating scale cell backgrounds
-
----
-
-### 6c. No-Mockup Default Design
-
-When the client provides **only a text prompt with no screenshots, mockup, or brand guidelines**, use this clean, modern default design system:
-
-| Property | Default Value |
-|----------|---------------|
-| **Background** | White (`#ffffff`) |
-| **Text color** | Dark gray (`#1a1a1a`) |
-| **Secondary text** | Medium gray (`#6b7280`) |
-| **Brand/accent color** | Ask the client; if none given, use a professional blue (`#2563eb`) |
-| **Font family** | System font stack: `system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif` |
-| **Content max-width** | `max-w-3xl` (48rem / 768px) |
-| **Card style** | White background, 1px `#e5e7eb` border, `0.75rem` border radius, `1.5rem` padding |
-| **Button style** | Brand color background, white text, `0.5rem` border radius, medium font weight |
-| **Radio options** | Card-style with border, subtle hover bg, brand-color border + light tint bg when selected |
-| **Rating scale** | Horizontal row of numbered badges, brand-color highlight on selected |
-| **Progress bar** | 4px height, gray-100 track, brand-color fill, rounded-full, smooth width transition |
-| **Spacing** | `2rem` between questions, `1rem` between options |
-| **Transitions** | `transition-all duration-200` on interactive elements |
-
-This creates a neutral, professional design that works for any brand. The agent should **still ask the client for their brand color** — it's the single most impactful customisation.
-
----
-
-### 6d. General Styling Standards (Apply to All Builds)
-
-- Ensure full **responsive design** (mobile-first with `sm:`, `md:`, `lg:` breakpoints).
-- Add **smooth transitions** on interactive elements.
-- Use **`sr-only`** class to hide native radio inputs while keeping them accessible.
-- Rating badges should display the option's `color` property using inline `style={{ backgroundColor: option.color }}` when available.
-- Text areas should show a **character count** using `question.maxCharacterCount`.
-- Validation errors should be **visually prominent** (not subtle gray text).
-
-### 6e. Logo Handling
-
-When a logo is provided (either `logo.fileName` or `logo.defaultUrl`):
-1. Render it in the header as an industry-standard practice.
-2. Apply styling to ensure it is displayed in a standard size. Regardless of its original pixel size or resolution, it MUST NOT exceed standard dimensions. Specifically, set its maximum height to 40px, preserve aspect ratio, and handle overflow. Do NOT hardcode large width/height dimensions that might break the layout. For example, use `style={{ maxHeight: '40px', width: 'auto', objectFit: 'contain', display: 'block' }}` or equivalent Tailwind classes.
-3. If using Next.js `<Image>`, do NOT let the width/height attributes override standard constraints. Always constrain the containing element or the image itself to `max-height: 40px` and `width: auto`.
-
----
-
-## 7. Configuration & Build Requirements
-
-### 7a. Required Dependencies
-
-```json
-{
-  "dependencies": {
-    "@explorer02/cfm-survey-sdk": "latest",
-    "@tanstack/react-query": "^5.0.0",
-    "next": "^15.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
-  },
-  "devDependencies": {
-    "@tailwindcss/postcss": "^4.0.0",
-    "@types/node": "^22.0.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "eslint": "^9.0.0",
-    "eslint-config-next": "^15.0.0",
-    "postcss": "^8.0.0",
-    "tailwindcss": "^4.0.0",
-    "typescript": "^5.0.0"
-  }
-}
-```
-
-### 7b. `next.config.js` — MANDATORY Configuration
-
-```javascript
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  reactStrictMode: true,
-  transpilePackages: ["@explorer02/cfm-survey-sdk"],
-};
-
-module.exports = nextConfig;
-```
-
-> **Why `transpilePackages` is required**: In this monorepo workspace, it allows Next.js to watch the local SDK files directly and hot-reload changes in real-time. For clients, since the SDK compiles to modern ES2022 JavaScript, transpiling allows Next.js's SWC compiler to tree-shake the code and down-transpile it to fit any older browser targets specified by the client application.
-
-### 7c. `layout.tsx` — Root Layout
-
-```tsx
-import type { Metadata } from "next";
-import "./globals.css";
-
-export const metadata: Metadata = {
-  title: "Customer Survey",       // ← Replace with client's survey title
-  description: "Customer feedback survey",
-};
-
-export default function RootLayout({
-  children,
-}: Readonly<{ children: React.ReactNode }>) {
-  return (
-    <html lang="en">
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-
----
-
-## 8. Deployment Phase
-
-### Pre-Deployment Checklist
-
-Before deploying, verify:
-- [ ] `npm run build` completes with zero errors
-- [ ] `next.config.js` has `transpilePackages: ["@explorer02/cfm-survey-sdk"]`
-- [ ] Logo files (if any) are in the `public/` directory
-- [ ] All components use `id={question.id}` on question wrappers
-- [ ] UI Verification Checklist (Phase 6) has been completed
-
-### Deployment Command
-
-Based on the `deployToVercel` flag inside `./survey-config.json` (or user approval in chat):
-
-```bash
-npx cfm-sdk deploy
-```
-
-This command handles the full Vercel deployment pipeline:
-1. **Node.js version check** — Ensures v18+ is installed.
-2. **Vercel CLI check** — Installs Vercel CLI globally if missing (with user consent), or falls back to `npx`.
-3. **Vercel authentication** — Checks for `VERCEL_TOKEN` env variable or prompts interactive login.
-4. **Production deployment** — Runs `vercel --prod --yes` and outputs the live URL.
-
-If the deployment command is not available (e.g., SDK not installed globally), you can deploy manually:
-
-```bash
-npx vercel --prod --yes
-```
-
----
-
-## 9. Reference: Styled Code Templates (Reference Only)
-
-> ⚠️ **WARNING — DO NOT COPY-PASTE STYLING FROM THIS SECTION**
->
-> The styled code below is a **reference implementation** from one specific client (Telekom). It is included **only** to show how the SDK data wiring connects to a real, working UI. The Tailwind classes, colors (`#e20074`), layout choices, and component designs in this section are **NOT universal** — they are specific to one brand.
->
-> **What you MUST do instead**:
-> 1. Use the **Logic Skeletons in Section 4** for the SDK integration structure.
-> 2. Design **all visuals from scratch** based on the client's mockup or prompt.
-> 3. Refer to this section ONLY to understand how SDK data flows into JSX — never for styling decisions.
-
-### `src/app/globals.css`
-```css
-@import "tailwindcss";
-
-:root {
-  --brand-color: #e20074;
-  --brand-bg-light: #fdf2f8;
-}
-
-body {
-  margin: 0;
-  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-  color: #262626;
-  background-color: #ffffff;
-}
-```
-
-### `src/app/layout.tsx`
-```tsx
-import type { Metadata } from "next";
-import "./globals.css";
-
-export const metadata: Metadata = {
-  title: "Customer Survey",
-  description: "Customer feedback survey",
-};
-
-export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
-  return (
-    <html lang="en">
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-
-### `src/app/page.tsx`
-```tsx
-import { Suspense } from "react";
-import SurveyPage from "@/components/SurveyPage";
-
-export default function Page() {
-  return (
-    <Suspense fallback={<div className="flex min-h-screen items-center justify-center"><p>Loading...</p></div>}>
-      <SurveyPage />
-    </Suspense>
-  );
-}
-```
-
-### `next.config.js`
-```javascript
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  reactStrictMode: true,
-  transpilePackages: ["@explorer02/cfm-survey-sdk"],
-};
-module.exports = nextConfig;
-```
-
----
-
-## Appendix A: Other Frameworks (Vite, Remix, CRA)
-
-The SDK's `useSurveySDK()` hook is a **standard React hook** — it works in any React-based framework, not just Next.js. Here are the key differences when using other frameworks:
-
-### Vite + React
-
-```bash
-# Initialise
-npx -y create-vite@latest ./ --template react-ts
-
-# Install dependencies
-npm install @explorer02/cfm-survey-sdk @tanstack/react-query
-```
-
-**Key differences from Next.js**:
-- ❌ **No `transpilePackages` needed** — Vite handles TypeScript transpilation natively.
-- ❌ **No `'use client'` directive needed** — Vite doesn't use Server Components.
-- ❌ **No `<Suspense>` boundary needed** — No Server Component hydration concerns.
-- ✅ **Still needs `useSurveySDK()`**, `id={question.id}`, `SURVEY_PLACEHOLDERS` outside component, and `onAction()` dispatcher — all SDK constraints still apply.
-
-### Remix
-
-```bash
-npx -y create-remix@latest ./
-npm install @explorer02/cfm-survey-sdk @tanstack/react-query
-```
-
-**Key differences from Next.js**:
-- ❌ **No `transpilePackages` needed** — Remix uses Vite/esbuild under the hood.
-- ✅ **`'use client'` IS needed** in Remix v2 if using Server Components (depends on version).
-- ✅ All SDK constraints still apply.
-
-### Create React App (CRA)
-
-```bash
-npx -y create-react-app ./ --template typescript
-npm install @explorer02/cfm-survey-sdk @tanstack/react-query
-```
-
-**Key differences from Next.js**:
-- ❌ **No `transpilePackages` needed** — CRA's webpack config handles this.
-- ❌ **No `'use client'` directive** — CRA doesn't have Server Components.
-- ❌ **No `<Suspense>` boundary needed** — No SSR concerns.
-- ✅ All SDK constraints still apply.
-
-### Universal SDK Constraints (Apply to ALL Frameworks)
-
-Regardless of framework, these rules always apply:
-1. `id={question.id}` on question wrappers — for scroll navigation.
-2. `dangerouslySetInnerHTML={{ __html: question.text }}` — for HTML in question text.
-3. `SURVEY_PLACEHOLDERS` defined outside the component — to prevent infinite re-renders.
-4. `onAction()` for all user interactions — never bypass the dispatcher.
-5. Import only from `@explorer02/cfm-survey-sdk` — never from internal paths.
-
----
-
-## Troubleshooting Guide
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `SyntaxError: Unexpected token 'export'` | Missing `transpilePackages` in `next.config.js` | Add `transpilePackages: ["@explorer02/cfm-survey-sdk"]` |
-| Scroll-to-error doesn't work | Missing `id={question.id}` on question wrapper | Add `id={question.id}` to the outermost element of each question |
-| Survey shows "No survey data" | SDK cannot reach the API endpoint | Check network connectivity; the SDK fetches from `https://custom-p0.feedbook.me/api/feedback/survey/cfm` |
-| Infinite re-renders | Placeholders object defined inside component | Move `SURVEY_PLACEHOLDERS` outside the component body |
-| `type SurveyQuestion` import error | Importing from wrong path | Import from `@explorer02/cfm-survey-sdk`, not internal paths |
-| Tailwind classes not applying | Missing `@import "tailwindcss"` in CSS | Add `@import "tailwindcss";` to `globals.css` |
-| Build error: "Cannot find module" | Missing dependencies | Run `npm install @explorer02/cfm-survey-sdk @tanstack/react-query` |
-| Hydration mismatch errors | Missing `<Suspense>` boundary in `page.tsx` | Wrap `<SurveyPage />` in `<Suspense>` in the entry page |
-| Survey looks identical to another client's | Agent copied styling from Section 9 reference | Delete all copied styles; redesign from scratch using Section 4 skeletons + client mockup |
+Open `node_modules/@explorer02/cfm-survey-sdk/docs/index.md` now and follow the instructions inside it strictly.