@intellectif/lk-react 12.0.1 → 14.0.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @intellectif/lk-react
 
+## 14.0.0
+
+### Major Changes
+
+- 7d25492: The browser half of `read-aloud`: the learner records a take, the SDK hands it to your storage and brings your server's judgement back, and the result is marked word by word. The type, the evidence shape and the grade are `@intellectif/lk-core` 0.14.0's. Nothing here judges a recording, calls a speech service, holds a key or keeps audio.
+
+  - `<ReadAloud>`, also at `@intellectif/lk-react/components/ReadAloud`: the text to read, the model recording and an optional slower one (both kept silent for as long as a take is being recorded, so the microphone never picks up the model), a recorder bounded by the item's take budget and its time limit, playback of the take before it is sent, and the result. A take leaves only through `recordingBinding`, a `RecordingBinding`:
+
+    - `upload(take)` puts the take in your storage and returns its `RecordingRef`. It is required outside `review`, and a missing one throws at render, in production too: a learner must never speak into a control that stores nothing.
+    - `assess(ref)` is optional and `practice` only. It returns a `ReadAloudAssessResult` — `graded` with the assessment and the grade, `unscorable` with a code, or `failed` with whether a retry makes sense. A grade calls `onComplete`. Without `assess` the take is still stored and submitted, and a notice takes the feedback's place.
+    - `playbackUrl(ref)` is `review` only.
+
+    In `exam` it uploads, submits and locks, and never assesses, scores, reveals or builds a statement. A take whose upload failed offers a retry and blocks submit rather than becoming a blank; a blank is handed in only through an explicit "submit without recording". In `review` it renders the stored `outcome`, marked from the `assessment` you pass or rebuilt from the grade's stored `details`. `onChange` is never called: the answer is a storage key, which exists only once the take is uploaded, and `onSubmit` carries it once. `onInteraction` reports `recording-started`, `recording-stopped`, `recording-discarded`, `recording-uploaded`, `recording-upload-failed`, `assessment-requested` and `assessment-failed`, each with `takes` and `durationMs`, and `retryable` on the two failures. The subpath exports `RecordingBinding`, `RecordedTake` and `ReadAloudAssessResult` beside the component.
+
+  - `<PronunciationFeedback>`, also at `@intellectif/lk-react/components/PronunciationFeedback`: the marks on their own, for a screen that has evidence but no activity. The four dimensions each read as a percentage or "not assessed", never 0%, and every word is `correct`, `mispronounced`, `omitted` or `inserted`, opening onto its syllables, its sounds, what was heard instead and a button that plays just that word. It checks the evidence with `validateSpeechAssessment` before aligning it: in development a refusal throws `ActivitySchemaError`, and in production the word list is left out while the grade beside it is still shown.
+  - `useSpeechRecorder(options)`, also at `@intellectif/lk-react/hooks/useSpeechRecorder`: microphone capture to 16 kHz mono 16-bit PCM WAV, the format `inspectWav` measures, with an input level, a minimum take length, a take budget and an auto-stop counted from the samples rather than from a timer. Support is discovered inside `start()`, which never rejects, so a server render and its hydration agree; the microphone and the audio context are released on stop, discard, error and unmount. `discard()` gives no take back, and `reset()` starts over with the budget refunded, for a recorder handed a different reading. The hook is the first entry in the bundle budgets that is not a component, with a limit of its own: 10 kB.
+  - `CAPTURE_PROCESSOR_SOURCE` is exported beside the hook, for a Content-Security-Policy whose `script-src` does not allow `blob:`. Serve it from a URL your policy allows and pass that URL as `workletUrl`; the contract a module there must meet is written on the constant. A `workletUrl` that fails to load is not reported: the hook records through the main-thread `ScriptProcessorNode` instead, so check that the module is fetched.
+  - `<ActivitySequence>` renders a `read-aloud` slot through `<ReadAloud>`, and takes two new props:
+
+    - `recordingBinding`, a `SequenceRecordingBinding`, whose `upload`, `assess` and `playbackUrl` each receive a second argument, a `SequenceRecordingSlot` — `{ slotId, index, activityId }`, the shape `onSubmit` already passes;
+    - `assessments`, a `Readonly<Record<string, SpeechAssessment>>` keyed by `slotId` and read live rather than at mount, so a `review` shows the marks behind each stored grade once they arrive.
+
+    A `renderers` override receives neither. `<ActivityPreview>` renders a read-aloud draft with an in-memory binding that has no `assess`, so an author can record, play back and submit, and sees the notice where feedback would be.
+
+  - A graded take's xAPI statement carries the grade as a fraction of 1 — `score.scaled`, with `score.max` 1 — whatever units the grade was recorded in, so the statement always validates. `onComplete` still receives the grade's own `score` and `maxScore`.
+  - `LkStrings` gains 40 strings, 20 for read-aloud and 20 for pronunciation feedback, which makes 114. A read-aloud review reuses `awaitingGrade` and `couldNotBeGraded`.
+  - `skin.css` styles both components. The marks reuse the dictation's vocabulary — the same glyphs, decorations and tokens, with `mispronounced` standing where `incorrect` stands there — under their own `.lk-ra-*` and `.lk-pf-*` classes, and are restated in forced colours.
+
+  **Upgrading.**
+
+  - **A `read-aloud` item now renders.** `<ActivitySequence>` and `<ActivityPreview>` used to show their unsupported-activity note for one. The sequence now renders `<ReadAloud>`, which throws without `recordingBinding.upload` outside `review` — so a `practice` or `exam` sequence carrying read-aloud items needs a `recordingBinding`, or those slots render the error boundary's fallback where the note used to be.
+  - **In `practice`, a read-aloud slot completes when it is submitted.** The sequence records a `responded` outcome on submit, as it already did for every slot in `exam`, and a `scored` outcome from the slot's grade replaces it. An unscorable take, a failed assessment or a binding with no `assess` therefore no longer keeps `onFinished` from firing. A learner who records again after a grade has the new grade recorded as well, so `onActivityComplete` can fire more than once for the same `slotId` — once per graded take. A `responded` never replaces a grade: a later take that comes back ungraded leaves the earlier grade in the slot, although `onSubmit` has already reported the later take.
+  - **`onFinished` waits for an assessment in flight.** When the last slot is filled while a read-aloud is still being assessed, the set is reported once the assessment ends — with the grade in place, or with the slot's `responded` outcome when no grade came back. An assessment that never settles leaves the set unreported. `onFinished` and `onComplete` still fire once per set: a take after that reaches you through `onSubmit`, and its grade through `onActivityComplete`.
+  - **A practice take that could not be stored still completes its slot**, as `{ kind: 'unsubmitted' }` with no response. It is reported through `onFinished` only, never through `onSubmit`. That is not `responded` with `recording: null`: a null recording is a blank the learner chose, and a grader marks it 0. A storage outage must not become a zero. A retry that stores the take replaces the slot.
+  - **`SequenceItemOutcome` gained `unsubmitted`, and a `scored` outcome may carry the `response` the grade belongs to.** An exhaustive `switch` on `kind` needs a new arm. `onFinished` is the only callback that sees `unsubmitted`.
+  - **`<ReadAloud>` no longer accepts `captureGroup`.** The pager still stops a hidden slot's microphone, through `SequenceSlotContext`, not through a public prop. A spread that passed `captureGroup` used to type-check and could stop another pager's take; it is now a type error.
+  - **For every activity type, `<ActivitySequence>` refuses an outcome that arrives after `activities` changed** and does not match the `slotId` and `activityId` of the slot now at its index. A grade still being computed when the paper was swapped used to land in the new paper's slot, and could report as finished a set whose question was never answered. A paper that is only re-created, with the same slots, still accepts it.
+  - A dictionary declared as a complete `LkStrings` does not type-check until it supplies the 40 new strings; partial overrides are unaffected. A `switch` that must be exhaustive over `RenderableActivity` gains a member.
+
+### Patch Changes
+
+- Updated dependencies [7d25492]
+  - @intellectif/lk-core@0.14.0
+
+## 13.0.0
+
+### Major 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.
+
+### Patch Changes
+
+- Updated dependencies [f26bab6]
+  - @intellectif/lk-core@0.13.0
+
 ## 12.0.1
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # @intellectif/lk-react
 
