@intellectif/lk-core 0.8.2 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @intellectif/lk-core
 
+## 0.10.0
+
+### Minor Changes
+
+- a88b3f9: Multiple-choice options can carry a picture or a recording.
+
+  The A1/A2 picture-choice item ("which picture shows a cat?") and the minimal-pair listening item had no expression in the data contract: `media` sat above the question, one asset per activity, so four pictures as four options was not sayable.
+
+  `MultipleChoiceOption.media` adds it, additively — `text` stays required on every option, because it names the option in the accessible name and in the xAPI statement and is what the learner sees when a picture fails to load.
+
+  **Only `image` and `audio` are accepted.** `video` and `embed` are refused by the schema, and not out of caution: both render a control surface that swallows the click meant to select the option, so the learner could not choose it. An option also carries **no `playback` policy** — `maxPlays` binds per slot through a `MediaBudgetBinding`, and nothing has decided whether four recordings in one question share a budget or hold one each, so writing one is an error rather than a promise no renderer keeps.
+
+  A picture renders **inside** the option's label, so clicking it selects the option and its `alt` joins the accessible name. A recording renders **outside** the label, so pressing play does not commit the learner to that answer before they have heard the others. An option with no media renders exactly the markup it always did.
+
+  `alt` follows the rule activity media already uses — required and non-empty for an image, optional for audio. Note that on a picture-choice item the `alt` is part of the item: it can hand a screen-reader user the answer. The SDK requires it so an option is never silently inaccessible and leaves the wording to you; the authoring guide says so plainly.
+
+  Redaction keeps option media intact — it is what the learner picks — and removes only `isCorrect` and per-option `feedback`. Draft checks report an option's media under the codes media already uses (`media_url_required`, `media_alt_required`, `media_url_invalid`), plus one new code, `mc_option_media_kind`, for a refused `video` or `embed`.
+
+## 0.9.0
+
+### Minor Changes
+
+- 8ca07c8: Authoring: tell an unfinished question from a wrong one.
+
+  `validateActivity` answers "may this be stored?", and to that question a question an author added a second ago and a broken one get the same answer. An editor that used it as its only check reported every new question as an error — enough to disable a whole form's Save button and blank its preview.
+
+  **lk-core**
+
+  - `validateDraft(type, draft)` returns `{ status: 'complete', data, issues: [] }` or `{ status: 'incomplete' | 'invalid', issues }`. Each issue is a `ValidationError` plus a `severity`, at the paths `validateActivity` reports. Its `code` is documented per type in the authoring guide for every problem the checks recognise; anything else is the schema's own diagnostic, at `invalid`. There is deliberately no `success` boolean, which would have to call an incomplete draft either a success or a failure.
+  - It is stricter than `validateActivity` and never looser. It reports a title or option text that is only whitespace, a blank written-response `prompt` even beside `promptHtml`, a rubric criterion name that is only whitespace, a rubric whose weights are all 0 or add up to more than a number can hold, a fill-in-the-blanks match `locale` that is not a language tag (scoring would throw on it), and `redacted: true`. A `null` in a required field reads as not set; any other `null` the schema refuses is `null_not_allowed`, for every registered type. It does not report `minWords: 0`, which means no lower limit, or a rubric weight above 1.
+  - `createDraft(type, { newId })` returns an empty draft that `validateDraft` reports as `incomplete`. It invents no ids, and a new multiple-choice draft marks no option correct, so an untouched correctness control can never become an answer key.
+  - `ActivityTypeDescriptor.authoring` — `createDraft` and `checkDraft` — gives a registered type the same support. The three built-in descriptors carry one.
+
+  **lk-react**
+
+  - `<ActivityPreview>`, also at `@intellectif/lk-react/components/ActivityPreview`, renders a draft in any `renderMode` with a simulated `response` — marked with `evaluate()` in `review` — and renders a notice, or your `fallback` with the issues, while the draft is not complete. Nothing it renders is recorded, and a recording's play limit is enforced in memory in `practice` and `exam`. It checks the draft by content on every render, whatever order its keys are in, so an editor that rebuilds or reloads its payload does not restart the question being tried.
+  - `LkStrings` gains `previewIncomplete` and `previewInvalid`. A dictionary declared as a complete `LkStrings` must add both; partial overrides are unaffected.
+
+  Nothing that already exists changes behaviour in either package. lk-react's major version comes from its lk-core peer range.
+
 ## 0.8.2
 
 ### Patch Changes

package/README.md

@@ -16,7 +16,8 @@ npm install @intellectif/lk-core
 
 - **Activity schemas** for `multiple-choice`, `fill-in-the-blanks` and `written-response`, with semantic refinements (e.g. *at least one correct option*, *single-select ⇒ exactly one correct*, *passage ↔ blank-id bijection*, *image/embed require `alt`*). Loose at every level, so your sidecar fields survive validation.
 - **`validateActivity(type, data)`** — the authoritative runtime validator. Returns a typed `{ success, data }` or a structured `{ success: false, errors[] }`, and **throws `UnknownActivityTypeError` if `type` is not registered** — so guard it when validating a content bank that may carry types this build does not know. `validateItemGroup(data)` is the equivalent for a `Stimulus` + `ItemGroup` container, which `validateActivity` cannot take.
