@classytic/stage 0.2.0 → 0.4.0

package/dist/physics/kinematics/equations.mjs

@@ -0,0 +1,126 @@
+import { relation } from "../../relation/index.mjs";
+
+//#region src/physics/kinematics/equations.ts
+/**
+* The five SUVAT equations, declared once with their units.
+*
+* This file is the single source of truth for what the equations ARE. Everything else in this
+* directory reads them: the chooser picks one, the solver rearranges one, the derivation prints
+* one. Nothing rewrites them, which is the property that stops a second, subtly different copy of
+* `s = ut + ½at²` appearing somewhere and being wrong in a way that looks right.
+*/
+const MOTION_VARS = [
+	"u",
+	"v",
+	"a",
+	"s",
+	"t"
+];
+/** What each symbol means, for a lesson that lists them and for error messages that name them. */
+const MOTION_NAMES = {
+	u: "initial velocity",
+	v: "final velocity",
+	a: "acceleration",
+	s: "displacement",
+	t: "time"
+};
+/**
+* The unit each quantity is held in, spelled for the UNIT PARSER.
+*
+* These strings are machine input, not display text. `m/s^2` is how `parseUnit` reads metres per
+* second squared; it is not how a physics paper prints it, and putting it on screen is how a
+* derivation ends up with a stray caret in it.
+*/
+const MOTION_UNITS = {
+	u: "m/s",
+	v: "m/s",
+	a: "m/s^2",
+	s: "m",
+	t: "s"
+};
+/**
+* The same units spelled for DISPLAY, as LaTeX.
+*
+* Index notation (`m s⁻²`) rather than a solidus, because that is the convention in every physics
+* paper these students will sit, and upright roman rather than italic, because an italic `m` is a
+* variable and an upright one is metres. The thin space between the symbols is not decoration: it
+* is what distinguishes `m s` (metre-seconds) from `ms` (milliseconds).
+*/
+const MOTION_UNITS_TEX = {
+	u: "\\mathrm{m\\,s^{-1}}",
+	v: "\\mathrm{m\\,s^{-1}}",
+	a: "\\mathrm{m\\,s^{-2}}",
+	s: "\\mathrm{m}",
+	t: "\\mathrm{s}"
+};
+const units = MOTION_UNITS;
+/**
+* The five equations.
+*
+* `s = vt − ½at²` is the one most textbooks omit, and then they have to fudge every question that
+* gives the FINAL velocity and asks for the displacement. It is included for the same reason the
+* other four are: leaving it out would mean one of the five choices has no equation behind it, and
+* the method would stop being reliable exactly once per chapter.
+*/
+const MOTION_EQUATIONS = [
+	{
+		id: "v=u+at",
+		relation: relation("v = u + a*t", {
+			v: units.v,
+			u: units.u,
+			a: units.a,
+			t: units.t
+		}, "v = u + at"),
+		omits: "s",
+		quadraticInTime: false
+	},
+	{
+		id: "s=(u+v)t/2",
+		relation: relation("s = 0.5*(u + v)*t", {
+			s: units.s,
+			u: units.u,
+			v: units.v,
+			t: units.t
+		}, "s = \\tfrac{1}{2}(u + v)t"),
+		omits: "a",
+		quadraticInTime: false
+	},
+	{
+		id: "s=ut+at^2/2",
+		relation: relation("s = u*t + 0.5*a*t^2", {
+			s: units.s,
+			u: units.u,
+			a: units.a,
+			t: units.t
+		}, "s = ut + \\tfrac{1}{2}at^2"),
+		omits: "v",
+		quadraticInTime: true
+	},
+	{
+		id: "v^2=u^2+2as",
+		relation: relation("v^2 = u^2 + 2*a*s", {
+			v: units.v,
+			u: units.u,
+			a: units.a,
+			s: units.s
+		}, "v^2 = u^2 + 2as"),
+		omits: "t",
+		quadraticInTime: false
+	},
+	{
+		id: "s=vt-at^2/2",
+		relation: relation("s = v*t - 0.5*a*t^2", {
+			s: units.s,
+			v: units.v,
+			a: units.a,
+			t: units.t
+		}, "s = vt - \\tfrac{1}{2}at^2"),
+		omits: "u",
+		quadraticInTime: true
+	}
+];
+/** The equation that leaves out a given quantity. Exactly one does, which is the whole method. */
+const equationWithout = (omitted) => MOTION_EQUATIONS.find((e) => e.omits === omitted);
+
+//#endregion
+export { MOTION_EQUATIONS, MOTION_NAMES, MOTION_UNITS, MOTION_UNITS_TEX, MOTION_VARS, equationWithout };

