@intellectif/lk-core 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @intellectif/lk-core
 
+## 0.14.0
+
+### Minor Changes
+
+- 7d25492: A built-in `read-aloud` activity type: the learner reads a text aloud, a pronunciation-assessment engine judges the recording, and the SDK turns that judgement into a grade.
+
+  - `ReadAloudData` carries the `referenceText` the learner reads, a `locale` in canonical BCP 47 with a region, a model recording and an optional slower one (`slowMedia`, a separate file that needs the recording it is the slower reading of), the bounds of a take (`recording`), and `scoring.dimensions` — one to four of `accuracy`, `fluency`, `completeness` and `prosody`, each weighted, at least one above 0. There is no default set of dimensions and a new draft starts with none: an untouched draft must not quietly become a grading rule. The text, the weights and the bounds are all public, so a read-aloud item has no answer key: `redact()` drops the authored feedback, marks the copy, and keeps the rest — a projection a learner may render in full. The schema refuses a text nothing survives of once punctuation and spacing are folded away (`"..."` marks no word at all, so a silent take would record no omission and a perfect reading would align as one insertion after another), and, for now, a script written without spaces between its words, because per-word marks need boundaries the SDK does not compute. Nineteen draft issue codes (`ra_*`) with their severities and paths are in the authoring guide.
+  - `ReadAloudLearnerResponse` carries a `RecordingRef` — `{ key, mimeType }`, where the key is opaque storage identity your application issues, never a URL and never bytes — or `null` for a learner who submitted without recording. A `durationMs` the browser reports may ride along and no grade reads it.
+  - **Grading is deferred.** `evaluate(data, response)` answers `{ status: 'deferred', reason: 'requires_async_grading', maxScore: 1, partial: { hasRecording } }`, and `score('read-aloud', data, response)` throws `DeferredScoringError` rather than inventing a number. A stored read-aloud item therefore keeps a composed assessment result provisional until it is graded; an unscorable one is left out of the total, so route those to a re-record or a person before releasing a verdict.
+  - `SpeechAssessment` is the evidence shape, neutral across engines: the assessed locale, the reference text and recording key the assessment is bound to, who assessed it, dimension scores on a declared 0–100 scale, the recognised text, and per-word marks with optional syllables, phonemes, what each was heard as, timings and break confidences. An absent score means "not measured" and is never a 0. `validateSpeechAssessment(value)` answers `{ success: true, data }` or `{ success: false, errors }` — one error per problem, with the same `path`, `message` and `code` `validateActivity` gives a schema failure — and every object is strict, so a misspelt key is an error rather than silently ignored. Three rules span fields: a scripted assessment carries its `referenceText` and `recordingKey`; a phoneme that names a symbol, or what it was heard as, needs `phonemeAlphabet`; and the words carry at most 8000 characters between them, as they are written and again as they spell once normalised — one character can stand for eighteen, and the marks are made by aligning tokens, so a per-word cap bounds no total.
+  - `gradeReadAloud(data, response, assessment, { measured, plausibility, allowAiAssessor?, rounding? })` returns a `GradeRecord` or `{ unscorable: true, code, reason }`. `measured` is your server's own measurement of the stored recording and `plausibility` your own policy; neither has a default, because every value in them decides whether a grade exists. Ten reasons a take is unscorable rather than a zero — evidence that is not well formed, not scripted, made for another locale, another text or another take, produced by a generative model you did not opt into, no speech, too little voiced time, more words per second than your policy allows, or a weighted dimension the assessment does not score. A blank grades 0 with every reference word marked omitted and no grader, because nobody measured it. The weighted dimensions become rubric criteria out of 100 and `gradeFromRubric` computes the total; `GradeRecord.details` carries one mark per reference word, and **word marks never move the item score**.
+  - `alignReadAloud(data, assessment)` returns the same comparison as a list a review screen can render: every reference word with its state — correct, mispronounced or omitted — and every inserted word where it was spoken, each pointing back into `assessment.words` so syllables, phonemes and timings are one lookup away. `reference` and `heard` are normalised, because that is what was compared. Branch on `state`, never on `heard === ''`: an inserted word whose text normalises to nothing reads empty too.
+  - `inspectWav(bytes, { silenceDbfs, frameMs })` measures a 16-bit PCM WAV's duration, sample rate, channels, peak level and voiced time without a decoding library, and refuses what it cannot read as `not_wav`, `unsupported_encoding` or `truncated`. Both policy fields are required, because neither has an answer that is right for every microphone. Voiced time is counted in windows and never exceeds the duration, which is what `gradeReadAloud` requires of a measurement.
+  - Additive elsewhere: `GradeRecord.details`, a machine-readable `code` on an `ItemOutcome`'s unscorable arm, written by the new `outcomeFromUnscorable`; a `rounding` option on `gradeFromRubric`, so a pass line can be compared the way a score is displayed, with the score itself left unrounded; and recording and assessment `InteractionKind` literals. `GraderKind`'s three values are now documented: `'auto'` is a non-generative measurement engine, `'ai'` a generative model, `'human'` a person.
+  - `@intellectif/lk-core/scoring` now names its own functions' types. Every argument, return value and nested shape a public signature on that subpath mentions is re-exported from it — twenty type names, including `GradeRecord`, `ItemOutcome`, `ReadAloudData`, `SpeechAssessment`, `SpeechWord` and `WavInspection`. A function whose arguments cannot be named is one that has to be called from `any`, which is how evidence stops being checked. Type-only: the bundle is unchanged.
+
+  **Upgrading.**
+
+  - `read-aloud` is now a built-in. If you registered an activity type of your own under that name, `registerActivityType` will throw; rename yours before upgrading.
+  - **`RedactedScoringError`'s message has been reworded**, for every type it is thrown for and not only the new one. Its old remedy — "or use `evaluate()` which returns `{ status: "unscorable" }`" — is not true of a deferred type, which `evaluate()` answers `deferred` for, redacted or not. The class, its `name` and its `activityType` are unchanged and no grade moves; only the sentence does, so an assertion on the exact text needs updating.
+  - A `switch` that must be exhaustive over `ActivityType`, `InteractionKind` or the redacted activity union gains new members to handle.
+  - **The grade-stability corpus is written in encoding version 2.** `CORPUS_VERSION` is now `2`: a vector can carry the bytes of a recording, as `{ "$bytes": "<base64>" }`, which `inspectWav` needs. `replay()` throws rather than comparing a corpus written in another encoding, so if you replay `vectors/scoring.json` yourself, load the `replay.mjs` shipped beside it rather than a copy you pinned earlier. No expectation moved with the bump, and every grade a released version froze replays unchanged.
+
 ## 0.13.1
 
 ### Patch Changes

