@classytic/stage 0.2.0 → 0.4.0

package/dist/chem/stereo.mjs

@@ -0,0 +1,286 @@
+import { elementBySymbol } from "../atomic/elements.mjs";
+import { bondsAt, implicitHydrogens, otherEnd } from "./molecule.mjs";
+
+//#region src/chem/stereo.ts
+/**
+* Stereochemistry: which carbons have a handedness, and which way round each one is.
+*
+* ## The question, and why ranking is the whole of it
+*
+* Two molecules can have the same atoms joined in the same order and still be different substances,
+* because four different groups around one carbon can be arranged two ways that are mirror images
+* and cannot be superimposed. Telling those two apart needs a rule for which group outranks which,
+* and that rule is the Cahn-Ingold-Prelog priority.
+*
+* Almost every treatment gives the rule as "highest atomic number first, and if there is a tie,
+* look further out". The second half is where all the difficulty lives and it is where textbooks
+* stop. Looking further out means comparing two whole branches, and the comparison has a definite
+* shape: gather the atoms at distance one from each branch, sort them heaviest first, compare the
+* two lists; if they match, gather distance two, and so on. It is a breadth-first comparison of
+* trees, and written that way it is neither vague nor hard.
+*
+* {@link comparePriority} does exactly that, so a learner can be shown the sphere at which two
+* branches finally differed rather than being told the answer.
+*
+* ## Double bonds are duplicated, which is the part that looks like a trick
+*
+* A doubly bonded oxygen counts twice. That is not a convention invented to break ties: the rule is
+* that an atom joined by a double bond is treated as joined to two of that atom, because a double
+* bond is two connections. So the carbon of an aldehyde carries (O, O, H) and the carbon of an
+* alcohol carries (O, H, H), and the aldehyde outranks it for a reason rather than by decree.
+*
+* ## What this covers, and what it refuses
+*
+* Tetrahedral carbon centres, and double bonds for E/Z. The priority comparison explores outward
+* through the whole molecule, so it settles the cases that matter at this level.
+*
+* It does NOT implement the auxiliary descriptors CIP needs for rings that are symmetric until
+* several spheres out, or for deciding between two branches that are identical in constitution and
+* differ only in their own stereochemistry. Those exist, they are genuinely intricate, and a
+* kernel that guessed at them would be wrong quietly. {@link comparePriority} returns undefined
+* where it cannot separate two branches, and everything above it reports that rather than picking.
+*
+* Pure: no React, no pixels.
+*/
+/** Proton number, which is what "higher atomic number wins" is comparing. */
+const protons = (element) => elementBySymbol(element)?.Z ?? 0;
+/**
+* The atoms one step out from `atom`, coming from `cameFrom`, heaviest first.
+*
+* Doubly and triply bonded neighbours appear as many times as the bond order, which is the
+* duplication rule. Implicit hydrogens are included, because a hydrogen is a substituent and
+* leaving it out would make a CH2 look like a CH.
+*/
+function neighbours(structure, atom, cameFrom) {
+	const out = [];
+	for (const bond of bondsAt(structure, atom)) {
+		const other = otherEnd(bond, atom);
+		const element = structure.atoms[other].element;
+		const order = bond.aromatic ? 2 : bond.order;
+		if (other !== cameFrom) out.push({
+			element,
+			id: other
+		});
+		for (let k = 1; k < order; k += 1) out.push({
+			element,
+			id: void 0
+		});
+	}
+	for (let k = 0; k < implicitHydrogens(structure, atom); k += 1) out.push({
+		element: "H",
+		id: void 0
+	});
+	return out.sort((a, b) => protons(b.element) - protons(a.element));
+}
+/**
+* Compare two branches by CIP priority.
+*
+* Returns a negative number when the first outranks the second, positive when the second does, and
+* `undefined` when they cannot be separated within the spheres explored, which for a real molecule
+* means they are the same branch.
+*
+* The comparison walks outward one sphere at a time. At each sphere both branches offer a list of
+* atoms sorted heaviest first; the lists are compared position by position, and the first
+* difference decides it. Only if they are identical does the walk go further out.
+*/
+function comparePriority(structure, centre, firstAtom, secondAtom, maxSpheres = 12) {
+	return compareBranches(structure, firstAtom, centre, secondAtom, centre, maxSpheres);
+}
+/**
+* The same comparison, for two branches hanging off DIFFERENT atoms.
+*
+* Needed by the meso check, where the two branches being weighed against each other belong to the
+* two ends of the molecule rather than to one centre. Passing both to {@link comparePriority} with
+* a single centre let each walk escape backwards through the other's parent, so two branches that
+* are plainly the same came out different and no meso form was ever found.
+*/
+function compareBranches(structure, firstAtom, firstFrom, secondAtom, secondFrom, maxSpheres = 12) {
+	const first = protons(structure.atoms[firstAtom].element);
+	const second = protons(structure.atoms[secondAtom].element);
+	if (first !== second) return second - first;
+	let frontA = [{
+		atom: firstAtom,
+		cameFrom: firstFrom
+	}];
+	let frontB = [{
+		atom: secondAtom,
+		cameFrom: secondFrom
+	}];
+	for (let sphere = 0; sphere < maxSpheres; sphere += 1) {
+		if (frontA.length === 0 && frontB.length === 0) return void 0;
+		const expand = (front) => {
+			const list = [];
+			const next = [];
+			for (const node of front) for (const n of neighbours(structure, node.atom, node.cameFrom)) {
+				list.push(n.element);
+				if (n.id !== void 0) next.push({
+					atom: n.id,
+					cameFrom: node.atom
+				});
+			}
+			return {
+				list,
+				next
+			};
+		};
+		const a = expand(frontA);
+		const b = expand(frontB);
+		const sortedA = [...a.list].sort((x, y) => protons(y) - protons(x));
+		const sortedB = [...b.list].sort((x, y) => protons(y) - protons(x));
+		const length = Math.max(sortedA.length, sortedB.length);
+		for (let k = 0; k < length; k += 1) {
+			const pa = protons(sortedA[k] ?? "");
+			const pb = protons(sortedB[k] ?? "");
+			if (pa !== pb) return pb - pa;
+		}
+		frontA = a.next;
+		frontB = b.next;
+	}
+}
+/**
+* The substituents of an atom in priority order, highest first.
+*
+* Returns undefined when two of them cannot be separated, which is the honest answer: a carbon with
+* two identical groups on it has no handedness, and saying so is more useful than an arbitrary
+* ordering that would then produce a confident R or S for a molecule that is neither.
+*/
+function rankSubstituents(structure, centre) {
+	const attached = bondsAt(structure, centre).map((bond) => otherEnd(bond, centre));
+	const hydrogens = implicitHydrogens(structure, centre);
+	if (attached.length + hydrogens !== 4) return void 0;
+	const sorted = [...attached];
+	for (let i = 0; i < sorted.length; i += 1) for (let j = i + 1; j < sorted.length; j += 1) {
+		const order = comparePriority(structure, centre, sorted[i], sorted[j]);
+		if (order === void 0) return void 0;
+		if (order > 0) [sorted[i], sorted[j]] = [sorted[j], sorted[i]];
+	}
+	const ranked = sorted.map((atom, index) => ({
+		atom,
+		element: structure.atoms[atom].element,
+		rank: index + 1
+	}));
+	if (hydrogens === 1) return ranked;
+	if (hydrogens === 0) return ranked;
+}
+/**
+* Every carbon with four different groups on it.
+*
+* The definition, applied rather than paraphrased. A carbon qualifies when the four things attached
+* to it can all be told apart by the priority rules, which is a stronger statement than "four
+* different atoms" and is why 3-methylhexane has a stereocentre and 3-methylpentane does not: in
+* the second, two of the branches are both ethyl.
+*/
+function stereocentres(structure) {
+	const found = [];
+	for (const atom of structure.atoms) {
+		if (atom.element !== "C" || atom.aromatic) continue;
+		const substituents = rankSubstituents(structure, atom.id);
+		if (substituents) found.push({
+			atom: atom.id,
+			substituents
+		});
+	}
+	return found;
+}
+/**
+* How many stereoisomers a molecule has, from its stereocentre count.
+*
+* Two arrangements at each centre, independently, so 2^n. This is the upper bound: see
+* {@link stereoisomerCount} for the number a molecule with an internal mirror plane actually has.
+*/
+const maximumStereoisomers = (centres) => 2 ** centres;
+/**
+* Whether two stereocentres are mirror images of each other through the middle of the molecule.
+*
+* True when the branches leading away from each centre are the same on both sides, which is what
+* makes the molecule superimposable on its own reflection.
+*/
+function centresArePaired(structure, first, second) {
+	const branchesOf = (centre, away) => bondsAt(structure, centre).map((bond) => otherEnd(bond, centre)).filter((id) => id !== away);
+	const a = branchesOf(first, second);
+	const b = branchesOf(second, first);
+	if (a.length !== b.length) return false;
+	const spare = [...b];
+	for (const branch of a) {
+		const match = spare.findIndex((other) => compareBranches(structure, branch, first, other, second) === void 0);
+		if (match === -1) return false;
+		spare.splice(match, 1);
+	}
+	return true;
+}
+/**
+* How many stereoisomers a molecule really has.
+*
+* The rule of 2^n over-counts whenever the molecule has an internal mirror plane. Tartaric acid has
+* two stereocentres and three isomers, not four: the arrangement with one centre left-handed and
+* the other right-handed is superimposable on its own reflection, so the two that 2^n counts
+* separately are one substance, and that substance is not optically active at all.
+*
+* Detected by asking whether the centres are mirror images of one another, which is checkable with
+* the machinery already here: the branches leading away from each centre have to be
+* indistinguishable, and indistinguishable is exactly what {@link comparePriority} reports when it
+* cannot separate two branches.
+*
+* Restricted to the two-centre case, which is the one syllabuses set. A molecule with more centres
+* and partial symmetry needs a full search over configurations, and this reports the maximum for
+* those rather than guessing.
+*/
+function stereoisomerCount(structure) {
+	const centres = stereocentres(structure);
+	const maximum = maximumStereoisomers(centres.length);
+	if (centres.length !== 2) return {
+		centres: centres.length,
+		maximum,
+		actual: maximum,
+		hasMeso: false,
+		because: centres.length < 2 ? "with fewer than two stereocentres there is no internal mirror plane to lose an isomer to" : "more than two centres are not searched for internal symmetry here, so this is the upper bound"
+	};
+	const paired = centresArePaired(structure, centres[0].atom, centres[1].atom);
+	return {
+		centres: 2,
+		maximum,
+		actual: paired ? maximum - 1 : maximum,
+		hasMeso: paired,
+		because: paired ? "the two centres carry the same groups, so the arrangement with one of each handedness is superimposable on its own mirror image: that meso form is one substance rather than two, and it is not optically active" : "the two centres carry different groups, so every one of the four arrangements is a distinct substance"
+	};
+}
+/**
+* Double bonds that can show E/Z, with the higher-priority group on each end identified.
+*
+* A double bond has a shape worth naming only when BOTH its carbons carry two different groups. If
+* either end has two of the same thing, swapping them changes nothing and there is only one
+* compound, which is why 1,1-dichloroethene has no isomers and 1,2-dichloroethene has two.
+*
+* Which arrangement is E and which is Z cannot be read off the connection table: it depends on
+* where the groups actually are in space, which a graph does not record. So this reports WHICH
+* group wins on each end, and the geometry has to say the rest.
+*/
+function stereogenicDoubleBonds(structure) {
+	const found = [];
+	for (const bond of structure.bonds) {
+		if (bond.order !== 2 || bond.aromatic) continue;
+		const higher = (end, far) => {
+			const groups = bondsAt(structure, end).map((b) => otherEnd(b, end)).filter((id) => id !== far);
+			const hydrogens = implicitHydrogens(structure, end);
+			if (groups.length + hydrogens !== 2) return void 0;
+			if (groups.length === 1 && hydrogens === 1) return groups[0];
+			if (groups.length !== 2) return void 0;
+			const order = comparePriority(structure, end, groups[0], groups[1]);
+			if (order === void 0) return void 0;
+			return order < 0 ? groups[0] : groups[1];
+		};
+		const higherOnA = higher(bond.a, bond.b);
+		const higherOnB = higher(bond.b, bond.a);
+		if (higherOnA === void 0 || higherOnB === void 0) continue;
+		found.push({
+			a: bond.a,
+			b: bond.b,
+			higherOnA,
+			higherOnB
+		});
+	}
+	return found;
+}
+
+//#endregion
+export { compareBranches, comparePriority, maximumStereoisomers, rankSubstituents, stereocentres, stereogenicDoubleBonds, stereoisomerCount };

