@pie-element/mc-populated-blank 0.2.10 → 0.2.11

package/dist/shared/layoutLimits.d.ts

@@ -0,0 +1,40 @@
+export type LayoutLimits = {
+    blankStandaloneWidthRem: number;
+    blankWideWidthRem: number;
+    blankUnderlineWidthPx: number;
+    blankUnderlineWideWidthPx: number;
+    horizontalChoiceWidthPx: number;
+    horizontalChoiceWidthVw: number;
+    horizontalChoiceTileMinHeightRem: number;
+    horizontalChoiceContentMinHeightRem: number;
+    selectedImageMaxHeightRem: number;
+    choiceImageMaxHeightRem: number;
+    listenButtonSizePx: number;
+    stimulusMinColumnPx: number;
+    textMinColumnPx: number;
+    legendMaxChars: number;
+    choiceGroupGapRem: number;
+    choiceRowGapRem: number;
+    toggleButtonGapRem: number;
+    horizontalChoiceRadioTopMarginRem: number;
+    audioBlankTemplateMarginTopRem: number;
+    audioBlankTemplateMarginBottomRem: number;
+    audioInstructionsMaxWidthPx: number;
+    narrowHorizontalChoiceMaxWidthPx: number;
+    stimulusGridColumnGapRem: number;
+    stimulusGridRowGapRem: number;
+    stimulusSentenceMarginTopRem: number;
+    stimulusChoicesMarginTopRem: number;
+    tokenGridColumnGapRem: number;
+    tokenGridRowGapRem: number;
+    tokenTemplateMarginTopRem: number;
+    tokenInlineTokenGapRem: number;
+    tokenChoicesMarginTopRem: number;
+    inlineGridColumnGapRem: number;
+    inlineGridRowGapRem: number;
+    inlineTemplateMarginTopRem: number;
+    inlineChoicesMarginTopRem: number;
+};
+/** Baseline values tuned to match historical CQT visuals; override via model.layoutLimits. */
+export declare const DEFAULT_LAYOUT_LIMITS: LayoutLimits;
+//# sourceMappingURL=layoutLimits.d.ts.map

package/dist/shared/layoutLimits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layoutLimits.d.ts","sourceRoot":"","sources":["../../src/shared/layoutLimits.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG;IACzB,uBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,yBAAyB,EAAE,MAAM,CAAC;IAClC,uBAAuB,EAAE,MAAM,CAAC;IAChC,uBAAuB,EAAE,MAAM,CAAC;IAChC,gCAAgC,EAAE,MAAM,CAAC;IACzC,mCAAmC,EAAE,MAAM,CAAC;IAC5C,yBAAyB,EAAE,MAAM,CAAC;IAClC,uBAAuB,EAAE,MAAM,CAAC;IAChC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iCAAiC,EAAE,MAAM,CAAC;IAC1C,8BAA8B,EAAE,MAAM,CAAC;IACvC,iCAAiC,EAAE,MAAM,CAAC;IAC1C,2BAA2B,EAAE,MAAM,CAAC;IACpC,gCAAgC,EAAE,MAAM,CAAC;IACzC,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,4BAA4B,EAAE,MAAM,CAAC;IACrC,2BAA2B,EAAE,MAAM,CAAC;IACpC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yBAAyB,EAAE,MAAM,CAAC;IAClC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,wBAAwB,EAAE,MAAM,CAAC;IACjC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0BAA0B,EAAE,MAAM,CAAC;IACnC,yBAAyB,EAAE,MAAM,CAAC;CACnC,CAAC;AAEF,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB,EAAE,YAoCnC,CAAC"}

package/dist/shared/types.d.ts