package/dist/physics/kinematics/free-fall.d.mts

@@ -0,0 +1,53 @@
+import { SignConvention } from "../vectors.mjs";
+import { MotionGiven } from "./given.mjs";
+
+//#region src/physics/kinematics/free-fall.d.ts
+declare const G_EARTH = 9.8;
+interface VerticalMotion {
+  /**
+   * Initial speed as a MAGNITUDE, always positive. Which way it goes is `direction`, not a sign:
+   * asking a caller to pre-sign this is asking them to do the step that goes wrong.
+   */
+  readonly speed?: number;
+  /** Which way it was launched. Omit `speed` or pass 0 for a body simply released. */
+  readonly direction?: 'up' | 'down';
+  /**
+   * How far the landing point is BELOW the launch point, as a positive distance. A stone thrown
+   * from a 58.8 m tower that lands at the foot has `fallsBy: 58.8`; one that returns to the hand
+   * has `fallsBy: 0`.
+   */
+  readonly fallsBy?: number;
+  readonly g?: number;
+  /** Which direction the resulting numbers call positive. Defaults to up, the usual choice. */
+  readonly convention?: SignConvention;
+}
+/**
+ * The signed `u`, `a` and `s` for a vertical motion, ready for {@link motion}.
+ *
+ * ```ts
+ * // Reference example 18: thrown up at 19.6 m/s from a 58.8 m tower.
+ * motion('t', vertical({ speed: 19.6, direction: 'up', fallsBy: 58.8 }));   // 6 s
+ * // The same flight described the other way up. Same answer.
+ * motion('t', vertical({ speed: 19.6, direction: 'up', fallsBy: 58.8, convention: downPositive() }));
+ * ```
+ */
+declare function vertical(m: VerticalMotion): MotionGiven & {
+  u: number;
+  a: number;
+  s: number;
+};
+/** A body simply released from rest, falling `distance` metres. */
+declare const dropped: (distance: number, g?: number) => MotionGiven & {
+  u: number;
+  a: number;
+  s: number;
+};
+/**
+ * A sentence describing the signs, for a lesson to print above the working.
+ *
+ * Saying this out loud once is worth more than any number of remembered formula variants, because
+ * it is the only step a learner has to get right before the equations take over.
+ */
+declare function describeSigns(m: VerticalMotion): string;
+//#endregion
+export { G_EARTH, VerticalMotion, describeSigns, dropped, vertical };

package/dist/physics/kinematics/free-fall.mjs

