@intellectif/lk-react 23.0.1 → 23.1.0

package/dist/index.cjs

@@ -3,29 +3,27 @@
 
 var chunkPNNUPUH4_cjs = require('./chunk-PNNUPUH4.cjs');
 var chunkK63VPFOV_cjs = require('./chunk-K63VPFOV.cjs');
-var chunkIYGF7PZY_cjs = require('./chunk-IYGF7PZY.cjs');
-var chunkWZ2TBXVB_cjs = require('./chunk-WZ2TBXVB.cjs');
-var chunkSHDSOOBF_cjs = require('./chunk-SHDSOOBF.cjs');
-var chunkB4JRBV56_cjs = require('./chunk-B4JRBV56.cjs');
-var chunkXS6OYYVR_cjs = require('./chunk-XS6OYYVR.cjs');
-var chunkQAZO3ANW_cjs = require('./chunk-QAZO3ANW.cjs');
-var chunkPGAPZ6UE_cjs = require('./chunk-PGAPZ6UE.cjs');
-var chunkB7JU52YQ_cjs = require('./chunk-B7JU52YQ.cjs');
-var chunkMXZHL4U5_cjs = require('./chunk-MXZHL4U5.cjs');
-require('./chunk-W6UMY7PF.cjs');
-var chunk6RIM5EQP_cjs = require('./chunk-6RIM5EQP.cjs');
-var chunkOJGTJOWI_cjs = require('./chunk-OJGTJOWI.cjs');
-var chunkDZ7VLLDQ_cjs = require('./chunk-DZ7VLLDQ.cjs');
-var chunk7F2YQWMW_cjs = require('./chunk-7F2YQWMW.cjs');
+var chunkCWTUWNV3_cjs = require('./chunk-CWTUWNV3.cjs');
+var chunkV6BA44DS_cjs = require('./chunk-V6BA44DS.cjs');
+var chunkKFLIDTDU_cjs = require('./chunk-KFLIDTDU.cjs');
+var chunkRPWUDXG5_cjs = require('./chunk-RPWUDXG5.cjs');
+var chunkMKXEM2C5_cjs = require('./chunk-MKXEM2C5.cjs');
+var chunkYY4PFR3Z_cjs = require('./chunk-YY4PFR3Z.cjs');
+var chunkDS6HN3YR_cjs = require('./chunk-DS6HN3YR.cjs');
+var chunk7ALBSPYR_cjs = require('./chunk-7ALBSPYR.cjs');
+var chunkNAK55BYU_cjs = require('./chunk-NAK55BYU.cjs');
+require('./chunk-KHKH5LCT.cjs');
+var chunkTP5UMRAU_cjs = require('./chunk-TP5UMRAU.cjs');
+var chunkLBEKRN6Y_cjs = require('./chunk-LBEKRN6Y.cjs');
 var chunkUDCQTOVU_cjs = require('./chunk-UDCQTOVU.cjs');
 require('./chunk-OD65OZIW.cjs');
-require('./chunk-VPU6UY4O.cjs');
-require('./chunk-J2QIHZ3H.cjs');
-require('./chunk-FISEZBLF.cjs');
-require('./chunk-54DX6SLS.cjs');
-require('./chunk-UKUHVCZX.cjs');
+require('./chunk-2PNSVBLQ.cjs');
+require('./chunk-J3C72RPK.cjs');
+var chunkLPUWXIPR_cjs = require('./chunk-LPUWXIPR.cjs');
+require('./chunk-NDBMKGQ5.cjs');
 var chunkXOR4MPEN_cjs = require('./chunk-XOR4MPEN.cjs');