-React 19 components, hooks, and theming for [learning-kit](https://github.com/intellectif/learning-kit): accessible activity components (Multiple Choice, Fill-in-the-Blanks, Written Response), a resumable in-place question-set pager with **exam** and **review** modes, a CSS-variable theming system with an optional skin, and an xAPI delivery hook.
+React 19 components, hooks, and theming for [learning-kit](https://github.com/intellectif/learning-kit): accessible activity components (Multiple Choice, Fill-in-the-Blanks, Gap Select, Dictation, Read Aloud, Written Response), a resumable in-place question-set pager with **exam** and **review** modes, a CSS-variable theming system with an optional skin, and an xAPI delivery hook.
 
 A lightweight, composable, bring-your-own-backend alternative to H5P — and unlike a
 practice-quiz widget, it is built to render a **summative** paper: in `exam` mode the
@@ -67,8 +67,12 @@ export function Demo() {
 
 - **`<MultipleChoice>`** — single / multi select, all-or-nothing or partial scoring, per-option `feedback`, and a deterministic option shuffle seeded by `shuffleSeed` (without one the order is stable for the life of the mount only, and is not reproducible afterwards).
 - **`<FillInTheBlanks>`** — `{{id}}` placeholders, case/whitespace options, per-blank `hint` (Show/Hide toggle as an icon), per-blank `feedback` shown inline on submit with a learner-controlled **Hide/Show feedback** toggle, optional `showCorrectAnswers`.
+- **`<GapSelect>`** — a dropdown cloze: `{{id}}` gaps answered from per-gap choices or a shared word bank, an empty first entry so "not answered" stays distinguishable from "answered wrongly", per-gap `feedback`, and a seeded per-gap choice shuffle.
+- **`<Dictation>`** — the learner listens and types; one or two recordings (`media`, and a slower `slowMedia` that follows the same playback policy — starting one pauses the other), progressive word hints in `practice` (recorded as `hintsRevealed`, never charged), and an accessible word-by-word marked result after submit: a hidden sentence per word for screen readers, a glyph and a text decoration per state for everyone else, a character-level diff inside each wrong word, a legend, and a **Show/Hide solution** toggle. In `review`, pass a scored `outcome` to show marks: they are recomputed from the transcript and the learner's text when the component has both (full data or `redact(data, { reveal: 'after-submit' })`, plus `value` or `defaultValue`), and rebuilt from the outcome's stored `details` otherwise. Without a scored `outcome`, nothing is marked. Its form is a landmark named by the title, so two dictations with the same title on one page — two attempts at one item, reviewed together — are two landmarks with one name, which axe reports as `landmark-unique`: give each its own title.
+- **`<ReadAloud>`** — the learner reads a text aloud. A model recording and an optional slower one (same playback policy, and both kept silent for as long as a take is being recorded, so the microphone never picks up the model), a microphone control bounded by the item's take budget and its time limit, playback of the take before it is sent, and a word-by-word pronunciation result. The SDK captures and renders; it stores nothing and judges nothing: `recordingBinding.upload` puts the take in **your** storage and `recordingBinding.assess` (`practice` only) returns **your** server's judgement, so no audio, no key and no assessor ever sit in the component. In `exam` it uploads, submits and locks without scoring, revealing or assessing — and a take whose upload failed offers a retry and blocks submit rather than silently becoming a blank. In `review` it renders the stored `outcome`, marked from an `assessment` you pass or, failing that, rebuilt from the outcome's stored `details`.
+- **`<PronunciationFeedback>`** — the marks on their own, for a review screen that has evidence but no activity: the graded dimensions (accuracy, fluency, completeness, prosody — one the engine did not measure reads "not assessed", **never 0%**), and every word marked `correct` / `mispronounced` / `omitted` / `inserted` with a hidden sentence per word for screen readers and a glyph plus a text decoration for everyone else. A word opens onto its syllables, its sounds, what was heard instead, and a button that plays just that word. Evidence it cannot trust is checked before it is aligned, so in production a malformed assessment costs the word list — never the grade beside it.
 - **`<WrittenResponse>`** — free-text writing with a live word counter and bounds messaging, graded **asynchronously**: it emits an ungraded submission (never a fake zero) and a SUBMITTED-verb xAPI statement, and renders a returned `GradeRecord` in `review` mode with per-criterion scores and inline corrections.
-- **`<ActivitySequence>`** — in-place "question set" pager (Previous/Next, "Question X of N", no scrolling, focus-managed). Accepts item groups and keeps their stimulus beside every question; `onSubmit` reports every raw answer with its `slotId`, which is the only response channel an `exam` sequence has. `onFinished` is the completion signal for a set that mixes scored and deferred-graded items, where `onComplete` can never fire.
+- **`<ActivitySequence>`** — in-place "question set" pager (Previous/Next, "Question X of N", no scrolling, focus-managed). Accepts item groups and keeps their stimulus beside every question; `onSubmit` reports every raw answer with its `slotId`, which is the only response channel an `exam` sequence has. `onFinished` is the completion signal for a set that mixes scored and deferred-graded items, where `onComplete` can never fire. A read-aloud slot takes its storage from `recordingBinding`, whose methods are told which slot a take belongs to, and a `review` its per-word marks from `assessments`, keyed by `slotId` — there is a [worked example](https://github.com/intellectif/learning-kit/blob/main/docs/speech-assessment.md#in-a-question-set).
 - **Resume and review a whole attempt** — `<ActivitySequence>` takes `defaultIndex`, `responses` and `submittedSlotIds` (read at mount; remount with a `key` to show a different attempt), so an interrupted paper reopens on the right question with the right answers and already-committed questions still committed. `onIndexChange` reports every position the pager lands on, including a clamp it had to apply. Pass `renderMode="review"` plus server-computed `outcomes` to render a finished attempt read-only. Pairs with `serializeAttemptState` / `restoreAttemptState` in `lk-core`.
 - **`renderMode`** — `practice` (default: the component scores locally and reveals correctness), `exam` (never scores, never reveals; submit emits the raw response for the server to grade), `review` (read-only, marks correctness only from an `outcome` you supply). This is the single switch that takes grading off the client.
 - **Controlled or uncontrolled** — every activity component follows the React convention: `defaultValue` to seed, `value` + `onChange` to own the answer outright, `defaultSubmitted` to mount an already-committed question as committed.
@@ -83,9 +87,10 @@ export function Demo() {
 - **Activity-level overall feedback** — `{ correct, incorrect }` shown after submit (h5p "Overall Feedback" parity).
 - **`useXAPI(config)`** — fire-and-forget LRS delivery with retry/backoff for 5xx/network (1 s / 2 s / 4 s), immediate fail on 4xx, never throws.
 - **`useActivityState()`** — `idle → in-progress → completed → reviewing` machine with `getTimeSpent()`.
+- **`useSpeechRecorder(options)`** — the capture half of a read-aloud, usable on its own: microphone permission, an RMS level for a meter, a minimum take length, and an auto-stop measured from the **sample count** rather than a timer, so a take can never outrun its own limit. It yields **16 kHz mono 16-bit PCM WAV** — the one format `inspectWav` in `lk-core` measures without a decoder. SSR-safe by construction (support is discovered inside `start()`, never probed during render, so a server render and its hydration cannot disagree), and the microphone and the audio context are released on stop, discard, error and unmount alike. Where a Content-Security-Policy's `script-src` does not allow `blob:`, serve `CAPTURE_PROCESSOR_SOURCE` — exported beside the hook, with the contract it meets written on it — and pass its URL as `workletUrl`. A `workletUrl` that fails to load is not reported: the hook falls back to the main-thread `ScriptProcessorNode`, so check that the module is fetched.
 - **`<ThemeProvider>` + `defaults.css`** — `--lk-*` design-token system; automatic dark mode via `prefers-color-scheme` (SSR-safe with `useSyncExternalStore`).
 - **`createTailwindTheme(theme)`** — optional Tailwind interop; consume the SDK palette from your own utilities.
-- **`<LkIntlProvider>`** — all 54 strings the SDK's own chrome renders, replaceable in one place, with a per-component `strings` prop for the exceptions. Interpolation and plurals are **functions**, not format strings, so your `Intl.PluralRules` does the work and TypeScript checks the arity. `locale` sets `lang` and derives `dir`; the skin uses logical properties, so RTL follows. The SDK ships the mechanism and **English only** — see [docs/i18n.md](https://github.com/intellectif/learning-kit/blob/main/docs/i18n.md).
+- **`<LkIntlProvider>`** — all 114 strings the SDK's own chrome renders, replaceable in one place, with a per-component `strings` prop for the exceptions. Interpolation and plurals are **functions**, not format strings, so your `Intl.PluralRules` does the work and TypeScript checks the arity. `locale` sets `lang` and derives `dir`; the skin uses logical properties, so RTL follows. The SDK ships the mechanism and **English only** — see [docs/i18n.md](https://github.com/intellectif/learning-kit/blob/main/docs/i18n.md).
 - **WCAG 2.2 AA** — axe-clean unit + Playwright e2e tests; full keyboard operability; numerically-verified contrast.
 - **RSC-compatible** — every component carries `'use client'` and hydrates inside a React Server Component tree.
 
@@ -97,11 +102,15 @@ export function Demo() {
 | `@intellectif/lk-react/components/MultipleChoice` | `<MultipleChoice>` (boundary-wrapped) |
 | `@intellectif/lk-react/components/FillInTheBlanks` | `<FillInTheBlanks>` (boundary-wrapped) |
 | `@intellectif/lk-react/components/GapSelect` | `<GapSelect>` dropdown cloze (boundary-wrapped) |
+| `@intellectif/lk-react/components/Dictation` | `<Dictation>` listen-and-type (boundary-wrapped) |
+| `@intellectif/lk-react/components/ReadAloud` | `<ReadAloud>` read-aloud speaking (boundary-wrapped), with the `RecordingBinding`, `RecordedTake` and `ReadAloudAssessResult` types a binding is written against |
+| `@intellectif/lk-react/components/PronunciationFeedback` | `<PronunciationFeedback>` per-word pronunciation marks (boundary-wrapped) |
 | `@intellectif/lk-react/components/WrittenResponse` | `<WrittenResponse>` (boundary-wrapped) |
 | `@intellectif/lk-react/components/ActivityPreview` | `<ActivityPreview>` draft preview for editors |
 | `@intellectif/lk-react/components/ActivitySequence` | `<ActivitySequence>` question-set pager |
 | `@intellectif/lk-react/components/StimulusPanel` | `<StimulusPanel>` shared-stimulus region |
 | `@intellectif/lk-react/hooks/useActivityState` | Lifecycle + timing |
+| `@intellectif/lk-react/hooks/useSpeechRecorder` | Microphone capture to 16 kHz mono WAV, and `CAPTURE_PROCESSOR_SOURCE` for a self-hosted worklet |
 | `@intellectif/lk-react/hooks/useXAPI` | LRS delivery (retry, never-throws) |
 | `@intellectif/lk-react/i18n/LkIntlProvider` | `<LkIntlProvider>`, `useLkStrings`, `useLkDirection`, `DEFAULT_STRINGS`, `mergeStrings`, `directionForLocale` |
 | `@intellectif/lk-react/theme/ThemeProvider` | `<ThemeProvider>`, `darkTheme`, `useTheme`, `createTailwindTheme` |
@@ -121,12 +130,13 @@ subpath of their own.
 |---|---|
 | **Scoring** | Pure & deterministic, in `lk-core`; per-activity `all-or-nothing` and `partial`. Weighted totals across items and sections are `composeAssessmentScore`; per-option weighting inside one activity is not implemented. |
 | **Grading on the client** | `practice` only. `exam` and `review` never score and never reveal correctness — pass a `redact()` projection and grade server-side. |
-| **Feedback** | Per-item (MC per-option, FIB per-blank) shown inline on submit with Hide/Show toggle, + activity-level overall. Score-band feedback is not implemented. |
+| **Speech** | A read-aloud is graded **asynchronously**, as a written response is. The SDK captures the take, renders the marks, and does the arithmetic (`gradeReadAloud` in `lk-core`); **your** application stores the recording, calls a pronunciation assessor, holds its keys, and decides every threshold. `<ReadAloud>` names no provider and assesses nothing itself, and `recordingBinding.assess` is wired in `practice` only — for anything that counts, assess on your server, where evidence a browser posted cannot be forged. See [docs/speech-assessment.md](https://github.com/intellectif/learning-kit/blob/main/docs/speech-assessment.md). |
+| **Feedback** | Per-item (MC per-option, FIB per-blank, GS per-gap) shown inline on submit with Hide/Show toggle, + activity-level overall. A dictation marks word by word instead, with a solution toggle. Score-band feedback is not implemented. |
 | **Retry** | Pass a new `data` reference or change the React `key` → the activity resets to **its seeded state**, not to blank. With `defaultValue` / `defaultSubmitted` set, a new `key` and a new `data` reference are indistinguishable: both return the restored answer, still locked as submitted. For a genuinely fresh attempt, change the `key` **and stop passing the seeds**. No built-in button — retry *policy* is yours. |
 | **Persistence / resume** | Storage is yours — capture `onSubmit` / `onChange` / `onInteraction` / `onIndexChange` and persist as you wish. Re-hydration is supported at **both** levels: `defaultValue` / `value` + `onChange` on a component (since 2.1.0), and `defaultIndex` / `responses` / `submittedSlotIds` on `<ActivitySequence>` (since 6.0.0). |
 | **Rich text** | Rendered only when you pass `sanitizeHtml`; the SDK bundles no sanitiser and injects no HTML without one. `FillInTheBlanks` deliberately **ignores** `passageHtml` — the passage hosts the answer inputs, so it is built from `passage` plus the blanks (dev-mode warning if you pass it). |
-| **i18n** | Every SDK-rendered string is replaceable through `<LkIntlProvider>` or a per-component `strings` prop (lk-react 7.1.0); `locale` sets `lang` and names xAPI statements. **No locale but English is bundled** — the SDK ships the mechanism and the English defaults, because it cannot review a translation it does not speak. RTL is supported: the provider derives `dir` from the locale — and declares neither `lang` nor `dir` when you supplied neither, so it cannot flip an RTL host back — and the skin uses logical properties throughout. Thrown errors stay English on purpose — they address the developer, not the learner. |
-| **Media** | `<audio>` / `<video>` are paused when the pager navigates away, preserving `currentTime` so a group resumes where the learner left it; nothing ever auto-plays. A provider `embed` (iframe) **cannot** be paused this way — controlling a third-party player needs its own JS API. Use `audio` / `video` for anything that must stop when the learner navigates. |
+| **i18n** | Every SDK-rendered string is replaceable through `<LkIntlProvider>` or a per-component `strings` prop (lk-react 7.1.0); `locale` sets `lang` and names xAPI statements. **No locale but English is bundled** — the SDK ships the mechanism and the English defaults, because it cannot review a translation it does not speak. RTL is supported: the provider derives `dir` from the locale — and declares neither `lang` nor `dir` when you supplied neither, so it cannot flip an RTL host back — and the skin uses logical properties throughout. A dictation's own `data.locale` puts `lang` and `dir` on its title, hints, marks and solution. Thrown errors stay English on purpose — they address the developer, not the learner. |
+| **Media** | `<audio>` / `<video>` are paused when the pager navigates away, preserving `currentTime` so a group resumes where the learner left it; nothing ever auto-plays. A dictation's two recordings never play at once: starting one pauses the other, which charges no play. A provider `embed` (iframe) **cannot** be paused this way — controlling a third-party player needs its own JS API. Use `audio` / `video` for anything that must stop when the learner navigates. |
 | **Playback policy** | Audio only. `maxPlays` / `seek` / `rate` are enforced by the SDK's own transport — a refused play is stopped inside the browser's `play` event, before a sample is audible. `nativeControlHints` is **advisory**: it emits `controlsList`, which some engines ignore, and never prevents a download. A budget is durable only if you persist it through `mediaBudget.onPlayConsumed`; the SDK stores nothing. Nothing here survives devtools. Not implemented for `video` or `embed`. |
 | **Authoring / content storage / CDN / auth** | Consumer responsibility. The contracts to build an editor on are provided: typed schemas, `validateActivity` and JSON Schema export, `validateDraft` / `createDraft` in `lk-core`, and `<ActivityPreview>` here. |
 | **SSR / RSC** | Fully supported; every component carries `'use client'`. |
@@ -149,6 +159,7 @@ before assuming a migration is needed.
 - [Authoring & content storage](https://github.com/intellectif/learning-kit/blob/main/docs/authoring.md)
 - [Styling](https://github.com/intellectif/learning-kit/blob/main/docs/styling.md) — tokens, the skin, overrides, dark mode, Tailwind.
 - [Internationalisation](https://github.com/intellectif/learning-kit/blob/main/docs/i18n.md) — the full string surface, precedence, plurals, RTL.
+- [Speech assessment](https://github.com/intellectif/learning-kit/blob/main/docs/speech-assessment.md) — the read-aloud item, the evidence an assessor must produce, and how a grade is computed.
 - [Project README](https://github.com/intellectif/learning-kit#readme) — full picture & monorepo layout.
 
 ## License

package/dist/{WrittenResponse-BgcpEM-e.d.ts → WrittenResponse-C0P34En1.d.ts}

@@ -1,5 +1,5 @@
 import { XAPIStatement, WrittenResponseData, LearnerResponse, ItemOutcome, InteractionEvent, ThemeTokens } from '@intellectif/lk-core';
-import { c as Renderable, R as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './strings-CN7n-BlE.js';
+import { f as Renderable, e as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './strings-CtdSf2St.js';
 
 /**
  * Payload delivered when the learner submits a written response. Grading is

package/dist/{WrittenResponse-ByzXYEoW.d.cts → WrittenResponse-pB1ik8hg.d.cts}

@@ -1,5 +1,5 @@
 import { XAPIStatement, WrittenResponseData, LearnerResponse, ItemOutcome, InteractionEvent, ThemeTokens } from '@intellectif/lk-core';
-import { c as Renderable, R as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './strings-CN7n-BlE.cjs';
+import { f as Renderable, e as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './strings--ADnHcaA.cjs';
 
 /**
  * Payload delivered when the learner submits a written response. Grading is