@@ -0,0 +1,71 @@
+import { upPositive } from "../vectors.mjs";
+
+//#region src/physics/kinematics/free-fall.ts
+/**
+* Vertical motion under gravity: turning a sentence into signed numbers.
+*
+* THERE ARE NO FREE-FALL EQUATIONS. There is SUVAT with `a = ±g`, and the only new thing a falling
+* body brings is the question of which sign, which is a question about how you chose to describe
+* the motion rather than about the motion.
+*
+* This matters because it is where textbooks multiply. A typical chapter prints three sets:
+*
+*     falling:                    v = u + gt,    h = ut + ½gt²
+*     thrown upwards:             v = u − gt,    h = ut − ½gt²
+*     thrown up, landing below:   v = −u + gt,   h = −ut + ½gt²
+*
+* Those are one equation written three times with the signs pre-substituted, and a student is
+* expected to remember which is which. They are all `s = ut + ½at²`. The third is simply the first
+* with down chosen as positive, so an upward launch makes `u` negative. Memorising three is harder
+* than understanding one AND it fails on the fourth case, the one the chapter did not print.
+*
+* So what this module provides is not equations. It is the TRANSLATION: a description in words
+* becomes the signed `u`, `a` and `s` that the one equation set needs, done once, visibly, and in a
+* way that can be flipped to the other convention to show the answer does not depend on it.
+*/
+const G_EARTH = 9.8;
+/**
+* The signed `u`, `a` and `s` for a vertical motion, ready for {@link motion}.
+*
+* ```ts
+* // Reference example 18: thrown up at 19.6 m/s from a 58.8 m tower.
+* motion('t', vertical({ speed: 19.6, direction: 'up', fallsBy: 58.8 }));   // 6 s
+* // The same flight described the other way up. Same answer.
+* motion('t', vertical({ speed: 19.6, direction: 'up', fallsBy: 58.8, convention: downPositive() }));
+* ```
+*/
+function vertical(m) {
+	const convention = m.convention ?? upPositive();
+	const g = m.g ?? 9.8;
+	const speed = m.speed ?? 0;
+	const direction = m.direction ?? "down";
+	return {
+		u: speed === 0 ? 0 : convention.signed(speed, direction),
+		a: convention.gravity(g),
+		s: convention.signed(m.fallsBy ?? 0, "down")
+	};
+}
+/** A body simply released from rest, falling `distance` metres. */
+const dropped = (distance, g = G_EARTH) => vertical({
+	fallsBy: distance,
+	g
+});
+/**
+* A sentence describing the signs, for a lesson to print above the working.
+*
+* Saying this out loud once is worth more than any number of remembered formula variants, because
+* it is the only step a learner has to get right before the equations take over.
+*/
+function describeSigns(m) {
+	const convention = m.convention ?? upPositive();
+	const g = m.g ?? 9.8;
+	const signed = vertical(m);
+	const parts = [`Taking ${convention.positive} as positive`];
+	if (signed.u !== 0) parts.push(`it is thrown ${m.direction ?? "down"}, so u = ${signed.u} m/s`);
+	parts.push(`gravity acts down, so a = ${convention.gravity(g)} m/s²`);
+	if (signed.s !== 0) parts.push(`and it ends ${Math.abs(m.fallsBy ?? 0)} m below the start, so s = ${signed.s} m`);
+	return `${parts.join(", ")}.`;
+}
+
+//#endregion
+export { G_EARTH, describeSigns, dropped, vertical };

package/dist/physics/kinematics/given.d.mts

@@ -0,0 +1,16 @@
+import { Given } from "../../relation/index.mjs";
+import { MotionEquation, MotionVar } from "./equations.mjs";
+
+//#region src/physics/kinematics/given.d.ts
+/** Values supplied to the solver: bare numbers in SI, or quantities in any compatible unit. */
+type MotionGiven = Partial<Record<MotionVar, Given>>;
+/**
+ * Which equation answers this question, and why.
+ *
+ * Throws with a message naming what is still needed, rather than guessing or returning null. A
+ * learner who has given two quantities has not made a type error, they have not finished reading
+ * the question, and the message should say which quantity is missing.
+ */
+declare function chooseEquation(target: MotionVar, given: MotionGiven): MotionEquation;
+//#endregion
+export { MotionGiven, chooseEquation };

package/dist/physics/kinematics/given.mjs

