@classytic/stage 0.3.0 → 0.4.0

package/dist/colour/srgb.mjs

@@ -0,0 +1,108 @@
+//#region src/colour/srgb.ts
+/** The sRGB / Rec. 709 matrix, for a D65 white point. */
+function xyzToLinear(xyz) {
+	const { X, Y, Z } = xyz;
+	return {
+		r: 3.2406 * X - 1.5372 * Y - .4986 * Z,
+		g: -.9689 * X + 1.8758 * Y + .0415 * Z,
+		b: .0557 * X - .204 * Y + 1.057 * Z
+	};
+}
+/**
+* Divide out the lamp, so the reference white comes out exactly white.
+*
+* The sRGB matrix above is defined for a D65 white point and this engine integrates against an
+* equal-energy white, which are not the same colour. Without this step a spectrum that absorbs
+* NOTHING came back as `#ffe6e2`, a faint pink, and every hue after it was rotated by the
+* difference: a yellow solution was named orange. That is a chromatic adaptation, the von Kries
+* kind, and in RGB it is one division per channel.
+*
+* It is also the physically honest statement. The lamp is what we call white; a colour here is what
+* the sample does TO that lamp.
+*/
+const whiteBalance = (rgb, white) => ({
+	r: white.r === 0 ? 0 : rgb.r / white.r,
+	g: white.g === 0 ? 0 : rgb.g / white.g,
+	b: white.b === 0 ? 0 : rgb.b / white.b
+});
+/**
+* Bring a colour into gamut: clamp the negative channels, then scale to fit.
+*
+* A pure wavelength is more saturated than three phosphors can make, so its linear RGB has a
+* negative component and something has to give. The alternative tried here first was to desaturate,
+* mixing toward grey of the same luminance until the negative channel reached zero, on the argument
+* that desaturation preserves hue and clamping does not.
+*
+* Measured across the spectrum at 20 nm, that argument is simply wrong for this data, and in the
+* red it is badly wrong. Desaturating 650 nm gives `#ff004e`, a pink, because the green channel is
+* far more negative than the blue: mixing far enough to lift green to zero carries blue up past it.
+* Clamping gives `#ff0000`. The same holds at 530 nm, where desaturating produces a mint green and
+* clamping produces green. Published spectral colour tables agree with the clamped values.
+*
+* The lesson is that the hue-preservation argument applies to a colour with ONE offending channel,
+* and a spectral colour usually has two of unequal size.
+*/
+function fitGamut(rgb) {
+	const clamped = {
+		r: Math.max(0, rgb.r),
+		g: Math.max(0, rgb.g),
+		b: Math.max(0, rgb.b)
+	};
+	const high = Math.max(clamped.r, clamped.g, clamped.b);
+	if (high <= 1) return clamped;
+	return {
+		r: clamped.r / high,
+		g: clamped.g / high,
+		b: clamped.b / high
+	};
+}
+/** The sRGB transfer function: not a plain 1/2.2 power, and the linear toe near black matters. */
+const encode = (v) => {
+	const c = Math.max(0, Math.min(1, v));
+	return c <= .0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - .055;
+};
+/** Linear RGB to 8-bit sRGB, fitting the gamut first. */
+function linearToSRGB(rgb) {
+	const fit = fitGamut(rgb);
+	return {
+		r: Math.round(encode(fit.r) * 255),
+		g: Math.round(encode(fit.g) * 255),
+		b: Math.round(encode(fit.b) * 255)
+	};
+}
+/** Tristimulus values straight to a displayable colour. */
+const xyzToSRGB = (xyz) => linearToSRGB(xyzToLinear(xyz));
+/** `#rrggbb`, for anything that draws. */
+const hexOf = (c) => "#" + [
+	c.r,
+	c.g,
+	c.b
+].map((v) => Math.max(0, Math.min(255, v)).toString(16).padStart(2, "0")).join("");
+/** Hue in degrees, saturation and lightness each 0 to 1. The form a colour NAME is decided from. */
+function hslOf(c) {
+	const r = c.r / 255;
+	const g = c.g / 255;
+	const b = c.b / 255;
+	const max = Math.max(r, g, b);
+	const min = Math.min(r, g, b);
+	const l = (max + min) / 2;
+	const d = max - min;
+	if (d === 0) return {
+		h: 0,
+		s: 0,
+		l
+	};
+	const s = d / (1 - Math.abs(2 * l - 1));
+	let h;
+	if (max === r) h = (g - b) / d % 6;
+	else if (max === g) h = (b - r) / d + 2;
+	else h = (r - g) / d + 4;
+	return {
+		h: (h * 60 % 360 + 360) % 360,
+		s,
+		l
+	};
+}
+
+//#endregion
+export { fitGamut, hexOf, hslOf, linearToSRGB, whiteBalance, xyzToLinear, xyzToSRGB };

package/dist/core/constants.d.mts

