@classytic/stage 0.3.0 → 0.4.0

package/dist/physics/energy/work.d.mts

@@ -0,0 +1,114 @@
+import { Worked } from "../../core/worked.mjs";
+
+//#region src/physics/energy/work.d.ts
+/**
+ * Scalar or vector, with the REASON attached.
+ *
+ * This table exists because the confusion it settles is a reliable source of lost marks and is never
+ * addressed head-on: a student who can recite "work is a scalar" will still write a direction beside
+ * a work answer, because they were told the fact and not the cause. The cause is that work is a dot
+ * product, and a dot product of two vectors is a scalar by construction. Once that is the reason,
+ * power and energy follow for free, and momentum and impulse fall on the other side for the equally
+ * concrete reason that nothing divided them into a projection.
+ */
+interface QuantityKind {
+  readonly name: string;
+  readonly kind: 'scalar' | 'vector';
+  readonly unit: string;
+  /** Why it lands on that side. Never "because the book says so". */
+  readonly because: string;
+}
+declare const MECHANICAL_KINDS: readonly QuantityKind[];
+/** Look one up by name. Returns undefined rather than throwing: a lab may ask about anything. */
+declare const kindOf: (name: string) => QuantityKind | undefined;
+/** What a given piece of work is DOING to the body's energy. */
+type WorkSign = 'positive' | 'negative' | 'none';
+interface WorkResult {
+  /** Joules, signed. */
+  readonly value: number;
+  readonly sign: WorkSign;
+  /** The component of the force that actually did anything: `F cos θ`. */
+  readonly effectiveForce: number;
+  readonly worked: Worked;
+}
+/**
+ * Which of the three a work value is, with the tolerance measured RELATIVE to the scale of the
+ * quantities involved.
+ *
+ * `scale` should be `F × d`: the largest the work could possibly have been. A perpendicular force
+ * gives a `cos` that is 6.1e-17 rather than 0, and multiplying that by a large force and a long
+ * distance produces a number that beats any fixed epsilon while still being nothing at all. Judging
+ * it against what the work COULD have been is the only test that holds at every size.
+ */
+declare function signOfWork(value: number, scale?: number): WorkSign;
+/**
+ * `W = F d cos θ`, where `θ` is the angle between the force and the displacement.
+ *
+ * The parameter is named `angleToDisplacementDeg` and not `angle` on purpose. Half of all lost marks
+ * on this topic are a correct multiplication of the wrong angle, and a name that states which two
+ * lines the angle sits between is the cheapest possible fix for that.
+ */
+declare function workDone(force: number, displacement: number, angleToDisplacementDeg?: number, sf?: number): WorkResult;
+/**
+ * Work from components, when both vectors are already resolved: `W = Fx dx + Fy dy (+ Fz dz)`.
+ *
+ * The same quantity by the other route, and worth having because it is how a 3D question must be
+ * done and because seeing `F d cos θ` and the component sum agree is what makes the dot product
+ * stop being two unrelated definitions.
+ */
+declare function workFromComponents(force: readonly number[], displacement: readonly number[], sf?: number): WorkResult;
+/** The angle between two vectors, recovered from the work they produced. */
+declare function angleFromWork(work: number, force: number, displacement: number): number;
+interface LiftWorkResult {
+  readonly value: number;
+  /** The work gravity itself did: the same size, opposite sign. */
+  readonly workByGravity: number;
+  readonly worked: Worked;
+}
+/**
+ * Work done against gravity in raising a mass through a height gain.
+ *
+ * The whole point, and the reason this is a named function rather than a call to `workDone`, is the
+ * thing it deliberately does NOT take: a path. Stairs, a ramp, a ladder, a winding road. Gravity
+ * charges for the height and for nothing else, so a 2 m staircase at 30 degrees and a 1 m vertical
+ * climb cost the same. Students who carry the slope length into this are answering the question the
+ * diagram invited rather than the one gravity asks.
+ *
+ * `heightGain` is signed, so a descent returns negative work, which is correct and is how a lowering
+ * question should be posed.
+ */
+declare function workAgainstGravity(mass: number, heightGain: number, g?: number, sf?: number): LiftWorkResult;
+/**
+ * The height gain of a body dragged along a slope, and the work that costs.
+ *
+ * Their standard picture: a slope of a stated LENGTH and ANGLE, or of a stated length and height.
+ * Both are here because both appear, and because the resolution `h = L sin θ` is the single line
+ * that connects them.
+ */
+declare function workUpSlope(mass: number, slopeLength: number, angleDeg: number, g?: number, sf?: number): LiftWorkResult & {
+  readonly heightGain: number;
+  readonly forceAlongSlope: number;
+};
+/**
+ * The work a stated force does in dragging a body up a rough slope: the full three-term account.
+ *
+ * Kept separate from `workUpSlope` because the moment friction enters, the applied force is no
+ * longer determined by the geometry and must be given. Returns each contribution so a lab can show
+ * where the energy went, which is the only way the sum stops looking arbitrary.
+ */
+declare function slopeEnergyAudit(mass: number, slopeLength: number, angleDeg: number, frictionCoefficient: number, g?: number, sf?: number): {
+  readonly againstGravity: number;
+  readonly againstFriction: number;
+  readonly value: number;
+  readonly normalForce: number;
+  readonly worked: Worked;
+};
+/**
+ * Work by a force that is itself a vector, against a displacement that is a vector.
+ *
+ * A convenience over `workFromComponents` for the common 2D case where both are given in polar
+ * form, which is how a question phrases it in words.
+ */
+declare function workFromPolar(force: number, forceAngleDeg: number, displacement: number, displacementAngleDeg: number, sf?: number): WorkResult;
+//#endregion
+export { LiftWorkResult, MECHANICAL_KINDS, QuantityKind, WorkResult, WorkSign, angleFromWork, kindOf, signOfWork, slopeEnergyAudit, workAgainstGravity, workDone, workFromComponents, workFromPolar, workUpSlope };