@@ -0,0 +1,55 @@
+import { Quantity } from "../../quantity/index.mjs";
+import { MOTION_EQUATIONS, MOTION_NAMES, MOTION_UNITS, MOTION_VARS, equationWithout } from "./equations.mjs";
+
+//#region src/physics/kinematics/given.ts
+/**
+* What the caller supplied, and choosing the equation that fits it.
+*
+* The chooser is the part worth reading. Five quantities, four in every equation, so there is
+* exactly one equation that omits any given quantity, and the choice is therefore forced rather
+* than a matter of taste:
+*
+*   list what you know, name what you want, and use the equation that leaves out the one
+*   quantity you neither know nor want.
+*
+* It is exported on its own because the choice is worth asking a learner to make before the answer
+* is revealed. "Which equation would you use?" is a much better question than "what is the answer",
+* and it is the one a static page of worked examples can never ask.
+*/
+const isGiven = (given, key) => given[key] !== void 0 && given[key] !== null;
+/** The supplied values as plain SI numbers, so they can be substituted and printed. */
+function normalise(given) {
+	const out = {};
+	for (const key of MOTION_VARS) {
+		const raw = given[key];
+		if (raw === void 0 || raw === null) continue;
+		out[key] = raw instanceof Quantity ? raw.in(MOTION_UNITS[key]) : raw;
+	}
+	return out;
+}
+/**
+* Which equation answers this question, and why.
+*
+* Throws with a message naming what is still needed, rather than guessing or returning null. A
+* learner who has given two quantities has not made a type error, they have not finished reading
+* the question, and the message should say which quantity is missing.
+*/
+function chooseEquation(target, given) {
+	const known = MOTION_VARS.filter((key) => key !== target && isGiven(given, key));
+	if (known.length < 3) {
+		const missing = MOTION_VARS.filter((key) => key !== target && !isGiven(given, key));
+		throw new Error(`To find ${MOTION_NAMES[target]} (${target}) you need three of the other four quantities; ${known.length === 0 ? "none were" : `only ${known.join(", ")} ${known.length === 1 ? "was" : "were"}`} given. Still needed: any ${3 - known.length} of ${missing.join(", ")}.`);
+	}
+	const absent = MOTION_VARS.filter((key) => key !== target && !isGiven(given, key));
+	if (absent.length === 1) {
+		const equation = equationWithout(absent[0]);
+		if (equation) return equation;
+	}
+	const candidates = MOTION_EQUATIONS.filter((e) => e.omits !== target && e.relation.variables.every((v) => v === target || isGiven(given, v)));
+	const chosen = candidates.find((e) => !(e.quadraticInTime && target === "t")) ?? candidates[0];
+	if (!chosen) throw new Error(`No SUVAT equation relates ${target} to the quantities given.`);
+	return chosen;
+}
+
+//#endregion
+export { chooseEquation, isGiven, normalise };

package/dist/physics/kinematics/roots.d.mts

@@ -0,0 +1,41 @@
+//#region src/physics/kinematics/roots.d.ts
+/**
+ * Candidate answers, and the argument for keeping or discarding each.
+ *
+ * A quadratic gives two times and a square root gives two speeds, and in both cases the extra
+ * answer is not noise to be filtered out. Which one you keep, and why, is the actual physics: the
+ * mathematics is finished and cannot decide it. So a root travels with its reason attached, and a
+ * discarded root is still returned so that a lesson can show the discarding rather than a solver
+ * doing it silently offstage.
+ */
+/** One candidate value, and whether physics accepts it. */
+interface Root {
+  readonly value: number;
+  /** A rejected root is still reported: the rejection is the lesson. */
+  readonly accepted: boolean;
+  /** Why it was accepted or rejected, in a sentence a learner reads. */
+  readonly reason: string;
+}
+/** Times smaller than this are the launch instant, not a distinct moment. */
+declare const TIME_EPSILON = 1e-12;
+/**
+ * Judge one root of the time quadratic.
+ *
+ * Three outcomes, not two. A negative time is before the stopwatch started and goes. A positive
+ * time stands. Zero is the awkward one: it is real, it is correct, and it is never the answer
+ * anybody wanted, because a stone thrown from the ground genuinely IS at ground level at t = 0.
+ * Textbooks deal with that by not mentioning it, which leaves a student who solves it by hand
+ * holding a root nobody told them about.
+ */
+declare function classifyTime(value: number): Root;
+/** The pair of speeds a square root leaves behind, when the sign is genuinely undetermined. */
+declare function speedRoots(magnitude: number): readonly Root[];
+/**
+ * Which root to report as THE answer.
+ *
+ * The first one strictly after the start. On level ground `s = 0` has roots 0 and T, and returning
+ * the launch instant as the time of flight is correct arithmetic and a useless answer.
+ */
+declare const preferredTime: (accepted: readonly Root[]) => Root | undefined;
+//#endregion
+export { Root, TIME_EPSILON, classifyTime, preferredTime, speedRoots };

