@intellectif/lk-core 1.10.1 → 1.12.0

package/dist/index.cjs

@@ -1,10 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_registry = require("./registry-C9O9txy5.cjs");
-const require_ai_writing = require("./ai-writing-_wciTWaI.cjs");
-const require_scoring = require("./scoring-Bmfu8RS5.cjs");
-const require_item_group = require("./item-group-C9boy5Mk.cjs");
-const require_schemas = require("./schemas-DcEAuAeU.cjs");
-const require_xapi = require("./xapi-DOAqH9__.cjs");
+const require_registry = require("./registry-DgLcT4rZ.cjs");
+const require_ai_writing = require("./ai-writing-gO4GRscd.cjs");
+const require_scoring = require("./scoring-Cfu_2qQ1.cjs");
+const require_item_group = require("./item-group-CRZNJ08j.cjs");
+const require_schemas = require("./schemas-BA8Y8z-S.cjs");
+const require_xapi = require("./xapi-BhROEuZQ.cjs");
 // src/delivery.ts
 /**
 * The policy that restricts nothing: every setting `true`. It is what an absent
@@ -772,6 +772,710 @@ function diffResponses(before, after) {
 	}
 	return entries;
 }
+// src/reading-route/plan.ts
+const isFields$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function quoted(body, quote) {
+	const match = require_item_group.findQuote(body, quote);
+	return match.found ? {
+		...match.range,
+		text: body.slice(match.range.start, match.range.end)
+	} : void 0;
+}
+const byStart = (a, b) => a.start - b.start || a.end - b.end;
+function sentenceRanges(layout, indices) {
+	return indices.map((index) => {
+		const sentence = layout.sentences[index];
+		return {
+			start: sentence.start,
+			end: sentence.end
+		};
+	});
+}
+function planQuestion(body, layout, item, entry, key, number, level) {
+	const evidence = (Array.isArray(entry.evidence) ? entry.evidence : []).map((quote) => quoted(body, quote)).filter((range) => range !== void 0).map(({ start, end }) => ({
+		start,
+		end
+	})).sort(byStart);
+	const evidenceSentences = [...new Set(evidence.flatMap((range) => require_item_group.sentencesTouching(layout, range)))].sort((a, b) => a - b);
+	const pairs = [];
+	for (const keyword of entry.keywords ?? []) {
+		const passage = keyword.passage === void 0 ? void 0 : quoted(body, keyword.passage);
+		pairs.push({
+			index: pairs.length + 1,
+			question: keyword.question,
+			...passage ? { passage } : {}
+		});
+	}
+	for (const link of entry.links ?? []) {
+		const from = quoted(body, link.from);
+		const to = quoted(body, link.to);
+		if (from !== void 0 && to !== void 0) pairs.push({
+			index: pairs.length + 1,
+			from,
+			to
+		});
+	}
+	const choices = require_item_group.choicesOf(item, entry.partId);
+	const traps = (entry.traps ?? []).map((trap) => {
+		const option = choices.find((choice) => choice.id === trap.optionId)?.text;
+		const lure = trap.lure === void 0 ? void 0 : quoted(body, trap.lure);
+		return {
+			optionId: trap.optionId,
+			kind: trap.kind,
+			...option !== void 0 ? { option } : {},
+			...lure !== void 0 ? { lure } : {}
+		};
+	});
+	return {
+		key,
+		itemId: entry.itemId,
+		...entry.partId !== void 0 ? { partId: entry.partId } : {},
+		number,
+		strategy: entry.strategy,
+		level: evidence.length === 0 ? "solo" : level,
+		evidence,
+		evidenceMatch: entry.evidenceMatch ?? "any",
+		evidenceSentences,
+		pairs,
+		traps,
+		...entry.wordLimit !== void 0 ? { wordLimit: entry.wordLimit } : {},
+		notes: isFields$1(entry.notes) ? { ...entry.notes } : {}
+	};
+}
+function step(question, move, fields = {}) {
+	const note = question.notes[move];
+	return {
+		id: `${question.key}/${move}`,
+		move,
+		level: question.level,
+		question: question.key,
+		number: question.number,
+		strategy: question.strategy,
+		highlight: [],
+		context: [],
+		phrases: [],
+		pairs: [],
+		traps: [],
+		params: {},
+		...fields,
+		...note !== void 0 ? { note } : {}
+	};
+}
+/** The sentences either side of `indices` within their paragraphs, not themselves. */
+function neighbours(layout, indices) {
+	const around = /* @__PURE__ */ new Set();
+	for (const index of indices) {
+		const sentence = layout.sentences[index];
+		if (sentence === void 0) continue;
+		for (const near of [index - 1, index + 1]) if (layout.sentences[near]?.paragraph === sentence.paragraph && !indices.includes(near)) around.add(near);
+	}
+	return [...around].sort((a, b) => a - b);
+}
+/** Label of the paragraph or section that holds a question's first evidence. */
+function regionOf(layout, question) {
+	const first = question.evidenceSentences[0];
+	if (first === void 0) return;
+	const paragraph = layout.paragraphs[layout.sentences[first].paragraph];
+	if (paragraph?.section !== void 0) return layout.sections[paragraph.section]?.label;
+	return paragraph?.label;
+}
+function stepsFor(body, layout, item, question, previous) {
+	const strategy = require_item_group.ROUTE_STRATEGIES[question.strategy];
+	const steps = [];
+	const evidenceRanges = sentenceRanges(layout, question.evidenceSentences);
+	const phrases = question.pairs.flatMap((pair) => pair.question === void 0 ? [] : [pair.question]);
+	const isChoice = item.type !== "fill-in-the-blanks";
+	const answerPart = item.type === "multiple-choice" ? "question" : "answer";
+	const runStart = previous?.strategy !== question.strategy;
+	const region = regionOf(layout, question);
+	const sameRun = previous !== void 0 && !runStart && previous.evidenceSentences.length > 0;
+	const lastBefore = sameRun ? previous.evidenceSentences.at(-1) : void 0;
+	for (const move of strategy.moves) switch (move) {
+		case "survey": break;
+		case "read-instructions": {
+			const hasInstructions = typeof item.instructions === "string" && item.instructions.trim() !== "";
+			if (runStart && (hasInstructions || question.wordLimit !== void 0)) steps.push(step(question, move, {
+				part: hasInstructions ? "instructions" : answerPart,
+				params: question.wordLimit !== void 0 ? { wordLimit: question.wordLimit } : {}
+			}));
+			break;
+		}
+		case "keywords":
+			steps.push(step(question, move, {
+				part: "question",
+				phrases
+			}));
+			break;
+		case "predict":
+			steps.push(step(question, move, { part: answerPart }));
+			break;
+		case "locate": {
+			let zone;
+			if (strategy.followsOrder && lastBefore !== void 0) zone = {
+				start: layout.sentences[lastBefore].end,
+				end: body.length
+			};
+			else if (question.strategy === "matching-headings" && question.evidenceSentences.length > 0) {
+				const paragraph = layout.paragraphs[layout.sentences[question.evidenceSentences[0]].paragraph];
+				if (paragraph !== void 0) zone = {
+					start: paragraph.start,
+					end: paragraph.end
+				};
+			}
+			steps.push(step(question, move, {
+				ask: "locate",
+				highlight: evidenceRanges,
+				phrases,
+				...zone !== void 0 ? { zone } : {},
+				params: {
+					...sameRun ? { previous: previous.number } : {},
+					...region !== void 0 ? { region } : {}
+				}
+			}));
+			break;
+		}
+		case "read-around":
+			steps.push(step(question, move, {
+				highlight: evidenceRanges,
+				context: sentenceRanges(layout, neighbours(layout, question.evidenceSentences))
+			}));
+			break;
+		case "paraphrase": {
+			const keywordPairs = question.pairs.filter((pair) => pair.question !== void 0);
+			steps.push(step(question, move, {
+				part: isChoice && item.type !== "multiple-choice" ? "answer" : "question",
+				highlight: keywordPairs.flatMap((pair) => pair.passage ? [pair.passage] : []),
+				context: evidenceRanges,
+				phrases,
+				pairs: keywordPairs
+			}));
+			break;
+		}
+		case "decide":
+			steps.push(step(question, move, {
+				part: "options",
+				highlight: question.evidence
+			}));
+			break;
+		case "eliminate":
+			steps.push(step(question, move, {
+				part: item.type === "multiple-choice" ? "options" : "answer",
+				highlight: question.evidence,
+				context: question.traps.flatMap((trap) => trap.lure ? [trap.lure] : []),
+				traps: question.traps
+			}));
+			break;
+		case "cohesion": {
+			const links = question.pairs.filter((pair) => pair.from !== void 0);
+			steps.push(step(question, move, {
+				highlight: links.flatMap((pair) => [pair.from, pair.to]),
+				context: evidenceRanges,
+				pairs: links
+			}));
+			break;
+		}
+		case "check-answer":
+			steps.push(step(question, move, {
+				part: "answer",
+				params: question.wordLimit !== void 0 ? { wordLimit: question.wordLimit } : {}
+			}));
+			break;
+		case "compare-views": steps.push(step(question, move, {
+			part: "options",
+			highlight: question.evidence
+		}));
+	}
+	return steps;
+}
+/**
+* The planned route of `group`: its passage laid out, each question with its
+* quotes found, and the steps of every question not at `solo`. A group with
+* no route, or with a redacted one, plans every question at `solo`.
+*/
+function planRoute(group, options = {}) {
+	const body = typeof group.stimulus.body === "string" ? group.stimulus.body : "";
+	const route = group.route;
+	const layout = require_item_group.passageLayout(body, route);
+	const entries = /* @__PURE__ */ new Map();
+	for (const entry of route?.questions ?? []) entries.set(require_item_group.questionKey(entry.itemId, entry.partId), entry);
+	const itemsById = new Map(group.items.map((item) => [item.id, item]));
+	const startAt = route?.startAt ?? 1;
+	const questions = [];
+	for (const found of require_item_group.itemQuestions(group.items)) {
+		const entry = entries.get(found.key);
+		if (entry === void 0 || !require_item_group.isRouteStrategyId(entry.strategy)) continue;
+		const level = options.level ?? options.levels?.[entry.strategy] ?? "walkthrough";
+		questions.push(planQuestion(body, layout, itemsById.get(found.itemId), entry, found.key, startAt + found.position, level));
+	}
+	const steps = [];
+	const surveying = questions.filter((question) => question.level !== "solo").find((question) => require_item_group.ROUTE_STRATEGIES[question.strategy].moves.includes("survey"));
+	if (surveying !== void 0) {
+		const openings = layout.paragraphs.flatMap((paragraph) => {
+			const first = layout.sentences.find((sentence) => sentence.paragraph === paragraph.index && /\p{L}/u.test(body.slice(sentence.start, sentence.end)));
+			return first === void 0 ? [] : [{
+				start: first.start,
+				end: first.end
+			}];
+		});
+		steps.push({
+			id: "survey",
+			move: "survey",
+			level: surveying.level,
+			strategy: surveying.strategy,
+			highlight: openings,
+			context: [],
+			phrases: [],
+			pairs: [],
+			traps: [],
+			params: {}
+		});
+	}
+	let previous;
+	for (const question of questions) {
+		if (question.level !== "solo") steps.push(...stepsFor(body, layout, itemsById.get(question.itemId) ?? {}, question, previous));
+		previous = question;
+	}
+	const levels = {};
+	for (const question of questions) levels[question.strategy] ??= question.level;
+	return {
+		layout,
+		questions,
+		steps,
+		levels
+	};
+}
+// src/reading-route/progress.ts
+/**
+* What a learner did in a route, read back: which answers were right, where
+* they found — or did not find — the evidence, why each wrong answer went
+* wrong, and how much help each strategy should get next time.
+*
+* None of it is a grade. The questions grade exactly as they do without a
+* route; this is the report beside the grade, and the fading that reads it.
+*/
+const LEVELS = [
+	"walkthrough",
+	"coached",
+	"solo"
+];
+const isLevel = (value) => LEVELS.includes(value);
+const isFields = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isCount = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+const isTime = (value) => typeof value === "number" && Number.isFinite(value);
+/** The fingerprint a trace of this passage carries. */
+function routePassageFingerprint(body) {
+	return require_scoring.fingerprint(body);
+}
+function readLevels(value) {
+	const levels = {};
+	if (isFields(value)) {
+		for (const [strategy, level] of Object.entries(value)) if (require_item_group.isRouteStrategyId(strategy) && isLevel(level)) levels[strategy] = level;
+	}
+	return levels;
+}
+function readEvent(value) {
+	if (!isFields(value) || !isTime(value.at)) return null;
+	const { at } = value;
+	const question = typeof value.question === "string" ? value.question : void 0;
+	switch (value.type) {
+		case "started": return {
+			at,
+			type: "started",
+			levels: readLevels(value.levels)
+		};
+		case "finished": return {
+			at,
+			type: "finished"
+		};
+		case "step": return typeof value.step === "string" ? {
+			at,
+			type: "step",
+			step: value.step,
+			...question !== void 0 ? { question } : {}
+		} : null;
+		case "located": return question !== void 0 && isCount(value.sentence) && typeof value.hit === "boolean" ? {
+			at,
+			type: "located",
+			question,
+			sentence: value.sentence,
+			hit: value.hit
+		} : null;
+		case "shown":
+		case "answered": return question !== void 0 ? {
+			at,
+			type: value.type,
+			question
+		} : null;
+		case "marked": return question !== void 0 && isCount(value.sentence) && typeof value.on === "boolean" ? {
+			at,
+			type: "marked",
+			question,
+			sentence: value.sentence,
+			on: value.on
+		} : null;
+		default: return null;
+	}
+}
+/**
+* A stored trace read back. Never throws: anything that is not a trace is
+* `null`, and an event it cannot read is left out rather than failing the rest.
+*/
+function readRouteTrace(value) {
+	if (!isFields(value) || value.traceVersion !== "1" || typeof value.passage !== "string") return null;
+	const events = Array.isArray(value.events) ? value.events.map(readEvent).filter((event) => event !== null) : [];
+	return {
+		traceVersion: "1",
+		passage: value.passage,
+		events
+	};
+}
+function answered(response, partId) {
+	if (response === void 0) return false;
+	switch (response.type) {
+		case "multiple-choice": return Array.isArray(response.selectedOptionIds) && response.selectedOptionIds.length > 0;
+		case "fill-in-the-blanks": return partId !== void 0 && (response.answers?.[partId] ?? "").trim() !== "";
+		case "gap-select": return partId !== void 0 && (response.selections?.[partId] ?? "") !== "";
+		default: return false;
+	}
+}
+function correctIn(outcome, type, partId) {
+	if (outcome === void 0 || outcome.status !== "scored" && outcome.status !== "graded") return null;
+	const details = outcome.status === "scored" ? outcome.details : outcome.details;
+	if (!Array.isArray(details)) return null;
+	if (type === "multiple-choice") return details.every((detail) => detail.outcome === "correct" || detail.outcome === "correct-omission");
+	const detail = details.find((candidate) => candidate.itemId === partId);
+	return detail === void 0 ? null : detail.outcome === "correct";
+}
+/**
+* Whether each question of a routed group was answered correctly, keyed by
+* question key. Graded from `outcomes` where given — a review, or a server's
+* grades — and otherwise by `evaluate` on the full item, as the item's own
+* component would grade it. A question that cannot be graded here (a redacted
+* item and no outcome) reads as not answered.
+*/
+function routeAnswers(group, responses, outcomes = {}) {
+	const itemsById = new Map(group.items.map((item) => [item.id, item]));
+	const graded = /* @__PURE__ */ new Map();
+	const outcomeOf = (itemId) => {
+		if (!graded.has(itemId)) {
+			let outcome = Object.hasOwn(outcomes, itemId) ? outcomes[itemId] : void 0;
+			const response = Object.hasOwn(responses, itemId) ? responses[itemId] : void 0;
+			if (outcome === void 0 && response !== void 0) try {
+				outcome = require_scoring.evaluate(itemsById.get(itemId), response);
+			} catch {
+				outcome = void 0;
+			}
+			graded.set(itemId, outcome);
+		}
+		return graded.get(itemId);
+	};
+	const answers = {};
+	for (const question of require_item_group.itemQuestions(group.items)) {
+		const response = Object.hasOwn(responses, question.itemId) ? responses[question.itemId] : void 0;
+		const answer = { correct: null };
+		if (response?.type === "multiple-choice" && response.selectedOptionIds?.[0] !== void 0) answer.chosen = response.selectedOptionIds[0];
+		else if (response?.type === "gap-select" && question.partId !== void 0) {
+			const chosen = response.selections?.[question.partId];
+			if (chosen !== void 0 && chosen !== "") answer.chosen = chosen;
+		} else if (response?.type === "fill-in-the-blanks" && question.partId !== void 0) {
+			const written = response.answers?.[question.partId];
+			if (written !== void 0 && written.trim() !== "") answer.written = written;
+		}
+		if (answered(response, question.partId)) answer.correct = correctIn(outcomeOf(question.itemId), question.type, question.partId);
+		answers[question.key] = answer;
+	}
+	return answers;
+}
+/** Sentences a learner has marked for a question by the end of the trace. */
+function markedSentences(trace, question) {
+	const marked = /* @__PURE__ */ new Set();
+	for (const event of trace.events) if (event.type === "marked" && event.question === question) {
+		if (event.on) marked.add(event.sentence);
+		else marked.delete(event.sentence);
+	}
+	return [...marked].sort((a, b) => a - b);
+}
+/**
+* Whether marked sentences find the evidence: at least one of them holds it,
+* and no more were marked than the evidence spans plus one. Marking a whole
+* paragraph is what weaker readers do, and it is not finding the answer.
+*/
+function marksFindEvidence(marked, evidence) {
+	return marked.some((sentence) => evidence.includes(sentence)) && marked.length <= Math.max(2, evidence.length + 1);
+}
+/**
+* The report of one route: per question, whether the learner found the
+* evidence and with how much help, whether they answered correctly, and the
+* cause of each wrong answer; per strategy, the totals that fading reads.
+* `answers` is `routeAnswers`'s result. The order the learner looked in is
+* never part of it: there is more than one good way to read.
+*/
+function summarizeRoute(group, trace, answers) {
+	const started = trace.events.find((event) => event.type === "started");
+	const finished = [...trace.events].reverse().find((event) => event.type === "finished");
+	const plan = planRoute(group, { levels: started?.type === "started" ? started.levels : {} });
+	const firstStep = /* @__PURE__ */ new Map();
+	const answeredAt = /* @__PURE__ */ new Map();
+	for (const event of trace.events) {
+		if (event.type === "step" && event.question !== void 0 && !firstStep.has(event.question)) firstStep.set(event.question, event.at);
+		if (event.type === "answered" && !answeredAt.has(event.question)) answeredAt.set(event.question, event.at);
+	}
+	const answerTimes = [...answeredAt.entries()].sort((a, b) => a[1] - b[1]);
+	const sinceBefore = /* @__PURE__ */ new Map();
+	answerTimes.forEach(([key, at], index) => {
+		const before = index === 0 ? started?.at : answerTimes[index - 1]?.[1];
+		if (before !== void 0) sinceBefore.set(key, Math.max(0, at - before));
+	});
+	const questions = plan.questions.map((question) => {
+		const locates = trace.events.filter((event) => event.type === "located" && event.question === question.key);
+		const shown = trace.events.some((event) => event.type === "shown" && event.question === question.key);
+		let located = null;
+		if (locates[0] !== void 0) located = locates[0].hit;
+		else if (shown) located = false;
+		else {
+			const marked = markedSentences(trace, question.key);
+			if (marked.length > 0) located = marksFindEvidence(marked, question.evidenceSentences);
+		}
+		const answer = answers[question.key];
+		const correct = answer?.correct ?? null;
+		let cause = null;
+		let trap;
+		if (correct === null) cause = "unanswered";
+		else if (!correct) {
+			trap = question.traps.find((candidate) => candidate.optionId === answer?.chosen)?.kind;
+			if (question.wordLimit !== void 0 && answer?.written !== void 0 && require_registry.countWords(answer.written) > question.wordLimit) cause = "limit";
+			else if (trap !== void 0) cause = "trap";
+			else if (located === false) cause = "search";
+			else if (located === true) cause = "meaning";
+			else cause = "unknown";
+		}
+		const answeredTime = answeredAt.get(question.key);
+		const stepTime = firstStep.get(question.key);
+		const seconds = answeredTime === void 0 ? null : stepTime !== void 0 ? Math.max(0, answeredTime - stepTime) / 1e3 : (sinceBefore.get(question.key) ?? 0) / 1e3;
+		return {
+			key: question.key,
+			itemId: question.itemId,
+			...question.partId !== void 0 ? { partId: question.partId } : {},
+			number: question.number,
+			strategy: question.strategy,
+			level: question.level,
+			located,
+			tries: locates.length,
+			shown,
+			correct,
+			cause: correct === true ? null : cause,
+			...answer?.chosen !== void 0 ? { chosen: answer.chosen } : {},
+			...trap !== void 0 && cause === "trap" ? { trap } : {},
+			seconds
+		};
+	});
+	const strategies = [];
+	for (const question of questions) {
+		let entry = strategies.find((candidate) => candidate.strategy === question.strategy);
+		if (entry === void 0) {
+			entry = {
+				strategy: question.strategy,
+				level: question.level,
+				questions: 0,
+				correct: 0,
+				located: 0,
+				locatable: 0
+			};
+			strategies.push(entry);
+		}
+		entry.questions += 1;
+		entry.correct += question.correct === true ? 1 : 0;
+		if (question.located !== null) {
+			entry.locatable += 1;
+			entry.located += question.located ? 1 : 0;
+		}
+	}
+	return {
+		groupId: group.id,
+		questions,
+		strategies,
+		correct: questions.filter((question) => question.correct === true).length,
+		total: questions.length,
+		seconds: started !== void 0 && finished !== void 0 ? Math.max(0, finished.at - started.at) / 1e3 : null
+	};
+}
+/** A stored learner state read back. Never throws: anything unreadable is a fresh state. */
+function readRouteLearnerState(value) {
+	const state = {
+		stateVersion: "1",
+		strategies: {},
+		seen: []
+	};
+	if (!isFields(value) || value.stateVersion !== "1") return state;
+	if (isFields(value.strategies)) {
+		for (const [strategy, entry] of Object.entries(value.strategies)) if (require_item_group.isRouteStrategyId(strategy) && isFields(entry) && isLevel(entry.level)) state.strategies[strategy] = {
+			level: entry.level,
+			streak: typeof entry.streak === "number" && Number.isInteger(entry.streak) ? entry.streak : 0
+		};
+	}
+	if (Array.isArray(value.seen)) state.seen = value.seen.filter((id) => typeof id === "string");
+	return state;
+}
+/**
+* The level each strategy of `group` is presented at: the learner's, or
+* `entry` for a strategy they have not met. `level` pins one for all.
+*/
+function routeLevels(group, state, options = {}) {
+	const levels = {};
+	for (const question of group.route?.questions ?? []) if (require_item_group.isRouteStrategyId(question.strategy)) levels[question.strategy] = options.level ?? state?.strategies[question.strategy]?.level ?? options.entry ?? "walkthrough";
+	return levels;
+}
+const lessHelp = (level) => LEVELS[Math.min(LEVELS.indexOf(level) + 1, LEVELS.length - 1)];
+const moreHelp = (level) => LEVELS[Math.max(LEVELS.indexOf(level) - 1, 0)];
+/**
+* The learner's next state after a route. Per strategy, a question succeeds
+* when it is right, its evidence was not missed, and the learner did not ask
+* to be shown; `promoteAfter` successes in a row take one level of help away,
+* `demoteAfter` failures in a row give one back, and one passage moves a
+* strategy at most one level. A passage already in `seen` changes nothing:
+* a second attempt is memory of where the answers were.
+*/
+function nextRouteLearnerState(state, summary, options = {}) {
+	const current = readRouteLearnerState(state);
+	if (current.seen.includes(summary.groupId)) return current;
+	const promoteAfter = Math.max(1, options.promoteAfter ?? 2);
+	const demoteAfter = Math.max(1, options.demoteAfter ?? 2);
+	const remember = Math.max(1, options.remember ?? 500);
+	const strategies = { ...current.strategies };
+	for (const totals of summary.strategies) {
+		const base = totals.level;
+		const stored = strategies[totals.strategy];
+		let streak = stored?.level === base ? stored.streak : 0;
+		let level = base;
+		for (const question of summary.questions) {
+			if (question.strategy !== totals.strategy) continue;
+			streak = question.correct === true && question.located !== false && !question.shown ? Math.max(streak, 0) + 1 : Math.min(streak, 0) - 1;
+			if (streak >= promoteAfter && lessHelp(level) !== level) {
+				level = lessHelp(level);
+				streak = 0;
+				break;
+			}
+			if (streak <= -demoteAfter && moreHelp(level) !== level) {
+				level = moreHelp(level);
+				streak = 0;
+				break;
+			}
+		}
+		strategies[totals.strategy] = {
+			level,
+			streak: Math.max(-demoteAfter, Math.min(promoteAfter, streak))
+		};
+	}
+	return {
+		stateVersion: "1",
+		strategies,
+		seen: [...current.seen, summary.groupId].slice(-remember)
+	};
+}
+// src/reading-route/text.ts
+const NUMBER_WORDS = [
+	"",
+	"ONE",
+	"TWO",
+	"THREE",
+	"FOUR",
+	"FIVE",
+	"SIX",
+	"SEVEN",
+	"EIGHT",
+	"NINE",
+	"TEN"
+];
+/** "NO MORE THAN TWO WORDS", as the instructions of a paper write it. */
+function limitWords(limit) {
+	return `${NUMBER_WORDS[limit] ?? String(limit)} WORD${limit === 1 ? "" : "S"}`;
+}
+const quote = (words) => `“${words}”`;
+function list(words) {
+	const quoted = words.map(quote);
+	if (quoted.length <= 1) return quoted.join("");
+	return `${quoted.slice(0, -1).join(", ")} and ${quoted.at(-1)}`;
+}
+/** Why a trapped option attracts, in one sentence. */
+function routeTrapText(trap) {
+	const option = trap.option !== void 0 && trap.option !== "" ? quote(trap.option) : "This option";
+	return {
+		"word-match": `${option} repeats words from the text, but the text says something different about them.`,
+		opposite: `${option} says the opposite of what the text says.`,
+		partial: `${option} is only partly right: the text supports one half of it, not all of it.`,
+		"outside-knowledge": `${option} may be true in the real world, but this text does not say it.`,
+		"too-general": `${option} is too general: the text is about something narrower.`,
+		"too-specific": `${option} is too specific: it matches one detail, not the whole idea.`,
+		"not-the-question": `${option} is true, but it does not answer this question.`
+	}[trap.kind];
+}
+/**
+* What the learner reads at a step, in English. An author's note for the step
+* replaces the strategy's words.
+*/
+function routeStepText(step) {
+	if (step.note !== void 0) return step.note;
+	const n = step.number ?? 0;
+	const strategy = step.strategy;
+	const phrases = step.phrases;
+	const limit = step.params.wordLimit;
+	switch (step.move) {
+		case "survey":
+			if (strategy === "gapped-text") return "First read the main text, skipping the gaps, to follow its line of thought. Then skim the missing paragraphs to see what each is about.";
+			if (strategy === "cross-text") return "Before the questions, skim each text for its writer's overall opinion. Note where each one stands on the topic.";
+			return "Before the questions, skim: read the title and the first sentence of each paragraph. You want what each part is about, not the details.";
+		case "read-instructions":
+			if (limit !== void 0) return `Read the instructions first. Write NO MORE THAN ${limitWords(limit)} from the text: a longer answer loses the mark, even when it is correct.`;
+			if (strategy === "tfng") return "Read the instructions. True / False / Not Given asks about facts: does the text give this information, contradict it, or not say?";
+			if (strategy === "ynng") return "Read the instructions. Yes / No / Not Given asks about the writer's views and claims, not about facts in general.";
+			return "Read the instructions first: they say exactly what to find and how to answer.";
+		case "keywords":
+			if (strategy === "matching-information") return `Question ${n} asks for a kind of information — an example, a reason, a comparison, a description. Note which kind${phrases.length > 0 ? `, and its key words: ${list(phrases)}` : ""}.`;
+			if (phrases.length > 0) return `Find the key words in question ${n}: ${list(phrases)}. Names, numbers, dates and specialist terms are the easiest to scan for, because the text rarely changes them.`;
+			return `Find the key words in question ${n}: the words that tell you what to look for. Names, numbers, dates and specialist terms are the easiest to scan for.`;
+		case "predict":
+			if (strategy === "multiple-choice") return `Read the question, not the options. Try to answer question ${n} in your own words before you look at the choices.`;
+			if (strategy === "sentence-endings") return `Read the beginning of sentence ${n} and predict how it could end. The ending must complete it in meaning and in grammar.`;
+			return `Before you look, predict the answer to question ${n}: what kind of word fits — a noun, a number, a verb, an adjective? Singular or plural?`;
+		case "locate": {
+			const target = phrases.length > 0 ? list(phrases) : "the key words";
+			if (strategy === "matching-headings") return `Which sentence carries the main idea of ${step.params.region !== void 0 ? `paragraph ${step.params.region}` : "this paragraph"}? It is often the first or the last, but read the whole paragraph to be sure.`;
+			if (strategy === "gapped-text") return `Read the sentences just before and just after gap ${n}. Which sentence in the missing paragraphs connects to them?`;
+			if (strategy === "cross-text") return `Find where the texts discuss ${target}. You need what every writer thinks, not just one of them.`;
+			if (strategy !== void 0 && require_item_group.ROUTE_STRATEGIES[strategy].followsOrder) {
+				if (step.params.previous !== void 0) return `Scan for ${target}, or words that mean the same. The answers follow the order of the text, so start after the answer to question ${step.params.previous}.`;
+				return `Scan for ${target}, or words that mean the same. The answers follow the order of the text: this is the first question of its set, so its answer comes before the others.`;
+			}
+			return `Scan the whole text for ${target}, or words that mean the same.${strategy === "matching-information" ? " This information can be anywhere, and one paragraph may hold more than one answer." : " These answers can come in any order."}`;
+		}
+		case "read-around": return "Now read this sentence carefully, with the one before and the one after it. The answer depends on every word — small ones like \"only\", \"all\", \"not\" and \"some\" most of all.";
+		case "paraphrase": {
+			const shown = step.pairs.filter((pair) => pair.question !== void 0 && pair.passage !== void 0);
+			if (shown.length > 0) return `Same meaning, different words: ${shown.map((pair) => `the question says ${quote(pair.question)}, the text says ${quote(pair.passage?.text)}`).join("; ")}. That is how answers are hidden.`;
+			return "Compare the question's words with the text's. Look for the same idea in different words, not for the same words.";
+		}
+		case "decide":
+			if (strategy === "ynng") return "Decide. If the writer agrees with the statement, it is Yes. If the writer says the opposite, it is No. If you cannot tell what the writer thinks, it is Not Given.";
+			return "Decide. If the text agrees with the statement, it is True. If it says the opposite, it is False. If it does not say, it is Not Given. Use only the text, never what you know.";
+		case "eliminate": {
+			const traps = step.traps.map(routeTrapText).join(" ");
+			const tail = traps === "" ? "" : ` ${traps}`;
+			if (strategy === "matching-headings") return `Compare the paragraph's main idea with the headings. A heading that matches a single detail or example is a trap.${tail}`;
+			if (strategy === "sentence-endings") return `Check each ending: it must say what the text says and fit the grammar of the beginning. Some endings are true but belong to another sentence.${tail}`;
+			if (strategy === "gapped-text") return `Test your choice: does its first sentence follow on from the text before the gap, and does its last sentence lead into the text after it? One paragraph fits nowhere.${tail}`;
+			return `Check every option against the sentence you found. Reject one that repeats words from the text but changes the meaning, or that is true but does not answer the question.${tail}`;
+		}
+		case "cohesion": {
+			const links = step.pairs.filter((pair) => pair.from !== void 0 && pair.to !== void 0);
+			if (links.length > 0) return `Follow the links: ${links.map((pair) => `${quote(pair.from?.text)} points to ${quote(pair.to?.text)}`).join("; ")}. Words like these show which paragraph belongs in the gap.`;
+			return "Look for words that point backwards or forwards — this, these, such, it, they; however, as a result, also. They show which paragraph belongs in the gap.";
+		}
+		case "check-answer":
+			if (strategy === "summary-word-list") return "Check your choice fits the grammar of the summary and means what the text says. The list uses different words from the text.";
+			return limit !== void 0 ? `Check your answer: spell it exactly as the text does, make sure it fits the grammar of the sentence, and count the words — no more than ${limit}.` : "Check your answer: spell it exactly as the text does, and make sure it fits the grammar of the sentence.";
+		case "compare-views": return "Compare what the writers say about it. Which of them agree, and which one takes a different view?";
+	}
+}
 // src/redact.ts
 /** Merges per-call overrides over a registered policy, one level deep. */
 function mergePolicy(base, overrides) {
@@ -918,6 +1622,28 @@ const ITEM_GROUP_FIELD_POLICY = {
 			title: "public"
 		},
 		navigation: "public"
+	},
+	route: {
+		routeVersion: "public",
+		startAt: "public",
+		paragraphLabels: "public",
+		sections: {
+			label: "public",
+			title: "public",
+			paragraphs: "public"
+		},
+		questions: {
+			itemId: "public",
+			partId: "public",
+			strategy: "public",
+			wordLimit: "public",
+			evidence: "answer-key",
+			evidenceMatch: "answer-key",
+			keywords: "answer-key",
+			links: "answer-key",
+			traps: "answer-key",
+			notes: "answer-key"
+		}
 	}
 };
 /**
@@ -1389,10 +2115,16 @@ exports.DeferredScoringError = require_registry.DeferredScoringError;
 exports.INTERACTIVE_VIDEO_ITEM_TYPES = require_item_group.INTERACTIVE_VIDEO_ITEM_TYPES;
 exports.ITEM_SCORING_MAX_RETRIES = require_scoring.ITEM_SCORING_MAX_RETRIES;
 exports.OPEN_DELIVERY_POLICY = OPEN_DELIVERY_POLICY;
+exports.READING_ROUTE_ITEM_TYPES = require_item_group.READING_ROUTE_ITEM_TYPES;
 exports.READ_ALOUD_MAX_DIMENSION_WEIGHT = require_registry.READ_ALOUD_MAX_DIMENSION_WEIGHT;
 exports.READ_ALOUD_MAX_REFERENCE_LENGTH = require_registry.READ_ALOUD_MAX_REFERENCE_LENGTH;
 exports.READ_ALOUD_MAX_SECONDS = require_registry.READ_ALOUD_MAX_SECONDS;
 exports.READ_ALOUD_MAX_TAKES = require_registry.READ_ALOUD_MAX_TAKES;
+exports.ROUTE_NOTE_MAX_LENGTH = require_item_group.ROUTE_NOTE_MAX_LENGTH;
+exports.ROUTE_SEGMENTER = require_item_group.ROUTE_SEGMENTER;
+exports.ROUTE_STRATEGIES = require_item_group.ROUTE_STRATEGIES;
+exports.ROUTE_STRATEGY_IDS = require_item_group.ROUTE_STRATEGY_IDS;
+exports.ROUTE_WORD_LIMIT_MAX = require_item_group.ROUTE_WORD_LIMIT_MAX;
 exports.RedactedScoringError = require_registry.RedactedScoringError;
 exports.SCRIPT_MAX_TURNS = require_registry.SCRIPT_MAX_TURNS;
 exports.SPEECH_ASSESSMENT_MAX_WORDS = require_registry.SPEECH_ASSESSMENT_MAX_WORDS;
@@ -1440,10 +2172,12 @@ exports.composeTimelineScore = composeTimelineScore;
 exports.computePassThreshold = require_scoring.computePassThreshold;
 exports.contentHash = require_scoring.contentHash;
 exports.contentJsonSchema = require_schemas.contentJsonSchema;
+exports.countParagraphs = require_item_group.countParagraphs;
 exports.countWords = require_registry.countWords;
 exports.createDraft = require_ai_writing.createDraft;
 exports.createInteractiveVideoDraft = require_ai_writing.createInteractiveVideoDraft;
 exports.createItemGroupDraft = require_ai_writing.createItemGroupDraft;
+exports.createReadingRouteDraft = require_ai_writing.createReadingRouteDraft;
 exports.critiqueDraft = require_ai_writing.critiqueDraft;
 exports.critiqueDrafts = require_ai_writing.critiqueDrafts;
 exports.critiqueItemGroupDraft = require_ai_writing.critiqueItemGroupDraft;
@@ -1459,6 +2193,7 @@ exports.evaluate = require_scoring.evaluate;
 exports.evaluateTries = require_scoring.evaluateTries;
 exports.fillInTheBlanksJsonSchema = require_schemas.fillInTheBlanksJsonSchema;
 exports.fillInTheBlanksType = require_registry.fillInTheBlanksType;
+exports.findQuote = require_item_group.findQuote;
 exports.fingerprint = require_scoring.fingerprint;
 exports.flattenSequence = flattenSequence;
 exports.gapSelectJsonSchema = require_schemas.gapSelectJsonSchema;
@@ -1481,23 +2216,36 @@ exports.interactiveVideoFromDrafts = require_ai_writing.interactiveVideoFromDraf
 exports.isBuiltInActivityType = require_registry.isBuiltInActivityType;
 exports.isInteractiveVideoItemType = require_item_group.isInteractiveVideoItemType;
 exports.isItemGroup = isItemGroup;
+exports.isReadingRouteItemType = require_item_group.isReadingRouteItemType;
+exports.isRouteStrategyId = require_item_group.isRouteStrategyId;
 exports.itemGroupJsonSchema = require_schemas.itemGroupJsonSchema;
 exports.jsonSchemaFor = require_schemas.jsonSchemaFor;
 exports.levenshteinDistance = require_registry.levenshteinDistance;
 exports.listMediaRefs = require_ai_writing.listMediaRefs;
 exports.mapMediaRefs = require_ai_writing.mapMediaRefs;
+exports.markedSentences = markedSentences;
+exports.marksFindEvidence = marksFindEvidence;
 exports.matchText = require_registry.matchText;
 exports.multipleChoiceJsonSchema = require_schemas.multipleChoiceJsonSchema;
 exports.multipleChoiceType = require_registry.multipleChoiceType;
+exports.nextRouteLearnerState = nextRouteLearnerState;
 exports.outcomeFromGrade = require_scoring.outcomeFromGrade;
 exports.outcomeFromRoutedGrade = require_scoring.outcomeFromRoutedGrade;
 exports.outcomeFromUnscorable = require_scoring.outcomeFromUnscorable;
+exports.overlaps = require_item_group.overlaps;
+exports.passageLayout = require_item_group.passageLayout;
 exports.planAttempt = planAttempt;
 exports.planMediaBudgets = planMediaBudgets;
+exports.planRoute = planRoute;
+exports.questionKey = require_item_group.questionKey;
+exports.quoteText = require_item_group.quoteText;
 exports.readAiTextResult = require_ai_writing.readAiTextResult;
 exports.readAloudJsonSchema = require_schemas.readAloudJsonSchema;
 exports.readAloudType = require_registry.readAloudType;
 exports.readMediaProgress = readMediaProgress;
+exports.readRouteLearnerState = readRouteLearnerState;
+exports.readRouteTrace = readRouteTrace;
+exports.readingQuizzes = require_item_group.readingQuizzes;
 exports.redact = redact;
 exports.redactItemGroup = redactItemGroup;
 exports.registerActivityType = require_registry.registerActivityType;
@@ -1508,16 +2256,24 @@ exports.resolvePlaybackPolicy = resolvePlaybackPolicy;
 exports.restoreAttemptState = restoreAttemptState;
 exports.restoreMediaPlayLedger = restoreMediaPlayLedger;
 exports.roundGrade = require_scoring.roundGrade;
+exports.routeAnswers = routeAnswers;
 exports.routeGrade = require_scoring.routeGrade;
+exports.routeIssues = require_item_group.routeIssues;
+exports.routeLevels = routeLevels;
+exports.routePassageFingerprint = routePassageFingerprint;
+exports.routeStepText = routeStepText;
+exports.routeTrapText = routeTrapText;
 exports.score = require_scoring.score;
 exports.scoreTries = require_scoring.scoreTries;
 exports.scoredItemsFromPlan = scoredItemsFromPlan;
 exports.seededShuffle = require_scoring.seededShuffle;
+exports.sentencesTouching = require_item_group.sentencesTouching;
 exports.serializeAttemptState = serializeAttemptState;
 exports.serializeMediaPlayLedger = serializeMediaPlayLedger;
 exports.slotMediaKey = slotMediaKey;
 exports.stimulusJsonSchema = require_schemas.stimulusJsonSchema;
 exports.stimulusMediaKey = stimulusMediaKey;
+exports.summarizeRoute = summarizeRoute;
 exports.transcriptOf = require_ai_writing.transcriptOf;
 exports.validateActivity = require_schemas.validateActivity;
 exports.validateDeliveryPolicy = validateDeliveryPolicy;