package/dist/physics/energy/work.mjs

@@ -0,0 +1,219 @@
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { compose, resolve, toDegrees } from "../vectors.mjs";
+import { G_EARTH } from "../kinematics/free-fall.mjs";
+import { frictionOn } from "../dynamics/friction.mjs";
+
+//#region src/physics/energy/work.ts
+/**
+* Work: the dot product, wearing a physics hat.
+*
+* Every formula in this file is `W = F·d`. The list of cases a textbook prints (work by a constant
+* force, work going up a slope, work against gravity, work done by friction) is not a list of
+* formulas. It is one formula asked about four geometries, and the only thing that changes is which
+* angle you feed it.
+*
+* TWO IDEAS DO ALL THE LIFTING HERE, and both are about the `cos θ`:
+*
+*   1. `θ` is the angle between the FORCE and the DISPLACEMENT. Not between the force and the
+*      ground, not between the force and the slope. Learners lose marks by pairing the angle with
+*      whichever line is drawn most prominently in the diagram, which is usually neither of those.
+*   2. `cos θ` carries a SIGN, and the sign is the physics. Positive work puts energy in, negative
+*      work takes it out, and `θ = 90°` does nothing at all: this is why carrying a bag along a
+*      level corridor is no work on the bag however much your arm disagrees, and why the tension in
+*      a string does no work on a body going round a circle.
+*
+* Pure: no React, no pixels.
+*/
+const MECHANICAL_KINDS = [
+	{
+		name: "work",
+		kind: "scalar",
+		unit: "J",
+		because: "a dot product of force and displacement, and a dot product returns a plain number"
+	},
+	{
+		name: "energy",
+		kind: "scalar",
+		unit: "J",
+		because: "it is what work deposits, so it inherits work being a scalar"
+	},
+	{
+		name: "power",
+		kind: "scalar",
+		unit: "W",
+		because: "a scalar (work) divided by a scalar (time) stays a scalar"
+	},
+	{
+		name: "force",
+		kind: "vector",
+		unit: "N",
+		because: "a push has a direction, and two pushes add by the triangle rule rather than by adding numbers"
+	},
+	{
+		name: "displacement",
+		kind: "vector",
+		unit: "m",
+		because: "it is the straight line from start to finish, which needs a direction to be stated at all"
+	},
+	{
+		name: "momentum",
+		kind: "vector",
+		unit: "kg m s^-1",
+		because: "mass times velocity, and multiplying a vector by a plain number leaves it a vector"
+	},
+	{
+		name: "impulse",
+		kind: "vector",
+		unit: "N s",
+		because: "force times time, with nothing projecting it onto anything, so the direction survives"
+	}
+];
+/** Look one up by name. Returns undefined rather than throwing: a lab may ask about anything. */
+const kindOf = (name) => MECHANICAL_KINDS.find((k) => k.name === name.toLowerCase());
+const describeSign = (sign) => sign === "positive" ? "positive: the force has a component along the motion, so it feeds energy in" : sign === "negative" ? "negative: the force opposes the motion, so it takes energy out" : "zero: the force is perpendicular to the motion, so it transfers nothing however large it is";
+/**
+* Which of the three a work value is, with the tolerance measured RELATIVE to the scale of the
+* quantities involved.
+*
+* `scale` should be `F × d`: the largest the work could possibly have been. A perpendicular force
+* gives a `cos` that is 6.1e-17 rather than 0, and multiplying that by a large force and a long
+* distance produces a number that beats any fixed epsilon while still being nothing at all. Judging
+* it against what the work COULD have been is the only test that holds at every size.
+*/
+function signOfWork(value, scale = 1) {
+	if (Math.abs(value) <= Math.max(Math.abs(scale), 1) * 1e-12) return "none";
+	return value > 0 ? "positive" : "negative";
+}
+/**
+* `W = F d cos θ`, where `θ` is the angle between the force and the displacement.
+*
+* The parameter is named `angleToDisplacementDeg` and not `angle` on purpose. Half of all lost marks
+* on this topic are a correct multiplication of the wrong angle, and a name that states which two
+* lines the angle sits between is the cheapest possible fix for that.
+*/
+function workDone(force, displacement, angleToDisplacementDeg = 0, sf = 3) {
+	const effectiveForce = resolve(force, angleToDisplacementDeg).x;
+	const value = effectiveForce * displacement;
+	const sign = signOfWork(value, force * displacement);
+	return {
+		value,
+		sign,
+		effectiveForce,
+		worked: calc().step("W = \\vec{F} \\cdot \\vec{d} = F d \\cos\\theta", "theta is the angle between the force and the DISPLACEMENT, not between the force and the ground").step(`W = ${texSigFigs(force, sf)} \\times ${texSigFigs(displacement, sf)} \\times \\cos ${texSigFigs(angleToDisplacementDeg, sf)}^\\circ`).step(`F\\cos\\theta = ${texSigFigs(effectiveForce, sf)}\\ \\mathrm{N}`, "only this component lies along the motion. The rest of the force does nothing to the energy").step(`W = ${texSigFigs(value, sf)}\\ \\mathrm{J}`, describeSign(sign)).done(value)
+	};
+}
+/**
+* Work from components, when both vectors are already resolved: `W = Fx dx + Fy dy (+ Fz dz)`.
+*
+* The same quantity by the other route, and worth having because it is how a 3D question must be
+* done and because seeing `F d cos θ` and the component sum agree is what makes the dot product
+* stop being two unrelated definitions.
+*/
+function workFromComponents(force, displacement, sf = 3) {
+	if (force.length !== displacement.length) throw new Error(`A force with ${force.length} components cannot be dotted with a displacement with ${displacement.length}. Both vectors must live in the same number of dimensions.`);
+	let value = 0;
+	for (let i = 0; i < force.length; i++) value += force[i] * displacement[i];
+	const dMag = Math.hypot(...displacement);
+	const sign = signOfWork(value, Math.hypot(...force) * dMag);
+	const terms = force.map((f, i) => `(${texSigFigs(f, sf)})(${texSigFigs(displacement[i], sf)})`);
+	const worked = calc().step("\\vec{F} \\cdot \\vec{d} = F_x d_x + F_y d_y + F_z d_z", "multiply matching components and add. No angle is needed, because the components already encode it").step(`W = ${terms.join(" + ")}`).step(`W = ${texSigFigs(value, sf)}\\ \\mathrm{J}`, describeSign(sign)).done(value);
+	return {
+		value,
+		sign,
+		effectiveForce: dMag === 0 ? 0 : value / dMag,
+		worked
+	};
+}
+/** The angle between two vectors, recovered from the work they produced. */
+function angleFromWork(work, force, displacement) {
+	const product = force * displacement;
+	if (product === 0) throw new Error("With a zero force or a zero displacement the angle is not defined by the work.");
+	const cos = Math.max(-1, Math.min(1, work / product));
+	return toDegrees(Math.acos(cos));
+}
+/**
+* Work done against gravity in raising a mass through a height gain.
+*
+* The whole point, and the reason this is a named function rather than a call to `workDone`, is the
+* thing it deliberately does NOT take: a path. Stairs, a ramp, a ladder, a winding road. Gravity
+* charges for the height and for nothing else, so a 2 m staircase at 30 degrees and a 1 m vertical
+* climb cost the same. Students who carry the slope length into this are answering the question the
+* diagram invited rather than the one gravity asks.
+*
+* `heightGain` is signed, so a descent returns negative work, which is correct and is how a lowering
+* question should be posed.
+*/
+function workAgainstGravity(mass, heightGain, g = G_EARTH, sf = 3) {
+	const value = mass * g * heightGain;
+	const worked = calc().step("W = mgh", "the path is not in this formula. Only the height gain is, so every route between the same two levels costs the same").step(`W = ${texSigFigs(mass, sf)} \\times ${texSigFigs(g, sf)} \\times ${texSigFigs(heightGain, sf)}`).step(`W = ${texSigFigs(value, sf)}\\ \\mathrm{J}`, heightGain >= 0 ? "done against gravity, so it is stored and can be got back" : "gravity did this work on the body, so energy came out").done(value);
+	return {
+		value,
+		workByGravity: -value,
+		worked
+	};
+}
+/**
+* The height gain of a body dragged along a slope, and the work that costs.
+*
+* Their standard picture: a slope of a stated LENGTH and ANGLE, or of a stated length and height.
+* Both are here because both appear, and because the resolution `h = L sin θ` is the single line
+* that connects them.
+*/
+function workUpSlope(mass, slopeLength, angleDeg, g = G_EARTH, sf = 3) {
+	const heightGain = resolve(slopeLength, angleDeg).y;
+	const forceAlongSlope = frictionOn({
+		mass,
+		muStatic: 0,
+		inclineDeg: angleDeg,
+		g
+	}).driving;
+	const value = forceAlongSlope * slopeLength;
+	const worked = calc().step("F = mg\\sin\\theta", "on a smooth slope the only thing to push against is the component of the weight that lies along it").step(`F = ${texSigFigs(mass, sf)} \\times ${texSigFigs(g, sf)} \\times \\sin ${texSigFigs(angleDeg, sf)}^\\circ = ${texSigFigs(forceAlongSlope, sf)}\\ \\mathrm{N}`).step(`W = F L = ${texSigFigs(forceAlongSlope, sf)} \\times ${texSigFigs(slopeLength, sf)} = ${texSigFigs(value, sf)}\\ \\mathrm{J}`).step(`h = L\\sin\\theta = ${texSigFigs(heightGain, sf)}\\ \\mathrm{m}, \\quad mgh = ${texSigFigs(mass * g * heightGain, sf)}\\ \\mathrm{J}`, "the same answer by the height alone. The slope changed the force and the distance in exactly compensating ways").done(value);
+	return {
+		value,
+		workByGravity: -value,
+		heightGain,
+		forceAlongSlope,
+		worked
+	};
+}
+/**
+* The work a stated force does in dragging a body up a rough slope: the full three-term account.
+*
+* Kept separate from `workUpSlope` because the moment friction enters, the applied force is no
+* longer determined by the geometry and must be given. Returns each contribution so a lab can show
+* where the energy went, which is the only way the sum stops looking arbitrary.
+*/
+function slopeEnergyAudit(mass, slopeLength, angleDeg, frictionCoefficient, g = G_EARTH, sf = 3) {
+	const onSlope = frictionOn({
+		mass,
+		muStatic: frictionCoefficient,
+		inclineDeg: angleDeg,
+		g
+	});
+	const normalForce = onSlope.normal;
+	const againstGravity = onSlope.driving * slopeLength;
+	const againstFriction = onSlope.limiting * slopeLength;
+	const value = againstGravity + againstFriction;
+	return {
+		againstGravity,
+		againstFriction,
+		value,
+		normalForce,
+		worked: calc().step("W = W_{\\text{gravity}} + W_{\\text{friction}}", "two things resist the drag, and they resist for different reasons, so they are counted separately").step(`W_{\\text{gravity}} = mg\\sin\\theta \\cdot L = ${texSigFigs(againstGravity, sf)}\\ \\mathrm{J}`, "recoverable: let the body slide back and you get this returned").step(`N = mg\\cos\\theta = ${texSigFigs(normalForce, sf)}\\ \\mathrm{N}`, "the slope only presses back on the component pressing into it").step(`W_{\\text{friction}} = \\mu N L = ${texSigFigs(frictionCoefficient, sf)} \\times ${texSigFigs(normalForce, sf)} \\times ${texSigFigs(slopeLength, sf)} = ${texSigFigs(againstFriction, sf)}\\ \\mathrm{J}`, "gone as heat. Sliding back down does not give it back, and sliding back costs it again").step(`W = ${texSigFigs(value, sf)}\\ \\mathrm{J}`).done(value)
+	};
+}
+/**
+* Work by a force that is itself a vector, against a displacement that is a vector.
+*
+* A convenience over `workFromComponents` for the common 2D case where both are given in polar
+* form, which is how a question phrases it in words.
+*/
+function workFromPolar(force, forceAngleDeg, displacement, displacementAngleDeg, sf = 3) {
+	const f = resolve(force, forceAngleDeg);
+	const d = resolve(displacement, displacementAngleDeg);
+	return workDone(force, displacement, compose(d.x, d.y).angleDeg - compose(f.x, f.y).angleDeg, sf);
+}
+
+//#endregion
+export { MECHANICAL_KINDS, angleFromWork, kindOf, signOfWork, slopeEnergyAudit, workAgainstGravity, workDone, workFromComponents, workFromPolar, workUpSlope };

