@intellectif/lk-react 21.0.0 → 23.0.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @intellectif/lk-react
 
+## 23.0.0
+
+### Major Changes
+
+- [#82](https://github.com/intellectif/learning-kit/pull/82) [`bcae525`](https://github.com/intellectif/learning-kit/commit/bcae52599d7d0481ccd8ceecdfc59f2bd6d4d281) Thanks [@diego28e](https://github.com/diego28e)! - **1.0**: what every 1.x keeps stable, written down, and from now on a lk-core minor releases no lk-react. No grade changes.
+
+  **Action required:** only if you read `ScoringDetail.correct`, import a zod schema from lk-core, or register an activity type of your own. Install lk-core 1.0.0 and lk-react 23.0.0 together. Each change and its replacement is in the upgrading guide: https://github.com/intellectif/learning-kit/blob/main/docs/upgrading.md
+
+  - **Stability:** grades, the public API, content and runtimes — what a 1.x release may and may not change — are set out in https://github.com/intellectif/learning-kit/blob/main/docs/stability.md. lk-react 23 peers on `@intellectif/lk-core@^1.0.0`, and a lk-core minor or patch releases no lk-react.
+  - **`ScoringDetail.correct` is removed, and `outcome` is required.** Deprecated since 0.3; on a multiple-choice option it meant "the learner acted rightly on it". Read `outcome`. The grade-stability corpus changed only there: 142 vectors lose `correct`, and no score, pass or feedback moves. A detail stored before 0.3 still carries only `correct`; the SDK's components still read it.
+  - **Zod is private to lk-core.** No zod schema is exported and no published type names zod, so your app can use any zod, or none. `validateMedia` and `validateOptionMedia` replace `MediaSchema.safeParse` and `MultipleChoiceOptionMediaSchema.safeParse`; `validateActivity`, `validateDraft` and `validateItemGroup` replace the rest. The `*JsonSchema` constants are typed `Record<string, unknown>`, and the `Redacted*` types are written out, unchanged in shape.
+  - **A type you register takes Standard Schemas** (https://standardschema.dev): `schema` and `redactedSchema` are `StandardSchemaV1`. A zod 4 schema is one as written; valibot and ArkType work too. Validation must be synchronous. `registerActivityType` throws on a value that is not a Standard Schema, and `jsonSchemaFor` on your type needs the descriptor's new `jsonSchema` unless the schema produces JSON Schema itself, as zod 4.6 does.
+  - **Built on zod 4.6.5, pinned exactly**, instead of the zod 4 preview in zod 3.25. A new zod reaches you only in a lk-core release. If your app uses another version of zod, your bundle carries two copies. Every built-in validation accepts and refuses what it did, checked against 0.21.0 on 28,000 inputs; from 1.0, `vectors/validation.json` in the tarball freezes that for over three thousand inputs, and each release replays it. Two error lists are one error shorter: a speech assessment with a string where a list of phonemes or syllables belongs, and an xAPI statement whose actor's `mbox` is not a `mailto:` address.
+  - **Fixed (lk-react):** a host's grade whose details carry no `correct` — every detail lk-core 1.0 writes — had all its details dropped, a read-aloud's word marks among them. It is now read.
+
+### Patch Changes
+
+- Updated dependencies [[`bcae525`](https://github.com/intellectif/learning-kit/commit/bcae52599d7d0481ccd8ceecdfc59f2bd6d4d281)]:
+  - @intellectif/lk-core@1.0.0
+
+## 22.0.0
+
+### Major Changes
+
+- [#80](https://github.com/intellectif/learning-kit/pull/80) [`782b01b`](https://github.com/intellectif/learning-kit/commit/782b01ba697a90583b472ab1a7a2be102fd888c4) Thanks [@diego28e](https://github.com/diego28e)! - **Feedback on writing**: "Get feedback on my draft" on a written response in practice. The learner revises and asks again, and every correction must quote what they wrote.
+
+  **Action required:** none unless your code switches exhaustively over `AiFeature` or `AiRefusal` (new members `'writing-feedback'` and `'misquotes-answer'`), reads `AiCheckCase.request` without narrowing on `feature`, or implements a complete `LkStrings` (eight new keys). Nothing changes until you pass a `writingFeedback` port. Otherwise this is a major only because the peer range moves to `@intellectif/lk-core@^0.22.0`.
+
+  - **lk-core:** `aiWritingFeedbackRequest` builds what a model is given: the task, the draft verbatim, its word count as the grader counts it, the rubric, and the feedback on earlier drafts. `checkAiWritingFeedback` checks the reply before a learner sees it. It finds each correction's quote in the draft itself (typographic quotes and runs of whitespace folded, case kept) and anchors it there. A correction of words the draft does not contain refuses the whole reply as `misquotes-answer`. Criteria must be the rubric's; the author's weights are attached, and a model's weight is ignored. The indicative score is `gradeFromRubric`'s total, computed only when every criterion was judged. It is never a grade. Limits: 20 corrections, 500 characters a field.
+  - **lk-react:** a `writingFeedback` port and `maxWritingFeedback` (3 by default, at most 10) on `LearnerAi`. `<WrittenResponse>` shows the feedback with its corrections, rubric comments, the indicative score marked "Not a grade." and the AI notice, and says so once the draft has changed. It is never in `exam` or `review`, and it follows the author's and the paper's `ai.explanations`, `feedback` and `solutions`. `useAiWritingFeedback` gives a written response you draw yourself the same rules.
+  - **Records:** `ai-writing-feedback-shown` (the draft number, how many corrections, the indicative score, provenance and usage; never the text), and `ai-help-refused` with `feature: 'writing-feedback'`.
+  - **ai-check:** a `writingFeedback` port runs four writing cases: a draft with mistakes, one without, a revision, and feedback asked for in Spanish.
+  - Eight new strings: `aiWritingFeedback`, `aiWritingFeedbackLoading`, `aiWritingFeedbackHeading`, `aiWritingFeedbackUnavailable`, `aiNoMoreWritingFeedback`, `aiWritingFeedbackOutdated`, `aiCorrections`, `aiIndicativeScore`.
+
+  Guide: https://github.com/intellectif/learning-kit/blob/main/docs/ai.md#feedback-on-writing
+
+### Patch Changes
+
+- Updated dependencies [[`782b01b`](https://github.com/intellectif/learning-kit/commit/782b01ba697a90583b472ab1a7a2be102fd888c4)]:
+  - @intellectif/lk-core@0.22.0
+
 ## 21.0.0
 
 ### Major Changes

package/README.md

@@ -75,7 +75,7 @@ export function Demo() {
 - **`<InteractiveVideo>`** — a video that stops at each quiz and asks its questions over itself, then plays on. **A formative tool**, for lessons and practice — deliver official summative exams with `<ActivitySequence>`. One player: a progress bar that marks every quiz and previews the caption under the pointer, speed, volume, captions drawn from WebVTT it parses itself (through a `captionsLoader` when the file needs the learner's credentials) — in one language or two at once, a second line under the first for a learner matching what they hear to what it means — a contents and transcript panel, picture-in-picture, fullscreen and a keyboard map with a shortcut sheet. A quiz covers the video and grows the player rather than scrolling inside it, every question of an opened quiz stays mounted so a rewind loses no answer, the controls are `inert` while it is open, and a **required** quiz holds both playback and seeking until it is answered. Answers report with the slot the question sits in and the quiz it belongs to, and `onProgress` gives a resume point that is never past an unanswered required quiz. A host with renderers of its own draws any question itself through `renderQuestion` — the video still counts it, tells it when it leaves the screen so it can stop its microphone, and holds Finish while its answer is still on its way. See the [interactive video guide](https://github.com/intellectif/learning-kit/blob/main/docs/interactive-video.md).
 - **Delivery policies** — `delivery` on any activity, `<ActivitySequence>` or `<InteractiveVideo>` switches off feedback, solutions, hints or AI help for that paper, so one question serves practice and a final without being authored twice. It can only take away, an empty policy is exactly the default, and a pager's policy holds in every question it holds — a host's own renderer included. See [Delivery policies](https://github.com/intellectif/learning-kit/blob/main/docs/delivery.md).
 - **Scoring policies** — `scoring` on any activity, `<ActivitySequence>` or `<InteractiveVideo>` gives a practice question "Try again", chooses which try counts, and charges for tries and hints, saying what a hint costs before the learner asks. The right answer and "Explain my answer" wait until the tries end, a set waits for a question being tried again, and no policy changes nothing. See [Scoring policies](https://github.com/intellectif/learning-kit/blob/main/docs/scoring.md).
-- **AI help for learners** — "Explain my answer" after grading and "Get a hint" before submit, in `<MultipleChoice>`, `<FillInTheBlanks>`, `<GapSelect>` and `<Dictation>` (explanations only), through ports **you** supply with `<LkAiProvider>` or an `ai` prop (also on `<ActivitySequence>` and `<InteractiveVideo>`). The SDK never calls a model or holds a key: it builds the facts your model is given, refuses an explanation that contradicts the grade and a hint that contains the answer, marks everything a model wrote, and drops a late answer. Never in `exam`. What was shown reaches `onInteraction` with the model that wrote it and what the call cost; what was refused reaches it with the reason, and never the text. See the [AI guide](https://github.com/intellectif/learning-kit/blob/main/docs/ai.md).
+- **AI help for learners** — "Explain my answer" after grading and "Get a hint" before submit, in `<MultipleChoice>`, `<FillInTheBlanks>`, `<GapSelect>` and `<Dictation>` (explanations only), and "Get feedback on my draft" in `<WrittenResponse>` in practice — revise and ask again, and a correction that quotes words the learner never wrote refuses the feedback — through ports **you** supply with `<LkAiProvider>` or an `ai` prop (also on `<ActivitySequence>` and `<InteractiveVideo>`). The SDK never calls a model or holds a key: it builds the facts your model is given, refuses an explanation that contradicts the grade and a hint that contains the answer, marks everything a model wrote, and drops a late answer. Never in `exam`. What was shown reaches `onInteraction` with the model that wrote it and what the call cost; what was refused reaches it with the reason, and never the text. See the [AI guide](https://github.com/intellectif/learning-kit/blob/main/docs/ai.md).
 - **`<ActivitySequence>`** — in-place "question set" pager (Previous/Next, "Question X of N", no scrolling, focus-managed). Accepts item groups and keeps their stimulus beside every question; `onSubmit` reports every raw answer with its `slotId`, which is the only response channel an `exam` sequence has. `onFinished` is the completion signal for a set that mixes scored and deferred-graded items, where `onComplete` can never fire. A read-aloud slot takes its storage from `recordingBinding`, whose methods are told which slot a take belongs to, and a `review` its per-word marks from `assessments`, keyed by `slotId` — there is a [worked example](https://github.com/intellectif/learning-kit/blob/main/docs/speech-assessment.md#in-a-question-set).
 - **Resume and review a whole attempt** — `<ActivitySequence>` takes `defaultIndex`, `responses` and `submittedSlotIds` (read at mount; remount with a `key` to show a different attempt), so an interrupted paper reopens on the right question with the right answers and already-committed questions still committed. `onIndexChange` reports every position the pager lands on, including a clamp it had to apply. Pass `renderMode="review"` plus server-computed `outcomes` to render a finished attempt read-only. Pairs with `serializeAttemptState` / `restoreAttemptState` in `lk-core`.
 - **`renderMode`** — `practice` (default: the component scores locally and reveals correctness), `exam` (never scores, never reveals; submit emits the raw response for the server to grade), `review` (read-only, marks correctness only from an `outcome` you supply). This is the single switch that takes grading off the client.
@@ -85,7 +85,7 @@ export function Demo() {
 - **`<StimulusPanel>`** — a shared passage / recording / image (an item group's stimulus) as a landmark region; the sequence uses it, and a custom runner can too.
 - **`<ActivityPreview>`** — an editor's preview. Renders a draft in any `renderMode` with a simulated `response` (marked with `evaluate()` in `review`), and a translatable notice — or your `fallback`, handed the issues — while `validateDraft` says the draft is not finished. Nothing it renders is recorded, and a recording's play limit is counted in memory only.
 - **Custom activity types** — `renderers={{ 'my-type': MyRenderer }}` on the sequence; a key matching a built-in overrides it, so you can replace a bundled renderer without forking the sequencer. A renderer is given the same contract the SDK's own components have: a `question` prop that says when it is the question on screen (so it can stop its microphone), holds the set while its own work is in flight, gives it somewhere to portal a popover, and reports what the learner did through calls that keep one identity.
-- **AI help in a question you draw** — `useAiHints` and `useAiExplanation` give a host's own renderer the rules, the facts and the refusals the bundled components use, without their buttons. `ask` does nothing where the rules say no, so an exam reaches no model however the page asks.
+- **AI help in a question you draw** — `useAiHints`, `useAiExplanation` and `useAiWritingFeedback` give a host's own renderer the rules, the facts and the refusals the bundled components use, without their buttons. `ask` does nothing where the rules say no, so an exam reaches no model however the page asks.
 - **Rich text, opt-in** — `sanitizeHtml` renders author-supplied `questionHtml` / `promptHtml`. The SDK ships **no** sanitiser and injects no HTML without one; without it the escaped plain-text field is used. (`FillInTheBlanks` ignores `passageHtml` by design — its passage hosts the answer inputs.)
 - **Media per question** — optional `image` / `audio` / `video` / `embed` (YouTube/Vimeo iframe) above the question; alt-text required for `image`/`embed` (WCAG).
 - **Playback policy for listening papers** — an audio recording can declare `maxPlays`, `seek: 'none'` and `rate: 'fixed'`. The SDK then renders its own accessible transport (44px targets, a live plays-remaining status, an exhausted button that stays focusable and says why) and enforces the policy from the element's own events, so a hardware media key goes through the budget too. Wire `mediaBudget` on `<ActivitySequence>` to make a play budget survive a refresh.
@@ -95,7 +95,7 @@ export function Demo() {
 - **`useSpeechRecorder(options)`** — the capture half of a read-aloud, usable on its own: microphone permission, an RMS level for a meter, a minimum take length, and an auto-stop measured from the **sample count** rather than a timer, so a take can never outrun its own limit. It yields **16 kHz mono 16-bit PCM WAV** — the one format `inspectWav` in `lk-core` measures without a decoder. SSR-safe by construction (support is discovered inside `start()`, never probed during render, so a server render and its hydration cannot disagree), and the microphone and the audio context are released on stop, discard, error and unmount alike. Where a Content-Security-Policy's `script-src` does not allow `blob:`, serve `CAPTURE_PROCESSOR_SOURCE` — exported beside the hook, with the contract it meets written on it — and pass its URL as `workletUrl`. A `workletUrl` that fails to load is not reported: the hook falls back to the main-thread `ScriptProcessorNode`, so check that the module is fetched.
 - **`<ThemeProvider>` + `defaults.css`** — `--lk-*` design-token system; automatic dark mode via `prefers-color-scheme` (SSR-safe with `useSyncExternalStore`).
 - **`createTailwindTheme(theme)`** — optional Tailwind interop; consume the SDK palette from your own utilities.
-- **`<LkIntlProvider>`** — all 188 strings the SDK's own chrome renders, replaceable in one place, with a per-component `strings` prop for the exceptions. Interpolation and plurals are **functions**, not format strings, so your `Intl.PluralRules` does the work and TypeScript checks the arity. `locale` sets `lang` and derives `dir`; the skin uses logical properties, so RTL follows. The SDK ships the mechanism and **English only** — see [docs/i18n.md](https://github.com/intellectif/learning-kit/blob/main/docs/i18n.md).
+- **`<LkIntlProvider>`** — all 196 strings the SDK's own chrome renders, replaceable in one place, with a per-component `strings` prop for the exceptions. Interpolation and plurals are **functions**, not format strings, so your `Intl.PluralRules` does the work and TypeScript checks the arity. `locale` sets `lang` and derives `dir`; the skin uses logical properties, so RTL follows. The SDK ships the mechanism and **English only** — see [docs/i18n.md](https://github.com/intellectif/learning-kit/blob/main/docs/i18n.md).
 - **WCAG 2.2 AA** — axe-clean unit + Playwright e2e tests; full keyboard operability; numerically-verified contrast.
 - **RSC-compatible** — every component carries `'use client'` and hydrates inside a React Server Component tree.
 
@@ -119,7 +119,7 @@ export function Demo() {
 | `@intellectif/lk-react/hooks/useSpeechRecorder` | Microphone capture to 16 kHz mono WAV, and `CAPTURE_PROCESSOR_SOURCE` for a self-hosted worklet |
 | `@intellectif/lk-react/hooks/useXAPI` | LRS delivery (retry, never-throws) |
 | `@intellectif/lk-react/ai/LkAiProvider` | `<LkAiProvider>`, `useLearnerAi`, and the `LearnerAi` type |
-| `@intellectif/lk-react/ai/useAiHelp` | `useAiHints`, `useAiExplanation` — the AI rules without the SDK's own buttons |
+| `@intellectif/lk-react/ai/useAiHelp` | `useAiHints`, `useAiExplanation`, `useAiWritingFeedback` — the AI rules without the SDK's own buttons |
 | `@intellectif/lk-react/i18n/LkIntlProvider` | `<LkIntlProvider>`, `useLkStrings`, `useLkDirection`, `DEFAULT_STRINGS`, `mergeStrings`, `directionForLocale` |
 | `@intellectif/lk-react/theme/ThemeProvider` | `<ThemeProvider>`, `darkTheme`, `useTheme`, `createTailwindTheme` |
 | `@intellectif/lk-react/theme/defaults.css` | Tokens (required) |

package/dist/{WrittenResponse-BVPmrmQL.d.cts → WrittenResponse-CgRrjM4S.d.ts}

@@ -1,5 +1,6 @@
 import { XAPIStatement, WrittenResponseData, LearnerResponse, ItemOutcome, InteractionEvent, ThemeTokens, DeliveryPolicy } from '@intellectif/lk-core';
-import { f as Renderable, e as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './types-Botf4Wqj.cjs';
+import { LearnerAi } from './ai/LkAiProvider.js';
+import { f as Renderable, e as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './types-CrtIcRcK.js';
 
 /**
  * Payload delivered when the learner submits a written response. Grading is
@@ -95,11 +96,20 @@ interface WrittenResponseProps {
     locale?: string;
     disabled?: boolean;
     /**
-     * The delivery policy. An essay is graded later, so only `feedback` reaches
-     * it: `false` reads a returned grade back as nothing in `review`. See
-     * `DeliveryPolicy` in lk-core.
+     * The delivery policy. An essay is graded later, so `feedback` reaches it —
+     * `false` reads a returned grade back as nothing in `review` — and so does
+     * AI feedback on a draft, which needs `feedback`, `solutions` and
+     * `ai.explanations`. See `DeliveryPolicy` in lk-core.
      */
     delivery?: DeliveryPolicy | null;
+    /**
+     * The host's AI ports, overriding `LkAiProvider`'s. With a `writingFeedback`
+     * port, a learner in `practice` can ask for feedback on a draft before
+     * submitting it — up to `maxWritingFeedback` times — and revise. Every
+     * correction in it quotes the learner's own words, or the SDK refuses it.
+     * Never in `exam` or `review`. See {@link LearnerAi}.
+     */
+    ai?: LearnerAi;
 }
 
 export type { WrittenResponseProps as W, WrittenResponseSubmission as a };

package/dist/{WrittenResponse-IAJvvL-g.d.ts → WrittenResponse-D2K1VW_V.d.cts}

@@ -1,5 +1,6 @@
 import { XAPIStatement, WrittenResponseData, LearnerResponse, ItemOutcome, InteractionEvent, ThemeTokens, DeliveryPolicy } from '@intellectif/lk-core';
-import { f as Renderable, e as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './types-7lGlo0zE.js';
+import { LearnerAi } from './ai/LkAiProvider.cjs';
+import { f as Renderable, e as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './types-CO0XLEN6.cjs';
 
 /**
  * Payload delivered when the learner submits a written response. Grading is
@@ -95,11 +96,20 @@ interface WrittenResponseProps {
     locale?: string;
     disabled?: boolean;
     /**
-     * The delivery policy. An essay is graded later, so only `feedback` reaches
-     * it: `false` reads a returned grade back as nothing in `review`. See
-     * `DeliveryPolicy` in lk-core.
+     * The delivery policy. An essay is graded later, so `feedback` reaches it —
+     * `false` reads a returned grade back as nothing in `review` — and so does
+     * AI feedback on a draft, which needs `feedback`, `solutions` and
+     * `ai.explanations`. See `DeliveryPolicy` in lk-core.
      */
     delivery?: DeliveryPolicy | null;
+    /**
+     * The host's AI ports, overriding `LkAiProvider`'s. With a `writingFeedback`
+     * port, a learner in `practice` can ask for feedback on a draft before
+     * submitting it — up to `maxWritingFeedback` times — and revise. Every
+     * correction in it quotes the learner's own words, or the SDK refuses it.
+     * Never in `exam` or `review`. See {@link LearnerAi}.
+     */
+    ai?: LearnerAi;
 }
 
 export type { WrittenResponseProps as W, WrittenResponseSubmission as a };

package/dist/ai/LkAiProvider.cjs

@@ -1,17 +1,17 @@
 'use client';
 'use strict';
 
-var chunkMPHX3Y42_cjs = require('../chunk-MPHX3Y42.cjs');
+var chunkOJGTJOWI_cjs = require('../chunk-OJGTJOWI.cjs');
 
 
 
 Object.defineProperty(exports, "LkAiProvider", {
   enumerable: true,
-  get: function () { return chunkMPHX3Y42_cjs.LkAiProvider; }
+  get: function () { return chunkOJGTJOWI_cjs.LkAiProvider; }
 });
 Object.defineProperty(exports, "useLearnerAi", {
   enumerable: true,
-  get: function () { return chunkMPHX3Y42_cjs.useLearnerAi; }
+  get: function () { return chunkOJGTJOWI_cjs.useLearnerAi; }
 });
 //# sourceMappingURL=LkAiProvider.cjs.map
 //# sourceMappingURL=LkAiProvider.cjs.map

package/dist/ai/LkAiProvider.d.cts

@@ -1,4 +1,4 @@
-import { AiExplanationRequest, AiTextResult, AiHintRequest } from '@intellectif/lk-core';
+import { AiExplanationRequest, AiTextResult, AiHintRequest, AiWritingFeedbackRequest, AiWritingFeedbackResult } from '@intellectif/lk-core';
 import { ReactNode } from 'react';
 
 /**
@@ -28,6 +28,17 @@ interface LearnerAi {
     }) => Promise<AiTextResult>;
     /** The most hints a learner can ask for on one question. Default 3, at most 10. */
     maxHints?: number;
+    /**
+     * Gives feedback on a draft of a written response, before the learner
+     * submits it: the overall feedback as text, corrections that quote the
+     * draft, and a judgement per rubric criterion. See `checkAiWritingFeedback`
+     * in lk-core for what is refused.
+     */
+    writingFeedback?: (request: AiWritingFeedbackRequest, options: {
+        signal: AbortSignal;
+    }) => Promise<AiWritingFeedbackResult>;
+    /** How many times a learner can ask for feedback on one written response. Default 3, at most 10. */
+    maxWritingFeedback?: number;
     /**
      * The language to write explanations and hints in, as a tag (`es`,
      * `pt-BR`). Defaults to the component's `locale`: the interface language,

package/dist/ai/LkAiProvider.d.ts

@@ -1,4 +1,4 @@
-import { AiExplanationRequest, AiTextResult, AiHintRequest } from '@intellectif/lk-core';
+import { AiExplanationRequest, AiTextResult, AiHintRequest, AiWritingFeedbackRequest, AiWritingFeedbackResult } from '@intellectif/lk-core';
 import { ReactNode } from 'react';
 
 /**
@@ -28,6 +28,17 @@ interface LearnerAi {
     }) => Promise<AiTextResult>;
     /** The most hints a learner can ask for on one question. Default 3, at most 10. */
     maxHints?: number;
+    /**
+     * Gives feedback on a draft of a written response, before the learner
+     * submits it: the overall feedback as text, corrections that quote the
+     * draft, and a judgement per rubric criterion. See `checkAiWritingFeedback`
+     * in lk-core for what is refused.
+     */
+    writingFeedback?: (request: AiWritingFeedbackRequest, options: {
+        signal: AbortSignal;
+    }) => Promise<AiWritingFeedbackResult>;
+    /** How many times a learner can ask for feedback on one written response. Default 3, at most 10. */
+    maxWritingFeedback?: number;
     /**
      * The language to write explanations and hints in, as a tag (`es`,
      * `pt-BR`). Defaults to the component's `locale`: the interface language,

package/dist/ai/LkAiProvider.js

@@ -1,4 +1,4 @@
 'use client';
-export { LkAiProvider, useLearnerAi } from '../chunk-MCTNLUKO.js';
+export { LkAiProvider, useLearnerAi } from '../chunk-RX3A6KIY.js';
 //# sourceMappingURL=LkAiProvider.js.map
 //# sourceMappingURL=LkAiProvider.js.map

package/dist/ai/useAiHelp.cjs

@@ -1,20 +1,24 @@
 'use client';
 'use strict';
 
-var chunkY4IDF5UO_cjs = require('../chunk-Y4IDF5UO.cjs');
-require('../chunk-MPHX3Y42.cjs');
+var chunk6RIM5EQP_cjs = require('../chunk-6RIM5EQP.cjs');
+require('../chunk-OJGTJOWI.cjs');
 require('../chunk-J2QIHZ3H.cjs');
-require('../chunk-EANGKAKG.cjs');
+require('../chunk-54DX6SLS.cjs');
 
 
 
 Object.defineProperty(exports, "useAiExplanation", {
   enumerable: true,
-  get: function () { return chunkY4IDF5UO_cjs.useAiExplanation; }
+  get: function () { return chunk6RIM5EQP_cjs.useAiExplanation; }
 });
 Object.defineProperty(exports, "useAiHints", {
   enumerable: true,
-  get: function () { return chunkY4IDF5UO_cjs.useAiHints; }
+  get: function () { return chunk6RIM5EQP_cjs.useAiHints; }
+});
+Object.defineProperty(exports, "useAiWritingFeedback", {
+  enumerable: true,
+  get: function () { return chunk6RIM5EQP_cjs.useAiWritingFeedback; }
 });
 //# sourceMappingURL=useAiHelp.cjs.map
 //# sourceMappingURL=useAiHelp.cjs.map

package/dist/ai/useAiHelp.d.cts

@@ -1,5 +1,5 @@
-import { AiTextResult, LearnerResponse, InteractionEvent, DeliveryPolicy, ItemOutcome } from '@intellectif/lk-core';
-import { g as RenderableActivity, e as RenderMode } from '../types-Botf4Wqj.cjs';
+import { AiTextResult, LearnerResponse, InteractionEvent, DeliveryPolicy, ItemOutcome, AiWritingFeedback } from '@intellectif/lk-core';
+import { g as RenderableActivity, e as RenderMode } from '../types-CO0XLEN6.cjs';
 import { LearnerAi } from './LkAiProvider.cjs';
 import '../machine-CuwKqWXC.cjs';
 import 'react';
@@ -148,5 +148,60 @@ declare function useAiExplanation(input: AiExplanationInput): AiExplanationHelp;
  * given — while `offered` turns false. Another question starts with none.
  */
 declare function useAiHints(input: AiHintsInput): AiHintsHelp;
+interface AiWritingFeedbackInput extends AiHelpSituation {
+    /** A disabled question takes no feedback, as it takes no answer. */
+    disabled?: boolean;
+}
+interface AiWritingFeedbackHelp {
+    /**
+     * Whether the learner may ask for feedback here at all: a port is present,
+     * the mode is `practice`, the answer is not in, the question is a written
+     * response that is not disabled or redacted, its author left explanations on,
+     * and the paper shows feedback and solutions and allows AI explanations. It
+     * stays true once `used` reaches `limit`.
+     */
+    offered: boolean;
+    status: 'idle' | 'loading' | 'unavailable';
+    /** Every piece of feedback shown for this question, oldest first. */
+    feedback: readonly AiWritingFeedback[];
+    /** The latest, or `null` before any. Its `text` is text, never HTML. */
+    latest: AiWritingFeedback | null;
+    /**
+     * Whether `latest` is about the draft as it stands. Once the learner revises,
+     * its corrections point at words that may no longer be there: say so.
+     */
+    current: boolean;
+    /** The host's `maxWritingFeedback`, as a whole number from 1 to 10 (3 by default). */
+    limit: number;
+    /** How many times feedback has been shown. A refused reply is not counted. */
+    used: number;
+    /**
+     * Asks for feedback on the draft as it stands. Does nothing at the limit,
+     * while a call is on its way, on an empty draft, or where `offered` is false.
+     * One identity for the life of the question.
+     */
+    ask: () => void;
+}
+/**
+ * "Get feedback on my draft", without the SDK's own button and panel: the
+ * rules, the call, the checks and the record, for a written response you draw
+ * yourself.
+ *
+ * It is what `<WrittenResponse>` uses, so a host's own essay box gets feedback
+ * on the same terms: only in `practice` before submit, up to the host's limit,
+ * and never feedback that corrects words the learner did not write — which is
+ * refused rather than shown, and not counted.
+ *
+ * ```tsx
+ * const { offered, status, latest, current, used, limit, ask } = useAiWritingFeedback({
+ *   data, response, submitted, renderMode, ai: question.ai,
+ * });
+ * ```
+ *
+ * **Say who wrote it**, as the SDK's own panel does: "Written by AI. It can make
+ * mistakes." And show `indicativeScore` as what it is — an indication, not a
+ * grade.
+ */
+declare function useAiWritingFeedback(input: AiWritingFeedbackInput): AiWritingFeedbackHelp;
 
-export { type AiExplanationHelp, type AiExplanationInput, type AiHelpSituation, type AiHintsHelp, type AiHintsInput, useAiExplanation, useAiHints };
+export { type AiExplanationHelp, type AiExplanationInput, type AiHelpSituation, type AiHintsHelp, type AiHintsInput, type AiWritingFeedbackHelp, type AiWritingFeedbackInput, useAiExplanation, useAiHints, useAiWritingFeedback };

package/dist/ai/useAiHelp.d.ts

@@ -1,5 +1,5 @@
-import { AiTextResult, LearnerResponse, InteractionEvent, DeliveryPolicy, ItemOutcome } from '@intellectif/lk-core';
-import { g as RenderableActivity, e as RenderMode } from '../types-7lGlo0zE.js';
+import { AiTextResult, LearnerResponse, InteractionEvent, DeliveryPolicy, ItemOutcome, AiWritingFeedback } from '@intellectif/lk-core';
+import { g as RenderableActivity, e as RenderMode } from '../types-CrtIcRcK.js';
 import { LearnerAi } from './LkAiProvider.js';
 import '../machine-CuwKqWXC.js';
 import 'react';
@@ -148,5 +148,60 @@ declare function useAiExplanation(input: AiExplanationInput): AiExplanationHelp;
  * given — while `offered` turns false. Another question starts with none.
  */
 declare function useAiHints(input: AiHintsInput): AiHintsHelp;
+interface AiWritingFeedbackInput extends AiHelpSituation {
+    /** A disabled question takes no feedback, as it takes no answer. */
+    disabled?: boolean;
+}
+interface AiWritingFeedbackHelp {
+    /**
+     * Whether the learner may ask for feedback here at all: a port is present,
+     * the mode is `practice`, the answer is not in, the question is a written
+     * response that is not disabled or redacted, its author left explanations on,
+     * and the paper shows feedback and solutions and allows AI explanations. It
+     * stays true once `used` reaches `limit`.
+     */
+    offered: boolean;
+    status: 'idle' | 'loading' | 'unavailable';
+    /** Every piece of feedback shown for this question, oldest first. */
+    feedback: readonly AiWritingFeedback[];
+    /** The latest, or `null` before any. Its `text` is text, never HTML. */
+    latest: AiWritingFeedback | null;
+    /**
+     * Whether `latest` is about the draft as it stands. Once the learner revises,
+     * its corrections point at words that may no longer be there: say so.
+     */
+    current: boolean;
+    /** The host's `maxWritingFeedback`, as a whole number from 1 to 10 (3 by default). */
+    limit: number;
+    /** How many times feedback has been shown. A refused reply is not counted. */
+    used: number;
+    /**
+     * Asks for feedback on the draft as it stands. Does nothing at the limit,
+     * while a call is on its way, on an empty draft, or where `offered` is false.
+     * One identity for the life of the question.
+     */
+    ask: () => void;
+}
+/**
+ * "Get feedback on my draft", without the SDK's own button and panel: the
+ * rules, the call, the checks and the record, for a written response you draw
+ * yourself.
+ *
+ * It is what `<WrittenResponse>` uses, so a host's own essay box gets feedback
+ * on the same terms: only in `practice` before submit, up to the host's limit,
+ * and never feedback that corrects words the learner did not write — which is
+ * refused rather than shown, and not counted.
+ *
+ * ```tsx
+ * const { offered, status, latest, current, used, limit, ask } = useAiWritingFeedback({
+ *   data, response, submitted, renderMode, ai: question.ai,
+ * });
+ * ```
+ *
+ * **Say who wrote it**, as the SDK's own panel does: "Written by AI. It can make
+ * mistakes." And show `indicativeScore` as what it is — an indication, not a
+ * grade.
+ */
+declare function useAiWritingFeedback(input: AiWritingFeedbackInput): AiWritingFeedbackHelp;
 
-export { type AiExplanationHelp, type AiExplanationInput, type AiHelpSituation, type AiHintsHelp, type AiHintsInput, useAiExplanation, useAiHints };
+export { type AiExplanationHelp, type AiExplanationInput, type AiHelpSituation, type AiHintsHelp, type AiHintsInput, type AiWritingFeedbackHelp, type AiWritingFeedbackInput, useAiExplanation, useAiHints, useAiWritingFeedback };

package/dist/ai/useAiHelp.js

@@ -1,7 +1,7 @@
 'use client';
-export { useAiExplanation, useAiHints } from '../chunk-NDIKHMLJ.js';
-import '../chunk-MCTNLUKO.js';
+export { useAiExplanation, useAiHints, useAiWritingFeedback } from '../chunk-CXIP7ERK.js';
+import '../chunk-RX3A6KIY.js';
 import '../chunk-U4KTOH7C.js';
-import '../chunk-PPFVTXGJ.js';
+import '../chunk-DXFCYNST.js';
 //# sourceMappingURL=useAiHelp.js.map
 //# sourceMappingURL=useAiHelp.js.map

package/dist/{chunk-M3K6BF5M.js → chunk-2OP5YHRR.js}

@@ -1,8 +1,8 @@
 'use client';
 import { localeDirectionOf } from './chunk-YORQQXGO.js';
-import { ActivityErrorBoundary } from './chunk-U6SEII5V.js';
-import { isDevelopment } from './chunk-PPFVTXGJ.js';
-import { useLkStrings } from './chunk-EYLBSS4Y.js';
+import { ActivityErrorBoundary } from './chunk-E4UF4XZM.js';
+import { isDevelopment } from './chunk-DXFCYNST.js';
+import { useLkStrings } from './chunk-C4PSJ3ZC.js';
 import { ActivitySchemaError, alignReadAloud, validateSpeechAssessment } from '@intellectif/lk-core';
 import { useState, useCallback, useId, useMemo, useRef, useEffect } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
@@ -90,13 +90,19 @@ function readDetail(value) {
     return null;
   }
   const { itemId, correct, outcome, learnerResponse, correctResponse, weight, score } = value;
-  if (typeof itemId !== "string" || typeof correct !== "boolean" || !isResponse(learnerResponse) || !isResponse(correctResponse)) {
+  if (typeof itemId !== "string" || !isResponse(learnerResponse) || !isResponse(correctResponse)) {
     return null;
   }
   const checkedOutcome = OUTCOMES.find((known) => known === outcome);
   if (!isAbsent(outcome) && checkedOutcome === void 0) {
     return null;
   }
+  if (!isAbsent(correct) && typeof correct !== "boolean") {
+    return null;
+  }
+  if (checkedOutcome === void 0 && typeof correct !== "boolean") {
+    return null;
+  }
   if (!isAbsent(weight) && !isFiniteNumber(weight)) {
     return null;
   }
@@ -106,10 +112,9 @@ function readDetail(value) {
   }
   return {
     itemId,
-    correct,
     learnerResponse,
     correctResponse,
-    ...checkedOutcome !== void 0 ? { outcome: checkedOutcome } : {},
+    ...checkedOutcome !== void 0 ? { outcome: checkedOutcome } : { correct },
     ...!isAbsent(weight) ? { weight } : {},
     ...checkedScore !== void 0 ? { score: checkedScore } : {}
   };
@@ -534,5 +539,5 @@ function PronunciationFeedback2(props) {
 }
 
 export { PronunciationFeedback2 as PronunciationFeedback, VISUALLY_HIDDEN, fractionOfGrade, markSentence, percentOfGrade, readAssessResult, readEvidence, readOutcome, usePlaybackRefusal };
-//# sourceMappingURL=chunk-M3K6BF5M.js.map
-//# sourceMappingURL=chunk-M3K6BF5M.js.map
+//# sourceMappingURL=chunk-2OP5YHRR.js.map
+//# sourceMappingURL=chunk-2OP5YHRR.js.map