package/dist/chem/stoichiometry.d.mts

@@ -0,0 +1,95 @@
+import { BalancedEquation } from "./equation.mjs";
+
+//#region src/chem/stoichiometry.d.ts
+/** How much of a substance is present, in whichever way it was measured. */
+interface Amount {
+  /** Grams. */
+  readonly mass?: number;
+  /** Moles, if they are known directly. */
+  readonly moles?: number;
+  /** Volume in cubic decimetres, for something in solution. */
+  readonly volumeDm3?: number;
+  /** Concentration in mol per cubic decimetre, used with the volume. */
+  readonly concentration?: number;
+}
+/** Moles of a substance from however it was given. */
+declare function molesOf(formula: string, amount: Amount): number;
+interface ReactantState {
+  readonly formula: string;
+  readonly coefficient: number;
+  readonly moles: number;
+  /**
+   * Moles available divided by the coefficient: how many times the equation can run on this one.
+   *
+   * The number the whole calculation turns on, and the one a mass comparison never reaches.
+   */
+  readonly equationRuns: number;
+  readonly limiting: boolean;
+  /** Moles of this reactant left when the limiting one is spent. */
+  readonly leftOver: number;
+}
+interface ProductState {
+  readonly formula: string;
+  readonly coefficient: number;
+  readonly moles: number;
+  readonly mass: number;
+}
+interface Reaction {
+  readonly equation: BalancedEquation;
+  /** How many times the equation as written can proceed. */
+  readonly runs: number;
+  readonly reactants: readonly ReactantState[];
+  readonly products: readonly ProductState[];
+  readonly limiting: ReactantState;
+}
+/**
+ * Work a reaction out from the amounts given.
+ *
+ * The equation is balanced here rather than taken on trust, because every mole ratio below depends
+ * on the coefficients and an unbalanced equation would make all of them confidently wrong.
+ */
+declare function react(equation: string, amounts: Readonly<Record<string, Amount>>): Reaction;
+/** The most of a product the equation allows, in grams. */
+declare function theoreticalYield(reaction: Reaction, product: string): number;
+interface YieldReport {
+  /** Measured over theoretical, as a percentage. Reported even when it is impossible. */
+  readonly percent: number;
+  /** Why this figure cannot be a yield, when it cannot be. */
+  readonly impossible?: string;
+}
+/**
+ * The measured mass as a percentage of the theoretical one, whatever it comes to.
+ *
+ * Reports rather than refuses, because a figure above a hundred per cent is a real thing that comes
+ * out of a real balance and is the single most useful measurement in the topic: it is the one that
+ * tells you something is wrong with the sample. A lab teaching that has to be able to SHOW 112 per
+ * cent before asking what it means.
+ *
+ * What it must not do is call that a yield. So the number comes back with the reason it is not one
+ * attached, and {@link percentageYield} is the strict form built on this for the places where the
+ * value has to be legitimate.
+ */
+declare function apparentYield(theoretical: number, measured: number): YieldReport;
+/**
+ * The fraction of the theoretical yield actually obtained, as a percentage.
+ *
+ * Refuses anything above a hundred. A flask cannot produce more than the equation allows, so a
+ * figure above it is evidence about the sample rather than about the reaction, and reporting it as
+ * a yield hides the one piece of information the number actually carries. Use {@link apparentYield}
+ * where that figure needs to be shown rather than accepted.
+ */
+declare function percentageYield(theoretical: number, measured: number): number;
+/**
+ * The mass of one reactant needed to use up a given amount of another exactly.
+ *
+ * What a preparation asks: how much of this do I weigh out so nothing is wasted.
+ */
+declare function amountNeeded(equation: string, have: {
+  formula: string;
+  amount: Amount;
+}, want: string): {
+  moles: number;
+  mass: number;
+};
+//#endregion
+export { Amount, ProductState, ReactantState, Reaction, YieldReport, amountNeeded, apparentYield, molesOf, percentageYield, react, theoreticalYield };