@@ -0,0 +1,138 @@
+//#region src/core/constants.d.ts
+/**
+ * Universal physical constants, in SI, as the single place a number like the gas
+ * constant is written down.
+ *
+ * Written because `R` had three definitions in this package: `thermo/index.ts`
+ * and `chem/index.ts` both declared `8.314462618`, and `chem/relations.ts`
+ * carried `8.31446262` inside its `CONSTANTS` table. The last of those is the
+ * same constant rounded one digit shorter, which is the failure mode worth
+ * naming: a duplicated constant does not stay duplicated, it drifts, and then
+ * two parts of one calculation disagree in the eighth figure for no reason a
+ * reader can find.
+ *
+ * Values are CODATA 2018. The four that are EXACT by the 2019 SI redefinition
+ * are marked as such, because "exact" changes what a test may assert: a defined
+ * constant can be compared for equality, a measured one can only be compared to
+ * a tolerance.
+ *
+ * Domain kernels re-export what they need under their own name, so
+ * `@classytic/stage/thermo` still exports `R` and nothing downstream has to know
+ * this file exists. What they must not do is write the number again.
+ */
+/** Avogadro constant, per mole. EXACT by definition. */
+declare const AVOGADRO = 6.02214076e+23;
+/** Boltzmann constant, J/K. EXACT by definition. */
+declare const BOLTZMANN = 1.380649e-23;
+/**
+ * Molar gas constant, J/(mol·K). EXACT, being the product of two exact
+ * constants: R = N_A · k_B.
+ *
+ * Written as that product rather than as a literal, so the identity cannot rot.
+ * A reader who doubts the digits can check the multiplication instead of a
+ * table.
+ */
+declare const GAS_CONSTANT: number;
+/** Elementary charge, C. EXACT by definition. */
+declare const ELEMENTARY_CHARGE = 1.602176634e-19;
+/** Speed of light in vacuum, m/s. EXACT: it is what DEFINES the metre. */
+declare const SPEED_OF_LIGHT = 299792458;
+/** Planck constant, J·s. EXACT: it is what defines the kilogram. */
+declare const PLANCK = 6.62607015e-34;
+/** Reduced Planck constant, J·s. */
+declare const PLANCK_REDUCED: number;
+/**
+ * `hc` in eV·nm, so a photon's energy in electronvolts is `HC_EV_NM / lambdaNm`.
+ *
+ * The most useful derived constant at this level, and worth its own export
+ * rather than making every caller assemble it, because the assembly is where
+ * the factors of 1e-9 and 1.602e-19 go missing.
+ */
+declare const HC_EV_NM: number;
+/** Permeability of free space, N/A². */
+declare const VACUUM_PERMEABILITY = 0.00000125663706212;
+/**
+ * Permittivity of free space, F/m, derived from c and μ₀ rather than tabulated.
+ *
+ * Because c² = 1/(μ₀ε₀) is not a coincidence to be checked against a table, it
+ * is what Maxwell's equations SAY, and it is the argument that light is an
+ * electromagnetic wave. Writing ε₀ as a literal beside the other two lets a
+ * typo break the identity silently; writing it as the rearrangement cannot.
+ */
+declare const VACUUM_PERMITTIVITY: number;
+/** Faraday constant, C/mol: the charge on a mole of electrons. EXACT. */
+declare const FARADAY: number;
+/** Standard atmosphere, Pa. EXACT by definition. */
+declare const STANDARD_ATMOSPHERE = 101325;
+/**
+ * Molar volume of an ideal gas at 0 °C and one atmosphere, in cubic decimetres
+ * (litres) per mole. The 22.4 dm³ every chemistry course quotes.
+ *
+ * Written as RT/p rather than as 22.4, because the number is a CONSEQUENCE of a
+ * stated temperature and pressure and not a property of gases. "STP" has meant
+ * two different pressures in living memory: IUPAC moved it to 100 kPa in 1982,
+ * which gives 22.711 dm³/mol instead, and a syllabus still teaching 22.4 is
+ * using the older atmosphere. Anyone who needs the other one changes the
+ * pressure here and can see what they changed.
+ */
+declare const MOLAR_GAS_VOLUME_STP: number;
+/** Molar volume at 25 °C and one atmosphere, dm³/mol: room-temperature questions. */
+declare const MOLAR_GAS_VOLUME_RTP: number;
+/** Stefan-Boltzmann constant, W/(m²·K⁴). Derived from the exact four. */
+declare const STEFAN_BOLTZMANN = 5.670374419e-8;
+/** Wien displacement-law constant, m·K. */
+declare const WIEN_DISPLACEMENT = 0.002897771955;
+/**
+ * Newtonian constant of gravitation, m³/(kg·s²). CODATA 2018.
+ *
+ * The ODD ONE OUT in this file, and worth saying why rather than filing it silently beside the
+ * others. Every constant above is either exact by definition or known to nine or more figures.
+ * This one is known to FOUR, with a relative uncertainty around 2×10⁻⁵, which makes it the
+ * worst-measured constant in physics by a wide margin: it has been measured for two centuries and
+ * independent modern experiments still disagree past the fourth digit. Gravity is simply too weak
+ * to shield from everything else in the room.
+ *
+ * That has a consequence a gravitation kernel cannot hide from. `GM` for the Earth is known to ten
+ * significant figures because it is measured DIRECTLY, from how satellites move; `M` alone is known
+ * to four, because getting it out of `GM` means dividing by this. So a lab that quotes the Earth's
+ * mass to six figures is quoting precision that does not exist, and the product `GM` is the honest
+ * number to carry. `physics/gravitation/body.ts` carries it.
+ *
+ * Textbooks in different countries print 6.67e-11, 6.673e-11 or 6.674e-11 and a mark scheme will
+ * accept any of them at three figures. Kernels take it as a DEFAULT PARAMETER rather than reading
+ * it directly, so a lesson can pass the value its own syllabus prints and still get the marks.
+ */
+declare const GRAVITATIONAL_CONSTANT = 6.6743e-11;
+/**
+ * The offset between the Celsius and Kelvin scales, K.
+ *
+ * Note that this is a SHIFT and not a conversion factor, which is the whole
+ * reason `quantity` refuses to multiply by a Celsius temperature. 20 °C is not
+ * twice 10 °C; 293.15 K is not twice 283.15 K either, but at least the second
+ * pair is on a scale where a ratio means something.
+ */
+declare const ZERO_CELSIUS_K = 273.15;
+/**
+ * The triple point of water, K. EXACT before 2019, when it defined the kelvin;
+ * now a measured quantity that happens to sit within 0.1 mK of 273.16.
+ *
+ * Kept because the constant-volume gas thermometer is still calibrated against
+ * it in every syllabus, and T = 273.16 · (p/p_triple) is the definition those
+ * questions use.
+ */
+declare const WATER_TRIPLE_POINT_K = 273.16;
+/** Standard atmosphere, Pa. EXACT by convention. */
+declare const ATMOSPHERE_PA = 101325;
+/** Standard acceleration of free fall, m/s². EXACT by convention. */
+declare const STANDARD_GRAVITY = 9.80665;
+/**
+ * The mechanical equivalent of heat, J/cal.
+ *
+ * Joule's constant, and a historical unit conversion rather than a constant of
+ * nature: it is exactly 4.184 because the thermochemical calorie was DEFINED
+ * that way once heat was understood to be energy. That is the point of the
+ * experiment, so the number is kept where a lesson about it can reach it.
+ */
+declare const JOULES_PER_CALORIE = 4.184;
+//#endregion
+export { ATMOSPHERE_PA, AVOGADRO, BOLTZMANN, ELEMENTARY_CHARGE, FARADAY, GAS_CONSTANT, GRAVITATIONAL_CONSTANT, HC_EV_NM, JOULES_PER_CALORIE, MOLAR_GAS_VOLUME_RTP, MOLAR_GAS_VOLUME_STP, PLANCK, PLANCK_REDUCED, SPEED_OF_LIGHT, STANDARD_ATMOSPHERE, STANDARD_GRAVITY, STEFAN_BOLTZMANN, VACUUM_PERMEABILITY, VACUUM_PERMITTIVITY, WATER_TRIPLE_POINT_K, WIEN_DISPLACEMENT, ZERO_CELSIUS_K };