package/dist/physics/gravitation/body.d.mts

@@ -0,0 +1,85 @@
+import { Worked } from "../../core/worked.mjs";
+
+//#region src/physics/gravitation/body.d.ts
+/**
+ * A spherically symmetric attracting body.
+ *
+ * Spherical symmetry is doing real work here and is not a simplifying lie: by the shell theorem it
+ * is exactly why a planet can be treated as a point at its centre, which is the assumption every
+ * formula in this kernel rests on. `potential.ts` proves it rather than asserting it.
+ */
+interface CentralBody {
+  readonly name: string;
+  /** Mass, kg. Present for teaching; prefer `mu` for anything that must be accurate. */
+  readonly mass: number;
+  /** Mean radius, m. */
+  readonly radius: number;
+  /** Standard gravitational parameter `GM`, m³/s². The number the physics actually uses. */
+  readonly mu: number;
+  /**
+   * Sidereal rotation period, s, where the body has one.
+   *
+   * The SIDEREAL day, not the solar day: 86164 s for the Earth, not 86400. A geostationary
+   * satellite has to keep pace with the Earth's rotation against the stars, and using 86400 puts
+   * the orbit about 80 km too high. The difference is four minutes and it is not rounding.
+   */
+  readonly rotationPeriodS?: number;
+}
+/** A body from its mass and radius, the textbook pair. `mu` is derived, so it inherits `G`'s error. */
+declare function bodyFromMass(name: string, mass: number, radius: number, G?: number): CentralBody;
+/**
+ * A body from its MEAN DENSITY and radius: `M = (4/3)πR³ρ`, so `g = (4/3)πGρR`.
+ *
+ * The form worth knowing, because it says the thing the mass form hides: at equal density, surface
+ * gravity is proportional to RADIUS ALONE. A planet twice the size of another made of the same
+ * stuff has twice the surface gravity, not four times and not eight. Students reliably guess one of
+ * the other two, because they are reasoning from `M/R²` without noticing `M` carries an `R³`.
+ */
+declare function bodyFromDensity(name: string, meanDensity: number, radius: number, G?: number): CentralBody;
+/**
+ * A body from its SURFACE GRAVITY and radius: `mu = gR²`.
+ *
+ * The most accurate route available in a classroom, and the one to prefer whenever a question gives
+ * you `g`, because it never touches `G` at all. `gR²` for the Earth is 9.81 × (6.371×10⁶)² which
+ * lands within a fraction of a percent of the measured `mu`, whereas going via `M` and `G` throws
+ * away four figures for nothing.
+ */
+declare function bodyFromSurfaceGravity(name: string, surfaceG: number, radius: number, G?: number): CentralBody;
+/** Surface gravity, m/s²: `g = mu/R²`. What a scale at the poles would read per kilogram. */
+declare const surfaceGravity: (body: CentralBody) => number;
+/** Mean density, kg/m³: mass over the volume of the sphere. */
+declare const meanDensity: (body: CentralBody) => number;
+/** The body's volume, m³. Separated out because the density questions ask for it directly. */
+declare const bodyVolume: (body: CentralBody) => number;
+/**
+ * Surface gravity worked through from the density, showing why radius alone decides it.
+ *
+ * Exists as a `Worked` rather than a bare number because the CANCELLATION is the lesson: the `R³`
+ * in the mass meets the `R²` underneath and one `R` survives.
+ */
+declare function surfaceGravityFromDensity(meanDensityKgM3: number, radius: number, G?: number, sf?: number): Worked;
+/**
+ * The ratio of surface gravities of two bodies: `g₁/g₂ = (M₁/M₂)(R₂/R₁)²`.
+ *
+ * The single commonest exam framing in the chapter ("the Moon's mass is 1/81 of the Earth's and its
+ * radius 1/4, so what does an 80 kg astronaut weigh there?"), and the one where students halve when
+ * they should quarter. Note `G` never appears: a ratio question needs no constant, and reaching for
+ * one is the sign of a student solving it the long way.
+ */
+declare function surfaceGravityRatio(a: CentralBody, b: CentralBody, sf?: number): Worked;
+/** Earth. Mean radius; the equatorial radius is 6.3781×10⁶ m and matters for latitude questions. */
+declare const EARTH: CentralBody;
+/** The Moon. Its mass is 1/81.3 of the Earth's, which is the "81" every textbook problem uses. */
+declare const MOON: CentralBody;
+/** The Sun. */
+declare const SUN: CentralBody;
+/** Mars. A sidereal day of 24 h 37 min, which is why its "areostationary" orbit is a nice exercise. */
+declare const MARS: CentralBody;
+/** Jupiter. Ten hours to turn once, and 318 Earth masses. */
+declare const JUPITER: CentralBody;
+/** Mean Earth-Moon centre separation, m. The distance the null-point questions are set at. */
+declare const EARTH_MOON_DISTANCE = 384400000;
+/** Mean Earth-Sun separation, m. One astronomical unit. */
+declare const EARTH_SUN_DISTANCE = 149597870700;
+//#endregion
+export { CentralBody, EARTH, EARTH_MOON_DISTANCE, EARTH_SUN_DISTANCE, JUPITER, MARS, MOON, SUN, bodyFromDensity, bodyFromMass, bodyFromSurfaceGravity, bodyVolume, meanDensity, surfaceGravity, surfaceGravityFromDensity, surfaceGravityRatio };

