@classytic/labs 0.3.0 → 0.4.0

package/dist/physics/electrostatics/coulomb-preset.mjs

@@ -0,0 +1,331 @@
+'use client';
+
+import { Tex } from "../../core/tex.mjs";
+import { ActivitySelect, Segmented, Stepper } from "../../kit/controls.mjs";
+import { Activity } from "../../kit/activity.mjs";
+import { Field, Stat, StatList } from "../../kit/frame.mjs";
+import { AuthoredActivityRuntime } from "../../kit/authored-activity-runtime.mjs";
+import { Figure, HUE } from "../../kit/figure/figure.mjs";
+import { FigText } from "../../kit/figure/text.mjs";
+import { Particle } from "../../kit/figure/body.mjs";
+import { Arrow } from "../../kit/figure/beam.mjs";
+import { coulombSuperpositionActivity } from "./coulomb-activity.mjs";
+import { ARRANGEMENTS } from "./coulomb-presets.mjs";
+import { useMemo, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { contributionsAt, potentialAt, resultant } from "@classytic/stage/physics/electrostatics";
+
+//#region src/physics/electrostatics/coulomb-preset.tsx
+/**
+* CoulombSuperpositionLab: the vector sum, built one charge at a time, with the working shown.
+*
+* The interaction is deliberately the SAME as `NetworkReductionLab`'s: a stepper that adds one
+* move at a time and says what it did. A student who has met one already knows how to drive the
+* other, and the two labs are teaching the same underlying habit, which is to do a hard thing in
+* small legal steps rather than in one leap.
+*
+* Step 0 shows the charges and the probe and nothing else, so a prediction can be made. Step k adds
+* charge k's contribution as an arrow and its resolved components to the running totals. The last
+* step recombines the totals into the resultant. That is exactly the order a marker reads a script
+* in, which is the reason for it.
+*
+* ── Scale ───────────────────────────────────────────────────────────────────────────────────────
+* Arrows are scaled so the LARGEST contribution in the arrangement is a fixed length on screen, and
+* every other arrow is drawn in true proportion to it. Scaling each arrow to its own comfortable
+* length would look tidier and would destroy the one thing the picture is for: seeing that a charge
+* twice as far away contributes a quarter as much.
+*
+* ── Position, not softening ─────────────────────────────────────────────────────────────────────
+* The engine throws when the probe sits on a charge, rather than returning a large number.
+* This file catches that and says so, because an arrangement whose probe is on a charge is a
+* malformed question and should read as one.
+*/
+const VIEW_WIDTH = 460;
+/** Longest contribution arrow, in scene units. Every other arrow is drawn in proportion to it. */
+const MAX_ARROW = 88;
+const CHARGE_R = 11;
+const toScene = (frame, x, y) => [frame.cx + x * frame.scale, frame.cy - y * frame.scale];
+/**
+* Fit the arrangement into the viewBox.
+*
+* The extent has to include the ARROWS, not just the charges, or the resultant runs off the top of
+* a scene that looked perfectly well fitted at step 0.
+*/
+function frameFor(arrangement, longestArrowUnits) {
+	const xs = [...arrangement.charges.map((c) => c.at.x), arrangement.probe.x];
+	const ys = [...arrangement.charges.map((c) => c.at.y), arrangement.probe.y];
+	const spanX = Math.max(...xs) - Math.min(...xs) || .2;
+	const spanY = Math.max(...ys) - Math.min(...ys) || .2;
+	const midX = (Math.max(...xs) + Math.min(...xs)) / 2;
+	const midY = (Math.max(...ys) + Math.min(...ys)) / 2;
+	const margin = longestArrowUnits + CHARGE_R + 26;
+	const usableW = VIEW_WIDTH - 2 * margin;
+	const scale = Math.max(40, Math.min(usableW / spanX, 900));
+	const height = Math.max(200, spanY * scale + 2 * margin);
+	return {
+		scale,
+		cx: VIEW_WIDTH / 2 - midX * scale,
+		cy: height / 2 + midY * scale,
+		top: 0,
+		height
+	};
+}
+const fmt = (value, digits = 2) => {
+	if (value === 0) return "0";
+	const abs = Math.abs(value);
+	if (abs >= 1e5 || abs < .01) {
+		const exponent = Math.floor(Math.log10(abs));
+		return `${(value / 10 ** exponent).toFixed(digits)}e${exponent}`;
+	}
+	return value.toFixed(digits);
+};
+const POS = HUE.hot;
+const NEG = HUE.cold;
+function CoulombSuperpositionLab({ arrangement: arrangementKey = "triangle", view: initialView = "field", startStep = 0, lockArrangement = false, lockView = false, title = "Add the fields as vectors, one charge at a time", prompt = "Which way does each charge push a positive test charge placed at P?", objectives, activity }) {
+	const [key, setKey] = useState(arrangementKey);
+	const [view, setView] = useState(initialView);
+	const [step, setStep] = useState(startStep);
+	const arrangement = ARRANGEMENTS[key];
+	const { contributions, volts, error } = useMemo(() => {
+		try {
+			return {
+				contributions: contributionsAt(arrangement.charges, arrangement.probe),
+				volts: potentialAt(arrangement.charges, arrangement.probe),
+				error: null
+			};
+		} catch (cause) {
+			return {
+				contributions: [],
+				volts: 0,
+				error: cause instanceof Error ? cause.message : "this arrangement has no defined answer"
+			};
+		}
+	}, [arrangement]);
+	const maxStep = contributions.length + 1;
+	const at = Math.min(Math.max(step, 0), maxStep);
+	const added = contributions.slice(0, Math.min(at, contributions.length));
+	const showResultant = at === maxStep;
+	const running = resultant(added.map((c) => c.vector));
+	const total = resultant(contributions.map((c) => c.vector));
+	const justAdded = at >= 1 && at <= contributions.length ? contributions[at - 1] : null;
+	const biggest = contributions.reduce((m, c) => Math.max(m, c.magnitude), 0);
+	const arrowUnits = (value) => biggest > 0 ? value / biggest * MAX_ARROW : 0;
+	const frame = frameFor(arrangement, MAX_ARROW);
+	const pick = (next) => {
+		setKey(next);
+		setStep(0);
+	};
+	const [px, py] = toScene(frame, arrangement.probe.x, arrangement.probe.y);
+	const chargeMark = (c) => {
+		const [x, y] = toScene(frame, c.at.x, c.at.y);
+		const positive = c.microCoulomb > 0;
+		return /* @__PURE__ */ jsxs("g", { children: [
+			/* @__PURE__ */ jsx(Particle, {
+				x,
+				y,
+				r: CHARGE_R,
+				color: positive ? POS : NEG
+			}),
+			/* @__PURE__ */ jsx(FigText, {
+				x,
+				y: y + 4,
+				size: "label",
+				anchor: "middle",
+				tone: "inverse",
+				halo: false,
+				children: positive ? "+" : "−"
+			}),
+			/* @__PURE__ */ jsx(FigText, {
+				x,
+				y: y + CHARGE_R + 15,
+				size: "label",
+				anchor: "middle",
+				tone: "soft",
+				children: `${c.id} ${c.microCoulomb} µC`
+			})
+		] }, c.id);
+	};
+	const contributionArrow = (c, index) => {
+		const length = arrowUnits(c.magnitude);
+		if (length <= 0) return null;
+		const radians = c.angleDeg * Math.PI / 180;
+		const x2 = px + length * Math.cos(radians);
+		const y2 = py - length * Math.sin(radians);
+		const live = justAdded?.from === c.from;
+		/**
+		* Only the arrow just added carries a label.
+		*
+		* In the square arrangement the contributions from the positive and the negative on the same
+		* diagonal are EXACTLY collinear: one points away from the plus and the other toward the minus,
+		* which is the same direction. Labelling every arrow put "E1" and "E3" on the same pixel, and
+		* the collision gate caught it. Superimposed arrows are the honest drawing there, since the two
+		* really do reinforce, so the fix belongs on the labels rather than on the geometry.
+		*/
+		return /* @__PURE__ */ jsx(Arrow, {
+			x1: px,
+			y1: py,
+			x2,
+			y2,
+			color: live ? HUE[1] : HUE.soft,
+			weight: live ? "edge" : "line",
+			head: 9,
+			label: live ? `E${index + 1}` : void 0
+		}, `c-${c.from}`);
+	};
+	const resultantArrow = () => {
+		const length = arrowUnits(total.magnitude);
+		if (length <= 0) return null;
+		const radians = total.angleDeg * Math.PI / 180;
+		return /* @__PURE__ */ jsx(Arrow, {
+			x1: px,
+			y1: py,
+			x2: px + length * Math.cos(radians),
+			y2: py - length * Math.sin(radians),
+			color: HUE.good,
+			weight: "bold",
+			head: 12,
+			label: "E"
+		});
+	};
+	const sceneLabel = error ? "This arrangement has no defined answer." : showResultant ? `Resultant field ${fmt(total.magnitude)} newtons per coulomb at ${fmt(total.angleDeg, 1)} degrees.` : at === 0 ? `${arrangement.charges.length} charges and the probe point P, with no contributions drawn yet.` : `${added.length} of ${contributions.length} contributions drawn.`;
+	const scene = /* @__PURE__ */ jsxs(Figure, {
+		viewBox: `0 0 ${VIEW_WIDTH} ${frame.height}`,
+		label: sceneLabel,
+		children: [
+			view === "field" && added.map(contributionArrow),
+			view === "field" && showResultant && resultantArrow(),
+			arrangement.charges.map(chargeMark),
+			/* @__PURE__ */ jsx(Particle, {
+				x: px,
+				y: py,
+				r: 5,
+				color: HUE.ink
+			}),
+			/* @__PURE__ */ jsx(FigText, {
+				x: px,
+				y: py - 14,
+				size: "label",
+				anchor: "middle",
+				tone: "ink",
+				children: "P"
+			})
+		]
+	});
+	const controls = /* @__PURE__ */ jsxs(Fragment$1, { children: [
+		!lockView && /* @__PURE__ */ jsx(Field, {
+			label: "Quantity",
+			name: "view",
+			children: /* @__PURE__ */ jsx(Segmented, {
+				ariaLabel: "quantity",
+				value: view,
+				onChange: setView,
+				options: [{
+					value: "field",
+					label: "Field (vector)"
+				}, {
+					value: "potential",
+					label: "Potential (scalar)"
+				}]
+			})
+		}),
+		!lockArrangement && /* @__PURE__ */ jsx(Field, {
+			label: "Arrangement",
+			name: "arrangement",
+			children: /* @__PURE__ */ jsx(ActivitySelect, {
+				ariaLabel: "charge arrangement",
+				value: key,
+				onChange: pick,
+				options: [
+					{
+						value: "dipole",
+						label: "Equal and opposite"
+					},
+					{
+						value: "like-pair",
+						label: "Two like charges"
+					},
+					{
+						value: "triangle",
+						label: "Triangle"
+					},
+					{
+						value: "square",
+						label: "Square"
+					},
+					{
+						value: "null-point",
+						label: "Null point"
+					}
+				]
+			})
+		}),
+		view === "field" && /* @__PURE__ */ jsx(Field, {
+			label: "Charges added",
+			name: "step",
+			children: /* @__PURE__ */ jsx(Stepper, {
+				value: at,
+				onChange: setStep,
+				min: 0,
+				max: maxStep,
+				label: "superposition step"
+			})
+		})
+	] });
+	const evidence = view === "potential" ? /* @__PURE__ */ jsxs(StatList, { children: [/* @__PURE__ */ jsx(Stat, {
+		label: "Potential at P",
+		value: `${fmt(volts)} V`,
+		tone: "good"
+	}), /* @__PURE__ */ jsx(Stat, {
+		label: "Field at P",
+		value: `${fmt(total.magnitude)} N/C`
+	})] }) : /* @__PURE__ */ jsxs(StatList, { children: [
+		/* @__PURE__ */ jsx(Stat, {
+			label: "Σ Ex",
+			value: fmt(running.vector.x)
+		}),
+		/* @__PURE__ */ jsx(Stat, {
+			label: "Σ Ey",
+			value: fmt(running.vector.y)
+		}),
+		showResultant ? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(Stat, {
+			label: "Resultant",
+			value: `${fmt(total.magnitude)} N/C`,
+			tone: "good"
+		}), /* @__PURE__ */ jsx(Stat, {
+			label: "Direction",
+			value: `${fmt(total.angleDeg, 1)}°`,
+			tone: "good"
+		})] }) : null
+	] });
+	const observation = error ? error : view === "potential" ? `Potential is a scalar, so the contributions are added as signed numbers with no directions at all: ${fmt(volts)} V. Compare it with the field, which needs every one of those directions.` : justAdded ? `${justAdded.from} sits ${fmt(justAdded.distanceM, 3)} m from P and contributes ${fmt(justAdded.magnitude)} N/C, pointing ${justAdded.outward ? "AWAY from it because it is positive" : "TOWARD it because it is negative"}, at ${fmt(justAdded.angleDeg, 1)}°.` : showResultant ? `Recombining the two totals: magnitude ${fmt(total.magnitude)} N/C at ${fmt(total.angleDeg, 1)}° from the x axis.` : "Before anything is computed: decide which way each charge pushes a positive test charge placed at P. A contribution points away from a positive charge and toward a negative one.";
+	return /* @__PURE__ */ jsxs(AuthoredActivityRuntime, {
+		className: "physics-fields",
+		focusLayout: "immersive",
+		activity: activity ?? coulombSuperpositionActivity,
+		activityId: "coulomb-superposition",
+		eyebrow: "Electric fields",
+		title,
+		description: prompt,
+		controls,
+		evidence,
+		observation,
+		children: [
+			scene,
+			view === "field" && justAdded ? /* @__PURE__ */ jsx(Tex, {
+				tex: `E_{${justAdded.from}} = \\frac{kQ}{r^2} = ${fmt(justAdded.magnitude)}\\ \\mathrm{N\\,C^{-1}}`,
+				block: true
+			}) : null,
+			view === "field" && showResultant ? /* @__PURE__ */ jsx(Tex, {
+				tex: `E = \\sqrt{(\\Sigma E_x)^2 + (\\Sigma E_y)^2} = ${fmt(total.magnitude)}\\ \\mathrm{N\\,C^{-1}}`,
+				block: true
+			}) : null,
+			/* @__PURE__ */ jsx(Activity.Disclosure, {
+				label: "What this arrangement is for",
+				children: /* @__PURE__ */ jsx("p", { children: arrangement.caption })
+			})
+		]
+	});
+}
+
+//#endregion
+export { CoulombSuperpositionLab, CoulombSuperpositionLab as default };

