@classytic/stage 0.3.0 → 0.4.0

package/dist/chem/ionic.mjs

@@ -0,0 +1,156 @@
+import { parseFormula } from "./formula.mjs";
+
+//#region src/chem/ionic.ts
+/**
+* Ions, and the formula two of them make.
+*
+* ## The one rule, which is usually taught as a trick
+*
+* "Write the formula of aluminium oxide" is answered in most classrooms by the crossover trick:
+* write the charges, swap them over, drop the signs. It gives Al2O3, and it gives the wrong answer
+* for magnesium oxide, where crossing over 2 and 2 gives Mg2O2 and the compound is MgO. The trick
+* then acquires a patch: "and cancel down if you can".
+*
+* There is no trick. A compound has no overall charge, so the positive and negative charges in it
+* must cancel exactly, and the formula is the SMALLEST whole number of each ion that makes them.
+* That is a lowest common multiple, and it gets magnesium oxide right without a patch because the
+* smallest multiple of 2 that is also a multiple of 2 is 2, not 4.
+*
+* {@link neutralRatio} computes it that way, so the reasoning a learner is shown is the reasoning
+* the engine uses.
+*
+* ## Charges are data, and the ones worth knowing are here
+*
+* Which charge an ion carries is not derivable for a transition metal, and only roughly derivable
+* from the group for everything else. So the common ones are listed, with their names, because
+* "what is the formula of iron(III) sulfate" needs both the charge and the fact that sulfate is one
+* unit that keeps its brackets.
+*
+* Pure: no React, no pixels.
+*/
+const ion = (formula, charge, name) => ({
+	formula,
+	charge,
+	name,
+	polyatomic: parseFormula(formula).reduce((total, e) => total + e.count, 0) > 1
+});
+/** The cations a syllabus expects to be known. */
+const CATIONS = [
+	ion("H", 1, "hydrogen"),
+	ion("Li", 1, "lithium"),
+	ion("Na", 1, "sodium"),
+	ion("K", 1, "potassium"),
+	ion("Ag", 1, "silver"),
+	ion("NH4", 1, "ammonium"),
+	ion("Mg", 2, "magnesium"),
+	ion("Ca", 2, "calcium"),
+	ion("Ba", 2, "barium"),
+	ion("Zn", 2, "zinc"),
+	ion("Cu", 2, "copper(II)"),
+	ion("Fe", 2, "iron(II)"),
+	ion("Pb", 2, "lead(II)"),
+	ion("Al", 3, "aluminium"),
+	ion("Cr", 3, "chromium(III)")
+];
+/** Iron and copper each appear twice, so the ion has to be named rather than the element. */
+const IRON_III = ion("Fe", 3, "iron(III)");
+const COPPER_I = ion("Cu", 1, "copper(I)");
+/** The anions a syllabus expects to be known. */
+const ANIONS = [
+	ion("F", -1, "fluoride"),
+	ion("Cl", -1, "chloride"),
+	ion("Br", -1, "bromide"),
+	ion("I", -1, "iodide"),
+	ion("OH", -1, "hydroxide"),
+	ion("NO3", -1, "nitrate"),
+	ion("HCO3", -1, "hydrogencarbonate"),
+	ion("O", -2, "oxide"),
+	ion("S", -2, "sulfide"),
+	ion("SO4", -2, "sulfate"),
+	ion("CO3", -2, "carbonate"),
+	ion("PO4", -3, "phosphate")
+];
+/** Every ion listed here, cations and anions together. */
+const IONS = [
+	...CATIONS,
+	IRON_III,
+	COPPER_I,
+	...ANIONS
+];
+/**
+* Find an ion by the name it takes in a compound.
+*
+* Matched case-insensitively on BOTH sides. Lowercasing only the input looked right and failed for
+* every ion whose name carries a Roman numeral, since "iron(iii)" never matches "iron(III)".
+*/
+const ionByName = (name) => {
+	const wanted = name.trim().toLowerCase();
+	return IONS.find((i) => i.name.toLowerCase() === wanted);
+};
+const gcd = (a, b) => b === 0 ? Math.abs(a) : gcd(b, a % b);
+/**
+* How many of each ion make a compound with no overall charge, in the smallest whole numbers.
+*
+* The lowest common multiple of the two charge sizes, divided by each. Magnesium and oxide both
+* carry two, their lowest common multiple is two, and one of each is the answer: MgO. The crossover
+* trick would have given Mg2O2 and needed a separate rule to cancel it down.
+*/
+function neutralRatio(cationCharge, anionCharge) {
+	if (cationCharge <= 0) throw new Error(`a cation carries a positive charge, not ${cationCharge}`);
+	if (anionCharge >= 0) throw new Error(`an anion carries a negative charge, not ${anionCharge}`);
+	const size = Math.abs(anionCharge);
+	const lcm = cationCharge * size / gcd(cationCharge, size);
+	return [lcm / cationCharge, lcm / size];
+}
+/** One ion written out with its count, bracketed when it needs to be. */
+function writeIon(part, count) {
+	if (count === 1) return part.formula;
+	return part.polyatomic ? `(${part.formula})${count}` : `${part.formula}${count}`;
+}
+/**
+* The compound two ions form.
+*
+* `ionicFormula(aluminium, oxide)` gives Al2O3; `ionicFormula(magnesium, oxide)` gives MgO, not
+* Mg2O2; `ionicFormula(calcium, nitrate)` gives Ca(NO3)2 with the brackets that stop it being read
+* as thirty-two oxygens.
+*/
+function ionicCompound(cation, anion) {
+	const [cationCount, anionCount] = neutralRatio(cation.charge, anion.charge);
+	return {
+		formula: `${writeIon(cation, cationCount)}${writeIon(anion, anionCount)}`,
+		name: `${cation.name} ${anion.name}`,
+		cation,
+		anion,
+		cationCount,
+		anionCount
+	};
+}
+/** The same, by name: `compoundOf('calcium', 'carbonate')`. */
+function compoundOf(cationName, anionName) {
+	const cation = ionByName(cationName);
+	const anion = ionByName(anionName);
+	if (!cation) throw new Error(`no ion named "${cationName}" in this table`);
+	if (!anion) throw new Error(`no ion named "${anionName}" in this table`);
+	if (cation.charge <= 0) throw new Error(`"${cationName}" is not a cation`);
+	if (anion.charge >= 0) throw new Error(`"${anionName}" is not an anion`);
+	return ionicCompound(cation, anion);
+}
+/**
+* Whether a proposed pair of counts makes a neutral compound, and whether it is the simplest one.
+*
+* Both answers matter and they are different. Mg2O2 IS neutral and is not a formula anyone writes,
+* so a learner offering it has understood the charge balance and not the "smallest" part, and
+* telling them only that it is wrong would hide which half they have.
+*/
+function assessCounts(cation, anion, cationCount, anionCount) {
+	const totalCharge = cation.charge * cationCount + anion.charge * anionCount;
+	const [wantCation, wantAnion] = neutralRatio(cation.charge, anion.charge);
+	return {
+		totalCharge,
+		neutral: totalCharge === 0,
+		simplest: cationCount === wantCation && anionCount === wantAnion
+	};
+}
+
+//#endregion
+export { ANIONS, CATIONS, IONS, assessCounts, compoundOf, ionByName, ionicCompound, neutralRatio, writeIon };