package/dist/core/constants.mjs

@@ -0,0 +1,139 @@
+//#region src/core/constants.ts
+/**
+* Universal physical constants, in SI, as the single place a number like the gas
+* constant is written down.
+*
+* Written because `R` had three definitions in this package: `thermo/index.ts`
+* and `chem/index.ts` both declared `8.314462618`, and `chem/relations.ts`
+* carried `8.31446262` inside its `CONSTANTS` table. The last of those is the
+* same constant rounded one digit shorter, which is the failure mode worth
+* naming: a duplicated constant does not stay duplicated, it drifts, and then
+* two parts of one calculation disagree in the eighth figure for no reason a
+* reader can find.
+*
+* Values are CODATA 2018. The four that are EXACT by the 2019 SI redefinition
+* are marked as such, because "exact" changes what a test may assert: a defined
+* constant can be compared for equality, a measured one can only be compared to
+* a tolerance.
+*
+* Domain kernels re-export what they need under their own name, so
+* `@classytic/stage/thermo` still exports `R` and nothing downstream has to know
+* this file exists. What they must not do is write the number again.
+*/
+/** Avogadro constant, per mole. EXACT by definition. */
+const AVOGADRO = 602214076e15;
+/** Boltzmann constant, J/K. EXACT by definition. */
+const BOLTZMANN = 1380649e-29;
+/**
+* Molar gas constant, J/(mol·K). EXACT, being the product of two exact
+* constants: R = N_A · k_B.
+*
+* Written as that product rather than as a literal, so the identity cannot rot.
+* A reader who doubts the digits can check the multiplication instead of a
+* table.
+*/
+const GAS_CONSTANT = AVOGADRO * BOLTZMANN;
+/** Elementary charge, C. EXACT by definition. */
+const ELEMENTARY_CHARGE = 1602176634e-28;
+/** Speed of light in vacuum, m/s. EXACT: it is what DEFINES the metre. */
+const SPEED_OF_LIGHT = 299792458;
+/** Planck constant, J·s. EXACT: it is what defines the kilogram. */
+const PLANCK = 662607015e-42;
+/** Reduced Planck constant, J·s. */
+const PLANCK_REDUCED = PLANCK / (2 * Math.PI);
+/**
+* `hc` in eV·nm, so a photon's energy in electronvolts is `HC_EV_NM / lambdaNm`.
+*
+* The most useful derived constant at this level, and worth its own export
+* rather than making every caller assemble it, because the assembly is where
+* the factors of 1e-9 and 1.602e-19 go missing.
+*/
+const HC_EV_NM = PLANCK * SPEED_OF_LIGHT / (ELEMENTARY_CHARGE * 1e-9);
+/** Permeability of free space, N/A². */
+const VACUUM_PERMEABILITY = 125663706212e-17;
+/**
+* Permittivity of free space, F/m, derived from c and μ₀ rather than tabulated.
+*
+* Because c² = 1/(μ₀ε₀) is not a coincidence to be checked against a table, it
+* is what Maxwell's equations SAY, and it is the argument that light is an
+* electromagnetic wave. Writing ε₀ as a literal beside the other two lets a
+* typo break the identity silently; writing it as the rearrangement cannot.
+*/
+const VACUUM_PERMITTIVITY = 1 / (VACUUM_PERMEABILITY * SPEED_OF_LIGHT * SPEED_OF_LIGHT);
+/** Faraday constant, C/mol: the charge on a mole of electrons. EXACT. */
+const FARADAY = AVOGADRO * ELEMENTARY_CHARGE;
+/** Standard atmosphere, Pa. EXACT by definition. */
+const STANDARD_ATMOSPHERE = 101325;
+/**
+* Molar volume of an ideal gas at 0 °C and one atmosphere, in cubic decimetres
+* (litres) per mole. The 22.4 dm³ every chemistry course quotes.
+*
+* Written as RT/p rather than as 22.4, because the number is a CONSEQUENCE of a
+* stated temperature and pressure and not a property of gases. "STP" has meant
+* two different pressures in living memory: IUPAC moved it to 100 kPa in 1982,
+* which gives 22.711 dm³/mol instead, and a syllabus still teaching 22.4 is
+* using the older atmosphere. Anyone who needs the other one changes the
+* pressure here and can see what they changed.
+*/
+const MOLAR_GAS_VOLUME_STP = GAS_CONSTANT * 273.15 * 1e3 / STANDARD_ATMOSPHERE;
+/** Molar volume at 25 °C and one atmosphere, dm³/mol: room-temperature questions. */
+const MOLAR_GAS_VOLUME_RTP = GAS_CONSTANT * 298.15 * 1e3 / STANDARD_ATMOSPHERE;
+/** Stefan-Boltzmann constant, W/(m²·K⁴). Derived from the exact four. */
+const STEFAN_BOLTZMANN = 5.670374419e-8;
+/** Wien displacement-law constant, m·K. */
+const WIEN_DISPLACEMENT = .002897771955;
+/**
+* Newtonian constant of gravitation, m³/(kg·s²). CODATA 2018.
+*
+* The ODD ONE OUT in this file, and worth saying why rather than filing it silently beside the
+* others. Every constant above is either exact by definition or known to nine or more figures.
+* This one is known to FOUR, with a relative uncertainty around 2×10⁻⁵, which makes it the
+* worst-measured constant in physics by a wide margin: it has been measured for two centuries and
+* independent modern experiments still disagree past the fourth digit. Gravity is simply too weak
+* to shield from everything else in the room.
+*
+* That has a consequence a gravitation kernel cannot hide from. `GM` for the Earth is known to ten
+* significant figures because it is measured DIRECTLY, from how satellites move; `M` alone is known
+* to four, because getting it out of `GM` means dividing by this. So a lab that quotes the Earth's
+* mass to six figures is quoting precision that does not exist, and the product `GM` is the honest
+* number to carry. `physics/gravitation/body.ts` carries it.
+*
+* Textbooks in different countries print 6.67e-11, 6.673e-11 or 6.674e-11 and a mark scheme will
+* accept any of them at three figures. Kernels take it as a DEFAULT PARAMETER rather than reading
+* it directly, so a lesson can pass the value its own syllabus prints and still get the marks.
+*/
+const GRAVITATIONAL_CONSTANT = 66743e-15;
+/**
+* The offset between the Celsius and Kelvin scales, K.
+*
+* Note that this is a SHIFT and not a conversion factor, which is the whole
+* reason `quantity` refuses to multiply by a Celsius temperature. 20 °C is not
+* twice 10 °C; 293.15 K is not twice 283.15 K either, but at least the second
+* pair is on a scale where a ratio means something.
+*/
+const ZERO_CELSIUS_K = 273.15;
+/**
+* The triple point of water, K. EXACT before 2019, when it defined the kelvin;
+* now a measured quantity that happens to sit within 0.1 mK of 273.16.
+*
+* Kept because the constant-volume gas thermometer is still calibrated against
+* it in every syllabus, and T = 273.16 · (p/p_triple) is the definition those
+* questions use.
+*/
+const WATER_TRIPLE_POINT_K = 273.16;
+/** Standard atmosphere, Pa. EXACT by convention. */
+const ATMOSPHERE_PA = 101325;
+/** Standard acceleration of free fall, m/s². EXACT by convention. */
+const STANDARD_GRAVITY = 9.80665;
+/**
+* The mechanical equivalent of heat, J/cal.
+*
+* Joule's constant, and a historical unit conversion rather than a constant of
+* nature: it is exactly 4.184 because the thermochemical calorie was DEFINED
+* that way once heat was understood to be energy. That is the point of the
+* experiment, so the number is kept where a lesson about it can reach it.
+*/
+const JOULES_PER_CALORIE = 4.184;
+
+//#endregion
+export { ATMOSPHERE_PA, AVOGADRO, BOLTZMANN, ELEMENTARY_CHARGE, FARADAY, GAS_CONSTANT, GRAVITATIONAL_CONSTANT, HC_EV_NM, JOULES_PER_CALORIE, MOLAR_GAS_VOLUME_RTP, MOLAR_GAS_VOLUME_STP, PLANCK, PLANCK_REDUCED, SPEED_OF_LIGHT, STANDARD_ATMOSPHERE, STANDARD_GRAVITY, STEFAN_BOLTZMANN, VACUUM_PERMEABILITY, VACUUM_PERMITTIVITY, WATER_TRIPLE_POINT_K, WIEN_DISPLACEMENT, ZERO_CELSIUS_K };