package/dist/physics/electrostatics/coulomb-presets.mjs

@@ -0,0 +1,60 @@
+//#region src/physics/electrostatics/coulomb-presets.ts
+const q = (id, microCoulomb, x, y, label) => ({
+	id,
+	microCoulomb,
+	at: {
+		x,
+		y
+	},
+	label
+});
+const ARRANGEMENTS = {
+	dipole: {
+		caption: "Equal and opposite, and the probe sits midway. Both contributions point the SAME way, away from the positive and toward the negative, so they add rather than cancel. The potential there is exactly zero at the same time.",
+		charges: [q("A", 4, -.2, 0), q("B", -4, .2, 0)],
+		probe: {
+			x: 0,
+			y: 0
+		}
+	},
+	"like-pair": {
+		caption: "Two equal positives. Midway between them the two contributions are equal and opposite, so the field is zero while the potential is at its largest. This is the exact reverse of the dipole, and the pair of them is the whole scalar-versus-vector lesson.",
+		charges: [q("A", 4, -.2, 0), q("B", 4, .2, 0)],
+		probe: {
+			x: 0,
+			y: 0
+		}
+	},
+	triangle: {
+		caption: "Three charges at the corners of an equilateral triangle, probed at one corner. Two contributions at 120 degrees to each other, which resolve along their own bisector.",
+		charges: [q("A", 5, -.15, -.0866), q("B", 5, .15, -.0866)],
+		probe: {
+			x: 0,
+			y: .1732
+		}
+	},
+	square: {
+		caption: "Four charges at the corners of a square, positives along the bottom and negatives along the top. Every horizontal component cancels in pairs and every vertical one reinforces, so the resultant points straight up.",
+		charges: [
+			q("A", 5, -.1, -.1),
+			q("B", 5, .1, -.1),
+			q("C", -5, .1, .1),
+			q("D", -5, -.1, .1)
+		],
+		probe: {
+			x: 0,
+			y: 0
+		}
+	},
+	"null-point": {
+		caption: "A −1 microcoulomb and a +4 microcoulomb charge. The point where the field vanishes is NOT between them: it sits out beyond the smaller charge, because only there can the nearer small charge match the further large one.",
+		charges: [q("A", -1, 0, 0), q("B", 4, .5, 0)],
+		probe: {
+			x: -.5,
+			y: 0
+		}
+	}
+};
+
+//#endregion
+export { ARRANGEMENTS };

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