package/dist/physics/kinematics/roots.mjs

@@ -0,0 +1,72 @@
+import { texSigFigs } from "../../core/worked.mjs";
+
+//#region src/physics/kinematics/roots.ts
+/**
+* Candidate answers, and the argument for keeping or discarding each.
+*
+* A quadratic gives two times and a square root gives two speeds, and in both cases the extra
+* answer is not noise to be filtered out. Which one you keep, and why, is the actual physics: the
+* mathematics is finished and cannot decide it. So a root travels with its reason attached, and a
+* discarded root is still returned so that a lesson can show the discarding rather than a solver
+* doing it silently offstage.
+*/
+/** Times smaller than this are the launch instant, not a distinct moment. */
+const TIME_EPSILON = 1e-12;
+/**
+* Judge one root of the time quadratic.
+*
+* Three outcomes, not two. A negative time is before the stopwatch started and goes. A positive
+* time stands. Zero is the awkward one: it is real, it is correct, and it is never the answer
+* anybody wanted, because a stone thrown from the ground genuinely IS at ground level at t = 0.
+* Textbooks deal with that by not mentioning it, which leaves a student who solves it by hand
+* holding a root nobody told them about.
+*/
+function classifyTime(value) {
+	if (value < 0) return {
+		value,
+		accepted: false,
+		reason: "negative, so it is a time before the motion started. Reject it."
+	};
+	if (value <= 1e-12) return {
+		value: 0,
+		accepted: true,
+		reason: "the launch instant itself: it starts at this displacement, so t = 0 solves the equation."
+	};
+	return {
+		value,
+		accepted: true,
+		reason: "positive, so it is a time after the motion started."
+	};
+}
+/** The pair of speeds a square root leaves behind, when the sign is genuinely undetermined. */
+function speedRoots(magnitude) {
+	return [{
+		value: magnitude,
+		accepted: true,
+		reason: "moving in the positive direction."
+	}, {
+		value: -magnitude,
+		accepted: true,
+		reason: "the same speed in the negative direction. Choose using the direction of travel, which the equation cannot know."
+	}];
+}
+/**
+* Which root to report as THE answer.
+*
+* The first one strictly after the start. On level ground `s = 0` has roots 0 and T, and returning
+* the launch instant as the time of flight is correct arithmetic and a useless answer.
+*/
+const preferredTime = (accepted) => accepted.find((r) => r.value > 1e-12) ?? accepted[0];
+/**
+* What to say about a pair of roots. Three genuinely different situations, and calling them all
+* "take the positive one" is how students end up discarding a root that was the answer.
+*/
+function rootNote(roots, sf) {
+	const rejected = roots.find((r) => !r.accepted);
+	if (rejected) return `${texSigFigs(rejected.value, sf)} s is before the motion started, so reject it`;
+	if (roots.some((r) => r.value === 0)) return "one root is the launch itself, at t = 0; the other is when it comes back to that level";
+	return "both times are real: the body is at this displacement twice, once on the way up and once coming down";
+}
+
+//#endregion
+export { TIME_EPSILON, classifyTime, preferredTime, rootNote, speedRoots };

package/dist/physics/kinematics/solve.d.mts