package/README.md

@@ -14,7 +14,7 @@ npm install @intellectif/lk-core
 
 ## What's in the box
 
-- **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.
+- **Activity schemas** for `multiple-choice`, `fill-in-the-blanks`, `written-response`, `gap-select`, `dictation` and `read-aloud`, 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*, *a read-aloud's text leaves at least one word once punctuation is folded away*). 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.

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

@@ -77,13 +77,21 @@ declare function matchText(input: string, accepted: string | readonly string[],
  * The SDK models the SHAPE and the arithmetic. It never calls a model, never
  * holds a key, and never decides what a rubric means — that stays yours.
  */
+
 /**
  * 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. */
+/**
+ * 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 {
@@ -166,6 +174,12 @@ interface GradeRecord {
     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. */
@@ -361,6 +375,7 @@ interface ActivityDataMap {
     'written-response': WrittenResponseData;
     'gap-select': GapSelectData;
     dictation: DictationData;
+    'read-aloud': ReadAloudData;
 }
 /**
  * The set of activity types supported by learning-kit. Derived from
@@ -885,6 +900,96 @@ interface DictationData {
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
 }
+/** 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;
+}
 /**
  * Maps each ActivityType string to its learner-response shape. Open for
  * extension via module augmentation, mirroring {@link ActivityDataMap}.
@@ -895,6 +1000,7 @@ interface LearnerResponseMap {
     'written-response': WrittenResponseLearnerResponse;
     'gap-select': GapSelectLearnerResponse;
     dictation: DictationLearnerResponse;
+    'read-aloud': ReadAloudLearnerResponse;
 }
 /** Union of all learner response shapes. */
 type LearnerResponse = LearnerResponseMap[keyof LearnerResponseMap];
@@ -947,6 +1053,28 @@ interface DictationLearnerResponse {
     /** Hint words revealed before submitting (practice only). 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, replacing the
  * ambiguous {@link ScoringDetail.correct}:
@@ -989,7 +1117,9 @@ interface ScoringDetail {
      * 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`.
+     * `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;
 }
@@ -1082,6 +1212,11 @@ type ItemOutcome = {
     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 {
@@ -1134,7 +1269,21 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
 /** 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' | (string & {});
+ | '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' | (string & {});
 /** Fired by activity components on every discrete learner interaction. */
 interface InteractionEvent {
     /** The kind of interaction that occurred. */
@@ -1147,4 +1296,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-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 };
+export { type WrittenResponseData as $, type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredReason as D, type MultipleChoiceLearnerResponse as E, type FillInTheBlanksData as F, type GapSelectBank as G, type MultipleChoiceOption as H, type InlineCorrection as I, type MultipleChoiceOptionMedia as J, type ReadAloudDimension as K, type LearnerResponse as L, type MediaPlaybackPolicy as M, type NativeControlHint as N, type ReadAloudDimensionWeight as O, type ReadAloudLearnerResponse as P, type ReadAloudSlowMedia as Q, type ReadAloudData as R, type RecordingBounds as S, type RecordingRef as T, type ScoringDetail as U, type ScoringOutcome as V, type ScoringResult as W, type TextMatchPolicy as X, type TextMatchResult as Y, type ValidationError as Z, type ValidationResult as _, type ActivityDataMap as a, type WrittenResponseLearnerResponse as a0, type WrittenResponseRubric as a1, type WrittenResponseRubricCriterion as a2, type XAPIActor as a3, type XAPIConfig as a4, type XAPIContext as a5, type XAPIContextActivities as a6, type XAPIError as a7, type XAPIObject as a8, type XAPIResult as a9, type XAPIScore as aa, type XAPIStatement as ab, type XAPIVerbObject as ac, levenshteinDistance as ad, matchText as ae, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type DeferredScoringPartial as f, type DictationData as g, type DictationEquivalence as h, type DictationLearnerResponse as i, type DictationSlowMedia as j, type DictationTolerance as k, type FillInTheBlanksLearnerResponse as l, type GapSelectChoice as m, type GapSelectData as n, type GapSelectGap as o, type GapSelectLearnerResponse as p, type GradeRecord as q, type Grader as r, type GraderKind as s, type GraderUsage as t, type GradingState as u, type InteractionEvent as v, type InteractionKind as w, type ItemOutcome as x, type LearnerResponseMap as y, type MultipleChoiceData as z };

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

@@ -77,13 +77,21 @@ declare function matchText(input: string, accepted: string | readonly string[],
  * The SDK models the SHAPE and the arithmetic. It never calls a model, never
  * holds a key, and never decides what a rubric means — that stays yours.
  */
+
 /**
  * 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. */
+/**
+ * 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 {
@@ -166,6 +174,12 @@ interface GradeRecord {
     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. */
@@ -361,6 +375,7 @@ interface ActivityDataMap {
     'written-response': WrittenResponseData;
     'gap-select': GapSelectData;
     dictation: DictationData;
+    'read-aloud': ReadAloudData;
 }
 /**
  * The set of activity types supported by learning-kit. Derived from
@@ -885,6 +900,96 @@ interface DictationData {
     /** Subjective difficulty on a 1–5 scale. */
     difficultyLevel?: 1 | 2 | 3 | 4 | 5;
 }
+/** 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;
+}
 /**
  * Maps each ActivityType string to its learner-response shape. Open for
  * extension via module augmentation, mirroring {@link ActivityDataMap}.
@@ -895,6 +1000,7 @@ interface LearnerResponseMap {
     'written-response': WrittenResponseLearnerResponse;
     'gap-select': GapSelectLearnerResponse;
     dictation: DictationLearnerResponse;
+    'read-aloud': ReadAloudLearnerResponse;
 }
 /** Union of all learner response shapes. */
 type LearnerResponse = LearnerResponseMap[keyof LearnerResponseMap];
@@ -947,6 +1053,28 @@ interface DictationLearnerResponse {
     /** Hint words revealed before submitting (practice only). 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, replacing the
  * ambiguous {@link ScoringDetail.correct}:
@@ -989,7 +1117,9 @@ interface ScoringDetail {
      * 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`.
+     * `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;
 }
@@ -1082,6 +1212,11 @@ type ItemOutcome = {
     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 {
@@ -1134,7 +1269,21 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
 /** 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' | (string & {});
+ | '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' | (string & {});
 /** Fired by activity components on every discrete learner interaction. */
 interface InteractionEvent {
     /** The kind of interaction that occurred. */
@@ -1147,4 +1296,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-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 };
+export { type WrittenResponseData as $, type ActivityData as A, type BlankConfig as B, type CriterionScore as C, type DeferredReason as D, type MultipleChoiceLearnerResponse as E, type FillInTheBlanksData as F, type GapSelectBank as G, type MultipleChoiceOption as H, type InlineCorrection as I, type MultipleChoiceOptionMedia as J, type ReadAloudDimension as K, type LearnerResponse as L, type MediaPlaybackPolicy as M, type NativeControlHint as N, type ReadAloudDimensionWeight as O, type ReadAloudLearnerResponse as P, type ReadAloudSlowMedia as Q, type ReadAloudData as R, type RecordingBounds as S, type RecordingRef as T, type ScoringDetail as U, type ScoringOutcome as V, type ScoringResult as W, type TextMatchPolicy as X, type TextMatchResult as Y, type ValidationError as Z, type ValidationResult as _, type ActivityDataMap as a, type WrittenResponseLearnerResponse as a0, type WrittenResponseRubric as a1, type WrittenResponseRubricCriterion as a2, type XAPIActor as a3, type XAPIConfig as a4, type XAPIContext as a5, type XAPIContextActivities as a6, type XAPIError as a7, type XAPIObject as a8, type XAPIResult as a9, type XAPIScore as aa, type XAPIStatement as ab, type XAPIVerbObject as ac, levenshteinDistance as ad, matchText as ae, type ActivityFeedback as b, type ActivityMedia as c, type ActivityResult as d, type ActivityType as e, type DeferredScoringPartial as f, type DictationData as g, type DictationEquivalence as h, type DictationLearnerResponse as i, type DictationSlowMedia as j, type DictationTolerance as k, type FillInTheBlanksLearnerResponse as l, type GapSelectChoice as m, type GapSelectData as n, type GapSelectGap as o, type GapSelectLearnerResponse as p, type GradeRecord as q, type Grader as r, type GraderKind as s, type GraderUsage as t, type GradingState as u, type InteractionEvent as v, type InteractionKind as w, type ItemOutcome as x, type LearnerResponseMap as y, type MultipleChoiceData as z };

package/dist/{chunk-DQKJUMUW.cjs → chunk-2NIALQEH.cjs}

@@ -10,7 +10,8 @@
 
 
 
-var _chunkXONKWL6Dcjs = require('./chunk-XONKWL6D.cjs');
+
+var _chunkVCXIPLEWcjs = require('./chunk-VCXIPLEW.cjs');
 
 // src/schemas/item-group.ts
 var _v4 = require('zod/v4');
@@ -38,7 +39,7 @@ var StimulusSchema = _v4.z.looseObject({
   title: _v4.z.string().optional(),
   body: _v4.z.string().optional(),
   bodyHtml: _v4.z.string().optional(),
-  media: _chunkXONKWL6Dcjs.MediaSchema.optional(),
+  media: _chunkVCXIPLEWcjs.MediaSchema.optional(),
   transcript: _v4.z.string().optional(),
   locale: _v4.z.string().optional(),
   attribution: _v4.z.string().optional()
@@ -88,7 +89,7 @@ var RedactedStimulusSchema = _v4.z.strictObject({
   title: _v4.z.string().optional(),
   body: _v4.z.string().optional(),
   bodyHtml: _v4.z.string().optional(),
-  media: _chunkXONKWL6Dcjs.RedactedMediaSchema.optional(),
+  media: _chunkVCXIPLEWcjs.RedactedMediaSchema.optional(),
   locale: _v4.z.string().optional(),
   attribution: _v4.z.string().optional()
 });
@@ -103,11 +104,11 @@ var RedactedItemGroupSchema = _v4.z.strictObject({
   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)) {
+  if (_chunkVCXIPLEWcjs.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,
+      message: _chunkVCXIPLEWcjs.GROUP_CAPTIONS_REVEAL_DICTATION,
       path: ["stimulus", "media", "captionsUrl"]
     });
   }
@@ -127,7 +128,7 @@ function validateItemGroup(data) {
   const errors = [];
   const items = [];
   container.data.items.forEach((item, index) => {
-    const descriptor = _chunkXONKWL6Dcjs.getActivityTypeDescriptor.call(void 0, item.type);
+    const descriptor = _chunkVCXIPLEWcjs.getActivityTypeDescriptor.call(void 0, item.type);
     if (descriptor === void 0) {
       errors.push({
         path: ["items", String(index), "type"],
@@ -143,10 +144,10 @@ function validateItemGroup(data) {
     }
     items.push(parsed.data);
   });
-  if (_chunkXONKWL6Dcjs.groupCaptionsRevealDictation.call(void 0, container.data)) {
+  if (_chunkVCXIPLEWcjs.groupCaptionsRevealDictation.call(void 0, container.data)) {
     errors.push({
       path: ["stimulus", "media", "captionsUrl"],
-      message: _chunkXONKWL6Dcjs.GROUP_CAPTIONS_REVEAL_DICTATION,
+      message: _chunkVCXIPLEWcjs.GROUP_CAPTIONS_REVEAL_DICTATION,
       code: "custom"
     });
   }
@@ -160,34 +161,37 @@ 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(_chunkXONKWL6Dcjs.GapSelectDataSchema, {
+var gapSelectJsonSchema = _v4.z.toJSONSchema(_chunkVCXIPLEWcjs.GapSelectDataSchema, {
+  target: "draft-7"
+});
+var dictationJsonSchema = _v4.z.toJSONSchema(_chunkVCXIPLEWcjs.DictationDataSchema, {
   target: "draft-7"
 });
-var dictationJsonSchema = _v4.z.toJSONSchema(_chunkXONKWL6Dcjs.DictationDataSchema, {
+var readAloudJsonSchema = _v4.z.toJSONSchema(_chunkVCXIPLEWcjs.ReadAloudDataSchema, {
   target: "draft-7"
 });
-var multipleChoiceJsonSchema = _v4.z.toJSONSchema(_chunkXONKWL6Dcjs.MultipleChoiceDataSchema, {
+var multipleChoiceJsonSchema = _v4.z.toJSONSchema(_chunkVCXIPLEWcjs.MultipleChoiceDataSchema, {
   target: "draft-7"
 });
-var fillInTheBlanksJsonSchema = _v4.z.toJSONSchema(_chunkXONKWL6Dcjs.FillInTheBlanksDataSchema, {
+var fillInTheBlanksJsonSchema = _v4.z.toJSONSchema(_chunkVCXIPLEWcjs.FillInTheBlanksDataSchema, {
   target: "draft-7"
 });
-var writtenResponseJsonSchema = _v4.z.toJSONSchema(_chunkXONKWL6Dcjs.WrittenResponseDataSchema, {
+var writtenResponseJsonSchema = _v4.z.toJSONSchema(_chunkVCXIPLEWcjs.WrittenResponseDataSchema, {
   target: "draft-7"
 });
 function jsonSchemaFor(type) {
-  const descriptor = _chunkXONKWL6Dcjs.getActivityTypeDescriptor.call(void 0, type);
+  const descriptor = _chunkVCXIPLEWcjs.getActivityTypeDescriptor.call(void 0, type);
   if (descriptor === void 0) {
-    throw new (0, _chunkXONKWL6Dcjs.UnknownActivityTypeError)(type);
+    throw new (0, _chunkVCXIPLEWcjs.UnknownActivityTypeError)(type);
   }
   return _v4.z.toJSONSchema(descriptor.schema, { target: "draft-7" });
 }
 
 // src/schemas/index.ts
 function validateActivity(type, data) {
-  const descriptor = _chunkXONKWL6Dcjs.getActivityTypeDescriptor.call(void 0, type);
+  const descriptor = _chunkVCXIPLEWcjs.getActivityTypeDescriptor.call(void 0, type);
   if (descriptor === void 0) {
-    throw new (0, _chunkXONKWL6Dcjs.UnknownActivityTypeError)(String(type));
+    throw new (0, _chunkVCXIPLEWcjs.UnknownActivityTypeError)(String(type));
   }
   const result = descriptor.schema.safeParse(data);
   if (result.success) {
@@ -218,5 +222,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.dictationJsonSchema = dictationJsonSchema; exports.multipleChoiceJsonSchema = multipleChoiceJsonSchema; exports.fillInTheBlanksJsonSchema = fillInTheBlanksJsonSchema; exports.writtenResponseJsonSchema = writtenResponseJsonSchema; exports.jsonSchemaFor = jsonSchemaFor; exports.validateActivity = validateActivity;
-//# sourceMappingURL=chunk-DQKJUMUW.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.readAloudJsonSchema = readAloudJsonSchema; exports.multipleChoiceJsonSchema = multipleChoiceJsonSchema; exports.fillInTheBlanksJsonSchema = fillInTheBlanksJsonSchema; exports.writtenResponseJsonSchema = writtenResponseJsonSchema; exports.jsonSchemaFor = jsonSchemaFor; exports.validateActivity = validateActivity;
+//# sourceMappingURL=chunk-2NIALQEH.cjs.map