package/dist/core/index.d.mts

@@ -1,9 +1,11 @@
 import { Matrix, Vec2, mat, vec } from "./vec.mjs";
 import { CoordinateSystem, CoordsOptions, ViewBox, createCoords, fmt } from "./coords.mjs";
 import { ControlMap, ControlSpec, ControlSurface, getControlSurface, listControlSurfaces, onControlChange, useControlSurface } from "./control.mjs";
+import { Calc, CalcStep, Worked, calc, texNum } from "./worked.mjs";
+import { Vec3, ZERO3, add3, angleBetween3, basisFor3, cross3, dist3, distToSegment3, dot3, lerp3, mag3, midpoint3, reject3, scale3, sub3, unit3, v3, vec3 } from "./vec3.mjs";
 import { CoordsContext, DragOverlayContext, StageRefContext, useCoords, useDragOverlay, useStageRef } from "./context.mjs";
 import { ClockProvider, ClockProviderProps, FrameDriver, FrameInfo, useFrameLoop } from "./clock.mjs";
 import { Learner, LearnerProvider, LearnerResult, PriorAttempts, useLearner } from "./learner.mjs";
 import { EaseFn, EaseName, Keyframe, OscillateOpts, SpringOpts, WaveShape, ease, lerp, oscillate, prefersReducedMotion, spring, timeline } from "./motion.mjs";
 import { approxEq, clamp, clamp01, gcd, remap, round, snapTo, toDeg, toRad } from "./math.mjs";
-export { ClockProvider, type ClockProviderProps, type ControlMap, type ControlSpec, type ControlSurface, type CoordinateSystem, CoordsContext, type CoordsOptions, DragOverlayContext, type EaseFn, type EaseName, type FrameDriver, type FrameInfo, type Keyframe, type Learner, LearnerProvider, type LearnerResult, type Matrix, type OscillateOpts, type PriorAttempts, type SpringOpts, StageRefContext, type Vec2, type ViewBox, type WaveShape, approxEq, clamp, clamp01, createCoords, ease, fmt, gcd, getControlSurface, lerp, listControlSurfaces, mat, onControlChange, oscillate, prefersReducedMotion, remap, round, snapTo, spring, timeline, toDeg, toRad, useControlSurface, useCoords, useDragOverlay, useFrameLoop, useLearner, useStageRef, vec };
+export { Calc, type CalcStep, ClockProvider, type ClockProviderProps, type ControlMap, type ControlSpec, type ControlSurface, type CoordinateSystem, CoordsContext, type CoordsOptions, DragOverlayContext, type EaseFn, type EaseName, type FrameDriver, type FrameInfo, type Keyframe, type Learner, LearnerProvider, type LearnerResult, type Matrix, type OscillateOpts, type PriorAttempts, type SpringOpts, StageRefContext, type Vec2, type Vec3, type ViewBox, type WaveShape, type Worked, ZERO3, add3, angleBetween3, approxEq, basisFor3, calc, clamp, clamp01, createCoords, cross3, dist3, distToSegment3, dot3, ease, fmt, gcd, getControlSurface, lerp, lerp3, listControlSurfaces, mag3, mat, midpoint3, onControlChange, oscillate, prefersReducedMotion, reject3, remap, round, scale3, snapTo, spring, sub3, texNum, timeline, toDeg, toRad, unit3, useControlSurface, useCoords, useDragOverlay, useFrameLoop, useLearner, useStageRef, v3, vec, vec3 };

