@intellectif/lk-react 23.0.1 → 23.1.1

package/dist/ai/LkAiProvider.d.cts

@@ -1,73 +1,2 @@
-import { AiExplanationRequest, AiTextResult, AiHintRequest, AiWritingFeedbackRequest, AiWritingFeedbackResult } from '@intellectif/lk-core';
-import { ReactNode } from 'react';
-
-/**
- * The model a host runs for learners, as the components call it. The SDK never
- * calls a model, holds a key or writes a prompt: each port is the host's
- * function — usually a request to its own server, which holds the key and the
- * prompt and chooses the model.
- *
- * A port is called only when the learner asks — a button, never on render —
- * and gets an `AbortSignal` that fires when the answer it was asked about goes
- * away. Whatever it resolves to is checked before a learner sees it: see
- * `checkAiExplanation` and `checkAiHint` in lk-core. A port that rejects, or
- * resolves to something refused, costs the learner the help, never the
- * question.
- *
- * Leave a port out to switch that feature off. Nothing AI renders in `exam`,
- * whatever is passed.
- */
-interface LearnerAi {
-    /** Explains a graded answer. */
-    explain?: (request: AiExplanationRequest, options: {
-        signal: AbortSignal;
-    }) => Promise<AiTextResult>;
-    /** Writes the next hint for an answer not yet submitted. */
-    hint?: (request: AiHintRequest, options: {
-        signal: AbortSignal;
-    }) => 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,
-     * 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;
-}
-interface LkAiProviderProps {
-    ai: LearnerAi;
-    children: ReactNode;
-}
-/**
- * Supplies the host's AI ports to every activity beneath, as `LkIntlProvider`
- * supplies strings. A component's own `ai` prop wins over it, whole.
- *
- * ```tsx
- * <LkAiProvider ai={{
- *   explain: (request, { signal }) => api.explain(request, signal),
- *   hint: (request, { signal }) => api.hint(request, signal),
- *   learnerLocale: learner.language,
- * }}>
- *   <ActivitySequence … />
- * </LkAiProvider>
- * ```
- */
-declare function LkAiProvider({ ai, children }: LkAiProviderProps): React.JSX.Element;
-/** The ports in force: a component's own, else the provider's, else none. */
-declare function useLearnerAi(override?: LearnerAi): LearnerAi | undefined;
-
-export { type LearnerAi, LkAiProvider, type LkAiProviderProps, useLearnerAi };
+import { i as useLearnerAi, n as LkAiProvider, r as LkAiProviderProps, t as LearnerAi } from "../LkAiProvider-DAPpA3PQ.cjs";
+export { LearnerAi, LkAiProvider, LkAiProviderProps, useLearnerAi };

package/dist/ai/LkAiProvider.d.ts

@@ -1,73 +1,2 @@
-import { AiExplanationRequest, AiTextResult, AiHintRequest, AiWritingFeedbackRequest, AiWritingFeedbackResult } from '@intellectif/lk-core';
-import { ReactNode } from 'react';
-
-/**
- * The model a host runs for learners, as the components call it. The SDK never
- * calls a model, holds a key or writes a prompt: each port is the host's
- * function — usually a request to its own server, which holds the key and the
- * prompt and chooses the model.
- *
- * A port is called only when the learner asks — a button, never on render —
- * and gets an `AbortSignal` that fires when the answer it was asked about goes
- * away. Whatever it resolves to is checked before a learner sees it: see
- * `checkAiExplanation` and `checkAiHint` in lk-core. A port that rejects, or
- * resolves to something refused, costs the learner the help, never the
- * question.
- *
- * Leave a port out to switch that feature off. Nothing AI renders in `exam`,
- * whatever is passed.
- */
-interface LearnerAi {
-    /** Explains a graded answer. */
-    explain?: (request: AiExplanationRequest, options: {
-        signal: AbortSignal;
-    }) => Promise<AiTextResult>;
-    /** Writes the next hint for an answer not yet submitted. */
-    hint?: (request: AiHintRequest, options: {
-        signal: AbortSignal;
-    }) => 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,
-     * 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;
-}
-interface LkAiProviderProps {
-    ai: LearnerAi;
-    children: ReactNode;
-}
-/**
- * Supplies the host's AI ports to every activity beneath, as `LkIntlProvider`
- * supplies strings. A component's own `ai` prop wins over it, whole.
- *
- * ```tsx
- * <LkAiProvider ai={{
- *   explain: (request, { signal }) => api.explain(request, signal),
- *   hint: (request, { signal }) => api.hint(request, signal),
- *   learnerLocale: learner.language,
- * }}>
- *   <ActivitySequence … />
- * </LkAiProvider>
- * ```
- */
-declare function LkAiProvider({ ai, children }: LkAiProviderProps): React.JSX.Element;
-/** The ports in force: a component's own, else the provider's, else none. */
-declare function useLearnerAi(override?: LearnerAi): LearnerAi | undefined;
-
-export { type LearnerAi, LkAiProvider, type LkAiProviderProps, useLearnerAi };
+import { i as useLearnerAi, n as LkAiProvider, r as LkAiProviderProps, t as LearnerAi } from "../LkAiProvider-QdEcIhoo.js";
+export { LearnerAi, LkAiProvider, LkAiProviderProps, useLearnerAi };

