@classytic/stage 0.3.0 → 0.4.0

package/dist/chem/polymer.mjs

@@ -0,0 +1,179 @@
+import { ATOMIC_MASS, molecularFormula, relativeMass } from "./molecule.mjs";
+import { functionalGroups } from "./functional-groups.mjs";
+
+//#region src/chem/polymer.ts
+/**
+* polymer, the repeat unit worked out from the monomer rather than drawn beside it.
+*
+* WHAT THIS IS FOR. Polymerisation is taught as two pictures to copy: an alkene with its double bond
+* opened, and two monomers with a water molecule falling out between them. Copied, they are
+* indistinguishable, and a learner who has copied both still cannot say which one a new monomer will
+* do. The question an exam actually asks is "draw the repeat unit", and that is a transformation of
+* a structure, so it can be performed.
+*
+* ## Addition: the double bond becomes the link
+*
+* An alkene's C=C opens. One bond stays holding the two carbons together, and the other becomes the
+* two bonds that join this unit to the next. So the repeat unit has the SAME molecular formula as
+* the monomer, which is the fact that tells addition from condensation without looking at anything
+* else.
+*
+* ## Condensation: two groups meet and lose a small molecule
+*
+* A carboxylic acid meets an alcohol and loses water, leaving an ester link. It meets an amine and
+* loses water, leaving an amide link, which is also the peptide link in a protein. The repeat unit
+* is therefore LIGHTER than the monomers by the mass of what left, and each monomer needs TWO
+* reactive groups or the chain stops after one join.
+*
+* That last point is the one usually left out, and it is what makes the difference between ethanoic
+* acid, which cannot polymerise, and hexanedioic acid, which can.
+*
+* Pure: no React, no pixels.
+*/
+/**
+* Open the double bond of an alkene to give the addition repeat unit.
+*
+* Refuses a monomer with no C=C, because "it must be addition" is a guess a learner makes and a
+* kernel should not. The formula is unchanged by construction, and the test asserts it.
+*/
+function addition(monomer) {
+	const alkene = functionalGroups(monomer).find((g) => g.kind === "alkene");
+	if (!alkene) throw new Error(`${molecularFormula(monomer)} has no C=C, so it cannot polymerise by addition. Addition polymerisation needs a double bond to open.`);
+	const [a, b] = alkene.atoms;
+	const bonds = monomer.bonds.map((bond) => bond.a === a && bond.b === b || bond.a === b && bond.b === a ? {
+		...bond,
+		order: 1
+	} : bond);
+	const structure = {
+		atoms: monomer.atoms.map((atom) => atom.id === a || atom.id === b ? {
+			...atom,
+			openValence: (atom.openValence ?? 0) + 1
+		} : atom),
+		bonds
+	};
+	return {
+		kind: "addition",
+		link: "carbon-carbon",
+		structure,
+		linkAtoms: [a, b],
+		formula: molecularFormula(structure),
+		mass: relativeMass(structure),
+		reason: "The C=C opens. One of its two bonds holds the carbons together and the other becomes the bonds to the units on either side, so nothing is lost and the repeat unit has the same formula as the monomer."
+	};
+}
+/** Groups that can form a link, and what they form it with. */
+const REACTIVE = [
+	"carboxylic-acid",
+	"alcohol",
+	"amine"
+];
+const reactiveGroups = (s) => functionalGroups(s).filter((g) => REACTIVE.includes(g.kind));
+/**
+* Can this monomer sustain a chain?
+*
+* Two reactive groups, or the chain stops after one join. Ethanoic acid has one and is therefore a
+* dead end; hexanedioic acid has two and is not. This is the check most treatments leave out and
+* the reason a learner cannot predict whether a new monomer will polymerise.
+*/
+const canSustainChain = (monomer) => reactiveGroups(monomer).length >= 2;
+const WATER = {
+	formula: "H2O",
+	mass: ATOMIC_MASS.H * 2 + ATOMIC_MASS.O
+};
+/**
+* Join two monomers and eliminate water, giving the condensation repeat unit.
+*
+* The pairing is decided by the groups that are actually present, not by an argument the caller
+* passes: an acid with an alcohol gives an ester link and an acid with an amine gives an amide link,
+* and those are the only two the syllabus needs. A pair that cannot make either is refused with the
+* reason, because "nothing happened" is not a useful answer to a learner.
+*/
+function condensation(first, second) {
+	const a = reactiveGroups(first);
+	const b = reactiveGroups(second);
+	const kindsA = new Set(a.map((g) => g.kind));
+	const kindsB = new Set(b.map((g) => g.kind));
+	const pairing = [[
+		"carboxylic-acid",
+		"alcohol",
+		"ester"
+	], [
+		"carboxylic-acid",
+		"amine",
+		"amide"
+	]].find(([x, y]) => kindsA.has(x) && kindsB.has(y) || kindsA.has(y) && kindsB.has(x));
+	if (!pairing) throw new Error(`${molecularFormula(first)} and ${molecularFormula(second)} have no pair of groups that can condense. An ester link needs an acid and an alcohol; an amide link needs an acid and an amine.`);
+	const [, , link] = pairing;
+	if (!canSustainChain(first) || !canSustainChain(second)) throw new Error(`A condensation polymer needs TWO reactive groups on each monomer. ${canSustainChain(first) ? molecularFormula(second) : molecularFormula(first)} has only one, so the chain would stop after a single join.`);
+	const acids = a.filter((g) => g.kind === "carboxylic-acid");
+	const partners = b.filter((g) => g.kind === (link === "ester" ? "alcohol" : "amine"));
+	if (acids.length < 2 || partners.length < 2) throw new Error("A repeat unit needs two acid groups and two partner groups, one pair to link and one pair to continue the chain.");
+	/** The atom that carries the new bond: the oxygen of an alcohol, or the nitrogen of an amine. */
+	const partnerAtom = (group) => group.kind === "alcohol" ? group.atoms[1] : group.atoms[0];
+	const shift = first.atoms.length;
+	const dropped = new Set([acids[0].atoms[2], acids[1].atoms[2]]);
+	const opened = new Map([[acids[1].atoms[0], 1], [partnerAtom(partners[1]) + shift, 1]]);
+	const kept = [...first.atoms.filter((atom) => !dropped.has(atom.id)), ...second.atoms.map((atom) => ({
+		...atom,
+		id: atom.id + shift
+	}))];
+	const renumber = new Map(kept.map((atom, i) => [atom.id, i]));
+	const merged = {
+		atoms: kept.map((atom, i) => ({
+			...atom,
+			id: i,
+			...opened.has(atom.id) ? { openValence: (atom.openValence ?? 0) + opened.get(atom.id) } : {}
+		})),
+		bonds: [
+			...first.bonds.filter((bond) => !dropped.has(bond.a) && !dropped.has(bond.b)),
+			...second.bonds.map((bond) => ({
+				...bond,
+				a: bond.a + shift,
+				b: bond.b + shift
+			})),
+			{
+				a: acids[0].atoms[0],
+				b: partnerAtom(partners[0]) + shift,
+				order: 1,
+				aromatic: false
+			}
+		].map((bond) => ({
+			...bond,
+			a: renumber.get(bond.a),
+			b: renumber.get(bond.b)
+		}))
+	};
+	const mass = relativeMass(merged);
+	const formula = molecularFormula(merged);
+	return {
+		kind: "condensation",
+		link,
+		structure: merged,
+		linkAtoms: [renumber.get(acids[1].atoms[0]), renumber.get(partnerAtom(partners[1]) + shift)],
+		formula,
+		mass,
+		lost: {
+			formula: WATER.formula,
+			mass: Math.round(WATER.mass * 10) / 10
+		},
+		reason: link === "ester" ? "The O-H of the acid and the O-H of the alcohol meet, water is eliminated and an ester link is left. Each monomer needs two groups, so the chain can continue at both ends." : "The O-H of the acid and an N-H of the amine meet, water is eliminated and an amide link is left. That is the same link that joins amino acids into a protein, where it is called a peptide link."
+	};
+}
+/**
+* The mass of a chain of `n` repeat units.
+*
+* For an addition polymer it is n times the monomer. For a condensation polymer the water has
+* already gone from the repeat unit, so the same multiplication works, and the difference between
+* the two shows up as a mass that is not a whole multiple of the monomers.
+*/
+const chainMass = (unit, n) => Math.round(unit.mass * n * 10) / 10;
+/**
+* How many repeat units a chain of this mass holds, to the nearest whole unit.
+*
+* The question an exam asks the other way round: a poly(ethene) sample with a relative molecular
+* mass of 28 000 contains 1000 repeat units, and that number is what "long chain" means.
+*/
+const unitsInChain = (unit, chainMr) => Math.round(chainMr / unit.mass);
+
+//#endregion
+export { addition, canSustainChain, chainMass, condensation, unitsInChain };

