vidspotai-shared 1.0.95 → 1.0.96

package/lib/schemas/demoQuestion.schema.d.ts

@@ -0,0 +1,286 @@
+import { z } from "zod";
+/**
+ * DemoQuestion — the contract for the demo generator's DYNAMIC clarifying
+ * questions (the "agent asks only when it needs to" loop, plan §clarification).
+ *
+ * ONE contract, TWO surfaces:
+ *   - PRE-GEN triage: on Generate, a cheap LLM pass inspects the website + inputs
+ *     and, only if it genuinely helps, returns questions the wizard renders inline
+ *     before any real spend.
+ *   - MID-RUN pause: the worker may pause (status AWAITING_INPUT) and surface the
+ *     same shape on the result page, resuming on answer (modeled on the agent
+ *     approval gate — worker returns + a user action re-enqueues).
+ *
+ * The frontend has ONE renderer for all of this; the value of every answer is
+ * `string | string[] | boolean` (see IDemoClarifyAnswerValue), so a single
+ * `Record<questionId, value>` map round-trips every kind.
+ *
+ * The LLM triage MUST emit output matching `DemoQuestionsSchema`; the answer
+ * endpoints validate the returned map is well-formed against the pending set.
+ */
+/** One selectable option for a single/multi-select question. */
+export declare const DemoQuestionOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DemoQuestionOption = z.infer<typeof DemoQuestionOptionSchema>;
+/** Pick exactly one option. */
+export declare const SingleSelectQuestionSchema: z.ZodObject<{
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    allowOther: z.ZodDefault<z.ZodBoolean>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"single">;
+}, z.core.$strip>;
+/** Pick any number of options. */
+export declare const MultiSelectQuestionSchema: z.ZodObject<{
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    allowOther: z.ZodDefault<z.ZodBoolean>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"multi">;
+}, z.core.$strip>;
+/** A yes/no toggle. The answer is a boolean. */
+export declare const ToggleQuestionSchema: z.ZodObject<{
+    default: z.ZodDefault<z.ZodBoolean>;
+    onLabel: z.ZodOptional<z.ZodString>;
+    offLabel: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"toggle">;
+}, z.core.$strip>;
+/** A typed free-text answer (short line or paragraph). */
+export declare const TextQuestionSchema: z.ZodObject<{
+    placeholder: z.ZodOptional<z.ZodString>;
+    multiline: z.ZodDefault<z.ZodBoolean>;
+    maxLength: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"text">;
+}, z.core.$strip>;
+/**
+ * A file-upload ask (the answer is the uploaded file's public URL, or an array
+ * of URLs when `multiple`). Used by the worker's deterministic asset asks —
+ * "we couldn't find your logo / any screenshots, add them?" — always optional:
+ * a skip means "generate with what we have" (asset asks never block a run).
+ * The frontend uploads via /v1/media/single-upload and answers with the URLs.
+ */
+export declare const UploadQuestionSchema: z.ZodObject<{
+    accept: z.ZodDefault<z.ZodLiteral<"image">>;
+    multiple: z.ZodDefault<z.ZodBoolean>;
+    maxFiles: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"upload">;
+}, z.core.$strip>;
+export declare const DemoQuestionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    allowOther: z.ZodDefault<z.ZodBoolean>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"single">;
+}, z.core.$strip>, z.ZodObject<{
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    allowOther: z.ZodDefault<z.ZodBoolean>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"multi">;
+}, z.core.$strip>, z.ZodObject<{
+    default: z.ZodDefault<z.ZodBoolean>;
+    onLabel: z.ZodOptional<z.ZodString>;
+    offLabel: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"toggle">;
+}, z.core.$strip>, z.ZodObject<{
+    placeholder: z.ZodOptional<z.ZodString>;
+    multiline: z.ZodDefault<z.ZodBoolean>;
+    maxLength: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"text">;
+}, z.core.$strip>, z.ZodObject<{
+    accept: z.ZodDefault<z.ZodLiteral<"image">>;
+    multiple: z.ZodDefault<z.ZodBoolean>;
+    maxFiles: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"upload">;
+}, z.core.$strip>], "kind">;
+export type DemoQuestion = z.infer<typeof DemoQuestionSchema>;
+export type DemoQuestionKind = DemoQuestion["kind"];
+/** The full set the agent asks in one round. Capped so we never wall the user. */
+export declare const DemoQuestionsSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    allowOther: z.ZodDefault<z.ZodBoolean>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"single">;
+}, z.core.$strip>, z.ZodObject<{
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    allowOther: z.ZodDefault<z.ZodBoolean>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"multi">;
+}, z.core.$strip>, z.ZodObject<{
+    default: z.ZodDefault<z.ZodBoolean>;
+    onLabel: z.ZodOptional<z.ZodString>;
+    offLabel: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"toggle">;
+}, z.core.$strip>, z.ZodObject<{
+    placeholder: z.ZodOptional<z.ZodString>;
+    multiline: z.ZodDefault<z.ZodBoolean>;
+    maxLength: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"text">;
+}, z.core.$strip>, z.ZodObject<{
+    accept: z.ZodDefault<z.ZodLiteral<"image">>;
+    multiple: z.ZodDefault<z.ZodBoolean>;
+    maxFiles: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodString;
+    prompt: z.ZodString;
+    help: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    kind: z.ZodLiteral<"upload">;
+}, z.core.$strip>], "kind">>;
+export type DemoQuestions = z.infer<typeof DemoQuestionsSchema>;
+/**
+ * The triage LLM's decision: whether to ask at all, and if so what. `ask:false`
+ * (the common case for a clear brief) means "no questions — just generate".
+ */
+export declare const DemoTriageResultSchema: z.ZodObject<{
+    ask: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodString>;
+    questions: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        allowOther: z.ZodDefault<z.ZodBoolean>;
+        id: z.ZodString;
+        prompt: z.ZodString;
+        help: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        kind: z.ZodLiteral<"single">;
+    }, z.core.$strip>, z.ZodObject<{
+        options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        allowOther: z.ZodDefault<z.ZodBoolean>;
+        id: z.ZodString;
+        prompt: z.ZodString;
+        help: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        kind: z.ZodLiteral<"multi">;
+    }, z.core.$strip>, z.ZodObject<{
+        default: z.ZodDefault<z.ZodBoolean>;
+        onLabel: z.ZodOptional<z.ZodString>;
+        offLabel: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        prompt: z.ZodString;
+        help: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        kind: z.ZodLiteral<"toggle">;
+    }, z.core.$strip>, z.ZodObject<{
+        placeholder: z.ZodOptional<z.ZodString>;
+        multiline: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        id: z.ZodString;
+        prompt: z.ZodString;
+        help: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        kind: z.ZodLiteral<"text">;
+    }, z.core.$strip>, z.ZodObject<{
+        accept: z.ZodDefault<z.ZodLiteral<"image">>;
+        multiple: z.ZodDefault<z.ZodBoolean>;
+        maxFiles: z.ZodDefault<z.ZodNumber>;
+        id: z.ZodString;
+        prompt: z.ZodString;
+        help: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        kind: z.ZodLiteral<"upload">;
+    }, z.core.$strip>], "kind">>>;
+}, z.core.$strip>;
+export type DemoTriageResult = z.infer<typeof DemoTriageResultSchema>;
+/**
+ * Validate a raw answer map (questionId → value) against a pending question set:
+ * drops answers with no matching question, coerces each value to the shape its
+ * question expects, and enforces `required`. Returns the cleaned map (safe to
+ * persist) or a list of problems. Kept dependency-free so both the Cloud Function
+ * endpoint and the worker can call it.
+ */
+export declare function validateClarifyAnswers(questions: DemoQuestion[], raw: Record<string, unknown>): {
+    ok: true;
+    answers: Record<string, string | string[] | boolean>;
+} | {
+    ok: false;
+    errors: string[];
+};
+//# sourceMappingURL=demoQuestion.schema.d.ts.map

