@intellectif/lk-react 23.1.0 → 23.1.2

package/dist/useAiHelp-h9yOLFqt.cjs

@@ -0,0 +1,995 @@
+'use client';
+const require_ai_LkAiProvider = require("./ai/LkAiProvider.cjs");
+let react = require("react");
+let _intellectif_lk_core = require("@intellectif/lk-core");
+//#region src/components/shared/sequence-slot.ts
+/** `null` outside a pager: a standalone component belongs to no slot. */
+const SequenceSlotContext = (0, react.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 ?? _intellectif_lk_core.OPEN_DELIVERY_POLICY;
+	return delivery.feedback && delivery.solutions && delivery.ai.explanations && renderMode === "practice" && !submitted && !disabled && data.redacted !== true && (0, _intellectif_lk_core.aiSupports)(data.type, "writing-feedback") && (0, _intellectif_lk_core.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 ?? _intellectif_lk_core.OPEN_DELIVERY_POLICY;
+	return delivery.hints && delivery.ai.hints && renderMode === "practice" && !submitted && !disabled && data.redacted !== true && (0, _intellectif_lk_core.aiSupports)(data.type, "hint") && (0, _intellectif_lk_core.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 ?? _intellectif_lk_core.OPEN_DELIVERY_POLICY;
+	if (!delivery.feedback || !delivery.solutions || !delivery.ai.explanations) return false;
+	return (renderMode === "practice" && submitted || renderMode === "review" && outcome?.status === "scored") && (0, _intellectif_lk_core.aiSupports)(data.type, "explanation") && (0, _intellectif_lk_core.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 ?? _intellectif_lk_core.OPEN_DELIVERY_POLICY;
+	return delivery.feedback && delivery.ai.explanations && renderMode !== "exam" && marked && (0, _intellectif_lk_core.aiSupports)(data.type, "pronunciation-coaching") && (0, _intellectif_lk_core.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 = (0, react.useContext)(SequenceSlotContext);
+	const renderMode = modeInForce(input.renderMode, around?.renderMode);
+	const delivery = (0, _intellectif_lk_core.combineDeliveryPolicies)(input.delivery, around?.delivery);
+	const ai = require_ai_LkAiProvider.useLearnerAi(input.ai);
+	const resetKey = explanationKey(renderMode, submitted, response, outcome);
+	const [state, setState] = (0, react.useState)({
+		key: resetKey,
+		status: "idle"
+	});
+	const run = (0, react.useRef)(0);
+	const controller = (0, react.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 = (0, react.useRef)({
+		input,
+		renderMode,
+		ai,
+		resetKey,
+		offered,
+		current
+	});
+	latest.current = {
+		input,
+		renderMode,
+		ai,
+		resetKey,
+		offered,
+		current
+	};
+	(0, react.useEffect)(() => {
+		return () => {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+		};
+	}, [resetKey]);
+	const ask = (0, react.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 = (0, _intellectif_lk_core.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 = (0, _intellectif_lk_core.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 = (0, react.useContext)(SequenceSlotContext);
+	const renderMode = modeInForce(input.renderMode, around?.renderMode);
+	const delivery = (0, _intellectif_lk_core.combineDeliveryPolicies)(input.delivery, around?.delivery);
+	const disabled = input.disabled === true;
+	const ai = require_ai_LkAiProvider.useLearnerAi(input.ai);
+	const resetKey = data.id;
+	const [state, setState] = (0, react.useState)({
+		key: resetKey,
+		hints: [],
+		status: "idle"
+	});
+	const run = (0, react.useRef)(0);
+	const controller = (0, react.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 = (0, react.useRef)({
+		input,
+		renderMode,
+		ai,
+		offered,
+		limit,
+		current
+	});
+	latest.current = {
+		input,
+		renderMode,
+		ai,
+		offered,
+		limit,
+		current
+	};
+	(0, react.useEffect)(() => {
+		return () => {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+		};
+	}, [resetKey]);
+	(0, react.useEffect)(() => {
+		if (!offered) {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+			setState((previous) => previous.status === "loading" ? {
+				...previous,
+				status: "idle"
+			} : previous);
+		}
+	}, [offered]);
+	const ask = (0, react.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 = (0, _intellectif_lk_core.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 = (0, _intellectif_lk_core.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 = (0, react.useContext)(SequenceSlotContext);
+	const renderMode = modeInForce(input.renderMode, around?.renderMode);
+	const delivery = (0, _intellectif_lk_core.combineDeliveryPolicies)(input.delivery, around?.delivery);
+	const disabled = input.disabled === true;
+	const ai = require_ai_LkAiProvider.useLearnerAi(input.ai);
+	const resetKey = data.id;
+	const [state, setState] = (0, react.useState)({
+		key: resetKey,
+		shown: [],
+		status: "idle"
+	});
+	const run = (0, react.useRef)(0);
+	const controller = (0, react.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 = (0, react.useRef)({
+		input,
+		ai,
+		offered,
+		limit,
+		current
+	});
+	latest.current = {
+		input,
+		ai,
+		offered,
+		limit,
+		current
+	};
+	(0, react.useEffect)(() => {
+		return () => {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+		};
+	}, [resetKey]);
+	(0, react.useEffect)(() => {
+		if (!offered) {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+			setState((previous) => previous.status === "loading" ? {
+				...previous,
+				status: "idle"
+			} : previous);
+		}
+	}, [offered]);
+	const ask = (0, react.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 = (0, _intellectif_lk_core.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 = (0, _intellectif_lk_core.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 = (0, react.useContext)(SequenceSlotContext);
+	const renderMode = modeInForce(input.renderMode, around?.renderMode);
+	const delivery = (0, _intellectif_lk_core.combineDeliveryPolicies)(input.delivery, around?.delivery);
+	const ai = require_ai_LkAiProvider.useLearnerAi(input.ai);
+	const { learnerLocale } = localeOf(ai, input.locale);
+	const { id, title, referenceText, locale: itemLocale, instructions, ai: permissions } = data;
+	const request = (0, react.useMemo)(() => {
+		return (0, _intellectif_lk_core.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 = (0, react.useMemo)(() => request === null ? "" : JSON.stringify([take, request]), [take, request]);
+	const [state, setState] = (0, react.useState)({
+		key: resetKey,
+		status: "idle"
+	});
+	const run = (0, react.useRef)(0);
+	const controller = (0, react.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 = (0, react.useRef)({
+		input,
+		ai,
+		request,
+		resetKey,
+		offered,
+		current
+	});
+	latest.current = {
+		input,
+		ai,
+		request,
+		resetKey,
+		offered,
+		current
+	};
+	(0, react.useEffect)(() => {
+		return () => {
+			run.current += 1;
+			controller.current?.abort();
+			controller.current = null;
+		};
+	}, [resetKey]);
+	(0, react.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 = (0, react.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 = (0, _intellectif_lk_core.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
+Object.defineProperty(exports, "ANONYMOUS_ACTOR", {
+	enumerable: true,
+	get: function() {
+		return ANONYMOUS_ACTOR;
+	}
+});
+Object.defineProperty(exports, "SequenceSlotContext", {
+	enumerable: true,
+	get: function() {
+		return SequenceSlotContext;
+	}
+});
+Object.defineProperty(exports, "detailIsRight", {
+	enumerable: true,
+	get: function() {
+		return detailIsRight;
+	}
+});
+Object.defineProperty(exports, "everyBuiltInTypeHandled", {
+	enumerable: true,
+	get: function() {
+		return everyBuiltInTypeHandled;
+	}
+});
+Object.defineProperty(exports, "isDevelopment", {
+	enumerable: true,
+	get: function() {
+		return isDevelopment;
+	}
+});
+Object.defineProperty(exports, "legacyCorrect", {
+	enumerable: true,
+	get: function() {
+		return legacyCorrect;
+	}
+});
+Object.defineProperty(exports, "mintTake", {
+	enumerable: true,
+	get: function() {
+		return mintTake;
+	}
+});
+Object.defineProperty(exports, "objectIdFor", {
+	enumerable: true,
+	get: function() {
+		return objectIdFor;
+	}
+});
+Object.defineProperty(exports, "randomSessionId", {
+	enumerable: true,
+	get: function() {
+		return randomSessionId;
+	}
+});
+Object.defineProperty(exports, "stampTake", {
+	enumerable: true,
+	get: function() {
+		return stampTake;
+	}
+});
+Object.defineProperty(exports, "takeOf", {
+	enumerable: true,
+	get: function() {
+		return takeOf;
+	}
+});
+Object.defineProperty(exports, "useAiCoaching", {
+	enumerable: true,
+	get: function() {
+		return useAiCoaching;
+	}
+});
+Object.defineProperty(exports, "useAiExplanation", {
+	enumerable: true,
+	get: function() {
+		return useAiExplanation;
+	}
+});
+Object.defineProperty(exports, "useAiHints", {
+	enumerable: true,
+	get: function() {
+		return useAiHints;
+	}
+});
+Object.defineProperty(exports, "useAiWritingFeedback", {
+	enumerable: true,
+	get: function() {
+		return useAiWritingFeedback;
+	}
+});
+
+//# sourceMappingURL=useAiHelp-h9yOLFqt.cjs.map