package/dist/chem/redox.d.mts

@@ -0,0 +1,138 @@
+//#region src/chem/redox.d.ts
+/**
+ * redox: oxidation numbers, half-equations, and the ionic equation they combine into.
+ *
+ * Three things the syllabus treats as three topics and which are one procedure applied at
+ * different scales. A learner who balances a half-equation in alkali by first balancing it in acid
+ * has understood that; one who memorises two procedures has not, which is why `medium` is an
+ * ARGUMENT here rather than a second function.
+ *
+ * ## Writing a species, and why the caret is required
+ *
+ * `'MnO4-'`, `'Cr2O7^2-'`, `'Fe^3+'`, `'H2O'`.
+ *
+ * A charge of one is a bare sign. **Any larger charge needs a caret**, because plain ASCII cannot
+ * distinguish the two readings of a digit before a sign and no syntactic rule can:
+ *
+ *   `MnO4-`  the 4 is a subscript, and the charge is −1
+ *   `Mn2+`   the 2 is the charge, and there is one manganese
+ *
+ * Both end in a letter, a digit and a sign. Only chemistry tells them apart, so an implementation
+ * that guesses is wrong roughly half the time and silently. Writing `Mn^2+` removes the question,
+ * and a digit before a bare sign is refused with a message saying so.
+ *
+ * `speciesToUnicode` renders `Mn^2+` as `Mn²⁺` for display, so the caret never reaches a learner.
+ *
+ * ## Oxidation numbers
+ *
+ * The rules are applied in order of how rarely they are broken: F is always −1, group 1 always +1,
+ * group 2 always +2, H is +1 except in a metal hydride, O is −2 except in a peroxide. Everything
+ * else is then fixed by the requirement that the oxidation numbers sum to the charge.
+ *
+ * That last line is the whole method, and it is why only ONE element may be unknown. A species with
+ * two unknowns is refused rather than guessed at, because the answer would not be determined.
+ *
+ * ## Balancing
+ *
+ * The five steps, in the order a mark scheme wants them:
+ *
+ *   1. balance the element being oxidised or reduced,
+ *   2. balance oxygen with H₂O,
+ *   3. balance hydrogen with H⁺,
+ *   4. balance the charge with electrons,
+ *   5. in ALKALI only, add OH⁻ to both sides to mop up the H⁺.
+ *
+ * Step 5 is what makes alkaline balancing one procedure rather than two: balance in acid, then
+ * neutralise. Every H⁺ meets an OH⁻ and becomes water, and the excess water cancels.
+ *
+ * Pure: no React, no pixels.
+ */
+type Medium = 'acid' | 'alkali';
+interface Species {
+  /** The formula as written, without its coefficient. */
+  readonly formula: string;
+  /** Element symbol to count. */
+  readonly elements: Readonly<Record<string, number>>;
+  /** Net charge. 0 for a neutral species. */
+  readonly charge: number;
+}
+interface Term {
+  readonly coeff: number;
+  readonly species: Species;
+}
+interface HalfEquation {
+  readonly left: readonly Term[];
+  readonly right: readonly Term[];
+  /** Electrons, on the side they appear. Always positive. */
+  readonly electrons: number;
+  /** 'left' for a reduction (electrons are gained), 'right' for an oxidation. */
+  readonly electronSide: 'left' | 'right';
+  readonly medium: Medium;
+}
+/** Parse `'Cr2O7^2-'` into its element counts and charge. See the docblock on the caret rule. */
+declare function parseSpecies(input: string): Species;
+/**
+ * Oxidation number of every element in a species.
+ *
+ * `peroxide` forces O to −1, for H₂O₂ and its salts. It is an argument rather than a detection
+ * rule, because H₂O₂ and H₂O differ only in a subscript and guessing from the formula would make
+ * the kernel wrong in exactly the case the syllabus asks about.
+ */
+declare function oxidationNumbers(input: string | Species, opts?: {
+  peroxide?: boolean;
+  hydride?: boolean;
+}): Record<string, number>;
+/**
+ * `'Cr2O7^2-'` → `'Cr₂O₇²⁻'`, for display.
+ *
+ * The caret is an input convention forced by ASCII ambiguity, and a learner should never see it.
+ *
+ * ## The one place the caret is not needed
+ *
+ * After a closing bracket. `[Cu(H2O)6]2+` has no ambiguity at all, because a digit cannot be the
+ * subscript of a `]`, and that is the form `complexFormula` emits. Without this case a complex ion
+ * came back as `[Cu(H₂O)₆]₂⁺`, with its charge written as a subscript: the same class of defect as a
+ * formatter producing a string its sibling parser cannot read.
+ */
+declare function speciesToUnicode(formula: string): string;
+/** Positive when oxidised, negative when reduced, for `element` between two species. */
+declare function oxidationChange(element: string, from: string, to: string): number;
+/**
+ * Balance one half-equation, in acid or in alkali.
+ *
+ * `balanceHalf('MnO4-', 'Mn2+')` → MnO₄⁻ + 8H⁺ + 5e⁻ → Mn²⁺ + 4H₂O.
+ *
+ * Alkali is not a second procedure: the equation is balanced in acid and then neutralised, which is
+ * exactly what a mark scheme wants written.
+ */
+declare function balanceHalf(from: string, to: string, medium?: Medium): HalfEquation;
+/**
+ * "MnO₄⁻ + 8H⁺ + 5e⁻ → Mn²⁺ + 4H₂O", for display.
+ *
+ * Built from the TERMS, not by running `speciesToUnicode` over the finished string. That was tried
+ * and is wrong: a coefficient is a normal-size number and a separator is a plus sign, so formatting
+ * the whole line turns `2Cr^3+ + 7H2O` into subscripted coefficients and superscripted plus signs.
+ * Chemistry typography is per-species, so the formatter has to be too.
+ */
+declare function halfToUnicode(half: HalfEquation): string;
+/** "MnO₄⁻ + 8H⁺ + 5Fe²⁺ → Mn²⁺ + 4H₂O + 5Fe³⁺", for display. */
+declare function ionicToUnicode(equation: IonicEquation): string;
+/** "MnO4- + 8H+ + 5e- -> Mn2+ + 4H2O" */
+declare function halfToString(half: HalfEquation): string;
+interface IonicEquation {
+  readonly left: readonly Term[];
+  readonly right: readonly Term[];
+  /** How many electrons were transferred once the two halves were scaled to match. */
+  readonly transferred: number;
+}
+/**
+ * Combine a reduction and an oxidation into the full ionic equation.
+ *
+ * Each half is scaled so the electrons cancel exactly, which is the step the whole topic exists to
+ * teach: electrons are not created, so the number lost must equal the number gained.
+ */
+declare function combineHalves(a: HalfEquation, b: HalfEquation): IonicEquation;
+/** "2MnO4- + 16H+ + 10Fe2+ -> 2Mn2+ + 8H2O + 10Fe3+" */
+declare function ionicToString(equation: IonicEquation): string;
+//#endregion
+export { HalfEquation, IonicEquation, Medium, Species, Term, balanceHalf, combineHalves, halfToString, halfToUnicode, ionicToString, ionicToUnicode, oxidationChange, oxidationNumbers, parseSpecies, speciesToUnicode };