package/dist/ai/LkAiProvider.js

@@ -1,4 +1,35 @@
 'use client';
-export { LkAiProvider, useLearnerAi } from '../chunk-RX3A6KIY.js';
-//# sourceMappingURL=LkAiProvider.js.map
+"use client";
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/ai/LkAiProvider.tsx
+const LkAiContext = createContext(null);
+/**
+* Supplies the host's AI ports to every activity beneath, as `LkIntlProvider`
+* supplies strings. A component's own `ai` prop wins over it, whole.
+*
+* ```tsx
+* <LkAiProvider ai={{
+*   explain: (request, { signal }) => api.explain(request, signal),
+*   hint: (request, { signal }) => api.hint(request, signal),
+*   learnerLocale: learner.language,
+* }}>
+*   <ActivitySequence … />
+* </LkAiProvider>
+* ```
+*/
+function LkAiProvider({ ai, children }) {
+	return /* @__PURE__ */ jsx(LkAiContext.Provider, {
+		value: ai,
+		children
+	});
+}
+/** The ports in force: a component's own, else the provider's, else none. */
+function useLearnerAi(override) {
+	const context = useContext(LkAiContext);
+	return override ?? context ?? void 0;
+}
+//#endregion
+export { LkAiProvider, useLearnerAi };
+
 //# sourceMappingURL=LkAiProvider.js.map