package/dist/chem/layout.d.mts

@@ -0,0 +1,46 @@
+import { Structure } from "./molecule.mjs";
+
+//#region src/chem/layout.d.ts
+interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+/**
+ * Where every atom goes, in bond lengths, with y downward.
+ *
+ * A disconnected structure lays each piece out and offsets it, so nothing overlaps: that happens
+ * when a reaction has produced a small molecule alongside the main one.
+ */
+declare function layout(structure: Structure): Map<number, Point>;
+interface LaidOut {
+  readonly positions: ReadonlyMap<number, Point>;
+  /** Corners of the drawing, in bond lengths, so a caller can centre and scale it. */
+  readonly bounds: {
+    readonly minX: number;
+    readonly minY: number;
+    readonly maxX: number;
+    readonly maxY: number;
+  };
+  /** Ring systems, in bonded order, so an aromatic circle can be drawn in the right place. */
+  readonly rings: readonly (readonly number[])[];
+}
+/** The layout plus everything a figure needs to place it on a page. */
+declare function layoutOf(structure: Structure): LaidOut;
+/** The centre of a ring, for the delocalisation circle. */
+declare function ringCentre(ring: readonly number[], positions: ReadonlyMap<number, Point>): Point;
+/**
+ * Several free directions at an atom, for drawing its hydrogens in a displayed formula.
+ *
+ * Returned widest-gap first and spread apart, so a CH2 puts its two hydrogens on opposite sides
+ * rather than side by side where they would touch.
+ */
+declare function freeDirections(structure: Structure, id: number, positions: ReadonlyMap<number, Point>, count: number): Point[];
+/**
+ * A free direction at an atom, for drawing an open valence or an implicit-hydrogen label.
+ *
+ * Returns the lattice direction furthest from every bond the atom already has, which is where a
+ * chemist would put it.
+ */
+declare function freeDirection(structure: Structure, id: number, positions: ReadonlyMap<number, Point>): Point;
+//#endregion
+export { LaidOut, Point, freeDirection, freeDirections, layout, layoutOf, ringCentre };

