@intellectif/lk-react 18.0.0 → 19.0.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @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
+
+- 50c3285: A question a host draws inside `<ActivitySequence>` gets everything one the SDK draws has, and the AI
+  rules are available without the SDK's buttons.
+
+  - **`renderers` overrides get a `question` prop** (`SequenceQuestion`), the pager's half of the
+    contract, as `renderQuestion` gave one to `<InteractiveVideo>` in 16.1.0:
+    - `active` — whether this is the question on screen. **Stop the microphone, any timer and any
+      speech when it turns `false`:** the pager pauses the media inside the question and stops the
+      recorders the SDK started, but cannot reach one it did not create;
+    - `setPending(true/false)` — work of your own is on its way (an upload, a save, a judgement).
+      `onFinished` and `onComplete` wait for it, so a set is never reported a moment before the last
+      answer settles. Call it with `false` however the work ends, a failure included;
+    - `portalContainer` — a node inside this question's own pane. Portal a popover into it rather than
+      into `document.body`, and it is hidden when the learner pages away and painted with the question
+      in fullscreen;
+    - `clear()` — the learner withdrew their answer: the slot holds nothing again, and the set is
+      unfinished until it is answered again;
+    - `emit(type, payload?)` — an interaction, with this question's `activityId` and the time filled
+      in;
+    - `slot` — the identity to store the answer against, the same object `onSubmit` is handed.
+  - **Every call keeps one identity for the life of the set**, `onSubmit` and `onComplete` included, so
+    a renderer may hold them in an effect and a host that re-renders on every keystroke does not re-run
+    it.
+  - **New: `useAiHints` and `useAiExplanation`** (`@intellectif/lk-react/ai/useAiHelp`, also on the
+    root) — AI help for a question you draw yourself: the same rules, facts, checks and records the
+    bundled components use, with your own markup. `ask` does nothing where the rules say no, so a page
+    drawing its own button reaches no model in an `exam`. The SDK's own components are built on these
+    hooks, so there is one implementation of the rules and not two.
+  - **The paper decides the mode.** A question inside `<ActivitySequence>` or `<InteractiveVideo>` now
+    knows the mode it is being delivered in, so the hooks refuse help on an `exam` paper even when the
+    host does not pass `renderMode` to them, or passes `practice` — which a component that defaults it
+    can do inside an exam. Without that, a host's own question under an `LkAiProvider` could reach a
+    model on a paper of record.
+
+  `ActivityRenderer` is now `ComponentType<ActivityProps & { question?: SequenceQuestion }>`. A
+  renderer written as `ComponentType<ActivityProps>` still fits and simply ignores the new prop; only
+  assigning an `ActivityRenderer` _back_ to a `ComponentType<ActivityProps>` variable needs a widened
+  annotation.
+
+  See `docs/ai.md` and the `renderers` documentation on `<ActivitySequence>`.
+
 ## 18.0.0
 
 ### Patch 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.