package/dist/ai/LkAiProvider.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"LkAiProvider.js"}
+{"version":3,"file":"LkAiProvider.js","names":[],"sources":["../../src/ai/LkAiProvider.tsx"],"sourcesContent":["'use client';\n\nimport type {\n  AiCoachingRequest,\n  AiCoachingResult,\n  AiExplanationRequest,\n  AiHintRequest,\n  AiTextResult,\n  AiWritingFeedbackRequest,\n  AiWritingFeedbackResult,\n} from '@intellectif/lk-core';\nimport { createContext, type ReactNode, useContext } from 'react';\n\n/**\n * The model a host runs for learners, as the components call it. The SDK never\n * calls a model, holds a key or writes a prompt: each port is the host's\n * function — usually a request to its own server, which holds the key and the\n * prompt and chooses the model.\n *\n * A port is called only when the learner asks — a button, never on render —\n * and gets an `AbortSignal` that fires when the answer it was asked about goes\n * away. Whatever it resolves to is checked before a learner sees it: see\n * `checkAiExplanation` and `checkAiHint` in lk-core. A port that rejects, or\n * resolves to something refused, costs the learner the help, never the\n * question.\n *\n * Leave a port out to switch that feature off. Nothing AI renders in `exam`,\n * whatever is passed.\n */\nexport interface LearnerAi {\n  /** Explains a graded answer. */\n  explain?: (\n    request: AiExplanationRequest,\n    options: { signal: AbortSignal },\n  ) => Promise<AiTextResult>;\n  /** Writes the next hint for an answer not yet submitted. */\n  hint?: (request: AiHintRequest, options: { signal: AbortSignal }) => Promise<AiTextResult>;\n  /** The most hints a learner can ask for on one question. Default 3, at most 10. */\n  maxHints?: number;\n  /**\n   * Gives feedback on a draft of a written response, before the learner\n   * submits it: the overall feedback as text, corrections that quote the\n   * draft, and a judgement per rubric criterion. See `checkAiWritingFeedback`\n   * in lk-core for what is refused.\n   */\n  writingFeedback?: (\n    request: AiWritingFeedbackRequest,\n    options: { signal: AbortSignal },\n  ) => Promise<AiWritingFeedbackResult>;\n  /** How many times a learner can ask for feedback on one written response. Default 3, at most 10. */\n  maxWritingFeedback?: number;\n  /**\n   * Coaches a learner on a graded reading aloud: what the speech engine's\n   * marks mean and how to practise, word by word. The marks are the engine's\n   * and are never re-scored; coaching on a word the engine did not mark, or a\n   * sound it did not report, is refused whole. See `checkAiCoaching` in\n   * lk-core. One coaching per reading.\n   */\n  pronunciationCoaching?: (\n    request: AiCoachingRequest,\n    options: { signal: AbortSignal },\n  ) => Promise<AiCoachingResult>;\n  /**\n   * The language to write explanations, hints, feedback and coaching in, as a tag (`es`,\n   * `pt-BR`). Defaults to the component's `locale`: the interface language,\n   * which the buttons around the help are in, and usually the right one. In a\n   * language course it need not be the item's — English items, explained in\n   * Spanish — and the item's own language reaches your port as `facts.locale`.\n   */\n  learnerLocale?: string;\n}\n\nconst LkAiContext = createContext<LearnerAi | null>(null);\n\nexport interface LkAiProviderProps {\n  ai: LearnerAi;\n  children: ReactNode;\n}\n\n/**\n * Supplies the host's AI ports to every activity beneath, as `LkIntlProvider`\n * supplies strings. A component's own `ai` prop wins over it, whole.\n *\n * ```tsx\n * <LkAiProvider ai={{\n *   explain: (request, { signal }) => api.explain(request, signal),\n *   hint: (request, { signal }) => api.hint(request, signal),\n *   learnerLocale: learner.language,\n * }}>\n *   <ActivitySequence … />\n * </LkAiProvider>\n * ```\n */\nexport function LkAiProvider({ ai, children }: LkAiProviderProps): React.JSX.Element {\n  return <LkAiContext.Provider value={ai}>{children}</LkAiContext.Provider>;\n}\n\n/** The ports in force: a component's own, else the provider's, else none. */\nexport function useLearnerAi(override?: LearnerAi): LearnerAi | undefined {\n  const context = useContext(LkAiContext);\n  return override ?? context ?? undefined;\n}\n"],"mappings":";;;;AAwEA,MAAM,cAAc,cAAgC,IAAI;;;;;;;;;;;;;;;AAqBxD,SAAgB,aAAa,EAAE,IAAI,YAAkD;CACnF,OAAO,oBAAC,YAAY,UAAb;EAAsB,OAAO;EAAK;CAA+B,CAAA;AAC1E;;AAGA,SAAgB,aAAa,UAA6C;CACxE,MAAM,UAAU,WAAW,WAAW;CACtC,OAAO,YAAY,WAAW,KAAA;AAChC"}

package/dist/ai/useAiHelp.cjs

@@ -1,24 +1,8 @@
 'use client';
