@classytic/stage 0.3.0 → 0.4.0

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

@@ -0,0 +1,127 @@
+import { Worked } from "../../core/worked.mjs";
+
+//#region src/physics/gravitation/kepler.d.ts
+/** The nearest and furthest points of an orbit: `r_p = a(1−e)`, `r_a = a(1+e)`. */
+declare function apsides(semiMajorAxis: number, eccentricity: number): {
+  periapsis: number;
+  apoapsis: number;
+};
+/**
+ * The orbit implied by its two extremes: `a = (r_p + r_a)/2`, `e = (r_a − r_p)/(r_a + r_p)`.
+ *
+ * The direction real questions run in, since what gets measured is the closest and furthest
+ * distance. Note `a` is the plain AVERAGE of the two, which is a genuinely useful thing to know and
+ * is not obvious from the picture.
+ */
+declare function orbitFromApsides(periapsis: number, apoapsis: number): {
+  semiMajorAxis: number;
+  eccentricity: number;
+};
+/** Semi-minor axis, `b = a√(1−e²)`. How little an eccentric ellipse differs from a circle. */
+declare const semiMinorAxis: (semiMajorAxis: number, eccentricity: number) => number;
+/**
+ * The speeds at the two apsides, and the check that `r_p v_p = r_a v_a`.
+ *
+ * At perihelion and aphelion alone, the velocity is perpendicular to the radius, so angular momentum
+ * is simply `mvr` and the ratio of speeds is the inverse ratio of distances. That is why the Earth
+ * moves about 3.4% faster in January than in July: `r_a/r_p` is 1.034, and the reference books quote
+ * exactly that number.
+ *
+ * The speeds themselves come from `visViva`, not from a separate apsis formula, because there is no
+ * separate apsis formula: it is the general equation at two particular radii.
+ */
+declare function apsisSpeeds(mu: number, semiMajorAxis: number, eccentricity: number, sf?: number): {
+  periapsisSpeed: number;
+  apoapsisSpeed: number;
+  worked: Worked;
+};
+/**
+ * Areal velocity, `dA/dt = L/2m = ½√(mu·a(1−e²))`, in m²/s.
+ *
+ * Constant around the whole orbit, which is the exact content of the second law. Exposed as a number
+ * so that a lab can shade two swept wedges at different parts of an orbit and show their areas
+ * agreeing, which is the only way the law becomes believable rather than recited.
+ */
+declare const arealVelocity: (mu: number, semiMajorAxis: number, eccentricity: number) => number;
+/** Specific angular momentum, `h = √(mu·a(1−e²))`, m²/s. Twice the areal velocity, by definition. */
+declare const specificAngularMomentum: (mu: number, semiMajorAxis: number, eccentricity: number) => number;
+/** Period of any orbit, circular or elliptical, from its semi-major axis: `T = 2π√(a³/mu)`. */
+declare const periodFromAxis: (mu: number, semiMajorAxis: number) => number;
+/** The semi-major axis of an orbit with a given period: `a = (mu·T²/4π²)^{1/3}`. */
+declare const axisFromPeriod: (mu: number, period: number) => number;
+/**
+ * The third law as a RATIO, needing no constant, no mass and no SI units: `T₂ = T₁(a₂/a₁)^{3/2}`.
+ *
+ * The form to use whenever a question gives you one orbit and asks about another, which is most of
+ * them. Units cancel, so days and astronomical units are as good as seconds and metres, and a
+ * learner who converts everything to SI first has done real work for no marks.
+ */
+declare function keplerRatio(knownPeriod: number, knownAxis: number, targetAxis: number, sf?: number): Worked;
+/**
+ * The mass of a central body from ANY orbit around it: `M = 4π²a³/GT²`.
+ *
+ * How everything in the sky has ever been weighed. Point a telescope at a moon, time one circuit,
+ * measure the distance, and the planet's mass drops out. It is worth pausing on what is NOT needed:
+ * you never go there, you never touch it, and the orbiting body's own mass cancels and is never
+ * required either.
+ *
+ * Returns the mass, with `mu` alongside, since `mu` is the honest quantity: `mu = 4π²a³/T²` is
+ * measured directly and accurately, and dividing by `G` to get `M` throws away six figures of it.
+ */
+declare function centralMassFromOrbit(semiMajorAxis: number, period: number, G?: number, sf?: number): {
+  mass: number;
+  mu: number;
+  worked: Worked;
+};
+/**
+ * The synodic period: how often two orbiting bodies line up again. `1/T_syn = |1/T₁ − 1/T₂|`.
+ *
+ * The difference between a year and the time between two oppositions of Mars, and the reason launch
+ * windows to Mars come round every 26 months rather than every 12 or 23. It is a beat frequency,
+ * exactly like two waves of different pitch, which is a connection worth making across topics.
+ */
+declare function synodicPeriod(period1: number, period2: number): number;
+/**
+ * Kepler's equation, `M = E − e·sin E`, solved for the eccentric anomaly by Newton-Raphson.
+ *
+ * THE OLDEST UNSOLVED-IN-CLOSED-FORM PROBLEM in the syllabus, and worth telling students about:
+ * there is no way to rearrange it, and every planetarium in the world iterates. Kepler himself said
+ * he could see no method and invited someone else to find one; nobody has, and it was later proved
+ * impossible in elementary functions.
+ *
+ * Migrated from `labs/src/physics/orbital/core.ts`, which owned it privately. The starting guess is
+ * `π` for high eccentricity rather than `M`, because `M` converges slowly for the elongated orbits
+ * where the equation matters most.
+ */
+declare function solveEccentricAnomaly(meanAnomaly: number, eccentricity: number, tolerance?: number, maxIterations?: number): number;
+/** Where a body is, and how fast, at a given point in its orbit. */
+interface OrbitPoint {
+  readonly x: number;
+  readonly y: number;
+  /** Distance from the focus, m. */
+  readonly radius: number;
+  /** Angle from periapsis as seen FROM THE FOCUS, radians. The physically meaningful angle. */
+  readonly trueAnomaly: number;
+  readonly eccentricAnomaly: number;
+}
+/**
+ * Position on an ellipse at a given mean anomaly, with the attracting body at the ORIGIN.
+ *
+ * The origin is the FOCUS, not the centre of the ellipse, which is Kepler's first law expressed as a
+ * coordinate choice rather than as a sentence. Drawing an orbit with the planet at the centre is the
+ * commonest illustration error in textbooks and it makes the second law look arbitrary.
+ *
+ * Mean anomaly advances uniformly with time (`M = 2πt/T`), which is what makes this drawable from a
+ * clock: a lab steps the mean anomaly linearly and the body visibly hurries through periapsis
+ * without anything in the animation code knowing why.
+ */
+declare function orbitPointAtMeanAnomaly(semiMajorAxis: number, eccentricity: number, meanAnomaly: number): OrbitPoint;
+/**
+ * The same, but from a TIME and a period rather than an anomaly, which is what an animation has.
+ *
+ * `t = 0` is periapsis. A lab driving this from its clock gets Kepler's second law for free: no part
+ * of the rendering has to know that the body should speed up, it simply does.
+ */
+declare function orbitPointAtTime(semiMajorAxis: number, eccentricity: number, timeS: number, periodS: number): OrbitPoint;
+//#endregion
+export { OrbitPoint, apsides, apsisSpeeds, arealVelocity, axisFromPeriod, centralMassFromOrbit, keplerRatio, orbitFromApsides, orbitPointAtMeanAnomaly, orbitPointAtTime, periodFromAxis, semiMinorAxis, solveEccentricAnomaly, specificAngularMomentum, synodicPeriod };