@@ -0,0 +1,52 @@
+import { Quantity } from "../../quantity/index.mjs";
+import { Worked } from "../../core/worked.mjs";
+import { MotionEquation, MotionVar } from "./equations.mjs";
+import { MotionGiven } from "./given.mjs";
+import { Root } from "./roots.mjs";
+
+//#region src/physics/kinematics/solve.d.ts
+interface MotionSolution {
+  readonly target: MotionVar;
+  /** The answer, in SI. When several roots are accepted this is the first one in time. */
+  readonly value: number;
+  readonly unit: string;
+  readonly quantity: Quantity;
+  /** The equation used: the reasoning, not just the result. */
+  readonly equation: MotionEquation;
+  /** The quantity that was neither known nor wanted, which is what selected the equation. */
+  readonly excluded: MotionVar;
+  /**
+   * Every candidate the mathematics produced, accepted and rejected, when the step was a quadratic
+   * or a square root. Absent when the solve was a plain rearrangement with one answer.
+   */
+  readonly roots?: readonly Root[];
+  /** The derivation, ready for a RuleCard or a lesson. */
+  readonly worked: Worked;
+}
+/**
+ * Solve for one quantity of a straight-line motion at constant acceleration.
+ *
+ * ```ts
+ * motion('t', { u: 19.6, a: -9.8, s: -58.8 });   // t = 6 s, and −2 s reported as rejected
+ * motion('v', { u: 0, a: 9.8, s: 45.9 });        // v = 30 m/s, with −30 reported as the other way
+ * motion('s', { u: qty(72, 'km/h'), a: -2, t: 5 });
+ * ```
+ */
+declare function motion(target: MotionVar, given: MotionGiven, sf?: number): MotionSolution;
+/**
+ * Every time at which the body is at displacement `s`.
+ *
+ * The direct form of the quadratic case, for a caller that wants the pair rather than one answer:
+ * "when is the stone 10 m up?" has two honest answers, and a lab that draws both is teaching
+ * something a lab that draws one is not.
+ */
+declare const timeToReach: (s: number | Quantity, given: Omit<MotionGiven, "s" | "t">, sf?: number) => readonly Root[];
+/**
+ * Fill in every quantity that follows from the ones given.
+ *
+ * For a lab's model: move a slider, get the whole consistent picture back, each entry carrying the
+ * derivation that produced it.
+ */
+declare function motionTable(given: MotionGiven, sf?: number): Partial<Record<MotionVar, MotionSolution>>;
+//#endregion
+export { MotionSolution, motion, motionTable, timeToReach };

package/dist/physics/kinematics/solve.mjs

