@cxpinsight/survey-spec 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -16,5 +16,7 @@ export { splitIntoPages } from './pageFlow';
 export { validateAnswer } from './validate';
 export type { ValidatableQuestion } from './validate';
 export type { Page, PageItem, PageFlowOptions, FlowQuestion, FlowSection } from './pageFlow';
+export { normalizeTranscript, matchBoolean, matchOption, matchOptions, rankOptions, matchNumberInRange, matchDate, distinctiveLabels, voiceSupport, voiceCanHandle, auditVoiceQuestions, voiceDisclaimer, skipNoteText, scaffoldFor, buildPromptText, shortCode, optionLabelOf, optionValueOf, voiceOptionsOf, optionLabelsOf, } from './voice';
+export type { VoiceSupport, VoiceQuestion, VoiceOption, VoiceScaffold } from './voice';
 export type { AnswersMap, VariablesMap, EvalContext } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC7F,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EACL,mBAAmB,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EACzE,kBAAkB,EAAE,SAAS,EAAE,iBAAiB,EAChD,YAAY,EAAE,cAAc,EAAE,mBAAmB,EACjD,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EACtE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,GAC7D,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACvF,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateAnswer = exports.splitIntoPages = exports.resolveVariable = exports.isParseable = exports.evaluateCondition = exports.evaluateExpression = void 0;
+exports.optionLabelsOf = exports.voiceOptionsOf = exports.optionValueOf = exports.optionLabelOf = exports.shortCode = exports.buildPromptText = exports.scaffoldFor = exports.skipNoteText = exports.voiceDisclaimer = exports.auditVoiceQuestions = exports.voiceCanHandle = exports.voiceSupport = exports.distinctiveLabels = exports.matchDate = exports.matchNumberInRange = exports.rankOptions = exports.matchOptions = exports.matchOption = exports.matchBoolean = exports.normalizeTranscript = exports.validateAnswer = exports.splitIntoPages = exports.resolveVariable = exports.isParseable = exports.evaluateCondition = exports.evaluateExpression = void 0;
 /**
  * @cxpinsight/survey-spec
  *
@@ -23,3 +23,24 @@ var pageFlow_1 = require("./pageFlow");
 Object.defineProperty(exports, "splitIntoPages", { enumerable: true, get: function () { return pageFlow_1.splitIntoPages; } });
 var validate_1 = require("./validate");
 Object.defineProperty(exports, "validateAnswer", { enumerable: true, get: function () { return validate_1.validateAnswer; } });
+var voice_1 = require("./voice");
+Object.defineProperty(exports, "normalizeTranscript", { enumerable: true, get: function () { return voice_1.normalizeTranscript; } });
+Object.defineProperty(exports, "matchBoolean", { enumerable: true, get: function () { return voice_1.matchBoolean; } });
+Object.defineProperty(exports, "matchOption", { enumerable: true, get: function () { return voice_1.matchOption; } });
+Object.defineProperty(exports, "matchOptions", { enumerable: true, get: function () { return voice_1.matchOptions; } });
+Object.defineProperty(exports, "rankOptions", { enumerable: true, get: function () { return voice_1.rankOptions; } });
+Object.defineProperty(exports, "matchNumberInRange", { enumerable: true, get: function () { return voice_1.matchNumberInRange; } });
+Object.defineProperty(exports, "matchDate", { enumerable: true, get: function () { return voice_1.matchDate; } });
+Object.defineProperty(exports, "distinctiveLabels", { enumerable: true, get: function () { return voice_1.distinctiveLabels; } });
+Object.defineProperty(exports, "voiceSupport", { enumerable: true, get: function () { return voice_1.voiceSupport; } });
+Object.defineProperty(exports, "voiceCanHandle", { enumerable: true, get: function () { return voice_1.voiceCanHandle; } });
+Object.defineProperty(exports, "auditVoiceQuestions", { enumerable: true, get: function () { return voice_1.auditVoiceQuestions; } });
+Object.defineProperty(exports, "voiceDisclaimer", { enumerable: true, get: function () { return voice_1.voiceDisclaimer; } });
+Object.defineProperty(exports, "skipNoteText", { enumerable: true, get: function () { return voice_1.skipNoteText; } });
+Object.defineProperty(exports, "scaffoldFor", { enumerable: true, get: function () { return voice_1.scaffoldFor; } });
+Object.defineProperty(exports, "buildPromptText", { enumerable: true, get: function () { return voice_1.buildPromptText; } });
+Object.defineProperty(exports, "shortCode", { enumerable: true, get: function () { return voice_1.shortCode; } });
+Object.defineProperty(exports, "optionLabelOf", { enumerable: true, get: function () { return voice_1.optionLabelOf; } });
+Object.defineProperty(exports, "optionValueOf", { enumerable: true, get: function () { return voice_1.optionValueOf; } });
+Object.defineProperty(exports, "voiceOptionsOf", { enumerable: true, get: function () { return voice_1.voiceOptionsOf; } });
+Object.defineProperty(exports, "optionLabelsOf", { enumerable: true, get: function () { return voice_1.optionLabelsOf; } });

package/dist/pageFlow.d.ts

@@ -35,12 +35,6 @@ export interface PageFlowOptions {
      */
     flow?: string | null;
     presentationMode?: string;