package/dist/chem/stoichiometry.mjs

@@ -0,0 +1,145 @@
+import { molarMass } from "./formula.mjs";
+import { balance } from "./equation.mjs";
+
+//#region src/chem/stoichiometry.ts
+/**
+* How much of what: limiting reagent, theoretical yield, and what is left over.
+*
+* ## The whole subject is one division
+*
+* Every quantitative question reduces to the same move. Convert what you have into moles, divide
+* each by its coefficient, and whichever comes out smallest runs out first. That ratio, the moles
+* available per unit of equation, is the only number that matters: it says how many times the
+* reaction as written can proceed, and everything else is that number multiplied by a coefficient.
+*
+* So {@link react} computes it once and reads every answer off it. There is no separate method for
+* limiting reagent, for yield, for excess: they are three questions about one quantity.
+*
+* ## The limiting reagent is not the one there is least of
+*
+* The most common mistake in the topic, and it is a mistake about what "least" means. Ten grams of
+* hydrogen and twenty-five of oxygen: there is less hydrogen by mass and far more by moles, and the
+* oxygen runs out first because the equation needs two hydrogens for every oxygen. Comparing masses
+* answers a question nobody asked, and comparing moles without dividing by the coefficients answers
+* a different wrong one.
+*
+* ## Yield is measured, and the theoretical figure is not a prediction of it
+*
+* The theoretical yield is what the equation permits. What comes out of a flask is always less:
+* some product stays in solution, some is lost in transfer, the reaction may not finish. So
+* {@link percentageYield} takes a measured mass and compares, and a yield above a hundred per cent
+* is refused rather than reported, because it means the product is wet or impure and the useful
+* answer is to say so.
+*
+* Pure: no React, no pixels.
+*/
+/** Moles of a substance from however it was given. */
+function molesOf(formula, amount) {
+	if (amount.moles !== void 0) return amount.moles;
+	if (amount.mass !== void 0) return amount.mass / molarMass(formula);
+	if (amount.volumeDm3 !== void 0 && amount.concentration !== void 0) return amount.volumeDm3 * amount.concentration;
+	throw new Error(`not enough to work out the moles of ${formula}: give a mass, a number of moles, or a volume together with a concentration`);
+}
+/**
+* Work a reaction out from the amounts given.
+*
+* The equation is balanced here rather than taken on trust, because every mole ratio below depends
+* on the coefficients and an unbalanced equation would make all of them confidently wrong.
+*/
+function react(equation, amounts) {
+	const balanced = balance(equation);
+	const named = new Set(Object.keys(amounts));
+	const missing = balanced.reactants.filter((r) => !named.has(r.formula));
+	if (missing.length > 0) throw new Error(`no amount given for ${missing.map((r) => r.formula).join(" or ")}: every reactant needs one, since the limiting one cannot be found without them all`);
+	const withRuns = balanced.reactants.map((term) => {
+		const moles = molesOf(term.formula, amounts[term.formula]);
+		return {
+			term,
+			moles,
+			equationRuns: moles / term.coefficient
+		};
+	});
+	const runs = Math.min(...withRuns.map((r) => r.equationRuns));
+	const limitingRuns = runs;
+	const reactants = withRuns.map(({ term, moles, equationRuns }) => ({
+		formula: term.formula,
+		coefficient: term.coefficient,
+		moles,
+		equationRuns,
+		limiting: equationRuns === limitingRuns,
+		leftOver: moles - limitingRuns * term.coefficient
+	}));
+	return {
+		equation: balanced,
+		runs,
+		reactants,
+		products: balanced.products.map((term) => ({
+			formula: term.formula,
+			coefficient: term.coefficient,
+			moles: runs * term.coefficient,
+			mass: runs * term.coefficient * molarMass(term.formula)
+		})),
+		limiting: reactants.find((r) => r.limiting)
+	};
+}
+/** The most of a product the equation allows, in grams. */
+function theoreticalYield(reaction, product) {
+	const found = reaction.products.find((p) => p.formula === product);
+	if (!found) throw new Error(`${product} is not a product of this reaction: it makes ${reaction.products.map((p) => p.formula).join(", ")}`);
+	return found.mass;
+}
+/**
+* The measured mass as a percentage of the theoretical one, whatever it comes to.
+*
+* Reports rather than refuses, because a figure above a hundred per cent is a real thing that comes
+* out of a real balance and is the single most useful measurement in the topic: it is the one that
+* tells you something is wrong with the sample. A lab teaching that has to be able to SHOW 112 per
+* cent before asking what it means.
+*
+* What it must not do is call that a yield. So the number comes back with the reason it is not one
+* attached, and {@link percentageYield} is the strict form built on this for the places where the
+* value has to be legitimate.
+*/
+function apparentYield(theoretical, measured) {
+	if (theoretical <= 0) throw new Error("a theoretical yield of zero has no percentage");
+	if (measured < 0) throw new Error("a measured mass cannot be negative");
+	const percent = measured / theoretical * 100;
+	if (percent > 100.0001) return {
+		percent,
+		impossible: `${measured} g is ${percent.toFixed(1)} per cent of the ${theoretical.toFixed(3)} g the equation allows. A reaction cannot make more than its theoretical maximum, so the product is wet or impure, or the balance is wrong.`
+	};
+	return { percent };
+}
+/**
+* The fraction of the theoretical yield actually obtained, as a percentage.
+*
+* Refuses anything above a hundred. A flask cannot produce more than the equation allows, so a
+* figure above it is evidence about the sample rather than about the reaction, and reporting it as
+* a yield hides the one piece of information the number actually carries. Use {@link apparentYield}
+* where that figure needs to be shown rather than accepted.
+*/
+function percentageYield(theoretical, measured) {
+	const report = apparentYield(theoretical, measured);
+	if (report.impossible) throw new Error(report.impossible);
+	return report.percent;
+}
+/**
+* The mass of one reactant needed to use up a given amount of another exactly.
+*
+* What a preparation asks: how much of this do I weigh out so nothing is wasted.
+*/
+function amountNeeded(equation, have, want) {
+	const balanced = balance(equation);
+	const from = balanced.reactants.find((r) => r.formula === have.formula);
+	const to = balanced.reactants.find((r) => r.formula === want);
+	if (!from) throw new Error(`${have.formula} is not a reactant in this equation`);
+	if (!to) throw new Error(`${want} is not a reactant in this equation`);
+	const moles = molesOf(have.formula, have.amount) / from.coefficient * to.coefficient;
+	return {
+		moles,
+		mass: moles * molarMass(want)
+	};
+}
+
+//#endregion
+export { amountNeeded, apparentYield, molesOf, percentageYield, react, theoreticalYield };