@@ -0,0 +1,172 @@
+import { parse } from "../../math/parse.mjs";
+import { solvePoly } from "../../math/solve.mjs";
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { qty } from "../../quantity/index.mjs";
+import { MOTION_UNITS, MOTION_UNITS_TEX, MOTION_VARS } from "./equations.mjs";
+import { chooseEquation, isGiven, normalise } from "./given.mjs";
+import { classifyTime, preferredTime, rootNote, speedRoots } from "./roots.mjs";
+
+//#region src/physics/kinematics/solve.ts
+/**
+* Solving one quantity out of a straight-line motion, and showing the working.
+*
+* Three paths, because three genuinely different things can happen once the equation is chosen:
+*
+*   - a plain rearrangement, which `relation` does and which has one answer;
+*   - a QUADRATIC, when `t` is wanted from `s = ut + ½at²`, which has two roots that are not
+*     interchangeable;
+*   - a SQUARE ROOT, when a speed is wanted from `v² = u² + 2as`, where the magnitude is settled
+*     and the direction is not, because squaring threw it away.
+*
+* The second and third are where marks are lost, and they are the reason this is a kernel rather
+* than five lines of arithmetic. Neither is allowed to quietly pick an answer.
+*/
+/** `u = 20\ \mathrm{m\,s^{-1}}`, for the substitution line. */
+const sub = (key, value, sf) => `${key} = ${texSigFigs(value, sf)}\\ ${MOTION_UNITS_TEX[key]}`;
+const substitutionLine = (equation, target, values, sf) => MOTION_VARS.filter((v) => v !== target && equation.relation.variables.includes(v)).map((v) => sub(v, values[v], sf)).join(",\\quad ");
+const answerLine = (target, value, sf) => `${target} = ${texSigFigs(value, sf)}\\ ${MOTION_UNITS_TEX[target]}`;
+const finish = (target, value, equation, worked, roots) => ({
+	target,
+	value,
+	unit: MOTION_UNITS[target],
+	quantity: qty(value, MOTION_UNITS[target]),
+	equation,
+	excluded: equation.omits,
+	...roots ? { roots } : {},
+	worked
+});
+/**
+* Solve for one quantity of a straight-line motion at constant acceleration.
+*
+* ```ts
+* motion('t', { u: 19.6, a: -9.8, s: -58.8 });   // t = 6 s, and −2 s reported as rejected
+* motion('v', { u: 0, a: 9.8, s: 45.9 });        // v = 30 m/s, with −30 reported as the other way
+* motion('s', { u: qty(72, 'km/h'), a: -2, t: 5 });
+* ```
+*/
+function motion(target, given, sf = 3) {
+	const equation = chooseEquation(target, given);
+	const values = normalise(given);
+	const knowns = MOTION_VARS.filter((v) => v !== target && equation.relation.variables.includes(v));
+	const w = calc().step(equation.relation.title, `you know ${knowns.join(", ")} and want ${target}, so use the equation without ${equation.omits}`);
+	if (equation.quadraticInTime && target === "t") return quadraticTime(equation, values, sf, w);
+	if (equation.omits === "t" && (target === "u" || target === "v")) return rootedSpeed(equation, target, values, sf, w);
+	const scoped = {};
+	for (const v of equation.relation.variables) if (v !== target) scoped[v] = values[v];
+	const solved = equation.relation.solveFor(target, scoped);
+	w.step(substitutionLine(equation, target, values, sf), "the values from the question");
+	w.step(answerLine(target, solved.value, sf), `to ${sf} significant figures`);
+	return finish(target, solved.value, equation, w.done(solved.value));
+}
+/**
+* The two roots of `a t² + b t + c = 0`, from the closed form, in the numerically stable arrangement.
+*
+* WHY NOT THE GENERAL ROOT FINDER. The polynomial solver behind `solvePoly` is Durand-Kerner, which
+* is iterative and converges to about ten significant figures. That is ample for a printed answer
+* and it was quietly wrong for two other reasons. The first is honesty: the derivation prints
+* `t = (-b ± √(b² − 4ac)) / 2a`, so the number beside it should be what that expression gives, not
+* what an iteration happened to land on. The second is that callers integrate against these times.
+* A landing time out by 4e-10 is invisible in a lesson and is a real error in an animation loop
+* that differences it.
+*
+* The arrangement matters as much as the formula. Computing both roots as `(-b ± √disc) / 2a` loses
+* most of the significant figures of the smaller root whenever `b² >> 4ac`, because one of the two
+* is then a subtraction of nearly equal numbers. Forming `q` with the sign of `b` makes that branch
+* an addition, and the other root comes from `c / q` instead, where nothing cancels.
+*/
+function quadraticRoots(a, b, c) {
+	const disc = b * b - 4 * a * c;
+	if (disc < 0) return [];
+	const sq = Math.sqrt(disc);
+	if (sq === 0) return [-b / (2 * a)];
+	const q = -.5 * (b + (b >= 0 ? sq : -sq));
+	return [q / a, c / q].sort((x, y) => x - y);
+}
+/**
+* `s = ut + ½at²` solved for `t`.
+*
+* The coefficients are read off the DECLARED equation rather than written out again here. A second
+* hand-written copy of the same equation is exactly the thing that drifts, and the drift would be
+* invisible, because both copies would still look like the formula.
+*/
+function quadraticTime(equation, values, sf, w) {
+	const [lhs, rhs] = equation.relation.equation.split("=");
+	const params = {};
+	for (const v of equation.relation.variables) if (v !== "t") params[v] = values[v];
+	const solution = solvePoly(parse(`(${rhs}) - (${lhs})`), "t", params);
+	if (!solution) throw new Error(`Could not read ${equation.relation.equation} as a polynomial in t.`);
+	w.step(substitutionLine(equation, "t", values, sf), "the values from the question");
+	if (solution.degree < 2) {
+		const [k0, k1] = solution.coeffs;
+		const only = k1 === void 0 || k1 === 0 ? solution.realRoots[0] : -k0 / k1;
+		if (only === void 0 || !Number.isFinite(only)) throw new Error("With a = 0 and this displacement there is no time that satisfies the motion.");
+		w.step(answerLine("t", only, sf), "a = 0, so the equation is linear in t");
+		return finish("t", only, equation, w.done(only), [{
+			value: only,
+			accepted: true,
+			reason: "the acceleration is zero, so there is one time."
+		}]);
+	}
+	const [c0, c1, c2] = solution.coeffs;
+	w.step(`${texSigFigs(c2, sf)}t^2 + ${texSigFigs(c1, sf)}t + ${texSigFigs(c0, sf)} = 0`, "rearranged: this is a quadratic in t, not a rearrangement");
+	const disc = solution.discriminant ?? c1 * c1 - 4 * c2 * c0;
+	if (disc < 0) throw new Error(`The body never reaches s = ${values.s} m. Solving gives a negative discriminant (${disc.toPrecision(3)}), so no real time satisfies the motion. Check the sign convention, or the displacement is genuinely out of reach.`);
+	w.step("t = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}", "two roots, and they are not interchangeable");
+	const exact = quadraticRoots(c2, c1, c0);
+	const roots = exact.map(classifyTime);
+	const accepted = roots.filter((r) => r.accepted);
+	if (accepted.length === 0) throw new Error(`Both roots are negative (${exact.map((r) => r.toPrecision(3)).join(", ")} s), so the body was never at this displacement after t = 0. The sign convention is the usual cause.`);
+	w.step(roots.map((r) => answerLine("t", r.value, sf)).join(",\\quad "), rootNote(roots, sf));
+	const chosen = preferredTime(accepted);
+	w.step(answerLine("t", chosen.value, sf), `to ${sf} significant figures`);
+	return finish("t", chosen.value, equation, w.done(chosen.value), roots);
+}
+/**
+* `v² = u² + 2as` solved for a speed.
+*
+* Squaring destroyed the direction, so the equation genuinely cannot say which sign is meant, and a
+* solver that silently returns the positive root teaches a student to lose a mark on every question
+* where the body is coming back down. Both are returned; choosing between them needs something the
+* equation does not contain.
+*/
+function rootedSpeed(equation, target, values, sf, w) {
+	const other = target === "v" ? "u" : "v";
+	const square = values[other] * values[other] + 2 * values.a * values.s;
+	w.step(substitutionLine(equation, target, values, sf), "the values from the question");
+	w.step(`${target}^2 = ${texSigFigs(square, sf)}\\ \\mathrm{m^2\\,s^{-2}}`);
+	if (square < 0) throw new Error(`${target}² works out negative (${square.toPrecision(3)}), so the body never reaches s = ${values.s} m. It stops and turns back first.`);
+	const magnitude = Math.sqrt(square);
+	w.step(`${target} = \\pm${texSigFigs(magnitude, sf)}\\ ${MOTION_UNITS_TEX[target]}`, "squaring lost the direction, so both signs solve the equation");
+	w.step(answerLine(target, magnitude, sf), `to ${sf} significant figures, taking the positive direction`);
+	return finish(target, magnitude, equation, w.done(magnitude), speedRoots(magnitude));
+}
+/**
+* Every time at which the body is at displacement `s`.
+*
+* The direct form of the quadratic case, for a caller that wants the pair rather than one answer:
+* "when is the stone 10 m up?" has two honest answers, and a lab that draws both is teaching
+* something a lab that draws one is not.
+*/
+const timeToReach = (s, given, sf = 3) => motion("t", {
+	...given,
+	s
+}, sf).roots ?? [];
+/**
+* Fill in every quantity that follows from the ones given.
+*
+* For a lab's model: move a slider, get the whole consistent picture back, each entry carrying the
+* derivation that produced it.
+*/
+function motionTable(given, sf = 3) {
+	const out = {};
+	for (const target of MOTION_VARS) {
+		if (isGiven(given, target)) continue;
+		try {
+			out[target] = motion(target, given, sf);
+		} catch {}
+	}
+	return out;
+}
+
+//#endregion
+export { motion, motionTable, timeToReach };