@intellectif/lk-react 20.0.0 → 22.0.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @intellectif/lk-react
 
+## 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
+
+- [#78](https://github.com/intellectif/learning-kit/pull/78) [`30a9b3d`](https://github.com/intellectif/learning-kit/commit/30a9b3da9be60589d63516752a02cc2f44bdf73b) Thanks [@diego28e](https://github.com/diego28e)! - **Scoring policies**: "Try again" in practice, which try counts, and what tries and hints cost — set per paper, recorded in the plan, and no grade moves without one.
+
+  **Action required:** only if you build an `InteractiveVideoQuestion` by hand (add `scoring`, e.g. `DEFAULT_ITEM_SCORING_POLICY`) or implement a complete `LkStrings` of your own (nine new keys). Everyone else upgrades with no change.
+
+  - **lk-core:** `ItemScoringPolicy` — `retries` (0–10), `counts` (`'first'` by default, `'best'`, `'last'`), `retryPenalty` and `hintPenalty` (fractions of the marks). `scoreTries` does the arithmetic: a cost is subtracted, never below zero, with floating-point residue under a pass line removed. `evaluate(item, response, { scoring })` charges the response's hints; `evaluateTries(item, responses, { scoring })` picks the try that counts. `validateItemScoringPolicy` and `resolveItemScoringPolicy` refuse a policy that cannot be applied — a `RangeError`, never a guess. `planAttempt(…, { scoring })` records it in the plan and `planHash`, and `verifyAttemptPlan` reports `scoringChanged`. With no policy every number is what it was; 43 new grade vectors pin the arithmetic.
+  - **Responses:** multiple-choice, fill-in-the-blanks and gap-select responses gain an optional `hintsRevealed`, as dictation's already had: in `practice`, the hints a learner was shown, counted from the start of the question.
+  - **lk-react:** `scoring` on every activity, `<ActivitySequence>` and `<InteractiveVideo>`; the paper's policy wins over a question's. "Try again" after an answer short of full marks keeps the answer and clears the marks; "Show answer" (or "Keep this answer") ends the tries. While a try is on offer the right answer and "Explain my answer" wait. `onComplete` fires after every try with the question's score so far. A set waits for any question being tried again, and for the question on screen while it offers a try, and closes every question's tries once it reports; the video closes them at Finish.
+  - **Fixed:** a dictation under `delivery={{ solutions: false }}` hid "Show solution" but its marks still named every word they corrected. They now say a word is wrong or missing without naming it, and draw no letter diff.
+  - Nine new strings: `tryAgain`, `showAnswer`, `keepAnswer`, `triesLeft`, `countedTry`, `scoreBeforeCosts`, `hintCost`, `dictationWordWrongUnnamed`, `dictationWordMissingUnnamed`.
+
+  Guide: https://github.com/intellectif/learning-kit/blob/main/docs/scoring.md
+
+### Patch Changes
+
+- Updated dependencies [[`30a9b3d`](https://github.com/intellectif/learning-kit/commit/30a9b3da9be60589d63516752a02cc2f44bdf73b)]:
+  - @intellectif/lk-core@0.21.0
+
 ## 20.0.0
 
 ### Major Changes

package/README.md

@@ -74,7 +74,8 @@ export function Demo() {
 - **`<WrittenResponse>`** — free-text writing with a live word counter and bounds messaging, graded **asynchronously**: it emits an ungraded submission (never a fake zero) and a SUBMITTED-verb xAPI statement, and renders a returned `GradeRecord` in `review` mode with per-criterion scores and inline corrections.
 - **`<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).
-- **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).
+- **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), 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.
@@ -84,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.
@@ -94,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 179 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.
 
@@ -118,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) |
@@ -159,15 +160,42 @@ that an exhaustive `switch` must handle, and a changed reset target for
 [CHANGELOG](https://github.com/intellectif/learning-kit/blob/main/packages/lk-react/CHANGELOG.md)
 before assuming a migration is needed.
 
+## Releases & upgrading
+
+- **What is supported, and since when** — [Features](https://github.com/intellectif/learning-kit/blob/main/docs/features.md): every activity and capability, the `lk-core` / `lk-react` versions it arrived in, and its guide.
+- **What changed** — [GitHub Releases](https://github.com/intellectif/learning-kit/releases), one per package version, and the same notes in each package's `CHANGELOG.md` (it ships in the npm package, so it is in your `node_modules` too). Notes written since release notes gained a template — every release after lk-core 0.20.0 / lk-react 20.0.0 — start with a one-line summary and **Action required**: `none`, or what to do. Earlier notes lead with the detail; the version map in the upgrading guide says what each one asks of you.
+- **How to upgrade** — [Upgrading](https://github.com/intellectif/learning-kit/blob/main/docs/upgrading.md): which `lk-core` goes with which `lk-react`, and a section per release saying what, if anything, you need to change. A `lk-react` major is often only the `lk-core` peer bump; the map says so.
+- **Hearing about a release** — on GitHub, **Watch → Custom → Releases**, or subscribe to [the releases feed](https://github.com/intellectif/learning-kit/releases.atom). Better still, let your dependency bot bring each release to you as a pull request, with its notes — and keep the two packages together in one, since they move together:
+
+  ```yaml
+  # .github/dependabot.yml — one entry per directory with a package.json
+  version: 2
+  updates:
+    - package-ecosystem: npm
+      directory: /
+      schedule: { interval: weekly }
+      groups:
+        learning-kit:
+          patterns: ["@intellectif/lk-*"]
+  ```
+
+  With Renovate: `"packageRules": [{ "matchPackageNames": ["@intellectif/lk-core", "@intellectif/lk-react"], "groupName": "learning-kit" }]`.
+
+  `lk-core` is still `0.x`, and a caret range on a `0.x` version matches only that minor: `^0.18.0` never installs `0.19.0`. A bot is how you find out there is one.
+
 ## Documentation
 
-- [Upgrading](https://github.com/intellectif/learning-kit/blob/main/docs/upgrading.md) — start here on any upgrade from 2.x, 3.x, 4.x or 5.x.
+- [Features](https://github.com/intellectif/learning-kit/blob/main/docs/features.md) — everything supported, and the versions each arrived in.
+- [Upgrading](https://github.com/intellectif/learning-kit/blob/main/docs/upgrading.md) — which `lk-core` goes with which `lk-react`, and what each release asks of you.
 - [Changelog](https://github.com/intellectif/learning-kit/blob/main/packages/lk-react/CHANGELOG.md) — every release, with the reasoning.
 - [Authoring & content storage](https://github.com/intellectif/learning-kit/blob/main/docs/authoring.md)
 - [Styling](https://github.com/intellectif/learning-kit/blob/main/docs/styling.md) — tokens, the skin, overrides, dark mode, Tailwind.
 - [Internationalisation](https://github.com/intellectif/learning-kit/blob/main/docs/i18n.md) — the full string surface, precedence, plurals, RTL.
 - [Interactive video](https://github.com/intellectif/learning-kit/blob/main/docs/interactive-video.md) — the timeline model, the player's props, captions, resume and required quizzes.
 - [Speech assessment](https://github.com/intellectif/learning-kit/blob/main/docs/speech-assessment.md) — the read-aloud item, the evidence an assessor must produce, and how a grade is computed.
+- [Delivery policies](https://github.com/intellectif/learning-kit/blob/main/docs/delivery.md) — what a school lets a learner see: feedback, solutions, hints and AI help, per paper.
+- [Scoring policies](https://github.com/intellectif/learning-kit/blob/main/docs/scoring.md) — "Try again", which try counts, and what tries and hints cost, per paper.
+- [AI help for learners](https://github.com/intellectif/learning-kit/blob/main/docs/ai.md) — connecting your model, what it is given, what the SDK refuses to show, and testing your prompts.
 - [Project README](https://github.com/intellectif/learning-kit#readme) — full picture & monorepo layout.
 
 ## License

package/dist/{WrittenResponse-D2YI8xOK.d.ts → 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-C-GMCJ0g.js';
+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-obIDDYDH.d.cts → 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-B_PCcqO-.cjs';
+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 chunkZDYNAWDZ_cjs = require('../chunk-ZDYNAWDZ.cjs');
+var chunkOJGTJOWI_cjs = require('../chunk-OJGTJOWI.cjs');
 
 
 
 Object.defineProperty(exports, "LkAiProvider", {
   enumerable: true,
-  get: function () { return chunkZDYNAWDZ_cjs.LkAiProvider; }
+  get: function () { return chunkOJGTJOWI_cjs.LkAiProvider; }
 });
 Object.defineProperty(exports, "useLearnerAi", {
   enumerable: true,
-  get: function () { return chunkZDYNAWDZ_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';
 
 /**
@@ -29,9 +29,22 @@ interface LearnerAi {
     /** The most hints a learner can ask for on one question. Default 3, at most 10. */
     maxHints?: number;
     /**
-     * The language to write explanations and hints in — the learner's own,
-     * which in a language course need not be the item's. Defaults to the
-     * component's `locale`.
+     * 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,
+     * which the buttons around the help are in, and usually the right one. In a
+     * language course it need not be the item's — English items, explained in
+     * Spanish — and the item's own language reaches your port as `facts.locale`.
      */
     learnerLocale?: string;
 }

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';
 
 /**
@@ -29,9 +29,22 @@ interface LearnerAi {
     /** The most hints a learner can ask for on one question. Default 3, at most 10. */
     maxHints?: number;
     /**
-     * The language to write explanations and hints in — the learner's own,
-     * which in a language course need not be the item's. Defaults to the
-     * component's `locale`.
+     * 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,
+     * which the buttons around the help are in, and usually the right one. In a
+     * language course it need not be the item's — English items, explained in
+     * Spanish — and the item's own language reaches your port as `facts.locale`.
      */
     learnerLocale?: string;
 }

package/dist/ai/LkAiProvider.js

@@ -1,4 +1,4 @@
 'use client';
-export { LkAiProvider, useLearnerAi } from '../chunk-YNDKAYW3.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 chunkTRMWBJWT_cjs = require('../chunk-TRMWBJWT.cjs');
-require('../chunk-ZDYNAWDZ.cjs');
-require('../chunk-BJLQKJZX.cjs');
+var chunkPZVRZ6OX_cjs = require('../chunk-PZVRZ6OX.cjs');
+require('../chunk-OJGTJOWI.cjs');
+require('../chunk-J2QIHZ3H.cjs');
 require('../chunk-EANGKAKG.cjs');
 
 
 
 Object.defineProperty(exports, "useAiExplanation", {
   enumerable: true,
-  get: function () { return chunkTRMWBJWT_cjs.useAiExplanation; }
+  get: function () { return chunkPZVRZ6OX_cjs.useAiExplanation; }
 });
 Object.defineProperty(exports, "useAiHints", {
   enumerable: true,
-  get: function () { return chunkTRMWBJWT_cjs.useAiHints; }
+  get: function () { return chunkPZVRZ6OX_cjs.useAiHints; }
+});
+Object.defineProperty(exports, "useAiWritingFeedback", {
+  enumerable: true,
+  get: function () { return chunkPZVRZ6OX_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-B_PCcqO-.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-C-GMCJ0g.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-AQIAQHJC.js';
-import '../chunk-YNDKAYW3.js';
-import '../chunk-WBLYD5QA.js';
+export { useAiExplanation, useAiHints, useAiWritingFeedback } from '../chunk-TRXUZSOY.js';
+import '../chunk-RX3A6KIY.js';
+import '../chunk-U4KTOH7C.js';
 import '../chunk-PPFVTXGJ.js';
 //# sourceMappingURL=useAiHelp.js.map
 //# sourceMappingURL=useAiHelp.js.map