@classytic/labs 0.6.0 → 0.7.0

package/dist/domains/chem/electrochemistry/redox-transfer/model.mjs

@@ -0,0 +1,807 @@
+import { defineLabModel } from "../../../../model/define.mjs";
+import { isRefusal, refuse } from "../../../../model/index.mjs";
+import { BAYS, DEFAULT_CARDS, DEFAULT_DRILL, DEFAULT_TRANSFER, DRILL_ITEMS, SORT_CARDS, TRANSFER_CASES } from "./cases.mjs";
+import { z } from "zod";
+import { classifyRedox, formulaDisplayText, oxidationNumberOf, parseSpecies } from "@classytic/stage/chem";
+import { elementBySymbol, ionConfigurationOf } from "@classytic/stage/atomic";
+
+//#region src/domains/chem/electrochemistry/redox-transfer/model.ts
+/**
+* Redox transfer (Class 9): electrons move from one atom to another, oxidation numbers say where,
+* and the reaction goes into one of five bays.
+*
+* Three modes, chosen by the lesson (`mode`):
+*   demo   an electron is carried from the donor atom to the acceptor atom, then each species is named
+*          reductant or oxidant. The first case is the worked example, later cases are changed cases.
+*   drill  the oxidation number of one element is found by turning a dial until the sum of all the
+*          numbers on the balance equals the charge of the species (book p149-150).
+*   sort   a reaction card, with its oxidation-number strip, goes into addition, decomposition,
+*          displacement, combustion or non-redox.
+*
+* Every chemical fact is read from stage's `redox-class` kernel: `classifyRedox` for what changes, who
+* gives and who takes, which types fit and how many electrons move; `oxidationNumberOf` for every
+* number the drill shows. Shell counts for the drawn atoms come from stage's `ionConfigurationOf`. This
+* file selects, groups and words those results. It owns no chemical rule.
+*
+* Oxidation numbers are whole numbers only (the kernel refuses fractions). The sort accepts every
+* type that fits a card (C + O2 is both addition and combustion), so a card can have two right bays.
+*
+* `goals` that do not belong to the lesson's mode are true, so one witness can satisfy them all; an
+* activity names only the goals of its own mode.
+*/
+/** The dial's range (book p150 drill answers run from -4 to +8). */
+const GUESS_RANGE = [-4, 8];
+/** The bead counts as dropped on the acceptor from this far along its path. */
+const DROP_AT = .65;
+/** A signed whole number as chemists write it: +6, 0, and a true minus sign for -2. */
+const signed = (n) => n > 0 ? `+${n}` : n < 0 ? `−${-n}` : "0";
+const unique = (list) => [...new Set(list)];
+const gcd = (a, b) => b === 0 ? a : gcd(b, a % b);
+/** `2Na + Cl2 -> 2NaCl` with subscripts and an arrow. Display only. */
+function displayEquation(equation) {
+	const side = (text) => text.split(/\s+\+\s+/).map((term) => {
+		const m = /^(\d+)?\s*(.+)$/.exec(term.trim());
+		return `${m[1] ?? ""}${formulaDisplayText(m[2])}`;
+	}).join(" + ");
+	const [left = "", right = ""] = equation.split("->");
+	return `${side(left)} → ${side(right)}`;
+}
+const electronsText = (n) => `${n === 1 ? "" : n}e⁻`;
+const ionText = (symbol, charge) => formulaDisplayText(`${symbol}^${Math.abs(charge) === 1 ? "" : Math.abs(charge)}${charge > 0 ? "+" : "-"}`);
+/** The shell counts of an atom or ion, innermost first: Na is 2,8,1 and Na+ is 2,8. From stage. */
+function shellCounts(Z, charge) {
+	const byShell = new Map();
+	for (const o of ionConfigurationOf(Z, charge)) byShell.set(o.n, (byShell.get(o.n) ?? 0) + o.electrons);
+	return [...byShell.entries()].sort(([a], [b]) => a - b).map(([, n]) => n);
+}
+/** Each element of an equation with its oxidation numbers before and after, from the kernel's reading. */
+function stripOf(reading) {
+	const elements = unique(reading.species.flatMap((sp) => Object.keys(sp.oxidationNumbers)));
+	const numbers = (element, side) => unique(reading.species.filter((sp) => sp.side === side && element in sp.oxidationNumbers).map((sp) => sp.oxidationNumbers[element])).sort((a, b) => a - b);
+	return elements.map((element) => {
+		const before = numbers(element, "reactant");
+		const after = numbers(element, "product");
+		return {
+			element,
+			before: before.map(signed).join(", "),
+			after: after.map(signed).join(", "),
+			changed: before.join() !== after.join()
+		};
+	});
+}
+function atomCount(reading, formula, element) {
+	const sp = reading.species.find((x) => x.side === "reactant" && x.formula === formula);
+	return sp.coefficient * (parseSpecies(formula).elements[element] ?? 0);
+}
+function transferCase(spec) {
+	const reading = classifyRedox(spec.equation);
+	if (isRefusal(reading)) return reading;
+	const display = displayEquation(spec.equation);
+	const base = {
+		id: spec.id,
+		name: spec.name,
+		equation: spec.equation,
+		display,
+		drawn: display,
+		unitNote: "",
+		strip: stripOf(reading),
+		...spec.bookNote ? { bookNote: spec.bookNote } : {}
+	};
+	if (!reading.redox) return {
+		...base,
+		redox: false,
+		donor: null,
+		acceptor: null,
+		electrons: 0,
+		truth: {},
+		halves: null
+	};
+	const gives = reading.changes.filter((c) => c.to > c.from);
+	const takes = reading.changes.filter((c) => c.to < c.from);
+	const [up, down] = [gives[0], takes[0]];
+	if (reading.changes.length !== 2 || !up || !down || up.from !== 0 || down.from !== 0) return refuse("transfer-needs-atoms", `${spec.equation}: the transfer picture needs one free element that gives and one that takes.`, { id: spec.id });
+	const each = {
+		donor: up.to - up.from,
+		acceptor: down.from - down.to
+	};
+	const whole = {
+		donor: atomCount(reading, up.species, up.element),
+		acceptor: atomCount(reading, down.species, down.element)
+	};
+	if (whole.donor * each.donor !== reading.electronsPerFormula || whole.acceptor * each.acceptor !== reading.electronsPerFormula) return refuse("transfer-count-mismatch", `${spec.equation}: the atoms drawn would move ${whole.donor * each.donor} electrons but stage counts ${reading.electronsPerFormula}.`, { id: spec.id });
+	const fits = (donors, acceptors) => donors <= 3 && acceptors <= 3 && donors * each.donor <= 6;
+	const k = fits(whole.donor, whole.acceptor) ? 1 : gcd(whole.donor, whole.acceptor);
+	const count = {
+		donor: whole.donor / k,
+		acceptor: whole.acceptor / k
+	};
+	const products = reading.species.filter((sp) => sp.side === "product");
+	if (!fits(count.donor, count.acceptor) || products.some((sp) => sp.coefficient % k !== 0)) return refuse("transfer-too-large", `${spec.equation}: even one formula unit needs ${count.donor} giving atoms and ${count.acceptor} taking atoms (at most 3 of each).`, { id: spec.id });
+	const electrons = count.donor * each.donor;
+	const n = (c) => c === 1 ? "" : String(c);
+	const unit = k > 1;
+	const drawn = unit ? `${n(count.donor)}${up.element} + ${n(count.acceptor)}${down.element} → ${products.map((sp) => `${n(sp.coefficient / k)}${formulaDisplayText(sp.formula)}`).join(" + ")}` : display;
+	const plan = (c, atoms, per) => {
+		const Z = elementBySymbol(c.element).Z;
+		return {
+			symbol: c.element,
+			Z,
+			species: c.species,
+			count: atoms,
+			each: per,
+			outer: shellCounts(Z, 0).at(-1),
+			from: c.from,
+			to: c.to
+		};
+	};
+	const donor = plan(up, count.donor, each.donor);
+	const acceptor = plan(down, count.acceptor, each.acceptor);
+	return {
+		...base,
+		drawn,
+		unitNote: unit ? `One formula unit: the picture moves ${electrons} electrons; the whole equation moves ${reading.electronsPerFormula}.` : "",
+		redox: true,
+		donor,
+		acceptor,
+		electrons,
+		truth: {
+			[donor.species]: "reductant",
+			[acceptor.species]: "oxidant"
+		},
+		halves: {
+			oxidation: `${donor.symbol} → ${ionText(donor.symbol, donor.each)} + ${electronsText(donor.each)}`,
+			reduction: `${acceptor.symbol} + ${electronsText(acceptor.each)} → ${ionText(acceptor.symbol, -acceptor.each)}`
+		}
+	};
+}
+function drillItem(spec) {
+	let elements;
+	let charge;
+	try {
+		const species = parseSpecies(spec.species);
+		elements = species.elements;
+		charge = species.charge;
+	} catch (error) {
+		return refuse("bad-species", `"${spec.species}" is not a species: ${error.message}`, { id: spec.id });
+	}
+	const given = spec.given ?? {};
+	const answer = oxidationNumberOf(spec.species, spec.element, given);
+	if (isRefusal(answer)) return answer;
+	if (answer < GUESS_RANGE[0] || answer > GUESS_RANGE[1]) return refuse("answer-out-of-range", `${spec.element} in ${spec.species} is ${signed(answer)}, outside the dial's ${signed(GUESS_RANGE[0])} to ${signed(GUESS_RANGE[1])}.`, { id: spec.id });
+	const atoms = [];
+	for (const [symbol, count] of Object.entries(elements)) {
+		if (symbol === spec.element) {
+			atoms.push({
+				symbol,
+				count,
+				on: null,
+				given: false
+			});
+			continue;
+		}
+		const on = oxidationNumberOf(spec.species, symbol, given);
+		if (isRefusal(on)) return on;
+		atoms.push({
+			symbol,
+			count,
+			on,
+			given: symbol in given
+		});
+	}
+	const known = atoms.filter((a) => a.on !== null);
+	const knownSum = known.reduce((sum, a) => sum + a.on * a.count, 0);
+	const unknownCount = elements[spec.element];
+	const terms = atoms.map((a) => a.on === null ? `x×${a.count}` : `(${signed(a.on)})×${a.count}`);
+	return {
+		id: spec.id,
+		species: spec.species,
+		display: formulaDisplayText(spec.species),
+		element: spec.element,
+		given,
+		answer,
+		charge,
+		atoms,
+		knownSum,
+		unknownCount,
+		working: `${terms.join(" + ")} = ${charge === 0 ? "0" : signed(charge)}`,
+		source: spec.source
+	};
+}
+function sortCard(spec) {
+	const reading = classifyRedox(spec.equation);
+	if (isRefusal(reading)) return reading;
+	if (reading.redox && reading.types.length === 0) return refuse("card-has-no-type", `${spec.equation} is redox but fits none of the four types.`, { id: spec.id });
+	if (!reading.redox && !spec.kind) return refuse("card-needs-kind", `${spec.equation} is not redox: name its kind (neutralisation or precipitation).`, { id: spec.id });
+	if (reading.redox && spec.kind) return refuse("card-kind-is-redox", `${spec.equation} is redox, so it cannot be a ${spec.kind}.`, { id: spec.id });
+	return {
+		id: spec.id,
+		equation: spec.equation,
+		display: displayEquation(spec.equation),
+		redox: reading.redox,
+		accepted: reading.redox ? reading.types : ["non-redox"],
+		strip: stripOf(reading),
+		reactants: reading.species.filter((sp) => sp.side === "reactant").length,
+		products: reading.species.filter((sp) => sp.side === "product").length,
+		electrons: reading.electronsPerFormula,
+		...spec.kind ? { kind: spec.kind } : {},
+		...spec.bookNote ? { bookNote: spec.bookNote } : {},
+		...reading.reductant ? { reductant: reading.reductant } : {},
+		...reading.oxidant ? { oxidant: reading.oxidant } : {}
+	};
+}
+const BAY_NAME = {
+	addition: "addition",
+	decomposition: "decomposition",
+	displacement: "displacement",
+	combustion: "combustion",
+	"non-redox": "non-redox"
+};
+const bayName = (bay) => BAY_NAME[bay];
+const BAY_RULE = {
+	addition: "Addition: two or more substances join into one product.",
+	decomposition: "Decomposition: one substance breaks into two or more.",
+	displacement: "Displacement: a free element pushes another element out of a compound.",
+	combustion: "Combustion: oxygen reacts and its oxidation number falls from 0 to -2.",
+	"non-redox": "Non-redox: no atom changes its oxidation number, so no electron moves."
+};
+const bayRule = (bay) => BAY_RULE[bay];
+/** Why a bay is wrong for a card, from the strip and the species counts. Never just "wrong". */
+function explainBay(card, bay) {
+	const changed = card.strip.filter((r) => r.changed);
+	const example = changed[0] ? `${changed[0].element} goes ${changed[0].before} → ${changed[0].after}` : "";
+	if (bay === "non-redox") return `The strip is not flat: ${example}. An atom whose number changes has gained or lost electrons, so this is redox.`;
+	if (!card.redox) return `Every number on the strip stays the same, so no electron moves. A reaction with a flat strip is non-redox (here a ${card.kind}), not ${bayName(bay)}.`;
+	const sizes = `${card.reactants} reactant${card.reactants === 1 ? "" : "s"} and ${card.products} product${card.products === 1 ? "" : "s"}`;
+	switch (bay) {
+		case "addition": return `This card has ${sizes}; addition ends with one product. ${bayRule(card.accepted[0])}`;
+		case "decomposition": return `This card has ${sizes}; decomposition starts from one substance. ${bayRule(card.accepted[0])}`;
+		case "displacement": return `Displacement needs a free element on each side with a compound beside it. ${bayRule(card.accepted[0])}`;
+		case "combustion": return `Oxygen does not go from 0 to -2 here, so it is not combustion. ${bayRule(card.accepted[0])}`;
+	}
+}
+/** Why a bay is right: the rule plus the evidence on the strip. */
+function whyBay(card, bay) {
+	if (bay === "non-redox") return `The strip is flat: no number changes, so no electron moves. This is a ${card.kind}. ${bayRule("non-redox")}`;
+	const changed = card.strip.filter((r) => r.changed);
+	const moves = changed.map((r) => `${r.element} ${r.before} → ${r.after}`).join(", ");
+	return `${moves}: ${card.electrons} electron${card.electrons === 1 ? "" : "s"} move. ${bayRule(bay)}`;
+}
+const BAY_IDS = BAYS;
+const caseOf = (s, id) => s.transfers.find((c) => c.id === id);
+const toggle = (list, id, on) => on ? list.includes(id) ? list : [...list, id] : list.filter((x) => x !== id);
+const rolesRight = (c, roles) => Object.entries(c.truth).every(([species, role]) => roles[species] === role);
+/** Keep the lists of finished cases in step with the current case after any change. */
+function sync(s, st) {
+	const c = caseOf(s, st.caseId);
+	const moved = c.redox ? st.moved === c.electrons : st.refusals > 0;
+	const named = !c.redox || !s.showRoles || moved && rolesRight(c, st.roles);
+	return {
+		...st,
+		movedCases: toggle(st.movedCases, c.id, moved),
+		roleCases: toggle(st.roleCases, c.id, moved && named)
+	};
+}
+const freshCase = (st, caseId) => ({
+	...st,
+	caseId,
+	moved: 0,
+	progress: 0,
+	dragged: false,
+	refusals: 0,
+	roles: {},
+	lastRole: ""
+});
+function commitMove(s, st) {
+	const c = caseOf(s, st.caseId);
+	if (!c.redox) return sync(s, {
+		...st,
+		progress: 0,
+		dragged: false,
+		refusals: st.refusals + 1
+	});
+	if (st.moved >= c.electrons) return {
+		...st,
+		progress: 0,
+		dragged: false
+	};
+	return sync(s, {
+		...st,
+		progress: 0,
+		dragged: false,
+		moved: st.moved + 1
+	});
+}
+const itemOf = (s, st) => s.drill[st.itemIndex];
+const cardOf = (s, st) => s.cards[st.cardIndex];
+/** The sum of every atom's oxidation number with the dial's value in for the unknown one. */
+const sumAt = (item, guess) => item.knownSum + item.unknownCount * guess;
+const isRight = (card, bay) => card.accepted.includes(bay);
+const drillEntry = z.union([z.string().describe("the id of a built-in item, such as \"cuso4-s\""), z.object({
+	species: z.string().min(1).describe("the species, such as \"CuSO4\" or \"MnO4-\""),
+	element: z.string().min(1).describe("the element whose number is asked"),
+	given: z.record(z.string(), z.number().int()).optional().describe("numbers the question states")
+})]);
+const redoxTransferModel = defineLabModel({
+	id: "redox-transfer",
+	params: z.object({
+		mode: z.enum([
+			"demo",
+			"drill",
+			"sort"
+		]).default("demo").describe("demo: carry electrons; drill: find oxidation numbers; sort: place reactions in bays"),
+		cases: z.array(z.string()).min(1).max(4).default([...DEFAULT_TRANSFER]).describe("demo: case ids in order. The first is the worked example, the rest are changed cases"),
+		drill: z.array(drillEntry).min(1).max(10).default([...DEFAULT_DRILL]).describe("drill: item ids, or { species, element, given } for an item of your own"),
+		cards: z.array(z.string()).min(2).max(12).default([...DEFAULT_CARDS]).describe("sort: reaction card ids in order. The last card is the unseen one"),
+		bays: z.array(z.enum(BAY_IDS)).min(2).max(5).default([...BAYS]).describe("sort: which bays are on the tray"),
+		showRoles: z.boolean().default(true).describe("demo: ask which species is the reductant and which the oxidant"),
+		showHalfEquations: z.boolean().default(true).describe("demo: show the two half-equations once the electrons have moved")
+	}),
+	resolve(p) {
+		const base = {
+			mode: p.mode,
+			bays: unique(p.bays),
+			showRoles: p.showRoles,
+			showHalfEquations: p.showHalfEquations
+		};
+		if (p.mode === "demo") {
+			if (unique(p.cases).length !== p.cases.length) return refuse("duplicate-case", "Each case may appear once.");
+			const transfers = [];
+			for (const id of p.cases) {
+				const spec = TRANSFER_CASES.find((c) => c.id === id);
+				if (!spec) return refuse("unknown-case", `No case "${id}". Known: ${TRANSFER_CASES.map((c) => c.id).join(", ")}.`);
+				const made = transferCase(spec);
+				if (isRefusal(made)) return made;
+				transfers.push(made);
+			}
+			return {
+				...base,
+				transfers,
+				drill: [],
+				cards: []
+			};
+		}
+		if (p.mode === "drill") {
+			const drill = [];
+			for (const [i, entry] of p.drill.entries()) {
+				const spec = typeof entry === "string" ? DRILL_ITEMS.find((d) => d.id === entry) : {
+					id: `custom-${i + 1}`,
+					species: entry.species,
+					element: entry.element,
+					...entry.given ? { given: entry.given } : {},
+					source: "your item"
+				};
+				if (!spec) return refuse("unknown-item", `No drill item "${String(entry)}". Known: ${DRILL_ITEMS.map((d) => d.id).join(", ")}.`);
+				const made = drillItem(spec);
+				if (isRefusal(made)) return made;
+				drill.push(made);
+			}
+			if (unique(drill.map((d) => d.id)).length !== drill.length) return refuse("duplicate-item", "Each drill item may appear once.");
+			return {
+				...base,
+				transfers: [],
+				drill,
+				cards: []
+			};
+		}
+		if (unique(p.cards).length !== p.cards.length) return refuse("duplicate-card", "Each card may appear once.");
+		const cards = [];
+		for (const id of p.cards) {
+			const spec = SORT_CARDS.find((c) => c.id === id);
+			if (!spec) return refuse("unknown-card", `No card "${id}". Known: ${SORT_CARDS.map((c) => c.id).join(", ")}.`);
+			const made = sortCard(spec);
+			if (isRefusal(made)) return made;
+			if (!made.accepted.some((bay) => base.bays.includes(bay))) return refuse("bay-missing", `Card "${id}" belongs in ${made.accepted.join(" or ")}, which is not on the tray.`);
+			cards.push(made);
+		}
+		return {
+			...base,
+			transfers: [],
+			drill: [],
+			cards
+		};
+	},
+	initial: (s) => ({
+		caseId: s.transfers[0]?.id ?? "",
+		moved: 0,
+		progress: 0,
+		dragged: false,
+		refusals: 0,
+		roles: {},
+		lastRole: "",
+		movedCases: [],
+		roleCases: [],
+		itemIndex: 0,
+		guesses: {},
+		solved: [],
+		cardIndex: 0,
+		placed: {},
+		wrong: {},
+		lastBay: ""
+	}),
+	controls: (c) => ({
+		case: c.choice({
+			label: "Case",
+			unset: true,
+			when: (s) => s.mode === "demo" && s.transfers.length > 1,
+			options: (s) => s.transfers.map((t) => ({
+				value: t.id,
+				label: t.name
+			})),
+			get: (st) => st.caseId,
+			set: (st, id, s) => sync(s, freshCase(st, id))
+		}),
+		electron: c.number({
+			label: "Electron",
+			when: (s, st) => {
+				if (s.mode !== "demo") return false;
+				const t = s.transfers.find((c) => c.id === st.caseId);
+				return !t ? false : t.redox ? st.moved < t.electrons : st.refusals === 0;
+			},
+			step: .25,
+			range: () => [0, 1],
+			get: (st) => st.progress,
+			set: (st, v) => ({
+				...st,
+				progress: v,
+				dragged: st.dragged || v > 0
+			}),
+			format: (v) => v >= .65 ? "over the acceptor" : v > 0 ? "on its way" : "on the donor"
+		}),
+		move: c.action({
+			label: "Move the electron",
+			when: (s, st) => {
+				if (s.mode !== "demo") return false;
+				const t = s.transfers.find((c) => c.id === st.caseId);
+				return !t ? false : t.redox ? st.moved < t.electrons : st.refusals === 0;
+			},
+			run: (s, st) => commitMove(s, st)
+		}),
+		undo: c.action({
+			label: "Undo",
+			when: (s, st) => s.mode === "demo" && Boolean(s.transfers.find((c) => c.id === st.caseId)?.redox),
+			enabled: (_s, st) => st.moved > 0,
+			run: (s, st) => {
+				const roles = {};
+				return sync(s, {
+					...st,
+					moved: st.moved - 1,
+					progress: 0,
+					dragged: false,
+					roles,
+					lastRole: ""
+				});
+			}
+		}),
+		role: c.choice({
+			label: "Role",
+			unset: true,
+			when: (s, st) => {
+				if (s.mode !== "demo" || !s.showRoles) return false;
+				const t = s.transfers.find((c) => c.id === st.caseId);
+				return Boolean(t?.redox) && st.moved === t.electrons;
+			},
+			options: (s, st) => {
+				const t = s.transfers.find((c) => c.id === st.caseId);
+				return Object.keys(t?.truth ?? {}).flatMap((species) => ["reductant", "oxidant"].map((role) => ({
+					value: `${species}:${role}`,
+					label: `${formulaDisplayText(species)} is the ${role}`
+				})));
+			},
+			get: (st) => st.lastRole,
+			set: (st, value, s) => {
+				const [species = "", role = ""] = value.split(":");
+				if (role !== "reductant" && role !== "oxidant") return st;
+				return sync(s, {
+					...st,
+					roles: {
+						...st.roles,
+						[species]: role
+					},
+					lastRole: value
+				});
+			}
+		}),
+		guess: c.number({
+			label: "Oxidation number x",
+			symbol: "x",
+			when: (s) => s.mode === "drill",
+			step: 1,
+			bigStep: 4,
+			range: () => GUESS_RANGE,
+			get: (st, s) => s.drill[st.itemIndex] ? st.guesses[itemOf(s, st).id] ?? 0 : 0,
+			set: (st, v, s) => {
+				const item = itemOf(s, st);
+				if (st.solved.includes(item.id)) return st;
+				return {
+					...st,
+					guesses: {
+						...st.guesses,
+						[item.id]: v
+					},
+					solved: toggle(st.solved, item.id, v === item.answer)
+				};
+			},
+			format: (v) => signed(v)
+		}),
+		bay: c.choice({
+			label: "Bay",
+			unset: true,
+			when: (s) => s.mode === "sort",
+			options: (s) => s.bays.map((b) => ({
+				value: b,
+				label: bayName(b)
+			})),
+			get: (st, s) => s.cards[st.cardIndex] ? st.placed[cardOf(s, st).id] ?? st.lastBay : "",
+			set: (st, bay, s) => {
+				const card = cardOf(s, st);
+				if (st.placed[card.id]) return st;
+				const chosen = bay;
+				if (isRight(card, chosen)) return {
+					...st,
+					placed: {
+						...st.placed,
+						[card.id]: chosen
+					},
+					lastBay: chosen
+				};
+				return {
+					...st,
+					wrong: {
+						...st.wrong,
+						[card.id]: [...st.wrong[card.id] ?? [], chosen]
+					},
+					lastBay: chosen
+				};
+			}
+		}),
+		next: c.action({
+			label: (s) => s.mode === "drill" ? "Next atom" : "Next card",
+			when: (s) => s.mode !== "demo",
+			enabled: (s, st) => s.mode === "drill" ? s.drill.length > 0 && st.solved.includes(itemOf(s, st).id) && st.itemIndex < s.drill.length - 1 : s.cards.length > 0 && Boolean(st.placed[cardOf(s, st).id]) && st.cardIndex < s.cards.length - 1,
+			run: (s, st) => s.mode === "drill" ? {
+				...st,
+				itemIndex: st.itemIndex + 1
+			} : {
+				...st,
+				cardIndex: st.cardIndex + 1,
+				lastBay: ""
+			}
+		})
+	}),
+	actions: {
+		/**
+		* Let go of the bead. A tap (the bead never left its place) or a drop past `DROP_AT` moves the
+		* electron; a drag let go short of the other atom springs back.
+		*/
+		release: (s, st) => !st.dragged || st.progress >= .65 ? commitMove(s, st) : {
+			...st,
+			progress: 0,
+			dragged: false
+		},
+		"show-case": (s, st, id) => typeof id === "string" && s.transfers.some((t) => t.id === id) ? sync(s, freshCase(st, id)) : st,
+		"show-card": (s, st, id) => {
+			const index = s.cards.findIndex((c) => c.id === id);
+			return index < 0 ? st : {
+				...st,
+				cardIndex: index,
+				lastBay: ""
+			};
+		}
+	},
+	read(s, st) {
+		const first = s.transfers[0]?.id;
+		const lastCard = s.cards.length - 1;
+		const demo = (() => {
+			if (s.mode !== "demo") return null;
+			const c = caseOf(s, st.caseId);
+			const m = c.redox ? st.moved : 0;
+			const atoms = (plan, side) => plan ? Array.from({ length: plan.count }, (_, i) => {
+				const done = Math.min(plan.each, Math.max(0, m - i * plan.each));
+				const charge = side === "donor" ? done : -done;
+				return {
+					key: `${side}-${i}`,
+					symbol: plan.symbol,
+					charge,
+					onFrom: plan.from,
+					onNow: charge,
+					onTo: plan.to,
+					shells: shellCounts(plan.Z, charge).join(","),
+					outer: plan.outer,
+					moved: done,
+					each: plan.each
+				};
+			}) : [];
+			const donors = atoms(c.donor, "donor");
+			const acceptors = atoms(c.acceptor, "acceptor");
+			const complete = c.redox ? st.moved === c.electrons : st.refusals > 0;
+			const next = c.redox && c.donor && c.acceptor && st.moved < c.electrons ? {
+				donor: Math.floor(st.moved / c.donor.each),
+				acceptor: Math.floor(st.moved / c.acceptor.each)
+			} : null;
+			const roles = Object.entries(c.truth).map(([species, truth]) => {
+				const assigned = st.roles[species] ?? null;
+				return {
+					species,
+					label: formulaDisplayText(species),
+					truth,
+					assigned,
+					ok: assigned === truth
+				};
+			});
+			const rolesDone = !c.redox || !s.showRoles ? complete : complete && roles.every((r) => r.ok);
+			const wrongRoles = roles.filter((r) => r.assigned && !r.ok);
+			const donorName = c.donor ? formulaDisplayText(c.donor.species) : "";
+			const acceptorName = c.acceptor ? formulaDisplayText(c.acceptor.species) : "";
+			const roleFeedback = wrongRoles.length ? `${wrongRoles.map((r) => `${r.label} ${r.truth === "reductant" ? "gave" : "took"} electrons`).join(" and ")}, so ${wrongRoles.length === 1 ? "it is" : "they are"} the ${wrongRoles[0].truth}. The reductant gives electrons and is oxidised; the oxidant takes them and is reduced.` : "";
+			const gap = c.redox && !complete ? st.moved === 0 ? `No electron has moved yet. ${c.donor.count * c.donor.each} must pass from ${c.donor.symbol} to ${c.acceptor.symbol}.` : `${st.moved} of ${c.electrons} electrons have moved, so ${c.donor.symbol} is not yet fully ${ionText(c.donor.symbol, c.donor.each)} and ${c.acceptor.symbol} is not yet ${ionText(c.acceptor.symbol, -c.acceptor.each)}. ${c.electrons - st.moved} more must move.` : "";
+			const refusalWhy = !c.redox && st.refusals > 0 ? `No electron can move: ${c.strip.map((r) => `${r.element} stays ${r.before}`).join(", ")}. With no number changing there is nothing to give and nothing to take. ${c.id === "neutralisation" ? "This is a neutralisation: H⁺ + OH⁻ → H₂O." : ""}`.trim() : "";
+			const insight = c.redox ? `Electrons lost = electrons gained = ${c.electrons}. ${donorName} is oxidised (number up, ${signed(c.donor.from)} → ${signed(c.donor.to)}); ${acceptorName} is reduced (number down, ${signed(c.acceptor.from)} → ${signed(c.acceptor.to)}). Neither half can happen alone.` : "";
+			return {
+				case: c,
+				complete,
+				electrons: c.electrons,
+				moved: st.moved,
+				progress: st.progress,
+				donors,
+				acceptors,
+				next,
+				roles,
+				rolesDone,
+				roleFeedback,
+				gap,
+				refusalWhy,
+				insight,
+				halves: c.halves && s.showHalfEquations && complete ? c.halves : null,
+				/** The worked example gets a dashed place for the electron; changed cases do not. */
+				guided: st.caseId === first,
+				refusals: st.refusals,
+				simultaneous: c.redox && complete
+			};
+		})();
+		const drill = (() => {
+			if (s.mode !== "drill") return null;
+			const item = itemOf(s, st);
+			const touched = item.id in st.guesses;
+			const guess = st.guesses[item.id] ?? 0;
+			const sum = sumAt(item, guess);
+			const off = sum - item.charge;
+			const solved = st.solved.includes(item.id);
+			const off0 = off === 0;
+			return {
+				item,
+				index: st.itemIndex,
+				total: s.drill.length,
+				guess,
+				touched,
+				sum,
+				target: item.charge,
+				off,
+				balanced: off0,
+				solved,
+				solvedCount: st.solved.length,
+				allSolved: s.drill.every((d) => st.solved.includes(d.id)),
+				/** Degrees, positive = right pan down. The sum is on the left pan, the charge on the right. */
+				tilt: Math.max(-16, Math.min(16, (item.charge - sum) * 4)),
+				hint: touched && !solved ? off > 0 ? `The sum reads ${signed(off)} too high: turn x down by ${Math.ceil(off / item.unknownCount)}.` : `The sum reads ${signed(off)} too low: turn x up by ${Math.ceil(-off / item.unknownCount)}.` : "",
+				valencyNote: "Oxidation number is not valency: it carries a sign, can be zero, and changes with the compound (book p150)."
+			};
+		})();
+		const sort = (() => {
+			if (s.mode !== "sort") return null;
+			const card = cardOf(s, st);
+			const placedBay = st.placed[card.id] ?? null;
+			const wrong = st.wrong[card.id] ?? [];
+			const wrongNow = !placedBay && st.lastBay ? st.lastBay : null;
+			const placedCount = s.cards.filter((c) => st.placed[c.id]).length;
+			const lastWrong = wrongNow ? explainBay(card, wrongNow) : "";
+			return {
+				card,
+				index: st.cardIndex,
+				total: s.cards.length,
+				placedBay,
+				wrong,
+				wrongNow,
+				explanation: wrongNow ? lastWrong : placedBay ? whyBay(card, placedBay) : "",
+				placedCount,
+				isUnseen: st.cardIndex === lastCard,
+				done: s.cards.every((c) => st.placed[c.id]),
+				bookNote: placedBay ? card.bookNote ?? "" : "",
+				/** Cards already in a bay, by bay, for the stacks on the tray. */
+				stacks: s.bays.map((bay) => ({
+					bay,
+					cards: s.cards.filter((c) => st.placed[c.id] === bay).map((c) => c.id)
+				}))
+			};
+		})();
+		const rest = s.transfers.slice(1);
+		const everyCaseDone = (ids) => ids.every((id) => st.movedCases.includes(id) && st.roleCases.includes(id));
+		const goalFlags = {
+			transfer: s.mode !== "demo" || first !== undefined && st.movedCases.includes(first),
+			roles: s.mode !== "demo" || first !== undefined && st.roleCases.includes(first),
+			changed: s.mode === "demo" ? everyCaseDone(rest.map((c) => c.id)) : s.mode === "sort" ? Boolean(st.placed[s.cards[lastCard].id]) : true,
+			number: s.mode !== "drill" || s.drill.every((d) => st.solved.includes(d.id)),
+			sort: s.mode !== "sort" || s.cards.slice(0, lastCard).every((c) => st.placed[c.id])
+		};
+		return {
+			mode: s.mode,
+			demo,
+			drill,
+			sort,
+			goalFlags
+		};
+	},
+	goals: {
+		transfer: (r) => r.goalFlags.transfer,
+		roles: (r) => r.goalFlags.roles,
+		changed: (r) => r.goalFlags.changed,
+		number: (r) => r.goalFlags.number,
+		sort: (r) => r.goalFlags.sort,
+		/** One case finished (moved and named), or every case when no `case` argument is given. */
+		caseDone: (r, st, s, args) => {
+			if (s.mode !== "demo") return true;
+			const ids = args?.case !== undefined ? [String(args.case)] : s.transfers.map((c) => c.id);
+			return ids.every((id) => st.movedCases.includes(id) && st.roleCases.includes(id));
+		}
+	},
+	witness: (s) => {
+		const start = {
+			caseId: s.transfers[0]?.id ?? "",
+			moved: 0,
+			progress: 0,
+			dragged: false,
+			refusals: 0,
+			roles: {},
+			lastRole: "",
+			movedCases: [],
+			roleCases: [],
+			itemIndex: 0,
+			guesses: {},
+			solved: [],
+			cardIndex: 0,
+			placed: {},
+			wrong: {},
+			lastBay: ""
+		};
+		if (s.mode === "drill") return {
+			...start,
+			itemIndex: s.drill.length - 1,
+			guesses: Object.fromEntries(s.drill.map((d) => [d.id, d.answer])),
+			solved: s.drill.map((d) => d.id)
+		};
+		if (s.mode === "sort") return {
+			...start,
+			cardIndex: s.cards.length - 1,
+			placed: Object.fromEntries(s.cards.map((c) => [c.id, c.accepted.find((b) => s.bays.includes(b))]))
+		};
+		const last = s.transfers.at(-1);
+		return {
+			...start,
+			caseId: last.id,
+			moved: last.electrons,
+			refusals: last.redox ? 0 : 1,
+			roles: { ...last.truth },
+			movedCases: s.transfers.map((t) => t.id),
+			roleCases: s.transfers.map((t) => t.id)
+		};
+	},
+	describe(s, _st, r) {
+		if (r.demo) {
+			const d = r.demo;
+			const c = d.case;
+			if (!c.redox) return `${c.display}. ${d.refusals > 0 ? d.refusalWhy : "No oxidation number changes. Try to move an electron."}`;
+			if (!d.complete) return `${c.display}. ${d.moved} of ${d.electrons} electrons moved. ${d.gap}`;
+			const roleLine = d.rolesDone ? d.insight : s.showRoles ? "Name the reductant and the oxidant." : "";
+			return `${c.display}. All ${d.electrons} electrons moved. ${roleLine} ${d.halves ? `${d.halves.oxidation}; ${d.halves.reduction}.` : ""}`.trim();
+		}
+		if (r.drill) {
+			const d = r.drill;
+			const it = d.item;
+			return `Item ${d.index + 1} of ${d.total}: the oxidation number of ${it.element} in ${it.display}${Object.keys(it.given).length ? `, given ${Object.entries(it.given).map(([e, n]) => `${e} ${signed(n)}`).join(", ")}` : ""}. x is ${signed(d.guess)}; the numbers add to ${signed(d.sum)} and the charge is ${signed(d.target)}. ${d.solved ? `Balanced: ${it.working}.` : d.hint}`.trim();
+		}
+		const sr = r.sort;
+		return `Card ${sr.index + 1} of ${sr.total}: ${sr.card.display}. ${sr.placedBay ? `In ${bayName(sr.placedBay)}. ${sr.explanation}` : sr.wrongNow ? `Not ${bayName(sr.wrongNow)}. ${sr.explanation}` : "Read the strip, then choose a bay."}`;
+	}
+});
+
+//#endregion
+export { DROP_AT, GUESS_RANGE, bayName, bayRule, displayEquation, explainBay, redoxTransferModel, signed, sumAt, whyBay };