@classytic/stage 0.2.0 → 0.4.0

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

@@ -0,0 +1,73 @@
+import { Worked } from "../../core/worked.mjs";
+import { Sweep } from "../integral-sweep.mjs";
+
+//#region src/physics/energy/spring.d.ts
+interface SpringWork {
+  /** Work done BY the spring: negative when the spring is being stretched further from natural length. */
+  readonly bySpring: number;
+  /** Work done by whatever is pulling or pushing: the same size, opposite sign. */
+  readonly byAgent: number;
+  /** Energy stored at the start and at the end, both measured from the natural length. */
+  readonly storedBefore: number;
+  readonly storedAfter: number;
+  /** The integral, ready to animate: strips under the force-extension graph. */
+  readonly sweep: Sweep;
+  readonly worked: Worked;
+}
+/**
+ * The work a spring does as its extension goes from `from` to `to`.
+ *
+ * Both extensions are measured from the NATURAL length and are signed, so a compression is negative.
+ * The squares mean the answer only ever depends on the two magnitudes, which is why `−3 cm to 0` and
+ * `+3 cm to 0` give the same release.
+ *
+ * Their Type-04 strategy sheet says to integrate rather than to reach for the formula, and to place
+ * the limits carefully with their signs. That is exactly what happens below.
+ */
+declare function springWork(stiffness: number, from: number, to: number, sf?: number): SpringWork;
+/**
+ * The stiffness a second spring needs so that a stated stretch stores a stated multiple of the
+ * energy of the first.
+ *
+ * Their Example-14, and a genuinely good question, because it cannot be answered by substituting
+ * into `½kx²` once. It has to be answered by the RATIO, where everything shared cancels and what is
+ * left is `k ∝ W/x²`. Returning the ratio as well as the stiffness is deliberate: the ratio is the
+ * transferable part.
+ */
+declare function stiffnessForEnergyRatio(stiffness: number, energyRatio: number, extensionRatio: number, sf?: number): {
+  readonly stiffness: number;
+  readonly ratio: number;
+  readonly worked: Worked;
+};
+interface SpringLaunch {
+  /** Speed of the body once the spring reaches its natural length. */
+  readonly speed: number;
+  readonly storedEnergy: number;
+  /** Energy lost to friction over the release, zero on a smooth surface. */
+  readonly lostToFriction: number;
+  readonly kineticEnergy: number;
+  readonly worked: Worked;
+}
+/**
+ * A compressed spring released against a block: how fast the block leaves.
+ *
+ * Optional friction, because the pair of questions "smooth" then "now with friction" is the standard
+ * way this is examined, and the second one is only harder in that one term joins the ledger. The
+ * ledger is the lesson: what the spring stored either ends up as motion or ends up as heat, and
+ * there is nowhere else for it to go.
+ */
+declare function springLaunch(stiffness: number, compression: number, mass: number, frictionForce?: number, sf?: number): SpringLaunch;
+/**
+ * How far a moving block compresses a spring before it stops.
+ *
+ * The launch run backwards, and the standard way a work-energy question is dressed up. The answer
+ * comes out as a magnitude and is then given a negative sign, because the spring was compressed:
+ * that last move is the one worth watching, since the square root cannot know which way the block
+ * came from.
+ */
+declare function springCompressionToStop(stiffness: number, mass: number, speed: number, sf?: number): {
+  readonly compression: number;
+  readonly worked: Worked;
+};
+//#endregion
+export { SpringLaunch, SpringWork, springCompressionToStop, springLaunch, springWork, stiffnessForEnergyRatio };

package/dist/physics/energy/spring.mjs

