@intellectif/lk-react 13.0.0 → 14.0.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @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

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, Gap Select, Dictation, 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
@@ -69,8 +69,10 @@ export function Demo() {
 - **`<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.
@@ -85,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 74 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.
 
@@ -100,11 +103,14 @@ export function Demo() {
 | `@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` |
@@ -124,6 +130,7 @@ 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. |
+| **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). |
@@ -152,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-B5p_-RnJ.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-DPTyLpHt.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-DWtS4tOL.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-DPTyLpHt.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