package/dist/chem/layout.mjs

@@ -0,0 +1,342 @@
+import { bondsAt, otherEnd } from "./molecule.mjs";
+import { ringSystems } from "./skeleton.mjs";
+
+//#region src/chem/layout.ts
+/**
+* layout, where every atom of a structure goes on the page.
+*
+* WHAT THIS IS FOR. Drawing a molecule from a graph needs coordinates, and until now the corpus got
+* them by having an author place a chain by hand. That works for a hand-written structure and cannot
+* work for a computed one: a polymer repeat unit is built by the kernel, and nobody is there to
+* place it. It also cannot express the shape that broke the polymer lab, a ring with the chain
+* running THROUGH it, because a hand-placed chain is a chain or a ring and never both.
+*
+* So positions are computed. Coordinates come back in BOND LENGTHS, with y increasing downward to
+* match SVG, and the caller scales and centres them.
+*
+* ## The lattice, and why 30 degrees
+*
+* Every bond points along one of twelve directions, 30 degrees apart. That single choice gives both
+* shapes chemistry needs: a zig-zag chain is bonds alternating at plus and minus 30 degrees from
+* horizontal, which is a 120 degree bond angle, and a hexagon's edges are at 30 plus multiples of
+* 60. A finer lattice would let bonds land at angles no structure drawing uses; a coarser one cannot
+* draw both shapes at once.
+*
+* ## Rings are placed first, and everything else grows off them
+*
+* A ring's geometry is fixed and a chain's is not, so the rings are laid down as regular polygons
+* and the acyclic atoms are then walked outward from whatever is already placed. Doing it the other
+* way round means discovering halfway along a chain that it has to close into a hexagon, and moving
+* everything already placed.
+*
+* ## How a direction is chosen
+*
+* From the direction the walk arrived, turn 60 degrees, alternating which way so a chain zig-zags
+* instead of curling into a circle. If that position is occupied, try the other way, then wider
+* angles. The occupancy test is what stops a branch being drawn on top of the chain it hangs from,
+* and it is why this is a search rather than a formula.
+*
+* Pure: no React, no pixels.
+*/
+/** Twelve directions, 30 degrees apart, as unit vectors. */
+const STEP = Math.PI / 6;
+const DIRECTIONS = Array.from({ length: 12 }, (_, k) => ({
+	x: Math.cos(k * STEP),
+	y: Math.sin(k * STEP)
+}));
+/** The lattice direction closest to an angle, as an index into {@link DIRECTIONS}. */
+const snap = (angle) => (Math.round(angle / STEP) % 12 + 12) % 12;
+const angleOf = (from, to) => Math.atan2(to.y - from.y, to.x - from.x);
+/** Two atoms are on top of each other if they are closer than this, in bond lengths. */
+const TOO_CLOSE = .55;
+const linked = (structure, id) => bondsAt(structure, id).map((b) => otherEnd(b, id));
+/**
+* How many atoms lie beyond a neighbour, without coming back through this one.
+*
+* Used to decide which way the CHAIN goes. At a branching atom the neighbour leading to the most
+* atoms is the backbone and takes the zig-zag; the small ones hanging off it are substituents and
+* are placed wherever there is room. Without this the order the bonds happen to be declared in
+* decides, so ethyl ethanoate gave its chain direction to the carbonyl oxygen and drew itself
+* vertically with the chain hanging off the side.
+*/
+function reachBeyond(structure, from, through) {
+	const seen = new Set([from, through]);
+	const stack = [through];
+	let count = 0;
+	while (stack.length) {
+		const at = stack.pop();
+		count += 1;
+		for (const n of linked(structure, at)) {
+			if (seen.has(n)) continue;
+			seen.add(n);
+			stack.push(n);
+		}
+	}
+	return count;
+}
+/**
+* Where every atom goes, in bond lengths, with y downward.
+*
+* A disconnected structure lays each piece out and offsets it, so nothing overlaps: that happens
+* when a reaction has produced a small molecule alongside the main one.
+*/
+function layout(structure) {
+	const placed = /* @__PURE__ */ new Map();
+	const rings = ringSystems(structure);
+	const occupied = (p, ignore) => [...placed].some(([id, q]) => id !== ignore && Math.hypot(p.x - q.x, p.y - q.y) < TOO_CLOSE);
+	/**
+	* Put a ring down as a regular polygon, turned so its substituents run across the page.
+	*
+	* A bare ring gets a vertex at the top, which is how benzene is printed. A SUBSTITUTED ring is
+	* turned so the first substituted vertex sits on the left, which for a para-disubstituted ring
+	* puts the other one on the right and lets the chain run horizontally through it. Without that,
+	* terephthalic acid came out six bond lengths tall and two wide, with its two carboxyls stacked.
+	*/
+	const placeRing = (ring, centre) => {
+		const n = ring.length;
+		const radius = 1 / (2 * Math.sin(Math.PI / n));
+		const ordered = orderRing(structure, ring);
+		const inRing = new Set(ordered);
+		const substituted = ordered.findIndex((id) => linked(structure, id).some((nb) => !inRing.has(nb)));
+		const turn = substituted >= 0 ? Math.PI - substituted * 2 * Math.PI / n : -Math.PI / 2;
+		ordered.forEach((id, i) => {
+			const a = turn + i * 2 * Math.PI / n;
+			placed.set(id, {
+				x: centre.x + radius * Math.cos(a),
+				y: centre.y + radius * Math.sin(a)
+			});
+		});
+	};
+	if (rings[0]?.length) placeRing(rings[0], {
+		x: 0,
+		y: 0
+	});
+	else if (structure.atoms[0]) placed.set(structure.atoms[0].id, {
+		x: 0,
+		y: 0
+	});
+	/** Directions already used by bonds at an atom, as angles. */
+	const usedAngles = (id) => linked(structure, id).filter((n) => placed.has(n)).map((n) => angleOf(placed.get(id), placed.get(n)));
+	/**
+	* The direction a bond leaves an atom in.
+	*
+	* CONTINUING A CHAIN is a reflection, not a rotation. A zig-zag is bonds alternating between plus
+	* and minus 30 degrees, which is exactly "mirror the direction you arrived on in the horizontal",
+	* so the chain travels along the page instead of turning. Rotating by a fixed 60 degrees each
+	* step was the first version and it curls: six carbons came out as a hexagon the molecule does not
+	* have, and hexanedioic acid was drawn taller than it was wide.
+	*
+	* A BRANCH has no direction to reflect, so it takes the lattice direction furthest from every bond
+	* the atom already has, which is where a chemist puts it and which is also what keeps a
+	* substituent off a ring's own edges.
+	*/
+	const directionFrom = (id, incoming) => {
+		const used = usedAngles(id);
+		if (incoming !== void 0 && used.length <= 1) {
+			const candidate = DIRECTIONS[snap(snap(-incoming) === snap(incoming) ? incoming + STEP : -incoming)];
+			if (!occupied({
+				x: placed.get(id).x + candidate.x,
+				y: placed.get(id).y + candidate.y
+			})) return candidate;
+		}
+		let best;
+		let bestGap = -1;
+		for (const d of DIRECTIONS) {
+			const here = placed.get(id);
+			if (occupied({
+				x: here.x + d.x,
+				y: here.y + d.y
+			})) continue;
+			const a = Math.atan2(d.y, d.x);
+			const gap = used.length ? Math.min(...used.map((u) => Math.abs(Math.atan2(Math.sin(a - u), Math.cos(a - u))))) : Math.PI;
+			if (gap > bestGap) {
+				bestGap = gap;
+				best = d;
+			}
+		}
+		return best ?? DIRECTIONS[0];
+	};
+	/**
+	* Walk outward from everything placed, breadth first, carrying the direction each step arrived on.
+	*
+	* Breadth first rather than depth first so a long chain is laid down before its branches, which
+	* means the branches see the chain already in place and step around it.
+	*/
+	const grow = () => {
+		const queue = [...placed.keys()].map((id) => ({
+			id,
+			incoming: void 0
+		}));
+		let progress = false;
+		const seen = new Set(queue.map((q) => q.id));
+		const flat = structure.atoms.length <= 2;
+		let seeded = placed.size > 1;
+		while (queue.length) {
+			const { id, incoming } = queue.shift();
+			let continued = false;
+			const outward = [...linked(structure, id)].sort((a, b) => reachBeyond(structure, id, b) - reachBeyond(structure, id, a));
+			for (const next of outward) {
+				if (placed.has(next)) {
+					if (!seen.has(next)) {
+						seen.add(next);
+						queue.push({
+							id: next,
+							incoming: angleOf(placed.get(id), placed.get(next))
+						});
+					}
+					continue;
+				}
+				const direction = !seeded ? DIRECTIONS[flat ? 0 : snap(STEP)] : directionFrom(id, continued ? void 0 : incoming);
+				seeded = true;
+				continued = true;
+				const here = placed.get(id);
+				placed.set(next, {
+					x: here.x + direction.x,
+					y: here.y + direction.y
+				});
+				seen.add(next);
+				queue.push({
+					id: next,
+					incoming: angleOf(here, placed.get(next))
+				});
+				progress = true;
+			}
+		}
+		return progress;
+	};
+	let changed = true;
+	while (changed) {
+		changed = grow();
+		for (const ring of rings.slice(1)) {
+			if (ring.every((id) => placed.has(id))) continue;
+			const anchor = ring.find((id) => placed.has(id));
+			if (anchor === void 0) continue;
+			const here = placed.get(anchor);
+			const away = usedAngles(anchor);
+			const outward = away.length ? away.reduce((a, b) => a + b, 0) / away.length + Math.PI : 0;
+			const radius = 1 / (2 * Math.sin(Math.PI / ring.length));
+			placeRing(ring, {
+				x: here.x + radius * Math.cos(outward),
+				y: here.y + radius * Math.sin(outward)
+			});
+			changed = true;
+		}
+	}
+	const missing = structure.atoms.filter((a) => !placed.has(a.id));
+	if (missing.length) {
+		const right = Math.max(...[...placed.values()].map((p) => p.x), 0) + 2;
+		missing.forEach((atom, i) => placed.set(atom.id, {
+			x: right + i,
+			y: 0
+		}));
+	}
+	return placed;
+}
+/** Put a ring's atoms in bonded order, so a polygon can be walked round. */
+function orderRing(structure, ring) {
+	const inRing = new Set(ring);
+	const ordered = [ring[0]];
+	const seen = new Set(ordered);
+	while (ordered.length < ring.length) {
+		const at = ordered[ordered.length - 1];
+		const next = linked(structure, at).find((n) => inRing.has(n) && !seen.has(n));
+		if (next === void 0) break;
+		seen.add(next);
+		ordered.push(next);
+	}
+	return ordered;
+}
+/** The layout plus everything a figure needs to place it on a page. */
+function layoutOf(structure) {
+	const positions = layout(structure);
+	const xs = [...positions.values()].map((p) => p.x);
+	const ys = [...positions.values()].map((p) => p.y);
+	return {
+		positions,
+		bounds: {
+			minX: Math.min(...xs, 0),
+			minY: Math.min(...ys, 0),
+			maxX: Math.max(...xs, 0),
+			maxY: Math.max(...ys, 0)
+		},
+		rings: ringSystems(structure).map((ring) => orderRing(structure, ring))
+	};
+}
+/** The centre of a ring, for the delocalisation circle. */
+function ringCentre(ring, positions) {
+	const pts = ring.map((id) => positions.get(id)).filter(Boolean);
+	return {
+		x: pts.reduce((s, p) => s + p.x, 0) / pts.length,
+		y: pts.reduce((s, p) => s + p.y, 0) / pts.length
+	};
+}
+/**
+* Several free directions at an atom, for drawing its hydrogens in a displayed formula.
+*
+* Returned widest-gap first and spread apart, so a CH2 puts its two hydrogens on opposite sides
+* rather than side by side where they would touch.
+*/
+function freeDirections(structure, id, positions, count) {
+	const here = positions.get(id);
+	if (!here || count <= 0) return [];
+	const taken = [...linked(structure, id).map((n) => positions.get(n)).filter((p) => Boolean(p)).map((p) => angleOf(here, p))];
+	const out = [];
+	for (let k = 0; k < count; k += 1) {
+		let best = DIRECTIONS[0];
+		let bestGap = -1;
+		for (const d of DIRECTIONS) {
+			const a = Math.atan2(d.y, d.x);
+			const gap = taken.length ? Math.min(...taken.map((u) => Math.abs(Math.atan2(Math.sin(a - u), Math.cos(a - u))))) : Math.PI;
+			if (gap > bestGap) {
+				bestGap = gap;
+				best = d;
+			}
+		}
+		out.push(best);
+		taken.push(Math.atan2(best.y, best.x));
+	}
+	return out;
+}
+/**
+* A free direction at an atom, for drawing an open valence or an implicit-hydrogen label.
+*
+* Returns the lattice direction furthest from every bond the atom already has, which is where a
+* chemist would put it.
+*/
+function freeDirection(structure, id, positions) {
+	const here = positions.get(id);
+	if (!here) return {
+		x: 1,
+		y: 0
+	};
+	const used = linked(structure, id).map((n) => positions.get(n)).filter((p) => Boolean(p)).map((p) => angleOf(here, p));
+	if (used.length === 0) return {
+		x: 1,
+		y: 0
+	};
+	const all = [...positions.values()];
+	const centroidX = all.reduce((sum, p) => sum + p.x, 0) / all.length;
+	const outward = here.x >= centroidX ? {
+		x: 1,
+		y: 0
+	} : {
+		x: -1,
+		y: 0
+	};
+	const outwardAngle = Math.atan2(outward.y, outward.x);
+	if (!used.some((u) => Math.abs(Math.atan2(Math.sin(outwardAngle - u), Math.cos(outwardAngle - u))) < STEP - 1e-6)) return outward;
+	let best = DIRECTIONS[0];
+	let bestGap = -1;
+	for (const d of DIRECTIONS) {
+		const a = Math.atan2(d.y, d.x);
+		const gap = Math.min(...used.map((u) => Math.abs(Math.atan2(Math.sin(a - u), Math.cos(a - u)))));
+		if (gap > bestGap) {
+			bestGap = gap;
+			best = d;
+		}
+	}
+	return best;
+}
+
+//#endregion
+export { freeDirection, freeDirections, layout, layoutOf, ringCentre };