package/dist/physics/gravitation/body.mjs

@@ -0,0 +1,168 @@
+import { GRAVITATIONAL_CONSTANT } from "../../core/constants.mjs";
+import { calc, texSigFigs } from "../../core/worked.mjs";
+
+//#region src/physics/gravitation/body.ts
+/**
+* The attracting body, as ONE object that every other function in this kernel takes.
+*
+* ── Why this file exists at all ─────────────────────────────────────────────────────────────────
+* A gravitation chapter looks like twenty formulas. Written out, they are:
+*
+*     g = GM/R²      g' = GM/(R+h)²     g' = g(1 − d/R)      g = (4/3)πGρR
+*     V = −GM/r      E = −GM/r²         v_e = √(2GM/R)       v_e = √(2gR)
+*     v = √(GM/r)    T² = 4π²r³/GM      E = −GMm/2r          ...
+*
+* Every one of them contains `GM` and a distance. Nothing else. `G`, `M`, `R` and `ρ` never appear
+* independently: they appear as the product `GM` and as a length. So the twenty formulas are two
+* numbers wearing different hats, and a student who has memorised them as twenty separate facts is
+* carrying eighteen unnecessary things and will still pick the wrong one under exam pressure.
+*
+* A kernel can either reproduce that confusion, by taking `(G, M, R)` as three loose arguments in
+* every function, or it can say the true thing in its types: there is a BODY, and it has a `mu`.
+* That is what this is. Pass a body and a radius, get physics.
+*
+* ── Why `mu` is stored rather than computed ─────────────────────────────────────────────────────
+* `mu = GM` is the standard gravitational parameter, and for every real body it is known FAR more
+* precisely than `G` or `M` are known separately: it is measured directly from how things orbit,
+* to ten significant figures for the Earth, while `M` on its own is known to four because getting
+* it means dividing by `G` (see `GRAVITATIONAL_CONSTANT`, the worst-measured constant in physics).
+*
+* So `EARTH.mu` is the measured 3.986004418×10¹⁴, NOT `G × EARTH.mass`, and those two differ in the
+* fifth figure. A lab quoting the Earth's mass to six figures is quoting precision that does not
+* exist. This is not pedantry about digits: it is the reason satellite navigation works at all
+* without anyone knowing what the Earth weighs.
+*
+* ── Why the constructors take different pairs ───────────────────────────────────────────────────
+* Exam questions do not hand you a mass. They hand you a density and a radius, or a surface `g` and
+* a radius, or a moon's period and orbit, and the FIRST step is always recovering the body. Making
+* that step a named constructor means the kernel can show its working for it, instead of a lesson
+* doing the algebra inline and the kernel picking up afterwards.
+*
+* Pure: no React, no pixels.
+*/
+const positive = (value, what) => {
+	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${what} must be positive and finite`);
+	return value;
+};
+/** A body from its mass and radius, the textbook pair. `mu` is derived, so it inherits `G`'s error. */
+function bodyFromMass(name, mass, radius, G = GRAVITATIONAL_CONSTANT) {
+	return {
+		name,
+		mass: positive(mass, "mass"),
+		radius: positive(radius, "radius"),
+		mu: G * mass
+	};
+}
+/**
+* A body from its MEAN DENSITY and radius: `M = (4/3)πR³ρ`, so `g = (4/3)πGρR`.
+*
+* The form worth knowing, because it says the thing the mass form hides: at equal density, surface
+* gravity is proportional to RADIUS ALONE. A planet twice the size of another made of the same
+* stuff has twice the surface gravity, not four times and not eight. Students reliably guess one of
+* the other two, because they are reasoning from `M/R²` without noticing `M` carries an `R³`.
+*/
+function bodyFromDensity(name, meanDensity, radius, G = GRAVITATIONAL_CONSTANT) {
+	const r = positive(radius, "radius");
+	const mass = 4 / 3 * Math.PI * r ** 3 * positive(meanDensity, "density");
+	return {
+		name,
+		mass,
+		radius: r,
+		mu: G * mass
+	};
+}
+/**
+* A body from its SURFACE GRAVITY and radius: `mu = gR²`.
+*
+* The most accurate route available in a classroom, and the one to prefer whenever a question gives
+* you `g`, because it never touches `G` at all. `gR²` for the Earth is 9.81 × (6.371×10⁶)² which
+* lands within a fraction of a percent of the measured `mu`, whereas going via `M` and `G` throws
+* away four figures for nothing.
+*/
+function bodyFromSurfaceGravity(name, surfaceG, radius, G = GRAVITATIONAL_CONSTANT) {
+	const r = positive(radius, "radius");
+	const mu = positive(surfaceG, "surface gravity") * r * r;
+	return {
+		name,
+		mass: mu / G,
+		radius: r,
+		mu
+	};
+}
+/** Surface gravity, m/s²: `g = mu/R²`. What a scale at the poles would read per kilogram. */
+const surfaceGravity = (body) => body.mu / body.radius ** 2;
+/** Mean density, kg/m³: mass over the volume of the sphere. */
+const meanDensity = (body) => body.mass / (4 / 3 * Math.PI * body.radius ** 3);
+/** The body's volume, m³. Separated out because the density questions ask for it directly. */
+const bodyVolume = (body) => 4 / 3 * Math.PI * body.radius ** 3;
+/**
+* Surface gravity worked through from the density, showing why radius alone decides it.
+*
+* Exists as a `Worked` rather than a bare number because the CANCELLATION is the lesson: the `R³`
+* in the mass meets the `R²` underneath and one `R` survives.
+*/
+function surfaceGravityFromDensity(meanDensityKgM3, radius, G = GRAVITATIONAL_CONSTANT, sf = 3) {
+	const r = positive(radius, "radius");
+	const rho = positive(meanDensityKgM3, "density");
+	const value = 4 / 3 * Math.PI * G * rho * r;
+	return calc().step("g = \\frac{GM}{R^2}", "the surface is just r = R in the field equation").step("M = \\tfrac{4}{3}\\pi R^3 \\rho", "a sphere of uniform density").step("g = \\frac{G}{R^2}\\cdot\\tfrac{4}{3}\\pi R^3 \\rho = \\tfrac{4}{3}\\pi G \\rho R", "the R cubed meets the R squared and ONE power of R survives: at equal density, g goes as the radius").step(`g = \\tfrac{4}{3}\\pi \\times ${texSigFigs(G, 4)} \\times ${texSigFigs(rho, sf)} \\times ${texSigFigs(r, sf)}`).step(`g = ${texSigFigs(value, sf)}\\ \\mathrm{m\\,s^{-2}}`).done(value);
+}
+/**
+* The ratio of surface gravities of two bodies: `g₁/g₂ = (M₁/M₂)(R₂/R₁)²`.
+*
+* The single commonest exam framing in the chapter ("the Moon's mass is 1/81 of the Earth's and its
+* radius 1/4, so what does an 80 kg astronaut weigh there?"), and the one where students halve when
+* they should quarter. Note `G` never appears: a ratio question needs no constant, and reaching for
+* one is the sign of a student solving it the long way.
+*/
+function surfaceGravityRatio(a, b, sf = 3) {
+	const value = surfaceGravity(a) / surfaceGravity(b);
+	return calc().step("\\frac{g_1}{g_2} = \\frac{GM_1/R_1^2}{GM_2/R_2^2}", "write both out").step("\\frac{g_1}{g_2} = \\frac{M_1}{M_2}\\left(\\frac{R_2}{R_1}\\right)^{2}", "G cancels. A ratio question never needs the constant, and never needs either mass on its own").step(`\\frac{g_1}{g_2} = ${texSigFigs(a.mass / b.mass, sf)} \\times \\left(${texSigFigs(b.radius / a.radius, sf)}\\right)^{-2}`, `${a.name} against ${b.name}`).step(`\\frac{g_1}{g_2} = ${texSigFigs(value, sf)}`).done(value);
+}
+/** Earth. Mean radius; the equatorial radius is 6.3781×10⁶ m and matters for latitude questions. */
+const EARTH = {
+	name: "Earth",
+	mass: 59722e20,
+	radius: 6371e3,
+	mu: 3986004418e5,
+	rotationPeriodS: 86164.0905
+};
+/** The Moon. Its mass is 1/81.3 of the Earth's, which is the "81" every textbook problem uses. */
+const MOON = {
+	name: "Moon",
+	mass: 7346e19,
+	radius: 1737400,
+	mu: 49048695e5,
+	rotationPeriodS: 2360591.5
+};
+/** The Sun. */
+const SUN = {
+	name: "Sun",
+	mass: 198847e25,
+	radius: 6957e5,
+	mu: 0x731c14d0e4439c000,
+	rotationPeriodS: 2192832
+};
+/** Mars. A sidereal day of 24 h 37 min, which is why its "areostationary" orbit is a nice exercise. */
+const MARS = {
+	name: "Mars",
+	mass: 64171e19,
+	radius: 3389500,
+	mu: 4282837e7,
+	rotationPeriodS: 88642.66
+};
+/** Jupiter. Ten hours to turn once, and 318 Earth masses. */
+const JUPITER = {
+	name: "Jupiter",
+	mass: 18982e23,
+	radius: 69911e3,
+	mu: 0x1c214bb40e53c00,
+	rotationPeriodS: 35730
+};
+/** Mean Earth-Moon centre separation, m. The distance the null-point questions are set at. */
+const EARTH_MOON_DISTANCE = 3844e5;
+/** Mean Earth-Sun separation, m. One astronomical unit. */
+const EARTH_SUN_DISTANCE = 149597870700;
+
+//#endregion
+export { EARTH, EARTH_MOON_DISTANCE, EARTH_SUN_DISTANCE, JUPITER, MARS, MOON, SUN, bodyFromDensity, bodyFromMass, bodyFromSurfaceGravity, bodyVolume, meanDensity, surfaceGravity, surfaceGravityFromDensity, surfaceGravityRatio };