package/dist/physics/gravitation/kepler.mjs

@@ -0,0 +1,216 @@
+import { GRAVITATIONAL_CONSTANT } from "../../core/constants.mjs";
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { visViva } from "./orbit.mjs";
+
+//#region src/physics/gravitation/kepler.ts
+/**
+* Kepler's three laws, and the ellipse machinery that makes them drawable.
+*
+* ── The laws are older than the explanation, and that is the lesson ─────────────────────────────
+* Kepler extracted these from Tycho Brahe's naked-eye positions decades before Newton, by brute
+* arithmetic and twenty years of failure. They are a DESCRIPTION. Newton's law is the EXPLANATION,
+* and all three then fall out of it in a few lines. Teaching them in that order is worth the effort:
+* it is the clearest example in a school syllabus of a pattern being found first and understood
+* afterwards, which is how science usually goes and almost never how it is taught.
+*
+* ── What each law actually says once you strip the astronomy off ────────────────────────────────
+*   I.   Orbits are ellipses with the Sun at ONE FOCUS. Not at the centre. The distinction is the
+*        whole law: at the centre would be a trivial rescaling of a circle and would predict
+*        nothing, whereas a focus is off-centre and forces the planet to vary its distance.
+*
+*   II.  The line to the Sun sweeps equal AREAS in equal times, so a planet hurries at perihelion
+*        and dawdles at aphelion. This is CONSERVATION OF ANGULAR MOMENTUM and nothing else. That
+*        identity is rarely stated and it is the most valuable sentence in the topic: the areal
+*        velocity is `L/2m`, so the second law is not an astronomical fact at all, it holds for any
+*        central force whatsoever, inverse-square or not.
+*
+*   III. `T² ∝ a³`, with the SAME constant for everything orbiting the same body. That constant is
+*        `4π²/GM`, which means measuring any moon's orbit WEIGHS THE PLANET. It is the only method
+*        we have ever had for the mass of anything in the sky, and it is three lines of algebra.
+*
+* ── Why the third law needs no units if it is asked as a ratio ──────────────────────────────────
+* "Mars is 1.52 AU out, how long is its year?" is `1.52^{1.5} = 1.88` years and needs no constant,
+* no mass, and no metres. Students who reach for `GM` on a ratio question lose time and accuracy
+* both. `keplerRatio` is that shortcut as a function, so a lesson can show it beside the long way.
+*
+* Pure: no React, no pixels.
+*/
+const TAU = 2 * Math.PI;
+const positive = (value, what) => {
+	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${what} must be positive and finite`);
+	return value;
+};
+const checkEccentricity = (e) => {
+	if (!(e >= 0 && e < 1)) throw new RangeError("eccentricity must be in [0, 1) for a closed orbit");
+	return e;
+};
+/** The nearest and furthest points of an orbit: `r_p = a(1−e)`, `r_a = a(1+e)`. */
+function apsides(semiMajorAxis, eccentricity) {
+	const a = positive(semiMajorAxis, "semi-major axis");
+	const e = checkEccentricity(eccentricity);
+	return {
+		periapsis: a * (1 - e),
+		apoapsis: a * (1 + e)
+	};
+}
+/**
+* The orbit implied by its two extremes: `a = (r_p + r_a)/2`, `e = (r_a − r_p)/(r_a + r_p)`.
+*
+* The direction real questions run in, since what gets measured is the closest and furthest
+* distance. Note `a` is the plain AVERAGE of the two, which is a genuinely useful thing to know and
+* is not obvious from the picture.
+*/
+function orbitFromApsides(periapsis, apoapsis) {
+	const rp = positive(periapsis, "periapsis");
+	const ra = positive(apoapsis, "apoapsis");
+	if (ra < rp) throw new RangeError("apoapsis cannot be nearer than periapsis");
+	return {
+		semiMajorAxis: (rp + ra) / 2,
+		eccentricity: (ra - rp) / (ra + rp)
+	};
+}
+/** Semi-minor axis, `b = a√(1−e²)`. How little an eccentric ellipse differs from a circle. */
+const semiMinorAxis = (semiMajorAxis, eccentricity) => positive(semiMajorAxis, "semi-major axis") * Math.sqrt(1 - checkEccentricity(eccentricity) ** 2);
+/**
+* The speeds at the two apsides, and the check that `r_p v_p = r_a v_a`.
+*
+* At perihelion and aphelion alone, the velocity is perpendicular to the radius, so angular momentum
+* is simply `mvr` and the ratio of speeds is the inverse ratio of distances. That is why the Earth
+* moves about 3.4% faster in January than in July: `r_a/r_p` is 1.034, and the reference books quote
+* exactly that number.
+*
+* The speeds themselves come from `visViva`, not from a separate apsis formula, because there is no
+* separate apsis formula: it is the general equation at two particular radii.
+*/
+function apsisSpeeds(mu, semiMajorAxis, eccentricity, sf = 4) {
+	const a = positive(semiMajorAxis, "semi-major axis");
+	const { periapsis, apoapsis } = apsides(a, checkEccentricity(eccentricity));
+	const periapsisSpeed = visViva(mu, periapsis, a);
+	const apoapsisSpeed = visViva(mu, apoapsis, a);
+	return {
+		periapsisSpeed,
+		apoapsisSpeed,
+		worked: calc().step("m v_p r_p = m v_a r_a", "angular momentum is conserved, and at the apsides alone the velocity is square-on to the radius").step(`\\frac{v_p}{v_a} = \\frac{r_a}{r_p} = ${texSigFigs(apoapsis / periapsis, sf)}`, "so the nearer point is the faster one, in exactly that proportion. This IS Kepler II").step(`v_p = ${texSigFigs(periapsisSpeed, sf)}\\ \\mathrm{m\\,s^{-1}},\\quad v_a = ${texSigFigs(apoapsisSpeed, sf)}\\ \\mathrm{m\\,s^{-1}}`, "from vis-viva at each radius. There is no special apsis formula to learn").done(periapsisSpeed)
+	};
+}
+/**
+* Areal velocity, `dA/dt = L/2m = ½√(mu·a(1−e²))`, in m²/s.
+*
+* Constant around the whole orbit, which is the exact content of the second law. Exposed as a number
+* so that a lab can shade two swept wedges at different parts of an orbit and show their areas
+* agreeing, which is the only way the law becomes believable rather than recited.
+*/
+const arealVelocity = (mu, semiMajorAxis, eccentricity) => .5 * Math.sqrt(positive(mu, "gravitational parameter") * positive(semiMajorAxis, "semi-major axis") * (1 - checkEccentricity(eccentricity) ** 2));
+/** Specific angular momentum, `h = √(mu·a(1−e²))`, m²/s. Twice the areal velocity, by definition. */
+const specificAngularMomentum = (mu, semiMajorAxis, eccentricity) => 2 * arealVelocity(mu, semiMajorAxis, eccentricity);
+/** Period of any orbit, circular or elliptical, from its semi-major axis: `T = 2π√(a³/mu)`. */
+const periodFromAxis = (mu, semiMajorAxis) => TAU * Math.sqrt(positive(semiMajorAxis, "semi-major axis") ** 3 / positive(mu, "gravitational parameter"));
+/** The semi-major axis of an orbit with a given period: `a = (mu·T²/4π²)^{1/3}`. */
+const axisFromPeriod = (mu, period) => Math.cbrt(positive(mu, "gravitational parameter") * positive(period, "period") ** 2 / (TAU * TAU));
+/**
+* The third law as a RATIO, needing no constant, no mass and no SI units: `T₂ = T₁(a₂/a₁)^{3/2}`.
+*
+* The form to use whenever a question gives you one orbit and asks about another, which is most of
+* them. Units cancel, so days and astronomical units are as good as seconds and metres, and a
+* learner who converts everything to SI first has done real work for no marks.
+*/
+function keplerRatio(knownPeriod, knownAxis, targetAxis, sf = 4) {
+	const ratio = positive(targetAxis, "axis") / positive(knownAxis, "axis");
+	const value = positive(knownPeriod, "period") * ratio ** 1.5;
+	return calc().step("\\frac{T_1^2}{a_1^3} = \\frac{T_2^2}{a_2^3}", "the same constant for everything orbiting the same body").step("T_2 = T_1\\left(\\frac{a_2}{a_1}\\right)^{3/2}", "no G, no mass, and no need for SI: whatever units the periods are in, the answer comes back in").step(`T_2 = ${texSigFigs(knownPeriod, sf)} \\times (${texSigFigs(ratio, sf)})^{3/2}`).step(`T_2 = ${texSigFigs(value, sf)}`).done(value);
+}
+/**
+* The mass of a central body from ANY orbit around it: `M = 4π²a³/GT²`.
+*
+* How everything in the sky has ever been weighed. Point a telescope at a moon, time one circuit,
+* measure the distance, and the planet's mass drops out. It is worth pausing on what is NOT needed:
+* you never go there, you never touch it, and the orbiting body's own mass cancels and is never
+* required either.
+*
+* Returns the mass, with `mu` alongside, since `mu` is the honest quantity: `mu = 4π²a³/T²` is
+* measured directly and accurately, and dividing by `G` to get `M` throws away six figures of it.
+*/
+function centralMassFromOrbit(semiMajorAxis, period, G = GRAVITATIONAL_CONSTANT, sf = 4) {
+	const a = positive(semiMajorAxis, "semi-major axis");
+	const T = positive(period, "period");
+	const mu = 4 * Math.PI ** 2 * a ** 3 / (T * T);
+	const mass = mu / G;
+	return {
+		mass,
+		mu,
+		worked: calc().step("\\frac{GMm}{a^2} = \\frac{4\\pi^2 m a}{T^2}", "gravity supplying the centripetal requirement, with omega written as 2 pi over T").step("M = \\frac{4\\pi^2 a^3}{G T^2}", "the ORBITING mass cancels, so a pebble weighs the planet as well as a moon does").step(`GM = \\frac{4\\pi^2 (${texSigFigs(a, sf)})^3}{(${texSigFigs(T, sf)})^2} = ${texSigFigs(mu, sf)}\\ \\mathrm{m^3\\,s^{-2}}`, "this product is what the measurement actually gives you, and it is good to many figures").step(`M = ${texSigFigs(mass, sf)}\\ \\mathrm{kg}`, "dividing by G costs most of that precision, because G is the worst-known constant in physics").done(mass)
+	};
+}
+/**
+* The synodic period: how often two orbiting bodies line up again. `1/T_syn = |1/T₁ − 1/T₂|`.
+*
+* The difference between a year and the time between two oppositions of Mars, and the reason launch
+* windows to Mars come round every 26 months rather than every 12 or 23. It is a beat frequency,
+* exactly like two waves of different pitch, which is a connection worth making across topics.
+*/
+function synodicPeriod(period1, period2) {
+	const difference = Math.abs(1 / positive(period1, "period") - 1 / positive(period2, "period"));
+	if (difference === 0) return Infinity;
+	return 1 / difference;
+}
+/**
+* Kepler's equation, `M = E − e·sin E`, solved for the eccentric anomaly by Newton-Raphson.
+*
+* THE OLDEST UNSOLVED-IN-CLOSED-FORM PROBLEM in the syllabus, and worth telling students about:
+* there is no way to rearrange it, and every planetarium in the world iterates. Kepler himself said
+* he could see no method and invited someone else to find one; nobody has, and it was later proved
+* impossible in elementary functions.
+*
+* Migrated from `labs/src/physics/orbital/core.ts`, which owned it privately. The starting guess is
+* `π` for high eccentricity rather than `M`, because `M` converges slowly for the elongated orbits
+* where the equation matters most.
+*/
+function solveEccentricAnomaly(meanAnomaly, eccentricity, tolerance = 1e-12, maxIterations = 30) {
+	const e = checkEccentricity(eccentricity);
+	const turns = Math.floor(meanAnomaly / TAU);
+	const normalised = meanAnomaly - turns * TAU;
+	let anomaly = e < .8 ? normalised : Math.PI;
+	for (let iteration = 0; iteration < maxIterations; iteration++) {
+		const delta = (anomaly - e * Math.sin(anomaly) - normalised) / (1 - e * Math.cos(anomaly));
+		anomaly -= delta;
+		if (Math.abs(delta) <= tolerance) break;
+	}
+	return anomaly + turns * TAU;
+}
+/**
+* Position on an ellipse at a given mean anomaly, with the attracting body at the ORIGIN.
+*
+* The origin is the FOCUS, not the centre of the ellipse, which is Kepler's first law expressed as a
+* coordinate choice rather than as a sentence. Drawing an orbit with the planet at the centre is the
+* commonest illustration error in textbooks and it makes the second law look arbitrary.
+*
+* Mean anomaly advances uniformly with time (`M = 2πt/T`), which is what makes this drawable from a
+* clock: a lab steps the mean anomaly linearly and the body visibly hurries through periapsis
+* without anything in the animation code knowing why.
+*/
+function orbitPointAtMeanAnomaly(semiMajorAxis, eccentricity, meanAnomaly) {
+	const a = positive(semiMajorAxis, "semi-major axis");
+	const e = checkEccentricity(eccentricity);
+	const eccentricAnomaly = solveEccentricAnomaly(meanAnomaly, e);
+	const x = a * (Math.cos(eccentricAnomaly) - e);
+	const y = a * Math.sqrt(1 - e * e) * Math.sin(eccentricAnomaly);
+	return {
+		x,
+		y,
+		radius: a * (1 - e * Math.cos(eccentricAnomaly)),
+		trueAnomaly: Math.atan2(y, x),
+		eccentricAnomaly
+	};
+}
+/**
+* The same, but from a TIME and a period rather than an anomaly, which is what an animation has.
+*
+* `t = 0` is periapsis. A lab driving this from its clock gets Kepler's second law for free: no part
+* of the rendering has to know that the body should speed up, it simply does.
+*/
+function orbitPointAtTime(semiMajorAxis, eccentricity, timeS, periodS) {
+	return orbitPointAtMeanAnomaly(semiMajorAxis, eccentricity, TAU * timeS / positive(periodS, "period"));
+}
+
+//#endregion
+export { apsides, apsisSpeeds, arealVelocity, axisFromPeriod, centralMassFromOrbit, keplerRatio, orbitFromApsides, orbitPointAtMeanAnomaly, orbitPointAtTime, periodFromAxis, semiMinorAxis, solveEccentricAnomaly, specificAngularMomentum, synodicPeriod };

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

@@ -0,0 +1,117 @@
+import { Worked } from "../../core/worked.mjs";
+import { Polar } from "../vectors.mjs";
+
+//#region src/physics/gravitation/law.d.ts
+/**
+ * The attraction between two point masses: `F = Gm₁m₂/r²`.
+ *
+ * `separation` is measured CENTRE TO CENTRE, which is the assumption doing the most quiet work in
+ * the chapter: a planet is not a point, and the only reason it may be treated as one is the shell
+ * theorem, proved in `potential.ts`. A question about a mass on the surface uses the planet's
+ * RADIUS, not the height above the ground, and that substitution is where answers go wrong by
+ * factors of millions.
+ */
+declare function gravitationalForce(mass1: number, mass2: number, separation: number, G?: number): number;
+/**
+ * The same, showing its working.
+ *
+ * Split from the bare value deliberately, and the split is not stylistic. A lab redrawing a force
+ * arrow as a learner drags a satellite calls this sixty times a second, and building a LaTeX
+ * derivation on every frame to throw it away is waste that shows up as dropped frames on a
+ * mid-range phone. Every function in this kernel that has both forms follows the same rule: the
+ * bare one for the pixels, the `Steps` one for the page.
+ */
+declare function gravitationalForceSteps(mass1: number, mass2: number, separation: number, G?: number, sf?: number): Worked;
+/**
+ * How the force changes when the separation is scaled: `F' / F = 1/k²`.
+ *
+ * A ratio, so no constant and no masses. Named because "three times as far is a NINTH of the pull"
+ * is the sentence the inverse square law is, and it is worth a function that can be shown rather
+ * than a fact to be asserted.
+ */
+declare function inverseSquareFactor(distanceFactor: number): number;
+/** A point source of gravity at a position in the plane. */
+interface GravitySource {
+  readonly name?: string;
+  readonly mass: number;
+  readonly x: number;
+  readonly y: number;
+}
+/** The pull from each source, plus the vector sum. */
+interface NetGravity {
+  /** One entry per source, in the order given. */
+  readonly contributions: readonly (Polar & {
+    readonly from: string;
+  })[];
+  readonly x: number;
+  readonly y: number;
+  /** The resultant, as a size and a direction above the horizontal. */
+  readonly resultant: Polar;
+}
+/**
+ * The net gravitational force on a mass at a point, from any number of sources.
+ *
+ * THE FUNCTION THIS FILE EXISTS FOR. Each source contributes an attraction along the line joining
+ * it, and the answer is the vector sum, recombined by `compose` so that the resultant's DIRECTION
+ * comes out alongside its size. A question that asks only for the magnitude is still a vector
+ * question, and answering it by adding two numbers is the error this is built to make visible: the
+ * Sun pulls the Moon about twice as hard as the Earth does, yet the Moon orbits the Earth, and the
+ * reconciliation is entirely in the directions.
+ */
+declare function netGravitationalForce(at: {
+  readonly x: number;
+  readonly y: number;
+  readonly mass: number;
+}, sources: readonly GravitySource[], G?: number): NetGravity;
+/**
+ * Where the pull of two bodies cancels, measured from the FIRST: `d₁ = d / (1 + √(M₂/M₁))`.
+ *
+ * The neutral point, and a question that needs neither `G` nor either mass on its own. Both cancel
+ * when the forces are set equal, leaving only the square root of the mass ratio, which is why the
+ * Earth-Moon point sits at nine tenths rather than at the middle: the Earth is 81 times heavier and
+ * √81 is 9, not 81.
+ *
+ * Note the point is nearer the LIGHTER body, which students consistently get backwards on instinct.
+ */
+declare function nullPoint(mass1: number, mass2: number, separation: number, sf?: number): Worked;
+/**
+ * The tidal (differential) acceleration across a body of given size: `Δg ≈ 2·mu·s / d³`.
+ *
+ * The stretch a distant mass applies, which is what a tide actually is. The `1/d³` is the whole
+ * story and is worth deriving in front of a student: differentiate `mu/d²` and the power drops.
+ *
+ * `size` is the half-width, so pass the Earth's RADIUS for the ocean bulge on one side, and the
+ * factor of 2 accounts for the far side being stretched outwards just as the near side is pulled
+ * inwards. That symmetry is why there are two high tides a day and not one, which is the question
+ * every learner asks and almost no textbook answers.
+ */
+declare function tidalAcceleration(mu: number, distance: number, size: number): number;
+/**
+ * How much bigger a tide one body raises than another: the comparison that settles the Sun-Moon
+ * argument.
+ *
+ * The Sun pulls the Earth about 175 times harder than the Moon does, and yet raises a tide less
+ * than half the size. Nothing about that is paradoxical once the `1/d³` is believed, and until it
+ * is believed the two facts look contradictory. Returns the ratio of the first body's tide to the
+ * second's, with the working that reconciles them.
+ */
+declare function tideRatio(a: {
+  readonly mu: number;
+  readonly distance: number;
+  readonly name?: string;
+}, b: {
+  readonly mu: number;
+  readonly distance: number;
+  readonly name?: string;
+}, sf?: number): Worked;
+/**
+ * The Roche limit for a rigid satellite: `d = R(2ρ_M/ρ_m)^{1/3}`.
+ *
+ * Inside it, the tidal stretch beats the moon's own gravity and it comes apart, which is where
+ * planetary rings come from: Saturn's rings sit inside its Roche limit and its moons sit outside.
+ * The rule is not arbitrary trivia, it is the same differential gravity as the tide, taken to the
+ * point where the difference exceeds what holds the body together.
+ */
+declare function rocheLimit(primaryRadius: number, primaryDensity: number, satelliteDensity: number): number;
+//#endregion
+export { GravitySource, NetGravity, gravitationalForce, gravitationalForceSteps, inverseSquareFactor, netGravitationalForce, nullPoint, rocheLimit, tidalAcceleration, tideRatio };

package/dist/physics/gravitation/law.mjs

@@ -0,0 +1,175 @@
+import { GRAVITATIONAL_CONSTANT } from "../../core/constants.mjs";
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { compose } from "../vectors.mjs";
+
+//#region src/physics/gravitation/law.ts
+/**
+* Newton's law of gravitation, and the two things it implies that students never connect to it.
+*
+* ── The law is trivial. The SUPERPOSITION is the subject ────────────────────────────────────────
+* `F = Gm₁m₂/r²` is one line and nobody fails it. What questions actually test is that gravity from
+* several bodies ADDS AS VECTORS, and that is where the marks go: the Earth pulls the Moon one way
+* and the Sun pulls it another, and the answer is not the sum of two numbers, it is the sum of two
+* arrows. A student who adds magnitudes gets a plausible-looking wrong answer with no warning.
+*
+* So this file does not own any vector arithmetic. It resolves into components with `resolve` and
+* recombines with `compose`, from `vectors.ts`, exactly as the projectile and ramp kernels do. The
+* point of teaching vectors once is that gravitation is then not a new skill.
+*
+* ── The null point, and why it is a mass RATIO question ─────────────────────────────────────────
+* "Where between the Earth and the Moon does the net pull vanish?" looks like it needs both masses
+* and the constant. It needs neither. Setting the two forces equal cancels `G` and the test mass,
+* and leaves `√(M₁/M₂)` dividing the separation. The Earth is 81 times the Moon, `√81 = 9`, so the
+* point sits nine tenths of the way across. Students who do not see the cancellation grind through
+* a quadratic and usually lose the root that lies outside the pair.
+*
+* ── Tides, which are not gravity but the DIFFERENCE in gravity ──────────────────────────────────
+* The commonest misconception in the whole chapter is that the Moon "lifts" the oceans. It does not:
+* the Moon's pull at the Earth is 3×10⁻⁵ m/s², a millionth of `g`, and it pulls the ocean and the
+* seabed almost identically. What raises a tide is the tiny DIFFERENCE across the Earth's diameter,
+* which falls off as `1/d³` rather than `1/d²`. That cube is why the Sun, despite pulling on the
+* Earth 175 times harder than the Moon does, raises a tide less than half the size.
+*
+* 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;
+};
+/**
+* The attraction between two point masses: `F = Gm₁m₂/r²`.
+*
+* `separation` is measured CENTRE TO CENTRE, which is the assumption doing the most quiet work in
+* the chapter: a planet is not a point, and the only reason it may be treated as one is the shell
+* theorem, proved in `potential.ts`. A question about a mass on the surface uses the planet's
+* RADIUS, not the height above the ground, and that substitution is where answers go wrong by
+* factors of millions.
+*/
+function gravitationalForce(mass1, mass2, separation, G = GRAVITATIONAL_CONSTANT) {
+	const r = positive(separation, "separation");
+	return G * positive(mass1, "mass") * positive(mass2, "mass") / (r * r);
+}
+/**
+* The same, showing its working.
+*
+* Split from the bare value deliberately, and the split is not stylistic. A lab redrawing a force
+* arrow as a learner drags a satellite calls this sixty times a second, and building a LaTeX
+* derivation on every frame to throw it away is waste that shows up as dropped frames on a
+* mid-range phone. Every function in this kernel that has both forms follows the same rule: the
+* bare one for the pixels, the `Steps` one for the page.
+*/
+function gravitationalForceSteps(mass1, mass2, separation, G = GRAVITATIONAL_CONSTANT, sf = 3) {
+	const r = positive(separation, "separation");
+	const value = gravitationalForce(mass1, mass2, r, G);
+	return calc().step("F = \\frac{G m_1 m_2}{r^2}", "r is measured CENTRE to centre, not surface to surface").step(`F = \\frac{${texSigFigs(G, 4)} \\times ${texSigFigs(mass1, sf)} \\times ${texSigFigs(mass2, sf)}}{(${texSigFigs(r, sf)})^2}`).step(`F = ${texSigFigs(value, sf)}\\ \\mathrm{N}`, "equal and opposite on each mass, by Newton III").done(value);
+}
+/**
+* How the force changes when the separation is scaled: `F' / F = 1/k²`.
+*
+* A ratio, so no constant and no masses. Named because "three times as far is a NINTH of the pull"
+* is the sentence the inverse square law is, and it is worth a function that can be shown rather
+* than a fact to be asserted.
+*/
+function inverseSquareFactor(distanceFactor) {
+	const k = positive(distanceFactor, "distance factor");
+	return 1 / (k * k);
+}
+/**
+* The net gravitational force on a mass at a point, from any number of sources.
+*
+* THE FUNCTION THIS FILE EXISTS FOR. Each source contributes an attraction along the line joining
+* it, and the answer is the vector sum, recombined by `compose` so that the resultant's DIRECTION
+* comes out alongside its size. A question that asks only for the magnitude is still a vector
+* question, and answering it by adding two numbers is the error this is built to make visible: the
+* Sun pulls the Moon about twice as hard as the Earth does, yet the Moon orbits the Earth, and the
+* reconciliation is entirely in the directions.
+*/
+function netGravitationalForce(at, sources, G = GRAVITATIONAL_CONSTANT) {
+	const contributions = sources.map((source, index) => {
+		const dx = source.x - at.x;
+		const dy = source.y - at.y;
+		const r = Math.hypot(dx, dy);
+		if (r === 0) throw new RangeError("a test mass cannot sit exactly on a point source");
+		const magnitude = G * source.mass * at.mass / (r * r);
+		return {
+			from: source.name ?? `source ${index + 1}`,
+			magnitude,
+			angleDeg: compose(dx, dy).angleDeg
+		};
+	});
+	let x = 0;
+	let y = 0;
+	for (const source of sources) {
+		const dx = source.x - at.x;
+		const dy = source.y - at.y;
+		const r = Math.hypot(dx, dy);
+		const magnitude = G * source.mass * at.mass / (r * r);
+		x += magnitude * (dx / r);
+		y += magnitude * (dy / r);
+	}
+	return {
+		contributions,
+		x,
+		y,
+		resultant: compose(x, y)
+	};
+}
+/**
+* Where the pull of two bodies cancels, measured from the FIRST: `d₁ = d / (1 + √(M₂/M₁))`.
+*
+* The neutral point, and a question that needs neither `G` nor either mass on its own. Both cancel
+* when the forces are set equal, leaving only the square root of the mass ratio, which is why the
+* Earth-Moon point sits at nine tenths rather than at the middle: the Earth is 81 times heavier and
+* √81 is 9, not 81.
+*
+* Note the point is nearer the LIGHTER body, which students consistently get backwards on instinct.
+*/
+function nullPoint(mass1, mass2, separation, sf = 3) {
+	const d = positive(separation, "separation");
+	const ratio = Math.sqrt(positive(mass2, "mass") / positive(mass1, "mass"));
+	const value = d / (1 + ratio);
+	return calc().step("\\frac{G M_1 m}{x^2} = \\frac{G M_2 m}{(d-x)^2}", "the two pulls are equal and opposite, so their magnitudes match").step("\\frac{M_1}{x^2} = \\frac{M_2}{(d-x)^2}", "G cancels, and so does the test mass m. The answer cannot depend on what you put there").step("\\frac{d-x}{x} = \\sqrt{\\frac{M_2}{M_1}}", "take the square root of both sides rather than expanding into a quadratic").step(`x = \\frac{d}{1 + \\sqrt{M_2/M_1}} = \\frac{${texSigFigs(d, sf)}}{1 + ${texSigFigs(ratio, sf)}}`).step(`x = ${texSigFigs(value, sf)}\\ \\mathrm{m}`, "measured from the FIRST body. The point lies nearer the lighter one").done(value);
+}
+/**
+* The tidal (differential) acceleration across a body of given size: `Δg ≈ 2·mu·s / d³`.
+*
+* The stretch a distant mass applies, which is what a tide actually is. The `1/d³` is the whole
+* story and is worth deriving in front of a student: differentiate `mu/d²` and the power drops.
+*
+* `size` is the half-width, so pass the Earth's RADIUS for the ocean bulge on one side, and the
+* factor of 2 accounts for the far side being stretched outwards just as the near side is pulled
+* inwards. That symmetry is why there are two high tides a day and not one, which is the question
+* every learner asks and almost no textbook answers.
+*/
+function tidalAcceleration(mu, distance, size) {
+	const d = positive(distance, "distance");
+	return 2 * positive(mu, "gravitational parameter") * positive(size, "size") / d ** 3;
+}
+/**
+* How much bigger a tide one body raises than another: the comparison that settles the Sun-Moon
+* argument.
+*
+* The Sun pulls the Earth about 175 times harder than the Moon does, and yet raises a tide less
+* than half the size. Nothing about that is paradoxical once the `1/d³` is believed, and until it
+* is believed the two facts look contradictory. Returns the ratio of the first body's tide to the
+* second's, with the working that reconciles them.
+*/
+function tideRatio(a, b, sf = 3) {
+	const pullRatio = a.mu / b.mu * (b.distance / a.distance) ** 2;
+	const value = a.mu / b.mu * (b.distance / a.distance) ** 3;
+	return calc().step("g = \\frac{\\mu}{d^2} \\Rightarrow \\left|\\frac{dg}{dd}\\right| = \\frac{2\\mu}{d^3}", "a tide is not the pull, it is how fast the pull CHANGES across the body. Differentiate, and the power drops").step(`\\frac{F_a}{F_b} = \\frac{\\mu_a}{\\mu_b}\\left(\\frac{d_b}{d_a}\\right)^{2} = ${texSigFigs(pullRatio, sf)}`, `the raw pull: ${a.name ?? "the first"} wins by this much`).step(`\\frac{\\Delta g_a}{\\Delta g_b} = \\frac{\\mu_a}{\\mu_b}\\left(\\frac{d_b}{d_a}\\right)^{3} = ${texSigFigs(value, sf)}`, "the tide: one more power of distance, and the order can reverse entirely").done(value);
+}
+/**
+* The Roche limit for a rigid satellite: `d = R(2ρ_M/ρ_m)^{1/3}`.
+*
+* Inside it, the tidal stretch beats the moon's own gravity and it comes apart, which is where
+* planetary rings come from: Saturn's rings sit inside its Roche limit and its moons sit outside.
+* The rule is not arbitrary trivia, it is the same differential gravity as the tide, taken to the
+* point where the difference exceeds what holds the body together.
+*/
+function rocheLimit(primaryRadius, primaryDensity, satelliteDensity) {
+	return positive(primaryRadius, "radius") * (2 * (positive(primaryDensity, "density") / positive(satelliteDensity, "density"))) ** (1 / 3);
+}
+
+//#endregion
+export { gravitationalForce, gravitationalForceSteps, inverseSquareFactor, netGravitationalForce, nullPoint, rocheLimit, tidalAcceleration, tideRatio };