package/dist/chem/lewis.d.mts

@@ -0,0 +1,79 @@
+import { Centre } from "./species.mjs";
+
+//#region src/chem/lewis.d.ts
+/** Valence electrons of an element, from its configuration. */
+declare function valenceElectronsFor(symbol: string): number;
+interface LewisCount {
+  /** Valence electrons of all the atoms, adjusted for the overall charge. */
+  readonly totalValenceElectrons: number;
+  /** Sigma bonds from the central atom, one per ligand atom. */
+  readonly bondingPairs: number;
+  /** Lone pairs left on the central atom. */
+  readonly lonePairs: number;
+  /**
+   * Bonding pairs plus lone pairs: the number of regions of electron density.
+   *
+   * Pi bonds are deliberately NOT counted. A double bond points the same way as the single bond
+   * underneath it, so it is one region, which is why carbon dioxide is linear.
+   */
+  readonly stericNumber: number;
+  /**
+   * Pi bonds formed by pulling a lone pair off an outer atom into the bond.
+   *
+   * Derived rather than guessed. Every pi bond moves the central atom's formal charge one step
+   * toward zero and the donating atom's one step away from it, so they are added while that trade
+   * is an improvement and stopped when it is not. Two guards end the process:
+   *
+   *   the central atom's formal charge reaches zero, so there is nothing left to gain;
+   *   the donor would end up positively charged while being MORE electronegative than the centre,
+   *   which is the situation no real structure adopts.
+   *
+   * That second guard is the whole of the difference between carbon dioxide and boron trifluoride.
+   * Carbon starts at +2 with two oxygens at -1, and two pi bonds take all three to zero. Boron
+   * starts at 0 already, so no pi bond would improve anything, and one would push fluorine, the most
+   * electronegative element there is, to +1.
+   */
+  readonly piBonds: number;
+  /** Bond order to each outer atom, in the order the formula writes them. */
+  readonly bondOrders: readonly {
+    readonly element: string;
+    readonly order: number;
+  }[];
+  /** Electrons around the central atom, pi bonds included. */
+  readonly centralElectrons: number;
+  /**
+   * How many electrons short of an octet the central atom REMAINS once pi bonding has done what it
+   * can.
+   *
+   * Zero for carbon dioxide, which closes its gap completely. Two for boron trifluoride, which
+   * cannot close it at all and is genuinely electron deficient: that is not a limitation of the
+   * calculation, it is the reason boron trifluoride is such a strong Lewis acid.
+   */
+  readonly octetShortfall: number;
+  /**
+   * Formal charge on the central atom in the structure this record describes.
+   *
+   * Worth being precise about, because formal charge belongs to a STRUCTURE and not to a species.
+   * Carbon dioxide drawn with single bonds gives its carbon +2 and drawn with two double bonds gives
+   * it 0, and both are statements about drawings. This is the charge in the pi-bonded structure the
+   * rest of this record describes, which is the one a chemist would draw.
+   */
+  readonly formalCharge: number;
+  /** Whether the central atom can hold more than eight, which needs an accessible d subshell. */
+  readonly canExpand: boolean;
+  /** Set when the count needs more than an octet on an atom that cannot hold one. */
+  readonly impossible?: string;
+}
+/**
+ * Work out the electron budget of a species.
+ *
+ * Returns the count rather than a drawing: where the electrons GO on the page is a layout decision,
+ * and how many there are is chemistry.
+ */
+declare function lewisCount(centre: Centre): LewisCount;
+/** How the central atom's electron count compares with an octet. */
+type OctetStatus = 'short of an octet' | 'an octet' | 'an expanded octet';
+/** Whether the central atom has fewer than eight electrons, eight, or more. */
+declare function octetStatus(count: LewisCount): OctetStatus;
+//#endregion
+export { LewisCount, OctetStatus, lewisCount, octetStatus, valenceElectronsFor };