@intellectif/lk-core 0.22.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @intellectif/lk-core
 
+## 1.1.0
+
+### Minor Changes
+
+- [#86](https://github.com/intellectif/learning-kit/pull/86) [`2215060`](https://github.com/intellectif/learning-kit/commit/22150600b0d8f5f058214a0551566b58e154276d) Thanks [@diego28e](https://github.com/diego28e)! - **Coaching on a reading aloud**: "Coach me on this reading" under a read-aloud's marks, where a model may coach only the words the speech engine marked.
+
+  **Action required:** none unless your code switches over `AiFeature`, `AiRefusal` or `InteractionKind` without a `default` branch (new members `'pronunciation-coaching'`, `'contradicts-marks'` and `'ai-coaching-shown'`), reads `AiCheckCase.request` without narrowing on `feature`, or implements a complete `LkStrings` (six new keys). Nothing changes until you pass a `pronunciationCoaching` port. Install lk-core 1.1.0 with lk-react 23.1.0: lk-react calls the new lk-core functions, and its peer range moves to `^1.1.0`. See https://github.com/intellectif/learning-kit/blob/main/docs/upgrading.md
+
+  - **lk-core:** `aiCoachingRequest` builds what a model is given: the text, the engine's marks word by word — with each word's sounds and what each was heard as, when the marks come from the assessment — its dimension scores, and the grade. `checkAiCoaching` checks the reply before a learner sees it. Every word it coaches must be one the engine marked mispronounced or omitted, and every sound one the engine reported for that word; anything else refuses the whole reply as `contradicts-marks`. The words come back in reading order, each as the marks show it, and no number in the reply is read. An assessment the grader would not read (no speech, unscripted, another text or locale) gives no coaching.
+  - **lk-react:** a `pronunciationCoaching` port on `LearnerAi`. `<ReadAloud>` offers coaching under its marks in `practice` once a take is graded and in `review` wherever marks are shown, from a kept assessment or a stored grade; never in `exam`. `<PronunciationFeedback>` offers it too, given the item's `id` and `title` in `data`, and takes `ai`, `renderMode`, `delivery` and `onInteraction` for it. It follows the author's and the paper's `ai.explanations` and needs `feedback`, not `solutions`. One coaching per take. `useAiCoaching` gives marks you draw yourself the same rules.
+  - **Records:** `ai-coaching-shown` (how many words were coached, provenance and usage; never the text), and `ai-help-refused` with `feature: 'pronunciation-coaching'`.
+  - **ai-check:** a `pronunciationCoaching` port runs four reading cases: a mispronounced "th" and a word left out, a clean reading, the same slips from a stored grade without sounds, and coaching asked for in Spanish.
+  - Six new strings: `aiCoaching`, `aiCoachingLoading`, `aiCoachingHeading`, `aiCoachingUnavailable`, `aiCoachingWords`, `aiCoachingSound`.
+  - **Stability:** the promise now says what a minor may add to a type the SDK hands you — a union member, a `LkStrings` key, an optional property — and that a `default` branch keeps a switch correct across minors.
+
+## 1.0.0
+
+### Major Changes
+
+- [#82](https://github.com/intellectif/learning-kit/pull/82) [`bcae525`](https://github.com/intellectif/learning-kit/commit/bcae52599d7d0481ccd8ceecdfc59f2bd6d4d281) Thanks [@diego28e](https://github.com/diego28e)! - **1.0**: what every 1.x keeps stable, written down, and from now on a lk-core minor releases no lk-react. No grade changes.
+
+  **Action required:** only if you read `ScoringDetail.correct`, import a zod schema from lk-core, or register an activity type of your own. Install lk-core 1.0.0 and lk-react 23.0.0 together. Each change and its replacement is in the upgrading guide: https://github.com/intellectif/learning-kit/blob/main/docs/upgrading.md
+
+  - **Stability:** grades, the public API, content and runtimes — what a 1.x release may and may not change — are set out in https://github.com/intellectif/learning-kit/blob/main/docs/stability.md. lk-react 23 peers on `@intellectif/lk-core@^1.0.0`, and a lk-core minor or patch releases no lk-react.
+  - **`ScoringDetail.correct` is removed, and `outcome` is required.** Deprecated since 0.3; on a multiple-choice option it meant "the learner acted rightly on it". Read `outcome`. The grade-stability corpus changed only there: 142 vectors lose `correct`, and no score, pass or feedback moves. A detail stored before 0.3 still carries only `correct`; the SDK's components still read it.
+  - **Zod is private to lk-core.** No zod schema is exported and no published type names zod, so your app can use any zod, or none. `validateMedia` and `validateOptionMedia` replace `MediaSchema.safeParse` and `MultipleChoiceOptionMediaSchema.safeParse`; `validateActivity`, `validateDraft` and `validateItemGroup` replace the rest. The `*JsonSchema` constants are typed `Record<string, unknown>`, and the `Redacted*` types are written out, unchanged in shape.
+  - **A type you register takes Standard Schemas** (https://standardschema.dev): `schema` and `redactedSchema` are `StandardSchemaV1`. A zod 4 schema is one as written; valibot and ArkType work too. Validation must be synchronous. `registerActivityType` throws on a value that is not a Standard Schema, and `jsonSchemaFor` on your type needs the descriptor's new `jsonSchema` unless the schema produces JSON Schema itself, as zod 4.6 does.
+  - **Built on zod 4.6.5, pinned exactly**, instead of the zod 4 preview in zod 3.25. A new zod reaches you only in a lk-core release. If your app uses another version of zod, your bundle carries two copies. Every built-in validation accepts and refuses what it did, checked against 0.21.0 on 28,000 inputs; from 1.0, `vectors/validation.json` in the tarball freezes that for over three thousand inputs, and each release replays it. Two error lists are one error shorter: a speech assessment with a string where a list of phonemes or syllables belongs, and an xAPI statement whose actor's `mbox` is not a `mailto:` address.
+  - **Fixed (lk-react):** a host's grade whose details carry no `correct` — every detail lk-core 1.0 writes — had all its details dropped, a read-aloud's word marks among them. It is now read.
+
 ## 0.22.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # @intellectif/lk-core
 
-Framework-free TypeScript core of [learning-kit](https://github.com/intellectif/learning-kit): Zod-based **activity schemas**, a pure **scoring engine**, **rubric and deferred grading**, **weighted assessment composition**, reproducible **exam attempt plans**, fail-closed **redaction**, and an **xAPI 1.0.3 statement builder + validator**. Zero React, zero DOM — usable in Node, browsers, edge, workers, or as the data layer behind `@intellectif/lk-react`.
+Framework-free TypeScript core of [learning-kit](https://github.com/intellectif/learning-kit): **activity schemas and validation**, a pure **scoring engine**, **rubric and deferred grading**, **weighted assessment composition**, reproducible **exam attempt plans**, fail-closed **redaction**, and an **xAPI 1.0.3 statement builder + validator**. Zero React, zero DOM — usable in Node, browsers, edge, workers, or as the data layer behind `@intellectif/lk-react`.
 
 It is built for **summative** assessment as much as practice: nothing here grades on the client, "not marked yet" is a first-class outcome that is never conflated with a zero, and every behavioural change that could move a historical grade is opt-in. A frozen corpus of grading vectors ships in the package, fails CI if any of them moves, and can be replayed against the build you install.
 
@@ -28,7 +28,7 @@ npm install @intellectif/lk-core
 - **Item groups** — `Stimulus` + `ItemGroup` (one passage or recording serving several questions), `flattenSequence()` for seeded, shuffle-atomic presentation order with stable slot identity. Slot ids are positional by default (`"3"`, `"1.0"`); author a `slotKey` on an entry and its id survives an insert, so a stored response cannot slide onto a different question.
 - **Delivery policies** — `DeliveryPolicy` says what a school lets a learner see around a question: feedback, solutions, hints and AI help. `resolveDeliveryPolicy` spells one out (an unreadable setting restricts, never allows), `validateDeliveryPolicy` checks one before it is stored, and `combineDeliveryPolicies` keeps a setting on only where every policy leaves it on.
 - **Scoring policies** — `ItemScoringPolicy` says how a paper's questions are scored when a learner can try again or ask for hints: `retries`, which try `counts`, and what a try and a hint cost. `scoreTries` does the arithmetic, `evaluate(…, { scoring })` and `evaluateTries` reach a question's outcome from its answers, and `validateItemScoringPolicy` / `resolveItemScoringPolicy` refuse a policy that cannot be applied rather than guess — every setting moves a grade. No policy changes nothing, and the arithmetic is pinned by the grade vectors.
-- **AI help contracts** — the SDK calls no model; it builds what yours is given and checks what comes back. `aiExplanationRequest`, `aiHintRequest` and `aiWritingFeedbackRequest` build the requests a component makes, so a server can rebuild them from its own copy of an item; `checkAiExplanation`, `checkAiHint` and `checkAiWritingFeedback` refuse an explanation that contradicts the grade, a hint that contains the answer, and writing feedback that corrects words the learner never wrote, and `checkAiWritingFeedback` computes the rubric's indicative score itself.
+- **AI help contracts** — the SDK calls no model; it builds what yours is given and checks what comes back. `aiExplanationRequest`, `aiHintRequest`, `aiWritingFeedbackRequest` and `aiCoachingRequest` build the requests a component makes, so a server can rebuild them from its own copy of an item; `checkAiExplanation`, `checkAiHint`, `checkAiWritingFeedback` and `checkAiCoaching` refuse an explanation that contradicts the grade, a hint that contains the answer, writing feedback that corrects words the learner never wrote, and coaching on a reading that names a word the speech engine did not mark or a sound it did not report; `checkAiWritingFeedback` computes the rubric's indicative score itself.
 - **Attempt plans** — `planAttempt(entries, { seed, shuffleEntries, points, delivery })` freezes the exact paper a learner sat, and the delivery policy it was sat under: slot order, per-slot points, a content hash of each item, and a `planHash` over the lot. `verifyAttemptPlan(plan, current)` reports the drift when that content is later edited (`changedSlotIds`, `changedStimulusSlotIds`, `changedPointsSlotIds`, `missingSlotIds`, …) — the thing you need during a remark or an appeal. `scoredItemsFromPlan(plan, outcomes)` turns collected outcomes into the `ScoredItem[]` composition wants, and defaults a slot with **no** outcome to `deferred` rather than silently shrinking the denominator.
 - **Attempt state** — `serializeAttemptState(plan, progress)` / `restoreAttemptState(plan, snapshot)` round-trip an interrupted attempt (responses, submitted slots, position) and are **bound to the plan**: restoring answers onto a paper the learner never sat throws instead of succeeding quietly. `diffResponses(before, after)` reports what moved between two snapshots, including an answer the learner *cleared*.
 - **Media playback policy** — `media.playback` on an audio recording: `maxPlays`, `seek`, `rate`, and advisory `nativeControlHints`. `resolvePlaybackPolicy()` derives the defaults once so the schema, the plan and the renderer cannot drift. Budgets are frozen into the plan by `planAttempt`, so editing `maxPlays` mid-window cannot change what a past learner was held to, and `planAttempt` refuses a paper where one recording is budgeted under two keys.
@@ -41,7 +41,7 @@ npm install @intellectif/lk-core
 - **xAPI builder** — `xAPIBuilder.buildAnsweredStatement(...)` / `buildSubmittedStatement(...)` / `buildCompletedStatement(...)` (plus `buildStatement(...)` for any verb) emit well-formed xAPI 1.0.3 statements with a v4 statement id and an ISO-8601 timestamp. Ids use `crypto.randomUUID()` where available and fall back to `crypto.getRandomValues()`, so statements stay well-formed on the non-secure origins `randomUUID` is gated behind.
 - **xAPI verbs for async grading** — `XAPIVerb.SUBMITTED` is emitted for work whose grade does not exist yet (`answered` would assert a score nobody computed), and `XAPIVerb.SCORED` is there for the grade that arrives later, often from a different actor. `XAPI_VERB_DISPLAY` supplies the `en-US` labels.
 - **`xapiDefinitionFor(data)`** — the xAPI interop descriptor (activity-type IRI, `cmi.interaction` type, `correctResponsesPattern`) for any registered type, so a consumer-registered activity gets correct interop with no component changes. Returns `{}` for an unregistered type, so it is always safe to spread.
-- **xAPI validator** — `validateXAPIStatement(statement)` (Zod-backed; throws on an invalid statement in development, warns in production).
+- **xAPI validator** — `validateXAPIStatement(statement)` (throws on an invalid statement in development, warns in production).
 - **Errors** — `ActivitySchemaError`, `UnknownActivityTypeError`, `DeferredScoringError` and `RedactedScoringError`, all with structured payloads.
 - **Types** — `ActivityData`, `ActivityResult`, `ScoringResult`, `XAPIStatement`, `ThemeTokens`, … all exported with JSDoc.
 
@@ -115,7 +115,7 @@ result.passed;   // boolean, or null while provisional. Never record a provision
 | Import | Contents |
 |---|---|
 | `@intellectif/lk-core` | Everything (barrel) |
-| `@intellectif/lk-core/schemas` | Zod schemas + `validateActivity` + JSON Schema export |
+| `@intellectif/lk-core/schemas` | `validateActivity`, `validateItemGroup`, `validateMedia`, `validateOptionMedia`, `jsonSchemaFor` and the JSON Schemas, and the redacted types |
 | `@intellectif/lk-core/scoring` | `score`, `evaluate`, `composeAssessmentScore`, rounding, text matching |
 | `@intellectif/lk-core/xapi` | `xAPIBuilder`, `XAPIVerb`, `validateXAPIStatement` |
 | `@intellectif/lk-core/ai-check` | `runAiCheck`, `aiCheckCases`, `formatAiCheckReport` — test your AI prompts in CI |
@@ -124,8 +124,8 @@ The barrel re-exports everything, and it is the **only** entry point for attempt
 plans, attempt state, item groups, redaction, the type registry, authoring drafts
 and content hashing — those have no subpath of their own.
 
-All exports ship as ESM + CJS with `.d.ts` types. Tree-shakeable; `sideEffects: false`. Node >= 20. In browsers, the SDK's own code needs `Object.hasOwn` — Chrome and Edge 93, Firefox 92, Safari 15.4 — because output targets ES2022 and nothing is polyfilled.
-Zod is the single runtime dependency: the package depends on `zod@^3.25` and imports the **Zod 4 API** from its `zod/v4` subpath, so it coexists with an app still on Zod 3.
+All exports ship as ESM + CJS with `.d.ts` types. Tree-shakeable; `sideEffects: false`. Node 22 or later. In browsers, the SDK's own code needs `Object.hasOwn` — Chrome and Edge 93, Firefox 92, Safari 15.4 — because output targets ES2022 and nothing is polyfilled.
+Zod is the single runtime dependency, pinned to one exact version and private: no export is a zod schema and no published type names zod, so your app can use any version of zod, or none. The pin keeps validation to what the SDK tested — a new zod ships in a lk-core release, once the validation corpus replays unchanged — at the cost of a second copy of zod in a bundle whose own zod is another version. A type you register brings its own schema, from any library that implements [Standard Schema](https://standardschema.dev). What 1.x keeps stable is set out in [Stability](https://github.com/intellectif/learning-kit/blob/main/docs/stability.md).
 
 ## Releases & upgrading
 

package/dist/{activity-CYc7SD3d.d.cts → activity-MBOYLBjR.d.cts}

@@ -226,8 +226,8 @@ interface GradeRecord {
 interface ActivityAiPermissions {
     /**
      * An explanation of the learner's graded answer — and, on a written
-     * response, feedback on a draft: both are a model's words about the
-     * learner's own answer.
+     * 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. */
@@ -248,7 +248,7 @@ interface AiActivityInput {
     readonly ai?: unknown;
 }
 /** The kinds of help a learner can be given. */
-type AiFeature = 'explanation' | 'hint' | 'writing-feedback';
+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';
 /**
@@ -411,9 +411,10 @@ interface AiTextResult {
 /**
  * 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.
+ * 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.
  */
-type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer' | 'misquotes-answer';
+type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer' | 'misquotes-answer' | 'contradicts-marks';
 /** One criterion of a written response's rubric, as the author wrote it. */
 interface AiRubricCriterionFact {
     name: string;
@@ -519,6 +520,110 @@ interface AiWritingFeedback {
     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;
+}
 
 /**
  * An xAPI Activity object — the thing a statement is about.
@@ -1460,8 +1565,7 @@ interface ReadAloudLearnerResponse {
     takes?: number;
 }
 /**
- * Fine-grained outcome of the learner's action on a single item, replacing the
- * ambiguous {@link ScoringDetail.correct}:
+ * 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).
@@ -1474,20 +1578,17 @@ interface ScoringDetail {
     /** 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
-     * correctly on this option" (`wasSelected === option.isCorrect`), NOT "this
-     * option is the answer" — an unselected wrong option reads `correct: true`.
-     * Read {@link ScoringDetail.outcome} instead; `correct` remains written for
-     * backward compatibility and will be removed in v1.0.
-     */
-    correct: boolean;
-    /**
-     * 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 every built-in scorer (by the first two since 0.3.0); becomes
-     * required in v1.0 when the deprecated `correct` is removed.
+     * 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;
+    outcome: ScoringOutcome;
     /** The learner's actual response for this item. */
     learnerResponse: string | string[];
     /** The expected correct response(s) for this item. */
@@ -1718,7 +1819,12 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
  * 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' | (string & {});
+ | '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. */
@@ -1731,4 +1837,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { type GradingState as $, type ActivityAiPermissions as A, type AiWordFact as B, type AiWritingCorrection as C, type AiWritingFacts as D, type AiWritingFeedback as E, type AiWritingFeedbackRequest as F, type AiWritingFeedbackResult as G, type BlankConfig as H, type CriterionScore as I, type DeferredReason as J, type DeferredScoringPartial as K, type DictationData as L, type DictationEquivalence as M, type DictationLearnerResponse as N, type DictationSlowMedia as O, type DictationTolerance as P, type FillInTheBlanksData as Q, type FillInTheBlanksLearnerResponse as R, type GapSelectBank as S, type GapSelectChoice as T, type GapSelectData as U, type GapSelectGap as V, type GapSelectLearnerResponse as W, type GradeRecord as X, type Grader as Y, type GraderKind as Z, type GraderUsage as _, type ActivityData as a, type InlineCorrection as a0, type InteractionEvent as a1, type InteractionKind as a2, type ItemOutcome as a3, type LearnerResponse as a4, type LearnerResponseMap as a5, type MediaPlaybackPolicy as a6, type MediaTrack as a7, type MultipleChoiceData as a8, type MultipleChoiceLearnerResponse as a9, type XAPIObject as aA, type XAPIResult as aB, type XAPIScore as aC, type XAPIStatement as aD, type XAPIVerbObject as aE, levenshteinDistance as aF, matchText as aG, type MultipleChoiceOption as aa, type MultipleChoiceOptionMedia as ab, type NativeControlHint as ac, type ReadAloudData as ad, type ReadAloudDimension as ae, type ReadAloudDimensionWeight as af, type ReadAloudLearnerResponse as ag, type ReadAloudSlowMedia as ah, type RecordingBounds as ai, type RecordingRef as aj, type ScoringDetail as ak, type ScoringOutcome as al, type ScoringResult as am, type TextMatchPolicy as an, type TextMatchResult as ao, type ValidationError as ap, type ValidationResult as aq, type WrittenResponseData as ar, type WrittenResponseLearnerResponse as as, type WrittenResponseRubric as at, type WrittenResponseRubricCriterion as au, type XAPIActor as av, type XAPIConfig as aw, type XAPIContext as ax, type XAPIContextActivities as ay, type XAPIError as az, type ActivityDataMap as b, type ActivityFeedback as c, type ActivityMedia as d, type ActivityResult as e, type ActivityType as f, type AiActivityInput as g, type AiBlankFact as h, type AiCriterionJudgement as i, type AiDictationFacts as j, type AiExplanationRequest as k, type AiFeature as l, type AiFillInTheBlanksFacts as m, type AiGapFact as n, type AiGapSelectFacts as o, type AiGrade as p, type AiHintRequest as q, type AiItemFacts as r, type AiMultipleChoiceFacts as s, type AiOptionFact as t, type AiProvenance as u, type AiRefusal as v, type AiRubricCriterionFact as w, type AiSupportedActivityType as x, type AiTextResult as y, type AiVerdict as z };
+export { type GapSelectData as $, type ActivityAiPermissions as A, type AiReadingWordFact as B, type AiRefusal as C, type AiRubricCriterionFact as D, type AiSoundFact as E, type AiSupportedActivityType as F, type AiTextResult as G, type AiVerdict as H, type AiWordFact as I, type AiWritingCorrection as J, type AiWritingFacts as K, type AiWritingFeedback as L, type AiWritingFeedbackRequest as M, type AiWritingFeedbackResult as N, type BlankConfig as O, type CriterionScore as P, type DeferredReason as Q, type DeferredScoringPartial as R, type DictationData as S, type DictationEquivalence as T, type DictationLearnerResponse as U, type DictationSlowMedia as V, type DictationTolerance as W, type FillInTheBlanksData as X, type FillInTheBlanksLearnerResponse as Y, type GapSelectBank as Z, type GapSelectChoice as _, type ActivityData as a, type GapSelectGap as a0, type GapSelectLearnerResponse as a1, type GradeRecord as a2, type Grader as a3, type GraderKind as a4, type GraderUsage as a5, type GradingState as a6, type InlineCorrection as a7, type InteractionEvent as a8, type InteractionKind as a9, type WrittenResponseRubric as aA, type WrittenResponseRubricCriterion as aB, type XAPIActor as aC, type XAPIConfig as aD, type XAPIContext as aE, type XAPIContextActivities as aF, type XAPIError as aG, type XAPIObject as aH, type XAPIResult as aI, type XAPIScore as aJ, type XAPIStatement as aK, type XAPIVerbObject as aL, levenshteinDistance as aM, matchText as aN, type ItemOutcome as aa, type LearnerResponse as ab, type LearnerResponseMap as ac, type MediaPlaybackPolicy as ad, type MediaTrack as ae, type MultipleChoiceData as af, type MultipleChoiceLearnerResponse as ag, type MultipleChoiceOption as ah, type MultipleChoiceOptionMedia as ai, type NativeControlHint as aj, type ReadAloudData as ak, type ReadAloudDimension as al, type ReadAloudDimensionWeight as am, type ReadAloudLearnerResponse as an, type ReadAloudSlowMedia as ao, type RecordingBounds as ap, type RecordingRef as aq, type ScoringDetail as ar, type ScoringOutcome as as, type ScoringResult as at, type TextMatchPolicy as au, type TextMatchResult as av, type ValidationError as aw, type ValidationResult as ax, type WrittenResponseData as ay, type WrittenResponseLearnerResponse as az, type ActivityDataMap as b, type ActivityFeedback as c, type ActivityMedia as d, type ActivityResult as e, type ActivityType as f, type AiActivityInput as g, type AiBlankFact as h, type AiCoaching as i, type AiCoachingRequest as j, type AiCoachingResult as k, type AiCoachingWord as l, type AiCriterionJudgement as m, type AiDictationFacts as n, type AiExplanationRequest as o, type AiFeature as p, type AiFillInTheBlanksFacts as q, type AiGapFact as r, type AiGapSelectFacts as s, type AiGrade as t, type AiHintRequest as u, type AiItemFacts as v, type AiMultipleChoiceFacts as w, type AiOptionFact as x, type AiProvenance as y, type AiReadingFacts as z };

package/dist/{activity-CYc7SD3d.d.ts → activity-MBOYLBjR.d.ts}

@@ -226,8 +226,8 @@ interface GradeRecord {
 interface ActivityAiPermissions {
     /**
      * An explanation of the learner's graded answer — and, on a written
-     * response, feedback on a draft: both are a model's words about the
-     * learner's own answer.
+     * 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. */
@@ -248,7 +248,7 @@ interface AiActivityInput {
     readonly ai?: unknown;
 }
 /** The kinds of help a learner can be given. */
-type AiFeature = 'explanation' | 'hint' | 'writing-feedback';
+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';
 /**
@@ -411,9 +411,10 @@ interface AiTextResult {
 /**
  * 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.
+ * 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.
  */
-type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer' | 'misquotes-answer';
+type AiRefusal = 'malformed' | 'empty' | 'too-long' | 'contradicts-grade' | 'reveals-answer' | 'misquotes-answer' | 'contradicts-marks';
 /** One criterion of a written response's rubric, as the author wrote it. */
 interface AiRubricCriterionFact {
     name: string;
@@ -519,6 +520,110 @@ interface AiWritingFeedback {
     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;
+}
 
 /**
  * An xAPI Activity object — the thing a statement is about.
@@ -1460,8 +1565,7 @@ interface ReadAloudLearnerResponse {
     takes?: number;
 }
 /**
- * Fine-grained outcome of the learner's action on a single item, replacing the
- * ambiguous {@link ScoringDetail.correct}:
+ * 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).
@@ -1474,20 +1578,17 @@ interface ScoringDetail {
     /** 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
-     * correctly on this option" (`wasSelected === option.isCorrect`), NOT "this
-     * option is the answer" — an unselected wrong option reads `correct: true`.
-     * Read {@link ScoringDetail.outcome} instead; `correct` remains written for
-     * backward compatibility and will be removed in v1.0.
-     */
-    correct: boolean;
-    /**
-     * 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 every built-in scorer (by the first two since 0.3.0); becomes
-     * required in v1.0 when the deprecated `correct` is removed.
+     * 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;
+    outcome: ScoringOutcome;
     /** The learner's actual response for this item. */
     learnerResponse: string | string[];
     /** The expected correct response(s) for this item. */
@@ -1718,7 +1819,12 @@ type InteractionKind = 'option-selected' | 'option-deselected' | 'blank-filled'
  * 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' | (string & {});
+ | '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. */
@@ -1731,4 +1837,4 @@ interface InteractionEvent {
     payload: Record<string, unknown>;
 }
 
-export { type GradingState as $, type ActivityAiPermissions as A, type AiWordFact as B, type AiWritingCorrection as C, type AiWritingFacts as D, type AiWritingFeedback as E, type AiWritingFeedbackRequest as F, type AiWritingFeedbackResult as G, type BlankConfig as H, type CriterionScore as I, type DeferredReason as J, type DeferredScoringPartial as K, type DictationData as L, type DictationEquivalence as M, type DictationLearnerResponse as N, type DictationSlowMedia as O, type DictationTolerance as P, type FillInTheBlanksData as Q, type FillInTheBlanksLearnerResponse as R, type GapSelectBank as S, type GapSelectChoice as T, type GapSelectData as U, type GapSelectGap as V, type GapSelectLearnerResponse as W, type GradeRecord as X, type Grader as Y, type GraderKind as Z, type GraderUsage as _, type ActivityData as a, type InlineCorrection as a0, type InteractionEvent as a1, type InteractionKind as a2, type ItemOutcome as a3, type LearnerResponse as a4, type LearnerResponseMap as a5, type MediaPlaybackPolicy as a6, type MediaTrack as a7, type MultipleChoiceData as a8, type MultipleChoiceLearnerResponse as a9, type XAPIObject as aA, type XAPIResult as aB, type XAPIScore as aC, type XAPIStatement as aD, type XAPIVerbObject as aE, levenshteinDistance as aF, matchText as aG, type MultipleChoiceOption as aa, type MultipleChoiceOptionMedia as ab, type NativeControlHint as ac, type ReadAloudData as ad, type ReadAloudDimension as ae, type ReadAloudDimensionWeight as af, type ReadAloudLearnerResponse as ag, type ReadAloudSlowMedia as ah, type RecordingBounds as ai, type RecordingRef as aj, type ScoringDetail as ak, type ScoringOutcome as al, type ScoringResult as am, type TextMatchPolicy as an, type TextMatchResult as ao, type ValidationError as ap, type ValidationResult as aq, type WrittenResponseData as ar, type WrittenResponseLearnerResponse as as, type WrittenResponseRubric as at, type WrittenResponseRubricCriterion as au, type XAPIActor as av, type XAPIConfig as aw, type XAPIContext as ax, type XAPIContextActivities as ay, type XAPIError as az, type ActivityDataMap as b, type ActivityFeedback as c, type ActivityMedia as d, type ActivityResult as e, type ActivityType as f, type AiActivityInput as g, type AiBlankFact as h, type AiCriterionJudgement as i, type AiDictationFacts as j, type AiExplanationRequest as k, type AiFeature as l, type AiFillInTheBlanksFacts as m, type AiGapFact as n, type AiGapSelectFacts as o, type AiGrade as p, type AiHintRequest as q, type AiItemFacts as r, type AiMultipleChoiceFacts as s, type AiOptionFact as t, type AiProvenance as u, type AiRefusal as v, type AiRubricCriterionFact as w, type AiSupportedActivityType as x, type AiTextResult as y, type AiVerdict as z };
+export { type GapSelectData as $, type ActivityAiPermissions as A, type AiReadingWordFact as B, type AiRefusal as C, type AiRubricCriterionFact as D, type AiSoundFact as E, type AiSupportedActivityType as F, type AiTextResult as G, type AiVerdict as H, type AiWordFact as I, type AiWritingCorrection as J, type AiWritingFacts as K, type AiWritingFeedback as L, type AiWritingFeedbackRequest as M, type AiWritingFeedbackResult as N, type BlankConfig as O, type CriterionScore as P, type DeferredReason as Q, type DeferredScoringPartial as R, type DictationData as S, type DictationEquivalence as T, type DictationLearnerResponse as U, type DictationSlowMedia as V, type DictationTolerance as W, type FillInTheBlanksData as X, type FillInTheBlanksLearnerResponse as Y, type GapSelectBank as Z, type GapSelectChoice as _, type ActivityData as a, type GapSelectGap as a0, type GapSelectLearnerResponse as a1, type GradeRecord as a2, type Grader as a3, type GraderKind as a4, type GraderUsage as a5, type GradingState as a6, type InlineCorrection as a7, type InteractionEvent as a8, type InteractionKind as a9, type WrittenResponseRubric as aA, type WrittenResponseRubricCriterion as aB, type XAPIActor as aC, type XAPIConfig as aD, type XAPIContext as aE, type XAPIContextActivities as aF, type XAPIError as aG, type XAPIObject as aH, type XAPIResult as aI, type XAPIScore as aJ, type XAPIStatement as aK, type XAPIVerbObject as aL, levenshteinDistance as aM, matchText as aN, type ItemOutcome as aa, type LearnerResponse as ab, type LearnerResponseMap as ac, type MediaPlaybackPolicy as ad, type MediaTrack as ae, type MultipleChoiceData as af, type MultipleChoiceLearnerResponse as ag, type MultipleChoiceOption as ah, type MultipleChoiceOptionMedia as ai, type NativeControlHint as aj, type ReadAloudData as ak, type ReadAloudDimension as al, type ReadAloudDimensionWeight as am, type ReadAloudLearnerResponse as an, type ReadAloudSlowMedia as ao, type RecordingBounds as ap, type RecordingRef as aq, type ScoringDetail as ar, type ScoringOutcome as as, type ScoringResult as at, type TextMatchPolicy as au, type TextMatchResult as av, type ValidationError as aw, type ValidationResult as ax, type WrittenResponseData as ay, type WrittenResponseLearnerResponse as az, type ActivityDataMap as b, type ActivityFeedback as c, type ActivityMedia as d, type ActivityResult as e, type ActivityType as f, type AiActivityInput as g, type AiBlankFact as h, type AiCoaching as i, type AiCoachingRequest as j, type AiCoachingResult as k, type AiCoachingWord as l, type AiCriterionJudgement as m, type AiDictationFacts as n, type AiExplanationRequest as o, type AiFeature as p, type AiFillInTheBlanksFacts as q, type AiGapFact as r, type AiGapSelectFacts as s, type AiGrade as t, type AiHintRequest as u, type AiItemFacts as v, type AiMultipleChoiceFacts as w, type AiOptionFact as x, type AiProvenance as y, type AiReadingFacts as z };