@classytic/stage 0.2.0 → 0.4.0

package/dist/relation/index.mjs

@@ -0,0 +1,234 @@
+import { evaluate } from "../math/ast.mjs";
+import { parse } from "../math/parse.mjs";
+import { isolate, occurrences } from "../math/rearrange.mjs";
+import { toLatex } from "../math/latex.mjs";
+import { calc, texSigFigs } from "../core/worked.mjs";
+import { Quantity, describeDimension, divDim, isDimensionless, mulDim, parseUnit, powDim, qty, sameDim } from "../quantity/index.mjs";
+import { checkDerivation, deriveValue, explain } from "./derive.mjs";
+
+//#region src/relation/index.ts
+/**
+* relation, a declared equation that can be solved for ANY of its variables and can show its
+* working.
+*
+* ```ts
+* const moles = relation('n = c * V', { n: 'mol', c: 'mol/dm3', V: 'dm3' });
+* moles.solve({ c: 0.100, V: 0.02450 });          // n = 2.45e-3 mol
+* moles.solve({ c: 0.100, V: qty(24.50, 'cm3') }); // the same, titre straight off the burette
+* moles.solve({ n: 2.45e-3, V: 0.02450 });        // c = 0.100 mol/dm3
+* moles.steps({ c: 0.100, V: 0.02450 });          // the substitution, line by line
+* ```
+*
+* ONE DECLARATION, THREE READERS. A lab's model recomputes from it when a slider moves, a lesson's
+* derivation is generated from it, and a checker verifies the lesson against it. Today those are
+* three hand-written copies of the same equation and nothing makes them agree.
+*
+* Two properties do the real work:
+*
+* **Units are checked when the relation is DECLARED, not when it is used.** The check is arithmetic
+* on the dimension vector, never on the spelling, so `V: 'cm3'` and `V: 'dm3'` both balance against
+* `n: 'mol'` and `c: 'mol/dm3'`: they are the same dimension and the factors sort themselves out.
+* What does not balance is refused before a single lesson can be written against it:
+*
+* ```ts
+* relation('n = c + V', { n: 'mol', c: 'mol/dm3', V: 'dm3' });
+* // Error: cannot add mol/m^3 and m^3
+* ```
+*
+* A wrong relation is worse than no relation, because lessons, labs and the checker would then all
+* agree with each other and all be wrong.
+*
+* **Every number in the working came from the caller.** A derivation generated by `.steps()` cannot
+* divide by a mass that is not in the question, because the only values it can substitute are the
+* ones passed in. That is the class of error that shipped into a draft lesson and was caught by
+* reading rather than by any gate.
+*
+* SOLVING IS ISOLATION, NOT ALGEBRA. The unknown must appear exactly once, and the solver peels
+* operations off it one at a time, applying each inverse to the other side. That covers the whole
+* A-level relation table. The moment a relation needs more than that, the scope is wrong and the
+* answer is to declare a second relation. `x` appearing twice is refused with a message that says
+* so, rather than being approximated numerically, because a silent numeric answer to a question the
+* kernel cannot really answer is worse than a refusal.
+*
+* Pure: no React, no pixels.
+*/
+/**
+* The dimension of an expression, given a dimension for each variable.
+*
+* `log`, `log10`, `ln` are the one deliberate deviation from strict dimensional analysis. The
+* logarithm of a dimensioned quantity is not defined, yet pH is *defined* as −log[H⁺] with [H⁺] in
+* mol dm⁻³. Chemistry means "the log of the numeric value in the stated unit", so that is what this
+* implements: the argument may carry a dimension, the result is dimensionless. Refusing it would
+* block every acid-base relation in the syllabus; silently pretending the argument is dimensionless
+* would lose the unit on the way in. Declaring the convention is the honest third option.
+*/
+function dimOf(node, dims, where) {
+	switch (node.type) {
+		case "num": return {};
+		case "var": {
+			const d = dims[node.name];
+			if (!d) throw new Error(`${where}: no unit declared for "${node.name}"`);
+			return d;
+		}
+		case "neg": return dimOf(node.arg, dims, where);
+		case "binary": {
+			const a = dimOf(node.left, dims, where);
+			const b = dimOf(node.right, dims, where);
+			switch (node.op) {
+				case "+":
+				case "-":
+					if (!sameDim(a, b)) throw new Error(`${where}: cannot ${node.op === "+" ? "add" : "subtract"} ${describeDimension(a)} and ${describeDimension(b)}`);
+					return a;
+				case "*": return mulDim(a, b);
+				case "/": return divDim(a, b);
+				case "%": return a;
+				case "^":
+					if (!isDimensionless(b)) throw new Error(`${where}: an exponent must be dimensionless, got ${describeDimension(b)}`);
+					if (node.right.type !== "num") {
+						if (isDimensionless(a)) return {};
+						throw new Error(`${where}: "${toLatex(node.left)}" is raised to a variable power, so its dimension is not fixed. Declare it dimensionless.`);
+					}
+					return powDim(a, node.right.value);
+				default: return a;
+			}
+		}
+		case "call": {
+			const arg = node.args[0] ? dimOf(node.args[0], dims, where) : {};
+			if (node.fn === "log" || node.fn === "log10" || node.fn === "log2" || node.fn === "ln") return {};
+			if (node.fn === "sqrt") return powDim(arg, .5);
+			if (node.fn === "cbrt") return powDim(arg, 1 / 3);
+			if (node.fn === "abs") return arg;
+			if (!isDimensionless(arg)) throw new Error(`${where}: ${node.fn}() needs a dimensionless argument, got ${describeDimension(arg)}`);
+			return {};
+		}
+		default: return {};
+	}
+}
+var Relation = class {
+	equation;
+	title;
+	units;
+	variables;
+	left;
+	right;
+	dims;
+	isolated = /* @__PURE__ */ new Map();
+	constructor(spec) {
+		const halves = spec.equation.split("=");
+		if (halves.length !== 2) throw new Error(`Relation "${spec.equation}" must have exactly one "=".`);
+		this.equation = spec.equation;
+		this.title = spec.title ?? spec.equation;
+		this.units = spec.units;
+		this.left = parse(halves[0]);
+		this.right = parse(halves[1]);
+		this.dims = {};
+		for (const [name, unit] of Object.entries(spec.units)) this.dims[name] = parseUnit(unit).dim;
+		const seen = /* @__PURE__ */ new Set();
+		const walk = (node) => {
+			if (node.type === "var") seen.add(node.name);
+			else if (node.type === "neg") walk(node.arg);
+			else if (node.type === "binary") {
+				walk(node.left);
+				walk(node.right);
+			} else if (node.type === "call") node.args.forEach(walk);
+		};
+		walk(this.left);
+		walk(this.right);
+		for (const name of [
+			"e",
+			"pi",
+			"tau"
+		]) seen.delete(name);
+		this.variables = [...seen];
+		for (const name of this.variables) if (!(name in this.dims)) throw new Error(`Relation "${spec.equation}": no unit declared for "${name}".`);
+		const dl = dimOf(this.left, this.dims, `Relation "${spec.equation}"`);
+		const dr = dimOf(this.right, this.dims, `Relation "${spec.equation}"`);
+		if (!sameDim(dl, dr)) throw new Error(`Relation "${spec.equation}" does not balance: left is ${describeDimension(dl)}, right is ${describeDimension(dr)}.`);
+	}
+	/** The declared unit of a variable. */
+	unitOf(name) {
+		const unit = this.units[name];
+		if (!unit) throw new Error(`"${name}" is not a variable of ${this.equation}`);
+		return unit;
+	}
+	/** Numeric values in declared units, converting any Quantity that was passed in. */
+	normalise(given) {
+		const scope = {};
+		for (const [name, value] of Object.entries(given)) {
+			if (!this.variables.includes(name)) throw new Error(`"${name}" is not a variable of ${this.equation}`);
+			scope[name] = value instanceof Quantity ? value.in(this.unitOf(name)) : value;
+		}
+		return scope;
+	}
+	/** The one variable of the relation that `given` does not supply. */
+	unknownOf(given) {
+		const missing = this.variables.filter((v) => !(v in given));
+		if (missing.length === 0) throw new Error(`Nothing to solve for in ${this.equation}: every variable was given.`);
+		if (missing.length > 1) throw new Error(`${this.equation} has ${missing.length} unknowns (${missing.join(", ")}); exactly one must be left out.`);
+		return missing[0];
+	}
+	expressionFor(target) {
+		const cached = this.isolated.get(target);
+		if (cached) return cached;
+		const count = occurrences(this.left, target) + occurrences(this.right, target);
+		if (count === 0) throw new Error(`"${target}" does not appear in ${this.equation}`);
+		if (count > 1) throw new Error(`Cannot solve ${this.equation} for "${target}": it appears ${count} times, and this kernel isolates rather than does algebra. Declare a second relation that already has "${target}" alone.`);
+		const expr = isolate(this.left, this.right, target);
+		this.isolated.set(target, expr);
+		return expr;
+	}
+	/** Solve for whichever variable was left out of `given`. */
+	solve(given) {
+		const target = this.unknownOf(given);
+		return this.solveFor(target, given);
+	}
+	/** Solve for a named variable, ignoring any value supplied for it. */
+	solveFor(target, given) {
+		const scope = this.normalise(given);
+		delete scope[target];
+		const value = evaluate(this.expressionFor(target), scope);
+		if (!Number.isFinite(value)) throw new Error(`Solving ${this.equation} for "${target}" gave ${value}. Check that every other variable was supplied and is in range.`);
+		const unit = this.unitOf(target);
+		return {
+			name: target,
+			value,
+			unit,
+			quantity: qty(value, unit)
+		};
+	}
+	/**
+	* The worked substitution, for a lesson's derivation.
+	*
+	* Three lines: the relation, the relation rearranged for the unknown, and the substitution with
+	* the answer. Every number shown came from `given`, which is the property that makes a generated
+	* derivation trustworthy in a way a hand-written one is not.
+	*/
+	steps(given, sf = 3) {
+		const target = this.unknownOf(given);
+		const scope = this.normalise(given);
+		const solved = this.solveFor(target, given);
+		const expr = this.expressionFor(target);
+		const w = calc().step(texOf(this.left, this.right), this.title);
+		const rearranged = `${target} = ${toLatex(expr)}`;
+		if (rearranged !== texOf(this.left, this.right)) w.step(rearranged, `rearranged for ${target}`);
+		const subs = this.variables.filter((v) => v !== target).map((v) => `${v} = ${fmt(scope[v], sf)}\\ \\mathrm{${this.unitOf(v)}}`).join(",\\quad ");
+		if (subs) w.step(subs, "the values from the question");
+		w.step(`${target} = ${fmt(solved.value, sf)}\\ \\mathrm{${solved.unit}}`, `to ${sf} significant figures`);
+		return w.done(solved.value);
+	}
+};
+const texOf = (left, right) => `${toLatex(left)} = ${toLatex(right)}`;
+/** Significant figures, without exponent notation for ordinary magnitudes. Shared with every other
+*  kernel that shows working, so two derivations of one quantity cannot round differently. */
+const fmt = (value, sf) => texSigFigs(value, sf);
+const relation = (equation, units, title) => new Relation(title === void 0 ? {
+	equation,
+	units
+} : {
+	equation,
+	units,
+	title
+});
+
+//#endregion
+export { Relation, checkDerivation, deriveValue, explain, relation };

