@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

package/templates/docs/MANIFEST.json

@@ -1,155 +1,562 @@
 {
-  "version": "1.0.0",
+  "docsSchemaVersion": "2.4.0",
+  "sdkTypesVersion": "0.2.1",
   "packageNames": {
     "npm": "@explorer02/cfm-survey-sdk",
     "monorepo": "@repo/sdk"
   },
-  "entryPoint": "index.md",
-  "clientInputs": ["initialPrompt", "instanceIdJwt", "deployConfirmation"],
+  "entryPoints": {
+    "index": "index.md",
+    "agentMonorepo": "../AGENT.md",
+    "agentNpm": "node_modules/@explorer02/cfm-survey-sdk/templates/AGENT.md"
+  },
+  "clientInputs": [
+    "initialPrompt",
+    "instanceIdJwt",
+    "deployConfirmation"
+  ],
+  "hookContract": {
+    "answersField": "state.answers",
+    "customFieldValuesField": "options.customFieldValues",
+    "changePayload": {
+      "questionId": "string",
+      "answerValue": "AnswerValue"
+    },
+    "stableRefs": [
+      "placeholders",
+      "customFieldValues",
+      "surveyOptions useMemo"
+    ],
+    "lifecycleActions": [
+      "SCROLL",
+      "RECORD_QUESTION_VIEW"
+    ],
+    "visibilityHelpers": {
+      "getVisibleMcqOptionsForAnswers": "4th arg customFieldValues optional",
+      "getVisibleRankOrderOptionsForAnswers": "4th arg customFieldValues optional",
+      "getVisibleMatrixItemsForAnswers": "4th arg customFieldValues optional",
+      "getVisibleStatementRowsForAnswers": "4th arg customFieldValues optional",
+      "getVisibleScaleColumnsForAnswers": "4th arg customFieldValues optional"
+    },
+    "forbiddenImports": [
+      "@explorer02/cfm-survey-sdk/src/**",
+      "@repo/sdk/src/**"
+    ]
+  },
+  "integrationDocs": [
+    {
+      "path": "00-integration/client-integration-guide.md",
+      "purpose": "Master wiring map — start here for full client integration"
+    },
+    {
+      "path": "00-integration/useSurveySDK.md",
+      "purpose": "Hook signature, actions, validation, lifecycle, partial save"
+    },
+    {
+      "path": "00-integration/skip-logic-and-navigation.md",
+      "purpose": "Skip logic behavior and client nav responsibilities"
+    },
+    {
+      "path": "00-integration/display-logic-and-navigation.md",
+      "purpose": "Question-level display logic and currentQuestions"
+    },
+    {
+      "path": "00-integration/answer-logic-and-navigation.md",
+      "purpose": "Option/row/column answer logic and visibility helpers"
+    },
+    {
+      "path": "00-integration/custom-field-logic-and-navigation.md",
+      "purpose": "CRM custom fields in logic rules — two wiring points"
+    },
+    {
+      "path": "00-integration/question-display-variants.md",
+      "purpose": "Conditional question text variants — SDK resolves questionText on currentQuestions"
+    },
+    {
+      "path": "00-integration/question-numbering.md",
+      "purpose": "Active-path question ordinals on currentQuestions.questionNumber"
+    },
+    {
+      "path": "00-integration/end-page-logic.md",
+      "purpose": "Multiple end pages — display-logic selection at submit"
+    },
+    {
+      "path": "00-integration/progress.md",
+      "purpose": "Progress bar formula and active-path credits"
+    },
+    {
+      "path": "00-integration/constraints.md",
+      "purpose": "Non-negotiable rules and troubleshooting"
+    },
+    {
+      "path": "00-integration/aws-deploy.md",
+      "purpose": "Deploy static survey UI to AWS via EC2 middle API (S3 + CloudFront)"
+    },
+    {
+      "path": "00-integration/question-type-sdk-matrix.md",
+      "purpose": "Master 11-type SDK integration matrix"
+    },
+    {
+      "path": "00-integration/placeholders-and-tokens.md",
+      "purpose": "Placeholder token resolution"
+    },
+    {
+      "path": "00-integration/partial-save-and-recovery.md",
+      "purpose": "Debounced partial save wiring"
+    },
+    {
+      "path": "00-integration/survey-lifecycle-analytics.md",
+      "purpose": "Mark-as-started and question activity"
+    },
+    {
+      "path": "00-integration/logic-fields-catalog.md",
+      "purpose": "Logic field reference by question type for skip/display/answer/end"
+    },
+    {
+      "path": "00-integration/analytics-events-catalog.md",
+      "purpose": "Consolidated SDK analytics and client lifecycle events"
+    },
+    {
+      "path": "00-integration/file-upload-aws.md",
+      "purpose": "Presigned S3 upload flow for FILE_UPLOAD submit contract"
+    }
+  ],
+  "templateScaleFiles": [
+    "templates/RankOrderScale.tsx",
+    "templates/MatrixDropdown.tsx",
+    "templates/CustomSliderTrack.tsx",
+    "templates/surveyUiIcons.tsx",
+    "templates/heatmapCoords.ts"
+  ],
+  "deployTargets": {
+    "aws": {
+      "doc": "00-integration/aws-deploy.md",
+      "script": "templates/deploy-to-aws.sh",
+      "apiBaseEnv": "CFM_DEPLOY_API_BASE",
+      "apiBaseDefault": "http://43.204.26.213:3000",
+      "instanceIdEnv": "CFM_INSTANCE_ID",
+      "outDirEnv": "OUT_DIR",
+      "healthPath": "/health",
+      "startPath": "/deploy/start",
+      "completePath": "/deploy/complete",
+      "maxFiles": 500,
+      "staticOutputDir": "out",
+      "frameworkStaticExport": {
+        "nextjs": {
+          "output": "export",
+          "assetPrefix": "./",
+          "imagesUnoptimized": true,
+          "postBuildCopy": ["index.txt", "index.html.txt"]
+        }
+      }
+    },
+    "vercel": {
+      "doc": "00-integration/setup.md",
+      "command": "npx cfm-sdk deploy",
+      "prerequisites": ["npm run build passes", "VERCEL_TOKEN or Vercel CLI"]
+    }
+  },
+  "sdkFeatures": {
+    "customFieldLogic": true,
+    "skipLogic": true,
+    "displayLogic": true,
+    "answerLogic": true,
+    "partialSave": true,
+    "markAsStarted": true,
+    "questionActivity": true,
+    "progressBar": true,
+    "placeholderResolution": true,
+    "visibilityHelpers": true,
+    "questionDisplayVariants": true,
+    "questionNumbering": true,
+    "endPageLogic": true
+  },
+  "typeLiterals": [
+    "MCQ",
+    "TEXTFIELD",
+    "NPS_SCALE",
+    "CFM_MATRIX",
+    "CSAT_MATRIX",
+    "RATING_MATRIX",
+    "SLIDER_MATRIX",
+    "FILE_UPLOAD",
+    "TEXT_AND_MEDIA",
+    "HEATMAP",
+    "RANK_ORDER"
+  ],
   "phases": [
     {
       "id": 0,
       "name": "orient",
-      "read": ["index.md", "../AGENT.md"],
-      "actions": ["detectFramework", "extractBrandingFromClientPrompt"]
+      "read": [
+        "index.md",
+        "../AGENT.md"
+      ],
+      "actions": [
+        "detectFramework",
+        "extractBrandingFromClientPrompt"
+      ]
     },
     {
       "id": 1,
       "name": "scaffold",
-      "read": ["00-integration/setup.md"],
-      "frameworks": ["nextjs", "vite", "cra"]
+      "read": [
+        "00-integration/setup.md"
+      ],
+      "frameworks": [
+        "nextjs",
+        "vite",
+        "cra"
+      ]
     },
     {
       "id": 2,
       "name": "instanceId",
-      "read": ["00-integration/useSurveySDK.md"]
+      "read": [
+        "00-integration/useSurveySDK.md"
+      ]
     },
     {
       "id": 3,
       "name": "sdkContract",
-      "read": ["00-integration/useSurveySDK.md"]
+      "read": [
+        "00-integration/client-integration-guide.md",
+        "00-integration/useSurveySDK.md",
+        "00-integration/question-type-sdk-matrix.md",
+        "02-reference/exports.md",
+        "02-reference/value-derivation.md",
+        "00-integration/skip-logic-and-navigation.md",
+        "00-integration/display-logic-and-navigation.md",
+        "00-integration/answer-logic-and-navigation.md",
+        "00-integration/custom-field-logic-and-navigation.md",
+        "00-integration/question-display-variants.md",
+        "00-integration/question-numbering.md",
+        "00-integration/placeholders-and-tokens.md",
+        "00-integration/partial-save-and-recovery.md",
+        "00-integration/survey-lifecycle-analytics.md",
+        "00-integration/end-page-logic.md",
+        "00-integration/progress.md",
+        "00-integration/logic-fields-catalog.md",
+        "00-integration/analytics-events-catalog.md"
+      ]
     },
     {
       "id": 4,
       "name": "planAndIngest",
-      "read": [
+      "readAlways": [
         "00-integration/component-checklist.md",
-        "03-ui-specs/README.md",
-        "01-components/README.md",
+        "00-integration/question-type-sdk-matrix.md",
+        "00-integration/logic-fields-catalog.md",
+        "03-ui-specs/00-question-shell.md",
+        "03-ui-specs/12-survey-chrome.md",
         "01-components/01-survey-page.md",
         "01-components/02-question.md",
-        "01-components/03-rating-scale.md",
-        "01-components/04-csat-scale.md",
-        "01-components/05-csat-matrix-scale.md",
-        "01-components/06-likert-matrix-scale.md",
-        "01-components/07-slider-matrix-scale.md",
-        "01-components/08-file-upload-scale.md",
-        "01-components/09-custom-slider-track.md",
-        "01-components/10-header-footer.md",
-        "01-components/11-progress-bar.md",
-        "01-components/12-language-selector.md",
-        "01-components/13-matrix-dropdown.md"
+        "01-components/14-intro-page.md",
+        "01-components/15-end-page.md",
+        "01-components/16-paused-page.md"
       ],
+      "readPerType": "questionTypes.{type}.blueprint + questionTypes.{type}.reference + questionTypes.{type}.uiSpec",
+      "readSharedWhen": "sharedUiSpecTriggers",
       "template": "templates/implementation_plan.md",
+      "inventorySchema": "templates/survey-inventory.schema.json",
       "questionDispatcher": "templates/Question.tsx",
       "output": "implementation_plan.md"
     },
     {
       "id": 5,
       "name": "build",
-      "read": ["00-integration/constraints.md", "02-reference/routing-table.md"],
+      "read": [
+        "00-integration/constraints.md",
+        "02-reference/routing-table.md"
+      ],
       "onDemand": "02-reference/question-types"
     },
     {
       "id": 6,
       "name": "verify",
-      "read": ["00-integration/constraints.md"],
+      "read": [
+        "00-integration/constraints.md"
+      ],
+      "script": "templates/verify-agent-build.sh",
       "checklist": [
-        "questionDispatcherCoversAll12Types",
-        "matrixRoutesBySubType",
+        "questionDispatcherCoversAll11Types",
+        "flatTypeRoutingNoSubType",
         "noStubPlaceholderText",
         "everyQuestionWrapperHasId",
         "noInternalSdkImports",
-        "surveyPageFiveStates",
-        "npmRunBuildPasses"
+        "surveyPagePhaseRouter",
+        "lifecycleEffectsWired",
+        "placeholdersStableRef",
+        "customFieldValuesStableRef",
+        "customFieldValuesPassedToVisibilityHelpers",
+        "monorepoSdkBuilt",
+        "npmRunBuildPasses",
+        "nextStaticExportConfigured",
+        "outIndexHtmlExists",
+        "outFileCountUnder500",
+        "rankOrderScaleTemplateCopied",
+        "dndKitWhenRankOrder",
+        "fileUploadPresignedFlowWhenFileUpload"
       ]
     },
     {
       "id": 7,
       "name": "deploy",
-      "command": "npx cfm-sdk deploy"
+      "requiresClientConfirmation": true,
+      "selectTargetFromPrompt": {
+        "awsKeywords": ["aws", "cloudfront", "s3", "ec2", "sprinklr"],
+        "default": "vercel"
+      },
+      "targets": {
+        "aws": {
+          "read": [
+            "00-integration/aws-deploy.md",
+            "00-integration/setup.md#nextjs-aws-static-export"
+          ],
+          "script": "templates/deploy-to-aws.sh",
+          "prerequisites": [
+            "phase6VerifyPassed",
+            "npmRunBuildPasses",
+            "instanceIdMatchesSurveyPage"
+          ],
+          "env": {
+            "CFM_DEPLOY_API_BASE": "http://43.204.26.213:3000",
+            "CFM_INSTANCE_ID": "same JWT as SurveyPage SURVEY_INSTANCE_ID",
+            "OUT_DIR": "absolute path to out/ (Next.js) or dist/ (Vite)"
+          },
+          "verifyAfterDeploy": [
+            "indexHtml200",
+            "nestedStaticAssets200",
+            "noRootAbsoluteAssetPaths"
+          ]
+        },
+        "vercel": {
+          "read": [],
+          "command": "npx cfm-sdk deploy",
+          "prerequisites": [
+            "npm run build passes",
+            "VERCEL_TOKEN or Vercel CLI authenticated"
+          ]
+        }
+      }
     }
   ],
   "questionTypes": {
-    "rating": {
-      "component": "01-components/03-rating-scale.md",
-      "reference": "02-reference/question-types/01-rating.md"
+    "nps": {
+      "typeLiteral": "NPS_SCALE",
+      "sdkTypeFile": "fetchSurvey/types/nps.ts",
+      "componentFiles": [
+        "RatingScale.tsx"
+      ],
+      "blueprint": "01-components/03-rating-scale.md",
+      "reference": "02-reference/question-types/01-rating.md",
+      "uiSpec": "03-ui-specs/01-rating.md",
+      "answerShape": "number",
+      "blocking": false
     },
-    "radio": {
-      "component": "01-components/02-question.md",
-      "reference": "02-reference/question-types/README.md#radio"
+    "mcq": {
+      "typeLiteral": "MCQ",
+      "sdkTypeFile": "fetchSurvey/types/mcq.ts",
+      "componentFiles": [],
+      "blueprint": "01-components/02-question.md",
+      "reference": "02-reference/question-types/README.md#mcq",
+      "uiSpec": "03-ui-specs/02-radio.md",
+      "answerShape": "string | number",
+      "blocking": false
     },
-    "text": {
-      "component": "01-components/02-question.md",
-      "reference": "02-reference/question-types/README.md#text"
+    "text_input": {
+      "typeLiteral": "TEXTFIELD",
+      "sdkTypeFile": "fetchSurvey/types/textInput.ts",
+      "componentFiles": [],
+      "blueprint": "01-components/02-question.md",
+      "reference": "02-reference/question-types/README.md#text_input",
+      "uiSpec": "03-ui-specs/03-text.md",
+      "answerShape": "string",
+      "blocking": false
     },
     "csat": {
-      "component": "01-components/04-csat-scale.md",
-      "reference": "02-reference/question-types/04-csat.md"
+      "typeLiteral": "CSAT_MATRIX",
+      "sdkTypeFile": "fetchSurvey/types/csat.ts",
+      "componentFiles": [
+        "CsatMatrixScale.tsx",
+        "MatrixDropdown.tsx",
+        "CustomSliderTrack.tsx"
+      ],
+      "blueprint": "01-components/05-csat-matrix-scale.md",
+      "reference": "02-reference/question-types/04-csat.md",
+      "uiSpec": "03-ui-specs/04-csat.md",
+      "answerShape": "MatrixRowAnswers",
+      "blocking": true
     },
-    "rating_scale": {
-      "component": "01-components/03-rating-scale.md",
-      "reference": "02-reference/question-types/05-rating-scale.md"
+    "star_rating": {
+      "deprecated": true,
+      "typeLiteral": "star_rating",
+      "sdkTypeFile": "fetchSurvey/types/starRating.ts",
+      "componentFiles": [
+        "RatingScale.tsx"
+      ],
+      "blueprint": "01-components/04-star-rating-scale.md",
+      "reference": "02-reference/question-types/05-rating-scale.md",
+      "uiSpec": "03-ui-specs/05-rating-scale.md",
+      "answerShape": "number",
+      "blocking": false
     },
     "slider": {
-      "component": "01-components/09-custom-slider-track.md",
-      "reference": "02-reference/question-types/06-slider.md"
+      "deprecated": true,
+      "typeLiteral": "slider",
+      "sdkTypeFile": "fetchSurvey/types/slider.ts",
+      "componentFiles": [
+        "CustomSliderTrack.tsx"
+      ],
+      "blueprint": "01-components/09-custom-slider-track.md",
+      "reference": "02-reference/question-types/06-slider.md",
+      "uiSpec": "03-ui-specs/06-slider.md",
+      "answerShape": "number",
+      "blocking": false
     },
-    "matrix": {
-      "component": "01-components/06-likert-matrix-scale.md",
+    "cfm_matrix": {
+      "typeLiteral": "CFM_MATRIX",
+      "sdkTypeFile": "fetchSurvey/types/cfmMatrix.ts",
+      "componentFiles": [
+        "LikertMatrixScale.tsx",
+        "MatrixDropdown.tsx"
+      ],
+      "blueprint": "01-components/06-likert-matrix-scale.md",
       "reference": "02-reference/question-types/07-matrix-cfm.md",
-      "subTypes": {
-        "CFM_MATRIX": "01-components/06-likert-matrix-scale.md",
-        "CSAT_MATRIX": "01-components/05-csat-matrix-scale.md",
-        "RATING_MATRIX": "01-components/05-csat-matrix-scale.md"
-      }
+      "uiSpec": "03-ui-specs/07-matrix-cfm.md",
+      "answerShape": "MatrixRowAnswers",
+      "blocking": true
     },
     "rating_matrix": {
-      "component": "01-components/05-csat-matrix-scale.md",
-      "reference": "02-reference/question-types/09-matrix-rating.md"
+      "typeLiteral": "RATING_MATRIX",
+      "sdkTypeFile": "fetchSurvey/types/ratingMatrix.ts",
+      "componentFiles": [
+        "CsatMatrixScale.tsx",
+        "MatrixDropdown.tsx",
+        "CustomSliderTrack.tsx"
+      ],
+      "blueprint": "01-components/05-csat-matrix-scale.md",
+      "reference": "02-reference/question-types/09-matrix-rating.md",
+      "uiSpec": "03-ui-specs/08-matrix-csat-rating.md",
+      "answerShape": "MatrixRowAnswers",
+      "blocking": true
     },
     "slider_matrix": {
-      "component": "01-components/07-slider-matrix-scale.md",
-      "reference": "02-reference/question-types/10-slider-matrix.md"
+      "typeLiteral": "SLIDER_MATRIX",
+      "sdkTypeFile": "fetchSurvey/types/sliderMatrix.ts",
+      "componentFiles": [
+        "SliderMatrixScale.tsx",
+        "CustomSliderTrack.tsx"
+      ],
+      "blueprint": "01-components/07-slider-matrix-scale.md",
+      "reference": "02-reference/question-types/10-slider-matrix.md",
+      "uiSpec": "03-ui-specs/09-slider-matrix.md",
+      "answerShape": "MatrixRowAnswers",
+      "blocking": true
     },
     "file_upload": {
-      "component": "01-components/08-file-upload-scale.md",
-      "reference": "02-reference/question-types/11-file-upload.md"
+      "typeLiteral": "FILE_UPLOAD",
+      "sdkTypeFile": "fetchSurvey/types/fileUpload.ts",
+      "componentFiles": [
+        "FileUploadScale.tsx"
+      ],
+      "blueprint": "01-components/08-file-upload-scale.md",
+      "reference": "02-reference/question-types/11-file-upload.md",
+      "uiSpec": "03-ui-specs/10-file-upload.md",
+      "answerShape": "UploadedFile[]",
+      "blocking": true
     },
     "text_and_media": {
-      "component": "01-components/02-question.md",
-      "reference": "02-reference/question-types/README.md#text_and_media"
+      "typeLiteral": "TEXT_AND_MEDIA",
+      "sdkTypeFile": "fetchSurvey/types/textAndMedia.ts",
+      "componentFiles": [],
+      "blueprint": "01-components/02-question.md",
+      "reference": "02-reference/question-types/README.md#text_and_media",
+      "uiSpec": "03-ui-specs/11-text-and-media.md",
+      "answerShape": "none",
+      "blocking": false
+    },
+    "heatmap": {
+      "typeLiteral": "HEATMAP",
+      "sdkTypeFile": "fetchSurvey/types/heatmap.ts",
+      "componentFiles": [
+        "HeatmapScale.tsx"
+      ],
+      "blueprint": "01-components/17-heatmap-scale.md",
+      "reference": "02-reference/question-types/12-heatmap.md",
+      "uiSpec": "03-ui-specs/13-heatmap.md",
+      "answerShape": "HeatmapAnswer",
+      "blocking": false
+    },
+    "rank_order": {
+      "typeLiteral": "RANK_ORDER",
+      "sdkTypeFile": "fetchSurvey/types/rankOrder.ts",
+      "componentFiles": [
+        "RankOrderScale.tsx"
+      ],
+      "blueprint": "01-components/18-rank-order-scale.md",
+      "reference": "02-reference/question-types/13-rank-order.md",
+      "uiSpec": "03-ui-specs/14-rank-order.md",
+      "answerShape": "RankOrderAnswers",
+      "blocking": false
     }
   },
   "uiSpecs": {
     "questionShell": "03-ui-specs/00-question-shell.md",
-    "rating": "03-ui-specs/01-rating.md",
-    "radio": "03-ui-specs/02-radio.md",
-    "text": "03-ui-specs/03-text.md",
+    "nps": "03-ui-specs/01-rating.md",
+    "mcq": "03-ui-specs/02-radio.md",
+    "text_input": "03-ui-specs/03-text.md",
     "csat": "03-ui-specs/04-csat.md",
-    "rating_scale": "03-ui-specs/05-rating-scale.md",
+    "star_rating": "03-ui-specs/05-rating-scale.md",
     "slider": "03-ui-specs/06-slider.md",
-    "matrix_CFM_MATRIX": "03-ui-specs/07-matrix-cfm.md",
-    "matrix_CSAT_MATRIX": "03-ui-specs/08-matrix-csat-rating.md",
-    "matrix_RATING_MATRIX": "03-ui-specs/08-matrix-csat-rating.md",
+    "cfm_matrix": "03-ui-specs/07-matrix-cfm.md",
+    "rating_matrix": "03-ui-specs/08-matrix-csat-rating.md",
     "slider_matrix": "03-ui-specs/09-slider-matrix.md",
     "file_upload": "03-ui-specs/10-file-upload.md",
     "text_and_media": "03-ui-specs/11-text-and-media.md",
+    "heatmap": "03-ui-specs/13-heatmap.md",
+    "rank_order": "03-ui-specs/14-rank-order.md",
     "surveyChrome": "03-ui-specs/12-survey-chrome.md"
   },
   "sharedUiSpecs": {
     "customSliderTrack": "03-ui-specs/shared/custom-slider-track.md",
     "matrixDropdown": "03-ui-specs/shared/matrix-dropdown.md"
   },
-  "configFieldIndex": "02-reference/config-field-index.md"
+  "sharedUiSpecTriggers": {
+    "gridLayout:dropdown": [
+      "matrixDropdown"
+    ],
+    "displayStyle:dropdown": [
+      "matrixDropdown"
+    ],
+    "displayStyle:selectbox": [
+      "matrixDropdown"
+    ],
+    "displayStyle:graphics": [
+      "customSliderTrack"
+    ],
+    "statementLayout:bipolar": []
+  },
+  "configFieldIndex": "02-reference/config-field-index.md",
+  "verify": {
+    "grepStubText": "grep -r \"not yet implemented\" src/ components/ app/ 2>/dev/null || true",
+    "grepInternalImports": "grep -r \"@explorer02/cfm-survey-sdk/src\\|@repo/sdk/src\" src/ components/ app/ 2>/dev/null || true",
+    "requiredDispatcherTypes": [
+      "MCQ",
+      "TEXTFIELD",
+      "NPS_SCALE",
+      "CFM_MATRIX",
+      "CSAT_MATRIX",
+      "RATING_MATRIX",
+      "SLIDER_MATRIX",
+      "FILE_UPLOAD",
+      "TEXT_AND_MEDIA",
+      "HEATMAP",
+      "RANK_ORDER"
+    ]
+  },
+  "doNotRead": [
+    "packages/sdk/src/**",
+    "node_modules/@explorer02/cfm-survey-sdk/src/**"
+  ]
 }