@@ -82,7 +82,8 @@ export function Demo() {
 - **`shuffleSeed`** — one seed drives question order *and* each item's option order, so a review render reproduces exactly the arrangement the learner sat. Shuffling in `exam` / `review` mode **requires** it.
 - **`<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.
+- **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.
 - **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.
@@ -116,6 +117,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/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-B4kY-U0v.d.ts → WrittenResponse-CeHY5u3W.d.ts}

@@ -1,5 +1,5 @@
 import { XAPIStatement, WrittenResponseData, LearnerResponse, ItemOutcome, InteractionEvent, ThemeTokens } from '@intellectif/lk-core';
-import { f as Renderable, e as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './strings-PCYKWCwd.js';
+import { f as Renderable, e as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './types-BY-4S5Rd.js';
 
 /**
  * Payload delivered when the learner submits a written response. Grading is

package/dist/{WrittenResponse-Dl3zah22.d.cts → WrittenResponse-DT_Yqbq1.d.cts}

@@ -1,5 +1,5 @@
 import { XAPIStatement, WrittenResponseData, LearnerResponse, ItemOutcome, InteractionEvent, ThemeTokens } from '@intellectif/lk-core';
-import { f as Renderable, e as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './strings-BOPKhnS-.cjs';
+import { f as Renderable, e as RenderMode, H as HtmlSanitizer, M as MediaBudgetBinding, b as MediaTransportStrings, a as LkStringsOverride } from './types-DtPYG1hh.cjs';
 
 /**
  * Payload delivered when the learner submits a written response. Grading is

package/dist/ai/useAiHelp.cjs

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

package/dist/ai/useAiHelp.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"useAiHelp.cjs"}

package/dist/ai/useAiHelp.d.cts

@@ -0,0 +1,146 @@
+import { AiTextResult, LearnerResponse, InteractionEvent, ItemOutcome } from '@intellectif/lk-core';
+import { g as RenderableActivity, e as RenderMode } from '../types-DtPYG1hh.cjs';
+import { LearnerAi } from './LkAiProvider.cjs';
+import '../machine-CuwKqWXC.cjs';
+import 'react';
+
+/**
+ * The question AI help is being asked about, as the SDK's own components know
+ * it. A host drawing its own question passes what it has; everything optional
+ * defaults to what the components pass.
+ */
+interface AiHelpSituation {
+    /** The question, as `data` is given to any activity component. */
+    data: RenderableActivity;
+    /** The learner's answer as it stands: submitted, restored, or being written. */
+    response: LearnerResponse;
+    /** Whether the learner has committed that answer. */
+    submitted: boolean;
+    /**
+     * Pass on the `renderMode` your question was given. Left out, the paper
+     * around the question answers for it — a question inside `<ActivitySequence>`
+     * or `<InteractiveVideo>` knows its mode — and `practice` only where there is
+     * no paper at all. An `exam` around the question wins over anything passed
+     * here.
+     */
+    renderMode?: RenderMode;
+    /**
+     * The AI ports to use, overriding {@link LkAiProvider}'s for this question.
+     * A question inside `<ActivitySequence>` or `<InteractiveVideo>` is handed
+     * the ports in force as `ai` — pass that straight in.
+     */
+    ai?: LearnerAi;
+    /** The interface language: the default language for what a model writes. */
+    locale?: string;
+    /** Where `ai-hint-shown` and `ai-explanation-shown` go. */
+    onInteraction?: (event: InteractionEvent) => void;
+}
+interface AiExplanationInput extends AiHelpSituation {
+    /** The grade of record, which `review` explains. */
+    outcome?: ItemOutcome;
+}
+interface AiExplanationHelp {
+    /**
+     * Whether to offer the learner an explanation at all: a port is present, the
+     * answer is graded, the type is one the SDK explains, and the author left
+     * explanations on. False in `exam`, always.
+     */
+    offered: boolean;
+    status: 'idle' | 'loading' | 'shown' | 'unavailable';
+    /** What to show, once it has arrived and been checked. Its `text` is text, never HTML. */
+    explanation: AiTextResult | null;
+    /**
+     * Asks the port, when the learner presses something. Does nothing while a
+     * call is on its way, and nothing at all where `offered` is false — so an
+     * exam cannot reach a model through this hook, whatever ports are in scope.
+     *
+     * One identity for the life of the question, so it is safe in an effect's
+     * dependencies.
+     */
+    ask: () => void;
+}
+interface AiHintsInput extends AiHelpSituation {
+    /** A disabled question gives no hints, as it takes no answer. */
+    disabled?: boolean;
+}
+interface AiHintsHelp {
+    /**
+     * Whether the learner may ask for hints here at all: a port is present, the
+     * mode is `practice`, the answer is not in, the question is not disabled or
+     * redacted, the type takes hints and the author left them on. It stays true
+     * once `used` reaches `limit` — there are no more to give, but the question
+     * is still one that gives them.
+     */
+    offered: boolean;
+    status: 'idle' | 'loading' | 'unavailable';
+    /** Every hint shown for this question, in the order they were given. */
+    hints: readonly AiTextResult[];
+    /** The host's `maxHints`, as a whole number from 1 to 10 (3 by default). */
+    limit: number;
+    /** How many hints have been shown. A refused hint is not counted. */
+    used: number;
+    /**
+     * Asks for the next hint. Does nothing at the limit, while a call is on its
+     * way, or where `offered` is false. One identity for the life of the
+     * question.
+     */
+    ask: () => void;
+}
+/**
+ * "Explain my answer", without the SDK's own button and panel: the rules, the
+ * call, the checks and the record, for a question you draw yourself.
+ *
+ * It is what `<MultipleChoice>` and the others use, so a host's own question
+ * offers help on exactly the same terms: never in `exam`, never where the
+ * item's author switched explanations off, and never an explanation whose
+ * verdict contradicts the grade the SDK computed.
+ *
+ * ```tsx
+ * const { offered, status, explanation, ask } = useAiExplanation({
+ *   data, response, submitted, renderMode, outcome, ai: question.ai,
+ * });
+ * if (!offered) return null;
+ * return explanation === null ? (
+ *   <button type="button" onClick={ask} aria-busy={status === 'loading'}>Explain my answer</button>
+ * ) : (
+ *   <section>
+ *     <p>{explanation.text}</p>
+ *     <p>Written by AI. It can make mistakes.</p>
+ *   </section>
+ * );
+ * ```
+ *
+ * **Say who wrote it.** The SDK's own panel carries "Written by AI. It can make
+ * mistakes."; a page that drops that line passes a model's words off as the
+ * course's.
+ *
+ * When the answer or its grade changes, the explanation is dropped and a call
+ * still on its way is abandoned — a late explanation never lands beside an
+ * answer it was not written for — as it is when the caller unmounts.
+ */
+declare function useAiExplanation(input: AiExplanationInput): AiExplanationHelp;
+/**
+ * "Get a hint", without the SDK's own button and list: the rules, the call, the
+ * checks and the record, for a question you draw yourself.
+ *
+ * It is what `<MultipleChoice>` and the others use, so a host's own question
+ * gives hints on exactly the same terms: only in `practice` before submit, up
+ * to the host's limit, never on a redacted item or a type the SDK does not hint
+ * for, and never a hint that gives the answer away — which is refused rather
+ * than shown, and not counted.
+ *
+ * ```tsx
+ * const { offered, status, hints, used, limit, ask } = useAiHints({
+ *   data, response, submitted, renderMode, ai: question.ai,
+ * });
+ * ```
+ *
+ * **Say who wrote them**, as the SDK's own list does: "Written by AI. It can
+ * make mistakes."
+ *
+ * Keep the hints on screen after submit — the learner can see what they were
+ * given — while `offered` turns false. Another question starts with none.
+ */
+declare function useAiHints(input: AiHintsInput): AiHintsHelp;
+
+export { type AiExplanationHelp, type AiExplanationInput, type AiHelpSituation, type AiHintsHelp, type AiHintsInput, useAiExplanation, useAiHints };

package/dist/ai/useAiHelp.d.ts

@@ -0,0 +1,146 @@
+import { AiTextResult, LearnerResponse, InteractionEvent, ItemOutcome } from '@intellectif/lk-core';
+import { g as RenderableActivity, e as RenderMode } from '../types-BY-4S5Rd.js';
+import { LearnerAi } from './LkAiProvider.js';
+import '../machine-CuwKqWXC.js';
+import 'react';
+
+/**
+ * The question AI help is being asked about, as the SDK's own components know
+ * it. A host drawing its own question passes what it has; everything optional
+ * defaults to what the components pass.
+ */
+interface AiHelpSituation {
+    /** The question, as `data` is given to any activity component. */
+    data: RenderableActivity;
+    /** The learner's answer as it stands: submitted, restored, or being written. */
+    response: LearnerResponse;
+    /** Whether the learner has committed that answer. */
+    submitted: boolean;
+    /**
+     * Pass on the `renderMode` your question was given. Left out, the paper
+     * around the question answers for it — a question inside `<ActivitySequence>`
+     * or `<InteractiveVideo>` knows its mode — and `practice` only where there is
+     * no paper at all. An `exam` around the question wins over anything passed
+     * here.
+     */
+    renderMode?: RenderMode;
+    /**
+     * The AI ports to use, overriding {@link LkAiProvider}'s for this question.
+     * A question inside `<ActivitySequence>` or `<InteractiveVideo>` is handed
+     * the ports in force as `ai` — pass that straight in.
+     */
+    ai?: LearnerAi;
+    /** The interface language: the default language for what a model writes. */
+    locale?: string;
+    /** Where `ai-hint-shown` and `ai-explanation-shown` go. */
+    onInteraction?: (event: InteractionEvent) => void;
+}
+interface AiExplanationInput extends AiHelpSituation {
+    /** The grade of record, which `review` explains. */
+    outcome?: ItemOutcome;
+}
+interface AiExplanationHelp {
+    /**
+     * Whether to offer the learner an explanation at all: a port is present, the
+     * answer is graded, the type is one the SDK explains, and the author left
+     * explanations on. False in `exam`, always.
+     */
+    offered: boolean;
+    status: 'idle' | 'loading' | 'shown' | 'unavailable';
+    /** What to show, once it has arrived and been checked. Its `text` is text, never HTML. */
+    explanation: AiTextResult | null;
+    /**
+     * Asks the port, when the learner presses something. Does nothing while a
+     * call is on its way, and nothing at all where `offered` is false — so an
+     * exam cannot reach a model through this hook, whatever ports are in scope.
+     *
+     * One identity for the life of the question, so it is safe in an effect's
+     * dependencies.
+     */
+    ask: () => void;
+}
+interface AiHintsInput extends AiHelpSituation {
+    /** A disabled question gives no hints, as it takes no answer. */
+    disabled?: boolean;
+}
+interface AiHintsHelp {
+    /**
+     * Whether the learner may ask for hints here at all: a port is present, the
+     * mode is `practice`, the answer is not in, the question is not disabled or
+     * redacted, the type takes hints and the author left them on. It stays true
+     * once `used` reaches `limit` — there are no more to give, but the question
+     * is still one that gives them.
+     */
+    offered: boolean;
+    status: 'idle' | 'loading' | 'unavailable';
+    /** Every hint shown for this question, in the order they were given. */
+    hints: readonly AiTextResult[];
+    /** The host's `maxHints`, as a whole number from 1 to 10 (3 by default). */
+    limit: number;
+    /** How many hints have been shown. A refused hint is not counted. */
+    used: number;
+    /**
+     * Asks for the next hint. Does nothing at the limit, while a call is on its
+     * way, or where `offered` is false. One identity for the life of the
+     * question.
+     */
+    ask: () => void;
+}
+/**
+ * "Explain my answer", without the SDK's own button and panel: the rules, the
+ * call, the checks and the record, for a question you draw yourself.
+ *
+ * It is what `<MultipleChoice>` and the others use, so a host's own question
+ * offers help on exactly the same terms: never in `exam`, never where the
+ * item's author switched explanations off, and never an explanation whose
+ * verdict contradicts the grade the SDK computed.
+ *
+ * ```tsx
+ * const { offered, status, explanation, ask } = useAiExplanation({
+ *   data, response, submitted, renderMode, outcome, ai: question.ai,
+ * });
+ * if (!offered) return null;
+ * return explanation === null ? (
+ *   <button type="button" onClick={ask} aria-busy={status === 'loading'}>Explain my answer</button>
+ * ) : (
+ *   <section>
+ *     <p>{explanation.text}</p>
+ *     <p>Written by AI. It can make mistakes.</p>
+ *   </section>
+ * );
+ * ```
+ *
+ * **Say who wrote it.** The SDK's own panel carries "Written by AI. It can make
+ * mistakes."; a page that drops that line passes a model's words off as the
+ * course's.
+ *
+ * When the answer or its grade changes, the explanation is dropped and a call
+ * still on its way is abandoned — a late explanation never lands beside an
+ * answer it was not written for — as it is when the caller unmounts.
+ */
+declare function useAiExplanation(input: AiExplanationInput): AiExplanationHelp;
+/**
+ * "Get a hint", without the SDK's own button and list: the rules, the call, the
+ * checks and the record, for a question you draw yourself.
+ *
+ * It is what `<MultipleChoice>` and the others use, so a host's own question
+ * gives hints on exactly the same terms: only in `practice` before submit, up
+ * to the host's limit, never on a redacted item or a type the SDK does not hint
+ * for, and never a hint that gives the answer away — which is refused rather
+ * than shown, and not counted.
+ *
+ * ```tsx
+ * const { offered, status, hints, used, limit, ask } = useAiHints({
+ *   data, response, submitted, renderMode, ai: question.ai,
+ * });
+ * ```
+ *
+ * **Say who wrote them**, as the SDK's own list does: "Written by AI. It can
+ * make mistakes."
+ *
+ * Keep the hints on screen after submit — the learner can see what they were
+ * given — while `offered` turns false. Another question starts with none.
+ */
+declare function useAiHints(input: AiHintsInput): AiHintsHelp;
+
+export { type AiExplanationHelp, type AiExplanationInput, type AiHelpSituation, type AiHintsHelp, type AiHintsInput, useAiExplanation, useAiHints };

package/dist/ai/useAiHelp.js

@@ -0,0 +1,7 @@
+'use client';
+export { useAiExplanation, useAiHints } from '../chunk-YIYMBCPV.js';
+import '../chunk-YNDKAYW3.js';
+import '../chunk-TEAVPUMX.js';
+import '../chunk-PPFVTXGJ.js';
+//# sourceMappingURL=useAiHelp.js.map
+//# sourceMappingURL=useAiHelp.js.map

package/dist/ai/useAiHelp.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"useAiHelp.js"}