@@ -0,0 +1,129 @@
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { sweep } from "../integral-sweep.mjs";
+
+//#region src/physics/energy/spring.ts
+/**
+* The spring: the first force a student meets that is not constant, and the reason work became an
+* integral.
+*
+* `W = Fd` is useless here, because there is no single `F`. The force grows as you stretch, so the
+* honest answer is to add up `F dx` over strips, and that is `∫kx dx = ½kx²`. This module performs
+* that integral SYMBOLICALLY through the shared integrator rather than quoting `½kx²` as a fact, so
+* the derivation a lab prints is the mathematics the engine actually did. The same `sweep` that
+* animates a moment of inertia animates this one, because the picture (strips accumulating under a
+* graph) is identical.
+*
+* THE SIGN IS THE WHOLE TOPIC, and it is where every mark is lost. Two different forces act during
+* the same stretch:
+*
+*   - the SPRING pulls back towards the natural length: `F_spring = −kx`;
+*   - the AGENT doing the stretching pulls outwards: `F_agent = +kx`.
+*
+* They are equal and opposite, so their works are equal and opposite. Stretching a spring from rest
+* to `x`, the agent does `+½kx²` and the spring does `−½kx²`. Releasing it, the two swap. A question
+* asking for "the work done by the spring" and one asking for "the work done in stretching the
+* spring" therefore differ by a minus sign and by nothing else, and `springWork` returns both rather
+* than making the caller guess which one it meant.
+*
+* Pure: no React, no pixels.
+*/
+/**
+* The work a spring does as its extension goes from `from` to `to`.
+*
+* Both extensions are measured from the NATURAL length and are signed, so a compression is negative.
+* The squares mean the answer only ever depends on the two magnitudes, which is why `−3 cm to 0` and
+* `+3 cm to 0` give the same release.
+*
+* Their Type-04 strategy sheet says to integrate rather than to reach for the formula, and to place
+* the limits carefully with their signs. That is exactly what happens below.
+*/
+function springWork(stiffness, from, to, sf = 3) {
+	const s = sweep({
+		element: "-k*x",
+		variable: "x",
+		from: "xi",
+		to: "xf"
+	}, {
+		k: stiffness,
+		xi: from,
+		xf: to
+	});
+	const storedBefore = .5 * stiffness * from * from;
+	const storedAfter = .5 * stiffness * to * to;
+	const bySpring = s.total;
+	const worked = calc().step("F_{\\text{spring}} = -kx", "the force is not constant, so W = Fd does not apply. It grows in proportion to how far the spring is from its natural length").step("W = \\int_{x_i}^{x_f} F\\,dx = \\int_{x_i}^{x_f} -kx\\,dx = -\\tfrac{1}{2}k\\left[x^2\\right]_{x_i}^{x_f}", "add up F dx over strips. The area under the force-extension graph IS the work").step(`W_{\\text{spring}} = \\tfrac{1}{2}k\\left(x_i^2 - x_f^2\\right) = \\tfrac{1}{2} \\times ${texSigFigs(stiffness, sf)} \\times \\left(${texSigFigs(from, sf)}^2 - ${texSigFigs(to, sf)}^2\\right)`).step(`W_{\\text{spring}} = ${texSigFigs(bySpring, sf)}\\ \\mathrm{J}`, bySpring >= 0 ? "positive: the spring is returning towards its natural length, so it is giving energy back" : "negative: the spring is being taken further from its natural length, so it is absorbing energy").step(`W_{\\text{agent}} = -W_{\\text{spring}} = ${texSigFigs(-bySpring, sf)}\\ \\mathrm{J}`, "the puller and the spring exert equal and opposite forces over the same displacement, so their works differ only in sign").step(`E_{\\text{stored}}: ${texSigFigs(storedBefore, sf)} \\rightarrow ${texSigFigs(storedAfter, sf)}\\ \\mathrm{J}`, "and the change in the store is exactly minus the work the spring did").done(bySpring);
+	return {
+		bySpring,
+		byAgent: -bySpring,
+		storedBefore,
+		storedAfter,
+		sweep: s,
+		worked
+	};
+}
+/**
+* The stiffness a second spring needs so that a stated stretch stores a stated multiple of the
+* energy of the first.
+*
+* Their Example-14, and a genuinely good question, because it cannot be answered by substituting
+* into `½kx²` once. It has to be answered by the RATIO, where everything shared cancels and what is
+* left is `k ∝ W/x²`. Returning the ratio as well as the stiffness is deliberate: the ratio is the
+* transferable part.
+*/
+function stiffnessForEnergyRatio(stiffness, energyRatio, extensionRatio, sf = 3) {
+	if (extensionRatio === 0) throw new Error("A second spring stretched by nothing stores nothing, so no stiffness satisfies the ratio.");
+	const ratio = energyRatio / (extensionRatio * extensionRatio);
+	const value = stiffness * ratio;
+	return {
+		stiffness: value,
+		ratio,
+		worked: calc().step("W = \\tfrac{1}{2}kx^2", "write it for both springs rather than evaluating either").step("\\frac{W_2}{W_1} = \\frac{k_2}{k_1}\\left(\\frac{x_2}{x_1}\\right)^2", "dividing kills the half and any shared quantity. What survives is the only thing the question is about").step(`\\frac{k_2}{k_1} = \\frac{W_2}{W_1} \\div \\left(\\frac{x_2}{x_1}\\right)^2 = ${texSigFigs(energyRatio, sf)} \\div ${texSigFigs(extensionRatio * extensionRatio, sf)} = ${texSigFigs(ratio, sf)}`).step(`k_2 = ${texSigFigs(ratio, sf)}k_1 = ${texSigFigs(value, sf)}\\ \\mathrm{N\\,m^{-1}}`, "halving the stretch while doubling the energy needs eight times the stiffness, because the extension enters squared").done(value)
+	};
+}
+/**
+* A compressed spring released against a block: how fast the block leaves.
+*
+* Optional friction, because the pair of questions "smooth" then "now with friction" is the standard
+* way this is examined, and the second one is only harder in that one term joins the ledger. The
+* ledger is the lesson: what the spring stored either ends up as motion or ends up as heat, and
+* there is nowhere else for it to go.
+*/
+function springLaunch(stiffness, compression, mass, frictionForce = 0, sf = 3) {
+	const storedEnergy = .5 * stiffness * compression * compression;
+	const lostToFriction = frictionForce * Math.abs(compression);
+	const kineticEnergy = storedEnergy - lostToFriction;
+	if (kineticEnergy < 0) throw new Error(`Friction would absorb ${lostToFriction.toPrecision(3)} J over that distance but the spring only stored ${storedEnergy.toPrecision(3)} J, so the block never reaches the natural length. It stops inside the spring.`);
+	const speed = Math.sqrt(2 * kineticEnergy / mass);
+	const w = calc().step("E_{\\text{stored}} = E_k + E_{\\text{lost}}", "the ledger. Everything the spring stored goes to motion or to heat, and nowhere else");
+	w.step(`E_{\\text{stored}} = \\tfrac{1}{2}kx^2 = \\tfrac{1}{2} \\times ${texSigFigs(stiffness, sf)} \\times ${texSigFigs(compression, sf)}^2 = ${texSigFigs(storedEnergy, sf)}\\ \\mathrm{J}`);
+	if (frictionForce !== 0) w.step(`E_{\\text{lost}} = fx = ${texSigFigs(frictionForce, sf)} \\times ${texSigFigs(Math.abs(compression), sf)} = ${texSigFigs(lostToFriction, sf)}\\ \\mathrm{J}`, "friction acts over the SAME distance the spring pushes through, which is the compression");
+	w.step(`E_k = ${texSigFigs(kineticEnergy, sf)}\\ \\mathrm{J}`, frictionForce === 0 ? "nothing is lost on a smooth surface" : "what is left over becomes motion");
+	w.step(`v = \\sqrt{\\frac{2E_k}{m}} = ${texSigFigs(speed, sf)}\\ \\mathrm{m\\,s^{-1}}`, "measured at the natural length, where the spring stops pushing");
+	return {
+		speed,
+		storedEnergy,
+		lostToFriction,
+		kineticEnergy,
+		worked: w.done(speed)
+	};
+}
+/**
+* How far a moving block compresses a spring before it stops.
+*
+* The launch run backwards, and the standard way a work-energy question is dressed up. The answer
+* comes out as a magnitude and is then given a negative sign, because the spring was compressed:
+* that last move is the one worth watching, since the square root cannot know which way the block
+* came from.
+*/
+function springCompressionToStop(stiffness, mass, speed, sf = 3) {
+	const kinetic = .5 * mass * speed * speed;
+	const magnitude = Math.sqrt(2 * kinetic / stiffness);
+	const worked = calc().step("\\Delta E_k = W_{\\text{spring}}", "the work-energy theorem. The spring is the only thing doing work, so it must absorb all the motion").step(`0 - \\tfrac{1}{2}mv^2 = -\\tfrac{1}{2}kx^2 \\Rightarrow x^2 = \\frac{mv^2}{k} = \\frac{${texSigFigs(mass, sf)} \\times ${texSigFigs(speed, sf)}^2}{${texSigFigs(stiffness, sf)}}`).step(`x = ${texSigFigs(-magnitude, sf)}\\ \\mathrm{m}`, "the square root gives a size only. The negative sign is put back by hand, because the spring was COMPRESSED and extensions are measured as positive").done(-magnitude);
+	return {
+		compression: -magnitude,
+		worked
+	};
+}
+
+//#endregion
+export { springCompressionToStop, springLaunch, springWork, stiffnessForEnergyRatio };

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

@@ -0,0 +1,63 @@
+import { Worked } from "../../core/worked.mjs";
+
+//#region src/physics/energy/store.d.ts
+/** `Ek = ½mv²`. Always positive: the speed is squared, so the direction of travel cannot enter. */
+declare function kineticEnergy(mass: number, speed: number, sf?: number): Worked;
+/**
+ * `Ek = p²/2m`, kinetic energy straight from momentum.
+ *
+ * Derived rather than asserted, because the derivation is two lines and the alternative is a fourth
+ * formula to remember. It matters beyond exam convenience: it is the form that says a heavy slow
+ * body and a light fast one can carry the same momentum while carrying wildly different energies,
+ * which is the whole reason a bullet and a truck are dangerous in different ways.
+ */
+declare function kineticFromMomentum(momentum: number, mass: number, sf?: number): Worked;
+/** The momentum a body of known kinetic energy carries: `p = √(2mEk)`. */
+declare function momentumFromKinetic(kinetic: number, mass: number, sf?: number): Worked;
+/** The speed a stated kinetic energy corresponds to: `v = √(2Ek/m)`. */
+declare function speedFromKinetic(kinetic: number, mass: number, sf?: number): Worked;
+/**
+ * Kinetic energy from a velocity given as components, in any number of dimensions.
+ *
+ * The useful lesson is in the middle step: you square the MAGNITUDE, which means squaring each
+ * component and adding, never squaring the components separately and calling each one an energy.
+ * Energy has no components to be resolved into.
+ */
+declare function kineticFromVelocity(mass: number, velocity: readonly number[], sf?: number): Worked;
+interface PotentialResult {
+  readonly value: number;
+  /** Height above the chosen reference, which is what actually went into the formula. */
+  readonly heightAboveReference: number;
+  readonly worked: Worked;
+}
+/**
+ * `Ep = mgh`, with the reference level stated out loud.
+ *
+ * Both heights are measured from the same arbitrary origin, and `h` in the formula is their
+ * DIFFERENCE. Making the caller name the reference is the point: a body on the floor has zero
+ * potential energy relative to the floor, `+mgh` relative to the basement, and `−mgh` relative to
+ * the table, and all three are correct at once. Only the change between two levels is ever measured
+ * by an experiment, which is why the arbitrariness never causes trouble.
+ */
+declare function gravitationalPE(mass: number, height: number, referenceLevel?: number, g?: number, sf?: number): PotentialResult;
+/**
+ * Work done against gravity between two radii of a spherical body: `W = GMm(1/r_a − 1/r_b)`.
+ *
+ * The far-field version, for when `mgh` will not do because `g` itself has changed over the journey.
+ * The final step shows the two collapsing into one another for a small rise, which is the connection
+ * a syllabus asserts and rarely demonstrates: `mgh` is not a different law, it is this law with the
+ * denominator barely moving.
+ */
+declare function gravitationalWork(centralMass: number, mass: number, fromRadius: number, toRadius: number, G?: number, sf?: number): Worked;
+/**
+ * `Ep = ½kx²`, the energy stored in a spring stretched or compressed by `x` from its natural length.
+ *
+ * `x` is squared, so stretching and compressing by the same amount store the same energy. That is
+ * worth stating because a compression is usually written as a negative extension and a learner who
+ * carries the minus sign into an energy gets a negative store, which is impossible.
+ *
+ * The derivation lives in `spring.ts`, where the integral is actually performed rather than quoted.
+ */
+declare function elasticPE(stiffness: number, extension: number, sf?: number): Worked;
+//#endregion
+export { PotentialResult, elasticPE, gravitationalPE, gravitationalWork, kineticEnergy, kineticFromMomentum, kineticFromVelocity, momentumFromKinetic, speedFromKinetic };

package/dist/physics/energy/store.mjs

@@ -0,0 +1,108 @@
+import { GRAVITATIONAL_CONSTANT } from "../../core/constants.mjs";
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { G_EARTH } from "../kinematics/free-fall.mjs";
+
+//#region src/physics/energy/store.ts
+/**
+* The energy stores, and the conversions between the ways of naming the same one.
+*
+* A body in motion has one kinetic energy. It can be written from the speed, from the momentum, or
+* from the components of a velocity vector, and a question will hand you whichever of those is least
+* convenient. These are not three quantities; they are three doors into one room, and a learner who
+* has only memorised `½mv²` will stall on a momentum-first question that is genuinely no harder.
+*
+* THE SUBTLETY THAT ACTUALLY COSTS MARKS is not here in the kinetic energy at all. It is that
+* gravitational potential energy has NO ABSOLUTE VALUE. It is always measured from a level you
+* chose, and a body below that level has a NEGATIVE potential energy, which is not a mistake and not
+* a sign error. `gravitationalPE` therefore takes the reference level explicitly instead of quietly
+* assuming the ground, because the assumption is exactly the thing being taught.
+*
+* Pure: no React, no pixels.
+*/
+/** `Ek = ½mv²`. Always positive: the speed is squared, so the direction of travel cannot enter. */
+function kineticEnergy(mass, speed, sf = 3) {
+	const value = .5 * mass * speed * speed;
+	return calc().step("E_k = \\tfrac{1}{2}mv^2").step(`E_k = \\tfrac{1}{2} \\times ${texSigFigs(mass, sf)} \\times ${texSigFigs(speed, sf)}^2 = ${texSigFigs(value, sf)}\\ \\mathrm{J}`, "v is squared, so a body moving backwards has the same kinetic energy as one moving forwards. Kinetic energy is never negative").done(value);
+}
+/**
+* `Ek = p²/2m`, kinetic energy straight from momentum.
+*
+* Derived rather than asserted, because the derivation is two lines and the alternative is a fourth
+* formula to remember. It matters beyond exam convenience: it is the form that says a heavy slow
+* body and a light fast one can carry the same momentum while carrying wildly different energies,
+* which is the whole reason a bullet and a truck are dangerous in different ways.
+*/
+function kineticFromMomentum(momentum, mass, sf = 3) {
+	const value = momentum * momentum / (2 * mass);
+	return calc().step("p = mv \\Rightarrow v = \\frac{p}{m}", "start from the definition of momentum and make v the subject").step("E_k = \\tfrac{1}{2}mv^2 = \\tfrac{1}{2}m\\left(\\frac{p}{m}\\right)^2 = \\frac{p^2}{2m}", "substitute and let one factor of m cancel. This is not a new formula, it is the old one in different clothes").step(`E_k = \\frac{${texSigFigs(momentum, sf)}^2}{2 \\times ${texSigFigs(mass, sf)}} = ${texSigFigs(value, sf)}\\ \\mathrm{J}`).done(value);
+}
+/** The momentum a body of known kinetic energy carries: `p = √(2mEk)`. */
+function momentumFromKinetic(kinetic, mass, sf = 3) {
+	const value = Math.sqrt(2 * mass * kinetic);
+	return calc().step("E_k = \\frac{p^2}{2m} \\Rightarrow p = \\sqrt{2mE_k}").step(`p = \\sqrt{2 \\times ${texSigFigs(mass, sf)} \\times ${texSigFigs(kinetic, sf)}} = ${texSigFigs(value, sf)}\\ \\mathrm{kg\\,m\\,s^{-1}}`).done(value);
+}
+/** The speed a stated kinetic energy corresponds to: `v = √(2Ek/m)`. */
+function speedFromKinetic(kinetic, mass, sf = 3) {
+	if (kinetic < 0) throw new Error("Kinetic energy cannot be negative, so no speed corresponds to it.");
+	const value = Math.sqrt(2 * kinetic / mass);
+	return calc().step("E_k = \\tfrac{1}{2}mv^2 \\Rightarrow v = \\sqrt{\\frac{2E_k}{m}}").step(`v = \\sqrt{\\frac{2 \\times ${texSigFigs(kinetic, sf)}}{${texSigFigs(mass, sf)}}} = ${texSigFigs(value, sf)}\\ \\mathrm{m\\,s^{-1}}`, "the speed only. Kinetic energy is a scalar and cannot tell you which way the body is going").done(value);
+}
+/**
+* Kinetic energy from a velocity given as components, in any number of dimensions.
+*
+* The useful lesson is in the middle step: you square the MAGNITUDE, which means squaring each
+* component and adding, never squaring the components separately and calling each one an energy.
+* Energy has no components to be resolved into.
+*/
+function kineticFromVelocity(mass, velocity, sf = 3) {
+	const squared = velocity.reduce((sum, c) => sum + c * c, 0);
+	const value = .5 * mass * squared;
+	return calc().step("v^2 = v_x^2 + v_y^2 + v_z^2", "square each component and add. This gives the square of the SPEED, which is the scalar the energy needs").step(`v^2 = ${velocity.map((c) => `${texSigFigs(c, sf)}^2`).join(" + ")} = ${texSigFigs(squared, sf)}`).step(`E_k = \\tfrac{1}{2} \\times ${texSigFigs(mass, sf)} \\times ${texSigFigs(squared, sf)} = ${texSigFigs(value, sf)}\\ \\mathrm{J}`, "one number, with no direction. There is no such thing as the x-component of an energy").done(value);
+}
+/**
+* `Ep = mgh`, with the reference level stated out loud.
+*
+* Both heights are measured from the same arbitrary origin, and `h` in the formula is their
+* DIFFERENCE. Making the caller name the reference is the point: a body on the floor has zero
+* potential energy relative to the floor, `+mgh` relative to the basement, and `−mgh` relative to
+* the table, and all three are correct at once. Only the change between two levels is ever measured
+* by an experiment, which is why the arbitrariness never causes trouble.
+*/
+function gravitationalPE(mass, height, referenceLevel = 0, g = G_EARTH, sf = 3) {
+	const h = height - referenceLevel;
+	const value = mass * g * h;
+	return {
+		value,
+		heightAboveReference: h,
+		worked: calc().step("E_p = mgh", "h is measured from a level YOU choose. The choice is free, and different choices give different values that are all correct").step(`h = ${texSigFigs(height, sf)} - ${texSigFigs(referenceLevel, sf)} = ${texSigFigs(h, sf)}\\ \\mathrm{m}`, "height above the chosen reference").step(`E_p = ${texSigFigs(mass, sf)} \\times ${texSigFigs(g, sf)} \\times ${texSigFigs(h, sf)} = ${texSigFigs(value, sf)}\\ \\mathrm{J}`, h < 0 ? "negative, because the body sits BELOW the reference. This is a correct answer, not a sign slip" : "positive: the body is above the reference level").step("\\Delta E_p = mg\\,\\Delta h", "the reference cancels out of any CHANGE, which is why the arbitrary choice never affects a physical answer").done(value)
+	};
+}
+/**
+* Work done against gravity between two radii of a spherical body: `W = GMm(1/r_a − 1/r_b)`.
+*
+* The far-field version, for when `mgh` will not do because `g` itself has changed over the journey.
+* The final step shows the two collapsing into one another for a small rise, which is the connection
+* a syllabus asserts and rarely demonstrates: `mgh` is not a different law, it is this law with the
+* denominator barely moving.
+*/
+function gravitationalWork(centralMass, mass, fromRadius, toRadius, G = GRAVITATIONAL_CONSTANT, sf = 4) {
+	if (fromRadius <= 0 || toRadius <= 0) throw new Error("Radii are measured from the centre of the attracting body and must be positive.");
+	const value = G * centralMass * mass * (1 / fromRadius - 1 / toRadius);
+	return calc().step("F = \\frac{GMm}{r^2}", "the force weakens with distance, so a single \"mg\" is no longer good enough over the journey").step("W = \\int_{r_a}^{r_b} \\frac{GMm}{r^2}\\,dr = GMm\\left(\\frac{1}{r_a} - \\frac{1}{r_b}\\right)", "integrate, because the force is not constant. The 1/r squared integrates to minus 1/r").step(`W = ${texSigFigs(G, 4)} \\times ${texSigFigs(centralMass, sf)} \\times ${texSigFigs(mass, sf)} \\left(\\frac{1}{${texSigFigs(fromRadius, sf)}} - \\frac{1}{${texSigFigs(toRadius, sf)}}\\right)`).step(`W = ${texSigFigs(value, sf)}\\ \\mathrm{J}`, "work done BY an outside agent moving the mass outwards. Gravity did the same amount with the opposite sign").step("r_b = r_a + h,\\ h \\ll r_a \\Rightarrow W \\approx \\frac{GMm}{r_a^2}h = mgh", "for a small rise the two radii barely differ, and this collapses into mgh. That is where mgh comes from").done(value);
+}
+/**
+* `Ep = ½kx²`, the energy stored in a spring stretched or compressed by `x` from its natural length.
+*
+* `x` is squared, so stretching and compressing by the same amount store the same energy. That is
+* worth stating because a compression is usually written as a negative extension and a learner who
+* carries the minus sign into an energy gets a negative store, which is impossible.
+*
+* The derivation lives in `spring.ts`, where the integral is actually performed rather than quoted.
+*/
+function elasticPE(stiffness, extension, sf = 3) {
+	const value = .5 * stiffness * extension * extension;
+	return calc().step("E_p = \\tfrac{1}{2}kx^2", "x is measured from the NATURAL length, not from wherever the spring happens to be sitting").step(`E_p = \\tfrac{1}{2} \\times ${texSigFigs(stiffness, sf)} \\times ${texSigFigs(extension, sf)}^2 = ${texSigFigs(value, sf)}\\ \\mathrm{J}`, "x is squared, so a compression of 3 cm stores exactly what a stretch of 3 cm stores. The store is never negative").done(value);
+}
+
+//#endregion
+export { elasticPE, gravitationalPE, gravitationalWork, kineticEnergy, kineticFromMomentum, kineticFromVelocity, momentumFromKinetic, speedFromKinetic };

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

@@ -0,0 +1,65 @@
+import { Worked } from "../../core/worked.mjs";
+
+//#region src/physics/energy/theorem.d.ts
+interface WorkEnergyResult {
+  readonly initialKinetic: number;
+  readonly finalKinetic: number;
+  /** `ΔEk`, which IS the net work done. Negative when the body slowed. */
+  readonly netWork: number;
+  readonly worked: Worked;
+}
+/**
+ * The theorem itself: the net work done on a body equals its change in kinetic energy.
+ *
+ * Deliberately blunt and general, taking only the two speeds. A body brought to rest from 30 m/s has
+ * had a definite amount of work done against it and it does not matter in the slightest whether that
+ * was a brake, a wall, a parachute, or a hill.
+ */
+declare function workEnergy(mass: number, initialSpeed: number, finalSpeed: number, sf?: number): WorkEnergyResult;
+/** The work that must be done against resistance to stop a moving body: `½mu²`. */
+declare const workToStop: (mass: number, speed: number, sf?: number) => Worked;
+interface PenetrationResult {
+  /** The average force resisting the penetration, newtons. */
+  readonly resistance: number;
+  /** Energy arriving at the surface, joules. */
+  readonly arriving: number;
+  /** The extra work gravity did during the penetration itself. Zero for a horizontal strike. */
+  readonly gravityDuringPenetration: number;
+  readonly worked: Worked;
+}
+/**
+ * A mass DROPPED onto a nail or a stake: the average resistance of the material.
+ *
+ * `mg(h + x) = Fx`. The `+ x` is the term this function exists to make unmissable: gravity does not
+ * switch off when the hammer touches the nail, and it keeps pulling for the whole penetration too.
+ * For a 5 m drop into 10 cm the correction is 2 per cent, which is small enough to look like a
+ * rounding difference and large enough to fail a mark scheme.
+ *
+ * `dropHeight` is the fall BEFORE contact. `penetration` is how far in it went.
+ */
+declare function resistanceFromDrop(mass: number, dropHeight: number, penetration: number, g?: number, sf?: number): PenetrationResult;
+/**
+ * A mass driven horizontally into a material at a known speed: resistance from kinetic energy alone.
+ *
+ * The simpler cousin, and simpler for a reason worth saying: struck sideways, gravity is
+ * perpendicular to the motion, so it does no work and the `+ x` term is genuinely absent. Not
+ * because the problem is easier, but because `cos 90° = 0`.
+ */
+declare function resistanceFromStrike(mass: number, speed: number, penetration: number, sf?: number): PenetrationResult;
+/**
+ * The speed needed to drive a known distance into a material of known resistance.
+ *
+ * `resistanceFromStrike` rearranged, and the form a question takes when it wants the hammer's speed
+ * rather than the wood's toughness.
+ */
+declare function speedToPenetrate(mass: number, resistance: number, penetration: number, sf?: number): Worked;
+/**
+ * How far a body travels before a constant resisting force stops it.
+ *
+ * The braking-distance question, and the place to notice that the distance goes as `v²`: doubling
+ * the speed quadruples the stopping distance. That single fact is the entire physics content of
+ * every road safety campaign.
+ */
+declare function stoppingDistance(mass: number, speed: number, resistance: number, sf?: number): Worked;
+//#endregion
+export { PenetrationResult, WorkEnergyResult, resistanceFromDrop, resistanceFromStrike, speedToPenetrate, stoppingDistance, workEnergy, workToStop };