-    /**
-     * Typeform / conversation only. See the header: this is an open product
-     * decision, carried as a parameter so neither channel changes under the
-     * other's rule before it is made.
-     */
-    typeformSections?: 'per-section' | 'per-question';
 }
 export declare function splitIntoPages<Q extends FlowQuestion = FlowQuestion, S extends FlowSection = FlowSection>(survey: {
     questions?: Q[];

package/dist/pageFlow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pageFlow.d.ts","sourceRoot":"","sources":["../src/pageFlow.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAK3C,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,CAAC,SAAS,WAAW,GAAG,WAAW,IAC3F;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,CAAC,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAE5C,MAAM,WAAW,IAAI,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,CAAC,SAAS,WAAW,GAAG,WAAW;IAC9F,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACxB,SAAS,EAAE,CAAC,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,aAAa,GAAG,cAAc,CAAC;CACnD;AAoBD,wBAAgB,cAAc,CAC5B,CAAC,SAAS,YAAY,GAAG,YAAY,EACrC,CAAC,SAAS,WAAW,GAAG,WAAW,EAEnC,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAA;CAAE,EAC3C,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,eAAoB,GAC5B,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAyEd"}
+{"version":3,"file":"pageFlow.d.ts","sourceRoot":"","sources":["../src/pageFlow.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAK3C,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,CAAC,SAAS,WAAW,GAAG,WAAW,IAC3F;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,CAAC,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAE5C,MAAM,WAAW,IAAI,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,CAAC,SAAS,WAAW,GAAG,WAAW;IAC9F,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACxB,SAAS,EAAE,CAAC,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAoBD,wBAAgB,cAAc,CAC5B,CAAC,SAAS,YAAY,GAAG,YAAY,EACrC,CAAC,SAAS,WAAW,GAAG,WAAW,EAEnC,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAA;CAAE,EAC3C,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,eAAoB,GAC5B,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CA+Dd"}

package/dist/pageFlow.js

@@ -24,13 +24,21 @@ exports.splitIntoPages = splitIntoPages;
  *     are honoured, not just `hidden`. Mobile ignored them, so a section
  *     conditioned away still split pages there.
  *
- * The third is a product decision, not a defect, so it is a PARAMETER rather
- * than a silent choice: in typeform and conversation modes, does a section
- * become one page, or does each of its questions get its own? React has always
- * done per-section; mobile has always done per-question, and says so in its own
- * comments. Encoding either one here would change page counts on live surveys
- * for whichever channel lost, so `typeformSections` carries the difference in
- * the open until someone decides.
+ * The third was a product decision rather than a defect, and it has been made:
+ * in typeform and conversation modes each question gets its own page, and a
+ * section does not group them. That is mobile's long-standing behaviour and
+ * matches what the builder does — it hides the add-page control in these modes
+ * and turns section headers into intro pages, so the author is already working
+ * one question at a time.
+ *
+ * It carried a `typeformSections` parameter while the question was open. The
+ * parameter is gone now the answer exists: a configurable behaviour nobody
+ * configures is a second code path that only gets exercised by accident.
+ *
+ * REACT CHANGES because of this. A typeform survey whose questions are grouped
+ * into sections previously showed one page per section there and now shows one
+ * per question, so its page count goes up and its progress bar moves in smaller
+ * steps. Mobile is unaffected.
  */
 const expressionEval_1 = require("./expressionEval");
 const isPageBreak = (q) => String(q.type || '').toLowerCase() === 'pagebreak';
@@ -54,35 +62,21 @@ function activeSections(sections, ctx) {
     return { claimed, active };
 }
 function splitIntoPages(survey, ctx, options = {}) {
-    const { flow, presentationMode, typeformSections = 'per-section' } = options;
+    const { flow, presentationMode } = options;
     const raw = survey.questions || [];
     const all = flow === null
         ? raw
         : raw.filter((q) => (q.flow || undefined) === (flow || undefined));
     const sections = survey.sections || [];
     const { claimed, active } = activeSections(sections, ctx);
+    // One question per page. Sections do not group in these modes — see the
+    // header. `claimed` is still computed above because section conditions can
+    // hide a question's section, and a question whose section is skipped still
+    // renders; it just gets its own page like every other.
     if (presentationMode === 'typeform' || presentationMode === 'conversation') {
-        const pages = [];
-        const emitted = new Set();
-        for (const q of all) {
-            if (isPageBreak(q))
-                continue;
-            const sid = typeformSections === 'per-section' ? claimed.get(q.id) : undefined;
-            if (sid) {
-                if (emitted.has(sid))
-                    continue;
-                const section = active.get(sid);
-                if (!section)
-                    continue;
-                const qs = all.filter((qq) => claimed.get(qq.id) === sid && !isPageBreak(qq));
-                pages.push({ section, items: qs.map((qq) => ({ kind: 'question', question: qq })), questions: qs });
-                emitted.add(sid);
-            }
-            else {
-                pages.push({ items: [{ kind: 'question', question: q }], questions: [q] });
-            }
-        }
-        return pages;
+        return all
+            .filter((q) => !isPageBreak(q))
+            .map((q) => ({ items: [{ kind: 'question', question: q }], questions: [q] }));
     }
     const pages = [];
     const emitted = new Set();

package/dist/voice.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Turning speech into an answer.
+ *
+ * This is the point where a respondent's VOICE becomes stored data, and a
+ * divergence between channels is invisible afterwards: the row looks fine, it
+ * is just a different value than the same sentence produced somewhere else.
+ * Three implementations existed — the React renderer's handsFreeVoice.tsx, the
+ * web SDK's voice.js (ported from it) and the mobile renderer's
+ * voiceParsers.ts (an older, stricter copy). Mobile had drifted: no fuzzy
+ * tolerance, no filler stripping, no letter shortcuts, no Arabic orthographic
+ * folding, English-only ordinals. "grean" for Green resolved on a link and on
+ * a website and failed on the phone, which is the channel where hands-free
+ * matters most.
+ *
+ * ── The seam ─────────────────────────────────────────────────────────────
+ *
+ * These functions return an option INDEX, never an answer. That is deliberate.
+ * The three renderers genuinely disagree about answer shape and are each right
+ * about their own: React's radio widget stores `{ choice: value }` and
+ * normalises it at submit, web and mobile store the bare value. A shared
+ * function returning "the answer" would have to pick one and break two.
+ * Matching a sentence to an option is the part that must be identical;
+ * wrapping an index in a shape is the part that must not be.
+ *
+ * tools/survey-conformance/voice.js runs the same spoken answers through all
+ * three and fails on any disagreement.
+ */
+export declare function shortCode(lang?: string): string;
+/** Lower-case, fold Arabic orthography, strip punctuation, normalise spelling. */
+export declare function normalizeTranscript(s: unknown): string;
+/**
+ * Strip the prefix every option shares, so "Option A / Option B / Option C"
+ * reduces to "a" / "b" / "c" and a respondent who just says "C" is understood.
+ */
+export declare function distinctiveLabels(labels: string[]): string[];
+export interface VoiceOption {
+    value?: unknown;
+    label?: string;
+    text?: string;
+    alt?: string;
+}
+export interface VoiceQuestion {
+    type?: string;
+    title?: string;
+    text?: string;
+    label?: string;
+    options?: unknown;
+    choices?: unknown;
+    yesLabel?: string;
+    noLabel?: string;
+    minValue?: number;
+    maxValue?: number;
+    minLabel?: string;
+    maxLabel?: string;
+    isRequired?: boolean;
+    required?: boolean;
+}
+export declare function optionLabelOf(o: VoiceOption): string;
+export declare function optionValueOf(o: VoiceOption): unknown;
+export declare function voiceOptionsOf(q: VoiceQuestion): VoiceOption[];
+export declare function optionLabelsOf(q: VoiceQuestion): string[];
+/** Yes/no, including the question's own yes/no labels. `null` = neither. */
+export declare function matchBoolean(q: VoiceQuestion, transcript: string): boolean | null;
+/** Single choice. Returns the option index, or -1 when nothing matched. */
+export declare function matchOption(q: VoiceQuestion, transcript: string): number;
+/** Multi-choice. Returns ascending option indices; empty when nothing matched. */
+export declare function matchOptions(q: VoiceQuestion, transcript: string): number[];
+/**
+ * Ranking. Returns option indices in the order they were spoken, or an empty
+ * array when fewer than two were heard — one name is not a ranking.
+ */
+export declare function rankOptions(q: VoiceQuestion, transcript: string): number[];
+/** A number inside [min, max], from digits, number words, or a homophone. */
+export declare function matchNumberInRange(transcript: string, min: number, max: number): number | null;
+/** A spoken date as ISO `YYYY-MM-DD`, or null. */
+export declare function matchDate(transcript: string): string | null;
+/**
+ * What a hands-free session can do with a question type.
+ *
+ *   full   — speak the scaffold, capture, parse into a value.
+ *   matrix — walk it row by row; each row is a single choice.
+ *   read   — display-only. Read it and advance; there is nothing to capture.
+ *   assist — read it aloud, then hand off to the visual UI. The respondent can
+ *            answer, just not by speaking.
+ *   none   — voice cannot produce this answer at all (a signature, a file).
+ *
+ * `assist` and `none` are one bucket to web and mobile, which collapse both to
+ * 'partial'. They are separate here because React distinguishes them and the
+ * spec should not force a renderer to lose a distinction it makes.
+ */
+export type VoiceSupport = 'full' | 'matrix' | 'read' | 'assist' | 'none';
+export declare function voiceSupport(type: string): VoiceSupport;
+/** Can a voice-only session get through this question unaided? */
+export declare function voiceCanHandle(type: string): boolean;
+/**
+ * blocking  = required questions voice can't handle → the session must not start.
+ * skippable = optional ones → announced and skipped.
+ */
+export declare function auditVoiceQuestions<Q extends VoiceQuestion>(questions: Q[]): {
+    blocking: Q[];
+    skippable: Q[];
+};
+export interface VoiceScaffold {
+    scale: (min: number, max: number, minL?: string, maxL?: string) => string;
+    binary: (y: string, n: string) => string;
+    options: (o: string[]) => string;
+    multi: (o: string[]) => string;
+    ranking: (o: string[]) => string;
+    date: () => string;
+    matrixStem: (stem: string) => string;
+    matrixRow: (row: string, cols: string[]) => string;
+}
+export declare function scaffoldFor(lang?: string): VoiceScaffold;
+export declare function voiceDisclaimer(n: number, lang?: string): string;
+export declare function skipNoteText(lang?: string): string;
+/** What the session says out loud to ask this question. */
+export declare function buildPromptText(q: VoiceQuestion, lang?: string): string;
+//# sourceMappingURL=voice.d.ts.map

package/dist/voice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.d.ts","sourceRoot":"","sources":["../src/voice.ts"],"names":[],"mappings":"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"}

package/dist/voice.js

@@ -0,0 +1,632 @@
+"use strict";
+/**
+ * Turning speech into an answer.
+ *
+ * This is the point where a respondent's VOICE becomes stored data, and a
+ * divergence between channels is invisible afterwards: the row looks fine, it
+ * is just a different value than the same sentence produced somewhere else.
+ * Three implementations existed — the React renderer's handsFreeVoice.tsx, the
+ * web SDK's voice.js (ported from it) and the mobile renderer's
+ * voiceParsers.ts (an older, stricter copy). Mobile had drifted: no fuzzy
+ * tolerance, no filler stripping, no letter shortcuts, no Arabic orthographic
+ * folding, English-only ordinals. "grean" for Green resolved on a link and on
+ * a website and failed on the phone, which is the channel where hands-free
+ * matters most.
+ *
+ * ── The seam ─────────────────────────────────────────────────────────────
+ *
+ * These functions return an option INDEX, never an answer. That is deliberate.
+ * The three renderers genuinely disagree about answer shape and are each right
+ * about their own: React's radio widget stores `{ choice: value }` and
+ * normalises it at submit, web and mobile store the bare value. A shared
+ * function returning "the answer" would have to pick one and break two.
+ * Matching a sentence to an option is the part that must be identical;
+ * wrapping an index in a shape is the part that must not be.
+ *
+ * tools/survey-conformance/voice.js runs the same spoken answers through all
+ * three and fails on any disagreement.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shortCode = shortCode;
+exports.normalizeTranscript = normalizeTranscript;
+exports.distinctiveLabels = distinctiveLabels;
+exports.optionLabelOf = optionLabelOf;
+exports.optionValueOf = optionValueOf;
+exports.voiceOptionsOf = voiceOptionsOf;
+exports.optionLabelsOf = optionLabelsOf;
+exports.matchBoolean = matchBoolean;
+exports.matchOption = matchOption;
+exports.matchOptions = matchOptions;
+exports.rankOptions = rankOptions;
+exports.matchNumberInRange = matchNumberInRange;
+exports.matchDate = matchDate;
+exports.voiceSupport = voiceSupport;
+exports.voiceCanHandle = voiceCanHandle;
+exports.auditVoiceQuestions = auditVoiceQuestions;
+exports.scaffoldFor = scaffoldFor;
+exports.voiceDisclaimer = voiceDisclaimer;
+exports.skipNoteText = skipNoteText;
+exports.buildPromptText = buildPromptText;
+/* ── Locale ─────────────────────────────────────────────────────────────── */
+function shortCode(lang) {
+    return String(lang || 'en').split('-')[0].toLowerCase();
+}
+/* ── Transcript normalization ───────────────────────────────────────────── */
+// Contractions expand BEFORE punctuation is stripped: otherwise "I'd say C"
+// loses the apostrophe and leaves a bare "d" token, which the letter shortcut
+// reads as option D — a silently wrong answer.
+const CONTRACTIONS = [
+    [/\bcan['’]t\b/g, 'can not'], [/\bwon['’]t\b/g, 'will not'],
+    [/n['’]t\b/g, ' not'], [/['’]ll\b/g, ' will'], [/['’]re\b/g, ' are'],
+    [/['’]ve\b/g, ' have'], [/['’]m\b/g, ' am'], [/['’]d\b/g, ' would'],
+    [/['’]s\b/g, ''],
+];
+// Whole-word pairs, never suffix regexes. A rule like -our→-or also rewrites
+// "four"→"for" and corrupts the number table; -re→-er turns "more" into
+// "moer". Boring beats clever here.
+const EN_SPELLING = {
+    colour: 'color', colours: 'colors', coloured: 'colored',
+    favour: 'favor', favours: 'favors', favourite: 'favorite', favourites: 'favorites',
+    flavour: 'flavor', flavours: 'flavors',
+    honour: 'honor', humour: 'humor', labour: 'labor',
+    neighbour: 'neighbor', neighbours: 'neighbors',
+    behaviour: 'behavior', behaviours: 'behaviors',
+    harbour: 'harbor', rumour: 'rumor', odour: 'odor',
+    armour: 'armor', vapour: 'vapor', endeavour: 'endeavor',
+    centre: 'center', centres: 'centers', theatre: 'theater',
+    metre: 'meter', metres: 'meters', litre: 'liter', litres: 'liters',
+    fibre: 'fiber', calibre: 'caliber',
+    organisation: 'organization', organisations: 'organizations',
+    organise: 'organize', organised: 'organized',
+    realise: 'realize', realised: 'realized',
+    recognise: 'recognize', recognised: 'recognized',
+    apologise: 'apologize', apologised: 'apologized',
+    personalise: 'personalize', personalised: 'personalized',
+    customise: 'customize', customised: 'customized',
+    analyse: 'analyze', analysed: 'analyzed',
+    catalogue: 'catalog', dialogue: 'dialog',
+    grey: 'gray', licence: 'license', defence: 'defense',
+    practise: 'practice', programme: 'program',
+    travelling: 'traveling', travelled: 'traveled', traveller: 'traveler',
+    cancelled: 'canceled', cancelling: 'canceling',
+    enquire: 'inquire', enquiry: 'inquiry', enquiries: 'inquiries',
+};
+/** Lower-case, fold Arabic orthography, strip punctuation, normalise spelling. */
+function normalizeTranscript(s) {
+    let out = String(s == null ? '' : s).toLowerCase();
+    for (const [re, to] of CONTRACTIONS)
+        out = out.replace(re, to);
+    // Hamza carriers, ta marbuta, alef maqsura, tashkeel and tatweel all fold,
+    // so "طلب مساعده" matches "طلب مساعدة".
+    out = out.replace(/[ً-ْٰـ]/g, '').replace(/[أإآٱ]/g, 'ا').replace(/ى/g, 'ي').replace(/ة/g, 'ه');
+    try {
+        out = out.replace(/[^\p{L}\p{N}\s]/gu, ' ');
+    }
+    catch {
+        out = out.replace(/[^a-z0-9؀-ۿ\s]/gi, ' ');
+    }
+    out = out.replace(/\s+/g, ' ').trim();
+    if (!out)
+        return out;
+    return out.split(' ').map((w) => (Object.prototype.hasOwnProperty.call(EN_SPELLING, w) ? EN_SPELLING[w] : w)).join(' ');
+}
+// Tables are keyed by NORMALIZED text. Writing 'أربعة' by hand while input
+// folds to 'اربعه' is exactly the mismatch that silently killed Arabic number
+// parsing in an earlier version.
+const normList = (arr) => arr.map(normalizeTranscript).filter(Boolean);
+const normPairs = (pairs) => pairs.map(([k, v]) => [normalizeTranscript(k), v]).filter(([k]) => !!k);
+const normObj = (obj) => {
+    const out = {};
+    for (const k of Object.keys(obj)) {
+        const n = normalizeTranscript(k);
+        if (n)
+            out[n] = obj[k];
+    }
+    return out;
+};
+const YES_WORDS = normList(['yes', 'yeah', 'yep', 'yup', 'yah', 'sure', 'ok', 'okay', 'true', 'correct', 'right',
+    'affirmative', 'absolutely', 'definitely', 'certainly', 'indeed', 'of course', 'i do', 'i would',
+    'agreed', 'agree', 'positive', 'for sure', 'why not',
+    'نعم', 'أجل', 'اجل', 'صحيح', 'أيوه', 'ايوه', 'اكيد', 'أكيد', 'طبعا', 'بالتأكيد', 'موافق',
+    'sí', 'si', 'oui', 'ja', 'sì']);
+const NO_WORDS = normList(['no', 'nope', 'nah', 'naw', 'false', 'incorrect', 'negative', 'never',
+    'not really', 'no way', 'i do not', 'i would not', 'disagree', 'wrong', 'nay',
+    'لا', 'كلا', 'مش', 'ابدا', 'أبدا', 'غير صحيح', 'لأ', 'non', 'nein']);
+const phrasesOf = (list) => list.filter((w) => w.indexOf(' ') !== -1);
+const YES_PHRASES = phrasesOf(YES_WORDS);
+const NO_PHRASES = phrasesOf(NO_WORDS);
+// Strong ordinals outrank weak cardinals: in "the third one", "one" is a
+// pronoun, not a position, and scoring both equally resolved to option 1.
+const ORDINALS_STRONG = normPairs([
+    ['first', 0], ['second', 1], ['third', 2], ['fourth', 3], ['fifth', 4], ['sixth', 5],
+    ['اول', 0], ['الاول', 0], ['الاولي', 0],
+    ['ثاني', 1], ['الثاني', 1], ['الثانيه', 1],
+    ['ثالث', 2], ['الثالث', 2], ['الثالثه', 2],
+    ['رابع', 3], ['الرابع', 3], ['الرابعه', 3],
+    ['خامس', 4], ['الخامس', 4], ['الخامسه', 4],
+    ['سادس', 5], ['السادس', 5], ['السادسه', 5],
+]);
+const ORDINALS_WEAK = normPairs([
+    ['one', 0], ['1', 0], ['two', 1], ['2', 1], ['three', 2], ['3', 2],
+    ['four', 3], ['4', 3], ['five', 4], ['5', 4], ['six', 5], ['6', 5],
+    ['واحد', 0], ['اثنين', 1], ['اتنين', 1], ['ثلاثه', 2], ['تلاته', 2], ['اربعه', 3], ['خمسه', 4], ['سته', 5],
+]);
+// Letter shortcuts — Latin by position, Arabic in abjad order.
+const LETTER_INDEX = normObj({ a: 0, b: 1, c: 2, d: 3, e: 4, f: 5, 'ا': 0, 'ب': 1, 'ج': 2, 'د': 3, 'ه': 4, 'و': 5 });
+// Discourse markers stripped before letter/ordinal detection, so "um, I would
+// say C please" reduces to "c". Articles are NOT included — they appear inside
+// real option labels.
+const FILLERS = normList(['um', 'uhm', 'uh', 'er', 'erm', 'hmm', 'mm', 'ah', 'oh', 'like', 'well', 'so',
+    'actually', 'basically', 'literally', 'maybe', 'probably', 'definitely', 'honestly', 'personally',
+    'please', 'thanks', 'thank you', 'ok', 'okay', 'right',
+    'يعني', 'اه', 'ايه', 'طيب', 'اوك', 'من فضلك', 'لو سمحت']);
+const FILLER_PHRASES = [/\bi would say\b/g, /\bi think\b/g, /\bi guess\b/g, /\bi mean\b/g,
+    /\blet me say\b/g, /\blets say\b/g, /\byou know\b/g, /\bkind of\b/g, /\bsort of\b/g,
+    /\bmy answer is\b/g, /\bthe answer is\b/g, /\bi choose\b/g, /\bi pick\b/g, /\bi select\b/g,
+    /\bgo with\b/g, /\bاختار\b/g, /\bاعتقد\b/g, /\bجوابي\b/g];
+function stripFillers(said) {
+    let out = said;
+    for (const re of FILLER_PHRASES)
+        out = out.replace(re, ' ');
+    const kept = out.split(/\s+/).filter((t) => t && FILLERS.indexOf(t) === -1);
+    return kept.join(' ').trim() || said;
+}
+// Connectors between multiple picks — "the staff and the prices" is two
+// answers, and matching the joined phrase as one string finds neither.
+const CONNECTOR_RE = /\s+(?:and|also|plus|as well as|و|وكذلك|وايضا|ايضا)\s+|\s*[,،]\s*/g;
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    let prev = [];
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[b.length];
+}
+function similarity(a, b) {
+    const longest = Math.max(a.length, b.length);
+    return longest === 0 ? 1 : 1 - editDistance(a, b) / longest;
+}
+/**
+ * Strip the prefix every option shares, so "Option A / Option B / Option C"
+ * reduces to "a" / "b" / "c" and a respondent who just says "C" is understood.
+ */
+function distinctiveLabels(labels) {
+    if (labels.length < 2)
+        return labels.slice();
+    const words = labels.map((l) => l.split(' '));
+    const shortest = words.reduce((m, w) => Math.min(m, w.length), Infinity);
+    let shared = 0;
+    while (shared < shortest - 1) {
+        let same = true;
+        for (let i = 1; i < words.length; i++)
+            if (words[i][shared] !== words[0][shared]) {
+                same = false;
+                break;
+            }
+        if (!same)
+            break;
+        shared++;
+    }
+    if (shared === 0)
+        return labels.slice();
+    const stripped = [];
+    for (const w of words) {
+        const t = w.slice(shared).join(' ');
+        if (!t)
+            return labels.slice(); // stripping would empty one — keep them all
+        stripped.push(t);
+    }
+    return stripped;
+}
+const lookupPair = (pairs, token) => {
+    for (const [k, v] of pairs)
+        if (k === token)
+            return v;
+    return -1;
+};
+/**
+ * How strongly does this utterance point at this option? Higher wins.
+ * The bands matter more than the numbers: an exact label always beats a
+ * distinctive-suffix hit, which always beats a letter or ordinal, which always
+ * beats a fuzzy near-miss.
+ */
+function scoreOption(said, label, distinctive, index) {
+    if (!said)
+        return 0;
+    if (said === label)
+        return 1000 + label.length;
+    if (said === distinctive)
+        return 900 + distinctive.length;
+    const tokens = stripFillers(said).split(' ');
+    if (label && said.indexOf(label) !== -1)
+        return 700 + label.length;
+    if (distinctive) {
+        const hit = distinctive.length >= 3 ? (said.indexOf(distinctive) !== -1) : (tokens.indexOf(distinctive) !== -1);
+        if (hit)
+            return 600 + distinctive.length;
+    }
+    if (said.length >= 3 && label.indexOf(said) !== -1)
+        return 500 + said.length;
+    for (const t of tokens) {
+        if (LETTER_INDEX[t] === index)
+            return 470;
+        if (lookupPair(ORDINALS_STRONG, t) === index)
+            return 460;
+    }
+    for (const t of tokens)
+        if (lookupPair(ORDINALS_WEAK, t) === index)
+            return 430;
+    const target = distinctive || label;
+    if (target.length >= 3) {
+        // Short labels need a tighter threshold: at 5 characters a single edit is
+        // already 20% of the word, and "blue"/"blur" are different answers.
+        const threshold = target.length <= 5 ? 0.8 : 0.72;
+        const sim = Math.max(similarity(said, target), similarity(said, label));
+        if (sim >= threshold)
+            return 100 + Math.round(sim * 100);
+    }
+    return 0;
+}
+function matchOptionIndex(said, labels, distinctives) {
+    let bestIdx = -1, bestScore = 0;
+    for (let i = 0; i < labels.length; i++) {
+        const sc = scoreOption(said, labels[i], distinctives[i], i);
+        if (sc > bestScore) {
+            bestScore = sc;
+            bestIdx = i;
+        }
+    }
+    return bestIdx;
+}
+const NUMBER_WORDS = normObj({
+    zero: 0, nought: 0, one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+    first: 1, second: 2, third: 3, fourth: 4, fifth: 5, sixth: 6, seventh: 7, eighth: 8, ninth: 9, tenth: 10,
+    'صفر': 0, 'واحد': 1, 'واحدة': 1, 'اثنان': 2, 'اثنين': 2, 'اتنين': 2, 'ثلاثة': 3, 'ثلاث': 3, 'تلاتة': 3, 'أربعة': 4, 'اربعة': 4,
+    'خمسة': 5, 'خمس': 5, 'ستة': 6, 'سبعة': 7, 'سبع': 7, 'ثمانية': 8, 'ثماني': 8, 'تمانية': 8, 'تسعة': 9, 'عشرة': 10, 'عشر': 10,
+});
+// What speech recognition emits INSTEAD of a number. These are ordinary words,
+// so they only apply when the utterance is essentially just the answer.
+const NUMBER_HOMOPHONES = normObj({
+    oh: 0, won: 1, wun: 1, to: 2, too: 2, tu: 2, tree: 3, free: 3,
+    for: 4, fore: 4, forth: 4, fife: 5, sex: 6, sicks: 6, ate: 8, nein: 9,
+});
+function optionLabelOf(o) {
+    return String((o && (o.label != null ? o.label : (o.text != null ? o.text : (o.value != null ? o.value : o.alt)))) || '');
+}
+function optionValueOf(o) {
+    return (o && o.value != null) ? o.value : optionLabelOf(o);
+}
+function voiceOptionsOf(q) {
+    if (Array.isArray(q.options))
+        return q.options;
+    if (Array.isArray(q.choices))
+        return q.choices;
+    return [];
+}
+function optionLabelsOf(q) {
+    return voiceOptionsOf(q).map(optionLabelOf).filter(Boolean);
+}
+/* ── Matchers — every one returns an index or a primitive, never an answer ── */
+/** Yes/no, including the question's own yes/no labels. `null` = neither. */
+function matchBoolean(q, transcript) {
+    const norm = normalizeTranscript(transcript);
+    // Multi-word entries can never match token-by-token. Negatives are scanned
+    // first: "not really" must not be caught by the positive pass.
+    for (const p of NO_PHRASES)
+        if (norm.indexOf(p) !== -1)
+            return false;
+    for (const p of YES_PHRASES)
+        if (norm.indexOf(p) !== -1)
+            return true;
+    const yes = typeof q.yesLabel === 'string' ? normalizeTranscript(q.yesLabel) : '';
+    const no = typeof q.noLabel === 'string' ? normalizeTranscript(q.noLabel) : '';
+    for (const t of norm.split(' ').filter(Boolean)) {
+        if (YES_WORDS.indexOf(t) !== -1)
+            return true;
+        if (NO_WORDS.indexOf(t) !== -1)
+            return false;
+        if (yes && t === yes)
+            return true;
+        if (no && t === no)
+            return false;
+    }
+    if (yes && norm.indexOf(yes) !== -1)
+        return true;
+    if (no && norm.indexOf(no) !== -1)
+        return false;
+    return null;
+}
+/** Single choice. Returns the option index, or -1 when nothing matched. */
+function matchOption(q, transcript) {
+    const options = voiceOptionsOf(q);
+    if (!options.length)
+        return -1;
+    const said = normalizeTranscript(transcript);
+    const labels = options.map((o) => normalizeTranscript(optionLabelOf(o)));
+    const dist = distinctiveLabels(labels);
+    let idx = matchOptionIndex(said, labels, dist);
+    if (idx < 0) {
+        // Retry per clause — "um, C I think" still scores, and a stray leading
+        // filler doesn't sink the match.
+        for (const clause of said.split(CONNECTOR_RE)) {
+            const c = (clause || '').trim();
+            if (!c)
+                continue;
+            idx = matchOptionIndex(c, labels, dist);
+            if (idx >= 0)
+                break;
+        }
+    }
+    return idx;
+}
+/** Multi-choice. Returns ascending option indices; empty when nothing matched. */
+function matchOptions(q, transcript) {
+    const options = voiceOptionsOf(q);
+    if (!options.length)
+        return [];
+    const said = normalizeTranscript(transcript);
+    const labels = options.map((o) => normalizeTranscript(optionLabelOf(o)));
+    const dist = distinctiveLabels(labels);
+    const picked = [];
+    const add = (n) => { if (n >= 0 && picked.indexOf(n) === -1)
+        picked.push(n); };
+    // Clause-driven: "the staff and the prices" is two answers, and scoring the
+    // joined phrase as one string finds neither.
+    for (const clause of said.split(CONNECTOR_RE)) {
+        const c = (clause || '').trim();
+        if (c)
+            add(matchOptionIndex(c, labels, dist));
+    }
+    // Then sweep for labels mentioned outright, catching picks the connector
+    // split missed. Literal containment ONLY here — a fuzzy near-miss must not
+    // be able to over-select, because an unwanted extra pick is worse than a
+    // missed one when the respondent can't see what was recorded.
+    for (let i = 0; i < labels.length; i++) {
+        const target = dist[i] || labels[i];
+        if (target.length >= 3 && said.indexOf(target) !== -1)
+            add(i);
+        else if (labels[i].length >= 3 && said.indexOf(labels[i]) !== -1)
+            add(i);
+    }
+    return picked.sort((a, b) => a - b);
+}
+/**
+ * Ranking. Returns option indices in the order they were spoken, or an empty
+ * array when fewer than two were heard — one name is not a ranking.
+ */
+function rankOptions(q, transcript) {
+    const options = voiceOptionsOf(q);
+    if (!options.length)
+        return [];
+    const norm = normalizeTranscript(transcript);
+    const found = [];
+    for (let i = 0; i < options.length; i++) {
+        const nl = normalizeTranscript(optionLabelOf(options[i]));
+        if (!nl)
+            continue;
+        const pos = norm.indexOf(nl);
+        if (pos >= 0)
+            found.push({ i, pos });
+    }
+    if (found.length < 2)
+        return [];
+    found.sort((a, b) => a.pos - b.pos);
+    return found.map((f) => f.i);
+}
+/** A number inside [min, max], from digits, number words, or a homophone. */
+function matchNumberInRange(transcript, min, max) {
+    // Arabic-Indic and Extended Arabic-Indic digits fold to ASCII first —
+    // common when speech recognition transcribes spoken numbers in the native
+    // script.
+    const ascii = String(transcript)
+        .replace(/[٠-٩]/g, (d) => String('٠١٢٣٤٥٦٧٨٩'.indexOf(d)))
+        .replace(/[۰-۹]/g, (d) => String('۰۱۲۳۴۵۶۷۸۹'.indexOf(d)));
+    const norm = normalizeTranscript(ascii);
+    // Every digit run in order, so "5 out of 10" on a 0-10 scale lands on 5
+    // rather than falling through to the word table.
+    const digits = norm.match(/\d+(?:\.\d+)?/g);
+    if (digits)
+        for (const m of digits) {
+            const n = Math.round(Number(m));
+            if (n >= min && n <= max)
+                return n;
+        }
+    // Word forms matched as whole tokens, never substrings — otherwise
+    // "fourteen" matches "four".
+    for (const t of norm.split(/\s+/).filter(Boolean)) {
+        const n = NUMBER_WORDS[t];
+        if (n !== undefined && n >= min && n <= max)
+            return n;
+    }
+    // Homophone rescue, short utterances only: a bare "for" on a 0-10 scale was
+    // almost certainly "four"; "for" inside a sentence is a preposition.
+    const core = stripFillers(norm).split(/\s+/).filter(Boolean);
+    if (core.length <= 2) {
+        for (const t of core) {
+            const n = NUMBER_HOMOPHONES[t];
+            if (n !== undefined && n >= min && n <= max)
+                return n;
+        }
+    }
+    return null;
+}
+/** A spoken date as ISO `YYYY-MM-DD`, or null. */
+function matchDate(transcript) {
+    const raw = String(transcript).trim();
+    // Strip filler words and ordinal suffixes ("January 5th" → "January 5") that
+    // trip the Date constructor; speech engines produce them constantly.
+    const cleaned = raw.replace(/\b(the|of|on|at)\b/gi, ' ').replace(/(\d+)(st|nd|rd|th)\b/gi, '$1').replace(/\s+/g, ' ').trim();
+    for (const c of [raw, cleaned, raw.replace(/(\d+)(st|nd|rd|th)\b/gi, '$1')]) {
+        if (!c)
+            continue;
+        const d = new Date(c);
+        if (!isNaN(d.getTime())) {
+            const m = String(d.getMonth() + 1).padStart(2, '0');
+            const day = String(d.getDate()).padStart(2, '0');
+            return `${d.getFullYear()}-${m}-${day}`;
+        }
+    }
+    return null;
+}
+function voiceSupport(type) {
+    switch (String(type || '').toLowerCase()) {
+        case 'text':
+        case 'textbox':
+        case 'shorttext':
+        case 'comment':
+        case 'textarea':
+        case 'longtext':
+        case 'binary':
+        case 'boolean':
+        case 'yesno':
+        case 'yes_no':
+        case 'radio':
+        case 'radiogroup':
+        case 'dropdown':
+        case 'select':
+        case 'rating':
+        case 'nps':
+        case 'checkbox':
+        case 'imagepicker':
+        case 'image_picker':
+        case 'ranking':
+        case 'date':
+            return 'full';
+        case 'matrix':
+            return 'matrix';
+        case 'content':
+        case 'html':
+        case 'image':
+        case 'expression':
+        case 'pagebreak':
+        case 'page_break':
+            return 'read';
+        case 'multitext':
+        case 'multi_text':
+        case 'multipletext':
+        case 'matrixdropdown':
+        case 'matrix_dropdown':
+        case 'matrixdynamic':
+        case 'matrix_dynamic':
+            return 'assist';
+        case 'paneldynamic':
+        case 'panel_dynamic':
+        case 'signature':
+        case 'fileupload':
+        case 'file_upload':
+        case 'file':
+            return 'none';
+        default:
+            return 'none';
+    }
+}
+/** Can a voice-only session get through this question unaided? */
+function voiceCanHandle(type) {
+    const s = voiceSupport(type);
+    return s === 'full' || s === 'matrix' || s === 'read';
+}
+/**
+ * blocking  = required questions voice can't handle → the session must not start.
+ * skippable = optional ones → announced and skipped.
+ */
+function auditVoiceQuestions(questions) {
+    const blocking = [], skippable = [];
+    for (const q of (Array.isArray(questions) ? questions : [])) {
+        if (!q)
+            continue;
+        const t = String(q.type || '').toLowerCase();
+        if (t === 'pagebreak' || t === 'page_break')
+            continue;
+        if (voiceCanHandle(String(q.type || '')))
+            continue;
+        if (q.isRequired || q.required)
+            blocking.push(q);
+        else
+            skippable.push(q);
+    }
+    return { blocking, skippable };
+}
+const SCAFFOLDS = {
+    en: {
+        scale: (min, max, minL, maxL) => {
+            const r = `Answer with a number from ${min} to ${max}`;
+            return (minL && maxL) ? `${r}. ${min} means ${minL}, ${max} means ${maxL}.` : `${r}.`;
+        },
+        binary: (y, n) => `Please answer ${y || 'yes'} or ${n || 'no'}.`,
+        options: (o) => `Options are: ${o.join(', ')}.`,
+        multi: (o) => `Multiple choices allowed. Options are: ${o.join(', ')}. Say the ones that apply.`,
+        ranking: (o) => `Rank in order of preference: ${o.join(', ')}.`,
+        date: () => 'Please say the date.',
+        matrixStem: (stem) => `${stem}. I’ll ask you row by row.`,
+        matrixRow: (row, cols) => `${row}. Options: ${cols.join(', ')}.`,
+    },
+    ar: {
+        scale: (min, max, minL, maxL) => {
+            const r = `أجب برقم من ${min} إلى ${max}`;
+            return (minL && maxL) ? `${r}. ${min} يعني ${minL}، ${max} يعني ${maxL}.` : `${r}.`;
+        },
+        binary: (y, n) => `يرجى الإجابة ${y || 'نعم'} أو ${n || 'لا'}.`,
+        options: (o) => `الخيارات: ${o.join('، ')}.`,
+        multi: (o) => `يمكن اختيار أكثر من إجابة. الخيارات: ${o.join('، ')}. قل الخيارات التي تنطبق.`,
+        ranking: (o) => `رتب حسب الأفضلية: ${o.join('، ')}.`,
+        date: () => 'يرجى قول التاريخ.',
+        matrixStem: (stem) => `${stem}. سأسألك عن كل صف على حدة.`,
+        matrixRow: (row, cols) => `${row}. الخيارات: ${cols.join('، ')}.`,
+    },
+};
+function scaffoldFor(lang) {
+    return SCAFFOLDS[shortCode(lang)] || SCAFFOLDS.en;
+}
+function voiceDisclaimer(n, lang) {
+    if (shortCode(lang) === 'ar')
+        return 'ملاحظة: ' + n + (n > 1 ? ' أسئلة' : ' سؤال') + ' لا يمكن الإجابة عليها صوتياً وسيتم تخطيها.';
+    return 'Heads up — ' + n + ' question' + (n > 1 ? 's' : '') + " can't be answered by voice and will be skipped.";
+}
+function skipNoteText(lang) {
+    if (shortCode(lang) === 'ar')
+        return 'هذا السؤال يحتاج إدخالاً يدوياً — سيتم تخطيه.';
+    return 'This one needs manual input — skipping it.';
+}
+/** What the session says out loud to ask this question. */
+function buildPromptText(q, lang) {
+    const s = scaffoldFor(lang);
+    const base = String(q.title || q.text || q.label || '').replace(/<[^>]*>/g, '').trim();
+    const type = String(q.type || '').toLowerCase();
+    if (['binary', 'boolean', 'yesno', 'yes_no'].indexOf(type) !== -1) {
+        return `${base}. ${s.binary(typeof q.yesLabel === 'string' ? q.yesLabel : '', typeof q.noLabel === 'string' ? q.noLabel : '')}`;
+    }
+    if (type === 'rating') {
+        return `${base}. ${s.scale(typeof q.minValue === 'number' ? q.minValue : 1, typeof q.maxValue === 'number' ? q.maxValue : 5, typeof q.minLabel === 'string' ? q.minLabel : undefined, typeof q.maxLabel === 'string' ? q.maxLabel : undefined)}`;
+    }
+    if (type === 'nps') {
+        // Always 0-10 regardless of the question's own min/max — every NPS
+        // renderer hardcodes that scale.
+        return `${base}. ${s.scale(0, 10, typeof q.minLabel === 'string' ? q.minLabel : 'Not at all likely', typeof q.maxLabel === 'string' ? q.maxLabel : 'Extremely likely')}`;
+    }
+    if (['radio', 'radiogroup', 'dropdown', 'select', 'imagepicker', 'image_picker'].indexOf(type) !== -1) {
+        const o = optionLabelsOf(q);
+        return o.length ? `${base}. ${s.options(o)}` : base;
+    }
+    if (type === 'checkbox') {
+        const o = optionLabelsOf(q);
+        return o.length ? `${base}. ${s.multi(o)}` : base;
+    }
+    if (type === 'ranking') {
+        const o = optionLabelsOf(q);
+        return o.length ? `${base}. ${s.ranking(o)}` : base;
+    }
+    if (type === 'date')
+        return `${base}. ${s.date()}`;
+    return base;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cxpinsight/survey-spec",
-  "version": "0.2.0",
-  "description": "The survey specification the renderers share — expression evaluation first. Source of truth for behaviour that must be identical on web, links and mobile.",
+  "version": "0.3.0",
+  "description": "The survey specification the renderers share \u2014 expression evaluation first. Source of truth for behaviour that must be identical on web, links and mobile.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [