@intellectif/lk-core 1.1.0 → 1.3.0

package/dist/ai-B222dtHH.d.cts

@@ -0,0 +1,2154 @@
+//#region src/scoring/text-match.d.ts
+/**
+ * Configurable free-text answer matching (R3.3).
+ *
+ * Grade-stability contract: the DEFAULTS reproduce the v1 fill-in-the-blanks
+ * semantics exactly (trim, then locale-insensitive lowercase, strict `===`).
+ * Every tolerance below is opt-in, because changing a default here changes
+ * historical grades — and this SDK powers real summative exams.
+ */
+interface TextMatchPolicy {
+  /** Compare case-sensitively. Default `false` (v1 behaviour). */
+  caseSensitive?: boolean;
+  /** Strip leading/trailing whitespace before comparing. Default `true` (v1 behaviour). */
+  trim?: boolean;
+  /**
+   * Unicode normalization applied to both sides before comparing. Default
+   * `'none'` (v1 behaviour). `'NFC'` makes a decomposed `está` (combining
+   * U+0301) equal its composed form — the fix for accent-input mismatches in
+   * EN/ES/PT content.
+   */
+  normalize?: 'none' | 'NFC' | 'NFKC';
+  /** Treat diacritics as equal to their base letters (`está` ≡ `esta`). Default `false`. */
+  foldDiacritics?: boolean;
+  /** Collapse runs of inner whitespace to a single space. Default `false`. */
+  collapseInnerWhitespace?: boolean;
+  /** Ignore Unicode punctuation on both sides. Default `false`. */
+  ignorePunctuation?: boolean;
+  /** Maximum Levenshtein edit distance still accepted as a match. Default `0`. */
+  levenshtein?: number;
+  /**
+   * BCP 47 tag for locale-aware case folding (e.g. `'tr'` for Turkish dotted /
+   * dotless I). Default: locale-insensitive `toLowerCase()` (v1 behaviour).
+   */
+  locale?: string;
+}
+/**
+ * How a match was achieved. Lets a consumer award full credit for an `exact`
+ * match and partial credit for a `folded` or `fuzzy` one (e.g. diacritic
+ * tolerance in a listening gap-fill vs. a spelling test).
+ * - `exact` — equal under the baseline trim/case rules alone.
+ * - `normalized` — required Unicode normalization, whitespace collapse, or punctuation tolerance.
+ * - `folded` — required diacritic folding.
+ * - `fuzzy` — required Levenshtein tolerance.
+ * - `none` — no accepted answer matched.
+ */
+interface TextMatchResult {
+  matched: boolean;
+  via: 'exact' | 'normalized' | 'folded' | 'fuzzy' | 'none';
+}
+/**
+ * Levenshtein distance with an early-exit bound: returns `max + 1` as soon as
+ * the distance provably exceeds `max`.
+ */
+declare function levenshteinDistance(a: string, b: string, max: number): number;
+/**
+ * Matches a learner's input against one or more accepted answers under a
+ * {@link TextMatchPolicy}. Tolerances are evaluated in stages — baseline
+ * (trim/case), then normalization, then diacritic folding, then Levenshtein —
+ * and {@link TextMatchResult.via} reports the first stage that produced the
+ * match, so graders can award credit by match quality.
+ *
+ * With no policy (or an empty one) this is byte-for-byte the v1 matching
+ * semantics: `trim` + locale-insensitive `toLowerCase` + strict equality.
+ */
+declare function matchText(input: string, accepted: string | readonly string[], policy?: TextMatchPolicy): TextMatchResult;
+//#endregion
+//#region src/types/grading.d.ts
+/**
+ * Lifecycle of a deferred grade. A grade exists only in the `graded` state;
+ * every other state means "no grade, and here is why" — which is precisely the
+ * distinction that stops an ungraded submission being rendered as a zero.
+ */
+type GradingState = 'queued' | 'running' | 'graded' | 'failed' | 'skipped';
+/**
+ * Who produced a grade.
+ *
+ * - `'auto'` — a non-generative measurement engine, for example a
+ *   pronunciation-assessment service.
+ * - `'ai'` — a generative model.
+ * - `'human'` — a person.
+ */
+type GraderKind = 'ai' | 'human' | 'auto';
+/** Provenance of a grade, so a re-grade two years later is explicable. */
+interface Grader {
+  kind: GraderKind;
+  /** Identifier of the human grader, when `kind` is `'human'`. */
+  id?: string;
+  /** Model identifier, when `kind` is `'ai'` (e.g. a model name and version). */
+  model?: string;
+  /** Hash or id of the prompt/rubric revision used, for auditability. */
+  promptHash?: string;
+}
+/** Optional cost/usage telemetry emitted by an AI grader. */
+interface GraderUsage {
+  promptTokens?: number;
+  completionTokens?: number;
+  costUsd?: number;
+}
+/** A grader's verdict on one rubric criterion. */
+interface CriterionScore {
+  /** Matches a `WrittenResponseRubricCriterion.name` when a rubric is known. */
+  name: string;
+  /**
+   * The grader's score for this criterion, out of {@link CriterionScore.maxScore}
+   * (which defaults to 1, the SDK's scaled convention). Absent when the
+   * criterion is judged on an ordinal `band`.
+   */
+  score?: number;
+  /**
+   * What `score` is out of. Defaults to `1`.
+   *
+   * Real graders rarely work in [0,1]: rubrics come back out of 100, out of 9
+   * (CEFR/IELTS bands), or out of a points total that differs between
+   * criteria. Before this field the only way to use {@link gradeFromRubric}
+   * was to normalise by hand first — and a grader that skipped that step got
+   * its scores REJECTED, which pushed integrators back to letting the model
+   * compute the weighted total itself. That is precisely the arithmetic this
+   * SDK exists to take away from a language model.
+   *
+   * Set it per criterion, so a rubric mixing a /100 criterion with a /9 band
+   * score still composes. `gradeFromRubric` normalises `score / maxScore`
+   * before weighting; the resulting ratio must land in [0,1].
+   */
+  maxScore?: number;
+  /** Ordinal verdict when the rubric is banded rather than numeric (e.g. `"B1"`). */
+  band?: string;
+  /** The grader's comment for this criterion, addressed to the learner. */
+  comment?: string;
+  /**
+   * Weight actually applied, echoed from the rubric so the total is checkable.
+   * Defaults to `1`. Zero or more: `gradeFromRubric` refuses a negative weight
+   * rather than let it carry the total outside [0,1].
+   */
+  weight?: number;
+  /** Not applicable to this submission (e.g. interaction on a monologue task). */
+  notApplicable?: boolean;
+}
+/** A suggested correction anchored in the learner's own text. */
+interface InlineCorrection {
+  /** Verbatim span from the submission. */
+  original: string;
+  /** Suggested replacement. */
+  corrected: string;
+  explanation?: string;
+  /** Character offsets into the submitted text, so a UI can anchor it inline. */
+  range?: {
+    start: number;
+    end: number;
+  };
+  /** Error-type tag (`"article"`, `"tense"`, `"register"`). */
+  category?: string;
+}
+/**
+ * A grade that came back from an asynchronous grader. `score` is scaled
+ * [0,1] against `maxScore`, matching every other score in the SDK. A grader
+ * that works in points does not have to normalise by hand: declare
+ * `maxScore` on each {@link CriterionScore} and let `gradeFromRubric` do the
+ * arithmetic, which is the whole point of handing it the judgements.
+ *
+ * `maxScore` is a positive, finite number and `score` a finite number from 0
+ * to it. `outcomeFromGrade` refuses a record that is not, rather than mirror
+ * numbers nobody can defend onto an outcome.
+ */
+interface GradeRecord {
+  score: number;
+  maxScore: number;
+  passed: boolean;
+  /** Narrative feedback addressed to the learner. */
+  feedback: string | null;
+  /** Per-criterion breakdown, when the grader worked against a rubric. */
+  criteria?: CriterionScore[];
+  /**
+   * Per-item marks carried by a grade — for example the per-word marks of a
+   * read-aloud grade. `outcomeFromGrade` does not mirror them onto the
+   * outcome; read `outcome.grade.details`.
+   */
+  details?: ScoringDetail[];
+  /** Corrections anchored in the learner's text. */
+  corrections?: InlineCorrection[];
+  /** Supporting observations the grader cited. */
+  evidence?: string[];
+  /** How the grader reached this verdict. */
+  rationale?: string;
+  /** The grader's own confidence — a signal for routing to human review. */
+  confidence?: 'high' | 'medium' | 'low';
+  /** The grader is unsure or the submission is atypical; route to a human. */
+  requiresHumanReview?: boolean;
+  grader?: Grader;
+  usage?: GraderUsage;
+  /** ISO 8601 timestamp of when the grade was produced. */
+  gradedAt?: string;
+}
+//#endregion
+//#region src/types/xapi.d.ts
+/**
+ * An xAPI Activity object — the thing a statement is about.
+ * This SDK only builds Activity-type objects (xAPI 1.0.3 §4.1.4.1).
+ */
+interface XAPIObject {
+  objectType: 'Activity';
+  /** IRI uniquely identifying the activity. */
+  id: string;
+  definition?: {
+    /** Language-map of human-readable names for the activity. */
+    name?: Record<string, string>;
+    /** Language-map of human-readable descriptions. */
+    description?: Record<string, string>;
+    /** IRI identifying the activity type. */
+    type?: string;
+    /** xAPI 1.0.3 cmi.interaction type (e.g. `choice`, `fill-in`, `long-fill-in`). */
+    interactionType?: string;
+    /** Patterns describing the correct response(s), per the xAPI CRP format. */
+    correctResponsesPattern?: string[];
+    /** For `choice`-family interactions: the available components. */
+    choices?: Array<{
+      id: string;
+      description?: Record<string, string>;
+    }>;
+    extensions?: Record<string, unknown>;
+  };
+}
+/**
+ * An xAPI Agent (person or system) that performed the statement's verb.
+ * Exactly one of `mbox` or `account` must be present.
+ */
+interface XAPIActor {
+  objectType: 'Agent';
+  /** Display name for the actor. */
+  name?: string;
+  /** Mailto IRI uniquely identifying the actor (e.g. `mailto:user@example.com`). */
+  mbox?: string;
+  /** Account-based actor identifier. */
+  account?: {
+    /** IRI of the home page of the account's service provider. */
+    homePage: string;
+    /** The actor's unique name on that service. */
+    name: string;
+  };
+}
+/** An xAPI Verb — the action performed in the statement. */
+interface XAPIVerbObject {
+  /** IRI uniquely identifying this verb (e.g. from adlnet.gov/expapi/verbs). */
+  id: string;
+  /** Language-map of human-readable verb labels. */
+  display: Record<string, string>;
+}
+/** Score sub-object within an xAPI Result. */
+interface XAPIScore {
+  /** Normalized score in the range [0, 1]. */
+  scaled: number;
+  /** Raw score in the instrument's native scale. */
+  raw?: number;
+  /** Minimum possible raw score. */
+  min?: number;
+  /** Maximum possible raw score. */
+  max?: number;
+}
+/** Result information attached to an xAPI Statement. */
+interface XAPIResult {
+  score?: XAPIScore;
+  /** Whether the actor's performance was successful. */
+  success?: boolean;
+  /** Whether the activity was completed. */
+  completion?: boolean;
+  /** ISO 8601 duration string representing time spent (e.g. `PT5M30S`). */
+  duration?: string;
+  /** A string representation of the learner's response. */
+  response?: string;
+  extensions?: Record<string, unknown>;
+}
+/** Related-activity references attached to a statement's context. */
+interface XAPIContextActivities {
+  /** Activities this statement's activity is directly part of (e.g. the exam section). */
+  parent?: XAPIObject[];
+  /** Broader groupings (e.g. the course). */
+  grouping?: XAPIObject[];
+  /** Categorisations (e.g. a profile IRI). */
+  category?: XAPIObject[];
+  /** Other contextually related activities. */
+  other?: XAPIObject[];
+}
+/** Context information attached to an xAPI Statement. */
+interface XAPIContext {
+  /** Name of the software used to record the statement. */
+  platform?: string;
+  /** BCP 47 language tag for the activity content. */
+  language?: string;
+  /** Related activities (parent/grouping/category/other). */
+  contextActivities?: XAPIContextActivities;
+  extensions?: Record<string, unknown>;
+}
+/** A complete xAPI 1.0.3 Statement. */
+interface XAPIStatement {
+  /** UUID v4 uniquely identifying this statement. */
+  id: string;
+  actor: XAPIActor;
+  verb: XAPIVerbObject;
+  object: XAPIObject;
+  result?: XAPIResult;
+  context?: XAPIContext;
+  /** ISO 8601 timestamp of when the statement occurred. */
+  timestamp: string;
+  version: '1.0.3';
+}
+/**
+ * Configuration passed to `useXAPI` to connect to an LRS endpoint.
+ * The `auth` field supports both HTTP Basic and Bearer token authentication.
+ */
+interface XAPIConfig {
+  /** Full URL of the LRS statements endpoint. */
+  endpoint: string;
+  /** Authentication credentials for the LRS. */
+  auth: {
+    type: 'basic';
+    username: string;
+    password: string;
+  } | {
+    type: 'bearer';
+    token: string;
+  };
+  /**
+   * Replaces the SDK's placeholder object id (`urn:learning-kit:activity:*`)
+   * before a statement is sent.
+   *
+   * - `string` — the IRI for THE activity this hook instance serves. A hook
+   *   instance is per-activity by contract; with several activities sharing
+   *   one hook, a plain string would collapse their statements onto one IRI —
+   *   use the function form instead.
+   * - `(sdkObjectId) => string` — maps each placeholder id (which embeds the
+   *   activity's `data.id`) to its deployment IRI, for pages that send many
+   *   activities through one hook.
+   *
+   * Object ids the consumer already rewrote (non-`urn:learning-kit:` ids) are
+   * never touched.
+   */
+  activityId: string | ((sdkObjectId: string) => string);
+  actor: XAPIActor;
+  /** Called after all retry attempts are exhausted. */
+  onError?: (err: XAPIError) => void;
+}
+/** Error payload delivered to `XAPIConfig.onError` after retries are exhausted. */
+interface XAPIError {
+  /** The statement that failed to send. */
+  statement: XAPIStatement;
+  /** The 1-based attempt number on which the final failure occurred. */
+  attempt: number;
+  /** HTTP status code from the LRS, if a response was received. */
+  statusCode?: number;
+  /** Human-readable error description. */
+  message: string;
+}
+//#endregion
+//#region src/types/activity.d.ts
+/**
+ * Maps each ActivityType string to its corresponding data shape.
+ *
+ * Open for extension via TypeScript module augmentation: a consumer that
+ * registers a custom activity type (`registerActivityType`) can augment this
+ * interface so `ActivityType`, `ActivityData`, `validateActivity`, and
+ * `evaluate` pick the new type up without an SDK release:
+ *
+ * ```ts
+ * declare module '@intellectif/lk-core' {
+ *   interface ActivityDataMap { 'my-type': MyTypeData }
+ *   interface LearnerResponseMap { 'my-type': MyTypeLearnerResponse }
+ * }
+ * ```
+ */
+interface ActivityDataMap {
+  'multiple-choice': MultipleChoiceData;
+  'fill-in-the-blanks': FillInTheBlanksData;
+  'written-response': WrittenResponseData;
+  'gap-select': GapSelectData;
+  dictation: DictationData;
+  'read-aloud': ReadAloudData;
+}
+/**
+ * The set of activity types supported by learning-kit. Derived from
+ * {@link ActivityDataMap}, so module augmentation widens it automatically.
+ */
+type ActivityType = keyof ActivityDataMap;
+/** Union of all valid activity data shapes. */
+type ActivityData = ActivityDataMap[ActivityType];
+/** A text track for an `audio` or `video` recording. */
+interface MediaTrack {
+  kind: 'captions' | 'subtitles';
+  /** WebVTT URL. A player may fetch it through a loader the host supplies, with the host's credentials. */
+  src: string;
+  /** BCP 47 language tag of the text (`en`, `es`, `pt-BR`). */
+  srclang: string;
+  /** Shown in the captions menu. Non-empty, at most 60 characters. */
+  label: string;
+  /** Selected when the learner has chosen no language yet. At most one track may be the default. */
+  default?: boolean;
+}
+/**
+ * Optional media (image/audio/video) shown above a question or passage.
+ * URL-only: hosting/delivery is the consuming application's responsibility.
+ */
+interface ActivityMedia {
+  /** The kind of media; selects the rendered element. `embed` → sandboxed iframe. */
+  type: 'image' | 'audio' | 'video' | 'embed';
+  /**
+   * Source URL. For `embed` this MUST be the provider's embeddable URL
+   * (e.g. `https://www.youtube.com/embed/<id>`), not the watch page.
+   */
+  url: string;
+  /** Alternative text. Required for `image` and `embed`; optional label for audio/video. */
+  alt?: string;
+  /** Optional WebVTT captions track URL for `audio`/`video`. */
+  captionsUrl?: string;
+  /**
+   * Text tracks for `audio`/`video`, one per language: what `captionsUrl`
+   * cannot say — a language, a label, more than one. When present, a player
+   * that reads it ignores `captionsUrl`. At most 12, one `default`, and no two
+   * sharing a `kind` and a `srclang`.
+   */
+  tracks?: MediaTrack[];
+  /** An image shown before the first play. `video` only. */
+  poster?: string;
+  /**
+   * How the recording may be played. `audio` only — see
+   * {@link MediaPlaybackPolicy}. Absent means today's behaviour exactly: the
+   * browser's own control bar, unlimited plays, free seeking and free speed.
+   */
+  playback?: MediaPlaybackPolicy;
+}
+/**
+ * A hint to the browser's own control bar, emitted as a `controlsList` token.
+ *
+ * Advisory, and engine-dependent. `hide-download` removes a menu item where
+ * `controlsList` is implemented; it never prevents a download, because the URL
+ * is in the page and the bytes are in the network panel. The real control is a
+ * short-lived signed URL, which belongs to the consuming application.
+ */
+type NativeControlHint = 'hide-download' | 'hide-rate';
+/**
+ * How an audio recording may be played.
+ *
+ * Every field is optional and every default reproduces the SDK's pre-0.8.0
+ * behaviour, so adding this key is the only thing that changes anything.
+ *
+ * Setting any *enforcement* field (`maxPlays`, `seek: 'none'`, `rate: 'fixed'`)
+ * resolves `controls` to `'minimal'`: the browser's bar cannot express a spent
+ * budget — its play button stays enabled — so the SDK renders its own
+ * transport rather than leave a control that looks operable and does nothing.
+ */
+interface MediaPlaybackPolicy {
+  /**
+   * `native` renders the browser's control bar. `minimal` renders the SDK
+   * transport. Resolved automatically; set it explicitly only to keep the
+   * native bar on a recording that has nothing to enforce.
+   */
+  controls?: 'native' | 'minimal';
+  /**
+   * How many times the recording may be STARTED (1–20). A play is consumed
+   * when playback begins from anywhere other than where it last stopped, so
+   * pausing, resuming, and paging between the questions of one listening group
+   * are free.
+   *
+   * The SDK refuses the play; it does not remember it. The count is durable
+   * only if the consuming application persists it — see `mediaBudget` on
+   * `<ActivitySequence>` in `@intellectif/lk-react`.
+   */
+  maxPlays?: number;
+  /** `none` renders no scrubber and reverts an out-of-band seek. Resolves to `none` under a budget. */
+  seek?: 'allow' | 'none';
+  /** `fixed` renders no speed control and snaps `playbackRate` back to 1. */
+  rate?: 'allow' | 'fixed';
+  /** Advisory hints to the native bar. See {@link NativeControlHint}. */
+  nativeControlHints?: NativeControlHint[];
+}
+/**
+ * Optional authored "overall feedback" shown after submission, chosen by
+ * whether the learner passed (h5p-style overall feedback). Distinct from
+ * per-option feedback; either field may be omitted.
+ */
+interface ActivityFeedback {
+  /** Shown when the learner passes (score ≥ pass threshold). */
+  correct?: string;
+  /** Shown when the learner does not pass. */
+  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.
+   *
+   * 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 {
+  schemaVersion: '1.0';
+  type: 'multiple-choice';
+  /** Unique identifier for this activity. */
+  id: string;
+  /** Human-readable title used in xAPI statements and error boundaries. */
+  title: string;
+  /** The question stem presented to the learner, as plain text. */
+  question: string;
+  /**
+   * Optional sanitised rich-HTML rendering of the question, parallel to
+   * `WrittenResponseData.promptHtml`. `<MultipleChoice>` renders it in place
+   * of `question` when — and only when — a `sanitizeHtml` function is
+   * supplied; without one the plain `question` is rendered and escaped.
+   * Sanitisation is the application's responsibility: the SDK ships none.
+   */
+  questionHtml?: string;
+  /** `single` allows one selection; `multi` allows multiple. */
+  mode: 'single' | 'multi';
+  /** Ordered list of answer options. */
+  options: MultipleChoiceOption[];
+  /** Scoring algorithm applied when the learner submits. */
+  scoringStrategy: 'all-or-nothing' | 'partial';
+  /** Optional media shown above the question. */
+  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;
+  /**
+   * When true, option order is shuffled deterministically.
+   *
+   * The order is derived from the renderer's `shuffleSeed` when one is given —
+   * pass the attempt id, and a review render reproduces exactly the order the
+   * learner sat. Without a seed the order is stable for the life of the mount
+   * only, and is NOT reproducible afterwards, so never grade or appeal against
+   * a remembered position.
+   */
+  shuffle?: boolean;
+  /** 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;
+  /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+  ai?: ActivityAiPermissions;
+}
+/** Configuration for a single fill-in-the-blank slot. */
+interface BlankConfig {
+  /** Unique identifier matching the `{{blank_id}}` placeholder in the passage. */
+  id: string;
+  /** List of strings accepted as correct answers for this blank. */
+  acceptedAnswers: string[];
+  /**
+   * Whether answer matching is case-sensitive. Defaults to false.
+   *
+   * @deprecated Since lk-core 1.3: write `match: { caseSensitive }`, which
+   * means the same. Still read throughout 1.x; a 2.0 may remove it.
+   */
+  caseSensitive?: boolean;
+  /**
+   * Whether leading/trailing whitespace is stripped before matching. Defaults to true.
+   *
+   * @deprecated Since lk-core 1.3: write `match: { trim }`, which means the
+   * same. Still read throughout 1.x; a 2.0 may remove it.
+   */
+  trimWhitespace?: boolean;
+  /**
+   * Optional matching-tolerance policy for this blank (Unicode normalization,
+   * diacritic folding, whitespace collapse, punctuation tolerance, typo
+   * tolerance). Every tolerance is opt-in; when absent, matching reproduces
+   * the v1 trim + case-fold semantics exactly. Fields set here take
+   * precedence over the legacy `caseSensitive` / `trimWhitespace` flags.
+   */
+  match?: TextMatchPolicy;
+  /** Optional hint text revealed on learner request. */
+  hint?: string;
+  /** Optional feedback shown inline next to this blank after submission. */
+  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;
+  /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+  ai?: ActivityAiPermissions;
+}
+interface FillInTheBlanksData {
+  schemaVersion: '1.0';
+  type: 'fill-in-the-blanks';
+  /** Unique identifier for this activity. */
+  id: string;
+  /** Human-readable title used in xAPI statements and error boundaries. */
+  title: string;
+  /** Passage text containing `{{blank_id}}` placeholders. */
+  passage: string;
+  /**
+   * Optional sanitised rich-HTML rendering of the passage, parallel to
+   * `WrittenResponseData.promptHtml`. Carried and redacted as learner-visible
+   * content; not rendered by the SDK yet. Sanitisation is the application's.
+   */
+  passageHtml?: string;
+  /** Configuration for each blank in the passage. */
+  blanks: BlankConfig[];
+  /** Scoring algorithm applied when the learner submits. */
+  scoringStrategy: 'all-or-nothing' | 'partial';
+  /** 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;
+  /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+  ai?: ActivityAiPermissions;
+}
+/** A single criterion within a written-response grading rubric. */
+interface WrittenResponseRubricCriterion {
+  /** Criterion name (e.g. "Task achievement", "Grammar range"). */
+  name: string;
+  /** Optional longer description of what the criterion assesses. */
+  description?: string;
+  /** Non-negative weight of this criterion in the overall grade. */
+  weight: number;
+}
+/** Grading rubric attached to a written-response activity. */
+interface WrittenResponseRubric {
+  /** Optional display label for the rubric as a whole. */
+  label?: string;
+  /** The criteria the response is graded against. Non-empty when present. */
+  criteria: WrittenResponseRubricCriterion[];
+}
+/**
+ * Data contract for a Written Response activity (free-text writing graded
+ * asynchronously — by an AI or human grader — after submission).
+ *
+ * Wire-format note: field names and casing are locked for
+ * byte-compatibility with consumer-stored JSONB rows. `feedback` and
+ * `passThreshold` are SDK-side optional additions for component parity —
+ * being optional, their absence keeps stored payloads
+ * byte-identical.
+ */
+interface WrittenResponseData {
+  schemaVersion: '1.0';
+  type: 'written-response';
+  /** Unique identifier for this activity. */
+  id: string;
+  /** Human-readable title used in xAPI statements and error boundaries. */
+  title: string;
+  /** The writing prompt, as plain text. */
+  prompt: string;
+  /**
+   * Optional sanitised rich-HTML sidecar of the prompt. `<WrittenResponse>`
+   * renders it in place of `prompt` when a `sanitizeHtml` function is
+   * supplied; without one the plain `prompt` is rendered and escaped.
+   */
+  promptHtml?: string;
+  /** Minimum acceptable word count (≥ 0). */
+  minWords: number;
+  /** Maximum acceptable word count (≥ 1, and ≥ `minWords`). */
+  maxWords: number;
+  /** Optional grading rubric consumed by the asynchronous grader. */
+  rubric?: WrittenResponseRubric;
+  /** Optional target language/level for the response (e.g. `"en-A2"`, `"es-B1"`). */
+  languageTarget?: string;
+  /** Optional media shown above the prompt. */
+  media?: ActivityMedia;
+  /** Optional authored overall feedback (surfaced once the deferred grade exists). */
+  feedback?: ActivityFeedback;
+  /** Minimum scaled score [0–1] required to pass once graded. 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;
+  /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+  ai?: ActivityAiPermissions;
+}
+/**
+ * A second, slower recording of a dictation — a separate file (a text-to-speech
+ * render at reduced speed, or a slower human reading), not a `playbackRate`
+ * change. It carries no `captionsUrl` (a caption track of a dictation is the
+ * transcript on screen) and no `playback` policy of its own: it follows the
+ * policy on `media`, except the play budget, which it never has.
+ */
+interface DictationSlowMedia {
+  type: 'audio';
+  /** Source URL, under the same policy as {@link ActivityMedia.url}. */
+  url: string;
+  /** Accessible label — a description ("Recording, slow"), never a transcription. */
+  alt?: string;
+}
+/**
+ * A whole-word rewrite applied to BOTH the transcript and the attempt before
+ * they are compared. `from` and `to` are literal text: a rule is applied to
+ * every whole-word occurrence, exactly once, in the order the rules are listed,
+ * after spacing is collapsed and before punctuation is ignored — so a rule may
+ * name a symbol (`{ from: '&', to: 'and' }`) and a multi-word `from` matches
+ * across any whitespace.
+ */
+interface DictationEquivalence {
+  /** What to rewrite: at least one code point that survives case, quote and whitespace folding. */
+  from: string;
+  /** What it becomes: 1..200 code points, something of which survives normalisation. A rule cannot delete a word. */
+  to: string;
+}
+/** Grading tolerances for a dictation. Part of the answer key. */
+interface DictationTolerance {
+  /** Whole-word rewrites, applied in listed order, each exactly once. */
+  equivalences?: DictationEquivalence[];
+}
+/**
+ * Data contract for a Dictation activity: the learner listens to a recording
+ * and types what they hear; the grade is how close their text is to the
+ * transcript.
+ *
+ * Scoring is character-level similarity over the whole sentence —
+ * `(length − edit distance) / length` over NFC code points after case,
+ * punctuation and spacing are ignored — with one {@link ScoringDetail} per
+ * transcript word carrying that word's own {@link ScoringDetail.score}. It is
+ * deliberately not a mode of {@link FillInTheBlanksData}: a blank is right or
+ * wrong, a dictation is graded on a continuum, and the whole `TextMatchPolicy`
+ * surface (typo tolerance, diacritic folding) would be a second, competing
+ * notion of "close enough".
+ */
+interface DictationData {
+  schemaVersion: '1.0';
+  type: 'dictation';
+  /** Unique identifier for this activity. */
+  id: string;
+  /**
+   * Human-readable title used in xAPI statements and error boundaries. It is
+   * the stem the learner sees, so it must not contain the transcript.
+   */
+  title: string;
+  /**
+   * What the learner is expected to type. ANSWER KEY. 1..2000 code points,
+   * before and after its equivalences are applied, and something must survive
+   * normalisation.
+   */
+  transcript: string;
+  /**
+   * Alternative transcriptions accepted at full credit — a regional spelling, a
+   * numeral, a whole-sentence contraction variant. ANSWER KEY. At most 10, each
+   * 1..2000 code points, none normalising equal to the transcript or to each
+   * other. The attempt is scored against every candidate and the best
+   * similarity wins; a tie goes to `transcript`.
+   */
+  acceptedTranscripts?: string[];
+  /**
+   * The recording. Audio only, never with captions. Optional in the schema — a
+   * dictation inside an item group may draw on the group's stimulus recording —
+   * but required whenever `slowMedia` is present. Budgeted per slot like any
+   * other activity media, with the usual playback policy.
+   */
+  media?: ActivityMedia;
+  /** A second, slower recording. See {@link DictationSlowMedia}. */
+  slowMedia?: DictationSlowMedia;
+  /**
+   * Progressive word hints, in `practice` only (the transcript is absent in
+   * `exam` mode, so there is nothing to reveal). Public: it reveals nothing by
+   * itself. `progressive-words` reveals the transcript's words left to right,
+   * one per request; a revealed hint never changes the score.
+   */
+  hints?: {
+    mode: 'progressive-words';
+  };
+  /** Grading tolerances. ANSWER KEY. */
+  tolerance?: DictationTolerance;
+  /** 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. Presentation only: scoring never reads it. */
+  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;
+  /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+  ai?: ActivityAiPermissions;
+}
+/** A dimension of speech a pronunciation assessor scores, on a 0–100 scale. */
+type ReadAloudDimension = 'accuracy' | 'fluency' | 'completeness' | 'prosody';
+/** One assessor dimension counted towards a read-aloud grade, and its weight. */
+interface ReadAloudDimensionWeight {
+  name: ReadAloudDimension;
+  /**
+   * Relative weight, 0..1000 (`READ_ALOUD_MAX_DIMENSION_WEIGHT`). Weights need
+   * not add up to anything; a weight of 0 leaves the dimension out of the grade.
+   */
+  weight: number;
+}
+/**
+ * The limits on a read-aloud take, applied where the learner records. No grade
+ * reads them: whether a take is plausible speech is decided from the server's
+ * own measurement of the recording, never from a bound the client enforced.
+ */
+interface RecordingBounds {
+  /** The longest take, in seconds: above 0, and at most `READ_ALOUD_MAX_SECONDS` (300). */
+  maxSeconds: number;
+  /** The shortest take, in seconds: at least 0, and below `maxSeconds`. */
+  minSeconds?: number;
+  /** How many takes the learner may record: a whole number from 1 to `READ_ALOUD_MAX_TAKES` (20). */
+  maxTakes?: number;
+}
+/**
+ * A second, slower model recording of the reference text — a separate file,
+ * not a `playbackRate` change. It carries no `captionsUrl` and no `playback`
+ * policy of its own, requires `media`, must be a different file from it, and
+ * cannot accompany a play limit on `media`.
+ */
+interface ReadAloudSlowMedia {
+  type: 'audio';
+  /** Source URL, under the same policy as {@link ActivityMedia.url}. */
+  url: string;
+  /** Accessible label — a description ("Model recording, slow"). */
+  alt?: string;
+}
+/**
+ * Data contract for a Read Aloud activity: the learner reads a text aloud, an
+ * assessor measures the recording, and the grade is the weighted total of the
+ * assessor's dimension scores.
+ *
+ * Grading is deferred — `evaluate()` returns `deferred` until the application
+ * holds an assessment — and nothing here is an answer key: the learner is shown
+ * the text they are asked to read.
+ */
+interface ReadAloudData {
+  schemaVersion: '1.0';
+  type: 'read-aloud';
+  /** Unique identifier for this activity. */
+  id: string;
+  /** Human-readable title used in xAPI statements and error boundaries. */
+  title: string;
+  /** Optional instructions shown to the learner, as plain text. */
+  instructions?: string;
+  /**
+   * The text the learner reads aloud. Shown to the learner (public). At most
+   * `READ_ALOUD_MAX_REFERENCE_LENGTH` code points before and after
+   * normalisation, in a script written with spaces between words.
+   */
+  referenceText: string;
+  /**
+   * BCP 47 tag in canonical form with a region (e.g. `en-US`). GRADE-DECIDING:
+   * an assessment made for another locale is unscorable.
+   */
+  locale: string;
+  /** A model recording of the text. Audio only; a playback policy is allowed. */
+  media?: ActivityMedia;
+  /** A second, slower model recording. See {@link ReadAloudSlowMedia}. */
+  slowMedia?: ReadAloudSlowMedia;
+  /** The limits on a take. See {@link RecordingBounds}. */
+  recording: RecordingBounds;
+  /**
+   * The assessor dimensions the grade is made of, with their weights: 1 to 4
+   * entries, each name at most once, at least one weight above 0. A weighted
+   * dimension the assessment has no score for makes the take unscorable, never
+   * a zero. Public.
+   */
+  scoring: {
+    dimensions: ReadAloudDimensionWeight[];
+  };
+  /** Minimum scaled score [0–1] required to pass once graded. Defaults to {@link DEFAULT_PASS_THRESHOLD} (0.7) when absent. */
+  passThreshold?: number;
+  /** Optional authored overall feedback, selected once the grade exists. */
+  feedback?: ActivityFeedback;
+  /** IRI references to learning objectives addressed by this activity. */
+  learningObjectives?: string[];
+  /** Subjective difficulty on a 1–5 scale. */
+  difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+  /** What an author allows AI to do for this item: see {@link ActivityAiPermissions}. */
+  ai?: ActivityAiPermissions;
+}
+/**
+ * Maps each ActivityType string to its learner-response shape. Open for
+ * extension via module augmentation, mirroring {@link ActivityDataMap}.
+ */
+interface LearnerResponseMap {
+  'multiple-choice': MultipleChoiceLearnerResponse;
+  'fill-in-the-blanks': FillInTheBlanksLearnerResponse;
+  'written-response': WrittenResponseLearnerResponse;
+  'gap-select': GapSelectLearnerResponse;
+  dictation: DictationLearnerResponse;
+  'read-aloud': ReadAloudLearnerResponse;
+}
+/** Union of all learner response shapes. */
+type LearnerResponse = LearnerResponseMap[keyof LearnerResponseMap];
+/** Learner response for a Multiple Choice activity. */
+interface MultipleChoiceLearnerResponse {
+  type: 'multiple-choice';
+  /** IDs of the options the learner selected. */
+  selectedOptionIds: string[];
+  /**
+   * Hints the learner was shown before submitting this answer, counted from
+   * the start of the question — the author's and AI hints alike. Written by
+   * the SDK's components in `practice`; absent or 0 means none. A scoring
+   * policy's `hintPenalty` charges for them. Client-reported, like any count
+   * a browser makes.
+   */
+  hintsRevealed?: number;
+}
+/** Learner response for a Fill-in-the-Blanks activity. */
+interface FillInTheBlanksLearnerResponse {
+  type: 'fill-in-the-blanks';
+  /** Map of blank ID to the learner's typed answer. */
+  answers: Record<string, string>;
+  /**
+   * Hints the learner was shown before submitting this answer, counted from
+   * the start of the question — the author's and AI hints alike. Written by
+   * the SDK's components in `practice`; absent or 0 means none. A scoring
+   * policy's `hintPenalty` charges for them. Client-reported, like any count
+   * a browser makes.
+   */
+  hintsRevealed?: number;
+}
+/**
+ * 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>;
+  /**
+   * Hints the learner was shown before submitting this answer, counted from
+   * the start of the question — the author's and AI hints alike. Written by
+   * the SDK's components in `practice`; absent or 0 means none. A scoring
+   * policy's `hintPenalty` charges for them. Client-reported, like any count
+   * a browser makes.
+   */
+  hintsRevealed?: number;
+}
+/** Learner response for a Written Response activity. */
+interface WrittenResponseLearnerResponse {
+  type: 'written-response';
+  /** The learner's free-text response. */
+  text: string;
+  /** Word count of `text`, computed with the canonical `countWords()` helper. */
+  wordCount: number;
+}
+/**
+ * Learner response for a Dictation activity.
+ *
+ * `text` is exactly what the learner typed; every normalisation happens in the
+ * scorer. `hintsRevealed` is client-reported — how many hint words were shown
+ * before submitting. The scorer ignores it; a scoring policy's `hintPenalty`
+ * charges for it, knowing it cannot be verified.
+ */
+interface DictationLearnerResponse {
+  type: 'dictation';
+  /** The learner's text, as typed. */
+  text: string;
+  /**
+   * Hint words shown before submitting (practice only), counted from the start
+   * of the question. Absent or 0 means none.
+   */
+  hintsRevealed?: number;
+}
+/**
+ * A learner recording held by the application. `key` is opaque,
+ * application-issued storage identity: never a URL or bytes. `durationMs` is a
+ * client claim no grade reads.
+ */
+interface RecordingRef {
+  key: string;
+  /** The media type the recording was stored as, e.g. `audio/wav`. */
+  mimeType: string;
+  durationMs?: number;
+}
+/**
+ * Learner response for a Read Aloud activity: a reference to the recording the
+ * application stored, never the audio itself.
+ */
+interface ReadAloudLearnerResponse {
+  type: 'read-aloud';
+  /** `null`: the learner submitted without recording (a blank). A take that failed to upload is never `null`. */
+  recording: RecordingRef | null;
+  /** Telemetry: takes used. No grade reads it. */
+  takes?: number;
+}
+/**
+ * Fine-grained outcome of the learner's action on a single item:
+ * - `correct` — the learner selected/entered the right answer.
+ * - `incorrect` — the learner selected/entered a wrong answer.
+ * - `correct-omission` — the learner correctly left a non-answer unselected (multiple-choice only).
+ * - `incorrect-omission` — a correct answer the learner did not give: an unselected
+ *   correct option, an unanswered gap, a missing dictation word.
+ */
+type ScoringOutcome = 'correct' | 'incorrect' | 'correct-omission' | 'incorrect-omission';
+/** Per-item scoring breakdown returned by the scoring engine. */
+interface ScoringDetail {
+  /** ID of the option, blank, gap or dictation word (`w1`…`wN`) this detail refers to. */
+  itemId: string;
+  /**
+   * The outcome of the learner's action on this item. On a multiple-choice
+   * option it says both whether the option was chosen and whether it is part
+   * of the answer.
+   *
+   * Until 1.0 a detail also carried `correct`, which on a multiple-choice
+   * option meant "the learner acted correctly on it" — an unselected wrong
+   * option read `correct: true` — and a detail stored before 0.3 carries only
+   * that. The SDK's components still read such a stored detail; a type written
+   * against 1.0 does not describe it.
+   */
+  outcome: ScoringOutcome;
+  /** The learner's actual response for this item. */
+  learnerResponse: string | string[];
+  /** The expected correct response(s) for this item. */
+  correctResponse: string | string[];
+  /**
+   * Weight applied to this item's contribution to the overall score. Every
+   * built-in scorer currently weights every item equally and writes `1`.
+   */
+  weight?: number;
+  /**
+   * The item's own scaled score in [0, 1], for a type that grades its items on
+   * a continuum rather than right or wrong. Written by the dictation scorer
+   * (the similarity of each transcript word to what was typed for it) and by
+   * `gradeReadAloud` (the assessor's accuracy for each reference word as a
+   * fraction, 0 for an omitted word, and absent where the assessor gave none).
+   * Absent, an item is right or wrong: read `outcome`.
+   */
+  score?: number;
+}
+/** Full scoring result returned by the scoring engine. */
+interface ScoringResult {
+  /** Scaled score in the range [0, 1]. */
+  score: number;
+  /** Maximum possible scaled score (always 1). */
+  maxScore: number;
+  /** Whether the score meets or exceeds the activity's pass threshold. */
+  passed: boolean;
+  /**
+   * The authored overall feedback selected for this result: `feedback.correct`
+   * when the learner passed, `feedback.incorrect` otherwise; `null` when the
+   * activity authored no matching feedback.
+   */
+  feedback: string | null;
+  /** Per-item scoring breakdown. */
+  details: ScoringDetail[];
+}
+/**
+ * Progress facts about a deferred (asynchronously graded) submission that are
+ * computable synchronously at submit time. For written-response, both fields
+ * are always present and `wordCount` is recomputed from the submitted text
+ * with the canonical `countWords()` (the client-supplied count is not trusted).
+ */
+interface DeferredScoringPartial {
+  /** Whether the recomputed word count falls within `[minWords, maxWords]`. */
+  withinWordBounds?: boolean;
+  /** Recomputed word count of the submitted text. */
+  wordCount?: number;
+  [key: string]: unknown;
+}
+/**
+ * Why an item has no grade *yet* — a state that is explicitly not final, and
+ * so keeps a composed assessment `provisional`.
+ *
+ * - `requires_async_grading` — the type is graded later by an AI or a human.
+ * - `no_response_recorded` — nothing was stored against this slot at all. It
+ *   is NOT the same as a zero: a learner who left a question blank on a
+ *   submitted paper has earned zero, but a slot missing because a save failed,
+ *   a grade has not landed, or the attempt is still open has earned nothing
+ *   yet, and recording it as zero is how an incomplete attempt becomes a
+ *   plausible-looking fail.
+ * - `grade_rejected` — a grade came back, and `outcomeFromGrade` refused it
+ *   because its numbers cannot be a grade (a `score` or `maxScore` that is not
+ *   a finite number, a `maxScore` of 0 or less, or a score outside 0 to
+ *   `maxScore`). The record is kept on `rejectedGrade`. A real grade is still
+ *   owed, so re-grade the slot: waiting will not bring one.
+ */
+type DeferredReason = 'requires_async_grading' | 'no_response_recorded' | 'grade_rejected';
+/**
+ * The outcome of evaluating a learner response against an activity — the
+ * union `evaluate()` returns. Unlike {@link ScoringResult}, it can express
+ * "not gradable yet" (`deferred`) and "not gradable at all" (`unscorable`),
+ * so an ungraded written response is never conflated with a score of 0.
+ */
+type ItemOutcome = {
+  status: 'scored';
+  /** Scaled score in the range [0, 1]. */
+  score: number;
+  /** Maximum possible scaled score. */
+  maxScore: number;
+  /** Whether the score meets or exceeds the activity's pass threshold. */
+  passed: boolean;
+  /** Authored overall feedback selected by pass state, or null. */
+  feedback: string | null;
+  /** Per-item scoring breakdown. */
+  details: ScoringDetail[];
+} | {
+  status: 'deferred';
+  /** Why no grade exists yet. See {@link DeferredReason}. */
+  reason: DeferredReason;
+  /** Maximum possible scaled score once graded. */
+  maxScore: number;
+  /** Synchronously computable progress facts (word bounds, counts). */
+  partial?: DeferredScoringPartial;
+  /**
+   * The record `outcomeFromGrade` refused, verbatim, when `reason` is
+   * `grade_rejected` — kept for audit and for the re-grade. Nothing on it
+   * is mirrored onto the outcome, and nothing reads it as a grade.
+   */
+  rejectedGrade?: GradeRecord;
+} | {
+  status: 'graded';
+  /**
+   * A grade produced by an asynchronous grader (AI or human) and handed
+   * back to the SDK. This is the state a `deferred` outcome transitions
+   * to once grading completes; nothing in the SDK ever manufactures it.
+   */
+  grade: GradeRecord;
+  /** Scaled score in the range [0, 1], mirrored from `grade` for uniform reads. */
+  score: number;
+  maxScore: number;
+  passed: boolean;
+  /** Narrative feedback from the grader, mirrored from `grade`. */
+  feedback: string | null;
+} | {
+  status: 'unscorable';
+  /** Why no grade can be produced (e.g. unregistered activity type). */
+  reason: string;
+  /** Maximum possible scaled score, when known. */
+  maxScore: number;
+  /**
+   * A machine-readable reason, written by `outcomeFromUnscorable` — for
+   * example a read-aloud `SpeechUnscorableCode`. `evaluate` never writes it.
+   */
+  code?: string;
+};
+/** A single validation error produced by `validateActivity`. */
+interface ValidationError {
+  /** JSON-path-style location of the invalid field. */
+  path: string[];
+  /** Human-readable description of the validation failure. */
+  message: string;
+  /** Machine-readable error code. */
+  code: string;
+}
+/**
+ * Result of a `validateActivity` call.
+ * On success, `data` is the validated and typed activity data.
+ * On failure, `errors` contains one entry per violated constraint.
+ */
+type ValidationResult<T> = {
+  success: true;
+  data: T;
+} | {
+  success: false;
+  errors: ValidationError[];
+};
+/** The payload delivered to an activity's `onComplete` callback. */
+interface ActivityResult {
+  /** Scaled score in the range [0, 1]. */
+  score: number;
+  /** Maximum possible scaled score (always 1). */
+  maxScore: number;
+  /** Whether the learner passed based on the activity's pass threshold. */
+  passed: boolean;
+  /** Time in milliseconds from first interaction to submission. */
+  timeSpent: number;
+  /** The xAPI statement built and (optionally) sent for this attempt. */
+  xapiStatement: XAPIStatement;
+}
+/**
+ * The kinds of interaction the built-in components emit. Custom activity types
+ * registered by consumers may emit their own kinds, so any string is accepted;
+ * the named literals are kept for autocompletion.
+ */
+type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled' | 'hint-requested' | 'text-changed' | 'submitted' |
+/**
+ * A play was charged against a recording's budget, before any audio was
+ * audible. Emitted only when a budget is in force, so a `review`-mode replay
+ * never pollutes the record an appeal reads.
+ */
+'media-play-consumed' |
+/** An exhausted budget refused a play. The artifact an appeal asks for. */
+'media-play-refused' |
+/** A charged play produced no audio — a failed or expired media URL. */
+'media-play-errored' |
+/** A charged play was returned, because the consumer accepted the refund. */
+'media-play-refunded' |
+/** The microphone began capturing a take. */
+'recording-started' |
+/** A take ended, by the learner or at its time limit. */
+'recording-stopped' |
+/** A take was thrown away, to record another. */
+'recording-discarded' |
+/** The application stored a take and returned its reference. */
+'recording-uploaded' |
+/** Storing a take failed. A take that failed to upload is never a blank answer. */
+'recording-upload-failed' |
+/** A stored take was sent for assessment. */
+'assessment-requested' |
+/** An assessment request failed: the take has no grade. */
+'assessment-failed' |
+/** Interactive video: the learner started playback. */
+'video-played' |
+/** Interactive video: playback paused, by the learner or by a quiz. */
+'video-paused' |
+/** Interactive video: the playhead moved (`from`, `to`, and whether navigation `clamped` it). */
+'video-seeked' | 'video-rate-changed' | 'video-ended' |
+/** Interactive video: a quiz opened (`cueId`, `at`). */
+'video-quiz-opened' |
+/** Interactive video: one question of an open quiz was shown (`cueId`, `slotId`). */
+'video-quiz-question-shown' | 'video-quiz-skipped' | 'video-quiz-closed' |
+/**
+ * Interactive video: the captions a learner chose. `payload.srclang` is the
+ * primary line's language, or `null` with captions off; `payload.secondary` is
+ * the second line's, or `null` with none showing. Fires when either changes.
+ */
+'video-captions-changed' | 'video-fullscreen-changed' | 'video-pip-changed' |
+/**
+ * An AI hint was shown to the learner (`hintNumber`, and the port's
+ * `provenance` when it sent one). Only a hint the SDK accepted: a refused one
+ * is never shown and never reported here.
+ */
+'ai-hint-shown' |
+/** An AI explanation of the graded answer was shown (`provenance`, `usage` when sent). */
+'ai-explanation-shown' |
+/**
+ * An AI answer was refused, and the learner was told help was not available
+ * (`feature`, `reason` — an {@link AiRefusal} — and `hintNumber` for a hint).
+ *
+ * **The text itself is never carried**: a hint refused for revealing the
+ * answer contains the answer, and this event is logged. It is how a host
+ * watches its own model in production, where the development console warning
+ * it accompanies is silent.
+ */
+'ai-help-refused' |
+/**
+ * Feedback on a draft of a written response was shown (`draftNumber`, the
+ * number of `corrections`, the `indicativeScore` when there was one, and the
+ * port's `provenance` and `usage` when it sent them). Never the text.
+ */
+'ai-writing-feedback-shown' |
+/**
+ * Coaching on a read-aloud was shown (the number of `words` it coached, and
+ * the port's `provenance` and `usage` when it sent them). Never the text.
+ */
+'ai-coaching-shown' | (string & {});
+/** Fired by activity components on every discrete learner interaction. */
+interface InteractionEvent {
+  /** The kind of interaction that occurred. */
+  type: InteractionKind;
+  /** ID of the activity that produced the event. */
+  activityId: string;
+  /** Unix timestamp (ms) of when the interaction occurred. */
+  timestamp: number;
+  /** Additional event-specific data. */
+  payload: Record<string, unknown>;
+}
+//#endregion
+//#region src/types/authoring.d.ts
+/**
+ * Why a draft is not an activity yet.
+ *
+ * - `incomplete` — something the author has not written yet: an empty title, an
+ *   option with no text, no option marked correct. The fix is to add it.
+ * - `invalid` — something is wrong in a way that writing more cannot fix: two
+ *   correct options on a single-selection question, a maximum word count below
+ *   the minimum, a media address with a scheme the SDK refuses, a `null` in an
+ *   optional field that accepts none. The fix is to change it.
+ */
+type DraftSeverity = 'incomplete' | 'invalid';
+/**
+ * One problem with a draft. A {@link ValidationError} with a severity, so code
+ * that already lists `validateActivity` errors can list these unchanged.
+ */
+interface DraftIssue extends ValidationError {
+  severity: DraftSeverity;
+}
+/** A draft that is a valid activity and has nothing left to write. */
+interface DraftComplete<T> {
+  status: 'complete';
+  /** The validated activity, exactly as `validateActivity` returns it. */
+  data: T;
+  /** Always empty. Present so that every result can be read the same way. */
+  issues: DraftIssue[];
+}
+/**
+ * A draft that is not an activity yet: `invalid` when any issue is invalid,
+ * otherwise `incomplete`. It carries no `data`, because nothing here may be
+ * stored or rendered as an activity.
+ */
+interface DraftNotComplete {
+  status: 'incomplete' | 'invalid';
+  issues: DraftIssue[];
+}
+/**
+ * The result of `validateDraft`.
+ *
+ * There is deliberately no `success` boolean. A boolean has to call an
+ * incomplete draft either a success, which lets a half-written answer key
+ * through anything that checks it, or a failure, which is the conflation this
+ * result exists to remove. Branch on `status`.
+ */
+type DraftValidationResult<T> = DraftComplete<T> | DraftNotComplete;
+/**
+ * How much a finding of the item critic matters. Neither makes a draft
+ * incomplete or invalid: an item with findings is a valid item, stored and
+ * served like any other, and whether to change it is the author's call.
+ *
+ * - `warning` — a known flaw a learner can exploit or trip over: the right
+ *   option is the longest, an answer printed in the passage, a hint that gives
+ *   the answer away, two options that read the same.
+ * - `advice` — an item-writing guideline the item departs from: "all of the
+ *   above", two accepted answers the matcher already treats as one.
+ */
+type ItemFindingSeverity = 'warning' | 'advice';
+/**
+ * One thing the item critic found. A {@link ValidationError} with a severity,
+ * as a {@link DraftIssue} is, so an editor lists both in one list — sorted by
+ * severity: `invalid`, `incomplete`, `warning`, `advice`.
+ */
+interface ItemFinding extends ValidationError {
+  severity: ItemFindingSeverity;
+}
+/** What `createDraft` hands an activity type's `authoring.createDraft`. */
+interface DraftContext {
+  /**
+   * Returns a new id on every call. The SDK invents none: an id made here would
+   * need `crypto`, which plain-http origins do not have, or would be positional —
+   * and option ids reach the learner, so ids like `"a"` and `"b"` would tell them
+   * which option was written first.
+   */
+  newId: () => string;
+}
+//#endregion
+//#region src/types/ai.d.ts
+/**
+ * What an author allows AI to do for one item. Absent, or a feature left out,
+ * leaves the choice to the deployment. `false` switches a feature off for this
+ * item wherever it is delivered; an author can only switch a feature off,
+ * never force one on.
+ *
+ * Switch hints off where any hint would give the answer away — a
+ * one-word vocabulary item, say.
+ */
+interface ActivityAiPermissions {
+  /**
+   * An explanation of the learner's graded answer — and, on a written
+   * response, feedback on a draft, and on a read-aloud, coaching on the
+   * marks: each is a model's words about the learner's own answer.
+   */
+  explanations?: boolean;
+  /** Hints before the learner submits. */
+  hints?: boolean;
+}
+/**
+ * An activity as a renderer holds it: full data or a `redact()` projection.
+ * Structural rather than the data union, so a renderer's own view of an item —
+ * whose answer-key fields may be absent — is accepted as it is. The AI
+ * functions read every field defensively.
+ */
+interface AiActivityInput {
+  readonly type: string;
+  readonly id: string;
+  readonly title: string;
+  readonly locale?: unknown;
+  readonly redacted?: unknown;
+  readonly ai?: unknown;
+}
+/** The kinds of help a learner can be given. */
+type AiFeature = 'explanation' | 'hint' | 'writing-feedback' | 'pronunciation-coaching';
+/** The activity types the SDK builds facts for. */
+type AiSupportedActivityType = 'multiple-choice' | 'fill-in-the-blanks' | 'gap-select' | 'dictation';
+/**
+ * A whole answer's grade, from the SDK's scorer. `category` is the verdict an
+ * explanation must agree with: all marks, some, or none.
+ */
+interface AiGrade {
+  score: number;
+  maxScore: number;
+  passed: boolean;
+  category: AiVerdict;
+}
+/** The three verdicts an explanation can speak to. */
+type AiVerdict = 'correct' | 'partly-correct' | 'incorrect';
+interface AiFactsBase {
+  activityId: string;
+  title: string;
+  /** The language the item is written in, when the author gave one. */
+  locale?: string;
+}
+/** One option of a multiple-choice question, and what the learner did with it. */
+interface AiOptionFact {
+  id: string;
+  text: string;
+  chosen: boolean;
+  /** Whether this option is part of the answer; `null` when the key is not available. */
+  correct: boolean | null;
+  /** The author's feedback on this option. */
+  feedback?: string;
+}
+interface AiMultipleChoiceFacts extends AiFactsBase {
+  activityType: 'multiple-choice';
+  question: string;
+  mode: 'single' | 'multi';
+  options: AiOptionFact[];
+}
+/** One blank, in the order it appears in the passage. */
+interface AiBlankFact {
+  id: string;
+  /** 1-based, in passage order. */
+  position: number;
+  /** What the learner typed, or `''`. */
+  typed: string;
+  /** The answers that count; `null` when the key is not available. */
+  accepted: string[] | null;
+  /** The SDK's verdict on this blank; `null` before it is graded or without a key. */
+  correct: boolean | null;
+  /** The author's hint for this blank. */
+  hint?: string;
+  /** The author's feedback for this blank. */
+  feedback?: string;
+}
+interface AiFillInTheBlanksFacts extends AiFactsBase {
+  activityType: 'fill-in-the-blanks';
+  /** The passage, each blank written as `[1]`, `[2]`… in passage order. */
+  passage: string;
+  blanks: AiBlankFact[];
+}
+/** One gap, in the order it appears in the passage. */
+interface AiGapFact {
+  id: string;
+  /** 1-based, in passage order. */
+  position: number;
+  /** The words offered at this gap. */
+  choices: string[];
+  /** The word the learner chose, or `null`. */
+  chosen: string | null;
+  /** The right word; `null` when the key is not available. */
+  answer: string | null;
+  /** The SDK's verdict on this gap; `null` before it is graded or without a key. */
+  correct: boolean | null;
+  /** The author's feedback for this gap. */
+  feedback?: string;
+}
+interface AiGapSelectFacts extends AiFactsBase {
+  activityType: 'gap-select';
+  /** The passage, each gap written as `[1]`, `[2]`… in passage order. */
+  passage: string;
+  gaps: AiGapFact[];
+}
+/** One word of a dictation, as the SDK's alignment paired it. */
+interface AiWordFact {
+  /** The word the recording says; `''` for an extra word the learner added. */
+  expected: string;
+  /** The word the learner typed; `''` for a word they left out. */
+  typed: string;
+  status: 'correct' | 'incorrect' | 'missing' | 'extra';
+}
+interface AiDictationFacts extends AiFactsBase {
+  activityType: 'dictation';
+  /** What the recording says; `null` when the key is not available. */
+  transcript: string | null;
+  /** What the learner typed. */
+  typed: string;
+  /** The alignment word by word; `null` when the key is not available. */
+  words: AiWordFact[] | null;
+}
+/**
+ * What a model is told about one item and one answer: the question as the
+ * learner saw it, what they answered, and — part by part — the SDK's verdict.
+ */
+type AiItemFacts = AiMultipleChoiceFacts | AiFillInTheBlanksFacts | AiGapSelectFacts | AiDictationFacts;
+/**
+ * Asks for an explanation of a graded answer. Sent after the SDK has graded
+ * it, so `grade` is always present, and an explanation that contradicts
+ * `grade.category` is refused.
+ */
+interface AiExplanationRequest {
+  feature: 'explanation';
+  facts: AiItemFacts;
+  grade: AiGrade;
+  /** The language to answer in: the learner's interface language, when known. */
+  learnerLocale?: string;
+}
+/**
+ * Asks for the next hint before the learner submits. `facts` carries the key
+ * so a model can hint toward the answer; the SDK refuses any hint that
+ * contains it.
+ */
+interface AiHintRequest {
+  feature: 'hint';
+  facts: AiItemFacts;
+  /** 1-based: the hint being asked for. */
+  hintNumber: number;
+  /** The hints already shown for this item, oldest first. */
+  previousHints: string[];
+  learnerLocale?: string;
+}
+/** What produced an AI text, for the record a host keeps. */
+interface AiProvenance {
+  /** The model's identifier, e.g. a name and version. */
+  model?: string;
+  /** A hash or id of the prompt revision. */
+  promptHash?: string;
+  /** ISO 8601. */
+  generatedAt?: string;
+}
+/**
+ * What a host's port returns. Plain text: the SDK renders it as text, never
+ * as HTML. An explanation may state the verdict it assumed; one that
+ * disagrees with the SDK's is refused.
+ */
+interface AiTextResult {
+  text: string;
+  /** For an explanation: the verdict the model explained. */
+  verdict?: AiVerdict;
+  provenance?: AiProvenance;
+  /**
+   * What the call cost, as the provider reported it to your port: the same
+   * {@link GraderUsage} a returned grade carries, so one shape covers help for
+   * a learner and marking by a grader.
+   *
+   * The SDK never estimates it and never adds it up. It carries what a port
+   * sends through to `onInteraction`, beside the provenance, so the record of
+   * what a learner was shown and the record of what it cost are the same
+   * record. Numbers that are not finite and zero or more are dropped.
+   */
+  usage?: GraderUsage;
+}
+/**
+ * Why a result was not shown. `misquotes-answer` is writing feedback that
+ * corrects words the learner did not write: a correction whose quote is not in
+ * the draft, or not where it claims to be. `contradicts-marks` is coaching on
+ * a word the engine did not mark, or on a sound it did not report.
+ * `contradicts-item` is a critique of an item that points at a field the item
+ * does not have, or quotes words that field does not contain.
+ */
+type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer' | 'misquotes-answer' | 'contradicts-marks' | 'contradicts-item';
+/** One criterion of a written response's rubric, as the author wrote it. */
+interface AiRubricCriterionFact {
+  name: string;
+  description?: string;
+  weight: number;
+}
+/**
+ * What a model is told about a draft of a written response: the task as the
+ * learner saw it, the draft verbatim, and the rubric it will be graded on.
+ */
+interface AiWritingFacts {
+  activityType: 'written-response';
+  activityId: string;
+  title: string;
+  /** The language the item is written in, when the author gave one. */
+  locale?: string;
+  prompt: string;
+  /** The draft, exactly as the learner wrote it. Every correction quotes it. */
+  text: string;
+  /** Recomputed with `countWords`, as the grader will count it. */
+  wordCount: number;
+  minWords: number;
+  maxWords: number;
+  withinWordBounds: boolean;
+  /** The rubric the answer will be graded on; `null` when the item has none. */
+  rubric: AiRubricCriterionFact[] | null;
+  /** The target language and level, when the author gave one (e.g. `"en-A2"`). */
+  languageTarget?: string;
+}
+/**
+ * Asks for feedback on a draft of a written response, before the learner
+ * submits it. Practice only.
+ */
+interface AiWritingFeedbackRequest {
+  feature: 'writing-feedback';
+  facts: AiWritingFacts;
+  /** 1-based: which draft this is. */
+  draftNumber: number;
+  /** The text of the feedback already shown on earlier drafts, oldest first. */
+  previousFeedback: string[];
+  /** The language to write in: the learner's interface language, when known. */
+  learnerLocale?: string;
+}
+/**
+ * One correction a model proposes. `original` must be words the learner
+ * wrote; the SDK finds them in the draft itself, so a model need not count
+ * characters — leave `range` out unless you are sure of it, because a range
+ * that does not hold the quote is refused.
+ */
+interface AiWritingCorrection {
+  original: string;
+  corrected: string;
+  explanation?: string;
+  /** An error-type tag, e.g. `"tense"`, `"article"`. */
+  category?: string;
+  range?: {
+    start: number;
+    end: number;
+  };
+}
+/**
+ * A model's judgement of one rubric criterion. The SDK attaches the author's
+ * weight; a weight sent here is ignored.
+ */
+type AiCriterionJudgement = Omit<CriterionScore, 'weight'> & {
+  weight?: number;
+};
+/**
+ * What a host's `writingFeedback` port returns: the overall feedback as plain
+ * text, and optionally corrections and a judgement per rubric criterion.
+ */
+interface AiWritingFeedbackResult {
+  /** The overall feedback, addressed to the learner. Plain text, never HTML. */
+  text: string;
+  corrections?: AiWritingCorrection[];
+  criteria?: AiCriterionJudgement[];
+  provenance?: AiProvenance;
+  usage?: GraderUsage;
+}
+/**
+ * Feedback on a draft, as the SDK accepted it: what a learner is shown.
+ */
+interface AiWritingFeedback {
+  text: string;
+  /**
+   * Every correction, anchored in the draft: `range` is where the SDK found
+   * the quote, and `original` is the draft's own text at that range.
+   */
+  corrections: InlineCorrection[];
+  /** The model's judgements, with the rubric's weights. */
+  criteria: CriterionScore[];
+  /**
+   * The rubric's weighted total of the judgements, from 0 to 1, computed by
+   * the SDK as `gradeFromRubric` computes a grade — when every criterion of
+   * the rubric was judged; `null` otherwise, and on an item with no rubric.
+   *
+   * **An indication, never a grade:** it is a model's reading of a draft the
+   * learner has not submitted, and nothing in the SDK scores an answer with
+   * it. `ai-writing-feedback-shown` reports it, so a record can say what the
+   * learner was shown.
+   */
+  indicativeScore: number | null;
+  provenance?: AiProvenance;
+  usage?: GraderUsage;
+}
+/** One sound of a word, as the engine reported it. */
+interface AiSoundFact {
+  /** The sound expected, in the assessment's phoneme alphabet. */
+  symbol: string;
+  /** How close it came, 0..100, when the engine scored it. */
+  accuracy?: number;
+  /** What the engine heard instead, best first, each with its score 0..100. */
+  heardAs?: {
+    symbol: string;
+    score: number;
+  }[];
+}
+/** One word of a reading, as the engine marked it. */
+interface AiReadingWordFact {
+  /** `w<n>` for a word of the text; absent for a word the learner added. */
+  itemId?: string;
+  /** The word of the text, normalised; `''` for a word the learner added. */
+  word: string;
+  /** What was heard, normalised; `''` for an omitted word. */
+  heard: string;
+  state: 'correct' | 'mispronounced' | 'omitted' | 'inserted';
+  /** The engine's accuracy for the word, 0..100, when it has one. */
+  accuracy?: number;
+  /** The word's sounds, from the full assessment only. */
+  sounds?: AiSoundFact[];
+}
+/**
+ * What a model is told about a read-aloud: the text, the engine's marks word
+ * by word, and its scores. The marks are the engine's; a model explains them
+ * and never makes its own.
+ */
+interface AiReadingFacts {
+  activityType: 'read-aloud';
+  activityId: string;
+  title: string;
+  /** The language the text is in. */
+  locale: string;
+  referenceText: string;
+  instructions?: string;
+  /** Who made the marks: a measurement engine, a model, or a person. */
+  assessor: 'auto' | 'ai' | 'human' | 'unknown';
+  /** The alphabet `sounds` are written in, when any are. */
+  phonemeAlphabet?: 'ipa' | 'sapi';
+  /** The engine's dimension scores, each 0..100, where it measured them. */
+  scores: {
+    accuracy?: number;
+    fluency?: number;
+    completeness?: number;
+    prosody?: number;
+  };
+  words: AiReadingWordFact[];
+}
+/**
+ * Asks for coaching on a graded reading: what to work on, word by word, and
+ * how. Never in an exam.
+ */
+interface AiCoachingRequest {
+  feature: 'pronunciation-coaching';
+  facts: AiReadingFacts;
+  /** The grade of the reading, when there is one. */
+  grade?: {
+    score: number;
+    maxScore: number;
+    passed: boolean;
+  };
+  /** The language to write in: the learner's interface language, when known. */
+  learnerLocale?: string;
+}
+/** One word a model coaches, as it returns it. */
+interface AiCoachingWord {
+  /** The `itemId` of a word the engine marked mispronounced or omitted. */
+  itemId: string;
+  /** What to do about it, addressed to the learner. */
+  tip: string;
+  /**
+   * A sound the engine reported for this word — `expected` — and, if the
+   * model names one, what the engine heard instead.
+   */
+  sound?: {
+    expected: string;
+    heard?: string;
+  };
+}
+/** What a host's `pronunciationCoaching` port returns. */
+interface AiCoachingResult {
+  /** The coaching as a whole, addressed to the learner. Plain text, never HTML. */
+  text: string;
+  words?: AiCoachingWord[];
+  provenance?: AiProvenance;
+  usage?: GraderUsage;
+}
+/** Coaching, as the SDK accepted it: what a learner is shown. */
+interface AiCoaching {
+  text: string;
+  /**
+   * The words to work on, in reading order, each with the word of the text as
+   * the SDK has it — never the model's spelling of it.
+   */
+  words: (AiCoachingWord & {
+    word: string;
+  })[];
+  provenance?: AiProvenance;
+  usage?: GraderUsage;
+}
+/**
+ * What a model may find wrong with an item, in the SDK's words:
+ *
+ * - `ambiguous` — a stem, passage or blank that reads two ways;
+ * - `second-answer` — a distractor that is defensibly right, or an answer the
+ *   key does not accept;
+ * - `wrong-key` — the answer marked right is not;
+ * - `implausible-distractor` — an option nobody who read the question would pick;
+ * - `cue` — grammar or wording that points at the answer;
+ * - `level` — language above or below the level the item is for;
+ * - `language` — a mistake in the item's own language;
+ * - `sensitivity` — content a learner may find loaded or unfamiliar for
+ *   reasons that have nothing to do with what is assessed;
+ * - `other`.
+ */
+type AiCritiqueKind = 'ambiguous' | 'second-answer' | 'wrong-key' | 'implausible-distractor' | 'cue' | 'level' | 'language' | 'sensitivity' | 'other';
+/** One field of an item a critique may point at, and what it says. */
+interface AiCritiqueField {
+  path: string[];
+  text: string;
+}
+/**
+ * What a host's model is given to review an item. Built by
+ * `aiCritiqueRequest`; for an author, never a learner, so it carries the
+ * answer key.
+ */
+interface AiCritiqueRequest {
+  feature: 'item-critique';
+  facts: {
+    activityType: string;
+    /** The item as the author wrote it, answer key included. */
+    item: Readonly<Record<string, unknown>>;
+    /** Every text field a finding may point at, with its text: the only paths a finding may name. */
+    fields: AiCritiqueField[];
+    /**
+     * What the SDK's own critic already found, so a model does not say it
+     * again: code, path and message.
+     */
+    findings: {
+      path: string[];
+      code: string;
+      message: string;
+    }[];
+    /** The level the item is for, as the host names it (`A2`, `B1`), when it gave one. */
+    level?: string;
+  };
+  /** The language to write findings in: the author's. */
+  authorLocale?: string;
+}
+/** One finding as a host's port returns it. */
+interface AiCritiqueFindingResult {
+  /** A path from `facts.fields`, exactly. */
+  path: (string | number)[];
+  kind: AiCritiqueKind;
+  /** What is wrong, and what to do, addressed to the author. */
+  message: string;
+  /** Words copied from that field, when the finding is about some of them. */
+  quote?: string;
+}
+/** What a host's critique port returns. */
+interface AiCritiqueResult {
+  findings: AiCritiqueFindingResult[];
+  provenance?: AiProvenance;
+  usage?: GraderUsage;
+}
+/**
+ * A model's finding, as the SDK accepted it: an `ItemFinding` — always
+ * `advice`, since it is a model's opinion — whose code is `ai_` and the kind
+ * (`ai_second_answer`), with the quote it pointed at.
+ */
+interface AiCritiqueFinding extends ItemFinding {
+  severity: 'advice';
+  quote?: string;
+}
+/** A critique, as the SDK accepted it. */
+interface AiCritique {
+  findings: AiCritiqueFinding[];
+  provenance?: AiProvenance;
+  usage?: GraderUsage;
+}
+/**
+ * The types a model can draft from a source. An interactive video takes the
+ * first five; a written response is for a quiz of its own.
+ */
+type AiDraftType = 'multiple-choice' | 'fill-in-the-blanks' | 'gap-select' | 'dictation' | 'read-aloud' | 'written-response';
+/**
+ * What drafts are written from: a passage or a script as text — an item
+ * group's `stimulus.transcript` is one — or a video's captions, each with its
+ * start and end in seconds, so a question can be placed where its caption ends.
+ */
+type AiDraftSource = {
+  kind: 'passage' | 'transcript';
+  text: string;
+} | {
+  kind: 'captions';
+  cues: {
+    start: number;
+    end: number;
+    text: string;
+  }[];
+};
+/** A caption as a model is given it: numbered, so a draft can name the one it is about. */
+interface AiDraftCaption {
+  index: number;
+  start: number;
+  end: number;
+  text: string;
+}
+/** One problem with a draft, as a model is told it on a repair. */
+interface AiDraftProblem {
+  path: string[];
+  code: string;
+  message: string;
+  severity: 'incomplete' | 'invalid' | 'warning';
+}
+/**
+ * Fields of the host's for every draft of a type — settings a model never
+ * writes: a read-aloud's `recording`, `scoring` and region-tagged `locale`, a
+ * question's `shuffle` or `scoringStrategy`. They are put on each draft of
+ * that type before it is checked, and never override what the model wrote, nor
+ * the draft's `id`, `type` or `schemaVersion`.
+ */
+type AiDraftSettings = Partial<Record<AiDraftType, Readonly<Record<string, unknown>>>>;
+/**
+ * What a host's model is given to draft items. Built by `aiDraftsRequest`, and
+ * by `aiDraftsRepairRequest` for a second pass over the drafts that came back
+ * unfinished or flawed in ways the model can fix.
+ */
+interface AiDraftsRequest {
+  feature: 'draft-generation';
+  facts: {
+    /**
+     * The types the author chose, in the author's order: the ones to lean on
+     * first, and the order questions are shown in where several share a moment
+     * of a video — or share the end of one.
+     */
+    activityTypes: AiDraftType[];
+    source: {
+      kind: 'passage' | 'transcript';
+      text: string;
+    } | {
+      kind: 'captions';
+      captions: AiDraftCaption[];
+    };
+    /** How many drafts to write, at most. Absent: as many as the source is worth, up to `AI_DRAFTS_MAX_COUNT`. */
+    count?: number;
+    /** The language the items are written in. */
+    locale?: string;
+    /** The level they are for, as the host names it (`A2`, `B1`). */
+    level?: string;
+    /** What the author asked for, in their words. */
+    instructions?: string;
+  };
+  /**
+   * The JSON Schema of a reply — `{ drafts: [...] }` — for a model's structured
+   * output, or its prompt. Plain JSON Schema a model can follow: types, required
+   * fields, enums and descriptions, nothing a provider's structured output
+   * commonly refuses. Each draft names its `type`, and fills the fields that
+   * type uses.
+   */
+  shape: Readonly<Record<string, unknown>>;
+  /** The host's settings for every draft of a type. Not for the model; `checkAiDrafts` applies them. */
+  settings?: AiDraftSettings;
+  /**
+   * On a repair: the drafts to fix, each as the model wrote it, with what is
+   * wrong with it that the model can fix. The reply holds one draft for each,
+   * in this order.
+   */
+  repair?: {
+    index: number;
+    draft: Readonly<Record<string, unknown>>;
+    problems: AiDraftProblem[];
+  }[];
+}
+/** A draft as the SDK made it from a reply: ids minted, settings applied, checked, and critiqued. */
+interface AiGeneratedDraft {
+  /** Its position in the first reply; a repaired draft keeps the position it replaces. */
+  index: number;
+  type: AiDraftType;
+  /** The draft, an activity of its type once `validation` says `complete`. */
+  draft: Record<string, unknown>;
+  /** What `validateDraft` says of it. `complete` means valid — never approved. */
+  validation: DraftValidationResult<unknown>;
+  /** What the item critic says of it. */
+  findings: ItemFinding[];
+  /**
+   * From captions: where the question goes, in seconds — the end of the
+   * caption it named. Absent when it named no caption the source has: it
+   * belongs at the end of the video.
+   */
+  at?: number;
+  /**
+   * A dictation from captions whose transcript is words of the caption it
+   * named: that caption's start and end, in seconds — the stretch of the
+   * video that says it, for a host that cuts the recording from the video.
+   */
+  clip?: {
+    start: number;
+    end: number;
+  };
+  /** The draft as the model wrote it, for a repair. */
+  generated: Readonly<Record<string, unknown>>;
+}
+/** What `checkAiDrafts` makes of a reply. */
+interface AiDrafts {
+  /** The drafts in the author's order of types, and in the order the model wrote them within a type. */
+  drafts: AiGeneratedDraft[];
+  /** What only the set shows: every right option in one place (`set_key_position_same`). */
+  findings: ItemFinding[];
+  provenance?: AiProvenance;
+  usage?: GraderUsage;
+}
+/** One call `generateDrafts` made: what it cost, or why it went no further. */
+type AiDraftsCall = {
+  ok: true;
+  provenance?: AiProvenance;
+  usage?: GraderUsage;
+} | {
+  ok: false;
+  refusal?: AiRefusal;
+  error?: string;
+};
+/** What `generateDrafts` came to. */
+interface AiDraftsRun {
+  /** The drafts, in the author's order of types, each the best pass of it. */
+  drafts: AiGeneratedDraft[];
+  /** What only the set shows, over the drafts as they ended. */
+  findings: ItemFinding[];
+  /** Every call, in order: the first, then each repair. */
+  calls: AiDraftsCall[];
+}
+/**
+ * An interactive video made of drafts: an item group whose stimulus is the
+ * video and whose timeline opens a quiz at each moment a draft was placed —
+ * and one at the end for every draft placed nowhere. A draft, like every
+ * draft: checked, critiqued, and approved by a person, never by the SDK.
+ */
+interface AiVideoDraft {
+  /** The item group, an interactive video once `validation` says `complete`. */
+  group: Record<string, unknown>;
+  /** What `validateItemGroupDraft` says of it. */
+  validation: DraftValidationResult<unknown>;
+  /** What `critiqueItemGroupDraft` says of it. */
+  findings: ItemFinding[];
+}
+//#endregion
+export { DraftComplete as $, WrittenResponseLearnerResponse as $t, AiGapSelectFacts as A, ItemOutcome as At, AiRefusal as B, ReadAloudData as Bt, AiDraftsCall as C, GapSelectBank as Ct, AiFeature as D, GapSelectLearnerResponse as Dt, AiExplanationRequest as E, GapSelectGap as Et, AiMultipleChoiceFacts as F, MultipleChoiceData as Ft, AiVerdict as G, RecordingBounds as Gt, AiSoundFact as H, ReadAloudDimensionWeight as Ht, AiOptionFact as I, MultipleChoiceLearnerResponse as It, AiWritingCorrection as J, ScoringOutcome as Jt, AiVideoDraft as K, RecordingRef as Kt, AiProvenance as L, MultipleChoiceOption as Lt, AiGrade as M, LearnerResponseMap as Mt, AiHintRequest as N, MediaPlaybackPolicy as Nt, AiFillInTheBlanksFacts as O, InteractionEvent as Ot, AiItemFacts as P, MediaTrack as Pt, AiWritingFeedbackResult as Q, WrittenResponseData as Qt, AiReadingFacts as R, MultipleChoiceOptionMedia as Rt, AiDrafts as S, matchText as Sn, FillInTheBlanksLearnerResponse as St, AiDraftsRun as T, GapSelectData as Tt, AiSupportedActivityType as U, ReadAloudLearnerResponse as Ut, AiRubricCriterionFact as V, ReadAloudDimension as Vt, AiTextResult as W, ReadAloudSlowMedia as Wt, AiWritingFeedback as X, ValidationError as Xt, AiWritingFacts as Y, ScoringResult as Yt, AiWritingFeedbackRequest as Z, ValidationResult as Zt, AiDraftCaption as _, GradingState as _n, DictationEquivalence as _t, AiCoachingRequest as a, XAPIContextActivities as an, ItemFinding as at, AiDraftSource as b, TextMatchResult as bn, DictationTolerance as bt, AiCriterionJudgement as c, XAPIResult as cn, ActivityDataMap as ct, AiCritiqueFinding as d, XAPIVerbObject as dn, ActivityResult as dt, WrittenResponseRubric as en, DraftContext as et, AiCritiqueFindingResult as f, CriterionScore as fn, ActivityType as ft, AiDictationFacts as g, GraderUsage as gn, DictationData as gt, AiCritiqueResult as h, GraderKind as hn, DeferredScoringPartial as ht, AiCoaching as i, XAPIContext as in, DraftValidationResult as it, AiGeneratedDraft as j, LearnerResponse as jt, AiGapFact as k, InteractionKind as kt, AiCritique as l, XAPIScore as ln, ActivityFeedback as lt, AiCritiqueRequest as m, Grader as mn, DeferredReason as mt, AiActivityInput as n, XAPIActor as nn, DraftNotComplete as nt, AiCoachingResult as o, XAPIError as on, ItemFindingSeverity as ot, AiCritiqueKind as p, GradeRecord as pn, BlankConfig as pt, AiWordFact as q, ScoringDetail as qt, AiBlankFact as r, XAPIConfig as rn, DraftSeverity as rt, AiCoachingWord as s, XAPIObject as sn, ActivityData as st, ActivityAiPermissions as t, WrittenResponseRubricCriterion as tn, DraftIssue as tt, AiCritiqueField as u, XAPIStatement as un, ActivityMedia as ut, AiDraftProblem as v, InlineCorrection as vn, DictationLearnerResponse as vt, AiDraftsRequest as w, GapSelectChoice as wt, AiDraftType as x, levenshteinDistance as xn, FillInTheBlanksData as xt, AiDraftSettings as y, TextMatchPolicy as yn, DictationSlowMedia as yt, AiReadingWordFact as z, NativeControlHint as zt };
+//# sourceMappingURL=ai-B222dtHH.d.cts.map