-- **An open type system** — `defineActivityType` / `registerActivityType` make an activity type a *value*, not a hard-coded union member: register one and `validateActivity`, `score`, `evaluate`, `redact` and `jsonSchemaFor` all work for it, with no SDK release.
+- **`validateDraft(type, draft)`** — for editors. Reports `complete`, `incomplete` (something not written yet) or `invalid` (something wrong), each issue with a `severity` and a `code` — documented for every problem the checks recognise — and deliberately no `success` boolean to misread. Stricter than `validateActivity`, never looser. **`createDraft(type, { newId })`** returns an empty draft to start from; a multiple-choice draft marks no option correct.
+- **An open type system** — `defineActivityType` / `registerActivityType` make an activity type a *value*, not a hard-coded union member: register one and `validateActivity`, `validateDraft`, `score`, `evaluate`, `redact` and `jsonSchemaFor` all work for it, with no SDK release. An `authoring` block on the descriptor gives it draft support.
 - **JSON Schema (Draft-7) export** — `jsonSchemaFor(type)` for any registered type (plus the static per-type exports), suitable for form generators or AI prompting.
 - **Scoring engine** — `score(activityType, data, response)` returning `{ score ∈ [0,1], maxScore: 1, passed, feedback, details }`. Pure, deterministic, 100 % test coverage enforced. It **throws** rather than inventing a number: `DeferredScoringError` for a deferred-graded type (`written-response`), and `RedactedScoringError` when handed a `redact()` projection, which has no answer key. Both are on the documented exam path — use `evaluate()` there, which returns `deferred` / `unscorable` instead of throwing.
 - **`evaluate(data, response)` → `ItemOutcome`** — the resilient result: `scored`, `deferred` (graded later by an AI or a human), `graded` (the grade came back), or `unscorable`. "Not graded yet" is expressible in the type system and is never conflated with a zero.
@@ -114,8 +115,8 @@ result.passed;   // boolean, or null while provisional. Never record a provision
 | `@intellectif/lk-core/xapi` | `xAPIBuilder`, `XAPIVerb`, `validateXAPIStatement` |
 
 The barrel re-exports everything, and it is the **only** entry point for attempt
-plans, attempt state, item groups, redaction, the type registry and content
-hashing — those have no subpath of their own.
+plans, attempt state, item groups, redaction, the type registry, authoring drafts
+and content hashing — those have no subpath of their own.
 
 All exports ship as ESM + CJS with `.d.ts` types. Tree-shakeable; `sideEffects: false`. Node >= 20. In browsers, the SDK's own code needs `Object.hasOwn` — Chrome and Edge 93, Firefox 92, Safari 15.4 — because output targets ES2022 and nothing is polyfilled.
 Zod is the single runtime dependency: the package depends on `zod@^3.25` and imports the **Zod 4 API** from its `zod/v4` subpath, so it coexists with an app still on Zod 3.