package/dist/core/index.mjs

@@ -6,5 +6,7 @@ import { getControlSurface, listControlSurfaces, onControlChange, useControlSurf
 import { LearnerProvider, useLearner } from "./learner.mjs";
 import { approxEq, clamp, clamp01, gcd, remap, round, snapTo, toDeg, toRad } from "./math.mjs";
 import { ease, lerp, oscillate, prefersReducedMotion, spring, timeline } from "./motion.mjs";
+import { ZERO3, add3, angleBetween3, basisFor3, cross3, dist3, distToSegment3, dot3, lerp3, mag3, midpoint3, reject3, scale3, sub3, unit3, v3, vec3 } from "./vec3.mjs";
+import { Calc, calc, texNum } from "./worked.mjs";
 
-export { ClockProvider, CoordsContext, DragOverlayContext, LearnerProvider, StageRefContext, approxEq, clamp, clamp01, createCoords, ease, fmt, gcd, getControlSurface, lerp, listControlSurfaces, mat, onControlChange, oscillate, prefersReducedMotion, remap, round, snapTo, spring, timeline, toDeg, toRad, useControlSurface, useCoords, useDragOverlay, useFrameLoop, useLearner, useStageRef, vec };
+export { Calc, ClockProvider, CoordsContext, DragOverlayContext, LearnerProvider, StageRefContext, ZERO3, add3, angleBetween3, approxEq, basisFor3, calc, clamp, clamp01, createCoords, cross3, dist3, distToSegment3, dot3, ease, fmt, gcd, getControlSurface, lerp, lerp3, listControlSurfaces, mag3, mat, midpoint3, onControlChange, oscillate, prefersReducedMotion, reject3, remap, round, scale3, snapTo, spring, sub3, texNum, timeline, toDeg, toRad, unit3, useControlSurface, useCoords, useDragOverlay, useFrameLoop, useLearner, useStageRef, v3, vec, vec3 };

package/dist/core/vec3.d.mts

@@ -0,0 +1,94 @@
+//#region src/core/vec3.d.ts
+/**
+ * 3D vector algebra, as the companion to `vec.ts`.
+ *
+ * Written because five files had grown their own copy: `chem/vsepr.ts` here,
+ * and four separate ones in labs (`physics/fields/spatial-core.ts`,
+ * `physics/biot-savart/core.ts`, `physics/magnetism/flux-core.ts`,
+ * `physics/magnetism/force-core.ts`). Each declared the same `{x,y,z}` shape
+ * and the same six operations, and a cross product written five times is five
+ * chances to get the sign wrong in one of them.
+ *
+ * The shape matches `Vec2`: a plain object, not a tuple or a class, so it
+ * serialises straight into scene JSON and reads the same way at a breakpoint.
+ *
+ * The named export is `vec3`, an object of operations, mirroring `vec`. The
+ * individual functions are also exported, because a line integral written with
+ * `vec3.add(vec3.scale(...))` everywhere is harder to check against the physics
+ * than one written with `add` and `scale`.
+ */
+interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+declare const v3: (x: number, y: number, z: number) => Vec3;
+declare const ZERO3: Vec3;
+declare const add3: (a: Vec3, b: Vec3) => Vec3;
+declare const sub3: (a: Vec3, b: Vec3) => Vec3;
+declare const scale3: (a: Vec3, k: number) => Vec3;
+declare const dot3: (a: Vec3, b: Vec3) => number;
+/**
+ * Right-handed cross product: a × b.
+ *
+ * The handedness is the whole content of this function. x̂ × ŷ = ẑ, which is
+ * what makes the right-hand rule come out right everywhere downstream, from a
+ * magnetic force to a torque to a surface normal.
+ */
+declare const cross3: (a: Vec3, b: Vec3) => Vec3;
+declare const mag3: (a: Vec3) => number;
+declare const dist3: (a: Vec3, b: Vec3) => number;
+/**
+ * Unit vector, which THROWS on a zero vector rather than returning one.
+ *
+ * A zero-length direction is always a caller's mistake: a segment with no
+ * length, a field point exactly on a source, an axis nobody set. Returning
+ * `{0,0,0}` or dividing by a `|| 1` guard lets that mistake travel silently
+ * into a picture, which is how a diagram ends up subtly wrong with every test
+ * still green.
+ */
+declare const unit3: (a: Vec3) => Vec3;
+/** Linear interpolation, with t = 0 at `a` and t = 1 at `b`. */
+declare const lerp3: (a: Vec3, b: Vec3, t: number) => Vec3;
+declare const midpoint3: (a: Vec3, b: Vec3) => Vec3;
+/** Angle between two vectors, in radians, clamped against floating-point drift. */
+declare const angleBetween3: (a: Vec3, b: Vec3) => number;
+/**
+ * The component of `a` perpendicular to `onto`, with the parallel part removed.
+ *
+ * The workhorse of anything that needs an in-plane direction: a flux loop's
+ * axes, a force resolved across a field, a distance from a line.
+ */
+declare const reject3: (a: Vec3, onto: Vec3) => Vec3;
+/** Shortest distance from a point to the segment ab, not to the infinite line. */
+declare const distToSegment3: (p: Vec3, a: Vec3, b: Vec3) => number;
+/**
+ * Two perpendicular unit vectors spanning the plane with this normal.
+ *
+ * A `preferred` direction becomes the FIRST axis, projected into the plane.
+ * Note that it must be projected and not merely passed to a cross product:
+ * `cross(preferred, n)` returns something perpendicular to `preferred`, which
+ * silently swaps the two axes and hands back a frame the caller did not ask
+ * for. That bug cost real time in the flux integrator.
+ */
+declare const basisFor3: (normal: Vec3, preferred?: Vec3) => [Vec3, Vec3];
+declare const vec3: {
+  v: (x: number, y: number, z: number) => Vec3;
+  add: (a: Vec3, b: Vec3) => Vec3;
+  sub: (a: Vec3, b: Vec3) => Vec3;
+  scale: (a: Vec3, k: number) => Vec3;
+  dot: (a: Vec3, b: Vec3) => number;
+  cross: (a: Vec3, b: Vec3) => Vec3;
+  mag: (a: Vec3) => number;
+  dist: (a: Vec3, b: Vec3) => number;
+  unit: (a: Vec3) => Vec3;
+  lerp: (a: Vec3, b: Vec3, t: number) => Vec3;
+  midpoint: (a: Vec3, b: Vec3) => Vec3;
+  angleBetween: (a: Vec3, b: Vec3) => number;
+  reject: (a: Vec3, onto: Vec3) => Vec3;
+  distToSegment: (p: Vec3, a: Vec3, b: Vec3) => number;
+  basisFor: (normal: Vec3, preferred?: Vec3) => [Vec3, Vec3];
+  ZERO: Vec3;
+};
+//#endregion
+export { Vec3, ZERO3, add3, angleBetween3, basisFor3, cross3, dist3, distToSegment3, dot3, lerp3, mag3, midpoint3, reject3, scale3, sub3, unit3, v3, vec3 };

package/dist/core/vec3.mjs

@@ -0,0 +1,123 @@
+//#region src/core/vec3.ts
+const v3 = (x, y, z) => ({
+	x,
+	y,
+	z
+});
+const ZERO3 = {
+	x: 0,
+	y: 0,
+	z: 0
+};
+const add3 = (a, b) => ({
+	x: a.x + b.x,
+	y: a.y + b.y,
+	z: a.z + b.z
+});
+const sub3 = (a, b) => ({
+	x: a.x - b.x,
+	y: a.y - b.y,
+	z: a.z - b.z
+});
+const scale3 = (a, k) => ({
+	x: a.x * k,
+	y: a.y * k,
+	z: a.z * k
+});
+const dot3 = (a, b) => a.x * b.x + a.y * b.y + a.z * b.z;
+/**
+* Right-handed cross product: a × b.
+*
+* The handedness is the whole content of this function. x̂ × ŷ = ẑ, which is
+* what makes the right-hand rule come out right everywhere downstream, from a
+* magnetic force to a torque to a surface normal.
+*/
+const cross3 = (a, b) => ({
+	x: a.y * b.z - a.z * b.y,
+	y: a.z * b.x - a.x * b.z,
+	z: a.x * b.y - a.y * b.x
+});
+const mag3 = (a) => Math.sqrt(dot3(a, a));
+const dist3 = (a, b) => mag3(sub3(a, b));
+/**
+* Unit vector, which THROWS on a zero vector rather than returning one.
+*
+* A zero-length direction is always a caller's mistake: a segment with no
+* length, a field point exactly on a source, an axis nobody set. Returning
+* `{0,0,0}` or dividing by a `|| 1` guard lets that mistake travel silently
+* into a picture, which is how a diagram ends up subtly wrong with every test
+* still green.
+*/
+const unit3 = (a) => {
+	const m = mag3(a);
+	if (m === 0) throw new RangeError("A zero-length vector has no direction.");
+	return scale3(a, 1 / m);
+};
+/** Linear interpolation, with t = 0 at `a` and t = 1 at `b`. */
+const lerp3 = (a, b, t) => add3(a, scale3(sub3(b, a), t));
+const midpoint3 = (a, b) => lerp3(a, b, .5);
+/** Angle between two vectors, in radians, clamped against floating-point drift. */
+const angleBetween3 = (a, b) => {
+	const denominator = mag3(a) * mag3(b);
+	if (denominator === 0) throw new RangeError("A zero-length vector has no angle.");
+	return Math.acos(Math.min(1, Math.max(-1, dot3(a, b) / denominator)));
+};
+/**
+* The component of `a` perpendicular to `onto`, with the parallel part removed.
+*
+* The workhorse of anything that needs an in-plane direction: a flux loop's
+* axes, a force resolved across a field, a distance from a line.
+*/
+const reject3 = (a, onto) => {
+	const n = unit3(onto);
+	return sub3(a, scale3(n, dot3(a, n)));
+};
+/** Shortest distance from a point to the segment ab, not to the infinite line. */
+const distToSegment3 = (p, a, b) => {
+	const ab = sub3(b, a);
+	const lengthSq = dot3(ab, ab);
+	if (lengthSq === 0) return dist3(p, a);
+	return dist3(p, add3(a, scale3(ab, Math.max(0, Math.min(1, dot3(sub3(p, a), ab) / lengthSq)))));
+};
+/**
+* Two perpendicular unit vectors spanning the plane with this normal.
+*
+* A `preferred` direction becomes the FIRST axis, projected into the plane.
+* Note that it must be projected and not merely passed to a cross product:
+* `cross(preferred, n)` returns something perpendicular to `preferred`, which
+* silently swaps the two axes and hands back a frame the caller did not ask
+* for. That bug cost real time in the flux integrator.
+*/
+const basisFor3 = (normal, preferred) => {
+	const n = unit3(normal);
+	if (preferred) {
+		const inPlane = sub3(preferred, scale3(n, dot3(preferred, n)));
+		if (mag3(inPlane) > 1e-9) {
+			const u = unit3(inPlane);
+			return [u, cross3(n, u)];
+		}
+	}
+	const u = unit3(cross3(Math.abs(n.z) < .9 ? v3(0, 0, 1) : v3(1, 0, 0), n));
+	return [u, cross3(n, u)];
+};
+const vec3 = {
+	v: v3,
+	add: add3,
+	sub: sub3,
+	scale: scale3,
+	dot: dot3,
+	cross: cross3,
+	mag: mag3,
+	dist: dist3,
+	unit: unit3,
+	lerp: lerp3,
+	midpoint: midpoint3,
+	angleBetween: angleBetween3,
+	reject: reject3,
+	distToSegment: distToSegment3,
+	basisFor: basisFor3,
+	ZERO: ZERO3
+};
+
+//#endregion
+export { ZERO3, add3, angleBetween3, basisFor3, cross3, dist3, distToSegment3, dot3, lerp3, mag3, midpoint3, reject3, scale3, sub3, unit3, v3, vec3 };

package/dist/core/worked.d.mts

@@ -0,0 +1,35 @@
+//#region src/core/worked.d.ts
+/**
+ * Worked calculations: the shape a kernel uses to SHOW ITS WORKING.
+ *
+ * A kernel that returns only an answer cannot teach. This is the data a kernel emits instead: the
+ * value plus every substitution and simplification that produced it, each as a LaTeX line with an
+ * optional note saying why that step follows. Pure and dependency-free; rendering is somebody
+ * else's job (in labs, `kit/rule`'s RuleCard and WorkedSteps).
+ *
+ * It lives in stage rather than in labs because the kernels are what produce it. A relation solver
+ * or a redox balancer that emits worked steps cannot describe its own return type if the type
+ * lives in a consumer. The renderer can stay downstream; the shape cannot.
+ */
+/** One line of a worked calculation: a LaTeX expression + an optional plain note. */
+interface CalcStep {
+  tex: string;
+  /** Why this step follows ("substitute n = 5", "the falling product"). */
+  note?: string;
+}
+/** The result of a worked calculation: the final value + the steps that got there. */
+interface Worked {
+  value: number;
+  steps: CalcStep[];
+}
+/** A tiny fluent builder: calc().step('…','…').step('…').done(value). */
+declare class Calc {
+  private readonly _steps;
+  step(tex: string, note?: string): this;
+  done(value: number): Worked;
+}
+declare const calc: () => Calc;
+/** Format a number for inline LaTeX (thin-space thousands so big counts read). */
+declare function texNum(n: number): string;
+//#endregion
+export { Calc, CalcStep, Worked, calc, texNum };