@intellectif/lk-react 18.1.0 → 19.0.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @intellectif/lk-react
 
+## 19.0.0
+
+### Major Changes
+
+- d576382: AI help now reports what it cost and what was refused.
+
+  - **`ai-hint-shown` and `ai-explanation-shown` carry `usage`** when your port sent it, beside the
+    `provenance` they already carried. What a learner was shown and what it cost are then one record,
+    keyed to the attempt — no second channel to reconcile.
+  - **`ai-help-refused` is new**, from the same one implementation the components and the hooks share
+    (`useAiHints`, `useAiExplanation`). It fires where a learner is told help is not available, with
+    `feature` (`hint` or `explanation`), `reason` (`reveals-answer`, `contradicts-grade`, `malformed`,
+    `empty`, `too-long`) and, for a hint, `hintNumber`. **The text is never carried:** a hint refused
+    for revealing the answer contains the answer, and interactions are logged.
+
+    A host that keeps every interaction will start seeing this kind. It is additive — nothing that
+    was emitted before has changed — but a `switch` over `InteractionKind` with no default will not
+    know it.
+
+  **Major** because the peer range moves to `@intellectif/lk-core@^0.19.0`, whose `ai-check` entry
+  point and `AiTextResult.usage` come with it. No React API was removed or renamed, and a host that
+  passes no AI port sees nothing new.
+
+  See `docs/ai.md`.
+
+### Patch Changes
+
+- Updated dependencies [d576382]
+  - @intellectif/lk-core@0.19.0
+
 ## 18.1.0
 
 ### Minor Changes

package/README.md

@@ -73,7 +73,7 @@ export function Demo() {
 - **`<PronunciationFeedback>`** — the marks on their own, for a review screen that has evidence but no activity: the graded dimensions (accuracy, fluency, completeness, prosody — one the engine did not measure reads "not assessed", **never 0%**), and every word marked `correct` / `mispronounced` / `omitted` / `inserted` with a hidden sentence per word for screen readers and a glyph plus a text decoration for everyone else. A word opens onto its syllables, its sounds, what was heard instead, and a button that plays just that word. Evidence it cannot trust is checked before it is aligned, so in production a malformed assessment costs the word list — never the grade beside it.
 - **`<WrittenResponse>`** — free-text writing with a live word counter and bounds messaging, graded **asynchronously**: it emits an ungraded submission (never a fake zero) and a SUBMITTED-verb xAPI statement, and renders a returned `GradeRecord` in `review` mode with per-criterion scores and inline corrections.
 - **`<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).
-- **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`. 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), 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.

package/dist/ai/useAiHelp.cjs

@@ -1,7 +1,7 @@
 'use client';
 'use strict';
 
-var chunkTL3GVPBO_cjs = require('../chunk-TL3GVPBO.cjs');
+var chunkSXU26SFO_cjs = require('../chunk-SXU26SFO.cjs');
 require('../chunk-ZDYNAWDZ.cjs');
 require('../chunk-JVWLXVYG.cjs');
 require('../chunk-EANGKAKG.cjs');
@@ -10,11 +10,11 @@ require('../chunk-EANGKAKG.cjs');
 
 Object.defineProperty(exports, "useAiExplanation", {
   enumerable: true,
-  get: function () { return chunkTL3GVPBO_cjs.useAiExplanation; }
+  get: function () { return chunkSXU26SFO_cjs.useAiExplanation; }
 });
 Object.defineProperty(exports, "useAiHints", {
   enumerable: true,
-  get: function () { return chunkTL3GVPBO_cjs.useAiHints; }
+  get: function () { return chunkSXU26SFO_cjs.useAiHints; }
 });
 //# sourceMappingURL=useAiHelp.cjs.map
 //# sourceMappingURL=useAiHelp.cjs.map

package/dist/ai/useAiHelp.js

@@ -1,5 +1,5 @@
 'use client';