package/lib/schemas/demoQuestion.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demoQuestion.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/demoQuestion.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,gEAAgE;AAChE,eAAO,MAAM,wBAAwB;;;;iBAOnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAc1E,+BAA+B;AAC/B,eAAO,MAAM,0BAA0B;;;;;;;;;;;;iBAMrC,CAAC;AAEH,kCAAkC;AAClC,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;iBAQpC,CAAC;AAEH,gDAAgD;AAChD,eAAO,MAAM,oBAAoB;;;;;;;;;iBAQ/B,CAAC;AAEH,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB;;;;;;;;;iBAO7B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;iBAS/B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAM7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;AAEpD,kFAAkF;AAClF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAAqC,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAOjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,YAAY,EAAE,EACzB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAmFtG"}

package/lib/schemas/demoQuestion.schema.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DemoTriageResultSchema = exports.DemoQuestionsSchema = exports.DemoQuestionSchema = exports.UploadQuestionSchema = exports.TextQuestionSchema = exports.ToggleQuestionSchema = exports.MultiSelectQuestionSchema = exports.SingleSelectQuestionSchema = exports.DemoQuestionOptionSchema = void 0;
+exports.validateClarifyAnswers = validateClarifyAnswers;
+const zod_1 = require("zod");
+/**
+ * DemoQuestion — the contract for the demo generator's DYNAMIC clarifying
+ * questions (the "agent asks only when it needs to" loop, plan §clarification).
+ *
+ * ONE contract, TWO surfaces:
+ *   - PRE-GEN triage: on Generate, a cheap LLM pass inspects the website + inputs
+ *     and, only if it genuinely helps, returns questions the wizard renders inline
+ *     before any real spend.
+ *   - MID-RUN pause: the worker may pause (status AWAITING_INPUT) and surface the
+ *     same shape on the result page, resuming on answer (modeled on the agent
+ *     approval gate — worker returns + a user action re-enqueues).
+ *
+ * The frontend has ONE renderer for all of this; the value of every answer is
+ * `string | string[] | boolean` (see IDemoClarifyAnswerValue), so a single
+ * `Record<questionId, value>` map round-trips every kind.
+ *
+ * The LLM triage MUST emit output matching `DemoQuestionsSchema`; the answer
+ * endpoints validate the returned map is well-formed against the pending set.
+ */
+/** One selectable option for a single/multi-select question. */
+exports.DemoQuestionOptionSchema = zod_1.z.object({
+    /** Stable machine value stored in the answer (e.g. "premium"). */
+    value: zod_1.z.string().min(1).max(120),
+    /** Human label shown on the chip/button (e.g. "Premium & cinematic"). */
+    label: zod_1.z.string().min(1).max(120),
+    /** Optional one-line helper under the label. */
+    description: zod_1.z.string().max(240).optional(),
+});
+/** Fields every question shares regardless of kind. */
+const QuestionBase = {
+    /** Stable id — the key the answer is stored under. */
+    id: zod_1.z.string().min(1).max(64),
+    /** The question text shown to the user. */
+    prompt: zod_1.z.string().min(1).max(400),
+    /** Optional secondary help / why-we're-asking line. */
+    help: zod_1.z.string().max(400).optional(),
+    /** If false (default), the user may skip it → the planner decides. */
+    required: zod_1.z.boolean().default(false),
+};
+/** Pick exactly one option. */
+exports.SingleSelectQuestionSchema = zod_1.z.object({
+    kind: zod_1.z.literal("single"),
+    ...QuestionBase,
+    options: zod_1.z.array(exports.DemoQuestionOptionSchema).min(2).max(8),
+    /** Allow a free-text "Other" answer beyond the listed options. */
+    allowOther: zod_1.z.boolean().default(false),
+});
+/** Pick any number of options. */
+exports.MultiSelectQuestionSchema = zod_1.z.object({
+    kind: zod_1.z.literal("multi"),
+    ...QuestionBase,
+    options: zod_1.z.array(exports.DemoQuestionOptionSchema).min(2).max(12),
+    /** Optional selection bounds for UI validation. */
+    min: zod_1.z.number().int().min(0).optional(),
+    max: zod_1.z.number().int().min(1).optional(),
+    allowOther: zod_1.z.boolean().default(false),
+});
+/** A yes/no toggle. The answer is a boolean. */
+exports.ToggleQuestionSchema = zod_1.z.object({
+    kind: zod_1.z.literal("toggle"),
+    ...QuestionBase,
+    /** Pre-checked state. */
+    default: zod_1.z.boolean().default(false),
+    /** Optional labels for the on/off states (default "Yes"/"No"). */
+    onLabel: zod_1.z.string().max(60).optional(),
+    offLabel: zod_1.z.string().max(60).optional(),
+});
+/** A typed free-text answer (short line or paragraph). */
+exports.TextQuestionSchema = zod_1.z.object({
+    kind: zod_1.z.literal("text"),
+    ...QuestionBase,
+    placeholder: zod_1.z.string().max(160).optional(),
+    /** Render a multi-line textarea instead of a single input. */
+    multiline: zod_1.z.boolean().default(false),
+    maxLength: zod_1.z.number().int().min(1).max(2000).default(500),
+});
+/**
+ * A file-upload ask (the answer is the uploaded file's public URL, or an array
+ * of URLs when `multiple`). Used by the worker's deterministic asset asks —
+ * "we couldn't find your logo / any screenshots, add them?" — always optional:
+ * a skip means "generate with what we have" (asset asks never block a run).
+ * The frontend uploads via /v1/media/single-upload and answers with the URLs.
+ */
+exports.UploadQuestionSchema = zod_1.z.object({
+    kind: zod_1.z.literal("upload"),
+    ...QuestionBase,
+    /** What the picker should accept. Only images are needed so far. */
+    accept: zod_1.z.literal("image").default("image"),
+    /** Allow more than one file (answer becomes string[]). */
+    multiple: zod_1.z.boolean().default(false),
+    /** Upper bound when `multiple`. */
+    maxFiles: zod_1.z.number().int().min(1).max(6).default(1),
+});
+exports.DemoQuestionSchema = zod_1.z.discriminatedUnion("kind", [
+    exports.SingleSelectQuestionSchema,
+    exports.MultiSelectQuestionSchema,
+    exports.ToggleQuestionSchema,
+    exports.TextQuestionSchema,
+    exports.UploadQuestionSchema,
+]);
+/** The full set the agent asks in one round. Capped so we never wall the user. */
+exports.DemoQuestionsSchema = zod_1.z.array(exports.DemoQuestionSchema).max(6);
+/**
+ * The triage LLM's decision: whether to ask at all, and if so what. `ask:false`
+ * (the common case for a clear brief) means "no questions — just generate".
+ */
+exports.DemoTriageResultSchema = zod_1.z.object({
+    /** Whether the agent has anything worth clarifying. */
+    ask: zod_1.z.boolean(),
+    /** One-line rationale shown above the questions ("A few quick calls to nail the vibe"). */
+    reason: zod_1.z.string().max(240).optional(),
+    /** The questions to ask; empty/omitted when `ask` is false. */
+    questions: exports.DemoQuestionsSchema.default([]),
+});
+/**
+ * Validate a raw answer map (questionId → value) against a pending question set:
+ * drops answers with no matching question, coerces each value to the shape its
+ * question expects, and enforces `required`. Returns the cleaned map (safe to
+ * persist) or a list of problems. Kept dependency-free so both the Cloud Function
+ * endpoint and the worker can call it.
+ */
+function validateClarifyAnswers(questions, raw) {
+    const errors = [];
+    const answers = {};
+    const byId = new Map(questions.map((q) => [q.id, q]));
+    for (const q of questions) {
+        const v = raw[q.id];
+        const missing = v === undefined || v === null || v === "" || (Array.isArray(v) && v.length === 0);
+        if (missing) {
+            if (q.required)
+                errors.push(`"${q.prompt}" is required.`);
+            continue;
+        }
+        switch (q.kind) {
+            case "single": {
+                if (typeof v !== "string") {
+                    errors.push(`"${q.prompt}" expects a single choice.`);
+                    break;
+                }
+                const known = q.options.some((o) => o.value === v);
+                if (!known && !q.allowOther) {
+                    errors.push(`"${v}" is not a valid option for "${q.prompt}".`);
+                    break;
+                }
+                answers[q.id] = v;
+                break;
+            }
+            case "multi": {
+                const arr = Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+                if (arr.length === 0) {
+                    errors.push(`"${q.prompt}" expects one or more choices.`);
+                    break;
+                }
+                const clean = q.allowOther ? arr : arr.filter((x) => q.options.some((o) => o.value === x));
+                if (typeof q.min === "number" && clean.length < q.min) {
+                    errors.push(`Pick at least ${q.min} for "${q.prompt}".`);
+                    break;
+                }
+                if (typeof q.max === "number" && clean.length > q.max) {
+                    errors.push(`Pick at most ${q.max} for "${q.prompt}".`);
+                    break;
+                }
+                answers[q.id] = clean;
+                break;
+            }
+            case "toggle": {
+                answers[q.id] = Boolean(v);
+                break;
+            }
+            case "text": {
+                if (typeof v !== "string") {
+                    errors.push(`"${q.prompt}" expects text.`);
+                    break;
+                }
+                answers[q.id] = v.slice(0, q.maxLength);
+                break;
+            }
+            case "upload": {
+                const isUrl = (x) => typeof x === "string" && /^https?:\/\//i.test(x);
+                if (q.multiple) {
+                    const arr = Array.isArray(v) ? v.filter(isUrl) : isUrl(v) ? [v] : [];
+                    if (arr.length === 0) {
+                        errors.push(`"${q.prompt}" expects uploaded file URL(s).`);
+                        break;
+                    }
+                    answers[q.id] = arr.slice(0, q.maxFiles);
+                }
+                else {
+                    const one = isUrl(v) ? v : Array.isArray(v) && isUrl(v[0]) ? v[0] : undefined;
+                    if (!one) {
+                        errors.push(`"${q.prompt}" expects an uploaded file URL.`);
+                        break;
+                    }
+                    answers[q.id] = one;
+                }
+                break;
+            }
+        }
+    }
+    // Ignore any answers for ids we never asked (defensive against stale clients).
+    void byId;
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, answers };
+}