-'use strict';
-
-var chunk6RIM5EQP_cjs = require('../chunk-6RIM5EQP.cjs');
-require('../chunk-OJGTJOWI.cjs');
-require('../chunk-J2QIHZ3H.cjs');
-require('../chunk-54DX6SLS.cjs');
-
-
-
-Object.defineProperty(exports, "useAiExplanation", {
-  enumerable: true,
-  get: function () { return chunk6RIM5EQP_cjs.useAiExplanation; }
-});
-Object.defineProperty(exports, "useAiHints", {
-  enumerable: true,
-  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
+"use client";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_useAiHelp = require("../useAiHelp-h9yOLFqt.cjs");
+exports.useAiCoaching = require_useAiHelp.useAiCoaching;
+exports.useAiExplanation = require_useAiHelp.useAiExplanation;
+exports.useAiHints = require_useAiHelp.useAiHints;
+exports.useAiWritingFeedback = require_useAiHelp.useAiWritingFeedback;

package/dist/ai/useAiHelp.d.cts

@@ -1,96 +1,94 @@
-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';
-
+import { t as LearnerAi } from "../LkAiProvider-DAPpA3PQ.cjs";
+import { a as RenderMode, s as RenderableActivity } from "../types-BOQd93x3.cjs";
+import { AiCoaching, AiTextResult, AiWritingFeedback, DeliveryPolicy, GradeRecord, InteractionEvent, ItemOutcome, LearnerResponse, ReadAloudData, SpeechAssessment } from "@intellectif/lk-core";
+//#region src/ai/useAiHelp.d.ts
 /**
  * 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;
-    /**
-     * The delivery policy your question was handed. The paper around the
-     * question holds as well — a set that switched AI hints off keeps them off
-     * here, whatever is passed — so leaving it out never turns anything on.
-     */
-    delivery?: DeliveryPolicy | null;
+export 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;
+  /**
+   * The delivery policy your question was handed. The paper around the
+   * question holds as well — a set that switched AI hints off keeps them off
+   * here, whatever is passed — so leaving it out never turns anything on.
+   */
+  delivery?: DeliveryPolicy | null;
 }
-interface AiExplanationInput extends AiHelpSituation {
-    /** The grade of record, which `review` explains. */
-    outcome?: ItemOutcome;
+export 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;
+export 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;
+export 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;
+export 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
@@ -124,7 +122,7 @@ interface AiHintsHelp {
  * 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;
+export 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.
@@ -147,40 +145,40 @@ declare function useAiExplanation(input: AiExplanationInput): AiExplanationHelp;
  * 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;
-interface AiWritingFeedbackInput extends AiHelpSituation {
-    /** A disabled question takes no feedback, as it takes no answer. */
-    disabled?: boolean;
+export declare function useAiHints(input: AiHintsInput): AiHintsHelp;
+export 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;
+export 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
@@ -202,6 +200,85 @@ interface AiWritingFeedbackHelp {
  * 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, type AiWritingFeedbackHelp, type AiWritingFeedbackInput, useAiExplanation, useAiHints, useAiWritingFeedback };
+export declare function useAiWritingFeedback(input: AiWritingFeedbackInput): AiWritingFeedbackHelp;
+export interface AiCoachingInput {
+  /**
+   * The read-aloud item, as `data` is given to `<ReadAloud>` — or as much of
+   * one as coaching reads: its id, title, text and language, and the author's
+   * `instructions` and `ai` settings where it has them.
+   */
+  data: Pick<ReadAloudData, 'id' | 'title' | 'referenceText' | 'locale'> & Partial<Pick<ReadAloudData, 'instructions' | 'ai'>>;
+  /**
+   * The speech engine's assessment of the take, as the learner is shown it.
+   * When given, it is the marks — each word's, with its sounds and what each
+   * was heard as — and the only ones: see `aiCoachingRequest` in lk-core.
+   */
+  assessment?: SpeechAssessment | null;
+  /**
+   * The grade of record. Its score is context for the model; without an
+   * assessment, its word details are the marks, and they carry no sounds.
+   */
+  grade?: GradeRecord | null;
+  /**
+   * Pass on the `renderMode` your reading was given. Coaching is never offered
+   * in `exam`, and an `exam` around the reading wins over anything passed here.
+   */
+  renderMode?: RenderMode;
+  /** The AI ports to use, overriding {@link LkAiProvider}'s for this reading. */
+  ai?: LearnerAi;
+  /** The interface language: the default language for what a model writes. */
+  locale?: string;
+  /** Where `ai-coaching-shown` and `ai-help-refused` go. */
+  onInteraction?: (event: InteractionEvent) => void;
+  /**
+   * The delivery policy your reading was handed. Coaching needs feedback shown
+   * and AI explanations allowed; the paper around the reading holds as well.
+   */
+  delivery?: DeliveryPolicy | null;
+}
+export interface AiCoachingHelp {
+  /**
+   * Whether to offer coaching at all: a `pronunciationCoaching` port is
+   * present, there are marks to coach, the mode is not `exam`, the item's
+   * author left explanations on, and the paper shows feedback and allows AI
+   * explanations.
+   */
+  offered: boolean;
+  status: 'idle' | 'loading' | 'shown' | 'unavailable';
+  /**
+   * What to show, once it has arrived and been checked: the coaching's text,
+   * and the words it works on in reading order, each with its tip and, where
+   * the engine reported one, the sound. All of it is text, never HTML.
+   */
+  coaching: AiCoaching | null;
+  /**
+   * Asks the port, when the learner presses something. Does nothing while a
+   * call is on its way, once coaching is shown — one per reading — or where
+   * `offered` is false. One identity for the life of the reading.
+   */
+  ask: () => void;
+}
+/**
+ * "Coach me on this reading", without the SDK's own button and panel: the
+ * rules, the call, the checks and the record, for marks you draw yourself.
+ *
+ * It is what `<PronunciationFeedback>` and `<ReadAloud>` use, so a host's own
+ * marks get coaching on the same terms: never in `exam`, never where the
+ * item's author switched explanations off, and never coaching on a word the
+ * engine did not mark or a sound it did not report — which is refused whole.
+ *
+ * ```tsx
+ * const { offered, status, coaching, ask } = useAiCoaching({
+ *   data: item, assessment, grade, renderMode, ai,
+ * });
+ * ```
+ *
+ * **Say who wrote it**, as the SDK's own panel does: "Written by AI. It can make
+ * mistakes." The marks beside it are the engine's; the coaching is a model's.
+ *
+ * Another reading — other marks, another text — drops the coaching and
+ * abandons a call still on its way, as the caller unmounting does.
+ */
+export declare function useAiCoaching(input: AiCoachingInput): AiCoachingHelp;
+//#endregion
+//# sourceMappingURL=useAiHelp.d.cts.map

package/dist/ai/useAiHelp.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAiHelp.d.cts","names":[],"sources":["../../src/ai/useAiHelp.ts"],"mappings":";;;;;;;;;iBA6CiB;;EAEf,MAAM;;EAEN,UAAU;;EAEV;;;;;;;;EAQA,aAAa;;;;;;EAMb,KAAK;;EAEL;;EAEA,iBAAiB,OAAO;;;;;;EAMxB,WAAW;;iBAGI,2BAA2B;;EAE1C,UAAU;;iBAGK;;;;;;EAMf;EACA;;EAEA,aAAa;;;;;;;;;EASb;;iBAGe,qBAAqB;;EAEpC;;iBAGe;;;;;;;;EAQf;EACA;;EAEA,gBAAgB;;EAEhB;;EAEA;;;;;;EAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAwEc,iBAAiB,OAAO,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;wBA8H7C,WAAW,OAAO,eAAe;iBA2HhC,+BAA+B;;EAE9C;;iBAGe;;;;;;;;EAQf;EACA;;EAEA,mBAAmB;;EAEnB,QAAQ;;;;;EAKR;;EAEA;;EAEA;;;;;;EAMA;;;;;;;;;;;;;;;;;;;;;;wBAiCc,qBAAqB,OAAO,yBAAyB;iBA4IpD;;;;;;EAMf,MAAM,KAAK,8DACT,QAAQ,KAAK;;;;;;EAMf,aAAa;;;;;EAKb,QAAQ;;;;;EAKR,aAAa;;EAEb,KAAK;;EAEL;;EAEA,iBAAiB,OAAO;;;;;EAKxB,WAAW;;iBAGI;;;;;;;EAOf;EACA;;;;;;EAMA,UAAU;;;;;;EAMV;;;;;;;;;;;;;;;;;;;;;;;wBA4Bc,cAAc,OAAO,kBAAkB"}