package/dist/physics/energy/theorem.mjs

@@ -0,0 +1,113 @@
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { G_EARTH } from "../kinematics/free-fall.mjs";
+
+//#region src/physics/energy/theorem.ts
+/**
+* The work-energy theorem, and the questions that are only tractable through it.
+*
+* `W_net = ΔEk`. Four symbols, and it replaces a whole class of problems that are painful through
+* forces and accelerations. A nail driven into wood decelerates enormously over a few millimetres
+* and nobody wants to find that acceleration; what they want is that the kinetic energy arriving had
+* to go somewhere, and the only place available was work done against the resisting force.
+*
+* TWO THINGS DECIDE WHETHER A SOLUTION IS RIGHT HERE, and neither is the arithmetic.
+*
+*   1. It is the NET work. Every force doing work goes in the ledger, with its sign. A solution that
+*      counts the resistance and forgets that gravity kept pulling during the penetration is out by
+*      a term, and for a hammer falling 5 m into 10 cm of wood that term is small but for a short
+*      drop it is not.
+*   2. The DISTANCE for each force is the distance THAT force acted over, and they are not always
+*      the same distance. Gravity acts over the drop AND the penetration; the resistance acts only
+*      over the penetration. `mg(h + x) = Fx` is that observation written down, and the `+ x` is the
+*      single most commonly dropped term in this topic.
+*
+* Pure: no React, no pixels.
+*/
+/**
+* The theorem itself: the net work done on a body equals its change in kinetic energy.
+*
+* Deliberately blunt and general, taking only the two speeds. A body brought to rest from 30 m/s has
+* had a definite amount of work done against it and it does not matter in the slightest whether that
+* was a brake, a wall, a parachute, or a hill.
+*/
+function workEnergy(mass, initialSpeed, finalSpeed, sf = 3) {
+	const initialKinetic = .5 * mass * initialSpeed * initialSpeed;
+	const finalKinetic = .5 * mass * finalSpeed * finalSpeed;
+	const netWork = finalKinetic - initialKinetic;
+	return {
+		initialKinetic,
+		finalKinetic,
+		netWork,
+		worked: calc().step("W_{\\text{net}} = \\Delta E_k = \\tfrac{1}{2}mv^2 - \\tfrac{1}{2}mu^2", "the net work done on a body is its gain in kinetic energy. What did the work is irrelevant").step(`E_k \\text{ initial} = \\tfrac{1}{2} \\times ${texSigFigs(mass, sf)} \\times ${texSigFigs(initialSpeed, sf)}^2 = ${texSigFigs(initialKinetic, sf)}\\ \\mathrm{J}`).step(`E_k \\text{ final} = \\tfrac{1}{2} \\times ${texSigFigs(mass, sf)} \\times ${texSigFigs(finalSpeed, sf)}^2 = ${texSigFigs(finalKinetic, sf)}\\ \\mathrm{J}`).step(`W_{\\text{net}} = ${texSigFigs(netWork, sf)}\\ \\mathrm{J}`, netWork < 0 ? "negative, because the body slowed. The work done AGAINST the resisting force is the same size, positive" : netWork > 0 ? "positive: energy was fed in and the body sped up" : "zero: the speed is unchanged, so however much force acted, the net work was nothing").done(netWork)
+	};
+}
+/** The work that must be done against resistance to stop a moving body: `½mu²`. */
+const workToStop = (mass, speed, sf = 3) => {
+	const value = .5 * mass * speed * speed;
+	return calc().step("W = \\Delta E_k = 0 - \\tfrac{1}{2}mu^2", "the body ends at rest, so all of its kinetic energy must be removed").step(`W_{\\text{against}} = \\tfrac{1}{2} \\times ${texSigFigs(mass, sf)} \\times ${texSigFigs(speed, sf)}^2 = ${texSigFigs(value, sf)}\\ \\mathrm{J}`, "quoted positive: it is the work done against the resisting force, not the work done on the body").done(value);
+};
+/**
+* A mass DROPPED onto a nail or a stake: the average resistance of the material.
+*
+* `mg(h + x) = Fx`. The `+ x` is the term this function exists to make unmissable: gravity does not
+* switch off when the hammer touches the nail, and it keeps pulling for the whole penetration too.
+* For a 5 m drop into 10 cm the correction is 2 per cent, which is small enough to look like a
+* rounding difference and large enough to fail a mark scheme.
+*
+* `dropHeight` is the fall BEFORE contact. `penetration` is how far in it went.
+*/
+function resistanceFromDrop(mass, dropHeight, penetration, g = G_EARTH, sf = 3) {
+	if (penetration <= 0) throw new Error("Nothing penetrated, so the material absorbed the energy over no distance and the force is unbounded.");
+	const arriving = mass * g * dropHeight;
+	const gravityDuringPenetration = mass * g * penetration;
+	const resistance = (arriving + gravityDuringPenetration) / penetration;
+	return {
+		resistance,
+		arriving,
+		gravityDuringPenetration,
+		worked: calc().step("W_{\\text{gravity}} = W_{\\text{resistance}}", "the hammer starts at rest and finishes at rest, so the net work over the whole journey is zero").step("mg(h + x) = Fx", "gravity acts over the drop AND the penetration, so its distance is h + x. The resistance only acts over x").step(`F = \\frac{mg(h + x)}{x} = \\frac{${texSigFigs(mass, sf)} \\times ${texSigFigs(g, sf)} \\times (${texSigFigs(dropHeight, sf)} + ${texSigFigs(penetration, sf)})}{${texSigFigs(penetration, sf)}}`).step(`F = ${texSigFigs(resistance, sf)}\\ \\mathrm{N}`, "an average. The real force rises from nothing as the material compresses, and this is the flat force that would do the same total work").step(`\\text{dropping the } +x \\text{ term would give } ${texSigFigs(arriving / penetration, sf)}\\ \\mathrm{N}`, "close enough to look right and wrong enough to be marked wrong").done(resistance)
+	};
+}
+/**
+* A mass driven horizontally into a material at a known speed: resistance from kinetic energy alone.
+*
+* The simpler cousin, and simpler for a reason worth saying: struck sideways, gravity is
+* perpendicular to the motion, so it does no work and the `+ x` term is genuinely absent. Not
+* because the problem is easier, but because `cos 90° = 0`.
+*/
+function resistanceFromStrike(mass, speed, penetration, sf = 3) {
+	if (penetration <= 0) throw new Error("Nothing penetrated, so the material absorbed the energy over no distance and the force is unbounded.");
+	const arriving = .5 * mass * speed * speed;
+	const resistance = arriving / penetration;
+	return {
+		resistance,
+		arriving,
+		gravityDuringPenetration: 0,
+		worked: calc().step("\\tfrac{1}{2}mv^2 = Fx", "struck horizontally, gravity is perpendicular to the motion and does no work. Only the kinetic energy has to be absorbed").step(`F = \\frac{\\tfrac{1}{2}mv^2}{x} = \\frac{\\tfrac{1}{2} \\times ${texSigFigs(mass, sf)} \\times ${texSigFigs(speed, sf)}^2}{${texSigFigs(penetration, sf)}}`).step(`F = ${texSigFigs(resistance, sf)}\\ \\mathrm{N}`).done(resistance)
+	};
+}
+/**
+* The speed needed to drive a known distance into a material of known resistance.
+*
+* `resistanceFromStrike` rearranged, and the form a question takes when it wants the hammer's speed
+* rather than the wood's toughness.
+*/
+function speedToPenetrate(mass, resistance, penetration, sf = 3) {
+	const value = Math.sqrt(2 * resistance * penetration / mass);
+	return calc().step("\\tfrac{1}{2}mv^2 = Fx \\Rightarrow v = \\sqrt{\\frac{2Fx}{m}}").step(`v = \\sqrt{\\frac{2 \\times ${texSigFigs(resistance, sf)} \\times ${texSigFigs(penetration, sf)}}{${texSigFigs(mass, sf)}}} = ${texSigFigs(value, sf)}\\ \\mathrm{m\\,s^{-1}}`).done(value);
+}
+/**
+* How far a body travels before a constant resisting force stops it.
+*
+* The braking-distance question, and the place to notice that the distance goes as `v²`: doubling
+* the speed quadruples the stopping distance. That single fact is the entire physics content of
+* every road safety campaign.
+*/
+function stoppingDistance(mass, speed, resistance, sf = 3) {
+	if (resistance <= 0) throw new Error("With no resisting force the body never stops.");
+	const value = .5 * mass * speed * speed / resistance;
+	return calc().step("\\tfrac{1}{2}mv^2 = Fd \\Rightarrow d = \\frac{mv^2}{2F}").step(`d = \\frac{${texSigFigs(mass, sf)} \\times ${texSigFigs(speed, sf)}^2}{2 \\times ${texSigFigs(resistance, sf)}} = ${texSigFigs(value, sf)}\\ \\mathrm{m}`).step("d \\propto v^2", "twice the speed is four times the distance, because the energy to be removed went up fourfold while the force did not").done(value);
+}
+
+//#endregion
+export { resistanceFromDrop, resistanceFromStrike, speedToPenetrate, stoppingDistance, workEnergy, workToStop };