package/dist/scene/Scene.d.mts

@@ -15,6 +15,9 @@ interface SceneProps {
   /** Author opt-in: start a sim running immediately (ambient motion) instead of
    *  the default "press Play". A SceneDoc with no `meta.sims` is always static. */
   autoPlay?: boolean;
+  /** Optional controlled playback for hosts that provide their own transport. */
+  playing?: boolean;
+  onPlayingChange?: (playing: boolean) => void;
 }
 declare function Scene({
   doc,
@@ -25,7 +28,9 @@ declare function Scene({
   height,
   view,
   ariaLabel,
-  autoPlay
+  autoPlay,
+  playing: playingProp,
+  onPlayingChange
 }: SceneProps): ReactNode;
 //#endregion
 export { Scene, SceneProps };

package/dist/scene/Scene.mjs

@@ -45,7 +45,7 @@ function autoView(resolved) {
 		yMax: Math.max(...ys) + pad
 	};
 }
-function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes = true, height, view, ariaLabel = "Interactive figure", autoPlay = false }) {
+function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes = true, height, view, ariaLabel = "Interactive figure", autoPlay = false, playing: playingProp, onPlayingChange }) {
 	const [overlay, setOverlay] = useState(/* @__PURE__ */ new Map());
 	const prevRef = useRef(void 0);
 	const sims = doc.meta?.sims;
@@ -55,14 +55,22 @@ function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes =
 	const [frame, setFrame] = useState(0);
 	const { ref: rootRef, inView } = useInView();
 	const [done, setDone] = useState(false);
-	const [playing, setPlaying] = useState(autoPlay);
+	const [internalPlaying, setInternalPlaying] = useState(autoPlay);
+	const playing = playingProp ?? internalPlaying;
+	const setPlaying = (next) => {
+		if (playingProp === void 0) setInternalPlaying(next);
+		onPlayingChange?.(next);
+	};
 	useFrameLoop((f) => {
 		if (!sims?.length || !simStates.current) return;
 		const next = stepSims(sims, simStates.current, Math.min(.05, f.dtMs / 1e3));
 		simStates.current = next.states;
 		simScalars.current = next.scalars;
 		setFrame((n) => (n + 1) % 1e6);
-		if (next.done) setDone(true);
+		if (next.done) {
+			setDone(true);
+			setPlaying(false);
+		}
 	}, { running: !!sims?.length && inView && playing && !done });
 	const merged = useMemo(() => {
 		const scalars = simScalars.current;
@@ -95,7 +103,7 @@ function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes =
 	const hasSims = !!sims?.length;
 	return /* @__PURE__ */ jsxs("div", {
 		ref: rootRef,
-		style: { position: "relative" },
+		className: "stage-scene",
 		children: [
 			/* @__PURE__ */ jsxs(Stage, {
 				view: v,
@@ -114,30 +122,9 @@ function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes =
 				type: "button",
 				onClick: () => setPlaying(true),
 				"aria-label": "Play simulation",
-				style: {
-					position: "absolute",
-					inset: 0,
-					display: "flex",
-					alignItems: "center",
-					justifyContent: "center",
-					background: "color-mix(in oklab, var(--stage-bg) 38%, transparent)",
-					border: "none",
-					borderRadius: 12,
-					cursor: "pointer"
-				},
+				className: "stage-scene__play-overlay",
 				children: /* @__PURE__ */ jsx("span", {
-					style: {
-						display: "inline-flex",
-						alignItems: "center",
-						gap: 8,
-						padding: "11px 26px",
-						borderRadius: 999,
-						background: "var(--stage-accent)",
-						color: "#fff",
-						fontWeight: 800,
-						fontSize: 16,
-						boxShadow: "0 6px 18px rgba(0,0,0,.28)"
-					},
+					className: "stage-scene__play-label",
 					children: "▶ Play"
 				})
 			}),
@@ -145,19 +132,7 @@ function Scene({ doc, onChange, interactive = true, showGrid = true, showAxes =
 				type: "button",
 				onClick: () => setPlaying(false),
 				"aria-label": "Pause simulation",
-				style: {
-					position: "absolute",
-					top: 10,
-					right: 10,
-					width: 34,
-					height: 34,
-					borderRadius: 999,
-					border: "1px solid var(--stage-grid)",
-					background: "color-mix(in oklab, var(--stage-bg) 80%, transparent)",
-					color: "var(--stage-fg)",
-					cursor: "pointer",
-					fontSize: 13
-				},
+				className: "stage-scene__pause",
 				children: "⏸"
 			})
 		]

package/dist/scene/evaluators.mjs

@@ -1,7 +1,7 @@
 import { vec } from "../core/vec.mjs";
 import { isCircleVal, isLineVal, isVec2, numOf } from "./types.mjs";
 import { getAsset } from "./assets.mjs";
-import { compileExpr } from "../math/index.mjs";
+import { compileExpr } from "../math/expr.mjs";
 
 //#region src/scene/evaluators.ts
 /**

package/dist/sim/thermal.mjs

@@ -1,36 +1,61 @@
+import { MATERIALS } from "../thermo/calorimetry.mjs";
+
 //#region src/sim/thermal.ts
+/**
+* `thermal`, calorimetry: pour heat into a substance and watch its temperature
+* and phase evolve. The one core behind the whole heat-&-temperature module.
+*
+* A substance has a specific heat in EACH phase (solid/liquid/gas) and a latent
+* heat for each transition (fusion at the melting point, vaporisation at the
+* boiling point). Pouring in power P for time dt adds q = P·dt of energy; that
+* energy climbs an ENERGY LADDER of segments:
+*
+*   • heating a phase   → temperature RISES, q = m·c·Δθ   (a sloped run, slope 1/mc)
+*   • a phase change    → temperature is FLAT, q = m·L     (a horizontal plateau)
+*
+* So plotting temperature against heat-added gives the classic heating curve:
+* sloped rises separated by flat plateaus, and the WIDTH of each segment is the
+* heat that part needs. The marker just walks along that fixed curve as energy
+* accumulates. Pure + deterministic (energy is linear in time at constant power),
+* so it replays as video and unit-tests with no DOM. `powerW` lives in state, so a
+* slider can change the heating rate live; flip it negative to cool back down.
+*/
 const clamp01 = (v) => Math.max(0, Math.min(1, v));
+/**
+* Build a `Substance` from the SI material data in `thermo/calorimetry`.
+*
+* This sim works in GRAMS and J/(g·K) because its whole surface does, and
+* changing that would break every lab driving it. The kernel works in kilograms
+* because the rest of physics does. Rather than keep two copies of water's
+* numbers and let them drift, the conversion happens once, here, and the
+* factor of 1000 appears exactly this many times in the package.
+*/
+const fromMaterial = (material, names) => ({
+	name: material.name,
+	...names,
+	cSolid: material.cSolid / 1e3,
+	cLiquid: material.cLiquid / 1e3,
+	cGas: material.cGas / 1e3,
+	lFusion: material.latentFusion / 1e3,
+	lVapor: material.latentVaporisation / 1e3,
+	tMelt: material.meltingPointC,
+	tBoil: material.boilingPointC
+});
 /** Real water, the canonical example (note: latent vaporisation ≫ everything,
 *  so the boiling plateau dwarfs the rest, which is exactly the lesson). */
-const WATER = {
-	name: "Water",
+const WATER = fromMaterial(MATERIALS.water, {
 	solidName: "ice",
 	liquidName: "water",
 	gasName: "steam",
-	cSolid: 2.09,
-	cLiquid: 4.18,
-	cGas: 2.01,
-	lFusion: 334,
-	lVapor: 2260,
-	tMelt: 0,
-	tBoil: 100,
 	color: "var(--stage-accent, #3b82f6)"
-};
+});
 /** Ethanol, lower boiling point, smaller latent heats; a contrasting curve. */
-const ETHANOL = {
-	name: "Ethanol",
+const ETHANOL = fromMaterial(MATERIALS.ethanol, {
 	solidName: "solid",
 	liquidName: "ethanol",
 	gasName: "vapour",
-	cSolid: 1.2,
-	cLiquid: 2.44,
-	cGas: 1.42,
-	lFusion: 108,
-	lVapor: 855,
-	tMelt: -114,
-	tBoil: 78,
 	color: "var(--stage-accent-2, #8b5cf6)"
-};
+});
 /** Build the energy ladder from `tStart` up to `tMax`, including only the phases
 *  reachable heating upward (a liquid start skips the solid+melting runs). */
 function buildSegs(sub, mass, tStart, tMax) {

package/dist/thermo/calorimetry.d.mts

@@ -0,0 +1,207 @@
+//#region src/thermo/calorimetry.d.ts
+/**
+ * Calorimetry: heat in, temperature and phase out.
+ *
+ * THE MODEL. Energy delivered to a body goes into exactly one of two things at
+ * any moment, and which one depends only on whether it is sitting at a
+ * transition temperature:
+ *
+ *   warming a phase    q = m·c·Δθ     temperature rises
+ *   changing phase     q = m·L        temperature is FLAT
+ *
+ * Everything here follows from putting those two in a row. A body's ENTHALPY
+ * LADDER is the alternating sequence of sloped runs and flat plateaus from a
+ * cold datum up to any temperature, and once you have the ladder you can ask
+ * either direction: how much heat to reach this temperature, or what
+ * temperature this much heat reaches.
+ *
+ * THE METHOD, and why it is exact. Total enthalpy H(θ) is piecewise LINEAR in
+ * temperature, with an upward jump of m·L at each transition. So the mixture
+ * problem, find the θ at which the bodies' enthalpies sum to what they started
+ * with, is the inversion of a piecewise-linear monotone function. That is
+ * solved by walking the brackets and doing one division, with no iteration and
+ * no tolerance. Bisection would also work and would be worse: it converges
+ * slowly exactly where the interesting answers are, at the plateaus, because
+ * there the function is flat in the inverse direction.
+ *
+ * This matters because it is what lets the solver answer the question a student
+ * actually cannot do by hand: mix ice below freezing with water above it, and
+ * the outcome is a case analysis (all ice, ice and water at 0 °C, all water)
+ * that the algebra hides. Here it falls out of which bracket the answer lands
+ * in.
+ *
+ * UNITS: SI. Mass in kg, specific heat capacity in J/(kg·K), latent heat in
+ * J/kg, energy in joules. Temperatures are in DEGREES CELSIUS, because every
+ * transition point a lesson names is quoted that way and the differences that
+ * appear in m·c·Δθ are identical in either scale.
+ *
+ * SCOPE. One-dimensional in temperature: no pressure dependence, so the boiling
+ * point is a constant rather than a function of the ambient pressure, and
+ * sublimation is not modelled. Specific heats are constant within a phase.
+ */
+type PhaseName = 'solid' | 'liquid' | 'gas';
+/**
+ * A material, as the four numbers that fix its enthalpy ladder plus the three
+ * specific heats.
+ *
+ * `latentFusion` and `latentVaporisation` are per kilogram, so the plateau
+ * widths scale with mass exactly as the sloped runs do.
+ */
+interface Material {
+  name: string;
+  /** Specific heat capacity in each phase, J/(kg·K). */
+  cSolid: number;
+  cLiquid: number;
+  cGas: number;
+  /** Latent heat of fusion, J/kg. */
+  latentFusion: number;
+  /** Latent heat of vaporisation, J/kg. */
+  latentVaporisation: number;
+  /** Melting point, °C. */
+  meltingPointC: number;
+  /** Boiling point at standard pressure, °C. */
+  boilingPointC: number;
+}
+/**
+ * Materials that appear in the standard problems.
+ *
+ * Water's numbers are worth reading as a set: the latent heat of vaporisation
+ * is 2.26 MJ/kg against 4.18 kJ/(kg·K) for warming, so boiling a kilogram away
+ * costs the same as heating it through 540 °C. That ratio is the whole reason
+ * sweating works and the reason a steam burn is worse than a boiling-water
+ * burn, and it is visible in the table before any lab draws it.
+ */
+declare const MATERIALS: Record<string, Material>;
+/**
+ * Heat to warm a mass through a temperature change: q = m·c·Δθ.
+ *
+ * Δθ is SIGNED, so cooling returns a negative number rather than an absolute
+ * one. That is what makes the mixture bookkeeping add up to zero instead of
+ * needing a hand-placed minus sign on whichever body happened to be hotter.
+ */
+declare function heatToWarmJ(massKg: number, specificHeat: number, deltaT: number): number;
+/** Heat to change the state of a mass at its transition temperature: q = m·L. */
+declare function heatToChangeStateJ(massKg: number, latentHeat: number): number;
+/** The inverse of q = m·c·Δθ, solved for the temperature change. */
+declare function temperatureRiseK(heatJ: number, massKg: number, specificHeat: number): number;
+/** The inverse of q = m·c·Δθ, solved for the specific heat capacity. */
+declare function specificHeatFromJ(heatJ: number, massKg: number, deltaT: number): number;
+/**
+ * The water equivalent of a calorimeter, kg: the mass of water with the same
+ * heat capacity.
+ *
+ * Lets a calorimeter be folded into a mixture as if it were more water, which
+ * is exactly how the textbook method handles it.
+ */
+declare function waterEquivalentKg(massKg: number, specificHeat: number): number;
+/**
+ * The enthalpy of a mass of material at temperature θ, J, measured from a datum
+ * of absolute zero with the material solid.
+ *
+ * The datum is arbitrary and cancels out of every difference, which is the only
+ * reason it is allowed to be as unphysical as "solid water at −273 °C". What
+ * matters is that the SAME datum is used for every body in a mixture.
+ *
+ * At a transition temperature this returns the value approached from BELOW, so
+ * `enthalpyJ(m, water, 0)` is solid ice at 0 °C with none of it melted. The
+ * jump of m·L lives between this value and `enthalpyJ` an epsilon higher, and
+ * the mixture solver resolves partial melting by landing inside that jump
+ * rather than by nudging the temperature.
+ */
+declare function enthalpyJ(massKg: number, material: Material, celsius: number): number;
+/** The phase a material is in at a temperature, taking a transition point as the lower phase. */
+declare function phaseAt(material: Material, celsius: number): PhaseName;
+/** One body entering a mixture. */
+interface MixtureBody {
+  label: string;
+  /** Mass, kg. */
+  massKg: number;
+  material: Material;
+  /** Starting temperature, °C. */
+  temperatureC: number;
+}
+interface MixtureBodyResult {
+  label: string;
+  /** Heat this body GAINED, J. Negative for a body that cooled. */
+  heatGainedJ: number;
+  startPhase: PhaseName;
+  endPhase: PhaseName;
+  /**
+   * How far through a transition the mixture ended, 0..1, or `null` when it did
+   * not settle at a transition temperature.
+   *
+   * This is the answer to "how much of the ice melted", which is the part the
+   * single final temperature cannot tell you: a mixture that settles at 0 °C
+   * with a third of the ice melted and one that settles at 0 °C with all of it
+   * melted have the same final temperature and different contents.
+   *
+   * It is a property of the POOL, not of this body, so every body of the same
+   * material sitting at that temperature reports the same number. That is not a
+   * simplification: ice at 0 °C is ice at 0 °C, and once two lots of it are in
+   * the same beaker there is no fact about which lot a given melted gram came
+   * from. `endPhase` stays at the lower phase while this is between 0 and 1, so
+   * "solid, 0.21" reads as a fifth melted.
+   */
+  transitionFraction: number | null;
+}
+interface MixtureResult {
+  /** The common final temperature, °C. */
+  finalTemperatureC: number;
+  bodies: MixtureBodyResult[];
+  /**
+   * The sum of every body's heat change, J.
+   *
+   * Reported rather than asserted, following the same choice the energy ledger
+   * makes: it must be zero to within rounding, and a caller who wants to prove
+   * that gets to see the number rather than take it on faith.
+   */
+  netHeatJ: number;
+  /** True when at least one body ended part-way through melting or boiling. */
+  partialTransition: boolean;
+}
+/**
+ * The equilibrium temperature of bodies placed in a perfectly insulated
+ * container, and what state each ends in.
+ *
+ * Solves ΣH_i(θ) = ΣH_i(θ_i) exactly, by walking the piecewise-linear total
+ * enthalpy curve bracket by bracket. The brackets are the distinct transition
+ * temperatures of the materials present; inside one, every body is in a fixed
+ * phase and the total is linear, so the crossing point is one division.
+ *
+ * ASSUMES the container itself has no heat capacity. Fold a real calorimeter in
+ * as an extra body, or use `waterEquivalentKg` to express it as more water.
+ */
+declare function mixtureEquilibrium(bodies: readonly MixtureBody[]): MixtureResult;
+/**
+ * The temperature rise when a fraction of a moving body's kinetic energy turns
+ * into heat inside it: f·½mv² = m·c·Δθ.
+ *
+ * The mass cancels, which is the point and the thing students are surprised by:
+ * a bullet's temperature rise on impact depends on its SPEED and its material,
+ * not on how big it is. `fraction` is how much of the energy stays in the body
+ * rather than going into the target, the air, or sound.
+ */
+declare function temperatureRiseFromSpeedK(speedMs: number, specificHeat: number, fraction?: number): number;
+/**
+ * The temperature rise when a fraction of a falling body's potential energy
+ * turns into heat inside it: f·mgh = m·c·Δθ.
+ *
+ * The mass cancels here too, so the answer depends only on the DROP. This is
+ * Joule's paddle-wheel experiment read backwards, and the classic worked
+ * example is the waterfall: the 4.2 kJ it takes to warm a kilogram of water by
+ * one degree is the same energy as dropping it 428 m.
+ */
+declare function temperatureRiseFromDropK(heightM: number, specificHeat: number, fraction?: number, gravity?: number): number;
+/**
+ * The mass melted when a fraction of a falling body's potential energy becomes
+ * heat in it: f·mgh = m'·L.
+ *
+ * Unlike the two above, this one keeps the mass, because the answer is a mass.
+ */
+declare function massMeltedFromDropKg(massKg: number, heightM: number, latentHeat: number, fraction?: number, gravity?: number): number;
+/** Calories to joules, through the thermochemical definition. */
+declare const caloriesToJoules: (calories: number) => number;
+/** Joules to calories, through the thermochemical definition. */
+declare const joulesToCalories: (joules: number) => number;
+//#endregion
+export { MATERIALS, Material, MixtureBody, MixtureBodyResult, MixtureResult, PhaseName, caloriesToJoules, enthalpyJ, heatToChangeStateJ, heatToWarmJ, joulesToCalories, massMeltedFromDropKg, mixtureEquilibrium, phaseAt, specificHeatFromJ, temperatureRiseFromDropK, temperatureRiseFromSpeedK, temperatureRiseK, waterEquivalentKg };