@@ -0,0 +1,82 @@
+import type { LayoutLimits } from './layoutLimits';
+export type McpbChoiceMode = 'text' | 'image';
+export type McpbInteractionMode = 'populate_blank' | 'audio_mc_only';
+export type McpbDeliveryMode = 'gather' | 'view' | 'evaluate' | 'authoring' | 'print';
+export type McpbRole = 'student' | 'instructor';
+export type McpbCorrectness = 'correct' | 'incorrect' | 'unanswered';
+export interface McpbChoice {
+    id: string;
+    labelHtml?: string;
+    imageUrl?: string;
+    imageAlt?: string;
+}
+export interface McpbAudioButtonSkin {
+    silentUrl: string;
+    playingUrl: string;
+}
+export interface McpbUiText {
+    answerChoices?: string;
+    selectedAnswerInSentence?: string;
+    showCorrectAnswer?: string;
+    hideCorrectAnswer?: string;
+    clickToEnableAutoplay?: string;
+    audioResourceUnavailable?: string;
+    transcriptLabel?: string;
+    listenLabelEn?: string;
+    listenLabelEs?: string;
+    listenSilentAlt?: string;
+    listenPlayingAlt?: string;
+    listenSilentAltEs?: string;
+    listenPlayingAltEs?: string;
+}
+export interface McpbQuestion {
+    id?: string;
+    element?: string;
+    prompt?: string;
+    promptEnabled?: boolean;
+    interactionMode?: McpbInteractionMode;
+    layoutProfile?: string;
+    choiceLayout?: string;
+    layoutProfilePresets?: Record<string, Partial<LayoutLimits>>;
+    layoutLimits?: Partial<LayoutLimits>;
+    audioButtonSkin?: McpbAudioButtonSkin | null;
+    audioButtonSkinsByLocale?: Record<string, McpbAudioButtonSkin>;
+    uiText?: McpbUiText;
+    sentenceHtml?: string;
+    template?: string;
+    choiceMode?: McpbChoiceMode;
+    choices?: McpbChoice[];
+    correctChoiceId?: string;
+    hasAudio?: boolean;
+    autoplayAudioEnabled?: boolean;
+    completeAudioEnabled?: boolean;
+    audioUrl?: string;
+    audioTranscript?: string;
+    showVisibleTranscript?: boolean;
+    useFeatureButtonAudio?: boolean;
+    locale?: string;
+    shuffle?: boolean;
+    lockChoiceOrder?: boolean;
+    teacherInstructions?: string;
+    teacherInstructionsEnabled?: boolean;
+    customType?: string;
+}
+export interface McpbSession {
+    id?: string;
+    element?: string;
+    choiceId?: string;
+    audioStartTime?: number;
+    audioEndTime?: number;
+    shuffledValues?: string[];
+    data?: {
+        shuffledValues?: string[];
+    };
+}
+export interface McpbEnv {
+    mode?: McpbDeliveryMode;
+    role?: McpbRole;
+    '@pie-element'?: {
+        lockChoiceOrder?: boolean;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pie-element/mc-populated-blank",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "Multiple-choice option populates an inline blank in a sentence template (Svelte 5 PIE element)",
   "type": "module",
   "main": "./dist/index.js",
@@ -47,6 +47,7 @@
     "clean": "rm -rf dist tsconfig.tsbuildinfo"
   },
   "dependencies": {
+    "@pie-lib/delivery-events-svelte": "0.1.0",
     "@pie-lib/styling-svelte": "0.1.2"
   },
   "peerDependencies": {
@@ -56,6 +57,7 @@
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "svelte": "^5.54.0",
     "typescript": "^5.9.3",
-    "vite": "^8.0.1"
+    "vite": "^8.0.1",
+    "vitest": "^4.1.0"
   }
 }

package/src/controller/defaults.ts

@@ -1,43 +1,9 @@
+import { DEFAULT_LAYOUT_LIMITS } from '../shared/layoutLimits';
+
+export { DEFAULT_LAYOUT_LIMITS };
+
 /** Token authors must include exactly once in `template` (HTML). */
 export const BLANK_TOKEN = '{{blank}}';
