@intellectif/lk-core 1.2.0 → 1.4.0

package/dist/ai-writing-G6tnCGzw.cjs

@@ -0,0 +1,2846 @@
+const require_registry = require("./registry-DVi0LR_i.cjs");
+const require_scoring = require("./scoring-B2_HEhMT.cjs");
+const require_item_group = require("./item-group-DroFXgLb.cjs");
+//#region src/ai-material.ts
+/**
+* What a model is told about the group a question sits in: the material the
+* learner reads and sees beside it.
+*
+* Internal: the request builders in `ai.ts` and `ai-writing.ts` are its public
+* face, through their `group` input.
+*/
+/**
+* The longest material text a model is given, in code points. A longer one is
+* cut and marked `truncated`: a long reading passage on an exam paper runs to
+* 4,000–7,000.
+*/
+const AI_MATERIAL_MAX_LENGTH = 12e3;
+const KINDS$2 = {
+	text: true,
+	audio: true,
+	video: true,
+	image: true,
+	mixed: true
+};
+const MEDIA_TYPES = {
+	image: true,
+	audio: true,
+	video: true,
+	embed: true
+};
+const isRecord$4 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A string with something in it, as written; otherwise nothing. */
+const filled = (value) => typeof value === "string" && value.trim() !== "" ? value : void 0;
+/**
+* `text` cut to {@link AI_MATERIAL_MAX_LENGTH} code points. The cut falls at
+* the last space in its second half, so no word is broken; in a script written
+* without spaces, at the limit itself.
+*/
+function cut(text) {
+	const points = [...text];
+	if (points.length <= 12e3) return {
+		text,
+		truncated: false
+	};
+	let end = AI_MATERIAL_MAX_LENGTH;
+	for (let at = AI_MATERIAL_MAX_LENGTH; at >= AI_MATERIAL_MAX_LENGTH / 2; at -= 1) if (/\s/u.test(points[at])) {
+		end = at;
+		break;
+	}
+	return {
+		text: points.slice(0, end).join("").trimEnd(),
+		truncated: true
+	};
+}
+/**
+* The facts of `group`'s material, or `null` without a group or a stimulus it
+* can read: not an object, or of a kind the SDK does not know.
+*
+* Only what the learner sees reaches a model. The `transcript` is author-only
+* and never read, so the facts are the same for a whole group and a redacted
+* one; a media address is never read either, since a model cannot open one
+* and a signed address must not end up in a prompt. Each field is read once.
+*/
+function materialFacts(group) {
+	if (!isRecord$4(group)) return null;
+	const stimulus = group.stimulus;
+	if (!isRecord$4(stimulus)) return null;
+	const kind = stimulus.kind;
+	if (typeof kind !== "string" || !Object.hasOwn(KINDS$2, kind)) return null;
+	const title = filled(stimulus.title) ?? filled(group.title);
+	const body = filled(stimulus.body);
+	const text = body === void 0 ? void 0 : cut(body);
+	const rawMedia = stimulus.media;
+	const mediaType = isRecord$4(rawMedia) ? rawMedia.type : void 0;
+	const alt = isRecord$4(rawMedia) ? filled(rawMedia.alt) : void 0;
+	const media = typeof mediaType === "string" && Object.hasOwn(MEDIA_TYPES, mediaType) ? {
+		type: mediaType,
+		...alt !== void 0 ? { alt } : {}
+	} : void 0;
+	const attribution = filled(stimulus.attribution);
+	const locale = filled(stimulus.locale);
+	return {
+		kind,
+		...title !== void 0 ? { title } : {},
+		...text !== void 0 ? { text: text.text } : {},
+		...text?.truncated === true ? { truncated: true } : {},
+		...media !== void 0 ? { media } : {},
+		...attribution !== void 0 ? { attribution } : {},
+		...locale !== void 0 ? { locale } : {}
+	};
+}
+//#endregion
+//#region src/ai-text.ts
+/**
+* How the SDK reads text a model wrote, before a learner does. Internal: shared
+* by the AI checks, and exported by none of the package's entry points.
+*/
+/**
+* Plain text as the learner will read it: line endings unified, control
+* characters other than line breaks and tabs removed, runs of blank lines
+* collapsed, the ends trimmed.
+*/
+function cleanText(text) {
+	return text.replace(/\r\n?/g, "\n").replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u2028\u2029]/g, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+/** A provenance field a host may send, kept only when it is a short string. */
+function provenanceOf(raw) {
+	if (typeof raw !== "object" || raw === null) return;
+	const kept = {};
+	for (const key of [
+		"model",
+		"promptHash",
+		"generatedAt"
+	]) {
+		const value = raw[key];
+		if (typeof value === "string" && value.length > 0 && value.length <= 200) kept[key] = value;
+	}
+	return Object.keys(kept).length > 0 ? kept : void 0;
+}
+/**
+* What the call cost, as a port reported it. Read on the same terms as the
+* provenance: a number that is not finite and zero or more says nothing about
+* a cost, so it is dropped rather than carried into a host's totals.
+*/
+function usageOf(raw) {
+	if (typeof raw !== "object" || raw === null) return;
+	const kept = {};
+	for (const key of [
+		"promptTokens",
+		"completionTokens",
+		"costUsd"
+	]) {
+		const value = raw[key];
+		if (typeof value === "number" && Number.isFinite(value) && value >= 0) kept[key] = value;
+	}
+	return Object.keys(kept).length > 0 ? kept : void 0;
+}
+/** Typographic quotes a model writes for the plain ones a learner typed, and back. */
+const QUOTE_FOLD = {
+	"‘": "'",
+	"’": "'",
+	"‛": "'",
+	"′": "'",
+	"“": "\"",
+	"”": "\"",
+	"„": "\"",
+	"″": "\""
+};
+/**
+* Text as a quote is matched against it: typographic quotes folded to plain
+* ones and every run of whitespace one space — the two liberties a model takes
+* when it copies words out — with, for each folded character, where it came
+* from, so a match maps back to the learner's own text. Case is kept: a
+* correction of "i" to "I" is about case.
+*/
+function folded(text) {
+	let chars = "";
+	const from = [];
+	let space = false;
+	for (let at = 0; at < text.length; at += 1) {
+		const char = text[at];
+		if (/\s/u.test(char)) {
+			if (!space) {
+				chars += " ";
+				from.push(at);
+				space = true;
+			}
+			continue;
+		}
+		space = false;
+		chars += QUOTE_FOLD[char] ?? char;
+		from.push(at);
+	}
+	return {
+		chars,
+		from
+	};
+}
+/** A quote as it is searched for: folded, and without the spaces around it. */
+const needle = (quote) => folded(quote).chars.trim();
+//#endregion
+//#region src/ai.ts
+/**
+* The activity types the SDK builds facts for, and which of them take hints.
+* A dictation takes none: its answer is the whole sentence, and it has
+* word-by-word hints of its own.
+*/
+const AI_EXPLANATION_TYPES = [
+	"multiple-choice",
+	"fill-in-the-blanks",
+	"gap-select",
+	"dictation"
+];
+const AI_HINT_TYPES = [
+	"multiple-choice",
+	"fill-in-the-blanks",
+	"gap-select"
+];
+/** The longest AI text shown, in code points. Longer is refused, not cut. */
+const AI_TEXT_MAX_LENGTH = 2e3;
+/**
+* Whether the SDK supports `feature` for this activity type: explanations and
+* hints for the types it builds facts for, and writing feedback for a written
+* response, and coaching for a read-aloud. A consumer's own type has none.
+*/
+function aiSupports(activityType, feature) {
+	if (feature === "writing-feedback") return activityType === "written-response";
+	if (feature === "pronunciation-coaching") return activityType === "read-aloud";
+	return (feature === "hint" ? AI_HINT_TYPES : AI_EXPLANATION_TYPES).includes(activityType);
+}
+/**
+* Whether the item's author allows `feature`. Only an explicit `false`
+* switches it off: an author can refuse a feature, never force one on.
+*
+* Writing feedback and pronunciation coaching read `explanations`: each is a
+* model's words about the learner's own answer, and an author who switched one
+* off has switched off the others.
+*/
+function aiAllowedByContent(data, feature) {
+	const permissions = data.ai;
+	if (typeof permissions !== "object" || permissions === null) return true;
+	return permissions[feature === "hint" ? "hints" : "explanations"] !== false;
+}
+/** A grade as an explanation must speak to it: all marks, some, or none. */
+function aiGradeOf(result) {
+	const ratio = result.maxScore > 0 ? result.score / result.maxScore : 0;
+	let category = "partly-correct";
+	if (ratio >= 1 - 1e-9) category = "correct";
+	else if (ratio <= 1e-9) category = "incorrect";
+	return {
+		score: result.score,
+		maxScore: result.maxScore,
+		passed: result.passed,
+		category
+	};
+}
+/**
+* The `correct` flag a detail stored before 0.3 carries instead of an
+* `outcome`. 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.
+*/
+const legacyCorrect = (detail) => detail.correct === true;
+/** Whether a blank, a gap or a word was right, read from a server's detail. */
+function detailRight(detail) {
+	const outcome = detail.outcome;
+	return outcome === void 0 ? legacyCorrect(detail) : outcome === "correct";
+}
+/** Whether an option is part of the answer, read from a server's detail (as the renderer reads it). */
+function isAnswerOption(detail, chosen) {
+	switch (detail.outcome) {
+		case "correct":
+		case "incorrect-omission": return true;
+		case "incorrect":
+		case "correct-omission": return false;
+		default: return chosen ? legacyCorrect(detail) : !legacyCorrect(detail);
+	}
+}
+const firstString = (value) => Array.isArray(value) ? value[0] : value;
+const listOf$1 = (value) => value === void 0 ? null : Array.isArray(value) ? [...value] : [value];
+/** The response a learner has before touching anything. */
+function emptyResponse(type) {
+	switch (type) {
+		case "multiple-choice": return {
+			type: "multiple-choice",
+			selectedOptionIds: []
+		};
+		case "fill-in-the-blanks": return {
+			type: "fill-in-the-blanks",
+			answers: {}
+		};
+		case "gap-select": return {
+			type: "gap-select",
+			selections: {}
+		};
+		case "dictation": return {
+			type: "dictation",
+			text: ""
+		};
+		default: return null;
+	}
+}
+const base = (data) => ({
+	activityId: data.id,
+	title: data.title,
+	...typeof data.locale === "string" ? { locale: data.locale } : {}
+});
+/**
+* The facts a model is given about one item and one answer. `details` are the
+* SDK's per-part verdicts — from its own scorer, or from a server's outcome in
+* review — and every `correct` is `null` without them. A redacted item yields
+* facts without a key, which is what the learner's side holds; a port that
+* needs the key loads the item on its server.
+*
+* `null` for a type the SDK builds no facts for.
+*/
+function buildAiFacts(data, response, details) {
+	const byId = new Map((details ?? []).map((detail) => [detail.itemId, detail]));
+	const full = data.redacted !== true;
+	switch (data.type) {
+		case "multiple-choice": {
+			const item = data;
+			const chosen = new Set(response?.type === "multiple-choice" ? response.selectedOptionIds : []);
+			return {
+				...base(data),
+				activityType: "multiple-choice",
+				question: item.question,
+				mode: item.mode,
+				options: item.options.map((option) => {
+					const detail = byId.get(option.id);
+					const wasChosen = chosen.has(option.id);
+					let correct = null;
+					if (full && typeof option.isCorrect === "boolean") correct = option.isCorrect;
+					else if (detail !== void 0) correct = isAnswerOption(detail, wasChosen);
+					return {
+						id: option.id,
+						text: option.text,
+						chosen: wasChosen,
+						correct,
+						...typeof option.feedback === "string" ? { feedback: option.feedback } : {}
+					};
+				})
+			};
+		}
+		case "fill-in-the-blanks": {
+			const item = data;
+			const answers = response?.type === "fill-in-the-blanks" ? response.answers : {};
+			const blanks = new Map(item.blanks.map((blank) => [blank.id, blank]));
+			return {
+				...base(data),
+				activityType: "fill-in-the-blanks",
+				passage: require_registry.numberedPassage(item.passage),
+				blanks: require_registry.placeholderOrder(item.passage).map((id, index) => {
+					const blank = blanks.get(id);
+					const detail = byId.get(id);
+					const accepted = full && Array.isArray(blank?.acceptedAnswers) ? [...blank.acceptedAnswers] : listOf$1(detail?.correctResponse);
+					return {
+						id,
+						position: index + 1,
+						typed: typeof answers[id] === "string" ? answers[id] : "",
+						accepted,
+						correct: detail === void 0 ? null : detailRight(detail),
+						...typeof blank?.hint === "string" ? { hint: blank.hint } : {},
+						...typeof blank?.feedback === "string" ? { feedback: blank.feedback } : {}
+					};
+				})
+			};
+		}
+		case "gap-select": {
+			const item = data;
+			const selections = response?.type === "gap-select" ? response.selections : {};
+			const gaps = new Map(item.gaps.map((gap) => [gap.id, gap]));
+			const banks = new Map((item.banks ?? []).map((bank) => [bank.id, bank]));
+			return {
+				...base(data),
+				activityType: "gap-select",
+				passage: require_registry.numberedPassage(item.passage),
+				gaps: require_registry.placeholderOrder(item.passage).map((id, index) => {
+					const gap = gaps.get(id);
+					const choices = gap?.choices ?? (gap?.bankId === void 0 ? [] : banks.get(gap.bankId)?.choices ?? []);
+					const textOf = (choiceId) => choiceId === void 0 ? null : choices.find((choice) => choice.id === choiceId)?.text ?? null;
+					const detail = byId.get(id);
+					const answerId = full && typeof gap?.correctChoiceId === "string" ? gap.correctChoiceId : firstString(detail?.correctResponse);
+					return {
+						id,
+						position: index + 1,
+						choices: choices.map((choice) => choice.text),
+						chosen: textOf(selections[id]),
+						answer: textOf(answerId),
+						correct: detail === void 0 ? null : detailRight(detail),
+						...typeof gap?.feedback === "string" ? { feedback: gap.feedback } : {}
+					};
+				})
+			};
+		}
+		case "dictation": {
+			const item = data;
+			const typed = response?.type === "dictation" ? response.text : "";
+			const hasKey = full && typeof item.transcript === "string";
+			let words = null;
+			if (hasKey) words = require_registry.alignDictation(item, typed).words.map((word) => ({
+				expected: word.reference,
+				typed: word.attempt,
+				status: word.status
+			}));
+			else if (details !== null && details.length > 0) words = details.map((detail) => {
+				const expected = firstString(detail.correctResponse) ?? "";
+				const attempt = firstString(detail.learnerResponse) ?? "";
+				let status = "incorrect";
+				if (detailRight(detail)) status = "correct";
+				else if (attempt === "") status = "missing";
+				else if (expected === "") status = "extra";
+				return {
+					expected,
+					typed: attempt,
+					status
+				};
+			});
+			return {
+				...base(data),
+				activityType: "dictation",
+				transcript: hasKey ? item.transcript : null,
+				typed,
+				words
+			};
+		}
+		default: return null;
+	}
+}
+/** The SDK's own grade of `response`, with its per-part details; `null` when it cannot grade. */
+function gradeLocally(data, response) {
+	if (data.redacted === true) return null;
+	try {
+		const result = require_scoring.score(data.type, data, response);
+		return {
+			details: result.details,
+			grade: aiGradeOf(result)
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* The request for an explanation of `response`, or `null` when there is none
+* to give: an unsupported type, an author who switched explanations off,
+* nothing graded to explain, or a grade of record that cannot be a grade.
+*
+* A scored `outcome` — the grade of record a review shows — wins over grading
+* locally, so the explanation speaks to the grade on the screen. One whose
+* numbers cannot be a grade (the rule `outcomeFromGrade` applies: `maxScore`
+* positive and finite, `score` finite from 0 to it) gets no explanation at all:
+* explaining 85 "out of 1" would tell the model a wrong answer was correct, and
+* grading locally instead would speak to a grade the screen does not show.
+*
+* `group` is the item group the question sits in: its material — the passage,
+* or the instructions the group's questions share — goes with the request as
+* `material`, as the learner sees it.
+*/
+function aiExplanationRequest(input) {
+	const { data, response, outcome, learnerLocale } = input;
+	if (!aiSupports(data.type, "explanation") || !aiAllowedByContent(data, "explanation")) return null;
+	let details = null;
+	let grade = null;
+	if (outcome?.status === "scored") {
+		const { score: recorded, maxScore, passed } = outcome;
+		if (!require_scoring.isGradeInRange(recorded, maxScore)) return null;
+		details = outcome.details;
+		grade = aiGradeOf({
+			score: recorded,
+			maxScore,
+			passed
+		});
+	} else if (response !== null) {
+		const local = gradeLocally(data, response);
+		if (local !== null) {
+			details = local.details;
+			grade = local.grade;
+		}
+	}
+	if (grade === null) return null;
+	const facts = buildAiFacts(data, response, details);
+	if (facts === null) return null;
+	const material = materialFacts(input.group);
+	return {
+		feature: "explanation",
+		facts,
+		grade,
+		...material !== null ? { material } : {},
+		...learnerLocale !== void 0 ? { learnerLocale } : {}
+	};
+}
+/**
+* The request for the next hint on an unsubmitted answer, or `null` when
+* there is none to give: an unsupported type, an author who switched hints
+* off, or a redacted item — hints are for practice, where the item is whole.
+*
+* The facts carry the key, and which parts the learner has right so far, so a
+* model can hint where it helps. The learner never sees them; a hint that
+* contains an answer is refused by {@link checkAiHint}, whatever it quotes —
+* the group's material included.
+*
+* `group` is the item group the question sits in, as for
+* {@link aiExplanationRequest}.
+*/
+function aiHintRequest(input) {
+	const { data, previousHints, learnerLocale } = input;
+	if (!aiSupports(data.type, "hint") || !aiAllowedByContent(data, "hint") || data.redacted === true) return null;
+	const response = input.response ?? emptyResponse(data.type);
+	const facts = buildAiFacts(data, response, (response === null ? null : gradeLocally(data, response))?.details ?? null);
+	if (facts === null) return null;
+	const material = materialFacts(input.group);
+	return {
+		feature: "hint",
+		facts,
+		hintNumber: previousHints.length + 1,
+		previousHints: [...previousHints],
+		...material !== null ? { material } : {},
+		...learnerLocale !== void 0 ? { learnerLocale } : {}
+	};
+}
+const VERDICTS = [
+	"correct",
+	"partly-correct",
+	"incorrect"
+];
+/**
+* Reads what a port returned. Anything but an object with a string `text` is
+* `malformed`; text that is empty once cleaned, or longer than
+* {@link AI_TEXT_MAX_LENGTH}, is refused rather than shown or cut.
+*/
+function readAiTextResult(raw) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {
+		ok: false,
+		refusal: "malformed"
+	};
+	const record = raw;
+	if (typeof record.text !== "string") return {
+		ok: false,
+		refusal: "malformed"
+	};
+	if (record.verdict !== void 0 && !VERDICTS.includes(record.verdict)) return {
+		ok: false,
+		refusal: "malformed"
+	};
+	const text = cleanText(record.text);
+	if (text === "") return {
+		ok: false,
+		refusal: "empty"
+	};
+	if ([...text].length > 2e3) return {
+		ok: false,
+		refusal: "too-long"
+	};
+	const provenance = provenanceOf(record.provenance);
+	const usage = usageOf(record.usage);
+	return {
+		ok: true,
+		result: {
+			text,
+			...record.verdict !== void 0 ? { verdict: record.verdict } : {},
+			...provenance !== void 0 ? { provenance } : {},
+			...usage !== void 0 ? { usage } : {}
+		}
+	};
+}
+/**
+* Checks an explanation a port returned for `request`. On top of
+* {@link readAiTextResult}: an explanation that states a verdict other than
+* the SDK's grade is refused (`contradicts-grade`) — it explains an answer
+* the learner did not get.
+*/
+function checkAiExplanation(raw, request) {
+	const read = readAiTextResult(raw);
+	if (!read.ok) return read;
+	if (read.result.verdict !== void 0 && read.result.verdict !== request.grade.category) return {
+		ok: false,
+		refusal: "contradicts-grade"
+	};
+	return read;
+}
+/**
+* Checks a hint a port returned for `request`. On top of
+* {@link readAiTextResult}: a hint that contains an answer is refused
+* (`reveals-answer`) — see {@link hintRevealsAnswer}.
+*/
+function checkAiHint(raw, request) {
+	const read = readAiTextResult(raw);
+	if (!read.ok) return read;
+	if (hintRevealsAnswer(request.facts, read.result.text)) return {
+		ok: false,
+		refusal: "reveals-answer"
+	};
+	return read;
+}
+/**
+* Whether a hint gives away an answer, judged against the facts it was asked
+* for. It is a floor, not a proof: it finds an answer written out, not one
+* spelled letter by letter or described.
+*
+* - **Multiple choice:** the text of any correct option, as whole words.
+* - **Fill-in-the-blanks and gap select:** any accepted answer, as whole words.
+*   An answer of one short word ("is", "the") counts only where the hint
+*   writes it beside a neighbour it has in the passage — "name is", "is
+*   Rossi" — so a hint may still use the word on its own.
+* - **Facts of any other kind:** revealing. A hint the check cannot read is
+*   withheld, not shown unchecked.
+*
+* Case, accents and punctuation are ignored on both sides.
+*/
+function hintRevealsAnswer(facts, hint) {
+	const reveals = (answer, passage, position) => require_registry.revealsAnswer(hint, answer, passage, position);
+	switch (facts.activityType) {
+		case "multiple-choice": return facts.options.some((option) => option.correct === true && reveals(option.text));
+		case "fill-in-the-blanks": return facts.blanks.some((blank) => (blank.accepted ?? []).some((answer) => reveals(answer, facts.passage, blank.position)));
+		case "gap-select": return facts.gaps.some((gap) => gap.answer !== null && reveals(gap.answer, facts.passage, gap.position));
+		case "dictation": return false;
+		default: return true;
+	}
+}
+//#endregion
+//#region src/ai-coaching.ts
+/** The most words one coaching may work on. More is refused, not cut. */
+const AI_COACHING_MAX_WORDS = 20;
+/** The longest tip for one word, in code points. */
+const AI_COACHING_MAX_TIP_LENGTH = 500;
+/** The longest sound symbol: a phoneme, not a sentence. */
+const MAX_SYMBOL_LENGTH = 16;
+/** The dimensions a reading is scored on, as the facts name them. */
+const DIMENSIONS = [
+	"accuracy",
+	"fluency",
+	"completeness",
+	"prosody"
+];
+/** Two decimals: what a stored score out of 1 was, out of 100, without float noise. */
+const hundredths = (value) => Math.round(value * 1e4) / 100;
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+/** A word's sounds as the engine reported them: only those it names. */
+function soundsOf(word) {
+	const sounds = [];
+	for (const phoneme of word?.phonemes ?? []) {
+		if (typeof phoneme.symbol !== "string") continue;
+		sounds.push({
+			symbol: phoneme.symbol,
+			...phoneme.accuracy !== void 0 ? { accuracy: phoneme.accuracy } : {},
+			...phoneme.heardAs !== void 0 && phoneme.heardAs.length > 0 ? { heardAs: phoneme.heardAs.map(({ symbol, score }) => ({
+				symbol,
+				score
+			})) } : {}
+		});
+	}
+	return sounds.length > 0 ? sounds : void 0;
+}
+/** The facts from the engine's full assessment: every word's mark, and its sounds. */
+function fromAssessment(item, assessment) {
+	const words = require_scoring.alignReadAloud(item, assessment).map((entry) => {
+		const sounds = entry.itemId !== void 0 && entry.wordIndex !== void 0 ? soundsOf(assessment.words[entry.wordIndex]) : void 0;
+		return {
+			...entry.itemId !== void 0 ? { itemId: entry.itemId } : {},
+			word: entry.reference,
+			heard: entry.heard,
+			state: entry.state,
+			...entry.accuracy !== void 0 ? { accuracy: entry.accuracy } : {},
+			...sounds !== void 0 ? { sounds } : {}
+		};
+	});
+	const scores = {};
+	for (const dimension of DIMENSIONS) {
+		const value = assessment.scores[dimension];
+		if (value !== void 0) scores[dimension] = value;
+	}
+	return {
+		assessor: assessment.assessor.kind,
+		...assessment.phonemeAlphabet !== void 0 ? { phonemeAlphabet: assessment.phonemeAlphabet } : {},
+		scores,
+		words
+	};
+}
+/**
+* Whether an assessment holds marks on this text: one `validateSpeechAssessment`
+* accepts, of speech heard, made against the item's own text in its own locale
+* — the checks `gradeReadAloud` makes before it reads a mark. Anything else is
+* not marks on this reading, and would tell a model every word was left out.
+*/
+const marksThisText = (item, assessment) => require_scoring.validateSpeechAssessment(assessment).success && assessment.status === "assessed" && assessment.task === "scripted" && assessment.locale === item.locale && assessment.referenceText === item.referenceText;
+const STATE_OF_OUTCOME = {
+	correct: "correct",
+	incorrect: "mispronounced",
+	"incorrect-omission": "omitted"
+};
+/**
+* The facts from a stored grade alone: each word's mark and score, and no
+* sounds — a grade's details do not keep them.
+*/
+function fromGrade(grade) {
+	if (!Array.isArray(grade.details) || grade.details.length === 0) return null;
+	const words = [];
+	for (const detail of grade.details) {
+		const state = STATE_OF_OUTCOME[detail.outcome];
+		if (state === void 0 || typeof detail.itemId !== "string") continue;
+		const text = (value) => Array.isArray(value) ? value.join(" ") : value;
+		words.push({
+			itemId: detail.itemId,
+			word: text(detail.correctResponse),
+			heard: text(detail.learnerResponse),
+			state,
+			...state !== "omitted" && isFiniteNumber(detail.score) ? { accuracy: hundredths(detail.score) } : {}
+		});
+	}
+	if (words.length === 0) return null;
+	const scores = {};
+	for (const criterion of grade.criteria ?? []) {
+		const dimension = DIMENSIONS.find((name) => name === criterion.name);
+		if (dimension !== void 0 && isFiniteNumber(criterion.score) && isFiniteNumber(criterion.maxScore) && criterion.maxScore > 0) scores[dimension] = hundredths(criterion.score / criterion.maxScore);
+	}
+	const kind = grade.grader?.kind;
+	return {
+		assessor: kind === "auto" || kind === "ai" || kind === "human" ? kind : "unknown",
+		scores,
+		words
+	};
+}
+/**
+* The request for coaching on a graded reading, or `null` when there is none
+* to give: not a read-aloud, an author who switched explanations off (coaching
+* reads `ai.explanations`), or no marks.
+*
+* The marks come from the `assessment` when one is given — with each word's
+* sounds and what each was heard as — and then only from it: an assessment
+* `gradeReadAloud` would not read (no speech heard, unscripted, or made against
+* another text or locale) gives none, rather than a stored grade's marks the
+* learner is not looking at. With no assessment, they come from
+* `grade.details`, without sounds.
+*
+* The facts are the text as the learner saw it, those marks word by word, and
+* the engine's dimension scores. The marks are the engine's; the model
+* explains them.
+*/
+function aiCoachingRequest(input) {
+	const { data, assessment, grade, learnerLocale } = input;
+	if (!aiSupports(data.type, "pronunciation-coaching") || !aiAllowedByContent(data, "pronunciation-coaching")) return null;
+	const item = data;
+	if (typeof item.referenceText !== "string" || typeof item.locale !== "string") return null;
+	const marks = assessment !== void 0 && assessment !== null ? marksThisText(item, assessment) ? fromAssessment(item, assessment) : null : grade !== void 0 && grade !== null ? fromGrade(grade) : null;
+	if (marks === null) return null;
+	const graded = grade !== void 0 && grade !== null && isFiniteNumber(grade.score) && isFiniteNumber(grade.maxScore) && typeof grade.passed === "boolean" ? {
+		score: grade.score,
+		maxScore: grade.maxScore,
+		passed: grade.passed
+	} : void 0;
+	return {
+		feature: "pronunciation-coaching",
+		facts: {
+			activityType: "read-aloud",
+			activityId: data.id,
+			title: data.title,
+			locale: item.locale,
+			referenceText: item.referenceText,
+			...typeof item.instructions === "string" ? { instructions: item.instructions } : {},
+			...marks
+		},
+		...graded !== void 0 ? { grade: graded } : {},
+		...learnerLocale !== void 0 ? { learnerLocale } : {}
+	};
+}
+const isRecord$3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A symbol as it is compared: composed, and without the spaces around it. */
+const symbolKey = (symbol) => symbol.normalize("NFC").trim();
+/**
+* Checks coaching a port returned for `request`, and turns it into what a
+* learner is shown. As every AI text, it is shown whole or not at all.
+*
+* - **The text** is read as every AI text is (`readAiTextResult`).
+* - **Every word coached is one the engine marked.** Each `itemId` names a word
+*   of the text marked `mispronounced` or `omitted`, once; coaching on a word
+*   read correctly, or one the text does not have, refuses the whole reply as
+*   `contradicts-marks`. Praise belongs in `text`.
+* - **Every sound named is one the engine reported** for that word, and a sound
+*   it was heard as is one the engine heard it as. Where the facts carry no
+*   sounds — marks from a stored grade, or an assessor that reports none — any
+*   sound is `contradicts-marks`: nothing stands behind it.
+* - **Nothing numeric is read.** A score in the reply is ignored: the marks and
+*   the grade are the engine's.
+* - **Limits:** {@link AI_COACHING_MAX_WORDS} words, a tip of
+*   {@link AI_COACHING_MAX_TIP_LENGTH} code points; over them `too-long`. A
+*   shape that is not the one documented is `malformed`.
+*
+* The words come back in reading order, each with the word as the marks show it
+* (the SDK's reading of the text, never the model's), and each sound spelt as
+* the engine spelt it.
+*/
+function checkAiCoaching(raw, request) {
+	const read = readAiTextResult(raw);
+	if (!read.ok) return read;
+	const entries = raw.words;
+	const words = [];
+	if (entries !== void 0 && entries !== null) {
+		if (!Array.isArray(entries)) return {
+			ok: false,
+			refusal: "malformed"
+		};
+		if (entries.length > 20) return {
+			ok: false,
+			refusal: "too-long"
+		};
+		const facts = /* @__PURE__ */ new Map();
+		request.facts.words.forEach((fact, order) => {
+			if (fact.itemId !== void 0) facts.set(fact.itemId, {
+				fact,
+				order
+			});
+		});
+		const seen = /* @__PURE__ */ new Set();
+		for (const entry of entries) {
+			if (!isRecord$3(entry) || typeof entry.itemId !== "string" || typeof entry.tip !== "string") return {
+				ok: false,
+				refusal: "malformed"
+			};
+			const tip = cleanText(entry.tip);
+			if (tip === "") return {
+				ok: false,
+				refusal: "malformed"
+			};
+			if ([...tip].length > 500) return {
+				ok: false,
+				refusal: "too-long"
+			};
+			if (seen.has(entry.itemId)) return {
+				ok: false,
+				refusal: "malformed"
+			};
+			seen.add(entry.itemId);
+			const found = facts.get(entry.itemId);
+			if (found === void 0 || found.fact.state !== "mispronounced" && found.fact.state !== "omitted") return {
+				ok: false,
+				refusal: "contradicts-marks"
+			};
+			const sound = checkSound(entry.sound, found.fact);
+			if (sound !== void 0 && "refusal" in sound) return sound;
+			words.push({
+				itemId: entry.itemId,
+				word: found.fact.word,
+				tip,
+				...sound !== void 0 ? { sound } : {},
+				order: found.order
+			});
+		}
+	}
+	const { text, provenance, usage } = read.result;
+	return {
+		ok: true,
+		coaching: {
+			text,
+			words: words.sort((a, b) => a.order - b.order).map(({ order: _order, ...word }) => word),
+			...provenance !== void 0 ? { provenance } : {},
+			...usage !== void 0 ? { usage } : {}
+		}
+	};
+}
+/** A sound a model names, checked against the sounds the engine reported for the word. */
+function checkSound(raw, fact) {
+	if (raw === void 0 || raw === null) return;
+	if (!isRecord$3(raw) || typeof raw.expected !== "string" || raw.heard !== void 0 && raw.heard !== null && typeof raw.heard !== "string") return {
+		ok: false,
+		refusal: "malformed"
+	};
+	const heard = typeof raw.heard === "string" ? raw.heard : void 0;
+	if ([...raw.expected].length > MAX_SYMBOL_LENGTH || heard !== void 0 && [...heard].length > MAX_SYMBOL_LENGTH) return {
+		ok: false,
+		refusal: "too-long"
+	};
+	const expected = symbolKey(raw.expected);
+	const reported = fact.sounds?.find((sound) => symbolKey(sound.symbol) === expected);
+	if (reported === void 0) return {
+		ok: false,
+		refusal: "contradicts-marks"
+	};
+	if (heard === void 0) return { expected: reported.symbol };
+	const instead = reported.heardAs?.find((candidate) => symbolKey(candidate.symbol) === symbolKey(heard));
+	if (instead === void 0) return {
+		ok: false,
+		refusal: "contradicts-marks"
+	};
+	return {
+		expected: reported.symbol,
+		heard: instead.symbol
+	};
+}
+//#endregion
+//#region src/authoring/item-group.ts
+/**
+* A new, empty reading or listening testlet for an editor to start from.
+*
+* The stimulus starts as `text`, the only kind that needs no media file to be
+* a valid draft — an author who is writing a passage can begin typing, and one
+* who is building a listening item changes `kind` before uploading. `items`
+* starts empty, exactly as a new fill-in-the-blanks draft starts with no
+* blanks: the group is `incomplete` until somebody writes a question into it.
+*
+* @throws Error when `newId` returns an empty or repeated id.
+*/
+function createItemGroupDraft(context) {
+	const issued = /* @__PURE__ */ new Set();
+	const newId = () => {
+		const id = context.newId();
+		if (typeof id !== "string" || id === "") throw new Error("createItemGroupDraft: newId() must return a non-empty string.");
+		if (issued.has(id)) throw new Error(`createItemGroupDraft: newId() returned "${id}" twice. Ids within one draft must differ.`);
+		issued.add(id);
+		return id;
+	};
+	return {
+		schemaVersion: "1.0",
+		type: "item-group",
+		id: newId(),
+		stimulus: {
+			id: newId(),
+			kind: "text",
+			body: ""
+		},
+		items: []
+	};
+}
+/**
+* A new, empty interactive video for an editor to start from: an item group
+* whose stimulus is a video with no file yet, no questions, and a timeline with
+* no quizzes.
+*
+* It is an ordinary item group — {@link validateItemGroupDraft} checks it, and
+* everything that reads groups reads it — because that is what keeps each
+* question its own slot. Like every new draft it is `incomplete`: an untouched
+* draft must never read as finished.
+*
+* @throws Error when `newId` returns an empty or repeated id.
+*/
+function createInteractiveVideoDraft(context) {
+	const draft = createItemGroupDraft(context);
+	return {
+		...draft,
+		stimulus: {
+			id: draft.stimulus.id,
+			kind: "video",
+			media: {
+				type: "video",
+				url: ""
+			}
+		},
+		timeline: { cues: [] }
+	};
+}
+/**
+* Tells an unfinished testlet from a broken one — {@link validateDraft} for the
+* container that holds several questions around one passage or recording.
+*
+* It is a **separate entry point rather than a `'item-group'` type**, because
+* `validateDraft('item-group', …)` throws by design: `item-group` is reserved
+* in the registry precisely so it can never be registered as an activity, and
+* that guard is what keeps `isItemGroup` and `flattenSequence` able to trust
+* their own container. Widening `validateDraft` to accept it would have meant
+* weakening that.
+*
+* Each item is checked by `validateDraft` for its own type and its issues are
+* re-pathed under `items.N.…`, so an editor gets one list for the whole group
+* and every code in it is the code that type already documents. An item whose
+* type nobody registered is REPORTED, never thrown — an author fixing a
+* six-item group wants all six problems, not the first one that blew up.
+*
+* The group is `complete` only when the container passes, every item passes its
+* own schema, and every item is itself `complete`.
+*
+* @throws the error a registered item type's `checkDraft` or schema throws, as
+*   `validateDraft` does for that item on its own. Only an unregistered type is
+*   turned into an issue: a fault in a type's own code is not a problem with the
+*   draft, and reporting it as an unknown type would hide it.
+*/
+/**
+* The item critic over a testlet: each item's findings, under `items.N.…`, and
+* what only the set shows — every single-answer question keeping its right
+* option in one place. The stimulus is not searched for answers: a reading
+* group's answers are meant to be in its passage.
+*
+* An item of a type that is not registered, or without a `type`, is skipped:
+* {@link validateItemGroupDraft} already reports it.
+*/
+function critiqueItemGroupDraft(draft) {
+	if (!require_registry.isRecord(draft)) return [];
+	const items = Array.isArray(draft.items) ? draft.items : [];
+	return require_registry.withValidationScope(() => [...items.flatMap((item, index) => repathed(critiqueItem(item), ["items", index])), ...require_registry.keyPositionFinding(items, ["items"])]);
+}
+/**
+* The item critic over a question set, as `<ActivitySequence>` takes one: each
+* entry's findings under its index — an item group's under `N.items.M.…` — and,
+* over the entries that are items, what only the set shows (see
+* {@link critiqueItemGroupDraft}). An entry of a type that is not registered is
+* skipped.
+*/
+function critiqueDrafts(entries) {
+	return require_registry.withValidationScope(() => [...entries.flatMap((entry, index) => repathed(require_registry.isRecord(entry) && entry.type === "item-group" ? critiqueItemGroupDraft(entry) : critiqueItem(entry), [index])), ...require_registry.keyPositionFinding(entries, [])]);
+}
+/** One item's findings, or none for an item the critic cannot place. */
+function critiqueItem(item) {
+	if (!require_registry.isRecord(item) || typeof item.type !== "string") return [];
+	if (require_registry.getActivityTypeDescriptor(item.type) === void 0) return [];
+	return critiqueDraft(item.type, item);
+}
+const repathed = (findings, prefix) => findings.map((found) => ({
+	...found,
+	path: [...prefix.map(String), ...found.path]
+}));
+function validateItemGroupDraft(draft) {
+	return require_registry.withValidationScope(() => validateItemGroupDraftInScope(draft));
+}
+function validateItemGroupDraftInScope(draft) {
+	const issues = [];
+	if (!require_registry.isRecord(draft)) {
+		issues.push(require_registry.issue("ig_not_an_object", [], "A group must be an object with a stimulus and its items."));
+		return {
+			status: "invalid",
+			issues
+		};
+	}
+	issues.push(...checkGroupIdentity(draft));
+	if (require_registry.isRecord(draft.stimulus)) issues.push(...checkStimulus(draft.stimulus));
+	else if (require_registry.isUnset(draft.stimulus)) issues.push(require_registry.issue("ig_stimulus_required", ["stimulus"], "Add the passage, recording or image the questions are about."));
+	issues.push(...checkItems(draft));
+	if (draft.timeline !== void 0 && draft.timeline !== null) issues.push(...checkTimeline(draft));
+	const captions = require_registry.groupCaptionsField(draft, (captionsUrl) => !require_registry.isUnwritten(captionsUrl));
+	if (captions !== void 0) issues.push(require_registry.issue("dc_captions_not_allowed", [
+		"stimulus",
+		"media",
+		captions
+	], require_registry.GROUP_CAPTIONS_REVEAL_DICTATION));
+	const parsed = require_item_group.ItemGroupSchema.safeParse(draft, { reportInput: true });
+	if (!parsed.success) for (const schemaIssue of parsed.error.issues) {
+		const path = schemaIssue.path.map(String);
+		if (issues.some((known) => require_registry.covers(known.path, path))) continue;
+		if (path.length > 0 && require_registry.refusesEmpty(draft, schemaIssue)) {
+			issues.push(require_registry.issue("null_not_allowed", path, "This field cannot be null. Leave it out if it is optional, or give it a value."));
+			continue;
+		}
+		issues.push({
+			path,
+			message: schemaIssue.message,
+			code: schemaIssue.code,
+			severity: "invalid"
+		});
+	}
+	const stored = require_item_group.validateItemGroup(draft);
+	if (issues.length === 0 && stored.success) return {
+		status: "complete",
+		data: stored.data,
+		issues
+	};
+	if (issues.length === 0) for (const error of stored.success ? [] : stored.errors) issues.push({
+		...error,
+		severity: "invalid"
+	});
+	return {
+		status: issues.some((found) => found.severity !== "incomplete") ? "invalid" : "incomplete",
+		issues
+	};
+}
+/**
+* An interactive video: every question in exactly one quiz, quizzes at real
+* moments, a video to hang them on, and only the five question types a video
+* may hold. Each check stands aside where another already names the problem —
+* an unset item type is `ig_item_type_required`, an unregistered one
+* `ig_item_type_unknown` — so an author sees one issue per mistake.
+*/
+function checkTimeline(draft) {
+	const issues = [];
+	const timeline = draft.timeline;
+	if (!require_registry.isRecord(timeline)) return issues;
+	const stimulus = require_registry.isRecord(draft.stimulus) ? draft.stimulus : void 0;
+	if (stimulus !== void 0 && !require_registry.isUnwritten(stimulus.kind) && stimulus.kind !== "video") issues.push(require_registry.issue("ig_timeline_stimulus_kind", ["stimulus", "kind"], "An interactive video needs a video: quizzes open at moments of it."));
+	else if (stimulus !== void 0 && require_registry.isRecord(stimulus.media) && !require_registry.isUnwritten(stimulus.media.type) && stimulus.media.type !== "video") issues.push(require_registry.issue("ig_timeline_stimulus_kind", [
+		"stimulus",
+		"media",
+		"type"
+	], "Upload a video file. An embedded player from another site cannot be paused when a quiz opens."));
+	if (draft.shuffle === "within-group") issues.push(require_registry.issue("ig_timeline_shuffle", ["shuffle"], "The questions of an interactive video appear in the order their quizzes open, so they cannot be shuffled."));
+	const items = Array.isArray(draft.items) ? draft.items : [];
+	const itemIndexById = /* @__PURE__ */ new Map();
+	items.forEach((item, index) => {
+		if (!require_registry.isRecord(item)) return;
+		if (typeof item.id === "string" && item.id !== "") itemIndexById.set(item.id, index);
+		const type = item.type;
+		if (typeof type === "string" && type !== "" && type !== "item-group" && !require_item_group.isInteractiveVideoItemType(type) && require_registry.getActivityTypeDescriptor(type) !== void 0) issues.push(require_registry.issue("ig_timeline_item_type", [
+			"items",
+			index,
+			"type"
+		], `An interactive video can hold ${require_item_group.INTERACTIVE_VIDEO_ITEM_TYPES.join(", ")} questions only.`));
+		if (type === "dictation" && require_registry.isUnset(item.media)) issues.push(require_registry.issue("ig_timeline_dictation_media", [
+			"items",
+			index,
+			"media"
+		], "Add the recording this dictation plays: inside a video it cannot play the video."));
+	});
+	const cues = Array.isArray(timeline.cues) ? timeline.cues : [];
+	const quizIds = /* @__PURE__ */ new Set();
+	const placed = /* @__PURE__ */ new Set();
+	cues.forEach((cue, cueIndex) => {
+		if (!require_registry.isRecord(cue)) return;
+		const at = (field, ...rest) => [
+			"timeline",
+			"cues",
+			cueIndex,
+			field,
+			...rest
+		];
+		if (require_registry.isMissingId(cue.id)) issues.push(require_registry.issue("ig_timeline_quiz_id_required", at("id"), "This quiz has no id."));
+		else if (typeof cue.id === "string") {
+			if (quizIds.has(cue.id)) issues.push(require_registry.issue("ig_timeline_quiz_id_duplicate", at("id"), `Two quizzes share the id "${cue.id}".`));
+			quizIds.add(cue.id);
+		}
+		if (require_registry.isUnset(cue.at)) issues.push(require_registry.issue("ig_timeline_quiz_time_required", at("at"), "Choose when in the video this quiz opens."));
+		else if (typeof cue.at !== "number" || !Number.isFinite(cue.at) || cue.at < 0) issues.push(require_registry.issue("ig_timeline_quiz_time_invalid", at("at"), "A quiz opens at a number of seconds, 0 or more."));
+		if (require_registry.isUnset(cue.itemIds) || Array.isArray(cue.itemIds) && cue.itemIds.length === 0) {
+			issues.push(require_registry.issue("ig_timeline_quiz_empty", at("itemIds"), "Add at least one question to this quiz."));
+			return;
+		}
+		if (!Array.isArray(cue.itemIds)) return;
+		cue.itemIds.forEach((itemId, position) => {
+			if (typeof itemId !== "string") return;
+			if (!itemIndexById.has(itemId)) issues.push(require_registry.issue("ig_timeline_quiz_unknown_item", at("itemIds", position), `This quiz names a question that is not in the video ("${itemId}").`));
+			else if (placed.has(itemId)) issues.push(require_registry.issue("ig_timeline_item_duplicate", at("itemIds", position), "This question is already in a quiz: each question belongs to one quiz."));
+			placed.add(itemId);
+		});
+	});
+	for (const [itemId, index] of itemIndexById) if (!placed.has(itemId)) issues.push(require_registry.issue("ig_timeline_item_unplaced", ["items", index], "Add this question to a quiz, or the video never shows it."));
+	const chapters = Array.isArray(timeline.chapters) ? timeline.chapters : [];
+	let previousAt;
+	chapters.forEach((chapter, index) => {
+		if (!require_registry.isRecord(chapter)) return;
+		if (require_registry.isUnwritten(chapter.title)) issues.push(require_registry.issue("ig_timeline_chapter_title", [
+			"timeline",
+			"chapters",
+			index,
+			"title"
+		], "Give this chapter a title."));
+		if (typeof chapter.at === "number" && Number.isFinite(chapter.at)) {
+			if (previousAt !== void 0 && chapter.at <= previousAt) issues.push(require_registry.issue("ig_timeline_chapter_order", [
+				"timeline",
+				"chapters",
+				index,
+				"at"
+			], "Chapters must start in order, each after the one before it."));
+			previousAt = chapter.at;
+		}
+	});
+	return issues;
+}
+/** The group's own envelope. `title` is optional on a group, unlike an activity. */
+function checkGroupIdentity(draft) {
+	const issues = [];
+	if (draft.schemaVersion !== "1.0") issues.push(require_registry.issue("schema_version_invalid", ["schemaVersion"], "The draft must have schemaVersion \"1.0\". A draft from createItemGroupDraft has it."));
+	if (draft.type !== "item-group") issues.push(require_registry.issue("type_mismatch", ["type"], "The draft's type must be \"item-group\"."));
+	if (require_registry.isMissingId(draft.id)) issues.push(require_registry.issue("id_required", ["id"], "The group has no id."));
+	if (!require_registry.isUnset(draft.shuffle) && draft.shuffle !== "none" && draft.shuffle !== "within-group") issues.push(require_registry.issue("ig_shuffle_invalid", ["shuffle"], "Shuffling is either \"none\" or \"within-group\". Leave it out to keep the authored order."));
+	return issues;
+}
+const KINDS$1 = /* @__PURE__ */ new Set([
+	"text",
+	"audio",
+	"video",
+	"image",
+	"mixed"
+]);
+/** Which media type each stimulus kind accepts — mirrors `StimulusSchema`'s refinement. */
+const MEDIA_FOR_KIND = {
+	audio: ["audio"],
+	video: ["video", "embed"],
+	image: ["image"],
+	mixed: [
+		"audio",
+		"video",
+		"image",
+		"embed"
+	]
+};
+/**
+* The passage, recording or image. The split this makes is the one the whole
+* draft contract exists for: a kind nobody has chosen and a body nobody has
+* typed are `incomplete`, while a recording attached to an image stimulus is
+* `invalid` — writing more will not reconcile them.
+*/
+function checkStimulus(stimulus) {
+	const issues = [];
+	const at = (...rest) => ["stimulus", ...rest];
+	if (require_registry.isMissingId(stimulus.id)) issues.push(require_registry.issue("ig_stimulus_id_required", at("id"), "The stimulus has no id."));
+	const kind = stimulus.kind;
+	if (require_registry.isUnwritten(kind)) issues.push(require_registry.issue("ig_stimulus_kind_required", at("kind"), "Choose what the questions are about: a text, a recording, a video, an image, or a mix."));
+	else if (typeof kind !== "string" || !KINDS$1.has(kind)) {
+		if (typeof kind === "string") issues.push(require_registry.issue("ig_stimulus_kind_invalid", at("kind"), `"${kind}" is not a stimulus kind. Use text, audio, video, image or mixed.`));
+		if (require_registry.isRecord(stimulus.media)) issues.push(...require_registry.checkMedia(stimulus.media, at("media")));
+		return issues;
+	}
+	const hasBody = typeof stimulus.body === "string" && stimulus.body.trim() !== "";
+	const htmlPresent = !require_registry.isUnset(stimulus.bodyHtml);
+	if (!hasBody && (kind === "text" || kind === "mixed" || htmlPresent)) issues.push(require_registry.issue("ig_stimulus_body_required", at("body"), require_registry.isUnwritten(stimulus.bodyHtml) ? "Write the passage." : "Write the passage as plain text too. The rich-text version is shown only where a sanitiser is supplied."));
+	if (kind !== "text" && require_registry.isUnset(stimulus.media)) issues.push(require_registry.issue("ig_stimulus_media_required", at("media"), "Add the recording, video or image."));
+	else if (require_registry.isRecord(stimulus.media)) {
+		const allowed = MEDIA_FOR_KIND[kind];
+		const mediaType = stimulus.media.type;
+		if (allowed !== void 0 && typeof mediaType === "string" && !allowed.includes(mediaType)) issues.push(require_registry.issue("ig_stimulus_media_kind", at("media", "type"), `A "${kind}" stimulus cannot carry ${mediaType} media. Use ${allowed.join(" or ")}.`));
+		issues.push(...require_registry.checkMedia(stimulus.media, at("media")));
+	}
+	return issues;
+}
+/**
+* Every item, checked by `validateDraft` for its own type.
+*
+* Re-pathing rather than re-implementing is the point: a multiple-choice
+* question inside a testlet reports exactly the codes a standalone one does,
+* so a consumer's translation table covers both and a rule can never drift
+* between them.
+*/
+function checkItems(draft) {
+	const issues = [];
+	const items = require_registry.isUnset(draft.items) ? [] : draft.items;
+	if (!Array.isArray(items)) return issues;
+	if (items.length === 0) {
+		issues.push(require_registry.issue("ig_items_required", ["items"], "Add at least one question about this material."));
+		return issues;
+	}
+	const seen = /* @__PURE__ */ new Set();
+	const repeated = /* @__PURE__ */ new Set();
+	for (const [index, item] of items.entries()) {
+		if (!require_registry.isRecord(item)) continue;
+		const ordinal = index + 1;
+		if (require_registry.isMissingId(item.id)) issues.push(require_registry.issue("ig_item_id_required", [
+			"items",
+			index,
+			"id"
+		], `Question ${ordinal} has no id.`));
+		else if (typeof item.id === "string") {
+			if (seen.has(item.id)) repeated.add(item.id);
+			seen.add(item.id);
+		}
+		if (item.type === "item-group") {
+			issues.push(require_registry.issue("ig_item_nested_group", [
+				"items",
+				index,
+				"type"
+			], "Groups do not nest: every item must be an activity."));
+			continue;
+		}
+		if (require_registry.isUnwritten(item.type)) {
+			issues.push(require_registry.issue("ig_item_type_required", [
+				"items",
+				index,
+				"type"
+			], `Choose what kind of question ${ordinal} is.`));
+			continue;
+		}
+		if (typeof item.type !== "string") continue;
+		let result;
+		try {
+			result = validateDraft(item.type, item);
+		} catch (error) {
+			if (!(error instanceof require_registry.UnknownActivityTypeError) || error.activityType !== item.type) throw error;
+			issues.push(require_registry.issue("ig_item_type_unknown", [
+				"items",
+				index,
+				"type"
+			], `"${item.type}" is not a registered activity type.`));
+			continue;
+		}
+		for (const found of result.issues) issues.push({
+			...found,
+			path: [
+				"items",
+				String(index),
+				...found.path
+			]
+		});
+	}
+	for (const id of repeated) issues.push(require_registry.issue("ig_item_id_duplicate", ["items"], `More than one question has the id "${id}".`));
+	return issues;
+}
+//#endregion
+//#region src/authoring/index.ts
+/**
+* Tells a draft that is not finished from a draft that is wrong.
+*
+* `validateActivity` answers "may this be stored?", and to that question an
+* empty new question and a broken one are the same answer: no. An editor needs
+* the difference — "Add a title" is a to-do, "Only one option can be marked
+* correct" is an error — so a freshly added question does not read as a
+* failure, disable a whole form, or blank a preview.
+*
+* - `complete` — the draft is a valid activity with nothing left to write.
+*   `data` is exactly what `validateActivity` returns for it.
+* - `incomplete` — every problem is something not yet written.
+* - `invalid` — at least one problem is wrong in a way writing more cannot fix.
+*
+* It is stricter than `validateActivity`, never looser: `complete` requires the
+* activity's schema to pass, and a draft can fail here that the schema accepts
+* (a title that is only whitespace). Content stored by an older build can
+* therefore be valid and still not `complete`. `validateActivity` stays the
+* check at your write boundary.
+*
+* Issues come from the type's `authoring.checkDraft`, plus every schema failure
+* it did not already report at that path or inside it. (A failure at the root of
+* the draft counts as reported only by an issue at the root, since every path is
+* inside the root.) Such a failure is added as `invalid`: under the code
+* `null_not_allowed` when the schema refused a `null` there, or an `undefined`
+* entry in a list, and otherwise under the schema's own code and message. A type
+* with no `checkDraft` therefore reports every schema failure as `invalid`.
+*
+* The codes documented in `docs/authoring.md` are a contract, and each is
+* reported with its documented severity, whichever check reports it. A code
+* passed through from the schema is not a contract: the code and its English
+* message belong to the schema library, so give a code you do not recognise a
+* generic message of your own.
+*
+* @throws UnknownActivityTypeError when `type` has no registered descriptor —
+*   including `'item-group'`, which is a container, not an activity type.
+*/
+function validateDraft(type, draft) {
+	return require_registry.withValidationScope(() => validateDraftInScope(type, draft));
+}
+function validateDraftInScope(type, draft) {
+	const descriptor = require_registry.getActivityTypeDescriptor(type);
+	if (descriptor === void 0) throw new require_registry.UnknownActivityTypeError(String(type));
+	const reported = require_registry.isRecord(draft) && descriptor.authoring?.checkDraft !== void 0 ? descriptor.authoring.checkDraft(draft).map(normalise) : [];
+	const issues = [...reported];
+	const parsed = require_registry.readSchema(descriptor.schema, draft, `Activity type "${descriptor.type}"`, { reportInput: true });
+	if (!parsed.success) {
+		const covered = require_registry.coveredPathsOf(reported);
+		const reportedEmpty = /* @__PURE__ */ new Set();
+		for (const schemaIssue of parsed.issues) {
+			const path = schemaIssue.path.map(String);
+			if (covered.has(require_registry.pathKey(path))) continue;
+			if (path.length > 0 && require_registry.refusesEmpty(draft, schemaIssue)) {
+				const key = JSON.stringify(path);
+				if (!reportedEmpty.has(key)) {
+					reportedEmpty.add(key);
+					issues.push(require_registry.issue("null_not_allowed", path, typeof schemaIssue.path.at(-1) === "number" ? "This entry has no value. Remove it, or fill it in." : "This field cannot be null. Leave it out if it is optional, or give it a value."));
+				}
+				continue;
+			}
+			issues.push({
+				path,
+				message: schemaIssue.message,
+				code: schemaIssue.code,
+				severity: "invalid"
+			});
+		}
+	}
+	if (parsed.success && issues.length === 0) return {
+		status: "complete",
+		data: parsed.data,
+		issues
+	};
+	return {
+		status: issues.some((found) => found.severity !== "incomplete") ? "invalid" : "incomplete",
+		issues
+	};
+}
+/**
+* A new, empty draft of an activity type, for an editor to start from.
+*
+* Every required field is present and nothing is authored, so the draft comes
+* back from {@link validateDraft} as `incomplete`, and `validateActivity`
+* rejects it until someone writes it. The SDK invents no ids: `newId` is called
+* once per id the draft needs, and must return a different non-empty string each
+* time.
+*
+* ```ts
+* const draft = createDraft('multiple-choice', { newId: () => crypto.randomUUID() });
+* ```
+*
+* @throws UnknownActivityTypeError when `type` has no registered descriptor.
+* @throws Error when the type declares no `authoring.createDraft`, or when
+*   `newId` returns an empty or repeated id.
+*/
+function createDraft(type, context) {
+	const descriptor = require_registry.getActivityTypeDescriptor(type);
+	if (descriptor === void 0) throw new require_registry.UnknownActivityTypeError(String(type));
+	const create = descriptor.authoring?.createDraft;
+	if (create === void 0) throw new Error(`Activity type "${String(type)}" declares no authoring.createDraft, so there is no empty draft to create. Build the draft yourself; validateDraft works for every registered type.`);
+	const issued = /* @__PURE__ */ new Set();
+	const newId = () => {
+		const id = context.newId();
+		if (typeof id !== "string" || id === "") throw new Error("createDraft: newId() must return a non-empty string.");
+		if (issued.has(id)) throw new Error(`createDraft: newId() returned "${id}" twice. Ids within one draft must differ — two options sharing an id cannot be scored apart.`);
+		issued.add(id);
+		return id;
+	};
+	return create({ newId });
+}
+/**
+* A check's issue as `validateDraft` reports it.
+*
+* A documented code carries its documented severity, whichever check reports
+* it. Any other code keeps the check's severity, and one that is not
+* `'incomplete'` — misspelled, or missing — is reported as `invalid`, so the
+* mistake fails closed. Path segments become strings, as the schema's are, so a
+* list index given as a number still covers the schema's failure there.
+*/
+function normalise(found) {
+	const documented = Object.hasOwn(require_registry.DRAFT_ISSUE_SEVERITY, found.code) ? require_registry.DRAFT_ISSUE_SEVERITY[found.code] : void 0;
+	return {
+		...found,
+		path: found.path.map(String),
+		severity: documented ?? (found.severity === "incomplete" ? "incomplete" : "invalid")
+	};
+}
+/**
+* What an experienced item writer would point out on review: flaws a learner
+* can exploit or trip over (`warning`) and item-writing guidelines the item
+* departs from (`advice`) — the right option much longer than the rest, an
+* answer printed in the passage, a hint that gives the answer away, two
+* options that read the same, "all of the above" under shuffle.
+*
+* A finding is never a reason to refuse an item. It does not change what
+* {@link validateDraft} says: a valid item with findings is still valid. The
+* shape is a `DraftIssue`'s, so an editor shows both in one list.
+*
+* It reads a draft, finished or not, and skips any rule whose fields are not
+* written yet. The codes are documented in `docs/authoring.md`, each with its
+* severity; the rule behind a code is advice and may be refined in a minor.
+*
+* ```ts
+* const list = [...validateDraft(type, draft).issues, ...critiqueDraft(type, draft)];
+* ```
+*
+* @throws UnknownActivityTypeError when `type` has no registered descriptor —
+*   including `'item-group'`: use {@link critiqueItemGroupDraft}.
+*/
+function critiqueDraft(type, draft) {
+	const descriptor = require_registry.getActivityTypeDescriptor(type);
+	if (descriptor === void 0) throw new require_registry.UnknownActivityTypeError(String(type));
+	const critique = descriptor.authoring?.critique;
+	if (!require_registry.isRecord(draft) || critique === void 0) return [];
+	return require_registry.withValidationScope(() => critique(draft)).map(require_registry.normaliseFinding);
+}
+//#endregion
+//#region src/ai-critique.ts
+/** The most findings one critique may carry. More is refused, not cut. */
+const AI_CRITIQUE_MAX_FINDINGS = 20;
+/** The longest message or quote in a finding, in code points. */
+const AI_CRITIQUE_MAX_FIELD_LENGTH = 500;
+const KINDS = [
+	"ambiguous",
+	"second-answer",
+	"wrong-key",
+	"implausible-distractor",
+	"cue",
+	"level",
+	"language",
+	"sensitivity",
+	"other"
+];
+/**
+* Keys whose values are settings, ids or addresses — nothing a critique of the
+* item's words is about. A string under any of them is not a field to point at.
+*/
+const NOT_WORDS = /* @__PURE__ */ new Set([
+	"id",
+	"type",
+	"schemaVersion",
+	"mode",
+	"scoringStrategy",
+	"presentation",
+	"locale",
+	"languageTarget",
+	"correctChoiceId",
+	"bankId",
+	"url",
+	"captionsUrl",
+	"match",
+	"playback",
+	"recording",
+	"scoring",
+	"ai",
+	"learningObjectives",
+	"hints",
+	"kind",
+	"timeline"
+]);
+/**
+* Every string an author wrote into an item, with its path: the question, the
+* options, the passage, the answers, the hints, the feedback, a picture's
+* `alt`. Settings, ids and addresses are left out, and so is any `…Html`
+* sidecar: the plain field beside it holds the same words.
+*/
+function fieldsOf(value, path = []) {
+	if (typeof value === "string") return value.trim() === "" ? [] : [{
+		path,
+		text: value
+	}];
+	if (Array.isArray(value)) return value.flatMap((entry, index) => fieldsOf(entry, [...path, String(index)]));
+	if (typeof value === "object" && value !== null) return Object.entries(value).flatMap(([key, entry]) => NOT_WORDS.has(key) || key.endsWith("Html") ? [] : fieldsOf(entry, [...path, key]));
+	return [];
+}
+/**
+* What a model is given to review an item, or `null` when there is nothing to
+* review: a draft that is not an object, or one with no words in it yet.
+*
+* The facts are the item as the author wrote it — the answer key included; this
+* is for an author, never a learner — every text field a finding may point at,
+* and what the SDK's own critic already found there, so a model spends its
+* words on what a rule cannot see: a stem that reads two ways, a distractor
+* that is defensibly right, a key that is wrong, language above the level.
+*
+* Works for every registered type, the SDK's own and yours: the fields are read
+* from the draft itself.
+*
+* @throws UnknownActivityTypeError when `type` has no registered descriptor.
+*/
+function aiCritiqueRequest(input) {
+	const { type, draft, level, authorLocale } = input;
+	if (require_registry.getActivityTypeDescriptor(type) === void 0) throw new require_registry.UnknownActivityTypeError(String(type));
+	if (typeof draft !== "object" || draft === null || Array.isArray(draft)) return null;
+	const fields = fieldsOf(draft);
+	if (fields.length === 0) return null;
+	return {
+		feature: "item-critique",
+		facts: {
+			activityType: String(type),
+			item: draft,
+			fields,
+			findings: critiqueDraft(type, draft).map(({ path, code, message }) => ({
+				path,
+				code,
+				message
+			})),
+			...level !== void 0 ? { level } : {}
+		},
+		...authorLocale !== void 0 ? { authorLocale } : {}
+	};
+}
+const isRecord$2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const tooLong = (text) => [...text].length > 500;
+/**
+* Checks a critique a port returned for `request`, and turns it into findings
+* an editor lists beside the SDK's own. As every AI answer, it is shown whole
+* or not at all.
+*
+* - **Every finding points at a field the item has.** Its `path` is one of
+*   `facts.fields`, exactly; a path to a field the item does not have refuses
+*   the whole reply as `contradicts-item`.
+* - **A quote is words that field contains**, typographic quotes and runs of
+*   spacing aside, case kept; one it does not refuses the reply the same way.
+* - **Every finding is `advice`.** It is a model's opinion about the item, and
+*   nothing in the SDK acts on it; its code is `ai_` and the kind
+*   (`ai_second_answer`).
+* - **Limits:** {@link AI_CRITIQUE_MAX_FINDINGS} findings; a message or quote of
+*   {@link AI_CRITIQUE_MAX_FIELD_LENGTH} code points; over them `too-long`. A
+*   kind the SDK does not name, or any other shape, is `malformed`.
+*/
+function checkAiCritique(raw, request) {
+	if (!isRecord$2(raw) || !Array.isArray(raw.findings)) return {
+		ok: false,
+		refusal: "malformed"
+	};
+	if (raw.findings.length > 20) return {
+		ok: false,
+		refusal: "too-long"
+	};
+	const fields = new Map(request.facts.fields.map((field) => [JSON.stringify(field.path), field]));
+	const findings = [];
+	for (const entry of raw.findings) {
+		if (!isRecord$2(entry) || !Array.isArray(entry.path) || !entry.path.every((segment) => typeof segment === "string" || typeof segment === "number") || typeof entry.kind !== "string" || !KINDS.includes(entry.kind) || typeof entry.message !== "string" || entry.quote !== void 0 && entry.quote !== null && typeof entry.quote !== "string") return {
+			ok: false,
+			refusal: "malformed"
+		};
+		const message = cleanText(entry.message);
+		const quote = typeof entry.quote === "string" ? cleanText(entry.quote) : void 0;
+		if (message === "" || quote === "") return {
+			ok: false,
+			refusal: "malformed"
+		};
+		if (tooLong(message) || quote !== void 0 && tooLong(quote)) return {
+			ok: false,
+			refusal: "too-long"
+		};
+		const field = fields.get(JSON.stringify(entry.path.map(String)));
+		if (field === void 0) return {
+			ok: false,
+			refusal: "contradicts-item"
+		};
+		if (quote !== void 0 && !folded(field.text).chars.includes(needle(quote))) return {
+			ok: false,
+			refusal: "contradicts-item"
+		};
+		findings.push({
+			path: field.path,
+			code: `ai_${entry.kind.replace(/-/g, "_")}`,
+			message,
+			severity: "advice",
+			...quote !== void 0 ? { quote } : {}
+		});
+	}
+	const provenance = provenanceOf(raw.provenance);
+	const usage = usageOf(raw.usage);
+	return {
+		ok: true,
+		critique: {
+			findings,
+			...provenance !== void 0 ? { provenance } : {},
+			...usage !== void 0 ? { usage } : {}
+		}
+	};
+}
+//#endregion
+//#region src/ai-drafts.ts
+/** The most drafts one request may ask for, and the most a reply may hold when it names no count. */
+const AI_DRAFTS_MAX_COUNT = 50;
+/** The most repair passes `generateDrafts` makes. */
+const AI_DRAFTS_MAX_REPAIRS = 3;
+const DRAFT_TYPES = [
+	"multiple-choice",
+	"fill-in-the-blanks",
+	"gap-select",
+	"dictation",
+	"read-aloud",
+	"written-response"
+];
+const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (description) => ({
+	type: "string",
+	description
+});
+const FEEDBACK = {
+	type: "object",
+	description: "Optional overall feedback, shown after answering.",
+	properties: {
+		correct: text("Shown when the learner passes."),
+		incorrect: text("Shown when the learner does not.")
+	}
+};
+/** Every field a model writes, and the shape of each. A name means one thing in every type that uses it. */
+const FIELDS = {
+	title: text("A short name for the item, shown to the learner above it. Never the answer, or any part of it."),
+	question: text("The question, as plain text."),
+	mode: {
+		type: "string",
+		enum: ["single", "multi"],
+		description: "`single`: exactly one option is right. `multi`: one or more are."
+	},
+	options: {
+		type: "array",
+		minItems: 2,
+		maxItems: 26,
+		items: {
+			type: "object",
+			required: ["text", "isCorrect"],
+			properties: {
+				text: text("The option as the learner reads it."),
+				isCorrect: { type: "boolean" },
+				feedback: text("Why this option is right or wrong, shown after answering.")
+			}
+		}
+	},
+	passage: text("The passage as plain text, with {{1}}, {{2}}, … where each gap goes, numbered in the order they appear."),
+	blanks: {
+		type: "array",
+		minItems: 1,
+		description: "One per gap, in the order the gaps appear: the first is {{1}}.",
+		items: {
+			type: "object",
+			required: ["acceptedAnswers"],
+			properties: {
+				acceptedAnswers: {
+					type: "array",
+					minItems: 1,
+					items: { type: "string" },
+					description: "Every answer that is right, spelled as a learner would type it."
+				},
+				hint: text("Optional. Helps without giving the answer or any of its words.")
+			}
+		}
+	},
+	gaps: {
+		type: "array",
+		minItems: 1,
+		description: "One per gap, in the order the gaps appear: the first is {{1}}.",
+		items: {
+			type: "object",
+			required: ["choices"],
+			properties: { choices: {
+				type: "array",
+				minItems: 2,
+				description: "What the learner chooses from. Exactly one is right.",
+				items: {
+					type: "object",
+					required: ["text", "isCorrect"],
+					properties: {
+						text: text("A choice."),
+						isCorrect: { type: "boolean" }
+					}
+				}
+			} }
+		}
+	},
+	transcript: text("What the learner hears and types: words from the source, as they are said there."),
+	referenceText: text("What the learner reads aloud: a sentence or two from the source."),
+	instructions: text("Optional. How to read it, shown to the learner."),
+	prompt: text("The writing task, as plain text."),
+	minWords: {
+		type: "integer",
+		minimum: 0
+	},
+	maxWords: {
+		type: "integer",
+		minimum: 1
+	},
+	rubric: {
+		type: "object",
+		description: "Optional. What the writing is assessed on; every criterion is weighted equally.",
+		properties: { criteria: {
+			type: "array",
+			minItems: 1,
+			items: {
+				type: "object",
+				required: ["name"],
+				properties: {
+					name: text("A short name."),
+					description: text("What it looks for.")
+				}
+			}
+		} }
+	},
+	feedback: FEEDBACK
+};
+/** The fields a model writes for each type: a draft's own names, never an id or a setting. */
+const WRITES = {
+	"multiple-choice": [
+		"title",
+		"question",
+		"mode",
+		"options",
+		"feedback"
+	],
+	"fill-in-the-blanks": [
+		"title",
+		"passage",
+		"blanks",
+		"feedback"
+	],
+	"gap-select": [
+		"title",
+		"passage",
+		"gaps",
+		"feedback"
+	],
+	dictation: [
+		"title",
+		"transcript",
+		"feedback"
+	],
+	"read-aloud": [
+		"title",
+		"referenceText",
+		"instructions",
+		"feedback"
+	],
+	"written-response": [
+		"title",
+		"prompt",
+		"minWords",
+		"maxWords",
+		"rubric"
+	]
+};
+/**
+* One draft, as a model writes it: its `type`, and the fields that type uses —
+* one object for every chosen type, since a structured output that must pick
+* between schemas is the thing providers support least.
+*/
+function itemShape(types, captions) {
+	const properties = { type: {
+		type: "string",
+		enum: [...types],
+		description: `The item's type, and the fields it fills. ${types.map((type) => `${type}: ${WRITES[type].filter((name) => name !== "title").join(", ")}`).join(". ")}.`
+	} };
+	for (const type of types) for (const name of WRITES[type]) properties[name] = FIELDS[name];
+	if (captions) properties.caption = {
+		type: "integer",
+		minimum: 0,
+		description: "The index of the caption the item is about. It opens when that caption ends."
+	};
+	return {
+		type: "object",
+		required: captions ? [
+			"type",
+			"title",
+			"caption"
+		] : ["type", "title"],
+		properties
+	};
+}
+/** A reply of up to `max` drafts — exactly `exactly` on a repair. */
+function replyShape(types, captions, max, exactly) {
+	return {
+		type: "object",
+		required: ["drafts"],
+		properties: { drafts: {
+			type: "array",
+			...exactly !== void 0 ? {
+				minItems: exactly,
+				maxItems: exactly
+			} : { maxItems: max },
+			items: itemShape(types, captions)
+		} }
+	};
+}
+/**
+* What a model is given to draft items from a source, or `null` when there is
+* no source to draft from: an empty text, or no caption with words in it.
+*
+* `types` are the ones the author chose, in the author's order: the model
+* leans on the first, and where several drafts share a moment of a video — or
+* the end of one — they are shown in this order. `count` is how many to write
+* at most; left out, the model writes as many as the source is worth, up to
+* {@link AI_DRAFTS_MAX_COUNT}.
+*
+* The facts are the source — a caption list numbered, with its times in
+* seconds — the types, the count, and the language, level and instructions
+* the author gave. `shape` is the JSON Schema of the reply: each draft names
+* its type and writes that type's own fields, with no ids, no HTML, no media
+* and no settings. Those are not a model's to write. `settings` are yours, put
+* on every draft of a type: a read-aloud's `recording` and `scoring`, say, which
+* the SDK has no default for.
+*
+* @throws RangeError when `types` is empty, repeats a type or names one a model
+*   does not draft, or `count` is not a whole number from 1 to
+*   {@link AI_DRAFTS_MAX_COUNT}.
+*/
+function aiDraftsRequest(input) {
+	const { types, source, count, locale, level, instructions, settings } = input;
+	if (!Array.isArray(types) || types.length === 0 || new Set(types).size !== types.length || !types.every((type) => DRAFT_TYPES.includes(type))) throw new RangeError(`aiDraftsRequest: types must be one or more of ${DRAFT_TYPES.join(", ")}, each once, in the author's order.`);
+	if (count !== void 0 && (!Number.isInteger(count) || count < 1 || count > 50)) throw new RangeError(`aiDraftsRequest: count must be a whole number from 1 to 50, or left out, not ${String(count)}.`);
+	let facts;
+	if (source.kind === "captions") {
+		const captions = (Array.isArray(source.cues) ? source.cues : []).flatMap((cue, index) => isRecord$1(cue) && typeof cue.text === "string" && cue.text.trim() !== "" && Number.isFinite(cue.start) && Number.isFinite(cue.end) ? [{
+			index,
+			start: cue.start,
+			end: cue.end,
+			text: cue.text
+		}] : []);
+		if (captions.length === 0) return null;
+		facts = {
+			kind: "captions",
+			captions
+		};
+	} else {
+		if (typeof source.text !== "string" || source.text.trim() === "") return null;
+		facts = {
+			kind: source.kind,
+			text: source.text
+		};
+	}
+	return {
+		feature: "draft-generation",
+		facts: {
+			activityTypes: [...types],
+			source: facts,
+			...count !== void 0 ? { count } : {},
+			...locale !== void 0 ? { locale } : {},
+			...level !== void 0 ? { level } : {},
+			...instructions !== void 0 ? { instructions } : {}
+		},
+		shape: replyShape(types, facts.kind === "captions", count ?? 50),
+		...settings !== void 0 ? { settings } : {}
+	};
+}
+const stringOf = (value) => typeof value === "string" ? value : "";
+const listOf = (value) => Array.isArray(value) ? value : [];
+const written = (value) => typeof value === "string" && value.trim() !== "" ? value : void 0;
+function feedbackOf(entry) {
+	if (!isRecord$1(entry.feedback)) return {};
+	const correct = written(entry.feedback.correct);
+	const incorrect = written(entry.feedback.incorrect);
+	return correct === void 0 && incorrect === void 0 ? {} : { feedback: {
+		...correct !== void 0 ? { correct } : {},
+		...incorrect !== void 0 ? { incorrect } : {}
+	} };
+}
+/** A type's content, read from what a model wrote. */
+function contentOf(type, entry, newId) {
+	switch (type) {
+		case "multiple-choice": return {
+			question: stringOf(entry.question),
+			...typeof entry.mode === "string" ? { mode: entry.mode } : {},
+			options: listOf(entry.options).map((option) => {
+				const fields = isRecord$1(option) ? option : {};
+				const feedback = written(fields.feedback);
+				return {
+					id: newId(),
+					text: stringOf(fields.text),
+					isCorrect: fields.isCorrect === true,
+					...feedback !== void 0 ? { feedback } : {}
+				};
+			}),
+			...feedbackOf(entry)
+		};
+		case "fill-in-the-blanks": return {
+			passage: stringOf(entry.passage),
+			blanks: listOf(entry.blanks).map((blank, index) => {
+				const fields = isRecord$1(blank) ? blank : {};
+				const hint = written(fields.hint);
+				return {
+					id: String(index + 1),
+					acceptedAnswers: listOf(fields.acceptedAnswers).filter((answer) => typeof answer === "string"),
+					...hint !== void 0 ? { hint } : {}
+				};
+			}),
+			...feedbackOf(entry)
+		};
+		case "gap-select": return {
+			passage: stringOf(entry.passage),
+			gaps: listOf(entry.gaps).map((gap, index) => {
+				const marked = listOf(isRecord$1(gap) ? gap.choices : void 0);
+				const choices = marked.map((choice) => ({
+					id: newId(),
+					text: stringOf(isRecord$1(choice) ? choice.text : void 0)
+				}));
+				const right = marked.flatMap((choice, at) => isRecord$1(choice) && choice.isCorrect === true ? [at] : []);
+				return {
+					id: String(index + 1),
+					choices,
+					correctChoiceId: right.length === 1 ? choices[right[0]]?.id : ""
+				};
+			}),
+			...feedbackOf(entry)
+		};
+		case "dictation": return {
+			transcript: stringOf(entry.transcript),
+			...feedbackOf(entry)
+		};
+		case "read-aloud": {
+			const instructions = written(entry.instructions);
+			return {
+				referenceText: stringOf(entry.referenceText),
+				...instructions !== void 0 ? { instructions } : {},
+				...feedbackOf(entry)
+			};
+		}
+		default: {
+			const criteria = listOf(isRecord$1(entry.rubric) ? entry.rubric.criteria : void 0);
+			return {
+				prompt: stringOf(entry.prompt),
+				...entry.minWords !== void 0 ? { minWords: entry.minWords } : {},
+				...entry.maxWords !== void 0 ? { maxWords: entry.maxWords } : {},
+				...criteria.length > 0 ? { rubric: { criteria: criteria.map((criterion) => {
+					const fields = isRecord$1(criterion) ? criterion : {};
+					const description = written(fields.description);
+					return {
+						name: stringOf(fields.name),
+						...description !== void 0 ? { description } : {},
+						weight: 1
+					};
+				}) } } : {}
+			};
+		}
+	}
+}
+/**
+* What a new draft of a type starts with, where the model writes nothing: a
+* scoring strategy on the three that have one — `all-or-nothing`, as a new
+* draft has — and a read-aloud's recording and scoring left unset, as a new
+* draft leaves them, for the host's settings or the author to fill.
+*/
+function startOf(type) {
+	switch (type) {
+		case "multiple-choice":
+		case "fill-in-the-blanks":
+		case "gap-select": return { scoringStrategy: "all-or-nothing" };
+		case "read-aloud": return {
+			recording: { maxSeconds: 0 },
+			scoring: { dimensions: [] }
+		};
+		default: return {};
+	}
+}
+/**
+* A draft from what a model wrote. Lenient: every field it can read is kept as
+* written, and anything it cannot is left for `validateDraft` to name — which
+* is what a repair tells the model. Ids are the host's; a blank's and a gap's
+* are the numbers of their placeholders, as the passage names them. In order:
+* what a new draft starts with, the language asked for, the host's settings,
+* then what the model wrote — so a setting never overrides the content, and
+* nothing overrides what the draft is.
+*/
+function draftFrom(type, entry, id, newId, request) {
+	const locale = request.facts.locale;
+	return {
+		...startOf(type),
+		...locale !== void 0 ? { locale } : {},
+		...request.settings?.[type],
+		title: stringOf(entry.title),
+		...contentOf(type, entry, newId),
+		schemaVersion: "1.0",
+		type,
+		id
+	};
+}
+/** Ids from the host, checked as `createDraft` checks them. */
+function idSource(newId, caller) {
+	const issued = /* @__PURE__ */ new Set();
+	return () => {
+		const id = newId();
+		if (typeof id !== "string" || id === "") throw new Error(`${caller}: newId() must return a non-empty string.`);
+		if (issued.has(id)) throw new Error(`${caller}: newId() returned "${id}" twice. Ids must differ — two options sharing an id cannot be scored apart.`);
+		issued.add(id);
+		return id;
+	};
+}
+/** Drafts in the author's order of types, and within a type in the order the model wrote them. */
+function inAuthorsOrder(drafts, types) {
+	return [...drafts].sort((a, b) => types.indexOf(a.type) - types.indexOf(b.type) || a.index - b.index);
+}
+function check(raw, request, newId, keep = []) {
+	const types = request.facts.activityTypes;
+	if (!isRecord$1(raw) || !Array.isArray(raw.drafts) || !raw.drafts.every((entry) => isRecord$1(entry) && types.includes(entry.type))) return {
+		ok: false,
+		refusal: "malformed"
+	};
+	const entries = raw.drafts;
+	const repair = request.repair;
+	const most = request.facts.count ?? 50;
+	if (repair !== void 0 ? entries.length !== repair.length : entries.length > most) return {
+		ok: false,
+		refusal: repair !== void 0 ? "malformed" : "too-long"
+	};
+	const source = request.facts.source;
+	const ordered = inAuthorsOrder(entries.map((entry, position) => {
+		const type = entry.type;
+		const draft = draftFrom(type, entry, keep[position] ?? newId(), newId, request);
+		const caption = source.kind === "captions" && Number.isInteger(entry.caption) ? source.captions.find((one) => one.index === entry.caption) : void 0;
+		const said = require_registry.fold(stringOf(entry.transcript));
+		const clip = type === "dictation" && caption !== void 0 && require_registry.containsWords(require_registry.fold(caption.text), said) ? {
+			start: caption.start,
+			end: caption.end
+		} : void 0;
+		return {
+			index: repair !== void 0 ? repair[position]?.index : position,
+			type,
+			draft,
+			validation: validateDraft(type, draft),
+			findings: critiqueDraft(type, draft),
+			...caption !== void 0 ? { at: caption.end } : {},
+			...clip !== void 0 ? { clip } : {},
+			generated: entry
+		};
+	}), types);
+	const provenance = provenanceOf(raw.provenance);
+	const usage = usageOf(raw.usage);
+	return {
+		ok: true,
+		drafts: {
+			drafts: ordered,
+			findings: require_registry.keyPositionFinding(ordered.map((one) => one.draft), []),
+			...provenance !== void 0 ? { provenance } : {},
+			...usage !== void 0 ? { usage } : {}
+		}
+	};
+}
+/**
+* Reads a model's reply to {@link aiDraftsRequest} into drafts an editor can
+* show for approval: each with ids from `newId`, your settings for its type,
+* what `validateDraft` says of it, what the item critic finds in it, and — from
+* captions — where it goes, and for a dictation the stretch of the video that
+* says its words. They come back in the author's order of types.
+*
+* Drafts are independent: one that is unfinished or wrong is returned as such,
+* for an author or {@link aiDraftsRepairRequest} to fix, beside the ones that
+* are complete. `complete` means valid, never approved: a model wrote it, and a
+* person decides whether learners see it. The whole reply is refused only when
+* it is not `{ drafts: [...] }` of objects of the chosen types (`malformed`), or
+* holds more drafts than asked for (`too-long`) — on a repair, not exactly one
+* per draft to fix (`malformed`).
+*
+* Only the fields a type's shape names are read: a model cannot set an id,
+* HTML, media, a switch or a scoring setting through this. A question is scored
+* `all-or-nothing` unless your settings say otherwise, a written response's
+* criteria are weighted equally, and a dictation carries no recording — attach
+* one, or cut it from the video at `clip`.
+*
+* @throws Error when `newId` returns an empty or repeated id.
+*/
+function checkAiDrafts(raw, request, options) {
+	return check(raw, request, idSource(options.newId, "checkAiDrafts"));
+}
+/**
+* Where a model wrote what a problem names: the draft's paths, but a gap's key
+* is its choices, and a reading too long for the host's recording time is the
+* text the model chose.
+*/
+function pathForModel(type, problem) {
+	const { path, code } = problem;
+	if (type === "gap-select" && path.length === 3 && path[0] === "gaps" && path[2] === "correctChoiceId") return [
+		"gaps",
+		path[1],
+		"choices"
+	];
+	return code === "ra_text_long_for_time" ? ["referenceText"] : [...path];
+}
+/**
+* What is wrong with a draft that the model can fix: every issue and warning
+* at a field the model writes. A read-aloud with no recording time, or a
+* dictation in a video with no recording, is the host's to finish, and is not
+* sent back.
+*/
+function problemsOf(one) {
+	const writes = WRITES[one.type];
+	return [...one.validation.issues.map((found) => ({
+		path: found.path,
+		code: found.code,
+		message: found.message,
+		severity: found.severity
+	})), ...one.findings.filter((found) => found.severity === "warning").map((found) => ({
+		path: found.path,
+		code: found.code,
+		message: found.message,
+		severity: "warning"
+	}))].map((problem) => ({
+		...problem,
+		path: pathForModel(one.type, problem)
+	})).filter((problem) => writes.includes(problem.path[0]));
+}
+/**
+* A second request, for the drafts with something wrong the model can fix —
+* unfinished, wrong, or a flaw the critic warns about, at a field the model
+* writes — each as the model wrote it, with those problems at the paths the
+* model wrote. `null` when there is none.
+*
+* The reply holds one draft for each, in order; {@link checkAiDrafts} reads it
+* and gives each the `index` of the draft it replaces.
+*/
+function aiDraftsRepairRequest(request, drafts) {
+	const repair = ("drafts" in drafts ? drafts.drafts : drafts).flatMap((one) => {
+		const problems = problemsOf(one);
+		return problems.length === 0 ? [] : [{
+			index: one.index,
+			draft: one.generated,
+			problems
+		}];
+	});
+	if (repair.length === 0) return null;
+	const { repair: _previous, ...first } = request;
+	return {
+		...first,
+		shape: replyShape(request.facts.activityTypes, request.facts.source.kind === "captions", repair.length, repair.length),
+		repair
+	};
+}
+const RANK = {
+	complete: 2,
+	incomplete: 1,
+	invalid: 0
+};
+/** Whether a repaired draft is at least as good as the one it would replace. */
+function noWorse(repaired, before) {
+	const warnings = (one) => one.findings.filter((found) => found.severity === "warning").length;
+	const now = RANK[repaired.validation.status];
+	const was = RANK[before.validation.status];
+	return now > was || now === was && warnings(repaired) <= warnings(before);
+}
+/**
+* Drafts items from a source, with a bounded repair loop: asks the port with
+* `request`, reads the reply with {@link checkAiDrafts}, then — up to `repairs`
+* times — sends back the drafts with something wrong the model can fix
+* ({@link aiDraftsRepairRequest}), and keeps a repaired draft only when it is
+* no worse than the one it replaces. A repaired draft keeps its id.
+*
+* Never throws for a model's failure: a port that throws or a reply the SDK
+* refuses ends the loop, and is recorded in `calls` beside the provenance and
+* usage of every call — which the SDK never adds up. A first call that fails
+* leaves no drafts.
+*
+* ```ts
+* const run = await generateDrafts({
+*   request: aiDraftsRequest({ types: ['multiple-choice', 'dictation'], source: { kind: 'transcript', text } }),
+*   port: (request) => callMyModel(DRAFTS_PROMPT, request),
+*   newId: () => crypto.randomUUID(),
+* });
+* // run.drafts: store each as proposed, for a person to approve.
+* ```
+*
+* @throws RangeError when `repairs` is not a whole number from 0 to
+*   {@link AI_DRAFTS_MAX_REPAIRS} (default 1), and Error when `newId` returns an
+*   empty or repeated id.
+*/
+async function generateDrafts(input) {
+	const { request, port, newId } = input;
+	const repairs = input.repairs ?? 1;
+	if (!Number.isInteger(repairs) || repairs < 0 || repairs > 3) throw new RangeError(`generateDrafts: repairs must be a whole number from 0 to 3, not ${String(repairs)}.`);
+	const calls = [];
+	const ids = idSource(newId, "generateDrafts");
+	const ask = async (asked, keep) => {
+		let raw;
+		try {
+			raw = await port(asked);
+		} catch (error) {
+			calls.push({
+				ok: false,
+				error: error instanceof Error ? error.message : String(error)
+			});
+			return;
+		}
+		const checked = check(raw, asked, ids, keep);
+		if (!checked.ok) {
+			calls.push({
+				ok: false,
+				refusal: checked.refusal
+			});
+			return;
+		}
+		const { provenance, usage } = checked.drafts;
+		calls.push({
+			ok: true,
+			...provenance !== void 0 ? { provenance } : {},
+			...usage !== void 0 ? { usage } : {}
+		});
+		return checked.drafts;
+	};
+	const first = await ask(request, []);
+	if (first === void 0) return {
+		drafts: [],
+		findings: [],
+		calls
+	};
+	let current = first.drafts;
+	for (let pass = 0; pass < repairs; pass += 1) {
+		const repairRequest = aiDraftsRepairRequest(request, current);
+		if (repairRequest === null) break;
+		const repaired = await ask(repairRequest, (repairRequest.repair ?? []).map((wanted) => {
+			const before = current.find((one) => one.index === wanted.index);
+			return typeof before?.draft.id === "string" ? before.draft.id : void 0;
+		}));
+		if (repaired === void 0) break;
+		current = current.map((before) => {
+			const after = repaired.drafts.find((one) => one.index === before.index);
+			return after !== void 0 && noWorse(after, before) ? after : before;
+		});
+	}
+	return {
+		drafts: current,
+		findings: require_registry.keyPositionFinding(current.map((one) => one.draft), []),
+		calls
+	};
+}
+/** The source as one text, kept with the video as its author-only transcript. */
+function sourceText(request) {
+	const source = request.facts.source;
+	return source.kind === "captions" ? source.captions.map((caption) => caption.text).join("\n") : source.text;
+}
+/**
+* An interactive video made of drafts: an item group whose stimulus is
+* `video`, whose items are the drafts, and whose timeline opens a quiz at each
+* moment a draft was placed — drafts placed at one moment share its quiz, in
+* the author's order of types — and one more at `durationSeconds` for every
+* draft placed nowhere: all of them when the source had no times.
+*
+* The SDK never reads the video, so it cannot know where the end is: without
+* `durationSeconds` that last quiz has no time yet, which
+* `validateItemGroupDraft` reports for the author to set. The source is kept on
+* the stimulus as its author-only `transcript`.
+*
+* Like every draft it is checked (`validateItemGroupDraft`) and critiqued
+* (`critiqueItemGroupDraft`), never approved. A dictation still needs its own
+* recording; a type a video does not take — a written response — is reported,
+* not dropped.
+*
+* @throws Error when `newId` returns an empty or repeated id.
+*/
+function interactiveVideoFromDrafts(input) {
+	const { request, drafts, video, durationSeconds, title } = input;
+	const ids = idSource(input.newId, "interactiveVideoFromDrafts");
+	const types = request.facts.activityTypes;
+	const list = "drafts" in drafts ? drafts.drafts : drafts;
+	const end = typeof durationSeconds === "number" && Number.isFinite(durationSeconds) && durationSeconds >= 0 ? durationSeconds : void 0;
+	const ordered = [...list.map((one) => ({
+		one,
+		at: one.at ?? end
+	}))].sort((a, b) => (a.at ?? Number.POSITIVE_INFINITY) - (b.at ?? Number.POSITIVE_INFINITY) || types.indexOf(a.one.type) - types.indexOf(b.one.type) || a.one.index - b.one.index);
+	const cues = [];
+	for (const { one, at } of ordered) {
+		const itemId = String(one.draft.id);
+		const last = cues[cues.length - 1];
+		if (last !== void 0 && last.at === at) last.itemIds.push(itemId);
+		else cues.push({
+			id: ids(),
+			...at !== void 0 ? { at } : {},
+			itemIds: [itemId]
+		});
+	}
+	const group = {
+		schemaVersion: "1.0",
+		type: "item-group",
+		id: ids(),
+		...title !== void 0 ? { title } : {},
+		stimulus: {
+			id: ids(),
+			kind: "video",
+			media: video,
+			transcript: sourceText(request)
+		},
+		items: ordered.map(({ one }) => one.draft),
+		timeline: { cues }
+	};
+	return {
+		group,
+		validation: validateItemGroupDraft(group),
+		findings: critiqueItemGroupDraft(group)
+	};
+}
+//#endregion
+//#region src/ai-writing.ts
+/** The most corrections one piece of writing feedback may carry. More is refused, not cut. */
+const AI_WRITING_MAX_CORRECTIONS = 20;
+/** The longest quote, correction, explanation or criterion comment, in code points. */
+const AI_WRITING_MAX_FIELD_LENGTH = 500;
+/** The longest `category` or `band`: a tag, not a sentence. */
+const MAX_TAG_LENGTH = 40;
+/**
+* The request for feedback on a draft, or `null` when there is none to give:
+* not a written response, an author who switched explanations off (writing
+* feedback reads `ai.explanations`), a redacted item — feedback is for
+* practice, where the item is whole — or a draft with nothing in it.
+*
+* The facts are the task as the learner saw it, the draft verbatim with its
+* word count recomputed as the grader will count it, and the rubric the answer
+* will be graded on. `previousFeedback` is the text of the feedback already
+* shown on earlier drafts, so a model can speak to what changed. `group` is the
+* item group the task sits in: its material, the text a summary is of, goes
+* with the request as `material`.
+*/
+function aiWritingFeedbackRequest(input) {
+	const { data, response, learnerLocale } = input;
+	if (!aiSupports(data.type, "writing-feedback") || !aiAllowedByContent(data, "writing-feedback") || data.redacted === true) return null;
+	const text = response?.type === "written-response" ? response.text : "";
+	if (typeof text !== "string" || text.trim() === "") return null;
+	const item = data;
+	const wordCount = require_registry.countWords(text);
+	const minWords = typeof item.minWords === "number" ? item.minWords : 0;
+	const maxWords = typeof item.maxWords === "number" ? item.maxWords : Number.POSITIVE_INFINITY;
+	const criteria = Array.isArray(item.rubric?.criteria) ? item.rubric.criteria : null;
+	const rubric = criteria === null || criteria.length === 0 ? null : criteria.map((criterion) => ({
+		name: criterion.name,
+		...typeof criterion.description === "string" ? { description: criterion.description } : {},
+		weight: criterion.weight
+	}));
+	const previousFeedback = [...input.previousFeedback ?? []];
+	const material = materialFacts(input.group);
+	return {
+		feature: "writing-feedback",
+		facts: {
+			activityType: "written-response",
+			activityId: data.id,
+			title: data.title,
+			...typeof data.locale === "string" ? { locale: data.locale } : {},
+			prompt: typeof item.prompt === "string" ? item.prompt : "",
+			text,
+			wordCount,
+			minWords,
+			maxWords,
+			withinWordBounds: wordCount >= minWords && wordCount <= maxWords,
+			rubric,
+			...typeof item.languageTarget === "string" ? { languageTarget: item.languageTarget } : {}
+		},
+		draftNumber: previousFeedback.length + 1,
+		previousFeedback,
+		...material !== null ? { material } : {},
+		...learnerLocale !== void 0 ? { learnerLocale } : {}
+	};
+}
+/**
+* Where `quote` sits in the draft: at `claimed`, when the model named a range —
+* which must then hold the quote — or else at its first occurrence not already
+* taken by an identical quote, so a mistake made twice is anchored twice. A
+* quote corrected more often than it occurs takes its first occurrence again.
+* `null` when the draft does not contain it where claimed, or at all.
+*/
+function anchor(draft, quote, claimed, taken) {
+	const sought = needle(quote);
+	if (sought === "") return null;
+	if (claimed !== void 0) {
+		const { start, end } = claimed;
+		if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end > draft.text.length || start >= end) return null;
+		const span = draft.text.slice(start, end);
+		if (needle(span) !== sought) return null;
+		const lead = span.length - span.trimStart().length;
+		const trail = span.length - span.trimEnd().length;
+		return {
+			start: start + lead,
+			end: end - trail
+		};
+	}
+	let first = null;
+	for (let at = draft.chars.indexOf(sought); at !== -1; at = draft.chars.indexOf(sought, at + 1)) {
+		const start = draft.from[at];
+		const end = draft.from[at + sought.length - 1] + 1;
+		const found = {
+			start,
+			end
+		};
+		first ??= found;
+		const key = `${start}:${end}`;
+		if (!taken.has(key)) {
+			taken.add(key);
+			return found;
+		}
+	}
+	return first;
+}
+/** A field that must be a string, at most `max` code points once cleaned; `undefined` when absent. */
+function textField(value, max) {
+	if (value === void 0 || value === null) return {
+		ok: true,
+		value: void 0
+	};
+	if (typeof value !== "string") return {
+		ok: false,
+		refusal: "malformed"
+	};
+	const cleaned = cleanText(value);
+	if ([...cleaned].length > max) return {
+		ok: false,
+		refusal: "too-long"
+	};
+	return {
+		ok: true,
+		value: cleaned === "" ? void 0 : cleaned
+	};
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The corrections, each anchored in the draft, or why the reply is refused. */
+function checkCorrections(raw, text) {
+	if (raw === void 0 || raw === null) return {
+		ok: true,
+		corrections: []
+	};
+	if (!Array.isArray(raw)) return {
+		ok: false,
+		refusal: "malformed"
+	};
+	if (raw.length > 20) return {
+		ok: false,
+		refusal: "too-long"
+	};
+	const draft = {
+		text,
+		...folded(text)
+	};
+	const taken = /* @__PURE__ */ new Set();
+	const corrections = [];
+	for (const entry of raw) {
+		if (!isRecord(entry) || typeof entry.original !== "string") return {
+			ok: false,
+			refusal: "malformed"
+		};
+		if (typeof entry.corrected !== "string") return {
+			ok: false,
+			refusal: "malformed"
+		};
+		if ([...entry.original].length > 500 || [...entry.corrected].length > 500) return {
+			ok: false,
+			refusal: "too-long"
+		};
+		if (needle(entry.original) === needle(entry.corrected)) return {
+			ok: false,
+			refusal: "malformed"
+		};
+		const explanation = textField(entry.explanation, 500);
+		const category = textField(entry.category, MAX_TAG_LENGTH);
+		if (!explanation.ok) return explanation;
+		if (!category.ok) return category;
+		let claimed;
+		if (entry.range !== void 0 && entry.range !== null) {
+			if (!isRecord(entry.range)) return {
+				ok: false,
+				refusal: "malformed"
+			};
+			claimed = {
+				start: entry.range.start,
+				end: entry.range.end
+			};
+		}
+		const at = anchor(draft, entry.original, claimed, taken);
+		if (at === null) return {
+			ok: false,
+			refusal: "misquotes-answer"
+		};
+		corrections.push({
+			original: text.slice(at.start, at.end),
+			corrected: cleanText(entry.corrected),
+			...explanation.value !== void 0 ? { explanation: explanation.value } : {},
+			...category.value !== void 0 ? { category: category.value } : {},
+			range: at
+		});
+	}
+	return {
+		ok: true,
+		corrections
+	};
+}
+/** A criterion score a grade could be computed from: finite, 0 or more, and not above its maximum. */
+function isJudgedScore(score, maxScore) {
+	if (score === void 0) return maxScore === void 0 || typeof maxScore === "number" && maxScore > 0;
+	const max = maxScore ?? 1;
+	return typeof score === "number" && typeof max === "number" && Number.isFinite(score) && Number.isFinite(max) && max > 0 && score >= 0 && score - max <= max * 1e-9;
+}
+/** The judgements, each on a criterion the author wrote and weighted as the author weighted it. */
+function checkCriteria(raw, rubric) {
+	if (raw === void 0 || raw === null) return {
+		ok: true,
+		criteria: []
+	};
+	if (!Array.isArray(raw)) return {
+		ok: false,
+		refusal: "malformed"
+	};
+	if (raw.length === 0) return {
+		ok: true,
+		criteria: []
+	};
+	if (rubric === null) return {
+		ok: false,
+		refusal: "malformed"
+	};
+	const weights = new Map(rubric.map((criterion) => [criterion.name, criterion.weight]));
+	const seen = /* @__PURE__ */ new Set();
+	const criteria = [];
+	for (const entry of raw) {
+		if (!isRecord(entry) || typeof entry.name !== "string") return {
+			ok: false,
+			refusal: "malformed"
+		};
+		const weight = weights.get(entry.name);
+		if (weight === void 0 || seen.has(entry.name)) return {
+			ok: false,
+			refusal: "malformed"
+		};
+		seen.add(entry.name);
+		if (!isJudgedScore(entry.score, entry.maxScore)) return {
+			ok: false,
+			refusal: "malformed"
+		};
+		if (entry.notApplicable !== void 0 && typeof entry.notApplicable !== "boolean") return {
+			ok: false,
+			refusal: "malformed"
+		};
+		const band = textField(entry.band, MAX_TAG_LENGTH);
+		const comment = textField(entry.comment, 500);
+		if (!band.ok) return band;
+		if (!comment.ok) return comment;
+		criteria.push({
+			name: entry.name,
+			...typeof entry.score === "number" ? { score: entry.score } : {},
+			...typeof entry.maxScore === "number" ? { maxScore: entry.maxScore } : {},
+			...band.value !== void 0 ? { band: band.value } : {},
+			...comment.value !== void 0 ? { comment: comment.value } : {},
+			...entry.notApplicable === true ? { notApplicable: true } : {},
+			weight
+		});
+	}
+	return {
+		ok: true,
+		criteria
+	};
+}
+/**
+* Checks writing feedback a port returned for `request`, and turns it into what
+* a learner is shown. The SDK shows a model's feedback whole or not at all: it
+* never drops the part it doubts and shows the rest.
+*
+* - **The text** is read as every AI text is (`readAiTextResult`): plain text,
+*   not empty, at most {@link AI_TEXT_MAX_LENGTH} code points.
+* - **Every correction must quote the draft** — the check only this SDK can run.
+*   The SDK finds each quote in the draft itself, typographic quotes and runs of
+*   whitespace aside, and anchors it there; a range the model claims must hold
+*   the quote. A correction of words the learner did not write refuses the
+*   whole reply as `misquotes-answer`, as a hint that gives the answer away
+*   refuses the hint. The `original` shown is the draft's own text at the range.
+*   At most {@link AI_WRITING_MAX_CORRECTIONS}; a correction that changes
+*   nothing is `malformed`.
+* - **Criteria are judgements; the arithmetic is the SDK's.** Each names a
+*   criterion of the item's rubric, once; its score, when it has one, is a
+*   score out of its `maxScore`. The rubric's weights are attached, whatever
+*   the model sent. Anything else is `malformed`, as is any criterion on an
+*   item with no rubric.
+* - **`indicativeScore`** is the rubric's weighted total, computed as
+*   `gradeFromRubric` computes a grade, when every criterion of the rubric was
+*   judged; `null` otherwise. An indication, never a grade.
+*/
+function checkAiWritingFeedback(raw, request) {
+	const read = readAiTextResult(raw);
+	if (!read.ok) return read;
+	const record = raw;
+	const corrections = checkCorrections(record.corrections, request.facts.text);
+	if (!corrections.ok) return corrections;
+	const rubric = request.facts.rubric;
+	const criteria = checkCriteria(record.criteria, rubric);
+	if (!criteria.ok) return criteria;
+	let indicativeScore = null;
+	const judged = new Set(criteria.criteria.map((criterion) => criterion.name));
+	if (rubric?.every((criterion) => judged.has(criterion.name))) {
+		const grade = require_scoring.gradeFromRubric(criteria.criteria);
+		indicativeScore = "unscorable" in grade ? null : grade.score;
+	}
+	const { text, provenance, usage } = read.result;
+	return {
+		ok: true,
+		feedback: {
+			text,
+			corrections: corrections.corrections,
+			criteria: criteria.criteria,
+			indicativeScore,
+			...provenance !== void 0 ? { provenance } : {},
+			...usage !== void 0 ? { usage } : {}
+		}
+	};
+}
+//#endregion
+Object.defineProperty(exports, "AI_COACHING_MAX_TIP_LENGTH", {
+	enumerable: true,
+	get: function() {
+		return AI_COACHING_MAX_TIP_LENGTH;
+	}
+});
+Object.defineProperty(exports, "AI_COACHING_MAX_WORDS", {
+	enumerable: true,
+	get: function() {
+		return AI_COACHING_MAX_WORDS;
+	}
+});
+Object.defineProperty(exports, "AI_CRITIQUE_MAX_FIELD_LENGTH", {
+	enumerable: true,
+	get: function() {
+		return AI_CRITIQUE_MAX_FIELD_LENGTH;
+	}
+});
+Object.defineProperty(exports, "AI_CRITIQUE_MAX_FINDINGS", {
+	enumerable: true,
+	get: function() {
+		return AI_CRITIQUE_MAX_FINDINGS;
+	}
+});
+Object.defineProperty(exports, "AI_DRAFTS_MAX_COUNT", {
+	enumerable: true,
+	get: function() {
+		return AI_DRAFTS_MAX_COUNT;
+	}
+});
+Object.defineProperty(exports, "AI_DRAFTS_MAX_REPAIRS", {
+	enumerable: true,
+	get: function() {
+		return AI_DRAFTS_MAX_REPAIRS;
+	}
+});
+Object.defineProperty(exports, "AI_EXPLANATION_TYPES", {
+	enumerable: true,
+	get: function() {
+		return AI_EXPLANATION_TYPES;
+	}
+});
+Object.defineProperty(exports, "AI_HINT_TYPES", {
+	enumerable: true,
+	get: function() {
+		return AI_HINT_TYPES;
+	}
+});
+Object.defineProperty(exports, "AI_MATERIAL_MAX_LENGTH", {
+	enumerable: true,
+	get: function() {
+		return AI_MATERIAL_MAX_LENGTH;
+	}
+});
+Object.defineProperty(exports, "AI_TEXT_MAX_LENGTH", {
+	enumerable: true,
+	get: function() {
+		return AI_TEXT_MAX_LENGTH;
+	}
+});
+Object.defineProperty(exports, "AI_WRITING_MAX_CORRECTIONS", {
+	enumerable: true,
+	get: function() {
+		return AI_WRITING_MAX_CORRECTIONS;
+	}
+});
+Object.defineProperty(exports, "AI_WRITING_MAX_FIELD_LENGTH", {
+	enumerable: true,
+	get: function() {
+		return AI_WRITING_MAX_FIELD_LENGTH;
+	}
+});
+Object.defineProperty(exports, "aiAllowedByContent", {
+	enumerable: true,
+	get: function() {
+		return aiAllowedByContent;
+	}
+});
+Object.defineProperty(exports, "aiCoachingRequest", {
+	enumerable: true,
+	get: function() {
+		return aiCoachingRequest;
+	}
+});
+Object.defineProperty(exports, "aiCritiqueRequest", {
+	enumerable: true,
+	get: function() {
+		return aiCritiqueRequest;
+	}
+});
+Object.defineProperty(exports, "aiDraftsRepairRequest", {
+	enumerable: true,
+	get: function() {
+		return aiDraftsRepairRequest;
+	}
+});
+Object.defineProperty(exports, "aiDraftsRequest", {
+	enumerable: true,
+	get: function() {
+		return aiDraftsRequest;
+	}
+});
+Object.defineProperty(exports, "aiExplanationRequest", {
+	enumerable: true,
+	get: function() {
+		return aiExplanationRequest;
+	}
+});
+Object.defineProperty(exports, "aiGradeOf", {
+	enumerable: true,
+	get: function() {
+		return aiGradeOf;
+	}
+});
+Object.defineProperty(exports, "aiHintRequest", {
+	enumerable: true,
+	get: function() {
+		return aiHintRequest;
+	}
+});
+Object.defineProperty(exports, "aiSupports", {
+	enumerable: true,
+	get: function() {
+		return aiSupports;
+	}
+});
+Object.defineProperty(exports, "aiWritingFeedbackRequest", {
+	enumerable: true,
+	get: function() {
+		return aiWritingFeedbackRequest;
+	}
+});
+Object.defineProperty(exports, "buildAiFacts", {
+	enumerable: true,
+	get: function() {
+		return buildAiFacts;
+	}
+});
+Object.defineProperty(exports, "checkAiCoaching", {
+	enumerable: true,
+	get: function() {
+		return checkAiCoaching;
+	}
+});
+Object.defineProperty(exports, "checkAiCritique", {
+	enumerable: true,
+	get: function() {
+		return checkAiCritique;
+	}
+});
+Object.defineProperty(exports, "checkAiDrafts", {
+	enumerable: true,
+	get: function() {
+		return checkAiDrafts;
+	}
+});
+Object.defineProperty(exports, "checkAiExplanation", {
+	enumerable: true,
+	get: function() {
+		return checkAiExplanation;
+	}
+});
+Object.defineProperty(exports, "checkAiHint", {
+	enumerable: true,
+	get: function() {
+		return checkAiHint;
+	}
+});
+Object.defineProperty(exports, "checkAiWritingFeedback", {
+	enumerable: true,
+	get: function() {
+		return checkAiWritingFeedback;
+	}
+});
+Object.defineProperty(exports, "createDraft", {
+	enumerable: true,
+	get: function() {
+		return createDraft;
+	}
+});
+Object.defineProperty(exports, "createInteractiveVideoDraft", {
+	enumerable: true,
+	get: function() {
+		return createInteractiveVideoDraft;
+	}
+});
+Object.defineProperty(exports, "createItemGroupDraft", {
+	enumerable: true,
+	get: function() {
+		return createItemGroupDraft;
+	}
+});
+Object.defineProperty(exports, "critiqueDraft", {
+	enumerable: true,
+	get: function() {
+		return critiqueDraft;
+	}
+});
+Object.defineProperty(exports, "critiqueDrafts", {
+	enumerable: true,
+	get: function() {
+		return critiqueDrafts;
+	}
+});
+Object.defineProperty(exports, "critiqueItemGroupDraft", {
+	enumerable: true,
+	get: function() {
+		return critiqueItemGroupDraft;
+	}
+});
+Object.defineProperty(exports, "generateDrafts", {
+	enumerable: true,
+	get: function() {
+		return generateDrafts;
+	}
+});
+Object.defineProperty(exports, "hintRevealsAnswer", {
+	enumerable: true,
+	get: function() {
+		return hintRevealsAnswer;
+	}
+});
+Object.defineProperty(exports, "interactiveVideoFromDrafts", {
+	enumerable: true,
+	get: function() {
+		return interactiveVideoFromDrafts;
+	}
+});
+Object.defineProperty(exports, "readAiTextResult", {
+	enumerable: true,
+	get: function() {
+		return readAiTextResult;
+	}
+});
+Object.defineProperty(exports, "validateDraft", {
+	enumerable: true,
+	get: function() {
+		return validateDraft;
+	}
+});
+Object.defineProperty(exports, "validateItemGroupDraft", {
+	enumerable: true,
+	get: function() {
+		return validateItemGroupDraft;
+	}
+});
+
+//# sourceMappingURL=ai-writing-G6tnCGzw.cjs.map