-export { useAiExplanation, useAiHints } from '../chunk-YGJE7RSW.js';
+export { useAiExplanation, useAiHints } from '../chunk-YIYMBCPV.js';
 import '../chunk-YNDKAYW3.js';
 import '../chunk-TEAVPUMX.js';
 import '../chunk-PPFVTXGJ.js';

package/dist/{chunk-TXMP5AOW.cjs → chunk-2X2NZF46.cjs}

@@ -3,10 +3,10 @@
 
 var chunk3FBBP5QR_cjs = require('./chunk-3FBBP5QR.cjs');
 var chunkCQNKZ435_cjs = require('./chunk-CQNKZ435.cjs');
-var chunkX4YU6BX7_cjs = require('./chunk-X4YU6BX7.cjs');
-var chunkJH77MAON_cjs = require('./chunk-JH77MAON.cjs');
-var chunk3SJ7TVL6_cjs = require('./chunk-3SJ7TVL6.cjs');
-var chunk7GYAUA56_cjs = require('./chunk-7GYAUA56.cjs');
+var chunkZME5FMED_cjs = require('./chunk-ZME5FMED.cjs');
+var chunkXUQ4KRTT_cjs = require('./chunk-XUQ4KRTT.cjs');
+var chunkXAIJNGTU_cjs = require('./chunk-XAIJNGTU.cjs');
+var chunkNGFTSRKO_cjs = require('./chunk-NGFTSRKO.cjs');
 var chunkNZM3M5IR_cjs = require('./chunk-NZM3M5IR.cjs');
 var chunkJVWLXVYG_cjs = require('./chunk-JVWLXVYG.cjs');
 var chunkEANGKAKG_cjs = require('./chunk-EANGKAKG.cjs');
@@ -614,7 +614,7 @@ function ActivitySequence({
     }
     if (activity.type === "multiple-choice") {
       return /* @__PURE__ */ jsxRuntime.jsx(
-        chunkX4YU6BX7_cjs.MultipleChoice,
+        chunkZME5FMED_cjs.MultipleChoice,
         {
           data: activity,
           ...shuffleSeed !== void 0 ? { shuffleSeed } : {},
@@ -623,11 +623,11 @@ function ActivitySequence({
       );
     }
     if (activity.type === "fill-in-the-blanks") {
-      return /* @__PURE__ */ jsxRuntime.jsx(chunkJH77MAON_cjs.FillInTheBlanks, { data: activity, ...childProps });
+      return /* @__PURE__ */ jsxRuntime.jsx(chunkXUQ4KRTT_cjs.FillInTheBlanks, { data: activity, ...childProps });
     }
     if (activity.type === "gap-select") {
       return /* @__PURE__ */ jsxRuntime.jsx(
-        chunk3SJ7TVL6_cjs.GapSelect,
+        chunkXAIJNGTU_cjs.GapSelect,
         {
           data: activity,
           ...shuffleSeed !== void 0 ? { shuffleSeed } : {},
@@ -636,7 +636,7 @@ function ActivitySequence({
       );
     }
     if (activity.type === "dictation") {
-      return /* @__PURE__ */ jsxRuntime.jsx(chunk7GYAUA56_cjs.Dictation, { data: activity, ...childProps });
+      return /* @__PURE__ */ jsxRuntime.jsx(chunkNGFTSRKO_cjs.Dictation, { data: activity, ...childProps });
     }
     if (activity.type === "read-aloud") {
       const slotRecordingBinding = recordingBindingFor(slot);
@@ -745,5 +745,5 @@ function ActivitySequence({
 }
 
 exports.ActivitySequence = ActivitySequence;
-//# sourceMappingURL=chunk-TXMP5AOW.cjs.map
-//# sourceMappingURL=chunk-TXMP5AOW.cjs.map
+//# sourceMappingURL=chunk-2X2NZF46.cjs.map
+//# sourceMappingURL=chunk-2X2NZF46.cjs.map