package/dist/chem/redox.mjs

@@ -0,0 +1,328 @@
+//#region src/chem/redox.ts
+/** Parse `'Cr2O7^2-'` into its element counts and charge. See the docblock on the caret rule. */
+function parseSpecies(input) {
+	const formula = input.trim();
+	if (!formula) throw new Error("Empty species");
+	let body = formula;
+	let charge = 0;
+	const caret = body.lastIndexOf("^");
+	if (caret >= 0) {
+		const tail = body.slice(caret + 1);
+		const m = /^(\d*)([+-])$/.exec(tail);
+		if (!m) throw new Error(`Cannot read the charge "${tail}" in "${formula}". Write it as ^2- or ^3+.`);
+		charge = (m[1] ? Number(m[1]) : 1) * (m[2] === "+" ? 1 : -1);
+		body = body.slice(0, caret);
+	} else {
+		const m = /([+-])$/.exec(body);
+		if (m) {
+			charge = m[1] === "+" ? 1 : -1;
+			body = body.slice(0, body.length - 1);
+			if (/^[A-Z][a-z]?\d+$/.test(body)) {
+				const split = /^([A-Z][a-z]?)(\d+)$/.exec(body);
+				throw new Error(`"${formula}" is ambiguous: the ${split[2]} could be a subscript or the charge. Write it as "${split[1]}^${split[2]}${m[1]}".`);
+			}
+		}
+	}
+	const elements = {};
+	const add = (symbol, n) => {
+		elements[symbol] = (elements[symbol] ?? 0) + n;
+	};
+	const walk = (text, multiplier) => {
+		let i = 0;
+		while (i < text.length) {
+			if (text[i] === "(") {
+				let depth = 1;
+				let j = i + 1;
+				while (j < text.length && depth > 0) {
+					if (text[j] === "(") depth++;
+					if (text[j] === ")") depth--;
+					j++;
+				}
+				if (depth !== 0) throw new Error(`Unclosed bracket in "${formula}"`);
+				const inner = text.slice(i + 1, j - 1);
+				const digits = /^\d+/.exec(text.slice(j));
+				walk(inner, multiplier * (digits ? Number(digits[0]) : 1));
+				i = j + (digits ? digits[0].length : 0);
+				continue;
+			}
+			const sym = /^[A-Z][a-z]?/.exec(text.slice(i));
+			if (!sym) throw new Error(`Cannot read "${text.slice(i)}" in "${formula}"`);
+			i += sym[0].length;
+			const digits = /^\d+/.exec(text.slice(i));
+			const count = digits ? Number(digits[0]) : 1;
+			i += digits ? digits[0].length : 0;
+			add(sym[0], count * multiplier);
+		}
+	};
+	walk(body, 1);
+	return {
+		formula,
+		elements,
+		charge
+	};
+}
+const ALWAYS = {
+	F: -1,
+	Li: 1,
+	Na: 1,
+	K: 1,
+	Rb: 1,
+	Cs: 1,
+	Be: 2,
+	Mg: 2,
+	Ca: 2,
+	Sr: 2,
+	Ba: 2
+};
+/**
+* Oxidation number of every element in a species.
+*
+* `peroxide` forces O to −1, for H₂O₂ and its salts. It is an argument rather than a detection
+* rule, because H₂O₂ and H₂O differ only in a subscript and guessing from the formula would make
+* the kernel wrong in exactly the case the syllabus asks about.
+*/
+function oxidationNumbers(input, opts = {}) {
+	const species = typeof input === "string" ? parseSpecies(input) : input;
+	const symbols = Object.keys(species.elements);
+	if (symbols.length === 1 && species.charge === 0) return { [symbols[0]]: 0 };
+	if (symbols.length === 1 && species.elements[symbols[0]] === 1) return { [symbols[0]]: species.charge };
+	const known = {};
+	const unknown = [];
+	for (const symbol of symbols) if (symbol in ALWAYS) known[symbol] = ALWAYS[symbol];
+	else if (symbol === "O") known.O = opts.peroxide ? -1 : -2;
+	else if (symbol === "H") known.H = opts.hydride ? -1 : 1;
+	else unknown.push(symbol);
+	if (unknown.length === 0) return known;
+	if (unknown.length > 1) throw new Error(`"${species.formula}" has ${unknown.length} elements with no fixed oxidation number (${unknown.join(", ")}), so none of them is determined. Split the species or state one.`);
+	const target = unknown[0];
+	let sum = 0;
+	for (const [symbol, value] of Object.entries(known)) sum += value * species.elements[symbol];
+	known[target] = (species.charge - sum) / species.elements[target];
+	return known;
+}
+const SUPER = {
+	"0": "⁰",
+	"1": "¹",
+	"2": "²",
+	"3": "³",
+	"4": "⁴",
+	"5": "⁵",
+	"6": "⁶",
+	"7": "⁷",
+	"8": "⁸",
+	"9": "⁹",
+	"+": "⁺",
+	"-": "⁻"
+};
+const SUB = {
+	"0": "₀",
+	"1": "₁",
+	"2": "₂",
+	"3": "₃",
+	"4": "₄",
+	"5": "₅",
+	"6": "₆",
+	"7": "₇",
+	"8": "₈",
+	"9": "₉"
+};
+/**
+* `'Cr2O7^2-'` → `'Cr₂O₇²⁻'`, for display.
+*
+* The caret is an input convention forced by ASCII ambiguity, and a learner should never see it.
+*
+* ## The one place the caret is not needed
+*
+* After a closing bracket. `[Cu(H2O)6]2+` has no ambiguity at all, because a digit cannot be the
+* subscript of a `]`, and that is the form `complexFormula` emits. Without this case a complex ion
+* came back as `[Cu(H₂O)₆]₂⁺`, with its charge written as a subscript: the same class of defect as a
+* formatter producing a string its sibling parser cannot read.
+*/
+function speciesToUnicode(formula) {
+	const bracketed = /^(.*\])(\d+)([+-])$/.exec(formula);
+	if (bracketed) return bracketed[1].replace(/\d/g, (d) => SUB[d]) + ([...bracketed[2]].map((d) => SUPER[d]).join("") + SUPER[bracketed[3]]);
+	const caret = formula.lastIndexOf("^");
+	const body = caret >= 0 ? formula.slice(0, caret) : formula.replace(/[+-]+$/, "");
+	const tail = caret >= 0 ? formula.slice(caret + 1) : /[+-]+$/.exec(formula)?.[0] ?? "";
+	return body.replace(/\d/g, (d) => SUB[d]) + [...tail].map((c) => SUPER[c] ?? c).join("");
+}
+/** Positive when oxidised, negative when reduced, for `element` between two species. */
+function oxidationChange(element, from, to) {
+	const a = oxidationNumbers(from)[element];
+	const b = oxidationNumbers(to)[element];
+	if (a === void 0 || b === void 0) throw new Error(`"${element}" is not in both ${from} and ${to}`);
+	return b - a;
+}
+const gcd = (a, b) => b === 0 ? Math.abs(a) : gcd(b, a % b);
+const WATER = parseSpecies("H2O");
+const PROTON = parseSpecies("H+");
+const HYDROXIDE = parseSpecies("OH-");
+const term = (coeff, species) => ({
+	coeff,
+	species
+});
+function countIn(terms, element) {
+	return terms.reduce((n, t) => n + t.coeff * (t.species.elements[element] ?? 0), 0);
+}
+const chargeOf = (terms) => terms.reduce((q, t) => q + t.coeff * t.species.charge, 0);
+/**
+* Balance one half-equation, in acid or in alkali.
+*
+* `balanceHalf('MnO4-', 'Mn2+')` → MnO₄⁻ + 8H⁺ + 5e⁻ → Mn²⁺ + 4H₂O.
+*
+* Alkali is not a second procedure: the equation is balanced in acid and then neutralised, which is
+* exactly what a mark scheme wants written.
+*/
+function balanceHalf(from, to, medium = "acid") {
+	const a = parseSpecies(from);
+	const b = parseSpecies(to);
+	const key = Object.keys(a.elements).filter((s) => s !== "O" && s !== "H");
+	let coeffA = 1;
+	let coeffB = 1;
+	for (const element of key) {
+		const inA = a.elements[element] ?? 0;
+		const inB = b.elements[element] ?? 0;
+		if (inA === 0 || inB === 0) continue;
+		const g = gcd(inA, inB);
+		coeffA = Math.max(coeffA, inB / g);
+		coeffB = Math.max(coeffB, inA / g);
+	}
+	let left = [term(coeffA, a)];
+	let right = [term(coeffB, b)];
+	const dO = countIn(left, "O") - countIn(right, "O");
+	if (dO > 0) right.push(term(dO, WATER));
+	else if (dO < 0) left.push(term(-dO, WATER));
+	const dH = countIn(left, "H") - countIn(right, "H");
+	if (dH > 0) right.push(term(dH, PROTON));
+	else if (dH < 0) left.push(term(-dH, PROTON));
+	const dQ = chargeOf(left) - chargeOf(right);
+	const electrons = Math.abs(dQ);
+	const electronSide = dQ > 0 ? "left" : "right";
+	if (medium === "alkali") {
+		const protons = [...left, ...right].find((t) => t.species.formula === "H+");
+		if (protons) {
+			const n = protons.coeff;
+			const protonsOnLeft = left.includes(protons);
+			left = left.filter((t) => t !== protons);
+			right = right.filter((t) => t !== protons);
+			if (protonsOnLeft) {
+				left.push(term(n, WATER));
+				right.push(term(n, HYDROXIDE));
+			} else {
+				right.push(term(n, WATER));
+				left.push(term(n, HYDROXIDE));
+			}
+			left = mergeWater(left);
+			right = mergeWater(right);
+			cancelWater(left, right);
+		}
+	}
+	return {
+		left: left.filter((t) => t.coeff > 0),
+		right: right.filter((t) => t.coeff > 0),
+		electrons,
+		electronSide,
+		medium
+	};
+}
+function mergeWater(terms) {
+	const water = terms.filter((t) => t.species.formula === "H2O");
+	if (water.length < 2) return terms;
+	const total = water.reduce((n, t) => n + t.coeff, 0);
+	return [...terms.filter((t) => t.species.formula !== "H2O"), term(total, WATER)];
+}
+/** Water on both sides cancels, which is the tidying step a mark scheme expects. */
+function cancelWater(left, right) {
+	const l = left.findIndex((t) => t.species.formula === "H2O");
+	const r = right.findIndex((t) => t.species.formula === "H2O");
+	if (l < 0 || r < 0) return;
+	const shared = Math.min(left[l].coeff, right[r].coeff);
+	left[l] = term(left[l].coeff - shared, WATER);
+	right[r] = term(right[r].coeff - shared, WATER);
+	if (left[l].coeff === 0) left.splice(l, 1);
+	const r2 = right.findIndex((t) => t.species.formula === "H2O" && t.coeff === 0);
+	if (r2 >= 0) right.splice(r2, 1);
+}
+/**
+* "MnO₄⁻ + 8H⁺ + 5e⁻ → Mn²⁺ + 4H₂O", for display.
+*
+* Built from the TERMS, not by running `speciesToUnicode` over the finished string. That was tried
+* and is wrong: a coefficient is a normal-size number and a separator is a plus sign, so formatting
+* the whole line turns `2Cr^3+ + 7H2O` into subscripted coefficients and superscripted plus signs.
+* Chemistry typography is per-species, so the formatter has to be too.
+*/
+function halfToUnicode(half) {
+	const side = (terms, withElectrons) => {
+		const parts = terms.map((t) => (t.coeff === 1 ? "" : String(t.coeff)) + speciesToUnicode(t.species.formula));
+		if (withElectrons && half.electrons > 0) parts.push((half.electrons === 1 ? "" : String(half.electrons)) + "e⁻");
+		return parts.join(" + ");
+	};
+	return `${side(half.left, half.electronSide === "left")} → ${side(half.right, half.electronSide === "right")}`;
+}
+/** "MnO₄⁻ + 8H⁺ + 5Fe²⁺ → Mn²⁺ + 4H₂O + 5Fe³⁺", for display. */
+function ionicToUnicode(equation) {
+	const side = (terms) => terms.map((t) => (t.coeff === 1 ? "" : String(t.coeff)) + speciesToUnicode(t.species.formula)).join(" + ");
+	return `${side(equation.left)} → ${side(equation.right)}`;
+}
+/** "MnO4- + 8H+ + 5e- -> Mn2+ + 4H2O" */
+function halfToString(half) {
+	const side = (terms, withElectrons) => {
+		const parts = terms.map((t) => t.coeff === 1 ? t.species.formula : `${t.coeff}${t.species.formula}`);
+		if (withElectrons && half.electrons > 0) parts.push(half.electrons === 1 ? "e-" : `${half.electrons}e-`);
+		return parts.join(" + ");
+	};
+	return `${side(half.left, half.electronSide === "left")} -> ${side(half.right, half.electronSide === "right")}`;
+}
+/**
+* Combine a reduction and an oxidation into the full ionic equation.
+*
+* Each half is scaled so the electrons cancel exactly, which is the step the whole topic exists to
+* teach: electrons are not created, so the number lost must equal the number gained.
+*/
+function combineHalves(a, b) {
+	const reduction = a.electronSide === "left" ? a : b;
+	const oxidation = a.electronSide === "left" ? b : a;
+	if (reduction.electronSide !== "left" || oxidation.electronSide !== "right") throw new Error("combineHalves needs one reduction and one oxidation, not two of the same.");
+	const g = gcd(reduction.electrons, oxidation.electrons) || 1;
+	const lcm = reduction.electrons * oxidation.electrons / g;
+	const scaleR = lcm / reduction.electrons;
+	const scaleO = lcm / oxidation.electrons;
+	const scale = (terms, by) => terms.map((t) => term(t.coeff * by, t.species));
+	const left = collect([...scale(reduction.left, scaleR), ...scale(oxidation.left, scaleO)]);
+	const right = collect([...scale(reduction.right, scaleR), ...scale(oxidation.right, scaleO)]);
+	cancelCommon(left, right);
+	return {
+		left,
+		right,
+		transferred: lcm
+	};
+}
+function collect(terms) {
+	const out = [];
+	for (const t of terms) {
+		const found = out.findIndex((u) => u.species.formula === t.species.formula);
+		if (found >= 0) out[found] = term(out[found].coeff + t.coeff, t.species);
+		else out.push(t);
+	}
+	return out;
+}
+/** A species on both sides is a spectator of the combination and is cancelled. */
+function cancelCommon(left, right) {
+	for (let i = left.length - 1; i >= 0; i--) {
+		const j = right.findIndex((t) => t.species.formula === left[i].species.formula);
+		if (j < 0) continue;
+		const shared = Math.min(left[i].coeff, right[j].coeff);
+		left[i] = term(left[i].coeff - shared, left[i].species);
+		right[j] = term(right[j].coeff - shared, right[j].species);
+		if (right[j].coeff === 0) right.splice(j, 1);
+		if (left[i].coeff === 0) left.splice(i, 1);
+	}
+}
+/** "2MnO4- + 16H+ + 10Fe2+ -> 2Mn2+ + 8H2O + 10Fe3+" */
+function ionicToString(equation) {
+	const side = (terms) => terms.map((t) => t.coeff === 1 ? t.species.formula : `${t.coeff}${t.species.formula}`).join(" + ");
+	return `${side(equation.left)} -> ${side(equation.right)}`;
+}
+
+//#endregion
+export { balanceHalf, combineHalves, halfToString, halfToUnicode, ionicToString, ionicToUnicode, oxidationChange, oxidationNumbers, parseSpecies, speciesToUnicode };