@intellectif/lk-core 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @intellectif/lk-core
 
+## 0.13.0
+
+### Minor Changes
+
+- f26bab6: A built-in `dictation` activity type: the learner listens and types what they hear, and the grade is how close their text is to the transcript.
+
+  **lk-core**
+
+  - `DictationData` carries a `transcript` (the answer key), optional `acceptedTranscripts` scored best-of, an audio recording with the usual playback policy, an optional second slower recording (`slowMedia`, a separate file that follows the recording's policy and never has a play budget of its own), progressive word hints for practice (`hints`), and whole-word rewrite rules in `tolerance.equivalences` — the place a contraction table or a regional spelling lives, as content rather than as code inside the scorer.
+  - The score is `(length − edit distance) / length` over the whole sentence, in NFC code points, after case, punctuation, spacing and invisible characters (control, format and default-ignorable characters, variation selectors included) are ignored; typographic apostrophes and the hyphens of other scripts are folded, compatibility characters such as fullwidth and halfwidth forms, Latin digraphs, ligatures and Kangxi radicals are read as the characters they stand for (a halfwidth voiced sound mark as the mark on the kana before it), and a few sequences written two ways — the Thai SARA AM typed as its two parts, a Malayalam chillu in its older spelling — compare as one. What is spelling counts: an apostrophe, a hyphen, a Catalan middle dot or a Tibetan tsheg inside a word, a zero-width joiner or non-joiner where it changes what is written (beside a virama, as Unicode 16 lists them, or the Persian half-space between two letters that would otherwise join), the Mongolian vowel separator and free variation selectors, the tag characters of a subdivision flag, the base of a keycap and the format characters that are drawn, such as the Arabic number sign; a combining mark belongs to its word. One `ScoringDetail` per transcript word carries its own `score` — a new optional field on `ScoringDetail` — so a stored result records how each word was marked; the item's `score` is not the mean of them.
+  - `alignDictation(data, text)` returns the same comparison as data: the normalised strings, which transcript was scored against, and the word pairings with their similarities. `diffDictationChars(reference, attempt)` returns the character-level edit operations for a marked display, and `dictationReferenceWords(data)` the ids and words a stored result can be checked against. A review screen or an analytics job never re-implements the arithmetic.
+  - Learner text is compared up to 8000 code points and a transcript is at most 2000; the alignment says when text was cut. An item carries at most ten accepted transcripts and 100 equivalence rules, each `from` and `to` at most 200 code points; a rule rewrites whole words — in a script written without spaces, whose words show no edges, wherever its letters stand, though a number is a word in every script — and inserts its rewrite as words, set apart by a space where a letter of a script written with spaces, or a digit, would touch one, so `50%` with a rule for `%` reads as `50 percent`; no rule deletes a word. While rules run the text is cut at twice the attempt cap — a transcript that needs that cut is refused, an attempt that needs it is reported as truncated — so no combination of rules, authored or stale, can exhaust the process that grades an exam. The caps are exported as constants.
+  - The schema refuses captions on a dictation recording (they are the answer), and `validateItemGroup` refuses them on a group's stimulus recording that a dictation plays. It refuses a title or recording description that contains the whole transcript, or a whole accepted transcript, as whole words — as written and with the item's rules applied, and also where punctuation joins them to other words — or, for a transcript with four or more letters of a script written without spaces, wherever those letters stand, the transcript always read as it is written; and one too long to be searched in full. `validateActivity` reports these beside a refusal in any other field of the item. `assertRedacted` refuses a dictation projection that carries captions, a slow recording beside a play budget or a slow recording with no recording, and `assertRedactedItemGroup` a captioned stimulus a dictation plays, so a payload built by hand cannot pass as learner-safe.
+  - `score()` and `evaluate()` accept an optional `{ rounding }` so a pass line can be compared the way a score is displayed; without it nothing changes, and a malformed policy throws a `RangeError` instead of failing every comparison.
+  - `dictationType` and the previously unexported `gapSelectType` are on the barrel, and so are `MediaPlaybackPolicy`, the type of `ActivityMedia.playback`, and the `NativeControlHint` it lists, by name. Twenty-one draft issue codes (`dc_*`) with their severities and paths are in the authoring guide.
+  - `validateDraft` matches a schema's failures against the issues already reported in the depth of each path, where it made a pass over every reported issue for each failure: a draft with thousands of malformed entries took seconds, for every type. The issues it reports are unchanged. `validateDraft` and `validateItemGroupDraft` also normalise each dictation transcript, title and recording description once, however many of their checks read it.
+  - Every existing grade replays unchanged: vectors were added, none changed.
+
+  **lk-react**
+
+  - `<Dictation>`, also at `@intellectif/lk-react/components/Dictation`: the recording(s), the text box, and after submission an accessible word-by-word marked result with a character-level diff and a solution toggle. A recording's play limit binds through `mediaBudget` as for every other activity. Starting one of the two recordings pauses the other, and pausing spends no play.
+  - The marks are built for assistive technology and for every script: the per-word sentences a screen reader hears are in the interface language and stay hidden without the optional skin; the dictation's own words carry its `data.locale`, and its word list and diff take their direction from that tag when it names one — by a script subtag, or a language written right to left — or else from the transcript's first letter or directional mark, rather than from whatever was typed; the form is named by its title; authored feedback in the live announcement is isolated from the interface text around it. A wrong character inside a wrong word is marked by its own shape, in forced colours too — a combining mark or a stacked letter together with the character it is drawn into — and a missing character's bullet keeps its place inside a number or a word of the other direction. Keyboard focus stays on the hint controls, and a response reports only the hints actually shown.
+  - `LkStrings` gains the dictation strings. A dictionary declared as a complete `LkStrings` must add them; partial overrides are unaffected.
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -14,12 +14,13 @@ npm install @intellectif/lk-core
 
 ## What's in the box
 
-- **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.
+- **Activity schemas** for `multiple-choice`, `fill-in-the-blanks`, `written-response`, `gap-select` and `dictation`, with semantic refinements (e.g. *at least one correct option*, *single-select ⇒ exactly one correct*, *passage ↔ blank-id bijection*, *image/embed require `alt`*, *a dictation title never contains its whole transcript as words*). 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.
 - **`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.
+- **Dictation marking as data** — a dictation is graded by the character-level similarity of the typed text to the transcript, with one `ScoringDetail` per word carrying its own `score`. `alignDictation(data, text)` returns the same comparison the grade was made of (normalised strings, word pairings, which accepted transcript won), `diffDictationChars(reference, attempt)` the character-level edits for a marked display, and `dictationReferenceWords(data)` the ids and words a stored result can be checked against — so a review screen or an analytics job never re-implements the arithmetic. `score()` and `evaluate()` take an optional `{ rounding }` to compare the pass line as displayed.
 - **`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.
 - **Deferred grading, both directions** — `GradeRecord`, `gradeFromRubric()` (the weighted total as a pure function of the grader's judgements — never the model's arithmetic; declare `maxScore` per criterion if your grader works out of 100 or out of 9), `outcomeFromGrade()`, `hasGrade()`.
 - **Assessment composition** — `composeAssessmentScore()` for weighted, sectioned totals, with a `provisional` status so an unmarked essay never deflates a grade, and `RoundingPolicy` / `roundGrade` / `gte` / `classifyBand` keeping grade rounding and band classification as the two distinct operations they are.

package/dist/{activity-B2QxK15j.d.cts → activity-DfAmJ1sl.d.cts}

@@ -360,6 +360,7 @@ interface ActivityDataMap {
     'fill-in-the-blanks': FillInTheBlanksData;
     'written-response': WrittenResponseData;
     'gap-select': GapSelectData;
+    dictation: DictationData;
 }
 /**
  * The set of activity types supported by learning-kit. Derived from
@@ -782,6 +783,108 @@ interface WrittenResponseData {
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
 }
+/**
+ * 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;
+}
 /**
  * Maps each ActivityType string to its learner-response shape. Open for
  * extension via module augmentation, mirroring {@link ActivityDataMap}.
@@ -791,6 +894,7 @@ interface LearnerResponseMap {
     'fill-in-the-blanks': FillInTheBlanksLearnerResponse;
     'written-response': WrittenResponseLearnerResponse;
     'gap-select': GapSelectLearnerResponse;
+    dictation: DictationLearnerResponse;
 }
 /** Union of all learner response shapes. */
 type LearnerResponse = LearnerResponseMap[keyof LearnerResponseMap];
@@ -828,18 +932,34 @@ interface WrittenResponseLearnerResponse {
     /** 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 telemetry — how many hint words
+ * were shown before submitting — that the scorer ignores and a consumer may
+ * log or penalise, knowing it cannot be verified.
+ */
+interface DictationLearnerResponse {
+    type: 'dictation';
+    /** The learner's text, as typed. */
+    text: string;
+    /** Hint words revealed before submitting (practice only). Absent or 0 means none. */
+    hintsRevealed?: number;
+}
 /**
  * Fine-grained outcome of the learner's action on a single item, replacing the
  * ambiguous {@link ScoringDetail.correct}:
  * - `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` — the learner failed to select a correct answer (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 or blank this detail refers to. */
+    /** ID of the option, blank, gap or dictation word (`w1`…`wN`) this detail refers to. */
     itemId: string;
     /**
      * @deprecated Ambiguous: for multiple-choice this means "the learner acted
@@ -852,8 +972,8 @@ interface ScoringDetail {
     /**
      * Unambiguous outcome of the learner's action on this item. Optional in the
      * type so 0.2-era consumer-constructed literals keep compiling, but ALWAYS
-     * written by both built-in scorers since 0.3.0; becomes required in v1.0
-     * when the deprecated `correct` is removed.
+     * written by every built-in scorer (by the first two since 0.3.0); becomes
+     * required in v1.0 when the deprecated `correct` is removed.
      */
     outcome?: ScoringOutcome;
     /** The learner's actual response for this item. */
@@ -861,10 +981,17 @@ interface ScoringDetail {
     /** The expected correct response(s) for this item. */
     correctResponse: string | string[];
     /**
-     * Weight applied to this item's contribution to the overall score. Both
-     * built-in scorers currently weight every item equally and write `1`.
+     * 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
+     * nothing else today. Absent, an item is right or wrong: read `outcome`.
+     */
+    score?: number;
 }
 /** Full scoring result returned by the scoring engine. */
 interface ScoringResult {
@@ -1020,4 +1147,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { levenshteinDistance as $, type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredScoringPartial as D, type WrittenResponseLearnerResponse as E, type FillInTheBlanksData as F, type GapSelectBank as G, type WrittenResponseRubric as H, type InlineCorrection as I, type WrittenResponseRubricCriterion as J, type XAPIConfig as K, type LearnerResponse as L, type MultipleChoiceData as M, type NativeControlHint as N, type XAPIContext as O, type XAPIContextActivities as P, type XAPIError as Q, type XAPIObject as R, type ScoringDetail as S, type TextMatchPolicy as T, type XAPIResult as U, type ValidationError as V, type WrittenResponseData as W, type XAPIActor as X, type XAPIScore as Y, type XAPIStatement as Z, type XAPIVerbObject as _, type ActivityDataMap as a, matchText as a0, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type FillInTheBlanksLearnerResponse as f, type GapSelectChoice as g, type GapSelectData as h, type GapSelectGap as i, type GapSelectLearnerResponse as j, type GradeRecord as k, type Grader as l, type GraderKind as m, type GraderUsage as n, type GradingState as o, type InteractionEvent as p, type InteractionKind as q, type ItemOutcome as r, type LearnerResponseMap as s, type MultipleChoiceLearnerResponse as t, type MultipleChoiceOption as u, type MultipleChoiceOptionMedia as v, type ScoringOutcome as w, type ScoringResult as x, type TextMatchResult as y, type ValidationResult as z };
+export { type XAPIError as $, type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredScoringPartial as D, type MultipleChoiceOption as E, type FillInTheBlanksData as F, type GapSelectBank as G, type MultipleChoiceOptionMedia as H, type InlineCorrection as I, type ScoringOutcome as J, type ScoringResult as K, type LearnerResponse as L, type MediaPlaybackPolicy as M, type NativeControlHint as N, type TextMatchResult as O, type ValidationResult as P, type WrittenResponseLearnerResponse as Q, type WrittenResponseRubric as R, type ScoringDetail as S, type TextMatchPolicy as T, type WrittenResponseRubricCriterion as U, type ValidationError as V, type WrittenResponseData as W, type XAPIActor as X, type XAPIConfig as Y, type XAPIContext as Z, type XAPIContextActivities as _, type ActivityDataMap as a, type XAPIObject as a0, type XAPIResult as a1, type XAPIScore as a2, type XAPIStatement as a3, type XAPIVerbObject as a4, levenshteinDistance as a5, matchText as a6, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type DictationData as f, type DictationEquivalence as g, type DictationLearnerResponse as h, type DictationSlowMedia as i, type DictationTolerance as j, type FillInTheBlanksLearnerResponse as k, type GapSelectChoice as l, type GapSelectData as m, type GapSelectGap as n, type GapSelectLearnerResponse as o, type GradeRecord as p, type Grader as q, type GraderKind as r, type GraderUsage as s, type GradingState as t, type InteractionEvent as u, type InteractionKind as v, type ItemOutcome as w, type LearnerResponseMap as x, type MultipleChoiceData as y, type MultipleChoiceLearnerResponse as z };

package/dist/{activity-B2QxK15j.d.ts → activity-DfAmJ1sl.d.ts}

@@ -360,6 +360,7 @@ interface ActivityDataMap {
     'fill-in-the-blanks': FillInTheBlanksData;
     'written-response': WrittenResponseData;
     'gap-select': GapSelectData;
+    dictation: DictationData;
 }
 /**
  * The set of activity types supported by learning-kit. Derived from
@@ -782,6 +783,108 @@ interface WrittenResponseData {
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
 }
+/**
+ * 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;
+}
 /**
  * Maps each ActivityType string to its learner-response shape. Open for
  * extension via module augmentation, mirroring {@link ActivityDataMap}.
@@ -791,6 +894,7 @@ interface LearnerResponseMap {
     'fill-in-the-blanks': FillInTheBlanksLearnerResponse;
     'written-response': WrittenResponseLearnerResponse;
     'gap-select': GapSelectLearnerResponse;
+    dictation: DictationLearnerResponse;
 }
 /** Union of all learner response shapes. */
 type LearnerResponse = LearnerResponseMap[keyof LearnerResponseMap];
@@ -828,18 +932,34 @@ interface WrittenResponseLearnerResponse {
     /** 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 telemetry — how many hint words
+ * were shown before submitting — that the scorer ignores and a consumer may
+ * log or penalise, knowing it cannot be verified.
+ */
+interface DictationLearnerResponse {
+    type: 'dictation';
+    /** The learner's text, as typed. */
+    text: string;
+    /** Hint words revealed before submitting (practice only). Absent or 0 means none. */
+    hintsRevealed?: number;
+}
 /**
  * Fine-grained outcome of the learner's action on a single item, replacing the
  * ambiguous {@link ScoringDetail.correct}:
  * - `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` — the learner failed to select a correct answer (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 or blank this detail refers to. */
+    /** ID of the option, blank, gap or dictation word (`w1`…`wN`) this detail refers to. */
     itemId: string;
     /**
      * @deprecated Ambiguous: for multiple-choice this means "the learner acted
@@ -852,8 +972,8 @@ interface ScoringDetail {
     /**
      * Unambiguous outcome of the learner's action on this item. Optional in the
      * type so 0.2-era consumer-constructed literals keep compiling, but ALWAYS
-     * written by both built-in scorers since 0.3.0; becomes required in v1.0
-     * when the deprecated `correct` is removed.
+     * written by every built-in scorer (by the first two since 0.3.0); becomes
+     * required in v1.0 when the deprecated `correct` is removed.
      */
     outcome?: ScoringOutcome;
     /** The learner's actual response for this item. */
@@ -861,10 +981,17 @@ interface ScoringDetail {
     /** The expected correct response(s) for this item. */
     correctResponse: string | string[];
     /**
-     * Weight applied to this item's contribution to the overall score. Both
-     * built-in scorers currently weight every item equally and write `1`.
+     * 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
+     * nothing else today. Absent, an item is right or wrong: read `outcome`.
+     */
+    score?: number;
 }
 /** Full scoring result returned by the scoring engine. */
 interface ScoringResult {
@@ -1020,4 +1147,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { levenshteinDistance as $, type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredScoringPartial as D, type WrittenResponseLearnerResponse as E, type FillInTheBlanksData as F, type GapSelectBank as G, type WrittenResponseRubric as H, type InlineCorrection as I, type WrittenResponseRubricCriterion as J, type XAPIConfig as K, type LearnerResponse as L, type MultipleChoiceData as M, type NativeControlHint as N, type XAPIContext as O, type XAPIContextActivities as P, type XAPIError as Q, type XAPIObject as R, type ScoringDetail as S, type TextMatchPolicy as T, type XAPIResult as U, type ValidationError as V, type WrittenResponseData as W, type XAPIActor as X, type XAPIScore as Y, type XAPIStatement as Z, type XAPIVerbObject as _, type ActivityDataMap as a, matchText as a0, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type FillInTheBlanksLearnerResponse as f, type GapSelectChoice as g, type GapSelectData as h, type GapSelectGap as i, type GapSelectLearnerResponse as j, type GradeRecord as k, type Grader as l, type GraderKind as m, type GraderUsage as n, type GradingState as o, type InteractionEvent as p, type InteractionKind as q, type ItemOutcome as r, type LearnerResponseMap as s, type MultipleChoiceLearnerResponse as t, type MultipleChoiceOption as u, type MultipleChoiceOptionMedia as v, type ScoringOutcome as w, type ScoringResult as x, type TextMatchResult as y, type ValidationResult as z };
+export { type XAPIError as $, type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredScoringPartial as D, type MultipleChoiceOption as E, type FillInTheBlanksData as F, type GapSelectBank as G, type MultipleChoiceOptionMedia as H, type InlineCorrection as I, type ScoringOutcome as J, type ScoringResult as K, type LearnerResponse as L, type MediaPlaybackPolicy as M, type NativeControlHint as N, type TextMatchResult as O, type ValidationResult as P, type WrittenResponseLearnerResponse as Q, type WrittenResponseRubric as R, type ScoringDetail as S, type TextMatchPolicy as T, type WrittenResponseRubricCriterion as U, type ValidationError as V, type WrittenResponseData as W, type XAPIActor as X, type XAPIConfig as Y, type XAPIContext as Z, type XAPIContextActivities as _, type ActivityDataMap as a, type XAPIObject as a0, type XAPIResult as a1, type XAPIScore as a2, type XAPIStatement as a3, type XAPIVerbObject as a4, levenshteinDistance as a5, matchText as a6, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type DictationData as f, type DictationEquivalence as g, type DictationLearnerResponse as h, type DictationSlowMedia as i, type DictationTolerance as j, type FillInTheBlanksLearnerResponse as k, type GapSelectChoice as l, type GapSelectData as m, type GapSelectGap as n, type GapSelectLearnerResponse as o, type GradeRecord as p, type Grader as q, type GraderKind as r, type GraderUsage as s, type GradingState as t, type InteractionEvent as u, type InteractionKind as v, type ItemOutcome as w, type LearnerResponseMap as x, type MultipleChoiceData as y, type MultipleChoiceLearnerResponse as z };

package/dist/{chunk-VYE6BYON.cjs → chunk-DQKJUMUW.cjs}

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
 
 
@@ -7,7 +7,10 @@
 
 
 
-var _chunkJ6POE4HLcjs = require('./chunk-J6POE4HL.cjs');
+
+
+
+var _chunkXONKWL6Dcjs = require('./chunk-XONKWL6D.cjs');
 
 // src/schemas/item-group.ts
 var _v4 = require('zod/v4');
@@ -35,7 +38,7 @@ var StimulusSchema = _v4.z.looseObject({
   title: _v4.z.string().optional(),
   body: _v4.z.string().optional(),
   bodyHtml: _v4.z.string().optional(),
-  media: _chunkJ6POE4HLcjs.MediaSchema.optional(),
+  media: _chunkXONKWL6Dcjs.MediaSchema.optional(),
   transcript: _v4.z.string().optional(),
   locale: _v4.z.string().optional(),
   attribution: _v4.z.string().optional()
@@ -85,7 +88,7 @@ var RedactedStimulusSchema = _v4.z.strictObject({
   title: _v4.z.string().optional(),
   body: _v4.z.string().optional(),
   bodyHtml: _v4.z.string().optional(),
-  media: _chunkJ6POE4HLcjs.RedactedMediaSchema.optional(),
+  media: _chunkXONKWL6Dcjs.RedactedMediaSchema.optional(),
   locale: _v4.z.string().optional(),
   attribution: _v4.z.string().optional()
 });
@@ -99,6 +102,15 @@ var RedactedItemGroupSchema = _v4.z.strictObject({
   stimulus: RedactedStimulusSchema,
   items: _v4.z.array(_v4.z.unknown()).min(1),
   shuffle: _v4.z.enum(["none", "within-group"]).optional()
+}).check((ctx) => {
+  if (_chunkXONKWL6Dcjs.groupCaptionsRevealDictation.call(void 0, ctx.value)) {
+    ctx.issues.push({
+      code: "custom",
+      input: _optionalChain([ctx, 'access', _ => _.value, 'access', _2 => _2.stimulus, 'access', _3 => _3.media, 'optionalAccess', _4 => _4.captionsUrl]),
+      message: _chunkXONKWL6Dcjs.GROUP_CAPTIONS_REVEAL_DICTATION,
+      path: ["stimulus", "media", "captionsUrl"]
+    });
+  }
 });
 function toValidationErrors(issues, prefix) {
   return issues.map((issue) => ({
@@ -115,7 +127,7 @@ function validateItemGroup(data) {
   const errors = [];
   const items = [];
   container.data.items.forEach((item, index) => {
-    const descriptor = _chunkJ6POE4HLcjs.getActivityTypeDescriptor.call(void 0, item.type);
+    const descriptor = _chunkXONKWL6Dcjs.getActivityTypeDescriptor.call(void 0, item.type);
     if (descriptor === void 0) {
       errors.push({
         path: ["items", String(index), "type"],
@@ -131,6 +143,13 @@ function validateItemGroup(data) {
     }
     items.push(parsed.data);
   });
+  if (_chunkXONKWL6Dcjs.groupCaptionsRevealDictation.call(void 0, container.data)) {
+    errors.push({
+      path: ["stimulus", "media", "captionsUrl"],
+      message: _chunkXONKWL6Dcjs.GROUP_CAPTIONS_REVEAL_DICTATION,
+      code: "custom"
+    });
+  }
   if (errors.length > 0) {
     return { success: false, errors };
   }
@@ -141,31 +160,34 @@ function validateItemGroup(data) {
 
 var stimulusJsonSchema = _v4.z.toJSONSchema(StimulusSchema, { target: "draft-7" });
 var itemGroupJsonSchema = _v4.z.toJSONSchema(ItemGroupSchema, { target: "draft-7" });
-var gapSelectJsonSchema = _v4.z.toJSONSchema(_chunkJ6POE4HLcjs.GapSelectDataSchema, {
+var gapSelectJsonSchema = _v4.z.toJSONSchema(_chunkXONKWL6Dcjs.GapSelectDataSchema, {
+  target: "draft-7"
+});
+var dictationJsonSchema = _v4.z.toJSONSchema(_chunkXONKWL6Dcjs.DictationDataSchema, {
   target: "draft-7"
 });
-var multipleChoiceJsonSchema = _v4.z.toJSONSchema(_chunkJ6POE4HLcjs.MultipleChoiceDataSchema, {
+var multipleChoiceJsonSchema = _v4.z.toJSONSchema(_chunkXONKWL6Dcjs.MultipleChoiceDataSchema, {
   target: "draft-7"
 });
-var fillInTheBlanksJsonSchema = _v4.z.toJSONSchema(_chunkJ6POE4HLcjs.FillInTheBlanksDataSchema, {
+var fillInTheBlanksJsonSchema = _v4.z.toJSONSchema(_chunkXONKWL6Dcjs.FillInTheBlanksDataSchema, {
   target: "draft-7"
 });
-var writtenResponseJsonSchema = _v4.z.toJSONSchema(_chunkJ6POE4HLcjs.WrittenResponseDataSchema, {
+var writtenResponseJsonSchema = _v4.z.toJSONSchema(_chunkXONKWL6Dcjs.WrittenResponseDataSchema, {
   target: "draft-7"
 });
 function jsonSchemaFor(type) {
-  const descriptor = _chunkJ6POE4HLcjs.getActivityTypeDescriptor.call(void 0, type);
+  const descriptor = _chunkXONKWL6Dcjs.getActivityTypeDescriptor.call(void 0, type);
   if (descriptor === void 0) {
-    throw new (0, _chunkJ6POE4HLcjs.UnknownActivityTypeError)(type);
+    throw new (0, _chunkXONKWL6Dcjs.UnknownActivityTypeError)(type);
   }
   return _v4.z.toJSONSchema(descriptor.schema, { target: "draft-7" });
 }
 
 // src/schemas/index.ts
 function validateActivity(type, data) {
-  const descriptor = _chunkJ6POE4HLcjs.getActivityTypeDescriptor.call(void 0, type);
+  const descriptor = _chunkXONKWL6Dcjs.getActivityTypeDescriptor.call(void 0, type);
   if (descriptor === void 0) {
-    throw new (0, _chunkJ6POE4HLcjs.UnknownActivityTypeError)(String(type));
+    throw new (0, _chunkXONKWL6Dcjs.UnknownActivityTypeError)(String(type));
   }
   const result = descriptor.schema.safeParse(data);
   if (result.success) {
@@ -195,5 +217,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.gapSelectJsonSchema = gapSelectJsonSchema; exports.multipleChoiceJsonSchema = multipleChoiceJsonSchema; exports.fillInTheBlanksJsonSchema = fillInTheBlanksJsonSchema; exports.writtenResponseJsonSchema = writtenResponseJsonSchema; exports.jsonSchemaFor = jsonSchemaFor; exports.validateActivity = validateActivity;
-//# sourceMappingURL=chunk-VYE6BYON.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.dictationJsonSchema = dictationJsonSchema; exports.multipleChoiceJsonSchema = multipleChoiceJsonSchema; exports.fillInTheBlanksJsonSchema = fillInTheBlanksJsonSchema; exports.writtenResponseJsonSchema = writtenResponseJsonSchema; exports.jsonSchemaFor = jsonSchemaFor; exports.validateActivity = validateActivity;
+//# sourceMappingURL=chunk-DQKJUMUW.cjs.map