@@ -0,0 +1,199 @@
+//#region src/physics/energy/core.d.ts
+/**
+ * Work, energy and power: the one quantity that crosses every other engine.
+ *
+ * Mechanics, electricity, magnetism, thermal and nuclear all end up saying "how
+ * much energy, transferred how fast, and what fraction of it was useful". Until
+ * now each said it in its own way, and the mechanical half did not say it in an
+ * engine at all: `W = Fd`, `W = mgh` and the efficiency fraction were written
+ * inside the React components that drew them, so nothing tested them and
+ * nothing else could call them.
+ *
+ * `m g h` in particular existed three times over, in `mechanics/core.ts`, in
+ * the power lab and in the energy skate lab. Three copies of a formula that
+ * agree today is not a safe state.
+ *
+ * ── AND THEN THIS FILE BECAME THE FOURTH COPY ────────────────────────────────
+ * Consolidating the labs' own duplicates was right and did not go far enough.
+ * `@classytic/stage/physics` now carries a tested energy kernel, so `W = Fd cos`,
+ * `½mv²`, `mgh`, `½kx²`, `P = W/t`, `P = Fv` and the efficiency chain existed
+ * here AND there, checked against different things and free to drift apart.
+ *
+ * So the arithmetic below is the engine's. What stays is this module's
+ * INTERFACE: plain numbers in and out, SI-suffixed names, and the argument
+ * validation, whose messages callers and tests depend on. The engine returns
+ * `Worked` objects carrying every substitution, which is the better thing for a
+ * lesson to render; a lab that wants the working should call the engine
+ * directly and get the steps rather than come through here for a bare number.
+ *
+ * These are marked `@deprecated` individually to say which engine call replaces
+ * each one. They are not going away: they are public API and several labs are
+ * built on them.
+ *
+ * ── Stores and transfers, not "types of energy" ───────────────────────────────
+ * Energy is not a substance with varieties; it is a number that sits in stores
+ * and moves between them. Modelling a lab as a LEDGER, an amount per store plus
+ * the transfers between them, makes conservation checkable instead of asserted,
+ * and makes efficiency fall out as a property of the transfers rather than a
+ * separate quantity to look after. It is also the shape a simulation needs: any
+ * domain can push a transfer into the same ledger without knowing about the
+ * others.
+ */
+/**
+ * Work done by a constant force: W = F s cos(theta).
+ *
+ * The angle is between the force and the DISPLACEMENT, which is the whole
+ * content of the cosine: a force at right angles to the motion does no work,
+ * however large it is. That is why a centripetal force never changes speed and
+ * why carrying a bag along a level floor does no work against gravity.
+ *
+ * Signed, deliberately. A force opposing the motion does NEGATIVE work, and
+ * hiding that behind an absolute value would make friction and braking
+ * impossible to express.
+ *
+ * @deprecated Prefer `workDone` from `@classytic/stage/physics`: same number, plus the working.
+ */
+declare function workDoneJ(forceN: number, distanceM: number, angleDeg?: number): number;
+/**
+ * Work done by a force that VARIES with position, by quadrature.
+ *
+ * This is the area under a force-displacement graph, which is what the graph is
+ * for. Simpson's rule, because the forces that matter here (a spring's k x, a
+ * gravitational inverse square) are smooth, and because a student reading the
+ * area off the graph is doing the same integral by eye.
+ */
+declare function workFromForceCurveJ(forceAt: (positionM: number) => number, fromM: number, toM: number, intervals?: number): number;
+/**
+ * Kinetic energy: E = 1/2 m v squared.
+ *
+ * @deprecated Prefer `kineticEnergy` from `@classytic/stage/physics`.
+ */
+declare function kineticEnergyJ(massKg: number, speedMs: number): number;
+/**
+ * Speed a given kinetic energy corresponds to.
+ *
+ * The inverse matters because energy questions are usually posed the other way
+ * round: an energy budget is given and a speed is wanted.
+ *
+ * @deprecated Prefer `speedFromKinetic` from `@classytic/stage/physics`.
+ */
+declare function speedFromKineticJ(massKg: number, energyJ: number): number;
+/**
+ * Gravitational potential energy near a surface: E = m g h.
+ *
+ * Only valid where g is effectively constant, which is what "near a surface"
+ * means. Far from a planet it is `-GMm/r`, which lives in the orbital engine,
+ * and the two are not interchangeable.
+ *
+ * @deprecated Prefer `gravitationalPE` from `@classytic/stage/physics`, which makes the reference
+ * level an argument instead of assuming the ground.
+ */
+declare function gravitationalPeJ(massKg: number, heightM: number, gravity?: number): number;
+/** Height a given gravitational potential energy corresponds to. */
+declare function heightFromPeJ(massKg: number, energyJ: number, gravity?: number): number;
+/**
+ * Elastic potential energy in a spring obeying Hooke's law: E = 1/2 k x squared.
+ *
+ * The one-half is the whole point and the commonest slip: the force grows from
+ * zero to k x, so the work is the AVERAGE force times the extension, not the
+ * final force times the extension.
+ *
+ * @deprecated Prefer `elasticPE`, or `springWork` when the work between two extensions is what
+ * is wanted, both from `@classytic/stage/physics`.
+ */
+declare function elasticPeJ(springConstantNPerM: number, extensionM: number): number;
+/** Thermal energy to warm a mass without changing its state: E = m c delta-theta. */
+declare function thermalEnergyJ(massKg: number, specificHeatJPerKgK: number, temperatureRiseK: number): number;
+/** Energy to change state at constant temperature: E = m L. */
+declare function latentEnergyJ(massKg: number, latentHeatJPerKg: number): number;
+/**
+ * Power as a rate of transfer: P = E / t.
+ *
+ * @deprecated Prefer `power` from `@classytic/stage/physics`, which also converts to horsepower.
+ */
+declare function powerW(energyJ: number, timeS: number): number;
+/**
+ * Power delivered by a force to something already moving: P = F v cos(theta).
+ *
+ * The form that matters for a vehicle at steady speed, where no energy is going
+ * into kinetic store and every watt is going against resistance. It follows
+ * from W = F s by dividing both sides by time, and saying so is better than
+ * presenting it as a second formula.
+ *
+ * @deprecated Prefer `powerFromForceSpeed` from `@classytic/stage/physics`.
+ */
+declare function powerFromForceW(forceN: number, speedMs: number, angleDeg?: number): number;
+/**
+ * Efficiency as a FRACTION, not a percentage.
+ *
+ * Returning 0 to 1 rather than 0 to 100 so it composes: two stages in series
+ * multiply. A percentage invites multiplying 45 by 80 and getting 3600.
+ *
+ * @deprecated Prefer `efficiency` from `@classytic/stage/physics`, which reports the wasted share
+ * alongside the fraction.
+ */
+declare function efficiency(usefulOutputJ: number, totalInputJ: number): number;
+/**
+ * Energy that did not do the wanted job.
+ *
+ * Never negative: the same guard as `efficiency` runs first, so a caller who
+ * claims more output than input is told rather than handed a negative waste.
+ */
+declare function wastedEnergyJ(usefulOutputJ: number, totalInputJ: number): number;
+/**
+ * Overall efficiency of stages in series: the fractions multiply.
+ *
+ * @deprecated Prefer `chainEfficiency` from `@classytic/stage/physics`.
+ */
+declare function combinedEfficiency(stages: readonly number[]): number;
+/**
+ * Where energy can sit.
+ *
+ * Deliberately a store list and not a "forms of energy" list: there is no
+ * "sound energy" store in the sense of a distinct substance, but there is
+ * energy in a sound wave, and naming them as stores keeps a lab from implying
+ * that a transfer changes what the energy IS.
+ */
+type EnergyStore = 'kinetic' | 'gravitational' | 'elastic' | 'thermal' | 'electrical' | 'chemical' | 'magnetic' | 'nuclear' | 'radiant' | 'sound';
+interface EnergyTransfer {
+  from: EnergyStore;
+  to: EnergyStore;
+  joules: number;
+  /** Whether this transfer is the one the device exists to make. */
+  useful?: boolean;
+  label?: string;
+}
+type Ledger = Readonly<Partial<Record<EnergyStore, number>>>;
+interface LedgerResult {
+  before: Ledger;
+  after: Ledger;
+  /** Total energy before minus total after. Should be zero to floating point. */
+  conservationErrorJ: number;
+  totalTransferredJ: number;
+  usefulJ: number;
+  wasteJ: number;
+  /** Useful over total transferred, or null when nothing moved. */
+  efficiency: number | null;
+}
+/**
+ * Apply a list of transfers to a set of stores, and report what happened.
+ *
+ * Refuses to take more out of a store than it holds. That is not defensive
+ * programming: a lab that drains a store past empty has modelled something
+ * impossible, and returning a negative store would let it draw a bar chart of
+ * it. Conservation is REPORTED rather than enforced, so a lesson can show that
+ * the books balance instead of being told they do.
+ */
+declare function applyTransfers(initial: Ledger, transfers: readonly EnergyTransfer[]): LedgerResult;
+/**
+ * A Sankey-ready breakdown: each transfer with its share of the total.
+ *
+ * The share is what a Sankey diagram's ribbon widths are, so computing it here
+ * keeps every energy diagram in the package proportioned by the same number
+ * rather than by whatever each scene divided by.
+ */
+declare function transferShares(transfers: readonly EnergyTransfer[]): Array<EnergyTransfer & {
+  share: number;
+}>;
+//#endregion
+export { EnergyStore, EnergyTransfer, Ledger, LedgerResult, applyTransfers, combinedEfficiency, efficiency, elasticPeJ, gravitationalPeJ, heightFromPeJ, kineticEnergyJ, latentEnergyJ, powerFromForceW, powerW, speedFromKineticJ, thermalEnergyJ, transferShares, wastedEnergyJ, workDoneJ, workFromForceCurveJ };