@@ -125,7 +126,7 @@ Zod is the single runtime dependency: the package depends on `zod@^3.25` and imp
 - [Upgrading](https://github.com/intellectif/learning-kit/blob/main/docs/upgrading.md) — start here on any upgrade from 0.3.x, 0.4.x or 0.5.x.
 - [Changelog](https://github.com/intellectif/learning-kit/blob/main/packages/lk-core/CHANGELOG.md) — every release, with the reasoning.
 - [Grade-stability vectors](https://github.com/intellectif/learning-kit/blob/main/packages/lk-core/vectors/README.md) — the package's grading frozen as data; replay it against the build you install.
-- [Authoring & content storage](https://github.com/intellectif/learning-kit/blob/main/docs/authoring.md) — data model, validation, fetch → validate → render flow.
+- [Authoring & content storage](https://github.com/intellectif/learning-kit/blob/main/docs/authoring.md) — data model, validation, fetch → validate → render flow, and building an editor (the draft issue codes).
 - [Project README](https://github.com/intellectif/learning-kit#readme) — the full picture, including the React renderers.
 - [Contributing](https://github.com/intellectif/learning-kit/blob/main/CONTRIBUTING.md) — adding a new activity type.
 

package/dist/{activity-CPtJUBek.d.cts → activity-B0zbvu18.d.cts}

@@ -359,6 +359,7 @@ interface ActivityDataMap {
     'multiple-choice': MultipleChoiceData;
     'fill-in-the-blanks': FillInTheBlanksData;
     'written-response': WrittenResponseData;
+    'gap-select': GapSelectData;
 }
 /**
  * The set of activity types supported by learning-kit. Derived from
@@ -447,15 +448,64 @@ interface ActivityFeedback {
     incorrect?: string;
 }
 /** A single selectable option within a Multiple Choice activity. */
+/**
+ * A picture or a recording carried by ONE multiple-choice option — the
+ * A1/A2 picture-choice item, and the minimal-pair listening item.
+ *
+ * Narrower than {@link ActivityMedia}, which sits above the question, and
+ * deliberately so. An option is a click target, and two of the activity-level
+ * kinds cannot be one:
+ *
+ * - **`embed` is refused.** A provider iframe swallows pointer events, so
+ *   clicking the option would play the video instead of selecting the answer.
+ *   The learner could not choose it at all.
+ * - **`video` is refused** for the same reason one step down: a native control
+ *   bar inside the option's label eats the clicks meant for the radio.
+ * - **No `playback` policy.** `maxPlays` binds per slot through a
+ *   `MediaBudgetBinding`, and four recordings in one question raise a question
+ *   nothing has answered yet — whether the budget belongs to the option or to
+ *   the item. Until something asks, an option plays through the browser's own
+ *   bar and counts nothing.
+ *
+ * `alt` follows the same rule {@link ActivityMedia} uses, so there is only one
+ * rule to learn: required and non-empty for an image, optional for audio, where
+ * it becomes the player's accessible label.
+ *
+ * **On an image option, `alt` is part of the item.** It joins the option's
+ * `text` in the radio's accessible name, so on "which picture shows a cat?" an
+ * `alt` of "a cat" hands a screen-reader user the answer that a sighted learner
+ * has to work out. That is a property of picture-choice items, not something a
+ * schema can fix — the SDK requires `alt` so an option is never SILENTLY
+ * inaccessible, and leaves the wording, and the item's validity, to the author.
+ */
+interface MultipleChoiceOptionMedia {
+    /** `image` for a picture-choice option, `audio` for a listening option. */
+    type: 'image' | 'audio';
+    /** Address of the file. Same scheme allow-list as {@link ActivityMedia}. */
+    url: string;
+    /** Required and non-empty for `image`; an optional accessible label for `audio`. */
+    alt?: string;
+    /** WebVTT captions for an audio option, rendered as a `<track>`. */
+    captionsUrl?: string;
+}
 interface MultipleChoiceOption {
     /** Unique identifier for this option within the activity. */
     id: string;
-    /** Display text shown to the learner. */
+    /**
+     * Display text shown to the learner.
+     *
+     * Required even when the option carries {@link media}: it names the option in
+     * the radio's accessible name and in the xAPI statement, and it is what the
+     * learner sees if a picture fails to load. For a pure picture-choice option,
+     * a neutral label ("Picture 1") keeps the naming out of the answer.
+     */
     text: string;
     /** Whether this option is part of the correct answer. */
     isCorrect: boolean;
     /** Optional per-option feedback shown after submission. */
     feedback?: string;
+    /** An optional picture or recording shown as part of this option. */
+    media?: MultipleChoiceOptionMedia;
 }
 /** Data contract for a Multiple Choice activity. */
 interface MultipleChoiceData {
@@ -528,6 +578,116 @@ interface BlankConfig {
     feedback?: string;
 }
 /** Data contract for a Fill-in-the-Blanks activity. */
+/** One selectable option in a Gap Select activity. */
+interface GapSelectChoice {
+    /** Unique identifier within the choice set the gap resolves to. */
+    id: string;
+    /** The text the learner reads in the selector. */
+    text: string;
+}
+/**
+ * A named set of choices several gaps can draw from — a word bank.
+ *
+ * A bank is what makes distractors possible: three gaps sharing a bank of five
+ * choices means every selector offers all five, and two of them answer no gap
+ * at all. That is the difference between a reading-comprehension item and a
+ * sequence of three-way guesses, so it is modelled once here rather than
+ * retrofitted after per-gap lists ship.
+ */
+interface GapSelectBank {
+    /** Unique identifier referenced by {@link GapSelectGap.bankId}. */
+    id: string;
+    /** The choices every gap on this bank offers. */
+    choices: GapSelectChoice[];
+}
+/**
+ * One gap in the passage, matching a `{{gap_id}}` placeholder.
+ *
+ * Its choices come from exactly one place: `choices` for a list of its own, or
+ * `bankId` for a shared word bank. Both, or neither, is an authoring error the
+ * schema rejects — with two sources a reader cannot tell which list the learner
+ * is offered, and the answer key means nothing without one.
+ */
+interface GapSelectGap {
+    /** Unique identifier matching the `{{gap_id}}` placeholder in the passage. */
+    id: string;
+    /** This gap's own choices. Mutually exclusive with {@link bankId}. */
+    choices?: GapSelectChoice[];
+    /** The {@link GapSelectBank} this gap draws from. Mutually exclusive with {@link choices}. */
+    bankId?: string;
+    /** The `id` of the one choice that is correct. Must exist in the resolved choice set. */
+    correctChoiceId: string;
+    /** Optional feedback shown inline next to this gap after submission. */
+    feedback?: string;
+}
+/**
+ * Data contract for a Gap Select activity: a passage whose gaps the learner
+ * fills by choosing from a list rather than typing.
+ *
+ * It is deliberately **not** a mode of {@link FillInTheBlanksData}, though the
+ * passage and its `{{id}}` placeholders are authored the same way. A learner
+ * picking from a selector cannot mistype, so the whole `TextMatchPolicy`
+ * surface — diacritic folding, typo tolerance, locale-aware case — is not just
+ * unused but misleading. Scoring is identity comparison of a choice id.
+ * Redaction inverts too: in Fill-in-the-Blanks the candidate answers ARE the
+ * key, while here the learner must be shown every choice and only
+ * `correctChoiceId` is withheld.
+ */
+interface GapSelectData {
+    schemaVersion: '1.0';
+    type: 'gap-select';
+    /** Unique identifier for this activity. */
+    id: string;
+    /** Human-readable title used in xAPI statements and error boundaries. */
+    title: string;
+    /** Passage text containing `{{gap_id}}` placeholders. */
+    passage: string;
+    /**
+     * Optional sanitised rich-HTML rendering of the passage. Carried and redacted
+     * as learner-visible content; not rendered by the SDK, for the same reason
+     * `FillInTheBlanksData.passageHtml` is not — slicing sanitised HTML at the
+     * placeholders to host the selectors is both lossy and unsafe.
+     */
+    passageHtml?: string;
+    /** Every gap in the passage, one per distinct `{{id}}` placeholder. */
+    gaps: GapSelectGap[];
+    /** Shared word banks. Only needed by gaps that set `bankId`. */
+    banks?: GapSelectBank[];
+    /** Scoring algorithm applied when the learner submits. */
+    scoringStrategy: 'all-or-nothing' | 'partial';
+    /**
+     * How the choices are presented. Only `'dropdown'` exists today, and it is
+     * the default.
+     *
+     * The field is here rather than assumed because a drag-and-drop presentation
+     * is the obvious next request, and WCAG 2.5.7 requires that a drag interface
+     * always keep a non-drag path — so the choice has to be expressible in the
+     * content, not decided by a component prop. `'drag'` is NOT accepted yet:
+     * shipping a value nothing renders would freeze an API this repository has
+     * not validated. Widening the union later is additive.
+     */
+    presentation?: 'dropdown';
+    /**
+     * Whether the SDK shuffles each selector's choices. Off by default.
+     *
+     * Like `MultipleChoiceData.shuffle`, this needs a seed to be reproducible at
+     * a remark — `<ActivitySequence>` refuses to shuffle without one outside
+     * `practice` mode.
+     */
+    shuffleChoices?: boolean;
+    /** Optional media shown above the passage. */
+    media?: ActivityMedia;
+    /** Optional authored overall feedback shown after submission. */
+    feedback?: ActivityFeedback;
+    /** Minimum scaled score [0–1] required to pass. Defaults to {@link DEFAULT_PASS_THRESHOLD} (0.7) when absent. */
+    passThreshold?: number;
+    /** BCP 47 language tag for the activity content. */
+    locale?: string;
+    /** IRI references to learning objectives addressed by this activity. */
+    learningObjectives?: string[];
+    /** Subjective difficulty on a 1–5 scale. */
+    difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+}
 interface FillInTheBlanksData {
     schemaVersion: '1.0';
     type: 'fill-in-the-blanks';
@@ -630,6 +790,7 @@ interface LearnerResponseMap {
     'multiple-choice': MultipleChoiceLearnerResponse;
     'fill-in-the-blanks': FillInTheBlanksLearnerResponse;
     'written-response': WrittenResponseLearnerResponse;
+    'gap-select': GapSelectLearnerResponse;
 }
 /** Union of all learner response shapes. */
 type LearnerResponse = LearnerResponseMap[keyof LearnerResponseMap];
@@ -645,6 +806,20 @@ interface FillInTheBlanksLearnerResponse {
     /** Map of blank ID to the learner's typed answer. */
     answers: Record<string, string>;
 }
+/**
+ * Learner response for a Gap Select activity.
+ *
+ * A gap the learner has not answered is **absent from the map, or holds an
+ * empty string** — the two are equivalent, because a `<select>` whose
+ * placeholder is still showing submits `''`. Neither is a wrong answer: the
+ * scorer reports it as `incorrect-omission`, which is how a blank the learner
+ * never reached is told apart from one they got wrong.
+ */
+interface GapSelectLearnerResponse {
+    type: 'gap-select';
+    /** Map of gap ID to the ID of the choice the learner selected. */
+    selections: Record<string, string>;
+}
 /** Learner response for a Written Response activity. */
 interface WrittenResponseLearnerResponse {
     type: 'written-response';
@@ -845,4 +1020,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredScoringPartial as D, type XAPIError as E, type FillInTheBlanksData as F, type GradeRecord as G, type XAPIObject as H, type InlineCorrection as I, type XAPIResult as J, type XAPIScore as K, type LearnerResponse as L, type MultipleChoiceData as M, type NativeControlHint as N, type XAPIStatement as O, type XAPIVerbObject as P, levenshteinDistance as Q, matchText as R, type ScoringDetail as S, type TextMatchPolicy as T, type ValidationError as V, type WrittenResponseData as W, type XAPIActor as X, type ActivityDataMap as a, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type FillInTheBlanksLearnerResponse as f, type Grader as g, type GraderKind as h, type GraderUsage as i, type GradingState as j, type InteractionEvent as k, type InteractionKind as l, type ItemOutcome as m, type LearnerResponseMap as n, type MultipleChoiceLearnerResponse as o, type MultipleChoiceOption as p, type ScoringOutcome as q, type ScoringResult as r, type TextMatchResult as s, type ValidationResult as t, type WrittenResponseLearnerResponse as u, type WrittenResponseRubric as v, type WrittenResponseRubricCriterion as w, type XAPIConfig as x, type XAPIContext as y, type XAPIContextActivities as z };
+export { type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredScoringPartial as D, type XAPIContextActivities as E, type FillInTheBlanksData as F, type GradeRecord as G, type XAPIError as H, type InlineCorrection as I, type XAPIObject as J, type XAPIResult as K, type LearnerResponse as L, type MultipleChoiceData as M, type NativeControlHint as N, type XAPIScore as O, type XAPIStatement as P, type XAPIVerbObject as Q, levenshteinDistance as R, type ScoringDetail as S, type TextMatchPolicy as T, matchText as U, type ValidationError as V, type WrittenResponseData as W, type XAPIActor as X, type ActivityDataMap as a, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type FillInTheBlanksLearnerResponse as f, type Grader as g, type GraderKind as h, type GraderUsage as i, type GradingState as j, type InteractionEvent as k, type InteractionKind as l, type ItemOutcome as m, type LearnerResponseMap as n, type MultipleChoiceLearnerResponse as o, type MultipleChoiceOption as p, type MultipleChoiceOptionMedia as q, type ScoringOutcome as r, type ScoringResult as s, type TextMatchResult as t, type ValidationResult as u, type WrittenResponseLearnerResponse as v, type WrittenResponseRubric as w, type WrittenResponseRubricCriterion as x, type XAPIConfig as y, type XAPIContext as z };

package/dist/{activity-CPtJUBek.d.ts → activity-B0zbvu18.d.ts}

@@ -359,6 +359,7 @@ interface ActivityDataMap {
     'multiple-choice': MultipleChoiceData;
     'fill-in-the-blanks': FillInTheBlanksData;
     'written-response': WrittenResponseData;
+    'gap-select': GapSelectData;
 }
 /**
  * The set of activity types supported by learning-kit. Derived from
@@ -447,15 +448,64 @@ interface ActivityFeedback {
     incorrect?: string;
 }
 /** A single selectable option within a Multiple Choice activity. */
+/**
+ * A picture or a recording carried by ONE multiple-choice option — the
+ * A1/A2 picture-choice item, and the minimal-pair listening item.
+ *
+ * Narrower than {@link ActivityMedia}, which sits above the question, and
+ * deliberately so. An option is a click target, and two of the activity-level
+ * kinds cannot be one:
+ *
+ * - **`embed` is refused.** A provider iframe swallows pointer events, so
+ *   clicking the option would play the video instead of selecting the answer.
+ *   The learner could not choose it at all.
+ * - **`video` is refused** for the same reason one step down: a native control
+ *   bar inside the option's label eats the clicks meant for the radio.
+ * - **No `playback` policy.** `maxPlays` binds per slot through a
+ *   `MediaBudgetBinding`, and four recordings in one question raise a question
+ *   nothing has answered yet — whether the budget belongs to the option or to
+ *   the item. Until something asks, an option plays through the browser's own
+ *   bar and counts nothing.
+ *
+ * `alt` follows the same rule {@link ActivityMedia} uses, so there is only one
+ * rule to learn: required and non-empty for an image, optional for audio, where
+ * it becomes the player's accessible label.
+ *
+ * **On an image option, `alt` is part of the item.** It joins the option's
+ * `text` in the radio's accessible name, so on "which picture shows a cat?" an
+ * `alt` of "a cat" hands a screen-reader user the answer that a sighted learner
+ * has to work out. That is a property of picture-choice items, not something a
+ * schema can fix — the SDK requires `alt` so an option is never SILENTLY
+ * inaccessible, and leaves the wording, and the item's validity, to the author.
+ */
+interface MultipleChoiceOptionMedia {
+    /** `image` for a picture-choice option, `audio` for a listening option. */
+    type: 'image' | 'audio';
+    /** Address of the file. Same scheme allow-list as {@link ActivityMedia}. */
+    url: string;
+    /** Required and non-empty for `image`; an optional accessible label for `audio`. */
+    alt?: string;
+    /** WebVTT captions for an audio option, rendered as a `<track>`. */
+    captionsUrl?: string;
+}
 interface MultipleChoiceOption {
     /** Unique identifier for this option within the activity. */
     id: string;
-    /** Display text shown to the learner. */
+    /**
+     * Display text shown to the learner.
+     *
+     * Required even when the option carries {@link media}: it names the option in
+     * the radio's accessible name and in the xAPI statement, and it is what the
+     * learner sees if a picture fails to load. For a pure picture-choice option,
+     * a neutral label ("Picture 1") keeps the naming out of the answer.
+     */
     text: string;
     /** Whether this option is part of the correct answer. */
     isCorrect: boolean;
     /** Optional per-option feedback shown after submission. */
     feedback?: string;
+    /** An optional picture or recording shown as part of this option. */
+    media?: MultipleChoiceOptionMedia;
 }
 /** Data contract for a Multiple Choice activity. */
 interface MultipleChoiceData {
@@ -528,6 +578,116 @@ interface BlankConfig {
     feedback?: string;
 }
 /** Data contract for a Fill-in-the-Blanks activity. */
+/** One selectable option in a Gap Select activity. */
+interface GapSelectChoice {
+    /** Unique identifier within the choice set the gap resolves to. */
+    id: string;
+    /** The text the learner reads in the selector. */
+    text: string;
+}
+/**
+ * A named set of choices several gaps can draw from — a word bank.
+ *
+ * A bank is what makes distractors possible: three gaps sharing a bank of five
+ * choices means every selector offers all five, and two of them answer no gap
+ * at all. That is the difference between a reading-comprehension item and a
+ * sequence of three-way guesses, so it is modelled once here rather than
+ * retrofitted after per-gap lists ship.
+ */
+interface GapSelectBank {
+    /** Unique identifier referenced by {@link GapSelectGap.bankId}. */
+    id: string;
+    /** The choices every gap on this bank offers. */
+    choices: GapSelectChoice[];
+}
+/**
+ * One gap in the passage, matching a `{{gap_id}}` placeholder.
+ *
+ * Its choices come from exactly one place: `choices` for a list of its own, or
+ * `bankId` for a shared word bank. Both, or neither, is an authoring error the
+ * schema rejects — with two sources a reader cannot tell which list the learner
+ * is offered, and the answer key means nothing without one.
+ */
+interface GapSelectGap {
+    /** Unique identifier matching the `{{gap_id}}` placeholder in the passage. */
+    id: string;
+    /** This gap's own choices. Mutually exclusive with {@link bankId}. */
+    choices?: GapSelectChoice[];
+    /** The {@link GapSelectBank} this gap draws from. Mutually exclusive with {@link choices}. */
+    bankId?: string;
+    /** The `id` of the one choice that is correct. Must exist in the resolved choice set. */
+    correctChoiceId: string;
+    /** Optional feedback shown inline next to this gap after submission. */
+    feedback?: string;
+}
+/**
+ * Data contract for a Gap Select activity: a passage whose gaps the learner
+ * fills by choosing from a list rather than typing.
+ *
+ * It is deliberately **not** a mode of {@link FillInTheBlanksData}, though the
+ * passage and its `{{id}}` placeholders are authored the same way. A learner
+ * picking from a selector cannot mistype, so the whole `TextMatchPolicy`
+ * surface — diacritic folding, typo tolerance, locale-aware case — is not just
+ * unused but misleading. Scoring is identity comparison of a choice id.
+ * Redaction inverts too: in Fill-in-the-Blanks the candidate answers ARE the
+ * key, while here the learner must be shown every choice and only
+ * `correctChoiceId` is withheld.
+ */
+interface GapSelectData {
+    schemaVersion: '1.0';
+    type: 'gap-select';
+    /** Unique identifier for this activity. */
+    id: string;
+    /** Human-readable title used in xAPI statements and error boundaries. */
+    title: string;
+    /** Passage text containing `{{gap_id}}` placeholders. */
+    passage: string;
+    /**
+     * Optional sanitised rich-HTML rendering of the passage. Carried and redacted
+     * as learner-visible content; not rendered by the SDK, for the same reason
+     * `FillInTheBlanksData.passageHtml` is not — slicing sanitised HTML at the
+     * placeholders to host the selectors is both lossy and unsafe.
+     */
+    passageHtml?: string;
+    /** Every gap in the passage, one per distinct `{{id}}` placeholder. */
+    gaps: GapSelectGap[];
+    /** Shared word banks. Only needed by gaps that set `bankId`. */
+    banks?: GapSelectBank[];
+    /** Scoring algorithm applied when the learner submits. */
+    scoringStrategy: 'all-or-nothing' | 'partial';
+    /**
+     * How the choices are presented. Only `'dropdown'` exists today, and it is
+     * the default.
+     *
+     * The field is here rather than assumed because a drag-and-drop presentation
+     * is the obvious next request, and WCAG 2.5.7 requires that a drag interface
+     * always keep a non-drag path — so the choice has to be expressible in the
+     * content, not decided by a component prop. `'drag'` is NOT accepted yet:
+     * shipping a value nothing renders would freeze an API this repository has
+     * not validated. Widening the union later is additive.
+     */
+    presentation?: 'dropdown';
+    /**
+     * Whether the SDK shuffles each selector's choices. Off by default.
+     *
+     * Like `MultipleChoiceData.shuffle`, this needs a seed to be reproducible at
+     * a remark — `<ActivitySequence>` refuses to shuffle without one outside
+     * `practice` mode.
+     */
+    shuffleChoices?: boolean;
+    /** Optional media shown above the passage. */
+    media?: ActivityMedia;
+    /** Optional authored overall feedback shown after submission. */
+    feedback?: ActivityFeedback;
+    /** Minimum scaled score [0–1] required to pass. Defaults to {@link DEFAULT_PASS_THRESHOLD} (0.7) when absent. */
+    passThreshold?: number;
+    /** BCP 47 language tag for the activity content. */
+    locale?: string;
+    /** IRI references to learning objectives addressed by this activity. */
+    learningObjectives?: string[];
+    /** Subjective difficulty on a 1–5 scale. */
+    difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+}
 interface FillInTheBlanksData {
     schemaVersion: '1.0';
     type: 'fill-in-the-blanks';
@@ -630,6 +790,7 @@ interface LearnerResponseMap {
     'multiple-choice': MultipleChoiceLearnerResponse;
     'fill-in-the-blanks': FillInTheBlanksLearnerResponse;
     'written-response': WrittenResponseLearnerResponse;
+    'gap-select': GapSelectLearnerResponse;
 }
 /** Union of all learner response shapes. */
 type LearnerResponse = LearnerResponseMap[keyof LearnerResponseMap];
@@ -645,6 +806,20 @@ interface FillInTheBlanksLearnerResponse {
     /** Map of blank ID to the learner's typed answer. */
     answers: Record<string, string>;
 }
+/**
+ * Learner response for a Gap Select activity.
+ *
+ * A gap the learner has not answered is **absent from the map, or holds an
+ * empty string** — the two are equivalent, because a `<select>` whose
+ * placeholder is still showing submits `''`. Neither is a wrong answer: the
+ * scorer reports it as `incorrect-omission`, which is how a blank the learner
+ * never reached is told apart from one they got wrong.
+ */
+interface GapSelectLearnerResponse {
+    type: 'gap-select';
+    /** Map of gap ID to the ID of the choice the learner selected. */
+    selections: Record<string, string>;
+}
 /** Learner response for a Written Response activity. */
 interface WrittenResponseLearnerResponse {
     type: 'written-response';
@@ -845,4 +1020,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredScoringPartial as D, type XAPIError as E, type FillInTheBlanksData as F, type GradeRecord as G, type XAPIObject as H, type InlineCorrection as I, type XAPIResult as J, type XAPIScore as K, type LearnerResponse as L, type MultipleChoiceData as M, type NativeControlHint as N, type XAPIStatement as O, type XAPIVerbObject as P, levenshteinDistance as Q, matchText as R, type ScoringDetail as S, type TextMatchPolicy as T, type ValidationError as V, type WrittenResponseData as W, type XAPIActor as X, type ActivityDataMap as a, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type FillInTheBlanksLearnerResponse as f, type Grader as g, type GraderKind as h, type GraderUsage as i, type GradingState as j, type InteractionEvent as k, type InteractionKind as l, type ItemOutcome as m, type LearnerResponseMap as n, type MultipleChoiceLearnerResponse as o, type MultipleChoiceOption as p, type ScoringOutcome as q, type ScoringResult as r, type TextMatchResult as s, type ValidationResult as t, type WrittenResponseLearnerResponse as u, type WrittenResponseRubric as v, type WrittenResponseRubricCriterion as w, type XAPIConfig as x, type XAPIContext as y, type XAPIContextActivities as z };
+export { type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredScoringPartial as D, type XAPIContextActivities as E, type FillInTheBlanksData as F, type GradeRecord as G, type XAPIError as H, type InlineCorrection as I, type XAPIObject as J, type XAPIResult as K, type LearnerResponse as L, type MultipleChoiceData as M, type NativeControlHint as N, type XAPIScore as O, type XAPIStatement as P, type XAPIVerbObject as Q, levenshteinDistance as R, type ScoringDetail as S, type TextMatchPolicy as T, matchText as U, type ValidationError as V, type WrittenResponseData as W, type XAPIActor as X, type ActivityDataMap as a, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type FillInTheBlanksLearnerResponse as f, type Grader as g, type GraderKind as h, type GraderUsage as i, type GradingState as j, type InteractionEvent as k, type InteractionKind as l, type ItemOutcome as m, type LearnerResponseMap as n, type MultipleChoiceLearnerResponse as o, type MultipleChoiceOption as p, type MultipleChoiceOptionMedia as q, type ScoringOutcome as r, type ScoringResult as s, type TextMatchResult as t, type ValidationResult as u, type WrittenResponseLearnerResponse as v, type WrittenResponseRubric as w, type WrittenResponseRubricCriterion as x, type XAPIConfig as y, type XAPIContext as z };

package/dist/{chunk-FVLKIL6W.cjs → chunk-3FEAEO3D.cjs}

@@ -6,7 +6,8 @@
 
 
 
-var _chunkFKH4YT5Xcjs = require('./chunk-FKH4YT5X.cjs');
+
+var _chunk7ODQRNR4cjs = require('./chunk-7ODQRNR4.cjs');
 
 // src/schemas/item-group.ts
 var _v4 = require('zod/v4');
@@ -34,7 +35,7 @@ var StimulusSchema = _v4.z.looseObject({
   title: _v4.z.string().optional(),
   body: _v4.z.string().optional(),
   bodyHtml: _v4.z.string().optional(),
-  media: _chunkFKH4YT5Xcjs.MediaSchema.optional(),
+  media: _chunk7ODQRNR4cjs.MediaSchema.optional(),
   transcript: _v4.z.string().optional(),
   locale: _v4.z.string().optional(),
   attribution: _v4.z.string().optional()
@@ -84,7 +85,7 @@ var RedactedStimulusSchema = _v4.z.strictObject({
   title: _v4.z.string().optional(),
   body: _v4.z.string().optional(),
   bodyHtml: _v4.z.string().optional(),
-  media: _chunkFKH4YT5Xcjs.RedactedMediaSchema.optional(),
+  media: _chunk7ODQRNR4cjs.RedactedMediaSchema.optional(),
   locale: _v4.z.string().optional(),
   attribution: _v4.z.string().optional()
 });
@@ -114,7 +115,7 @@ function validateItemGroup(data) {
   const errors = [];
   const items = [];
   container.data.items.forEach((item, index) => {
-    const descriptor = _chunkFKH4YT5Xcjs.getActivityTypeDescriptor.call(void 0, item.type);
+    const descriptor = _chunk7ODQRNR4cjs.getActivityTypeDescriptor.call(void 0, item.type);
     if (descriptor === void 0) {
       errors.push({
         path: ["items", String(index), "type"],
@@ -140,28 +141,31 @@ function validateItemGroup(data) {
 
 var stimulusJsonSchema = _v4.z.toJSONSchema(StimulusSchema, { target: "draft-7" });
 var itemGroupJsonSchema = _v4.z.toJSONSchema(ItemGroupSchema, { target: "draft-7" });
-var multipleChoiceJsonSchema = _v4.z.toJSONSchema(_chunkFKH4YT5Xcjs.MultipleChoiceDataSchema, {
+var gapSelectJsonSchema = _v4.z.toJSONSchema(_chunk7ODQRNR4cjs.GapSelectDataSchema, {
+  target: "draft-7"
+});
+var multipleChoiceJsonSchema = _v4.z.toJSONSchema(_chunk7ODQRNR4cjs.MultipleChoiceDataSchema, {
   target: "draft-7"
 });
-var fillInTheBlanksJsonSchema = _v4.z.toJSONSchema(_chunkFKH4YT5Xcjs.FillInTheBlanksDataSchema, {
+var fillInTheBlanksJsonSchema = _v4.z.toJSONSchema(_chunk7ODQRNR4cjs.FillInTheBlanksDataSchema, {
   target: "draft-7"
 });
-var writtenResponseJsonSchema = _v4.z.toJSONSchema(_chunkFKH4YT5Xcjs.WrittenResponseDataSchema, {
+var writtenResponseJsonSchema = _v4.z.toJSONSchema(_chunk7ODQRNR4cjs.WrittenResponseDataSchema, {
   target: "draft-7"
 });
 function jsonSchemaFor(type) {
-  const descriptor = _chunkFKH4YT5Xcjs.getActivityTypeDescriptor.call(void 0, type);
+  const descriptor = _chunk7ODQRNR4cjs.getActivityTypeDescriptor.call(void 0, type);
   if (descriptor === void 0) {
-    throw new (0, _chunkFKH4YT5Xcjs.UnknownActivityTypeError)(type);
+    throw new (0, _chunk7ODQRNR4cjs.UnknownActivityTypeError)(type);
   }
   return _v4.z.toJSONSchema(descriptor.schema, { target: "draft-7" });
 }
 
 // src/schemas/index.ts
 function validateActivity(type, data) {
-  const descriptor = _chunkFKH4YT5Xcjs.getActivityTypeDescriptor.call(void 0, type);
+  const descriptor = _chunk7ODQRNR4cjs.getActivityTypeDescriptor.call(void 0, type);
   if (descriptor === void 0) {
-    throw new (0, _chunkFKH4YT5Xcjs.UnknownActivityTypeError)(String(type));
+    throw new (0, _chunk7ODQRNR4cjs.UnknownActivityTypeError)(String(type));
   }
   const result = descriptor.schema.safeParse(data);
   if (result.success) {
@@ -190,5 +194,6 @@ function validateActivity(type, data) {
 
 
 
-exports.StimulusSchema = StimulusSchema; exports.ItemGroupSchema = ItemGroupSchema; exports.RedactedStimulusSchema = RedactedStimulusSchema; exports.RedactedItemGroupSchema = RedactedItemGroupSchema; exports.validateItemGroup = validateItemGroup; exports.stimulusJsonSchema = stimulusJsonSchema; exports.itemGroupJsonSchema = itemGroupJsonSchema; exports.multipleChoiceJsonSchema = multipleChoiceJsonSchema; exports.fillInTheBlanksJsonSchema = fillInTheBlanksJsonSchema; exports.writtenResponseJsonSchema = writtenResponseJsonSchema; exports.jsonSchemaFor = jsonSchemaFor; exports.validateActivity = validateActivity;
-//# sourceMappingURL=chunk-FVLKIL6W.cjs.map
+
+exports.StimulusSchema = StimulusSchema; exports.ItemGroupSchema = ItemGroupSchema; exports.RedactedStimulusSchema = RedactedStimulusSchema; exports.RedactedItemGroupSchema = RedactedItemGroupSchema; exports.validateItemGroup = validateItemGroup; exports.stimulusJsonSchema = stimulusJsonSchema; exports.itemGroupJsonSchema = itemGroupJsonSchema; exports.gapSelectJsonSchema = gapSelectJsonSchema; exports.multipleChoiceJsonSchema = multipleChoiceJsonSchema; exports.fillInTheBlanksJsonSchema = fillInTheBlanksJsonSchema; exports.writtenResponseJsonSchema = writtenResponseJsonSchema; exports.jsonSchemaFor = jsonSchemaFor; exports.validateActivity = validateActivity;
+//# sourceMappingURL=chunk-3FEAEO3D.cjs.map