@intellectif/lk-react 23.1.0 → 23.1.2

package/dist/useAiHelp-B-ccDL5Q.js

@@ -0,0 +1,906 @@
+'use client';
+import { useLearnerAi } from "./ai/LkAiProvider.js";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { OPEN_DELIVERY_POLICY, aiAllowedByContent, aiCoachingRequest, aiExplanationRequest, aiHintRequest, aiSupports, aiWritingFeedbackRequest, checkAiCoaching, checkAiExplanation, checkAiHint, checkAiWritingFeedback, combineDeliveryPolicies } from "@intellectif/lk-core";
+//#region src/components/shared/sequence-slot.ts
+/** `null` outside a pager: a standalone component belongs to no slot. */
+const SequenceSlotContext = createContext(null);
+/**
+* The last take number handed out. Module-level and never reset, so a number
+* is unique for the life of the page: across mounts, across papers, and across
+* two pagers side by side. A result can therefore only ever match the take that
+* produced it, whatever slot and activity ids a later paper reuses — ids a host
+* chooses, and can repeat, never decide it.
+*/
+let lastTake = 0;
+/** A take number no other take on this page has had, or will have. */
+function mintTake() {
+	lastTake += 1;
+	return lastTake;
+}
+/**
+* The take each reported value belongs to. A `WeakMap` rather than a field, so
+* a response or a result a host receives carries no extra key it would persist
+* or compare, and the number never outlives the object.
+*/
+const takes = /* @__PURE__ */ new WeakMap();
+/** Marks `value` as produced by take `take`, and returns it. */
+function stampTake(value, take) {
+	takes.set(value, take);
+	return value;
+}
+/** The take `value` was produced by, or `undefined` when nothing stamped it. */
+function takeOf(value) {
+	return typeof value === "object" && value !== null ? takes.get(value) : void 0;
+}
+//#endregion
+//#region src/components/_internal.ts
+/**
+* Whether this is anything other than a production build — the one answer
+* every development check and the error boundary's stack trace read.
+*
+* **The literal `process.env.NODE_ENV`, spelled exactly so.** It is the one
+* expression bundlers replace at build time — Vite, webpack, esbuild, Next.js
+* and Rollup's replace plugin all substitute it — and a browser has no
+* `process` to read at run time. The reading this replaces,
+* `globalThis.process?.env?.NODE_ENV`, is not that expression, so no bundler
+* touched it, and in a browser it found no `process` and answered
+* "development" in every production app: learners were shown a stack trace
+* where each component's production fallback belonged. Tests running in Node
+* never saw it, because Node has a `process`.
+*
+* This package's own build must leave the literal in its output, for the
+* consumer's bundler to replace. A library build that substituted it would
+* freeze every consumer into whichever mode the library was built in.
+*
+* The `try` covers code that reaches a runtime unbundled, with no `process`
+* at all: that is development, as it always was.
+*/
+function isDevelopment() {
+	try {
+		return process.env.NODE_ENV !== "production";
+	} catch {
+		return true;
+	}
+}
+/**
+* Activity components cannot know the learner's identity: `ActivityProps`
+* carries none. They emit a structurally-valid statement with this anonymous
+* actor; real identity is applied by the useXAPI/LRS layer (XAPIConfig.actor).
+*/
+const ANONYMOUS_ACTOR = {
+	objectType: "Agent",
+	account: {
+		homePage: "https://github.com/intellectif/learning-kit",
+		name: "anonymous"
+	}
+};
+/** `data.id` is not an IRI; xAPI object ids must be. Wrap it as a URN. */
+function objectIdFor(id) {
+	return `urn:learning-kit:activity:${encodeURIComponent(id)}`;
+}
+/**
+* Random per-mount session id for the shuffle seed. `crypto.randomUUID` is
+* unavailable outside secure contexts (plain-http LAN/staging hosts), so a
+* Math.random fallback keeps the component from crashing there — the seed
+* only randomises presentation order, so cryptographic strength is not needed.
+*/
+function randomSessionId() {
+	const c = globalThis.crypto;
+	if (c?.randomUUID) return c.randomUUID();
+	return `s-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+}
+/**
+* The `correct` flag of a detail stored before lk-core 0.3, which carries it in
+* place of an `outcome`; `undefined` on any other detail. The type stopped
+* describing it in 1.0, but a grade of record stored then still has it. On a
+* blank, a gap or a word it meant the part was right; on a multiple-choice
+* option, that the learner acted rightly on it.
+*/
+function legacyCorrect(detail) {
+	const { correct } = detail;
+	return typeof correct === "boolean" ? correct : void 0;
+}
+/**
+* Whether a detail marks its blank, gap or word right: its `outcome`, or on a
+* detail stored before lk-core 0.3, its `correct` flag.
+*/
+function detailIsRight(detail) {
+	const outcome = detail.outcome;
+	return outcome === void 0 ? legacyCorrect(detail) === true : outcome === "correct";
+}
+/**
+* For the fallback of a dispatch over the built-in activity types — a
+* `switch` default, or the end of an `if` chain: `value` has type `never`
+* there only when every built-in type was handled above it, so a type lk-core
+* gains fails to compile here until it has a component. At runtime it does
+* nothing; what follows it decides what an unknown or custom type gets.
+*/
+function everyBuiltInTypeHandled(_value) {}
+//#endregion
+//#region src/ai/rules.ts
+/**
+* When AI help is offered, and what the SDK does with what a port answers.
+*
+* Internal: these are the rules behind {@link useAiHints} and
+* {@link useAiExplanation}, which are what a host calls. They live apart from
+* the hooks so the hooks' module exports nothing but the hooks themselves.
+*/
+/** The most hints a question gives when the host names no number, and the most it may name. */
+const DEFAULT_MAX_HINTS = 3;
+const MAX_HINTS_CEILING = 10;
+/** A host's limit as a whole number from 1 to 10; anything else is the default, 3. */
+function limitOf(asked) {
+	return typeof asked === "number" && Number.isInteger(asked) && asked >= 1 ? Math.min(asked, MAX_HINTS_CEILING) : DEFAULT_MAX_HINTS;
+}
+/** `maxHints` as a whole number from 1 to 10; anything else is the default. */
+function hintLimit(ai) {
+	return limitOf(ai?.maxHints);
+}
+/** `maxWritingFeedback` as a whole number from 1 to 10; anything else is the default. */
+function writingFeedbackLimit(ai) {
+	return limitOf(ai?.maxWritingFeedback);
+}
+/**
+* Whether the learner may ask for feedback on a draft: `practice`, before
+* submit, on a written response that is not disabled or redacted, whose author
+* left explanations on. The paper's policy must show feedback and solutions —
+* a correction is the right form beside a wrong one — and allow AI
+* explanations, which writing feedback is: a model's words about the
+* learner's own answer.
+*/
+function writingFeedbackOffered(input) {
+	const { data, renderMode, submitted, disabled } = input;
+	const delivery = input.delivery ?? OPEN_DELIVERY_POLICY;
+	return delivery.feedback && delivery.solutions && delivery.ai.explanations && renderMode === "practice" && !submitted && !disabled && data.redacted !== true && aiSupports(data.type, "writing-feedback") && aiAllowedByContent(data, "writing-feedback");
+}
+/**
+* Whether the learner may ask for a hint: `practice`, before submit, on a
+* question that is not disabled, of a type that takes hints, whose author left
+* hints on, and whole — a redacted item is an exam's, and gives none.
+*/
+function hintOffered(input) {
+	const { data, renderMode, submitted, disabled } = input;
+	const delivery = input.delivery ?? OPEN_DELIVERY_POLICY;
+	return delivery.hints && delivery.ai.hints && renderMode === "practice" && !submitted && !disabled && data.redacted !== true && aiSupports(data.type, "hint") && aiAllowedByContent(data, "hint");
+}
+/**
+* Whether the learner may ask for an explanation: of a graded answer — in
+* `practice` once submitted, or in `review` when the grade of record is
+* scored — of a type the SDK explains, whose author left explanations on.
+* Never in `exam`.
+*/
+function explanationOffered(input) {
+	const { data, renderMode, submitted, outcome } = input;
+	const delivery = input.delivery ?? OPEN_DELIVERY_POLICY;
+	if (!delivery.feedback || !delivery.solutions || !delivery.ai.explanations) return false;
+	return (renderMode === "practice" && submitted || renderMode === "review" && outcome?.status === "scored") && aiSupports(data.type, "explanation") && aiAllowedByContent(data, "explanation");
+}
+/**
+* Whether the learner may ask for coaching on a reading: one whose marks are
+* on screen — which a read-aloud has only once it is graded, in `practice` or
+* in `review` — never in `exam`, on a read-aloud whose author left
+* explanations on. The paper's policy must show feedback, since the marks are
+* feedback, and allow AI explanations, which coaching is: a model's words
+* about the learner's own answer. Not `solutions`: a read-aloud hides no
+* answer, and its text is on screen throughout.
+*/
+function coachingOffered(input) {
+	const { data, renderMode, marked } = input;
+	const delivery = input.delivery ?? OPEN_DELIVERY_POLICY;
+	return delivery.feedback && delivery.ai.explanations && renderMode !== "exam" && marked && aiSupports(data.type, "pronunciation-coaching") && aiAllowedByContent(data, "pronunciation-coaching");
+}
+/** Calls a port, turning a synchronous throw into a rejection. */
+function callPort(call) {
+	try {
+		return Promise.resolve(call());
+	} catch (error) {
+		return Promise.reject(error);
+	}
+}
+/** Tells a developer why a port's answer was not shown. Silent in production. */
+function warnRefused(feature, activityId, reason) {
+	if (isDevelopment()) console.warn(`learning-kit: the AI ${feature} for "${activityId}" was not shown (${reason}). The learner saw "not available" instead.`);
+}
+/** The language to write in: the host's choice for the learner, else the interface language. */
+const localeOf = (ai, locale) => {
+	const chosen = ai?.learnerLocale ?? locale;
+	return chosen === void 0 ? {} : { learnerLocale: chosen };
+};
+/** What an explanation is about: when any of it changes, the explanation shown no longer is. */
+function explanationKey(renderMode, submitted, response, outcome) {
+	let graded = "";
+	if (outcome !== void 0) graded = `${outcome.status}:${"score" in outcome ? outcome.score : ""}`;
+	return `${renderMode}|${submitted}|${graded}|${JSON.stringify(response)}`;
+}
+//#endregion
+//#region src/ai/useAiHelp.ts
+/**
+* The mode a question is answered in: what the caller says, and what the paper
+* around it says.
+*
+* A host drawing its own question is given `renderMode` like every other prop
+* and is expected to pass it on, but nothing makes it — and a hook that took
+* `practice` on trust would offer hints on a paper of record, as soon as an
+* `LkAiProvider` sat anywhere above the pager. So an `exam` around the question
+* wins, and where the caller says nothing the paper answers for it. A question
+* standing on its own belongs to no paper, and is `practice` as before.
+*/
+function modeInForce(asked, around) {
+	if (around === "exam") return "exam";
+	return asked ?? around ?? "practice";
+}
+/**
+* What the record of help a learner was shown carries beside the fact of it:
+* who wrote it, and what the call cost — both only where the port sent them.
+*
+* The text is deliberately absent. A host that wants to keep what a learner
+* read has it in its own port; an interaction is a record of what happened, and
+* is kept for every learner and every question.
+*/
+function shownPayload(result) {
+	return {
+		...result.provenance !== void 0 ? { provenance: result.provenance } : {},
+		...result.usage !== void 0 ? { usage: result.usage } : {}
+	};
+}
+/**
+* "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.
+*/
+function useAiExplanation(input) {
+	const { data, response, submitted, outcome } = input;
+	const around = useContext(SequenceSlotContext);
+	const renderMode = modeInForce(input.renderMode, around?.renderMode);
+	const delivery = combineDeliveryPolicies(input.delivery, around?.delivery);
+	const ai = useLearnerAi(input.ai);
+	const resetKey = explanationKey(renderMode, submitted, response, outcome);
+	const [state, setState] = useState({
+		key: resetKey,
+		status: "idle"
+	});
+	const run = useRef(0);
+	const controller = useRef(null);
+	const current = state.key === resetKey ? state : {
+		key: resetKey,
+		status: "idle"
+	};
+	const offered = ai?.explain !== void 0 && explanationOffered({
+		data,
+		renderMode,
+		submitted,
+		outcome,
+		delivery
+	});
+	const latest = useRef({
+		input,
+		renderMode,
+		ai,
+		resetKey,
+		offered,
+		current
+	});
+	latest.current = {
+		input,
+		renderMode,
+		ai,
+		resetKey,
+		offered,
+		current
+	};
+	useEffect(() => {
+		return () => {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+		};
+	}, [resetKey]);
+	const ask = useCallback(() => {
+		const now = latest.current;
+		const port = now.ai?.explain;
+		if (port === void 0 || !now.offered || now.current.status === "loading") return;
+		const key = now.resetKey;
+		const request = aiExplanationRequest({
+			data: now.input.data,
+			response: now.input.response,
+			...now.renderMode === "review" && now.input.outcome !== void 0 ? { outcome: now.input.outcome } : {},
+			...localeOf(now.ai, now.input.locale)
+		});
+		if (request === null) {
+			setState({
+				key,
+				status: "unavailable"
+			});
+			return;
+		}
+		run.current += 1;
+		const mine = run.current;
+		controller.current?.abort();
+		const abort = new AbortController();
+		controller.current = abort;
+		setState({
+			key,
+			status: "loading"
+		});
+		callPort(() => port(request, { signal: abort.signal })).then((raw) => {
+			if (run.current !== mine) return;
+			const checked = checkAiExplanation(raw, request);
+			if (!checked.ok) {
+				warnRefused("explanation", now.input.data.id, checked.refusal);
+				setState({
+					key,
+					status: "unavailable"
+				});
+				latest.current.input.onInteraction?.({
+					type: "ai-help-refused",
+					activityId: now.input.data.id,
+					timestamp: Date.now(),
+					payload: {
+						feature: "explanation",
+						reason: checked.refusal
+					}
+				});
+				return;
+			}
+			setState({
+				key,
+				status: "shown",
+				result: checked.result
+			});
+			latest.current.input.onInteraction?.({
+				type: "ai-explanation-shown",
+				activityId: now.input.data.id,
+				timestamp: Date.now(),
+				payload: shownPayload(checked.result)
+			});
+		}, () => {
+			if (run.current === mine) setState({
+				key,
+				status: "unavailable"
+			});
+		});
+	}, []);
+	return {
+		offered,
+		status: current.status,
+		explanation: current.status === "shown" ? current.result : null,
+		ask
+	};
+}
+/**
+* "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.
+*/
+function useAiHints(input) {
+	const { data, submitted } = input;
+	const around = useContext(SequenceSlotContext);
+	const renderMode = modeInForce(input.renderMode, around?.renderMode);
+	const delivery = combineDeliveryPolicies(input.delivery, around?.delivery);
+	const disabled = input.disabled === true;
+	const ai = useLearnerAi(input.ai);
+	const resetKey = data.id;
+	const [state, setState] = useState({
+		key: resetKey,
+		hints: [],
+		status: "idle"
+	});
+	const run = useRef(0);
+	const controller = useRef(null);
+	const current = state.key === resetKey ? state : {
+		key: resetKey,
+		hints: [],
+		status: "idle"
+	};
+	const offered = ai?.hint !== void 0 && hintOffered({
+		data,
+		renderMode,
+		submitted,
+		disabled,
+		delivery
+	});
+	const limit = hintLimit(ai);
+	const latest = useRef({
+		input,
+		renderMode,
+		ai,
+		offered,
+		limit,
+		current
+	});
+	latest.current = {
+		input,
+		renderMode,
+		ai,
+		offered,
+		limit,
+		current
+	};
+	useEffect(() => {
+		return () => {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+		};
+	}, [resetKey]);
+	useEffect(() => {
+		if (!offered) {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+			setState((previous) => previous.status === "loading" ? {
+				...previous,
+				status: "idle"
+			} : previous);
+		}
+	}, [offered]);
+	const ask = useCallback(() => {
+		const now = latest.current;
+		const port = now.ai?.hint;
+		const held = now.current;
+		if (port === void 0 || !now.offered || held.status === "loading" || held.hints.length >= now.limit) return;
+		const key = held.key;
+		const request = aiHintRequest({
+			data: now.input.data,
+			response: now.input.response,
+			previousHints: held.hints.map((hint) => hint.text),
+			...localeOf(now.ai, now.input.locale)
+		});
+		if (request === null) {
+			setState({
+				...held,
+				status: "unavailable"
+			});
+			return;
+		}
+		run.current += 1;
+		const mine = run.current;
+		controller.current?.abort();
+		const abort = new AbortController();
+		controller.current = abort;
+		setState({
+			...held,
+			status: "loading"
+		});
+		callPort(() => port(request, { signal: abort.signal })).then((raw) => {
+			if (run.current !== mine) return;
+			const checked = checkAiHint(raw, request);
+			if (!checked.ok) {
+				warnRefused("hint", now.input.data.id, checked.refusal);
+				setState((shown) => ({
+					...shown,
+					status: "unavailable"
+				}));
+				latest.current.input.onInteraction?.({
+					type: "ai-help-refused",
+					activityId: now.input.data.id,
+					timestamp: Date.now(),
+					payload: {
+						feature: "hint",
+						reason: checked.refusal,
+						hintNumber: request.hintNumber
+					}
+				});
+				return;
+			}
+			setState((shown) => ({
+				...shown,
+				hints: shown.key === key ? [...shown.hints, checked.result] : shown.hints,
+				status: "idle"
+			}));
+			latest.current.input.onInteraction?.({
+				type: "ai-hint-shown",
+				activityId: now.input.data.id,
+				timestamp: Date.now(),
+				payload: {
+					hintNumber: request.hintNumber,
+					...shownPayload(checked.result)
+				}
+			});
+		}, () => {
+			if (run.current === mine) setState((shown) => ({
+				...shown,
+				status: "unavailable"
+			}));
+		});
+	}, []);
+	return {
+		offered,
+		status: current.status,
+		hints: current.hints,
+		limit,
+		used: current.hints.length,
+		ask
+	};
+}
+/** The text of a written response; another type's response is no draft at all. */
+const draftOf = (response) => response.type === "written-response" ? response.text : "";
+/**
+* "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.
+*/
+function useAiWritingFeedback(input) {
+	const { data, submitted, response } = input;
+	const around = useContext(SequenceSlotContext);
+	const renderMode = modeInForce(input.renderMode, around?.renderMode);
+	const delivery = combineDeliveryPolicies(input.delivery, around?.delivery);
+	const disabled = input.disabled === true;
+	const ai = useLearnerAi(input.ai);
+	const resetKey = data.id;
+	const [state, setState] = useState({
+		key: resetKey,
+		shown: [],
+		status: "idle"
+	});
+	const run = useRef(0);
+	const controller = useRef(null);
+	const current = state.key === resetKey ? state : {
+		key: resetKey,
+		shown: [],
+		status: "idle"
+	};
+	const offered = ai?.writingFeedback !== void 0 && writingFeedbackOffered({
+		data,
+		renderMode,
+		submitted,
+		disabled,
+		delivery
+	});
+	const limit = writingFeedbackLimit(ai);
+	const latest = useRef({
+		input,
+		ai,
+		offered,
+		limit,
+		current
+	});
+	latest.current = {
+		input,
+		ai,
+		offered,
+		limit,
+		current
+	};
+	useEffect(() => {
+		return () => {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+		};
+	}, [resetKey]);
+	useEffect(() => {
+		if (!offered) {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+			setState((previous) => previous.status === "loading" ? {
+				...previous,
+				status: "idle"
+			} : previous);
+		}
+	}, [offered]);
+	const ask = useCallback(() => {
+		const now = latest.current;
+		const port = now.ai?.writingFeedback;
+		const held = now.current;
+		if (port === void 0 || !now.offered || held.status === "loading" || held.shown.length >= now.limit) return;
+		const key = held.key;
+		const about = draftOf(now.input.response);
+		const request = aiWritingFeedbackRequest({
+			data: now.input.data,
+			response: now.input.response,
+			previousFeedback: held.shown.map((one) => one.feedback.text),
+			...localeOf(now.ai, now.input.locale)
+		});
+		if (request === null) return;
+		run.current += 1;
+		const mine = run.current;
+		controller.current?.abort();
+		const abort = new AbortController();
+		controller.current = abort;
+		setState({
+			...held,
+			status: "loading"
+		});
+		callPort(() => port(request, { signal: abort.signal })).then((raw) => {
+			if (run.current !== mine) return;
+			const checked = checkAiWritingFeedback(raw, request);
+			if (!checked.ok) {
+				warnRefused("writing feedback", now.input.data.id, checked.refusal);
+				setState((was) => ({
+					...was,
+					status: "unavailable"
+				}));
+				latest.current.input.onInteraction?.({
+					type: "ai-help-refused",
+					activityId: now.input.data.id,
+					timestamp: Date.now(),
+					payload: {
+						feature: "writing-feedback",
+						reason: checked.refusal,
+						draftNumber: request.draftNumber
+					}
+				});
+				return;
+			}
+			const { feedback } = checked;
+			setState((was) => ({
+				...was,
+				shown: was.key === key ? [...was.shown, {
+					feedback,
+					about
+				}] : was.shown,
+				status: "idle"
+			}));
+			latest.current.input.onInteraction?.({
+				type: "ai-writing-feedback-shown",
+				activityId: now.input.data.id,
+				timestamp: Date.now(),
+				payload: {
+					draftNumber: request.draftNumber,
+					corrections: feedback.corrections.length,
+					...feedback.indicativeScore !== null ? { indicativeScore: feedback.indicativeScore } : {},
+					...shownPayload(feedback)
+				}
+			});
+		}, () => {
+			if (run.current === mine) setState((was) => ({
+				...was,
+				status: "unavailable"
+			}));
+		});
+	}, []);
+	const last = current.shown[current.shown.length - 1];
+	return {
+		offered,
+		status: current.status,
+		feedback: current.shown.map((one) => one.feedback),
+		latest: last?.feedback ?? null,
+		current: last !== void 0 && last.about === draftOf(response),
+		limit,
+		used: current.shown.length,
+		ask
+	};
+}
+/**
+* "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.
+*/
+function useAiCoaching(input) {
+	const { data, assessment, grade } = input;
+	const around = useContext(SequenceSlotContext);
+	const renderMode = modeInForce(input.renderMode, around?.renderMode);
+	const delivery = combineDeliveryPolicies(input.delivery, around?.delivery);
+	const ai = useLearnerAi(input.ai);
+	const { learnerLocale } = localeOf(ai, input.locale);
+	const { id, title, referenceText, locale: itemLocale, instructions, ai: permissions } = data;
+	const request = useMemo(() => {
+		return aiCoachingRequest({
+			data: {
+				type: "read-aloud",
+				id,
+				title,
+				referenceText,
+				locale: itemLocale,
+				instructions,
+				ai: permissions
+			},
+			...assessment !== void 0 && assessment !== null ? { assessment } : {},
+			...grade !== void 0 && grade !== null ? { grade } : {},
+			...learnerLocale !== void 0 ? { learnerLocale } : {}
+		});
+	}, [
+		id,
+		title,
+		referenceText,
+		itemLocale,
+		instructions,
+		permissions,
+		assessment,
+		grade,
+		learnerLocale
+	]);
+	const take = typeof assessment?.recordingKey === "string" ? assessment.recordingKey : null;
+	const resetKey = useMemo(() => request === null ? "" : JSON.stringify([take, request]), [take, request]);
+	const [state, setState] = useState({
+		key: resetKey,
+		status: "idle"
+	});
+	const run = useRef(0);
+	const controller = useRef(null);
+	const current = state.key === resetKey ? state : {
+		key: resetKey,
+		status: "idle"
+	};
+	const offered = ai?.pronunciationCoaching !== void 0 && coachingOffered({
+		data: {
+			type: "read-aloud",
+			id,
+			title,
+			ai: permissions
+		},
+		renderMode,
+		marked: request !== null,
+		delivery
+	});
+	const latest = useRef({
+		input,
+		ai,
+		request,
+		resetKey,
+		offered,
+		current
+	});
+	latest.current = {
+		input,
+		ai,
+		request,
+		resetKey,
+		offered,
+		current
+	};
+	useEffect(() => {
+		return () => {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+		};
+	}, [resetKey]);
+	useEffect(() => {
+		if (!offered) {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+			setState((previous) => previous.status === "loading" ? {
+				key: previous.key,
+				status: "idle"
+			} : previous);
+		}
+	}, [offered]);
+	const ask = useCallback(() => {
+		const now = latest.current;
+		const port = now.ai?.pronunciationCoaching;
+		const request = now.request;
+		if (port === void 0 || !now.offered || request === null || now.current.status === "loading" || now.current.status === "shown") return;
+		const key = now.resetKey;
+		const activityId = request.facts.activityId;
+		run.current += 1;
+		const mine = run.current;
+		controller.current?.abort();
+		const abort = new AbortController();
+		controller.current = abort;
+		setState({
+			key,
+			status: "loading"
+		});
+		callPort(() => port(request, { signal: abort.signal })).then((raw) => {
+			if (run.current !== mine) return;
+			const checked = checkAiCoaching(raw, request);
+			if (!checked.ok) {
+				warnRefused("pronunciation coaching", activityId, checked.refusal);
+				setState({
+					key,
+					status: "unavailable"
+				});
+				latest.current.input.onInteraction?.({
+					type: "ai-help-refused",
+					activityId,
+					timestamp: Date.now(),
+					payload: {
+						feature: "pronunciation-coaching",
+						reason: checked.refusal
+					}
+				});
+				return;
+			}
+			const { coaching } = checked;
+			setState({
+				key,
+				status: "shown",
+				coaching
+			});
+			latest.current.input.onInteraction?.({
+				type: "ai-coaching-shown",
+				activityId,
+				timestamp: Date.now(),
+				payload: {
+					words: coaching.words.length,
+					...shownPayload(coaching)
+				}
+			});
+		}, () => {
+			if (run.current === mine) setState({
+				key,
+				status: "unavailable"
+			});
+		});
+	}, []);
+	return {
+		offered,
+		status: offered ? current.status : "idle",
+		coaching: offered && current.status === "shown" ? current.coaching : null,
+		ask
+	};
+}
+//#endregion
+export { ANONYMOUS_ACTOR as a, isDevelopment as c, randomSessionId as d, SequenceSlotContext as f, takeOf as h, useAiWritingFeedback as i, legacyCorrect as l, stampTake as m, useAiExplanation as n, detailIsRight as o, mintTake as p, useAiHints as r, everyBuiltInTypeHandled as s, useAiCoaching as t, objectIdFor as u };
+
+//# sourceMappingURL=useAiHelp-B-ccDL5Q.js.map