-var chunkNFGUJ52G_cjs = require('./chunk-NFGUJ52G.cjs');
+var chunkBIGGXHAW_cjs = require('./chunk-BIGGXHAW.cjs');
+var chunkTUVENMXB_cjs = require('./chunk-TUVENMXB.cjs');
 
 // src/components/types.ts
 function asRenderable(redacted) {
@@ -61,79 +59,75 @@ Object.defineProperty(exports, "useTheme", {
 });
 Object.defineProperty(exports, "InteractiveVideo", {
   enumerable: true,
-  get: function () { return chunkIYGF7PZY_cjs.InteractiveVideo; }
+  get: function () { return chunkCWTUWNV3_cjs.InteractiveVideo; }
 });
 Object.defineProperty(exports, "resolveCaptionTracks", {
   enumerable: true,
-  get: function () { return chunkIYGF7PZY_cjs.resolveCaptionTracks; }
+  get: function () { return chunkCWTUWNV3_cjs.resolveCaptionTracks; }
 });
 Object.defineProperty(exports, "ActivityPreview", {
   enumerable: true,
-  get: function () { return chunkWZ2TBXVB_cjs.ActivityPreview; }
+  get: function () { return chunkV6BA44DS_cjs.ActivityPreview; }
 });
 Object.defineProperty(exports, "ActivitySequence", {
   enumerable: true,
-  get: function () { return chunkSHDSOOBF_cjs.ActivitySequence; }
+  get: function () { return chunkKFLIDTDU_cjs.ActivitySequence; }
 });
 Object.defineProperty(exports, "StimulusPanel", {
   enumerable: true,
-  get: function () { return chunkB4JRBV56_cjs.StimulusPanel; }
+  get: function () { return chunkRPWUDXG5_cjs.StimulusPanel; }
 });
 Object.defineProperty(exports, "WrittenResponse", {
   enumerable: true,
-  get: function () { return chunkXS6OYYVR_cjs.WrittenResponse; }
+  get: function () { return chunkMKXEM2C5_cjs.WrittenResponse; }
 });
 Object.defineProperty(exports, "MultipleChoice", {
   enumerable: true,
-  get: function () { return chunkQAZO3ANW_cjs.MultipleChoice; }
+  get: function () { return chunkYY4PFR3Z_cjs.MultipleChoice; }
 });
 Object.defineProperty(exports, "FillInTheBlanks", {
   enumerable: true,
-  get: function () { return chunkPGAPZ6UE_cjs.FillInTheBlanks; }
+  get: function () { return chunkDS6HN3YR_cjs.FillInTheBlanks; }
 });
 Object.defineProperty(exports, "GapSelect", {
   enumerable: true,
-  get: function () { return chunkB7JU52YQ_cjs.GapSelect; }
+  get: function () { return chunk7ALBSPYR_cjs.GapSelect; }
 });
 Object.defineProperty(exports, "Dictation", {
   enumerable: true,
-  get: function () { return chunkMXZHL4U5_cjs.Dictation; }
+  get: function () { return chunkNAK55BYU_cjs.Dictation; }
 });
-Object.defineProperty(exports, "useAiExplanation", {
-  enumerable: true,
-  get: function () { return chunk6RIM5EQP_cjs.useAiExplanation; }
-});
-Object.defineProperty(exports, "useAiHints", {
+Object.defineProperty(exports, "ReadAloud", {
   enumerable: true,
-  get: function () { return chunk6RIM5EQP_cjs.useAiHints; }
+  get: function () { return chunkTP5UMRAU_cjs.ReadAloud; }
 });
-Object.defineProperty(exports, "useAiWritingFeedback", {
+Object.defineProperty(exports, "PronunciationFeedback", {
   enumerable: true,
-  get: function () { return chunk6RIM5EQP_cjs.useAiWritingFeedback; }
+  get: function () { return chunkLBEKRN6Y_cjs.PronunciationFeedback; }
 });
-Object.defineProperty(exports, "LkAiProvider", {
+Object.defineProperty(exports, "CAPTURE_PROCESSOR_SOURCE", {
   enumerable: true,
-  get: function () { return chunkOJGTJOWI_cjs.LkAiProvider; }
+  get: function () { return chunkUDCQTOVU_cjs.CAPTURE_PROCESSOR_SOURCE; }
 });
-Object.defineProperty(exports, "useLearnerAi", {
+Object.defineProperty(exports, "useSpeechRecorder", {
   enumerable: true,
-  get: function () { return chunkOJGTJOWI_cjs.useLearnerAi; }
+  get: function () { return chunkUDCQTOVU_cjs.useSpeechRecorder; }
 });
-Object.defineProperty(exports, "ReadAloud", {
+Object.defineProperty(exports, "useAiCoaching", {
   enumerable: true,
-  get: function () { return chunkDZ7VLLDQ_cjs.ReadAloud; }
+  get: function () { return chunkLPUWXIPR_cjs.useAiCoaching; }
 });
-Object.defineProperty(exports, "PronunciationFeedback", {
+Object.defineProperty(exports, "useAiExplanation", {
   enumerable: true,
-  get: function () { return chunk7F2YQWMW_cjs.PronunciationFeedback; }
+  get: function () { return chunkLPUWXIPR_cjs.useAiExplanation; }
 });
-Object.defineProperty(exports, "CAPTURE_PROCESSOR_SOURCE", {
+Object.defineProperty(exports, "useAiHints", {
   enumerable: true,
-  get: function () { return chunkUDCQTOVU_cjs.CAPTURE_PROCESSOR_SOURCE; }
+  get: function () { return chunkLPUWXIPR_cjs.useAiHints; }
 });
-Object.defineProperty(exports, "useSpeechRecorder", {
+Object.defineProperty(exports, "useAiWritingFeedback", {
   enumerable: true,
-  get: function () { return chunkUDCQTOVU_cjs.useSpeechRecorder; }
+  get: function () { return chunkLPUWXIPR_cjs.useAiWritingFeedback; }
 });
 Object.defineProperty(exports, "useActivityState", {
   enumerable: true,
@@ -141,27 +135,35 @@ Object.defineProperty(exports, "useActivityState", {
 });
 Object.defineProperty(exports, "DEFAULT_STRINGS", {
   enumerable: true,
-  get: function () { return chunkNFGUJ52G_cjs.DEFAULT_STRINGS; }
+  get: function () { return chunkBIGGXHAW_cjs.DEFAULT_STRINGS; }
 });
 Object.defineProperty(exports, "LkIntlProvider", {
   enumerable: true,
-  get: function () { return chunkNFGUJ52G_cjs.LkIntlProvider; }
+  get: function () { return chunkBIGGXHAW_cjs.LkIntlProvider; }
 });
 Object.defineProperty(exports, "directionForLocale", {
   enumerable: true,
-  get: function () { return chunkNFGUJ52G_cjs.directionForLocale; }
+  get: function () { return chunkBIGGXHAW_cjs.directionForLocale; }
 });
 Object.defineProperty(exports, "mergeStrings", {
   enumerable: true,
-  get: function () { return chunkNFGUJ52G_cjs.mergeStrings; }
+  get: function () { return chunkBIGGXHAW_cjs.mergeStrings; }
 });
 Object.defineProperty(exports, "useLkDirection", {
   enumerable: true,
-  get: function () { return chunkNFGUJ52G_cjs.useLkDirection; }
+  get: function () { return chunkBIGGXHAW_cjs.useLkDirection; }
 });
 Object.defineProperty(exports, "useLkStrings", {
   enumerable: true,
-  get: function () { return chunkNFGUJ52G_cjs.useLkStrings; }
+  get: function () { return chunkBIGGXHAW_cjs.useLkStrings; }
+});
+Object.defineProperty(exports, "LkAiProvider", {
+  enumerable: true,
+  get: function () { return chunkTUVENMXB_cjs.LkAiProvider; }
+});
+Object.defineProperty(exports, "useLearnerAi", {
+  enumerable: true,
+  get: function () { return chunkTUVENMXB_cjs.useLearnerAi; }
 });
 exports.asRenderable = asRenderable;
 exports.asRenderableSequence = asRenderableSequence;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/components/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoOO,SAAS,aACd,QAAA,EACmB;AACnB,EAAA,OAAO,QAAA;AACT;AAoCO,SAAS,qBACd,OAAA,EAC8C;AAC9C,EAAA,OAAO,OAAA;AACT","file":"index.cjs","sourcesContent":["import type {\n  ActivityData,\n  ActivityResult,\n  DeliveryPolicy,\n  InteractionEvent,\n  ItemGroup,\n  ItemOutcome,\n  ItemScoringPolicy,\n  LearnerResponse,\n  MediaPlayClaim,\n  MediaPlayGrant,\n  MediaPlayLedgerEntry,\n  RecordingRef,\n  RedactedActivityData,\n  SequenceEntry,\n  ThemeTokens,\n} from '@intellectif/lk-core';\nimport type { LearnerAi } from '../ai/LkAiProvider.js';\nimport type { RecordedTake } from '../hooks/useSpeechRecorder.js';\nimport type { LkStringsOverride } from '../i18n/strings.js';\nimport type { ReadAloudAssessResult } from './ReadAloud/ReadAloud.js';\n\n/**\n * How an activity is being presented. This is the single switch that decides\n * whether the component may grade, reveal, or submit — the three things a\n * summative exam must take away from the client.\n *\n * - `practice` (default, and the only behaviour before `renderMode` existed):\n *   the component owns the attempt. It\n *   scores locally on submit, reveals correctness and feedback, and calls\n *   `onComplete` with a full {@link ActivityResult}.\n * - `exam`: the component NEVER scores and NEVER reveals correctness. Submit\n *   emits the raw learner response through `onSubmit`; the server grades it.\n *   Safe to render redacted data, because nothing here needs the answer key.\n * - `review`: read-only. Renders the learner's submitted answer, and marks\n *   correctness only from an `outcome` the caller supplies (which the server\n *   computed). Nothing is submittable.\n */\nexport type RenderMode = 'practice' | 'exam' | 'review';\n\n/**\n * Makes the answer-key-bearing parts of an activity optional, so a component\n * can render either full activity data OR a `redact()` projection with the\n * same props. Fields the SDK classifies `answer-key` become optional here;\n * a component in `exam` mode must not read them at all.\n */\nexport type Renderable<TData> = Omit<TData, 'scoringStrategy'> & {\n  scoringStrategy?: unknown;\n  /** Present on a `redact()` projection. */\n  redacted?: true;\n};\n\n/**\n * {@link Renderable} DISTRIBUTED over a union of activity types.\n *\n * This distinction is load-bearing, not cosmetic. `Renderable<T>` is built on\n * `Omit`, and `Omit` does not distribute: `Omit<A | B, K>` collapses to the\n * keys A and B have IN COMMON, so `Renderable<ActivityData>` is a single\n * object type carrying only the fields every activity shares. Narrowing it\n * dies with it — after `if (data.type === 'multiple-choice')` the compiler\n * still refuses `data.options`, because the union it would narrow to no\n * longer exists.\n *\n * The conditional below re-distributes, so `RenderableActivity` is a real\n * union of per-type renderables and `.type` narrows again. Anything that\n * accepts \"some renderable activity, I don't know which\" — a custom renderer,\n * a sequence entry — must use THIS, not `Renderable<ActivityData>`.\n */\nexport type RenderableActivity<TData extends ActivityData = ActivityData> = TData extends unknown\n  ? Renderable<TData>\n  : never;\n\n/**\n * Sanitiser for author-supplied rich text (`questionHtml`, `promptHtml`, and a\n * stimulus's `bodyHtml`). The SDK deliberately ships NO sanitiser — that would\n * add a dependency and, worse, a false promise. Rich text is rendered only when\n * you supply this function; without it the component falls back to the\n * plain-text field, which is always escaped. Fail-safe by construction: the SDK\n * never injects HTML it was not explicitly given a sanitiser for.\n *\n * `FillInTheBlanks.passageHtml` is the one exception, and is **never**\n * rendered: the passage hosts the answer inputs, so it cannot be split at the\n * `{{blank}}` placeholders without voiding the sanitiser. The plain `passage`\n * is always used, and passing `passageHtml` warns in development.\n */\nexport type HtmlSanitizer = (html: string) => string;\n\n/**\n * The prop contract shared by every activity component (Req 3.1). Defined\n * here (React-specific) rather than in lk-core, which is React-free.\n *\n * Controlled / uncontrolled follows the React convention: pass `value` +\n * `onChange` to own the learner's answer (restore an in-progress attempt,\n * autosave a delta, drive a review); pass `defaultValue` to seed an\n * uncontrolled component; pass neither to keep the pre-2.1.0 behaviour, where\n * the component owns the answer outright.\n */\nexport interface ActivityProps<TData extends ActivityData = ActivityData> {\n  /** Activity content. Accepts a `redact()` projection in `exam` mode. */\n  data: RenderableActivity<TData>;\n  /**\n   * Called when the component scored the attempt itself. Only ever fires in\n   * `practice` mode — in `exam` mode the client does not grade, so there is\n   * no `ActivityResult` to give you; use `onSubmit`.\n   */\n  onComplete?: (result: ActivityResult) => void;\n  /**\n   * Called on submit with the raw learner response and no grade. Fires in\n   * every mode, before `onComplete`, so an exam runner can persist the\n   * response and let the server score it.\n   */\n  onSubmit?: (response: LearnerResponse) => void;\n  /** Controlled value: the learner's current response. */\n  value?: LearnerResponse;\n  /** Initial response for an uncontrolled component (ignored when `value` is set). */\n  defaultValue?: LearnerResponse;\n  /**\n   * Mount the component as already submitted — read at mount only, like any\n   * `default*` prop.\n   *\n   * Restoring an attempt without it reopens a question the learner had already\n   * submitted as answerable, so on a summative paper they can change and\n   * re-submit it. `AttemptState.submittedSlotIds` is what this consumes.\n   */\n  defaultSubmitted?: boolean;\n  /** Fires on every change to the learner's response. Required for a controlled component. */\n  onChange?: (response: LearnerResponse) => void;\n  /** Presentation mode. Defaults to `practice`. */\n  renderMode?: RenderMode;\n  /**\n   * Server-computed outcome, used by `review` mode to mark correctness\n   * without the client ever scoring. Ignored in other modes.\n   */\n  outcome?: ItemOutcome;\n  /** Renders author-supplied rich text when provided. See {@link HtmlSanitizer}. */\n  sanitizeHtml?: HtmlSanitizer;\n  /**\n   * Binds this activity's own `data.media` to a play budget the consumer\n   * persists. Usually supplied by `<ActivitySequence mediaBudget={…}>`; pass it\n   * yourself when rendering an activity standalone.\n   */\n  mediaBudget?: MediaBudgetBinding;\n  /** Translations for the audio transport chrome. See {@link MediaTransportStrings}. */\n  mediaStrings?: Partial<MediaTransportStrings>;\n  /**\n   * Overrides the SDK's chrome text for this activity, layered on whatever\n   * `LkIntlProvider` supplies. `mediaStrings` still works and is merged after\n   * this, so an existing 0.8.x call site keeps behaving as it did.\n   */\n  strings?: LkStringsOverride;\n  onInteraction?: (event: InteractionEvent) => void;\n  /**\n   * The host's AI ports for this activity — an explanation after grading, hints\n   * before submit — overriding `LkAiProvider`'s. Leave a port out to switch\n   * that help off. Nothing AI appears in `exam`, and an item whose author\n   * switched a feature off (`data.ai`) never shows it. See {@link LearnerAi}.\n   */\n  ai?: LearnerAi;\n  /**\n   * What the school running this paper lets a learner see: feedback,\n   * solutions, hints, and AI help. Every setting only takes something away\n   * from what the mode shows, and an absent policy takes nothing away. Inside\n   * `<ActivitySequence>` or `<InteractiveVideo>`, the paper's own policy holds\n   * as well, whichever is stricter. See `DeliveryPolicy` in lk-core.\n   */\n  delivery?: DeliveryPolicy | null;\n  /**\n   * How this question is scored when the learner can try again or ask for\n   * hints: how many tries, which counts, what tries and hints cost. Applies in\n   * `practice`, where the component grades — `<MultipleChoice>`,\n   * `<FillInTheBlanks>`, `<GapSelect>` and `<Dictation>`. `<ReadAloud>` takes\n   * the prop and ignores it: its tries are its own `recording.maxTakes`, and\n   * its grade comes from your assessor, not from the component. Inside\n   * `<ActivitySequence>` or `<InteractiveVideo>`, the paper's own policy wins\n   * over this one. See `ItemScoringPolicy` in lk-core.\n   *\n   * With tries, `onComplete` fires after every graded try: `score` and\n   * `passed` are the question's under the policy so far, and `xapiStatement`\n   * records the try just made. A policy `validateItemScoringPolicy` refuses\n   * throws at render.\n   */\n  scoring?: ItemScoringPolicy | null;\n  /** Per-instance token overrides, applied as inline CSS vars on the root. */\n  theme?: Partial<ThemeTokens>;\n  /**\n   * BCP 47 tag stamped as `lang` on this component's root. This is the\n   * INTERFACE language — the SDK's own chrome renders inside that element — so\n   * it should carry the same value you give `<LkIntlProvider locale>`. Passing\n   * a different one re-declares the language of every SDK string in this\n   * subtree without changing the words.\n   *\n   * It is NOT `data.locale`, which labels xAPI statements — and, on a\n   * dictation, places the dictation's own words: `<Dictation>` puts it, and\n   * the direction it names, on its title, hints, marks and solution. Other\n   * authored content in another language belongs on `stimulus.locale`, which\n   * `<StimulusPanel>` puts on the passage alone.\n   */\n  locale?: string;\n  disabled?: boolean;\n}\n\n/**\n * Bridges a server-produced `redact()` projection into the `data` prop.\n *\n * `RedactedActivityData` is deliberately index-signature typed in lk-core — it\n * proves a payload is learner-safe, not what shape it has — so TypeScript\n * cannot know it still carries the public fields a renderer needs. This is the\n * SDK's single, documented crossing of that gap, so an exam runner does not\n * have to write `as unknown as` at every call site:\n *\n * ```tsx\n * <MultipleChoice\n *   data={asRenderable<MultipleChoiceData>(redactedFromServer)}\n *   renderMode=\"exam\"\n *   onSubmit={persist}\n * />\n * ```\n *\n * Safe because `exam` mode reads only public fields; the answer-key fields the\n * type claims are exactly the ones the component is forbidden to touch there.\n *\n * Per-type redacted interfaces (`RedactedMultipleChoiceData`, …) ship from\n * lk-core since 0.6.0, but they are not yet *assignable* to `data`:\n * {@link Renderable} widens `scoringStrategy` and leaves nested answer-key\n * fields (`options[].isCorrect`, `blanks[].acceptedAnswers`) required, so a\n * real redacted payload still needs this bridge. Closing that gap is tracked\n * in the roadmap.\n */\nexport function asRenderable<TData extends ActivityData>(\n  redacted: RedactedActivityData,\n): Renderable<TData> {\n  return redacted as unknown as Renderable<TData>;\n}\n\n/**\n * The same bridge as {@link asRenderable}, for a whole sequence: activities\n * and item groups as a server hands them over, ready for `<ActivitySequence>`.\n *\n * Needed for the same reason and no other. `redactItemGroup` returns\n * `ItemGroup<RedactedActivityData>`, and `RedactedActivityData` is an\n * index-signature type whose fields are all `unknown` — so its `question` is\n * not a `string` and it satisfies no per-type renderable, however the prop is\n * widened. Widening alone cannot fix this; a crossing point is required, and\n * having exactly one keeps `as unknown as` out of consumer code.\n *\n * ```tsx\n * const entries = await fetchExam();            // redacted, server-side\n * <ActivitySequence\n *   activities={asRenderableSequence(entries)}\n *   renderMode=\"exam\"                           // REQUIRED: see below\n *   shuffleSeed={attemptId}\n *   onSubmit={persist}\n * />\n * ```\n *\n * Pass `renderMode=\"exam\"` (or `\"review\"`). Redacted data has no answer key, and\n * almost every built-in activity throws at render in the default `practice`\n * mode rather than fail later: `<MultipleChoice>`, `<FillInTheBlanks>`,\n * `<GapSelect>` and `<Dictation>` because they grade locally, and\n * `<WrittenResponse>` because `practice` still runs its local submit path and\n * emits a practice-mode xAPI statement.\n *\n * `<ReadAloud>` is the exception and renders a projection in every mode: a\n * read-aloud item has no answer key to withhold, so `redact()` removes only the\n * authored feedback and leaves the reading, its language and its bounds — which\n * is everything the component puts on screen. It grades nothing locally either;\n * the grade comes back from whatever the application asked to judge the take.\n */\nexport function asRenderableSequence(\n  entries: readonly (RedactedActivityData | RedactedItemGroupData)[],\n): readonly SequenceEntry<RenderableActivity>[] {\n  return entries as unknown as readonly SequenceEntry<RenderableActivity>[];\n}\n\n/** Structural shape of a `redactItemGroup()` projection, as it arrives from a server. */\ntype RedactedItemGroupData = ItemGroup<RedactedActivityData> & { redacted: true };\n\n/**\n * Every word the SDK's audio transport renders.\n *\n * Words, not characters: the `m:ss / m:ss` clock is digits and punctuation and\n * is formatted by the component, because it reads identically in every locale\n * this SDK targets. The scrubber's SPOKEN value does have a word in it and does\n * have a key ({@link MediaTransportStrings.timeValue}).\n *\n * Supply them to translate it. These are the highest-stakes strings on a\n * listening paper — \"No plays remaining\" decides whether a learner believes\n * they may try again — so shipping them as untranslatable English inside a\n * Spanish panel was not acceptable. Supplying any of them also sets `lang` on\n * the transport chrome, so a screen reader does not read the SDK's own words\n * with the passage's phonetics.\n */\nexport interface MediaTransportStrings {\n  play: string;\n  pause: string;\n  preparing: string;\n  mute: string;\n  unmute: string;\n  volume: string;\n  speed: string;\n  seek: string;\n  /**\n   * Spoken value of the scrubber, e.g. `('1:05', '4:30') => '1:05 of 4:30'`.\n   * Takes ALREADY-FORMATTED `m:ss` strings: a translation should not have to\n   * reimplement the clock to change the word between them.\n   */\n  timeValue: (elapsed: string, duration: string) => string;\n  /** e.g. `(1, 2) => '1 of 2 plays remaining'`. */\n  playsRemaining: (remaining: number, max: number) => string;\n  noPlaysRemaining: string;\n  /** Shown before the LAST play is spent, so a stray press cannot cost it. */\n  lastPlayConfirm: string;\n  lastPlayStart: string;\n  lastPlayCancel: string;\n  seekBlocked: string;\n  rateBlocked: string;\n  playFailed: string;\n}\n\n/**\n * Binds ONE media block to a play budget the consumer persists.\n *\n * The SDK refuses a play; it does not remember one. Everything durable here is\n * the consuming application's — see {@link SequenceMediaBudget.onPlayConsumed}.\n */\nexport interface MediaBudgetBinding {\n  /** From `slotMediaKey(slotId)` / `stimulusMediaKey(slotId)` in lk-core. */\n  key: string;\n  /** Plays already spent, and where playback stood. Read at mount only. */\n  entry?: MediaPlayLedgerEntry;\n  /** Defaults to `renderMode !== 'review'`. An explicit boolean wins either way. */\n  enforced?: boolean;\n  /** Slot context stamped onto the claim and the interaction event. */\n  slotId: string;\n  index: number;\n  activityId?: string;\n  onPlayConsumed?: (claim: MediaPlayClaim) => undefined | Promise<MediaPlayGrant | undefined>;\n  onPlayRefunded?: (claim: MediaPlayClaim) => void;\n  onPosition?: (key: string, seconds: number) => void;\n  /** Translations for the transport chrome. */\n  strings?: Partial<MediaTransportStrings>;\n}\n\n/**\n * The pager-level half of a play budget. One prop, because it is one concept.\n */\nexport interface SequenceMediaBudget {\n  /**\n   * `MediaPlayLedger.entries` goes straight in. An absent key means nothing\n   * spent. Read at mount, like `responses`.\n   */\n  plays?: Readonly<Record<string, MediaPlayLedgerEntry>>;\n  /**\n   * Re-seed token. Change this string and the budgets re-seed from `plays`\n   * WITHOUT remounting the pager — the invigilator path (\"the audio never\n   * started, give her the play back\") that would otherwise cost the learner\n   * their focus, their scroll position and an unsaved answer.\n   */\n  resumeKey?: string;\n  /** Explicit override of the default (`renderMode !== 'review'`). */\n  enforced?: boolean;\n  /**\n   * Called the instant a play is claimed, BEFORE any audio is audible.\n   *\n   * Two tiers, chosen by what you return:\n   *\n   * - **Return nothing (optimistic).** Playback starts immediately and the\n   *   count is only as durable as your write. **Do not debounce this, and do\n   *   not batch it with the answer autosave** — an eight-second debounce is\n   *   exactly long enough to start a third play and hard-reload. A `pagehide`\n   *   beacon is a backstop, not the mechanism. A crash between this call and\n   *   your write landing RETURNS the play to the learner; that is the honest\n   *   description of what you are buying.\n   * - **Return a promise (confirmed).** Playback is held — the button reads\n   *   \"Preparing…\" and is `aria-busy` — until it settles. Resolve with\n   *   `{ playsUsed }` from an ATOMIC server write (`UPDATE … SET plays = plays\n   *   + 1 … RETURNING plays`, or a compare-and-set on\n   *   `claim.previousPlaysUsed`). A resolved count above `maxPlays` refuses the\n   *   play, which is how a second tab is caught: two mounts both seeded at 0\n   *   both claim 1, and only an atomic increment can tell them apart. A\n   *   rejection charges nothing and lets the learner retry. This is the only\n   *   tier in which \"consumed before audible\" is true of storage rather than\n   *   only of memory; use it for summative papers.\n   *\n   * Never settle the promise and the learner cannot play at all: settle it.\n   */\n  onPlayConsumed?: (claim: MediaPlayClaim) => undefined | Promise<MediaPlayGrant | undefined>;\n  /**\n   * Called when a charged play produced no audio — the element errored before\n   * playback advanced past 0.25 s, an expired signed URL being the realistic\n   * cause. Supply it to give the play back, decrementing with a compare-and-set\n   * on `claim.playsUsed`. Omit it and the play stays spent: the SDK will not\n   * decrement a ledger it has no channel to correct.\n   */\n  onPlayRefunded?: (claim: MediaPlayClaim) => void;\n  /**\n   * Position reports, so a refresh resumes the play the learner already paid\n   * for instead of charging them again. Fires on pause, on end (with 0), and at\n   * most once per whole second of playback.\n   *\n   * **This one you MAY throttle** — the granularity you persist is the\n   * granularity of the replay a crash grants. Three seconds is sane; three\n   * minutes is not.\n   */\n  onPosition?: (key: string, seconds: number) => void;\n  /** Translations for the transport chrome. Defaults are English. */\n  strings?: Partial<MediaTransportStrings>;\n}\n\n/**\n * Which slot a recording belongs to, stamped on every call the pager makes.\n *\n * Exactly the shape {@link ActivitySequenceProps.onSubmit} already passes, so\n * one identity travels with the answer and with the take that answer points at\n * — and a consumer writes `slotId` in both places rather than reconciling two\n * spellings of \"which question was this\".\n */\nexport interface SequenceRecordingSlot {\n  /** Identity from `flattenSequence` — stable under shuffling. Store against THIS. */\n  slotId: string;\n  /** Presented position, which moves under shuffling. */\n  index: number;\n  activityId: string;\n}\n\n/**\n * The pager-level half of a read-aloud recording binding: where every take in\n * this sequence is stored, and how a judgement comes back.\n *\n * One prop at both levels, because it is one concept — the media-budget\n * precedent ({@link SequenceMediaBudget} beside {@link MediaBudgetBinding}).\n * The difference is the second argument: a per-slot binding knows which slot it\n * belongs to, so a sequence-level one is told.\n *\n * The SDK records and hands over; it never judges. `assess` is `practice` only\n * and optional — a sequence that only stores takes gets the \"assessment is not\n * available\" notice rather than a throw — and `playbackUrl` is `review` only.\n * A slot whose activity is not a read-aloud never calls any of them.\n */\nexport interface SequenceRecordingBinding {\n  /**\n   * Puts the take in your storage and returns its key. **Required** outside\n   * `review`: without it a learner can speak into a control that submits\n   * nothing, which the component refuses to render. Settle it.\n   */\n  upload(take: RecordedTake, slot: SequenceRecordingSlot): Promise<RecordingRef>;\n  /** Judges the stored take. `practice` only; an exam never assesses on the client. */\n  assess?(ref: RecordingRef, slot: SequenceRecordingSlot): Promise<ReadAloudAssessResult>;\n  /** A playable link to a stored take. `review` only. */\n  playbackUrl?(ref: RecordingRef, slot: SequenceRecordingSlot): Promise<string>;\n}\n"]}
+{"version":3,"sources":["../src/components/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAoOO,SAAS,aACd,QAAA,EACmB;AACnB,EAAA,OAAO,QAAA;AACT;AAoCO,SAAS,qBACd,OAAA,EAC8C;AAC9C,EAAA,OAAO,OAAA;AACT","file":"index.cjs","sourcesContent":["import type {\n  ActivityData,\n  ActivityResult,\n  DeliveryPolicy,\n  InteractionEvent,\n  ItemGroup,\n  ItemOutcome,\n  ItemScoringPolicy,\n  LearnerResponse,\n  MediaPlayClaim,\n  MediaPlayGrant,\n  MediaPlayLedgerEntry,\n  RecordingRef,\n  RedactedActivityData,\n  SequenceEntry,\n  ThemeTokens,\n} from '@intellectif/lk-core';\nimport type { LearnerAi } from '../ai/LkAiProvider.js';\nimport type { RecordedTake } from '../hooks/useSpeechRecorder.js';\nimport type { LkStringsOverride } from '../i18n/strings.js';\nimport type { ReadAloudAssessResult } from './ReadAloud/ReadAloud.js';\n\n/**\n * How an activity is being presented. This is the single switch that decides\n * whether the component may grade, reveal, or submit — the three things a\n * summative exam must take away from the client.\n *\n * - `practice` (default, and the only behaviour before `renderMode` existed):\n *   the component owns the attempt. It\n *   scores locally on submit, reveals correctness and feedback, and calls\n *   `onComplete` with a full {@link ActivityResult}.\n * - `exam`: the component NEVER scores and NEVER reveals correctness. Submit\n *   emits the raw learner response through `onSubmit`; the server grades it.\n *   Safe to render redacted data, because nothing here needs the answer key.\n * - `review`: read-only. Renders the learner's submitted answer, and marks\n *   correctness only from an `outcome` the caller supplies (which the server\n *   computed). Nothing is submittable.\n */\nexport type RenderMode = 'practice' | 'exam' | 'review';\n\n/**\n * Makes the answer-key-bearing parts of an activity optional, so a component\n * can render either full activity data OR a `redact()` projection with the\n * same props. Fields the SDK classifies `answer-key` become optional here;\n * a component in `exam` mode must not read them at all.\n */\nexport type Renderable<TData> = Omit<TData, 'scoringStrategy'> & {\n  scoringStrategy?: unknown;\n  /** Present on a `redact()` projection. */\n  redacted?: true;\n};\n\n/**\n * {@link Renderable} DISTRIBUTED over a union of activity types.\n *\n * This distinction is load-bearing, not cosmetic. `Renderable<T>` is built on\n * `Omit`, and `Omit` does not distribute: `Omit<A | B, K>` collapses to the\n * keys A and B have IN COMMON, so `Renderable<ActivityData>` is a single\n * object type carrying only the fields every activity shares. Narrowing it\n * dies with it — after `if (data.type === 'multiple-choice')` the compiler\n * still refuses `data.options`, because the union it would narrow to no\n * longer exists.\n *\n * The conditional below re-distributes, so `RenderableActivity` is a real\n * union of per-type renderables and `.type` narrows again. Anything that\n * accepts \"some renderable activity, I don't know which\" — a custom renderer,\n * a sequence entry — must use THIS, not `Renderable<ActivityData>`.\n */\nexport type RenderableActivity<TData extends ActivityData = ActivityData> = TData extends unknown\n  ? Renderable<TData>\n  : never;\n\n/**\n * Sanitiser for author-supplied rich text (`questionHtml`, `promptHtml`, and a\n * stimulus's `bodyHtml`). The SDK deliberately ships NO sanitiser — that would\n * add a dependency and, worse, a false promise. Rich text is rendered only when\n * you supply this function; without it the component falls back to the\n * plain-text field, which is always escaped. Fail-safe by construction: the SDK\n * never injects HTML it was not explicitly given a sanitiser for.\n *\n * `FillInTheBlanks.passageHtml` is the one exception, and is **never**\n * rendered: the passage hosts the answer inputs, so it cannot be split at the\n * `{{blank}}` placeholders without voiding the sanitiser. The plain `passage`\n * is always used, and passing `passageHtml` warns in development.\n */\nexport type HtmlSanitizer = (html: string) => string;\n\n/**\n * The prop contract shared by every activity component (Req 3.1). Defined\n * here (React-specific) rather than in lk-core, which is React-free.\n *\n * Controlled / uncontrolled follows the React convention: pass `value` +\n * `onChange` to own the learner's answer (restore an in-progress attempt,\n * autosave a delta, drive a review); pass `defaultValue` to seed an\n * uncontrolled component; pass neither to keep the pre-2.1.0 behaviour, where\n * the component owns the answer outright.\n */\nexport interface ActivityProps<TData extends ActivityData = ActivityData> {\n  /** Activity content. Accepts a `redact()` projection in `exam` mode. */\n  data: RenderableActivity<TData>;\n  /**\n   * Called when the component scored the attempt itself. Only ever fires in\n   * `practice` mode — in `exam` mode the client does not grade, so there is\n   * no `ActivityResult` to give you; use `onSubmit`.\n   */\n  onComplete?: (result: ActivityResult) => void;\n  /**\n   * Called on submit with the raw learner response and no grade. Fires in\n   * every mode, before `onComplete`, so an exam runner can persist the\n   * response and let the server score it.\n   */\n  onSubmit?: (response: LearnerResponse) => void;\n  /** Controlled value: the learner's current response. */\n  value?: LearnerResponse;\n  /** Initial response for an uncontrolled component (ignored when `value` is set). */\n  defaultValue?: LearnerResponse;\n  /**\n   * Mount the component as already submitted — read at mount only, like any\n   * `default*` prop.\n   *\n   * Restoring an attempt without it reopens a question the learner had already\n   * submitted as answerable, so on a summative paper they can change and\n   * re-submit it. `AttemptState.submittedSlotIds` is what this consumes.\n   */\n  defaultSubmitted?: boolean;\n  /** Fires on every change to the learner's response. Required for a controlled component. */\n  onChange?: (response: LearnerResponse) => void;\n  /** Presentation mode. Defaults to `practice`. */\n  renderMode?: RenderMode;\n  /**\n   * Server-computed outcome, used by `review` mode to mark correctness\n   * without the client ever scoring. Ignored in other modes.\n   */\n  outcome?: ItemOutcome;\n  /** Renders author-supplied rich text when provided. See {@link HtmlSanitizer}. */\n  sanitizeHtml?: HtmlSanitizer;\n  /**\n   * Binds this activity's own `data.media` to a play budget the consumer\n   * persists. Usually supplied by `<ActivitySequence mediaBudget={…}>`; pass it\n   * yourself when rendering an activity standalone.\n   */\n  mediaBudget?: MediaBudgetBinding;\n  /** Translations for the audio transport chrome. See {@link MediaTransportStrings}. */\n  mediaStrings?: Partial<MediaTransportStrings>;\n  /**\n   * Overrides the SDK's chrome text for this activity, layered on whatever\n   * `LkIntlProvider` supplies. `mediaStrings` still works and is merged after\n   * this, so an existing 0.8.x call site keeps behaving as it did.\n   */\n  strings?: LkStringsOverride;\n  onInteraction?: (event: InteractionEvent) => void;\n  /**\n   * The host's AI ports for this activity — an explanation after grading, hints\n   * before submit — overriding `LkAiProvider`'s. Leave a port out to switch\n   * that help off. Nothing AI appears in `exam`, and an item whose author\n   * switched a feature off (`data.ai`) never shows it. See {@link LearnerAi}.\n   */\n  ai?: LearnerAi;\n  /**\n   * What the school running this paper lets a learner see: feedback,\n   * solutions, hints, and AI help. Every setting only takes something away\n   * from what the mode shows, and an absent policy takes nothing away. Inside\n   * `<ActivitySequence>` or `<InteractiveVideo>`, the paper's own policy holds\n   * as well, whichever is stricter. See `DeliveryPolicy` in lk-core.\n   */\n  delivery?: DeliveryPolicy | null;\n  /**\n   * How this question is scored when the learner can try again or ask for\n   * hints: how many tries, which counts, what tries and hints cost. Applies in\n   * `practice`, where the component grades — `<MultipleChoice>`,\n   * `<FillInTheBlanks>`, `<GapSelect>` and `<Dictation>`. `<ReadAloud>` takes\n   * the prop and ignores it: its tries are its own `recording.maxTakes`, and\n   * its grade comes from your assessor, not from the component. Inside\n   * `<ActivitySequence>` or `<InteractiveVideo>`, the paper's own policy wins\n   * over this one. See `ItemScoringPolicy` in lk-core.\n   *\n   * With tries, `onComplete` fires after every graded try: `score` and\n   * `passed` are the question's under the policy so far, and `xapiStatement`\n   * records the try just made. A policy `validateItemScoringPolicy` refuses\n   * throws at render.\n   */\n  scoring?: ItemScoringPolicy | null;\n  /** Per-instance token overrides, applied as inline CSS vars on the root. */\n  theme?: Partial<ThemeTokens>;\n  /**\n   * BCP 47 tag stamped as `lang` on this component's root. This is the\n   * INTERFACE language — the SDK's own chrome renders inside that element — so\n   * it should carry the same value you give `<LkIntlProvider locale>`. Passing\n   * a different one re-declares the language of every SDK string in this\n   * subtree without changing the words.\n   *\n   * It is NOT `data.locale`, which labels xAPI statements — and, on a\n   * dictation, places the dictation's own words: `<Dictation>` puts it, and\n   * the direction it names, on its title, hints, marks and solution. Other\n   * authored content in another language belongs on `stimulus.locale`, which\n   * `<StimulusPanel>` puts on the passage alone.\n   */\n  locale?: string;\n  disabled?: boolean;\n}\n\n/**\n * Bridges a server-produced `redact()` projection into the `data` prop.\n *\n * `RedactedActivityData` is deliberately index-signature typed in lk-core — it\n * proves a payload is learner-safe, not what shape it has — so TypeScript\n * cannot know it still carries the public fields a renderer needs. This is the\n * SDK's single, documented crossing of that gap, so an exam runner does not\n * have to write `as unknown as` at every call site:\n *\n * ```tsx\n * <MultipleChoice\n *   data={asRenderable<MultipleChoiceData>(redactedFromServer)}\n *   renderMode=\"exam\"\n *   onSubmit={persist}\n * />\n * ```\n *\n * Safe because `exam` mode reads only public fields; the answer-key fields the\n * type claims are exactly the ones the component is forbidden to touch there.\n *\n * Per-type redacted interfaces (`RedactedMultipleChoiceData`, …) ship from\n * lk-core since 0.6.0, but they are not yet *assignable* to `data`:\n * {@link Renderable} widens `scoringStrategy` and leaves nested answer-key\n * fields (`options[].isCorrect`, `blanks[].acceptedAnswers`) required, so a\n * real redacted payload still needs this bridge. Closing that gap is tracked\n * in the roadmap.\n */\nexport function asRenderable<TData extends ActivityData>(\n  redacted: RedactedActivityData,\n): Renderable<TData> {\n  return redacted as unknown as Renderable<TData>;\n}\n\n/**\n * The same bridge as {@link asRenderable}, for a whole sequence: activities\n * and item groups as a server hands them over, ready for `<ActivitySequence>`.\n *\n * Needed for the same reason and no other. `redactItemGroup` returns\n * `ItemGroup<RedactedActivityData>`, and `RedactedActivityData` is an\n * index-signature type whose fields are all `unknown` — so its `question` is\n * not a `string` and it satisfies no per-type renderable, however the prop is\n * widened. Widening alone cannot fix this; a crossing point is required, and\n * having exactly one keeps `as unknown as` out of consumer code.\n *\n * ```tsx\n * const entries = await fetchExam();            // redacted, server-side\n * <ActivitySequence\n *   activities={asRenderableSequence(entries)}\n *   renderMode=\"exam\"                           // REQUIRED: see below\n *   shuffleSeed={attemptId}\n *   onSubmit={persist}\n * />\n * ```\n *\n * Pass `renderMode=\"exam\"` (or `\"review\"`). Redacted data has no answer key, and\n * almost every built-in activity throws at render in the default `practice`\n * mode rather than fail later: `<MultipleChoice>`, `<FillInTheBlanks>`,\n * `<GapSelect>` and `<Dictation>` because they grade locally, and\n * `<WrittenResponse>` because `practice` still runs its local submit path and\n * emits a practice-mode xAPI statement.\n *\n * `<ReadAloud>` is the exception and renders a projection in every mode: a\n * read-aloud item has no answer key to withhold, so `redact()` removes only the\n * authored feedback and leaves the reading, its language and its bounds — which\n * is everything the component puts on screen. It grades nothing locally either;\n * the grade comes back from whatever the application asked to judge the take.\n */\nexport function asRenderableSequence(\n  entries: readonly (RedactedActivityData | RedactedItemGroupData)[],\n): readonly SequenceEntry<RenderableActivity>[] {\n  return entries as unknown as readonly SequenceEntry<RenderableActivity>[];\n}\n\n/** Structural shape of a `redactItemGroup()` projection, as it arrives from a server. */\ntype RedactedItemGroupData = ItemGroup<RedactedActivityData> & { redacted: true };\n\n/**\n * Every word the SDK's audio transport renders.\n *\n * Words, not characters: the `m:ss / m:ss` clock is digits and punctuation and\n * is formatted by the component, because it reads identically in every locale\n * this SDK targets. The scrubber's SPOKEN value does have a word in it and does\n * have a key ({@link MediaTransportStrings.timeValue}).\n *\n * Supply them to translate it. These are the highest-stakes strings on a\n * listening paper — \"No plays remaining\" decides whether a learner believes\n * they may try again — so shipping them as untranslatable English inside a\n * Spanish panel was not acceptable. Supplying any of them also sets `lang` on\n * the transport chrome, so a screen reader does not read the SDK's own words\n * with the passage's phonetics.\n */\nexport interface MediaTransportStrings {\n  play: string;\n  pause: string;\n  preparing: string;\n  mute: string;\n  unmute: string;\n  volume: string;\n  speed: string;\n  seek: string;\n  /**\n   * Spoken value of the scrubber, e.g. `('1:05', '4:30') => '1:05 of 4:30'`.\n   * Takes ALREADY-FORMATTED `m:ss` strings: a translation should not have to\n   * reimplement the clock to change the word between them.\n   */\n  timeValue: (elapsed: string, duration: string) => string;\n  /** e.g. `(1, 2) => '1 of 2 plays remaining'`. */\n  playsRemaining: (remaining: number, max: number) => string;\n  noPlaysRemaining: string;\n  /** Shown before the LAST play is spent, so a stray press cannot cost it. */\n  lastPlayConfirm: string;\n  lastPlayStart: string;\n  lastPlayCancel: string;\n  seekBlocked: string;\n  rateBlocked: string;\n  playFailed: string;\n}\n\n/**\n * Binds ONE media block to a play budget the consumer persists.\n *\n * The SDK refuses a play; it does not remember one. Everything durable here is\n * the consuming application's — see {@link SequenceMediaBudget.onPlayConsumed}.\n */\nexport interface MediaBudgetBinding {\n  /** From `slotMediaKey(slotId)` / `stimulusMediaKey(slotId)` in lk-core. */\n  key: string;\n  /** Plays already spent, and where playback stood. Read at mount only. */\n  entry?: MediaPlayLedgerEntry;\n  /** Defaults to `renderMode !== 'review'`. An explicit boolean wins either way. */\n  enforced?: boolean;\n  /** Slot context stamped onto the claim and the interaction event. */\n  slotId: string;\n  index: number;\n  activityId?: string;\n  onPlayConsumed?: (claim: MediaPlayClaim) => undefined | Promise<MediaPlayGrant | undefined>;\n  onPlayRefunded?: (claim: MediaPlayClaim) => void;\n  onPosition?: (key: string, seconds: number) => void;\n  /** Translations for the transport chrome. */\n  strings?: Partial<MediaTransportStrings>;\n}\n\n/**\n * The pager-level half of a play budget. One prop, because it is one concept.\n */\nexport interface SequenceMediaBudget {\n  /**\n   * `MediaPlayLedger.entries` goes straight in. An absent key means nothing\n   * spent. Read at mount, like `responses`.\n   */\n  plays?: Readonly<Record<string, MediaPlayLedgerEntry>>;\n  /**\n   * Re-seed token. Change this string and the budgets re-seed from `plays`\n   * WITHOUT remounting the pager — the invigilator path (\"the audio never\n   * started, give her the play back\") that would otherwise cost the learner\n   * their focus, their scroll position and an unsaved answer.\n   */\n  resumeKey?: string;\n  /** Explicit override of the default (`renderMode !== 'review'`). */\n  enforced?: boolean;\n  /**\n   * Called the instant a play is claimed, BEFORE any audio is audible.\n   *\n   * Two tiers, chosen by what you return:\n   *\n   * - **Return nothing (optimistic).** Playback starts immediately and the\n   *   count is only as durable as your write. **Do not debounce this, and do\n   *   not batch it with the answer autosave** — an eight-second debounce is\n   *   exactly long enough to start a third play and hard-reload. A `pagehide`\n   *   beacon is a backstop, not the mechanism. A crash between this call and\n   *   your write landing RETURNS the play to the learner; that is the honest\n   *   description of what you are buying.\n   * - **Return a promise (confirmed).** Playback is held — the button reads\n   *   \"Preparing…\" and is `aria-busy` — until it settles. Resolve with\n   *   `{ playsUsed }` from an ATOMIC server write (`UPDATE … SET plays = plays\n   *   + 1 … RETURNING plays`, or a compare-and-set on\n   *   `claim.previousPlaysUsed`). A resolved count above `maxPlays` refuses the\n   *   play, which is how a second tab is caught: two mounts both seeded at 0\n   *   both claim 1, and only an atomic increment can tell them apart. A\n   *   rejection charges nothing and lets the learner retry. This is the only\n   *   tier in which \"consumed before audible\" is true of storage rather than\n   *   only of memory; use it for summative papers.\n   *\n   * Never settle the promise and the learner cannot play at all: settle it.\n   */\n  onPlayConsumed?: (claim: MediaPlayClaim) => undefined | Promise<MediaPlayGrant | undefined>;\n  /**\n   * Called when a charged play produced no audio — the element errored before\n   * playback advanced past 0.25 s, an expired signed URL being the realistic\n   * cause. Supply it to give the play back, decrementing with a compare-and-set\n   * on `claim.playsUsed`. Omit it and the play stays spent: the SDK will not\n   * decrement a ledger it has no channel to correct.\n   */\n  onPlayRefunded?: (claim: MediaPlayClaim) => void;\n  /**\n   * Position reports, so a refresh resumes the play the learner already paid\n   * for instead of charging them again. Fires on pause, on end (with 0), and at\n   * most once per whole second of playback.\n   *\n   * **This one you MAY throttle** — the granularity you persist is the\n   * granularity of the replay a crash grants. Three seconds is sane; three\n   * minutes is not.\n   */\n  onPosition?: (key: string, seconds: number) => void;\n  /** Translations for the transport chrome. Defaults are English. */\n  strings?: Partial<MediaTransportStrings>;\n}\n\n/**\n * Which slot a recording belongs to, stamped on every call the pager makes.\n *\n * Exactly the shape {@link ActivitySequenceProps.onSubmit} already passes, so\n * one identity travels with the answer and with the take that answer points at\n * — and a consumer writes `slotId` in both places rather than reconciling two\n * spellings of \"which question was this\".\n */\nexport interface SequenceRecordingSlot {\n  /** Identity from `flattenSequence` — stable under shuffling. Store against THIS. */\n  slotId: string;\n  /** Presented position, which moves under shuffling. */\n  index: number;\n  activityId: string;\n}\n\n/**\n * The pager-level half of a read-aloud recording binding: where every take in\n * this sequence is stored, and how a judgement comes back.\n *\n * One prop at both levels, because it is one concept — the media-budget\n * precedent ({@link SequenceMediaBudget} beside {@link MediaBudgetBinding}).\n * The difference is the second argument: a per-slot binding knows which slot it\n * belongs to, so a sequence-level one is told.\n *\n * The SDK records and hands over; it never judges. `assess` is `practice` only\n * and optional — a sequence that only stores takes gets the \"assessment is not\n * available\" notice rather than a throw — and `playbackUrl` is `review` only.\n * A slot whose activity is not a read-aloud never calls any of them.\n */\nexport interface SequenceRecordingBinding {\n  /**\n   * Puts the take in your storage and returns its key. **Required** outside\n   * `review`: without it a learner can speak into a control that submits\n   * nothing, which the component refuses to render. Settle it.\n   */\n  upload(take: RecordedTake, slot: SequenceRecordingSlot): Promise<RecordingRef>;\n  /** Judges the stored take. `practice` only; an exam never assesses on the client. */\n  assess?(ref: RecordingRef, slot: SequenceRecordingSlot): Promise<ReadAloudAssessResult>;\n  /** A playable link to a stored take. `review` only. */\n  playbackUrl?(ref: RecordingRef, slot: SequenceRecordingSlot): Promise<string>;\n}\n"]}

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 export { LearnerAi, LkAiProvider, LkAiProviderProps, useLearnerAi } from './ai/LkAiProvider.cjs';
-export { AiExplanationHelp, AiExplanationInput, AiHelpSituation, AiHintsHelp, AiHintsInput, AiWritingFeedbackHelp, AiWritingFeedbackInput, useAiExplanation, useAiHints, useAiWritingFeedback } from './ai/useAiHelp.cjs';
+export { AiCoachingHelp, AiCoachingInput, AiExplanationHelp, AiExplanationInput, AiHelpSituation, AiHintsHelp, AiHintsInput, AiWritingFeedbackHelp, AiWritingFeedbackInput, useAiCoaching, useAiExplanation, useAiHints, useAiWritingFeedback } from './ai/useAiHelp.cjs';
 export { ActivityPreview, ActivityPreviewProps } from './components/ActivityPreview.cjs';
 export { ActivityRenderer, ActivitySequence, ActivitySequenceProps, SequenceItemOutcome, SequenceQuestion } from './components/ActivitySequence.cjs';
 export { Dictation, DictationProps } from './components/Dictation.cjs';
@@ -10,7 +10,7 @@ export { MultipleChoice, MultipleChoiceProps } from './components/MultipleChoice
 export { PronunciationFeedback, PronunciationFeedbackProps } from './components/PronunciationFeedback.cjs';
 export { ReadAloud } from './components/ReadAloud.cjs';
 export { StimulusPanel, StimulusPanelProps } from './components/StimulusPanel.cjs';
-export { A as ActivityProps, C as CaptionSize, D as DEFAULT_STRINGS, H as HtmlSanitizer, L as LkStrings, a as LkStringsOverride, M as MediaBudgetBinding, b as MediaTransportStrings, R as ReadAloudAssessResult, c as ReadAloudProps, d as RecordingBinding, e as RenderMode, f as Renderable, g as RenderableActivity, S as SequenceMediaBudget, h as SequenceRecordingBinding, i as SequenceRecordingSlot, V as VideoPreferences, j as asRenderable, k as asRenderableSequence, m as mergeStrings } from './types-CO0XLEN6.cjs';
+export { A as ActivityProps, C as CaptionSize, D as DEFAULT_STRINGS, H as HtmlSanitizer, L as LkStrings, a as LkStringsOverride, M as MediaBudgetBinding, b as MediaTransportStrings, R as ReadAloudAssessResult, c as ReadAloudProps, d as RecordingBinding, e as RenderMode, f as Renderable, g as RenderableActivity, S as SequenceMediaBudget, h as SequenceRecordingBinding, i as SequenceRecordingSlot, V as VideoPreferences, j as asRenderable, k as asRenderableSequence, m as mergeStrings } from './types-CJgZWtl4.cjs';
 export { WrittenResponse } from './components/WrittenResponse.cjs';
 export { ActivityState, UseActivityStateResult, useActivityState } from './hooks/useActivityState.cjs';
 export { CAPTURE_PROCESSOR_SOURCE, SpeechRecorder, SpeechRecorderOptions, useSpeechRecorder } from './hooks/useSpeechRecorder.cjs';
@@ -18,7 +18,7 @@ export { UseXAPIResult, useXAPI } from './hooks/useXAPI.cjs';
 export { LkDirection, LkIntlProvider, LkIntlProviderProps, directionForLocale, useLkDirection, useLkStrings } from './i18n/LkIntlProvider.cjs';
 export { TailwindThemeExtension, ThemeProvider, ThemeProviderProps, createTailwindTheme, darkTheme, defaultTheme, useTheme } from './theme/ThemeProvider.cjs';
 export { R as RecordedTake, S as SpeechRecorderError, a as SpeechRecorderStatus } from './machine-CuwKqWXC.cjs';
-export { W as WrittenResponseProps, a as WrittenResponseSubmission } from './WrittenResponse-D2K1VW_V.cjs';
+export { W as WrittenResponseProps, a as WrittenResponseSubmission } from './WrittenResponse-BpL9p2Hn.cjs';
 import '@intellectif/lk-core';
 import 'react';
 import 'react/jsx-runtime';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { LearnerAi, LkAiProvider, LkAiProviderProps, useLearnerAi } from './ai/LkAiProvider.js';
-export { AiExplanationHelp, AiExplanationInput, AiHelpSituation, AiHintsHelp, AiHintsInput, AiWritingFeedbackHelp, AiWritingFeedbackInput, useAiExplanation, useAiHints, useAiWritingFeedback } from './ai/useAiHelp.js';
+export { AiCoachingHelp, AiCoachingInput, AiExplanationHelp, AiExplanationInput, AiHelpSituation, AiHintsHelp, AiHintsInput, AiWritingFeedbackHelp, AiWritingFeedbackInput, useAiCoaching, useAiExplanation, useAiHints, useAiWritingFeedback } from './ai/useAiHelp.js';
 export { ActivityPreview, ActivityPreviewProps } from './components/ActivityPreview.js';
 export { ActivityRenderer, ActivitySequence, ActivitySequenceProps, SequenceItemOutcome, SequenceQuestion } from './components/ActivitySequence.js';
 export { Dictation, DictationProps } from './components/Dictation.js';
@@ -10,7 +10,7 @@ export { MultipleChoice, MultipleChoiceProps } from './components/MultipleChoice
 export { PronunciationFeedback, PronunciationFeedbackProps } from './components/PronunciationFeedback.js';
 export { ReadAloud } from './components/ReadAloud.js';
 export { StimulusPanel, StimulusPanelProps } from './components/StimulusPanel.js';
-export { A as ActivityProps, C as CaptionSize, D as DEFAULT_STRINGS, H as HtmlSanitizer, L as LkStrings, a as LkStringsOverride, M as MediaBudgetBinding, b as MediaTransportStrings, R as ReadAloudAssessResult, c as ReadAloudProps, d as RecordingBinding, e as RenderMode, f as Renderable, g as RenderableActivity, S as SequenceMediaBudget, h as SequenceRecordingBinding, i as SequenceRecordingSlot, V as VideoPreferences, j as asRenderable, k as asRenderableSequence, m as mergeStrings } from './types-CrtIcRcK.js';
+export { A as ActivityProps, C as CaptionSize, D as DEFAULT_STRINGS, H as HtmlSanitizer, L as LkStrings, a as LkStringsOverride, M as MediaBudgetBinding, b as MediaTransportStrings, R as ReadAloudAssessResult, c as ReadAloudProps, d as RecordingBinding, e as RenderMode, f as Renderable, g as RenderableActivity, S as SequenceMediaBudget, h as SequenceRecordingBinding, i as SequenceRecordingSlot, V as VideoPreferences, j as asRenderable, k as asRenderableSequence, m as mergeStrings } from './types-C4IsUQsK.js';
 export { WrittenResponse } from './components/WrittenResponse.js';
 export { ActivityState, UseActivityStateResult, useActivityState } from './hooks/useActivityState.js';
 export { CAPTURE_PROCESSOR_SOURCE, SpeechRecorder, SpeechRecorderOptions, useSpeechRecorder } from './hooks/useSpeechRecorder.js';
@@ -18,7 +18,7 @@ export { UseXAPIResult, useXAPI } from './hooks/useXAPI.js';
 export { LkDirection, LkIntlProvider, LkIntlProviderProps, directionForLocale, useLkDirection, useLkStrings } from './i18n/LkIntlProvider.js';
 export { TailwindThemeExtension, ThemeProvider, ThemeProviderProps, createTailwindTheme, darkTheme, defaultTheme, useTheme } from './theme/ThemeProvider.js';
 export { R as RecordedTake, S as SpeechRecorderError, a as SpeechRecorderStatus } from './machine-CuwKqWXC.js';
-export { W as WrittenResponseProps, a as WrittenResponseSubmission } from './WrittenResponse-CgRrjM4S.js';
+export { W as WrittenResponseProps, a as WrittenResponseSubmission } from './WrittenResponse-B7A5gHMj.js';
 import '@intellectif/lk-core';
 import 'react';
 import 'react/jsx-runtime';

package/dist/index.js

@@ -1,29 +1,27 @@
 'use client';
 export { useXAPI } from './chunk-2TW6WLBC.js';
 export { ThemeProvider, createTailwindTheme, darkTheme, defaultTheme, useTheme } from './chunk-UHKZXOXD.js';
-export { InteractiveVideo, resolveCaptionTracks } from './chunk-JMEZYYCE.js';
-export { ActivityPreview } from './chunk-TGTP5DKF.js';
-export { ActivitySequence } from './chunk-SPSKDNEE.js';
-export { StimulusPanel } from './chunk-HZIT24BK.js';
-export { WrittenResponse } from './chunk-DPNCCWOV.js';
-export { MultipleChoice } from './chunk-O7MINPKZ.js';
-export { FillInTheBlanks } from './chunk-KI6DJ5ZF.js';
-export { GapSelect } from './chunk-ERV666AR.js';
-export { Dictation } from './chunk-6GQLCCGN.js';
-import './chunk-U5VFJVQ2.js';
-export { useAiExplanation, useAiHints, useAiWritingFeedback } from './chunk-CXIP7ERK.js';
-export { LkAiProvider, useLearnerAi } from './chunk-RX3A6KIY.js';
-export { ReadAloud } from './chunk-4MXECBZT.js';
-export { PronunciationFeedback } from './chunk-2OP5YHRR.js';
+export { InteractiveVideo, resolveCaptionTracks } from './chunk-PWHECW6N.js';
+export { ActivityPreview } from './chunk-7NFY3M3W.js';
+export { ActivitySequence } from './chunk-G6PXJ2SA.js';
+export { StimulusPanel } from './chunk-4ZZWZSWI.js';
+export { WrittenResponse } from './chunk-FKGMSOJF.js';
+export { MultipleChoice } from './chunk-C7QZE5BI.js';
+export { FillInTheBlanks } from './chunk-TCDJY3H6.js';
+export { GapSelect } from './chunk-ABJJ3LII.js';
+export { Dictation } from './chunk-RBS5A2DF.js';
+import './chunk-FDQR4GAZ.js';
+export { ReadAloud } from './chunk-DC4CQCK5.js';
+export { PronunciationFeedback } from './chunk-XO5R73Y4.js';
 export { CAPTURE_PROCESSOR_SOURCE, useSpeechRecorder } from './chunk-MCO52PV5.js';
 import './chunk-YORQQXGO.js';
-import './chunk-XYJBRKBZ.js';
-import './chunk-U4KTOH7C.js';
-import './chunk-E4UF4XZM.js';
-import './chunk-DXFCYNST.js';
-import './chunk-HYOUMTPW.js';
+import './chunk-ORT3KLGI.js';
+import './chunk-7SB2MJA4.js';
+export { useAiCoaching, useAiExplanation, useAiHints, useAiWritingFeedback } from './chunk-MXNC5UNO.js';
+import './chunk-TS7J6DTY.js';
 export { useActivityState } from './chunk-6N43WDVG.js';
-export { DEFAULT_STRINGS, LkIntlProvider, directionForLocale, mergeStrings, useLkDirection, useLkStrings } from './chunk-C4PSJ3ZC.js';
+export { DEFAULT_STRINGS, LkIntlProvider, directionForLocale, mergeStrings, useLkDirection, useLkStrings } from './chunk-HNLRVRQR.js';
+export { LkAiProvider, useLearnerAi } from './chunk-ZPI6Q42R.js';
 
 // src/components/types.ts
 function asRenderable(redacted) {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/components/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAoOO,SAAS,aACd,QAAA,EACmB;AACnB,EAAA,OAAO,QAAA;AACT;AAoCO,SAAS,qBACd,OAAA,EAC8C;AAC9C,EAAA,OAAO,OAAA;AACT","file":"index.js","sourcesContent":["import type {\n  ActivityData,\n  ActivityResult,\n  DeliveryPolicy,\n  InteractionEvent,\n  ItemGroup,\n  ItemOutcome,\n  ItemScoringPolicy,\n  LearnerResponse,\n  MediaPlayClaim,\n  MediaPlayGrant,\n  MediaPlayLedgerEntry,\n  RecordingRef,\n  RedactedActivityData,\n  SequenceEntry,\n  ThemeTokens,\n} from '@intellectif/lk-core';\nimport type { LearnerAi } from '../ai/LkAiProvider.js';\nimport type { RecordedTake } from '../hooks/useSpeechRecorder.js';\nimport type { LkStringsOverride } from '../i18n/strings.js';\nimport type { ReadAloudAssessResult } from './ReadAloud/ReadAloud.js';\n\n/**\n * How an activity is being presented. This is the single switch that decides\n * whether the component may grade, reveal, or submit — the three things a\n * summative exam must take away from the client.\n *\n * - `practice` (default, and the only behaviour before `renderMode` existed):\n *   the component owns the attempt. It\n *   scores locally on submit, reveals correctness and feedback, and calls\n *   `onComplete` with a full {@link ActivityResult}.\n * - `exam`: the component NEVER scores and NEVER reveals correctness. Submit\n *   emits the raw learner response through `onSubmit`; the server grades it.\n *   Safe to render redacted data, because nothing here needs the answer key.\n * - `review`: read-only. Renders the learner's submitted answer, and marks\n *   correctness only from an `outcome` the caller supplies (which the server\n *   computed). Nothing is submittable.\n */\nexport type RenderMode = 'practice' | 'exam' | 'review';\n\n/**\n * Makes the answer-key-bearing parts of an activity optional, so a component\n * can render either full activity data OR a `redact()` projection with the\n * same props. Fields the SDK classifies `answer-key` become optional here;\n * a component in `exam` mode must not read them at all.\n */\nexport type Renderable<TData> = Omit<TData, 'scoringStrategy'> & {\n  scoringStrategy?: unknown;\n  /** Present on a `redact()` projection. */\n  redacted?: true;\n};\n\n/**\n * {@link Renderable} DISTRIBUTED over a union of activity types.\n *\n * This distinction is load-bearing, not cosmetic. `Renderable<T>` is built on\n * `Omit`, and `Omit` does not distribute: `Omit<A | B, K>` collapses to the\n * keys A and B have IN COMMON, so `Renderable<ActivityData>` is a single\n * object type carrying only the fields every activity shares. Narrowing it\n * dies with it — after `if (data.type === 'multiple-choice')` the compiler\n * still refuses `data.options`, because the union it would narrow to no\n * longer exists.\n *\n * The conditional below re-distributes, so `RenderableActivity` is a real\n * union of per-type renderables and `.type` narrows again. Anything that\n * accepts \"some renderable activity, I don't know which\" — a custom renderer,\n * a sequence entry — must use THIS, not `Renderable<ActivityData>`.\n */\nexport type RenderableActivity<TData extends ActivityData = ActivityData> = TData extends unknown\n  ? Renderable<TData>\n  : never;\n\n/**\n * Sanitiser for author-supplied rich text (`questionHtml`, `promptHtml`, and a\n * stimulus's `bodyHtml`). The SDK deliberately ships NO sanitiser — that would\n * add a dependency and, worse, a false promise. Rich text is rendered only when\n * you supply this function; without it the component falls back to the\n * plain-text field, which is always escaped. Fail-safe by construction: the SDK\n * never injects HTML it was not explicitly given a sanitiser for.\n *\n * `FillInTheBlanks.passageHtml` is the one exception, and is **never**\n * rendered: the passage hosts the answer inputs, so it cannot be split at the\n * `{{blank}}` placeholders without voiding the sanitiser. The plain `passage`\n * is always used, and passing `passageHtml` warns in development.\n */\nexport type HtmlSanitizer = (html: string) => string;\n\n/**\n * The prop contract shared by every activity component (Req 3.1). Defined\n * here (React-specific) rather than in lk-core, which is React-free.\n *\n * Controlled / uncontrolled follows the React convention: pass `value` +\n * `onChange` to own the learner's answer (restore an in-progress attempt,\n * autosave a delta, drive a review); pass `defaultValue` to seed an\n * uncontrolled component; pass neither to keep the pre-2.1.0 behaviour, where\n * the component owns the answer outright.\n */\nexport interface ActivityProps<TData extends ActivityData = ActivityData> {\n  /** Activity content. Accepts a `redact()` projection in `exam` mode. */\n  data: RenderableActivity<TData>;\n  /**\n   * Called when the component scored the attempt itself. Only ever fires in\n   * `practice` mode — in `exam` mode the client does not grade, so there is\n   * no `ActivityResult` to give you; use `onSubmit`.\n   */\n  onComplete?: (result: ActivityResult) => void;\n  /**\n   * Called on submit with the raw learner response and no grade. Fires in\n   * every mode, before `onComplete`, so an exam runner can persist the\n   * response and let the server score it.\n   */\n  onSubmit?: (response: LearnerResponse) => void;\n  /** Controlled value: the learner's current response. */\n  value?: LearnerResponse;\n  /** Initial response for an uncontrolled component (ignored when `value` is set). */\n  defaultValue?: LearnerResponse;\n  /**\n   * Mount the component as already submitted — read at mount only, like any\n   * `default*` prop.\n   *\n   * Restoring an attempt without it reopens a question the learner had already\n   * submitted as answerable, so on a summative paper they can change and\n   * re-submit it. `AttemptState.submittedSlotIds` is what this consumes.\n   */\n  defaultSubmitted?: boolean;\n  /** Fires on every change to the learner's response. Required for a controlled component. */\n  onChange?: (response: LearnerResponse) => void;\n  /** Presentation mode. Defaults to `practice`. */\n  renderMode?: RenderMode;\n  /**\n   * Server-computed outcome, used by `review` mode to mark correctness\n   * without the client ever scoring. Ignored in other modes.\n   */\n  outcome?: ItemOutcome;\n  /** Renders author-supplied rich text when provided. See {@link HtmlSanitizer}. */\n  sanitizeHtml?: HtmlSanitizer;\n  /**\n   * Binds this activity's own `data.media` to a play budget the consumer\n   * persists. Usually supplied by `<ActivitySequence mediaBudget={…}>`; pass it\n   * yourself when rendering an activity standalone.\n   */\n  mediaBudget?: MediaBudgetBinding;\n  /** Translations for the audio transport chrome. See {@link MediaTransportStrings}. */\n  mediaStrings?: Partial<MediaTransportStrings>;\n  /**\n   * Overrides the SDK's chrome text for this activity, layered on whatever\n   * `LkIntlProvider` supplies. `mediaStrings` still works and is merged after\n   * this, so an existing 0.8.x call site keeps behaving as it did.\n   */\n  strings?: LkStringsOverride;\n  onInteraction?: (event: InteractionEvent) => void;\n  /**\n   * The host's AI ports for this activity — an explanation after grading, hints\n   * before submit — overriding `LkAiProvider`'s. Leave a port out to switch\n   * that help off. Nothing AI appears in `exam`, and an item whose author\n   * switched a feature off (`data.ai`) never shows it. See {@link LearnerAi}.\n   */\n  ai?: LearnerAi;\n  /**\n   * What the school running this paper lets a learner see: feedback,\n   * solutions, hints, and AI help. Every setting only takes something away\n   * from what the mode shows, and an absent policy takes nothing away. Inside\n   * `<ActivitySequence>` or `<InteractiveVideo>`, the paper's own policy holds\n   * as well, whichever is stricter. See `DeliveryPolicy` in lk-core.\n   */\n  delivery?: DeliveryPolicy | null;\n  /**\n   * How this question is scored when the learner can try again or ask for\n   * hints: how many tries, which counts, what tries and hints cost. Applies in\n   * `practice`, where the component grades — `<MultipleChoice>`,\n   * `<FillInTheBlanks>`, `<GapSelect>` and `<Dictation>`. `<ReadAloud>` takes\n   * the prop and ignores it: its tries are its own `recording.maxTakes`, and\n   * its grade comes from your assessor, not from the component. Inside\n   * `<ActivitySequence>` or `<InteractiveVideo>`, the paper's own policy wins\n   * over this one. See `ItemScoringPolicy` in lk-core.\n   *\n   * With tries, `onComplete` fires after every graded try: `score` and\n   * `passed` are the question's under the policy so far, and `xapiStatement`\n   * records the try just made. A policy `validateItemScoringPolicy` refuses\n   * throws at render.\n   */\n  scoring?: ItemScoringPolicy | null;\n  /** Per-instance token overrides, applied as inline CSS vars on the root. */\n  theme?: Partial<ThemeTokens>;\n  /**\n   * BCP 47 tag stamped as `lang` on this component's root. This is the\n   * INTERFACE language — the SDK's own chrome renders inside that element — so\n   * it should carry the same value you give `<LkIntlProvider locale>`. Passing\n   * a different one re-declares the language of every SDK string in this\n   * subtree without changing the words.\n   *\n   * It is NOT `data.locale`, which labels xAPI statements — and, on a\n   * dictation, places the dictation's own words: `<Dictation>` puts it, and\n   * the direction it names, on its title, hints, marks and solution. Other\n   * authored content in another language belongs on `stimulus.locale`, which\n   * `<StimulusPanel>` puts on the passage alone.\n   */\n  locale?: string;\n  disabled?: boolean;\n}\n\n/**\n * Bridges a server-produced `redact()` projection into the `data` prop.\n *\n * `RedactedActivityData` is deliberately index-signature typed in lk-core — it\n * proves a payload is learner-safe, not what shape it has — so TypeScript\n * cannot know it still carries the public fields a renderer needs. This is the\n * SDK's single, documented crossing of that gap, so an exam runner does not\n * have to write `as unknown as` at every call site:\n *\n * ```tsx\n * <MultipleChoice\n *   data={asRenderable<MultipleChoiceData>(redactedFromServer)}\n *   renderMode=\"exam\"\n *   onSubmit={persist}\n * />\n * ```\n *\n * Safe because `exam` mode reads only public fields; the answer-key fields the\n * type claims are exactly the ones the component is forbidden to touch there.\n *\n * Per-type redacted interfaces (`RedactedMultipleChoiceData`, …) ship from\n * lk-core since 0.6.0, but they are not yet *assignable* to `data`:\n * {@link Renderable} widens `scoringStrategy` and leaves nested answer-key\n * fields (`options[].isCorrect`, `blanks[].acceptedAnswers`) required, so a\n * real redacted payload still needs this bridge. Closing that gap is tracked\n * in the roadmap.\n */\nexport function asRenderable<TData extends ActivityData>(\n  redacted: RedactedActivityData,\n): Renderable<TData> {\n  return redacted as unknown as Renderable<TData>;\n}\n\n/**\n * The same bridge as {@link asRenderable}, for a whole sequence: activities\n * and item groups as a server hands them over, ready for `<ActivitySequence>`.\n *\n * Needed for the same reason and no other. `redactItemGroup` returns\n * `ItemGroup<RedactedActivityData>`, and `RedactedActivityData` is an\n * index-signature type whose fields are all `unknown` — so its `question` is\n * not a `string` and it satisfies no per-type renderable, however the prop is\n * widened. Widening alone cannot fix this; a crossing point is required, and\n * having exactly one keeps `as unknown as` out of consumer code.\n *\n * ```tsx\n * const entries = await fetchExam();            // redacted, server-side\n * <ActivitySequence\n *   activities={asRenderableSequence(entries)}\n *   renderMode=\"exam\"                           // REQUIRED: see below\n *   shuffleSeed={attemptId}\n *   onSubmit={persist}\n * />\n * ```\n *\n * Pass `renderMode=\"exam\"` (or `\"review\"`). Redacted data has no answer key, and\n * almost every built-in activity throws at render in the default `practice`\n * mode rather than fail later: `<MultipleChoice>`, `<FillInTheBlanks>`,\n * `<GapSelect>` and `<Dictation>` because they grade locally, and\n * `<WrittenResponse>` because `practice` still runs its local submit path and\n * emits a practice-mode xAPI statement.\n *\n * `<ReadAloud>` is the exception and renders a projection in every mode: a\n * read-aloud item has no answer key to withhold, so `redact()` removes only the\n * authored feedback and leaves the reading, its language and its bounds — which\n * is everything the component puts on screen. It grades nothing locally either;\n * the grade comes back from whatever the application asked to judge the take.\n */\nexport function asRenderableSequence(\n  entries: readonly (RedactedActivityData | RedactedItemGroupData)[],\n): readonly SequenceEntry<RenderableActivity>[] {\n  return entries as unknown as readonly SequenceEntry<RenderableActivity>[];\n}\n\n/** Structural shape of a `redactItemGroup()` projection, as it arrives from a server. */\ntype RedactedItemGroupData = ItemGroup<RedactedActivityData> & { redacted: true };\n\n/**\n * Every word the SDK's audio transport renders.\n *\n * Words, not characters: the `m:ss / m:ss` clock is digits and punctuation and\n * is formatted by the component, because it reads identically in every locale\n * this SDK targets. The scrubber's SPOKEN value does have a word in it and does\n * have a key ({@link MediaTransportStrings.timeValue}).\n *\n * Supply them to translate it. These are the highest-stakes strings on a\n * listening paper — \"No plays remaining\" decides whether a learner believes\n * they may try again — so shipping them as untranslatable English inside a\n * Spanish panel was not acceptable. Supplying any of them also sets `lang` on\n * the transport chrome, so a screen reader does not read the SDK's own words\n * with the passage's phonetics.\n */\nexport interface MediaTransportStrings {\n  play: string;\n  pause: string;\n  preparing: string;\n  mute: string;\n  unmute: string;\n  volume: string;\n  speed: string;\n  seek: string;\n  /**\n   * Spoken value of the scrubber, e.g. `('1:05', '4:30') => '1:05 of 4:30'`.\n   * Takes ALREADY-FORMATTED `m:ss` strings: a translation should not have to\n   * reimplement the clock to change the word between them.\n   */\n  timeValue: (elapsed: string, duration: string) => string;\n  /** e.g. `(1, 2) => '1 of 2 plays remaining'`. */\n  playsRemaining: (remaining: number, max: number) => string;\n  noPlaysRemaining: string;\n  /** Shown before the LAST play is spent, so a stray press cannot cost it. */\n  lastPlayConfirm: string;\n  lastPlayStart: string;\n  lastPlayCancel: string;\n  seekBlocked: string;\n  rateBlocked: string;\n  playFailed: string;\n}\n\n/**\n * Binds ONE media block to a play budget the consumer persists.\n *\n * The SDK refuses a play; it does not remember one. Everything durable here is\n * the consuming application's — see {@link SequenceMediaBudget.onPlayConsumed}.\n */\nexport interface MediaBudgetBinding {\n  /** From `slotMediaKey(slotId)` / `stimulusMediaKey(slotId)` in lk-core. */\n  key: string;\n  /** Plays already spent, and where playback stood. Read at mount only. */\n  entry?: MediaPlayLedgerEntry;\n  /** Defaults to `renderMode !== 'review'`. An explicit boolean wins either way. */\n  enforced?: boolean;\n  /** Slot context stamped onto the claim and the interaction event. */\n  slotId: string;\n  index: number;\n  activityId?: string;\n  onPlayConsumed?: (claim: MediaPlayClaim) => undefined | Promise<MediaPlayGrant | undefined>;\n  onPlayRefunded?: (claim: MediaPlayClaim) => void;\n  onPosition?: (key: string, seconds: number) => void;\n  /** Translations for the transport chrome. */\n  strings?: Partial<MediaTransportStrings>;\n}\n\n/**\n * The pager-level half of a play budget. One prop, because it is one concept.\n */\nexport interface SequenceMediaBudget {\n  /**\n   * `MediaPlayLedger.entries` goes straight in. An absent key means nothing\n   * spent. Read at mount, like `responses`.\n   */\n  plays?: Readonly<Record<string, MediaPlayLedgerEntry>>;\n  /**\n   * Re-seed token. Change this string and the budgets re-seed from `plays`\n   * WITHOUT remounting the pager — the invigilator path (\"the audio never\n   * started, give her the play back\") that would otherwise cost the learner\n   * their focus, their scroll position and an unsaved answer.\n   */\n  resumeKey?: string;\n  /** Explicit override of the default (`renderMode !== 'review'`). */\n  enforced?: boolean;\n  /**\n   * Called the instant a play is claimed, BEFORE any audio is audible.\n   *\n   * Two tiers, chosen by what you return:\n   *\n   * - **Return nothing (optimistic).** Playback starts immediately and the\n   *   count is only as durable as your write. **Do not debounce this, and do\n   *   not batch it with the answer autosave** — an eight-second debounce is\n   *   exactly long enough to start a third play and hard-reload. A `pagehide`\n   *   beacon is a backstop, not the mechanism. A crash between this call and\n   *   your write landing RETURNS the play to the learner; that is the honest\n   *   description of what you are buying.\n   * - **Return a promise (confirmed).** Playback is held — the button reads\n   *   \"Preparing…\" and is `aria-busy` — until it settles. Resolve with\n   *   `{ playsUsed }` from an ATOMIC server write (`UPDATE … SET plays = plays\n   *   + 1 … RETURNING plays`, or a compare-and-set on\n   *   `claim.previousPlaysUsed`). A resolved count above `maxPlays` refuses the\n   *   play, which is how a second tab is caught: two mounts both seeded at 0\n   *   both claim 1, and only an atomic increment can tell them apart. A\n   *   rejection charges nothing and lets the learner retry. This is the only\n   *   tier in which \"consumed before audible\" is true of storage rather than\n   *   only of memory; use it for summative papers.\n   *\n   * Never settle the promise and the learner cannot play at all: settle it.\n   */\n  onPlayConsumed?: (claim: MediaPlayClaim) => undefined | Promise<MediaPlayGrant | undefined>;\n  /**\n   * Called when a charged play produced no audio — the element errored before\n   * playback advanced past 0.25 s, an expired signed URL being the realistic\n   * cause. Supply it to give the play back, decrementing with a compare-and-set\n   * on `claim.playsUsed`. Omit it and the play stays spent: the SDK will not\n   * decrement a ledger it has no channel to correct.\n   */\n  onPlayRefunded?: (claim: MediaPlayClaim) => void;\n  /**\n   * Position reports, so a refresh resumes the play the learner already paid\n   * for instead of charging them again. Fires on pause, on end (with 0), and at\n   * most once per whole second of playback.\n   *\n   * **This one you MAY throttle** — the granularity you persist is the\n   * granularity of the replay a crash grants. Three seconds is sane; three\n   * minutes is not.\n   */\n  onPosition?: (key: string, seconds: number) => void;\n  /** Translations for the transport chrome. Defaults are English. */\n  strings?: Partial<MediaTransportStrings>;\n}\n\n/**\n * Which slot a recording belongs to, stamped on every call the pager makes.\n *\n * Exactly the shape {@link ActivitySequenceProps.onSubmit} already passes, so\n * one identity travels with the answer and with the take that answer points at\n * — and a consumer writes `slotId` in both places rather than reconciling two\n * spellings of \"which question was this\".\n */\nexport interface SequenceRecordingSlot {\n  /** Identity from `flattenSequence` — stable under shuffling. Store against THIS. */\n  slotId: string;\n  /** Presented position, which moves under shuffling. */\n  index: number;\n  activityId: string;\n}\n\n/**\n * The pager-level half of a read-aloud recording binding: where every take in\n * this sequence is stored, and how a judgement comes back.\n *\n * One prop at both levels, because it is one concept — the media-budget\n * precedent ({@link SequenceMediaBudget} beside {@link MediaBudgetBinding}).\n * The difference is the second argument: a per-slot binding knows which slot it\n * belongs to, so a sequence-level one is told.\n *\n * The SDK records and hands over; it never judges. `assess` is `practice` only\n * and optional — a sequence that only stores takes gets the \"assessment is not\n * available\" notice rather than a throw — and `playbackUrl` is `review` only.\n * A slot whose activity is not a read-aloud never calls any of them.\n */\nexport interface SequenceRecordingBinding {\n  /**\n   * Puts the take in your storage and returns its key. **Required** outside\n   * `review`: without it a learner can speak into a control that submits\n   * nothing, which the component refuses to render. Settle it.\n   */\n  upload(take: RecordedTake, slot: SequenceRecordingSlot): Promise<RecordingRef>;\n  /** Judges the stored take. `practice` only; an exam never assesses on the client. */\n  assess?(ref: RecordingRef, slot: SequenceRecordingSlot): Promise<ReadAloudAssessResult>;\n  /** A playable link to a stored take. `review` only. */\n  playbackUrl?(ref: RecordingRef, slot: SequenceRecordingSlot): Promise<string>;\n}\n"]}
+{"version":3,"sources":["../src/components/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAoOO,SAAS,aACd,QAAA,EACmB;AACnB,EAAA,OAAO,QAAA;AACT;AAoCO,SAAS,qBACd,OAAA,EAC8C;AAC9C,EAAA,OAAO,OAAA;AACT","file":"index.js","sourcesContent":["import type {\n  ActivityData,\n  ActivityResult,\n  DeliveryPolicy,\n  InteractionEvent,\n  ItemGroup,\n  ItemOutcome,\n  ItemScoringPolicy,\n  LearnerResponse,\n  MediaPlayClaim,\n  MediaPlayGrant,\n  MediaPlayLedgerEntry,\n  RecordingRef,\n  RedactedActivityData,\n  SequenceEntry,\n  ThemeTokens,\n} from '@intellectif/lk-core';\nimport type { LearnerAi } from '../ai/LkAiProvider.js';\nimport type { RecordedTake } from '../hooks/useSpeechRecorder.js';\nimport type { LkStringsOverride } from '../i18n/strings.js';\nimport type { ReadAloudAssessResult } from './ReadAloud/ReadAloud.js';\n\n/**\n * How an activity is being presented. This is the single switch that decides\n * whether the component may grade, reveal, or submit — the three things a\n * summative exam must take away from the client.\n *\n * - `practice` (default, and the only behaviour before `renderMode` existed):\n *   the component owns the attempt. It\n *   scores locally on submit, reveals correctness and feedback, and calls\n *   `onComplete` with a full {@link ActivityResult}.\n * - `exam`: the component NEVER scores and NEVER reveals correctness. Submit\n *   emits the raw learner response through `onSubmit`; the server grades it.\n *   Safe to render redacted data, because nothing here needs the answer key.\n * - `review`: read-only. Renders the learner's submitted answer, and marks\n *   correctness only from an `outcome` the caller supplies (which the server\n *   computed). Nothing is submittable.\n */\nexport type RenderMode = 'practice' | 'exam' | 'review';\n\n/**\n * Makes the answer-key-bearing parts of an activity optional, so a component\n * can render either full activity data OR a `redact()` projection with the\n * same props. Fields the SDK classifies `answer-key` become optional here;\n * a component in `exam` mode must not read them at all.\n */\nexport type Renderable<TData> = Omit<TData, 'scoringStrategy'> & {\n  scoringStrategy?: unknown;\n  /** Present on a `redact()` projection. */\n  redacted?: true;\n};\n\n/**\n * {@link Renderable} DISTRIBUTED over a union of activity types.\n *\n * This distinction is load-bearing, not cosmetic. `Renderable<T>` is built on\n * `Omit`, and `Omit` does not distribute: `Omit<A | B, K>` collapses to the\n * keys A and B have IN COMMON, so `Renderable<ActivityData>` is a single\n * object type carrying only the fields every activity shares. Narrowing it\n * dies with it — after `if (data.type === 'multiple-choice')` the compiler\n * still refuses `data.options`, because the union it would narrow to no\n * longer exists.\n *\n * The conditional below re-distributes, so `RenderableActivity` is a real\n * union of per-type renderables and `.type` narrows again. Anything that\n * accepts \"some renderable activity, I don't know which\" — a custom renderer,\n * a sequence entry — must use THIS, not `Renderable<ActivityData>`.\n */\nexport type RenderableActivity<TData extends ActivityData = ActivityData> = TData extends unknown\n  ? Renderable<TData>\n  : never;\n\n/**\n * Sanitiser for author-supplied rich text (`questionHtml`, `promptHtml`, and a\n * stimulus's `bodyHtml`). The SDK deliberately ships NO sanitiser — that would\n * add a dependency and, worse, a false promise. Rich text is rendered only when\n * you supply this function; without it the component falls back to the\n * plain-text field, which is always escaped. Fail-safe by construction: the SDK\n * never injects HTML it was not explicitly given a sanitiser for.\n *\n * `FillInTheBlanks.passageHtml` is the one exception, and is **never**\n * rendered: the passage hosts the answer inputs, so it cannot be split at the\n * `{{blank}}` placeholders without voiding the sanitiser. The plain `passage`\n * is always used, and passing `passageHtml` warns in development.\n */\nexport type HtmlSanitizer = (html: string) => string;\n\n/**\n * The prop contract shared by every activity component (Req 3.1). Defined\n * here (React-specific) rather than in lk-core, which is React-free.\n *\n * Controlled / uncontrolled follows the React convention: pass `value` +\n * `onChange` to own the learner's answer (restore an in-progress attempt,\n * autosave a delta, drive a review); pass `defaultValue` to seed an\n * uncontrolled component; pass neither to keep the pre-2.1.0 behaviour, where\n * the component owns the answer outright.\n */\nexport interface ActivityProps<TData extends ActivityData = ActivityData> {\n  /** Activity content. Accepts a `redact()` projection in `exam` mode. */\n  data: RenderableActivity<TData>;\n  /**\n   * Called when the component scored the attempt itself. Only ever fires in\n   * `practice` mode — in `exam` mode the client does not grade, so there is\n   * no `ActivityResult` to give you; use `onSubmit`.\n   */\n  onComplete?: (result: ActivityResult) => void;\n  /**\n   * Called on submit with the raw learner response and no grade. Fires in\n   * every mode, before `onComplete`, so an exam runner can persist the\n   * response and let the server score it.\n   */\n  onSubmit?: (response: LearnerResponse) => void;\n  /** Controlled value: the learner's current response. */\n  value?: LearnerResponse;\n  /** Initial response for an uncontrolled component (ignored when `value` is set). */\n  defaultValue?: LearnerResponse;\n  /**\n   * Mount the component as already submitted — read at mount only, like any\n   * `default*` prop.\n   *\n   * Restoring an attempt without it reopens a question the learner had already\n   * submitted as answerable, so on a summative paper they can change and\n   * re-submit it. `AttemptState.submittedSlotIds` is what this consumes.\n   */\n  defaultSubmitted?: boolean;\n  /** Fires on every change to the learner's response. Required for a controlled component. */\n  onChange?: (response: LearnerResponse) => void;\n  /** Presentation mode. Defaults to `practice`. */\n  renderMode?: RenderMode;\n  /**\n   * Server-computed outcome, used by `review` mode to mark correctness\n   * without the client ever scoring. Ignored in other modes.\n   */\n  outcome?: ItemOutcome;\n  /** Renders author-supplied rich text when provided. See {@link HtmlSanitizer}. */\n  sanitizeHtml?: HtmlSanitizer;\n  /**\n   * Binds this activity's own `data.media` to a play budget the consumer\n   * persists. Usually supplied by `<ActivitySequence mediaBudget={…}>`; pass it\n   * yourself when rendering an activity standalone.\n   */\n  mediaBudget?: MediaBudgetBinding;\n  /** Translations for the audio transport chrome. See {@link MediaTransportStrings}. */\n  mediaStrings?: Partial<MediaTransportStrings>;\n  /**\n   * Overrides the SDK's chrome text for this activity, layered on whatever\n   * `LkIntlProvider` supplies. `mediaStrings` still works and is merged after\n   * this, so an existing 0.8.x call site keeps behaving as it did.\n   */\n  strings?: LkStringsOverride;\n  onInteraction?: (event: InteractionEvent) => void;\n  /**\n   * The host's AI ports for this activity — an explanation after grading, hints\n   * before submit — overriding `LkAiProvider`'s. Leave a port out to switch\n   * that help off. Nothing AI appears in `exam`, and an item whose author\n   * switched a feature off (`data.ai`) never shows it. See {@link LearnerAi}.\n   */\n  ai?: LearnerAi;\n  /**\n   * What the school running this paper lets a learner see: feedback,\n   * solutions, hints, and AI help. Every setting only takes something away\n   * from what the mode shows, and an absent policy takes nothing away. Inside\n   * `<ActivitySequence>` or `<InteractiveVideo>`, the paper's own policy holds\n   * as well, whichever is stricter. See `DeliveryPolicy` in lk-core.\n   */\n  delivery?: DeliveryPolicy | null;\n  /**\n   * How this question is scored when the learner can try again or ask for\n   * hints: how many tries, which counts, what tries and hints cost. Applies in\n   * `practice`, where the component grades — `<MultipleChoice>`,\n   * `<FillInTheBlanks>`, `<GapSelect>` and `<Dictation>`. `<ReadAloud>` takes\n   * the prop and ignores it: its tries are its own `recording.maxTakes`, and\n   * its grade comes from your assessor, not from the component. Inside\n   * `<ActivitySequence>` or `<InteractiveVideo>`, the paper's own policy wins\n   * over this one. See `ItemScoringPolicy` in lk-core.\n   *\n   * With tries, `onComplete` fires after every graded try: `score` and\n   * `passed` are the question's under the policy so far, and `xapiStatement`\n   * records the try just made. A policy `validateItemScoringPolicy` refuses\n   * throws at render.\n   */\n  scoring?: ItemScoringPolicy | null;\n  /** Per-instance token overrides, applied as inline CSS vars on the root. */\n  theme?: Partial<ThemeTokens>;\n  /**\n   * BCP 47 tag stamped as `lang` on this component's root. This is the\n   * INTERFACE language — the SDK's own chrome renders inside that element — so\n   * it should carry the same value you give `<LkIntlProvider locale>`. Passing\n   * a different one re-declares the language of every SDK string in this\n   * subtree without changing the words.\n   *\n   * It is NOT `data.locale`, which labels xAPI statements — and, on a\n   * dictation, places the dictation's own words: `<Dictation>` puts it, and\n   * the direction it names, on its title, hints, marks and solution. Other\n   * authored content in another language belongs on `stimulus.locale`, which\n   * `<StimulusPanel>` puts on the passage alone.\n   */\n  locale?: string;\n  disabled?: boolean;\n}\n\n/**\n * Bridges a server-produced `redact()` projection into the `data` prop.\n *\n * `RedactedActivityData` is deliberately index-signature typed in lk-core — it\n * proves a payload is learner-safe, not what shape it has — so TypeScript\n * cannot know it still carries the public fields a renderer needs. This is the\n * SDK's single, documented crossing of that gap, so an exam runner does not\n * have to write `as unknown as` at every call site:\n *\n * ```tsx\n * <MultipleChoice\n *   data={asRenderable<MultipleChoiceData>(redactedFromServer)}\n *   renderMode=\"exam\"\n *   onSubmit={persist}\n * />\n * ```\n *\n * Safe because `exam` mode reads only public fields; the answer-key fields the\n * type claims are exactly the ones the component is forbidden to touch there.\n *\n * Per-type redacted interfaces (`RedactedMultipleChoiceData`, …) ship from\n * lk-core since 0.6.0, but they are not yet *assignable* to `data`:\n * {@link Renderable} widens `scoringStrategy` and leaves nested answer-key\n * fields (`options[].isCorrect`, `blanks[].acceptedAnswers`) required, so a\n * real redacted payload still needs this bridge. Closing that gap is tracked\n * in the roadmap.\n */\nexport function asRenderable<TData extends ActivityData>(\n  redacted: RedactedActivityData,\n): Renderable<TData> {\n  return redacted as unknown as Renderable<TData>;\n}\n\n/**\n * The same bridge as {@link asRenderable}, for a whole sequence: activities\n * and item groups as a server hands them over, ready for `<ActivitySequence>`.\n *\n * Needed for the same reason and no other. `redactItemGroup` returns\n * `ItemGroup<RedactedActivityData>`, and `RedactedActivityData` is an\n * index-signature type whose fields are all `unknown` — so its `question` is\n * not a `string` and it satisfies no per-type renderable, however the prop is\n * widened. Widening alone cannot fix this; a crossing point is required, and\n * having exactly one keeps `as unknown as` out of consumer code.\n *\n * ```tsx\n * const entries = await fetchExam();            // redacted, server-side\n * <ActivitySequence\n *   activities={asRenderableSequence(entries)}\n *   renderMode=\"exam\"                           // REQUIRED: see below\n *   shuffleSeed={attemptId}\n *   onSubmit={persist}\n * />\n * ```\n *\n * Pass `renderMode=\"exam\"` (or `\"review\"`). Redacted data has no answer key, and\n * almost every built-in activity throws at render in the default `practice`\n * mode rather than fail later: `<MultipleChoice>`, `<FillInTheBlanks>`,\n * `<GapSelect>` and `<Dictation>` because they grade locally, and\n * `<WrittenResponse>` because `practice` still runs its local submit path and\n * emits a practice-mode xAPI statement.\n *\n * `<ReadAloud>` is the exception and renders a projection in every mode: a\n * read-aloud item has no answer key to withhold, so `redact()` removes only the\n * authored feedback and leaves the reading, its language and its bounds — which\n * is everything the component puts on screen. It grades nothing locally either;\n * the grade comes back from whatever the application asked to judge the take.\n */\nexport function asRenderableSequence(\n  entries: readonly (RedactedActivityData | RedactedItemGroupData)[],\n): readonly SequenceEntry<RenderableActivity>[] {\n  return entries as unknown as readonly SequenceEntry<RenderableActivity>[];\n}\n\n/** Structural shape of a `redactItemGroup()` projection, as it arrives from a server. */\ntype RedactedItemGroupData = ItemGroup<RedactedActivityData> & { redacted: true };\n\n/**\n * Every word the SDK's audio transport renders.\n *\n * Words, not characters: the `m:ss / m:ss` clock is digits and punctuation and\n * is formatted by the component, because it reads identically in every locale\n * this SDK targets. The scrubber's SPOKEN value does have a word in it and does\n * have a key ({@link MediaTransportStrings.timeValue}).\n *\n * Supply them to translate it. These are the highest-stakes strings on a\n * listening paper — \"No plays remaining\" decides whether a learner believes\n * they may try again — so shipping them as untranslatable English inside a\n * Spanish panel was not acceptable. Supplying any of them also sets `lang` on\n * the transport chrome, so a screen reader does not read the SDK's own words\n * with the passage's phonetics.\n */\nexport interface MediaTransportStrings {\n  play: string;\n  pause: string;\n  preparing: string;\n  mute: string;\n  unmute: string;\n  volume: string;\n  speed: string;\n  seek: string;\n  /**\n   * Spoken value of the scrubber, e.g. `('1:05', '4:30') => '1:05 of 4:30'`.\n   * Takes ALREADY-FORMATTED `m:ss` strings: a translation should not have to\n   * reimplement the clock to change the word between them.\n   */\n  timeValue: (elapsed: string, duration: string) => string;\n  /** e.g. `(1, 2) => '1 of 2 plays remaining'`. */\n  playsRemaining: (remaining: number, max: number) => string;\n  noPlaysRemaining: string;\n  /** Shown before the LAST play is spent, so a stray press cannot cost it. */\n  lastPlayConfirm: string;\n  lastPlayStart: string;\n  lastPlayCancel: string;\n  seekBlocked: string;\n  rateBlocked: string;\n  playFailed: string;\n}\n\n/**\n * Binds ONE media block to a play budget the consumer persists.\n *\n * The SDK refuses a play; it does not remember one. Everything durable here is\n * the consuming application's — see {@link SequenceMediaBudget.onPlayConsumed}.\n */\nexport interface MediaBudgetBinding {\n  /** From `slotMediaKey(slotId)` / `stimulusMediaKey(slotId)` in lk-core. */\n  key: string;\n  /** Plays already spent, and where playback stood. Read at mount only. */\n  entry?: MediaPlayLedgerEntry;\n  /** Defaults to `renderMode !== 'review'`. An explicit boolean wins either way. */\n  enforced?: boolean;\n  /** Slot context stamped onto the claim and the interaction event. */\n  slotId: string;\n  index: number;\n  activityId?: string;\n  onPlayConsumed?: (claim: MediaPlayClaim) => undefined | Promise<MediaPlayGrant | undefined>;\n  onPlayRefunded?: (claim: MediaPlayClaim) => void;\n  onPosition?: (key: string, seconds: number) => void;\n  /** Translations for the transport chrome. */\n  strings?: Partial<MediaTransportStrings>;\n}\n\n/**\n * The pager-level half of a play budget. One prop, because it is one concept.\n */\nexport interface SequenceMediaBudget {\n  /**\n   * `MediaPlayLedger.entries` goes straight in. An absent key means nothing\n   * spent. Read at mount, like `responses`.\n   */\n  plays?: Readonly<Record<string, MediaPlayLedgerEntry>>;\n  /**\n   * Re-seed token. Change this string and the budgets re-seed from `plays`\n   * WITHOUT remounting the pager — the invigilator path (\"the audio never\n   * started, give her the play back\") that would otherwise cost the learner\n   * their focus, their scroll position and an unsaved answer.\n   */\n  resumeKey?: string;\n  /** Explicit override of the default (`renderMode !== 'review'`). */\n  enforced?: boolean;\n  /**\n   * Called the instant a play is claimed, BEFORE any audio is audible.\n   *\n   * Two tiers, chosen by what you return:\n   *\n   * - **Return nothing (optimistic).** Playback starts immediately and the\n   *   count is only as durable as your write. **Do not debounce this, and do\n   *   not batch it with the answer autosave** — an eight-second debounce is\n   *   exactly long enough to start a third play and hard-reload. A `pagehide`\n   *   beacon is a backstop, not the mechanism. A crash between this call and\n   *   your write landing RETURNS the play to the learner; that is the honest\n   *   description of what you are buying.\n   * - **Return a promise (confirmed).** Playback is held — the button reads\n   *   \"Preparing…\" and is `aria-busy` — until it settles. Resolve with\n   *   `{ playsUsed }` from an ATOMIC server write (`UPDATE … SET plays = plays\n   *   + 1 … RETURNING plays`, or a compare-and-set on\n   *   `claim.previousPlaysUsed`). A resolved count above `maxPlays` refuses the\n   *   play, which is how a second tab is caught: two mounts both seeded at 0\n   *   both claim 1, and only an atomic increment can tell them apart. A\n   *   rejection charges nothing and lets the learner retry. This is the only\n   *   tier in which \"consumed before audible\" is true of storage rather than\n   *   only of memory; use it for summative papers.\n   *\n   * Never settle the promise and the learner cannot play at all: settle it.\n   */\n  onPlayConsumed?: (claim: MediaPlayClaim) => undefined | Promise<MediaPlayGrant | undefined>;\n  /**\n   * Called when a charged play produced no audio — the element errored before\n   * playback advanced past 0.25 s, an expired signed URL being the realistic\n   * cause. Supply it to give the play back, decrementing with a compare-and-set\n   * on `claim.playsUsed`. Omit it and the play stays spent: the SDK will not\n   * decrement a ledger it has no channel to correct.\n   */\n  onPlayRefunded?: (claim: MediaPlayClaim) => void;\n  /**\n   * Position reports, so a refresh resumes the play the learner already paid\n   * for instead of charging them again. Fires on pause, on end (with 0), and at\n   * most once per whole second of playback.\n   *\n   * **This one you MAY throttle** — the granularity you persist is the\n   * granularity of the replay a crash grants. Three seconds is sane; three\n   * minutes is not.\n   */\n  onPosition?: (key: string, seconds: number) => void;\n  /** Translations for the transport chrome. Defaults are English. */\n  strings?: Partial<MediaTransportStrings>;\n}\n\n/**\n * Which slot a recording belongs to, stamped on every call the pager makes.\n *\n * Exactly the shape {@link ActivitySequenceProps.onSubmit} already passes, so\n * one identity travels with the answer and with the take that answer points at\n * — and a consumer writes `slotId` in both places rather than reconciling two\n * spellings of \"which question was this\".\n */\nexport interface SequenceRecordingSlot {\n  /** Identity from `flattenSequence` — stable under shuffling. Store against THIS. */\n  slotId: string;\n  /** Presented position, which moves under shuffling. */\n  index: number;\n  activityId: string;\n}\n\n/**\n * The pager-level half of a read-aloud recording binding: where every take in\n * this sequence is stored, and how a judgement comes back.\n *\n * One prop at both levels, because it is one concept — the media-budget\n * precedent ({@link SequenceMediaBudget} beside {@link MediaBudgetBinding}).\n * The difference is the second argument: a per-slot binding knows which slot it\n * belongs to, so a sequence-level one is told.\n *\n * The SDK records and hands over; it never judges. `assess` is `practice` only\n * and optional — a sequence that only stores takes gets the \"assessment is not\n * available\" notice rather than a throw — and `playbackUrl` is `review` only.\n * A slot whose activity is not a read-aloud never calls any of them.\n */\nexport interface SequenceRecordingBinding {\n  /**\n   * Puts the take in your storage and returns its key. **Required** outside\n   * `review`: without it a learner can speak into a control that submits\n   * nothing, which the component refuses to render. Settle it.\n   */\n  upload(take: RecordedTake, slot: SequenceRecordingSlot): Promise<RecordingRef>;\n  /** Judges the stored take. `practice` only; an exam never assesses on the client. */\n  assess?(ref: RecordingRef, slot: SequenceRecordingSlot): Promise<ReadAloudAssessResult>;\n  /** A playable link to a stored take. `review` only. */\n  playbackUrl?(ref: RecordingRef, slot: SequenceRecordingSlot): Promise<string>;\n}\n"]}

package/dist/theme/skin.css

@@ -3339,7 +3339,8 @@
 }
 
 @layer lk-skin {
-  /* ── AI help: an explanation after grading, hints before submit ─────────
+  /* ── AI help: an explanation after grading, hints before submit, feedback
+     on a draft, and coaching on a reading ────────────────────────────────
      Set apart from the author's own feedback by a dashed rule and a notice
      under it, so a learner can always tell what a model wrote from what a
      teacher did. On the plain surface, where the muted notice is a colour
@@ -3445,6 +3446,50 @@
     font-weight: 600;
   }
 
+  /* Coaching on a reading holds a list of words as well as text, spaced as
+     feedback on a draft is. Each word coached leads with the word as the
+     reading spells it, then the sound, then what to do: the tip takes a line
+     of its own, so a long one never squeezes the word beside it. */
+  .lk-ai-coaching .lk-ai-panel {
+    display: flex;
+    flex-direction: column;
+    gap: var(--lk-spacing-sm);
+  }
+
+  .lk-ai-coaching .lk-ai-panel > * {
+    margin: 0;
+  }
+
+  .lk-ai-coaching-words {
+    display: flex;
+    flex-direction: column;
+    gap: var(--lk-spacing-xs);
+    padding: 0;
+    list-style: none;
+  }
+
+  .lk-ai-coaching-word {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    gap: var(--lk-spacing-xs) var(--lk-spacing-sm);
+    padding: var(--lk-spacing-xs) var(--lk-spacing-sm);
+    border-inline-start: 3px dashed var(--lk-color-primary);
+  }
+
+  .lk-ai-coaching-target {
+    font-weight: 600;
+  }
+
+  .lk-ai-coaching-sound {
+    font-size: var(--lk-font-size-sm);
+    color: var(--lk-color-text-muted);
+  }
+
+  .lk-ai-coaching-word > .lk-ai-text {
+    flex-basis: 100%;
+  }
+
   @media (prefers-reduced-motion: reduce) {
     .lk-ai-button {
       transition: none;

package/dist/{types-CrtIcRcK.d.ts → types-C4IsUQsK.d.ts}

@@ -456,6 +456,22 @@ interface LkStrings {
      * percentage — said to be an indication and not a grade, which it is not.
      */
     aiIndicativeScore: (percent: number) => string;
+    /** The button that asks for coaching on a graded reading aloud. */
+    aiCoaching: string;
+    /** The same button while the coaching is being written. */
+    aiCoachingLoading: string;
+    /** The heading over coaching on a reading, and its accessible name. */
+    aiCoachingHeading: string;
+    /** When no coaching can be shown: the port failed, or its coaching was refused. */
+    aiCoachingUnavailable: string;
+    /** The accessible name of the list of words the coaching works on. */
+    aiCoachingWords: string;
+    /**
+     * The sound a tip is about, as the speech engine spelt it — in the alphabet
+     * it reported, usually IPA — and, when the engine said so, what it was heard
+     * as instead.
+     */
+    aiCoachingSound: (expected: string, heard: string | undefined) => string;
     /**
      * The listening-paper transport. Shipped in 0.8.0 as its own `mediaStrings`
      * prop, which still works — this is the same shape, reachable from the one