package/dist/chem/synthesis.d.mts

@@ -0,0 +1,113 @@
+//#region src/chem/synthesis.d.ts
+/**
+ * synthesis, the functional-group map: every conversion as an edge, and a route as a path.
+ *
+ * WHAT THIS IS FOR. Every synthesis question in the AS and A2 papers has one form: convert X into
+ * Y, giving the reagents and conditions for each step. A learner who has memorised the reactions as
+ * a list still cannot answer it, because the question is not "what does an alcohol do" but "which
+ * sequence of things that alcohols do gets me to an ester". That is a path-finding problem, and the
+ * reason it feels hard is that a list is the wrong shape for it.
+ *
+ * Drawn as a graph the answer is computable: the groups are places, the reagents are roads, and a
+ * synthesis is a route. {@link findRoute} returns one, with the reagent and the condition for each
+ * step, so a lesson can state a route and have it CHECKED rather than asserted.
+ *
+ * ## Why the edges carry conditions and never omit them
+ *
+ * A route is not worth marks without them. `halogenoalkane -> alcohol` and
+ * `halogenoalkane -> alkene` are the same reagent, sodium hydroxide, and differ only in the
+ * solvent. An edge naming the reagent alone would make those two roads identical, which is exactly
+ * the confusion the elimination lesson exists to prevent. So `condition` is not optional.
+ *
+ * ## Why this is in stage and not in the lab that drew it
+ *
+ * It was written inside `labs/domains/chem/synthesis-route`, which meant the only thing that could
+ * ask a question of it was the figure sitting on top of it. A course could not verify a route it
+ * claimed, a second lab could not reuse the graph without copying it, and the most useful fact in
+ * the topic, that only two reactions change the number of carbon atoms, was computable but
+ * unreachable. Dependency direction decides where a shared function lives, and everything here
+ * points inward: the graph needs nothing from the lab, and the lab needs the graph.
+ *
+ * What stayed behind is presentation. Where a group sits on the map is a layout decision made by
+ * eye for legibility, and it is not chemistry.
+ *
+ * Pure: no React, no pixels.
+ */
+/** The functional groups an AS and A2 synthesis question moves between. */
+type GroupNode = 'alkane' | 'alkene' | 'halogenoalkane' | 'alcohol' | 'nitrile' | 'aldehyde' | 'ketone' | 'acid' | 'ester' | 'acyl-chloride' | 'arene' | 'nitroarene' | 'arylamine' | 'amine' | 'amide';
+/** What a learner calls the group. The name is chemistry; where it sits on a map is not. */
+declare const GROUP_LABELS: Readonly<Record<GroupNode, string>>;
+interface RouteEdge {
+  readonly from: GroupNode;
+  readonly to: GroupNode;
+  readonly reagent: string;
+  /** Never optional: the solvent and the temperature are the marks. */
+  readonly condition: string;
+  /** Does the carbon chain change length? Only two reactions here do. */
+  readonly changesChain?: boolean;
+  /** Which class of the starting group this needs, where it matters. */
+  readonly needs?: string;
+}
+declare const ROUTE_EDGES: readonly RouteEdge[];
+/** Every group the map knows, in the order the type declares them. */
+declare const GROUP_NODES: GroupNode[];
+/** Roads leaving a group. */
+declare const edgesFrom: (id: GroupNode) => readonly RouteEdge[];
+/** The road between two groups, if there is one. */
+declare const edgeBetween: (from: GroupNode, to: GroupNode) => RouteEdge | undefined;
+/** The roads along a path of groups, so a route can be read back as an answer. */
+declare function edgesAlong(path: readonly GroupNode[]): RouteEdge[];
+/**
+ * Shortest path length between two groups, by breadth-first search.
+ *
+ * `undefined` when no route exists, which is a real answer rather than a failure: a learner
+ * hunting for a reaction that does not exist is exactly what a route map is for.
+ */
+declare function shortestSteps(from: GroupNode, to: GroupNode): number | undefined;
+/** A synthesis, as a learner would have to write it out. */
+interface Route {
+  readonly path: readonly GroupNode[];
+  readonly steps: readonly RouteEdge[];
+  /** Does this route pass through a reaction that changes the number of carbon atoms? */
+  readonly changesChain: boolean;
+}
+/**
+ * One shortest route, with the reagent and condition for every step.
+ *
+ * This is the difference between a distance and an answer. A lesson claiming "alkene to carboxylic
+ * acid in three steps" can now be checked against the route the map actually gives, and the steps
+ * it returns are the marks.
+ *
+ * ## Why a plain breadth-first search was not enough
+ *
+ * Alkene to carboxylic acid has TWO routes of three steps. One hydrates and oxidises twice and
+ * keeps the carbon skeleton. The other goes through the nitrile, and a nitrile road adds a carbon,
+ * so it arrives at an acid ONE CARBON LONGER than the target. A search that returned whichever it
+ * reached first would hand a learner the wrong molecule half the time, and would do it silently,
+ * because both routes are three steps and both are real chemistry.
+ *
+ * So among equally short routes the chain-preserving one wins. A question that wants the longer
+ * chain says so, and {@link allRoutes} still has both.
+ */
+declare function findRoute(from: GroupNode, to: GroupNode): Route | undefined;
+/**
+ * Every route from one group to another within a step budget, shortest first.
+ *
+ * Exists because the shortest route is not always the best one, which is the single most arguable
+ * point in the topic. Esterifying an acid directly is one step and an equilibrium that stops well
+ * short; going via the acyl chloride is two steps and goes to completion. Both routes have to be
+ * on the table for that to be a judgement rather than a rule.
+ *
+ * `maxSteps` is capped at six, because the map's diameter is smaller than that and an uncapped
+ * enumeration on a cyclic graph does not terminate usefully.
+ */
+declare function allRoutes(from: GroupNode, to: GroupNode, maxSteps?: number): Route[];
+/**
+ * The reactions that change the number of carbon atoms.
+ *
+ * The most useful fact in the topic and the one that is invisible in a list: to reach a target with
+ * more carbons than the starting material, a route MUST pass through one of these.
+ */
+declare const chainChangingEdges: () => readonly RouteEdge[];
+//#endregion
+export { GROUP_LABELS, GROUP_NODES, GroupNode, ROUTE_EDGES, Route, RouteEdge, allRoutes, chainChangingEdges, edgeBetween, edgesAlong, edgesFrom, findRoute, shortestSteps };