-/** Baseline values tuned to match historical CQT visuals; override via model.layoutLimits. */
-export const DEFAULT_LAYOUT_LIMITS = {
-  blankStandaloneWidthRem: 7,
-  blankWideWidthRem: 10,
-  blankUnderlineWidthPx: 2,
-  blankUnderlineWideWidthPx: 4,
-  horizontalChoiceWidthPx: 170,
-  horizontalChoiceWidthVw: 30,
-  horizontalChoiceTileMinHeightRem: 11,
-  horizontalChoiceContentMinHeightRem: 7.5,
-  selectedImageMaxHeightRem: 4,
-  choiceImageMaxHeightRem: 5,
-  listenButtonSizePx: 128,
-  stimulusMinColumnPx: 210,
-  textMinColumnPx: 260,
-  legendMaxChars: 120,
-  choiceGroupGapRem: 0.5,
-  choiceRowGapRem: 0.5,
-  toggleButtonGapRem: 0.5,
-  horizontalChoiceRadioTopMarginRem: 0.5,
-  audioBlankTemplateMarginTopRem: 0.8,
-  audioBlankTemplateMarginBottomRem: 1.8,
-  audioInstructionsMaxWidthPx: 875,
-  narrowHorizontalChoiceMaxWidthPx: 230,
-  stimulusGridColumnGapRem: 2,
-  stimulusGridRowGapRem: 0.7,
-  stimulusSentenceMarginTopRem: 0.2,
-  stimulusChoicesMarginTopRem: 0.9,
-  tokenGridColumnGapRem: 1.5,
-  tokenGridRowGapRem: 0.8,
-  tokenTemplateMarginTopRem: 0.6,
-  tokenInlineTokenGapRem: 0.35,
-  tokenChoicesMarginTopRem: 0.2,
-  inlineGridColumnGapRem: 1.5,
-  inlineGridRowGapRem: 0.65,
-  inlineTemplateMarginTopRem: 0.45,
-  inlineChoicesMarginTopRem: 0.25,
-} as const;
 
 export default {
   model: {
@@ -54,7 +20,7 @@ export default {
     audioButtonSkinsByLocale: {},
     uiText: {
       answerChoices: 'Answer choices',
-      selectedAnswerInSentence: 'Selected answer in sentence',
+      selectedAnswerInSentence: 'blank',
       showCorrectAnswer: 'Show correct answer',
       hideCorrectAnswer: 'Hide correct answer',
       clickToEnableAutoplay: 'Click to enable audio autoplay',
@@ -62,6 +28,10 @@ export default {
       transcriptLabel: 'Transcript',
       listenLabelEn: 'Listen',
       listenLabelEs: 'Escuchar',
+      listenSilentAlt: 'Repeat instructions',
+      listenPlayingAlt: 'Instructions are playing',
+      listenSilentAltEs: 'Escuchar. Repetir las instrucciones.',
+      listenPlayingAltEs: 'Escuchar. Estas son las instrucciones.',
     },
     sentenceHtml: '',
     template: `<p>The answer is ${BLANK_TOKEN}.</p>`,

package/src/controller/index.test.ts

@@ -0,0 +1,428 @@
+/**
+ * Unit tests for the McPopulatedBlank controller.
+ *
+ * Cases are grouped by exported function.
+ *
+ * getCorrectness
+ *   G1. No session → unanswered
+ *   G2. No choiceId → unanswered
+ *   G3. Correct choice selected → correct
+ *   G4. Wrong choice selected → incorrect
+ *
+ * outcome
+ *   O1. Empty session → score 0, empty: true
+ *   O2. No choiceId → score 0, empty: true
+ *   O3. Correct choice → score 1, empty: false
+ *   O4. Wrong choice → score 0, empty: false
+ *   O5. traceLog includes mode, selected id, correct id, final score
+ *
+ * model — choice ordering
+ *   M1. shuffle=false → original order preserved
+ *   M2. shuffle=true, instructor role → original order locked
+ *   M3. shuffle=true, lockChoiceOrder=true → original order locked
+ *   M4. shuffle=true, stored shuffle in session.data.shuffledValues → restored
+ *   M5. shuffle=true, stored shuffle in session.shuffledValues (legacy) → restored
+ *   M6. shuffle=true, stored shuffle has unknown ids → extras appended at end
+ *   M7. shuffle=true, no stored shuffle → shuffled; updateSession called with new order
+ *   M8. shuffle=true, no stored shuffle, no updateSession → shuffled silently (no throw)
+ *
+ * model — output fields
+ *   M9. evaluate mode → correctness, responseCorrect, correctChoiceId present
+ *   M10. gather mode → correctness fields absent
+ *   M11. instructor + view mode → teacherInstructions included when enabled
+ *   M12. student role → teacherInstructions always null
+ *   M13. prompt included when promptEnabled=true
+ *   M14. prompt null when promptEnabled=false
+ *   M15. audioUrl null when hasAudio=false
+ *   M16. audioUrl passed through when hasAudio=true
+ *   M17. disabled=true in view/evaluate mode, false in gather
+ *
+ * validate
+ *   V1. Valid question → empty errors object
+ *   V2. promptEnabled + empty prompt → prompt error
+ *   V3. populate_blank with no blank token → template error
+ *   V4. populate_blank with two blank tokens → template error
+ *   V5. audio_mc_only with a blank token → template error
+ *   V6. Unknown interactionMode → interactionMode error
+ *   V7. Fewer than two choices → choices error
+ *   V8. Choice missing id → choices error
+ *   V9. Text mode choice missing labelHtml → choices error
+ *   V10. Image mode choice missing imageUrl → choices error
+ *   V11. Image mode choice missing imageAlt → choices error
+ *   V12. correctChoiceId not in choices → correctChoiceId error
+ *   V13. hasAudio=true with no audioUrl → audioUrl error
+ *   V14. layoutLimits with a non-positive value → layoutLimits error
+ *   V15. layoutLimits with a valid value → no error
+ *
+ * createCorrectResponseSession
+ *   CR1. Instructor + mode≠evaluate → session with correct choiceId
+ *   CR2. Student role → null
+ *   CR3. Evaluate mode → null
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { getCorrectness, outcome, model, validate, createCorrectResponseSession } from './index';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const CHOICES = [
+  { id: 'a', labelHtml: '<p>Alpha</p>' },
+  { id: 'b', labelHtml: '<p>Beta</p>' },
+  { id: 'c', labelHtml: '<p>Gamma</p>' },
+];
+
+const BASE_QUESTION = {
+  id: '1',
+  element: 'mc-populated-blank',
+  template: '<p>The answer is {{blank}}.</p>',
+  interactionMode: 'populate_blank' as const,
+  choiceMode: 'text' as const,
+  choices: CHOICES,
+  correctChoiceId: 'b',
+  hasAudio: false,
+  shuffle: false,
+};
+
+const GATHER_ENV = { mode: 'gather' as const, role: 'student' as const };
+const EVALUATE_ENV = { mode: 'evaluate' as const, role: 'student' as const };
+const INSTRUCTOR_VIEW_ENV = { mode: 'view' as const, role: 'instructor' as const };
+
+// ---------------------------------------------------------------------------
+// getCorrectness
+// ---------------------------------------------------------------------------
+
+describe('getCorrectness', () => {
+  it('G1: no session → unanswered', () => {
+    expect(getCorrectness(BASE_QUESTION, null as any)).toBe('unanswered');
+  });
+
+  it('G2: session with no choiceId → unanswered', () => {
+    expect(getCorrectness(BASE_QUESTION, {})).toBe('unanswered');
+  });
+
+  it('G3: correct choice selected → correct', () => {
+    expect(getCorrectness(BASE_QUESTION, { choiceId: 'b' })).toBe('correct');
+  });
+
+  it('G4: wrong choice selected → incorrect', () => {
+    expect(getCorrectness(BASE_QUESTION, { choiceId: 'a' })).toBe('incorrect');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// outcome
+// ---------------------------------------------------------------------------
+
+describe('outcome', () => {
+  it('O1: empty session → score 0, empty: true', async () => {
+    const result = await outcome(BASE_QUESTION, {}, GATHER_ENV);
+    expect(result).toMatchObject({ score: 0, empty: true });
+  });
+
+  it('O2: session with no choiceId → score 0, empty: true', async () => {
+    const result = await outcome(BASE_QUESTION, { choiceId: '' }, GATHER_ENV);
+    expect(result).toMatchObject({ score: 0, empty: true });
+  });
+
+  it('O3: correct choice → score 1, empty: false', async () => {
+    const result = await outcome(BASE_QUESTION, { choiceId: 'b' }, EVALUATE_ENV);
+    expect(result).toMatchObject({ score: 1, empty: false });
+  });
+
+  it('O4: wrong choice → score 0, empty: false', async () => {
+    const result = await outcome(BASE_QUESTION, { choiceId: 'a' }, EVALUATE_ENV);
+    expect(result).toMatchObject({ score: 0, empty: false });
+  });
+
+  it('O5: traceLog includes mode, selected id, correct id, final score', async () => {
+    const result = (await outcome(BASE_QUESTION, { choiceId: 'a' }, EVALUATE_ENV)) as any;
+    const log = result.traceLog.join('\n');
+    expect(log).toContain('evaluate');
+    expect(log).toContain('a');
+    expect(log).toContain('b');
+    expect(log).toContain('0');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// model — choice ordering
+// ---------------------------------------------------------------------------
+
+describe('model — choice ordering', () => {
+  it('M1: shuffle=false → original order preserved', async () => {
+    const result = (await model({ ...BASE_QUESTION, shuffle: false }, {}, GATHER_ENV)) as any;
+    expect(result.choices.map((c: any) => c.id)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('M2: shuffle=true, instructor role → original order locked', async () => {
+    const result = (await model(
+      { ...BASE_QUESTION, shuffle: true },
+      {},
+      { mode: 'view', role: 'instructor' }
+    )) as any;
+    expect(result.choices.map((c: any) => c.id)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('M3: shuffle=true, lockChoiceOrder=true → original order locked', async () => {
+    const result = (await model(
+      { ...BASE_QUESTION, shuffle: true, lockChoiceOrder: true },
+      {},
+      GATHER_ENV
+    )) as any;
+    expect(result.choices.map((c: any) => c.id)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('M4: shuffle=true, stored shuffle in session.data.shuffledValues → order restored', async () => {
+    const session = { data: { shuffledValues: ['c', 'a', 'b'] } };
+    const result = (await model({ ...BASE_QUESTION, shuffle: true }, session, GATHER_ENV)) as any;
+    expect(result.choices.map((c: any) => c.id)).toEqual(['c', 'a', 'b']);
+  });
+
+  it('M5: shuffle=true, stored shuffle in session.shuffledValues (legacy) → order restored', async () => {
+    const session = { shuffledValues: ['b', 'c', 'a'] };
+    const result = (await model({ ...BASE_QUESTION, shuffle: true }, session, GATHER_ENV)) as any;
+    expect(result.choices.map((c: any) => c.id)).toEqual(['b', 'c', 'a']);
+  });
+
+  it('M6: shuffle=true, stored shuffle has unknown id → known ids first, extras appended', async () => {
+    const session = { data: { shuffledValues: ['c', 'a', 'unknown'] } };
+    const result = (await model({ ...BASE_QUESTION, shuffle: true }, session, GATHER_ENV)) as any;
+    const ids = result.choices.map((c: any) => c.id);
+    expect(ids[0]).toBe('c');
+    expect(ids[1]).toBe('a');
+    expect(ids[2]).toBe('b'); // leftover appended
+    expect(ids).not.toContain('unknown');
+  });
+
+  it('M7: shuffle=true, no stored shuffle → shuffled; updateSession called with new order', async () => {
+    const session = { id: 'sess-1', element: 'mc-populated-blank' };
+    const updateSession = vi.fn().mockResolvedValue(undefined);
+    await model({ ...BASE_QUESTION, shuffle: true }, session, GATHER_ENV, updateSession);
+    expect(updateSession).toHaveBeenCalledOnce();
+    const [id, element, data] = updateSession.mock.calls[0];
+    expect(id).toBe('sess-1');
+    expect(element).toBe('mc-populated-blank');
+    expect(data.shuffledValues).toHaveLength(3);
+    expect(new Set(data.shuffledValues)).toEqual(new Set(['a', 'b', 'c']));
+  });
+
+  it('M8: shuffle=true, no stored shuffle, no updateSession → shuffled silently without throw', async () => {
+    const session = { id: 'sess-1', element: 'mc-populated-blank' };
+    const result = (await model({ ...BASE_QUESTION, shuffle: true }, session, GATHER_ENV)) as any;
+    expect(result.choices).toHaveLength(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// model — output fields
+// ---------------------------------------------------------------------------
+
+describe('model — output fields', () => {
+  it('M9: evaluate mode → correctness, responseCorrect, correctChoiceId in output', async () => {
+    const result = await model(BASE_QUESTION, { choiceId: 'b' }, EVALUATE_ENV);
+    expect(result.correctness).toBe('correct');
+    expect(result.responseCorrect).toBe(true);
+    expect(result.correctChoiceId).toBe('b');
+  });
+
+  it('M10: gather mode → correctness fields absent', async () => {
+    const result = await model(BASE_QUESTION, { choiceId: 'b' }, GATHER_ENV);
+    expect(result.correctness).toBeUndefined();
+    expect(result.responseCorrect).toBeUndefined();
+    expect(result.correctChoiceId).toBeUndefined();
+  });
+
+  it('M11: instructor + view mode → teacherInstructions included when enabled', async () => {
+    const q = {
+      ...BASE_QUESTION,
+      teacherInstructions: 'Do this.',
+      teacherInstructionsEnabled: true,
+    };
+    const result = await model(q, {}, INSTRUCTOR_VIEW_ENV);
+    expect(result.teacherInstructions).toBe('Do this.');
+  });
+
+  it('M12: student role → teacherInstructions always null', async () => {
+    const q = {
+      ...BASE_QUESTION,
+      teacherInstructions: 'Do this.',
+      teacherInstructionsEnabled: true,
+    };
+    const result = await model(q, {}, GATHER_ENV);
+    expect(result.teacherInstructions).toBeNull();
+  });
+
+  it('M13: promptEnabled=true → prompt included', async () => {
+    const q = { ...BASE_QUESTION, promptEnabled: true, prompt: '<p>Hello</p>' };
+    const result = await model(q, {}, GATHER_ENV);
+    expect(result.prompt).toBe('<p>Hello</p>');
+  });
+
+  it('M14: promptEnabled=false → prompt null', async () => {
+    const q = { ...BASE_QUESTION, promptEnabled: false, prompt: '<p>Hello</p>' };
+    const result = await model(q, {}, GATHER_ENV);
+    expect(result.prompt).toBeNull();
+  });
+
+  it('M15: hasAudio=false → audioUrl null', async () => {
+    const q = { ...BASE_QUESTION, hasAudio: false, audioUrl: 'https://example.com/a.mp3' };
+    const result = await model(q, {}, GATHER_ENV);
+    expect(result.audioUrl).toBeNull();
+  });
+
+  it('M16: hasAudio=true → audioUrl passed through', async () => {
+    const q = { ...BASE_QUESTION, hasAudio: true, audioUrl: 'https://example.com/a.mp3' };
+    const result = await model(q, {}, GATHER_ENV);
+    expect(result.audioUrl).toBe('https://example.com/a.mp3');
+  });
+
+  it('M17: disabled=false in gather mode, disabled=true in view mode', async () => {
+    const gather = await model(BASE_QUESTION, {}, GATHER_ENV);
+    const view = await model(BASE_QUESTION, {}, { mode: 'view', role: 'student' });
+    expect(gather.disabled).toBe(false);
+    expect(view.disabled).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validate
+// ---------------------------------------------------------------------------
+
+describe('validate', () => {
+  it('V1: valid question → empty errors', () => {
+    expect(validate(BASE_QUESTION)).toEqual({});
+  });
+
+  it('V2: promptEnabled + empty prompt → prompt error', () => {
+    const errors = validate({ ...BASE_QUESTION, promptEnabled: true, prompt: '' });
+    expect(errors.prompt).toBeTruthy();
+  });
+
+  it('V3: populate_blank with no blank token → template error', () => {
+    const errors = validate({ ...BASE_QUESTION, template: '<p>No token here.</p>' });
+    expect(errors.template).toBeTruthy();
+  });
+
+  it('V4: populate_blank with two blank tokens → template error', () => {
+    const errors = validate({ ...BASE_QUESTION, template: '<p>{{blank}} and {{blank}}</p>' });
+    expect(errors.template).toBeTruthy();
+  });
+
+  it('V5: audio_mc_only with a blank token in template → template error', () => {
+    const errors = validate({
+      ...BASE_QUESTION,
+      interactionMode: 'audio_mc_only',
+      template: '<p>{{blank}}</p>',
+    });
+    expect(errors.template).toBeTruthy();
+  });
+
+  it('V6: unknown interactionMode → interactionMode error', () => {
+    const errors = validate({ ...BASE_QUESTION, interactionMode: 'unknown' as any });
+    expect(errors.interactionMode).toBeTruthy();
+  });
+
+  it('V7: fewer than two choices → choices error', () => {
+    const errors = validate({ ...BASE_QUESTION, choices: [CHOICES[0]] });
+    expect(errors.choices).toBeTruthy();
+  });
+
+  it('V8: choice missing id → choices error', () => {
+    const errors = validate({
+      ...BASE_QUESTION,
+      choices: [{ id: '', labelHtml: '<p>A</p>' }, CHOICES[1]],
+    });
+    expect(errors.choices).toBeTruthy();
+  });
+
+  it('V9: text mode choice missing labelHtml → choices error', () => {
+    const errors = validate({
+      ...BASE_QUESTION,
+      choiceMode: 'text',
+      choices: [{ id: 'a', labelHtml: '' }, CHOICES[1]],
+    });
+    expect(errors.choices).toBeTruthy();
+  });
+
+  it('V10: image mode choice missing imageUrl → choices error', () => {
+    const errors = validate({
+      ...BASE_QUESTION,
+      choiceMode: 'image',
+      choices: [
+        { id: 'a', imageUrl: '', imageAlt: 'Alt' },
+        { id: 'b', imageUrl: 'https://example.com/b.png', imageAlt: 'B' },
+      ],
+    });
+    expect(errors.choices).toBeTruthy();
+  });
+
+  it('V11: image mode choice missing imageAlt → choices error', () => {
+    const errors = validate({
+      ...BASE_QUESTION,
+      choiceMode: 'image',
+      choices: [
+        { id: 'a', imageUrl: 'https://example.com/a.png', imageAlt: '' },
+        { id: 'b', imageUrl: 'https://example.com/b.png', imageAlt: 'B' },
+      ],
+    });
+    expect(errors.choices).toBeTruthy();
+  });
+
+  it('V12: correctChoiceId not in choices → correctChoiceId error', () => {
+    const errors = validate({ ...BASE_QUESTION, correctChoiceId: 'z' });
+    expect(errors.correctChoiceId).toBeTruthy();
+  });
+
+  it('V13: hasAudio=true with no audioUrl → audioUrl error', () => {
+    const errors = validate({ ...BASE_QUESTION, hasAudio: true, audioUrl: '' });
+    expect(errors.audioUrl).toBeTruthy();
+  });
+
+  it('V14: layoutLimits with non-positive value → layoutLimits error', () => {
+    const errors = validate({
+      ...BASE_QUESTION,
+      layoutLimits: { blankStandaloneWidthRem: -1 } as any,
+    });
+    expect(errors.layoutLimits).toBeTruthy();
+  });
+
+  it('V15: layoutLimits with valid positive value → no error', () => {
+    const errors = validate({
+      ...BASE_QUESTION,
+      layoutLimits: { blankStandaloneWidthRem: 8 } as any,
+    });
+    expect(errors.layoutLimits).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createCorrectResponseSession
+// ---------------------------------------------------------------------------
+
+describe('createCorrectResponseSession', () => {
+  it('CR1: instructor + mode≠evaluate → session with correct choiceId', async () => {
+    const result = await createCorrectResponseSession(BASE_QUESTION, {
+      mode: 'view',
+      role: 'instructor',
+    });
+    expect(result).toMatchObject({ choiceId: 'b' });
+  });
+
+  it('CR2: student role → null', async () => {
+    const result = await createCorrectResponseSession(BASE_QUESTION, {
+      mode: 'view',
+      role: 'student',
+    });
+    expect(result).toBeNull();
+  });
+
+  it('CR3: evaluate mode (instructor) → null', async () => {
+    const result = await createCorrectResponseSession(BASE_QUESTION, {
+      mode: 'evaluate',
+      role: 'instructor',
+    });
+    expect(result).toBeNull();
+  });
+});