@classytic/stage 0.2.0 → 0.4.0

package/dist/math/answer-check.mjs

@@ -0,0 +1,106 @@
+import { parse } from "./parse.mjs";
+import { simplify } from "./calculus.mjs";
+import { compileExpr } from "./expr.mjs";
+
+//#region src/math/answer-check.ts
+/**
+* answer-check, the "is the student right?" layer, built on the expr engine beside it. Two modes,
+* the ones exams need:
+*
+*   • NUMBER     — value within tolerance, parsed so `pi/2` and `2*sqrt(5)` count.
+*   • EXPRESSION — any algebraically EQUIVALENT form accepted, checked BOTH symbolically
+*                  (simplify(student − answer) → 0) AND numerically by sampling, so
+*                  `(x+1)(x+2)` ≡ `x^2+3x+2`.
+*
+* Both passes run because neither is sufficient alone: the simplifier cannot collapse every
+* equivalent pair, and sampling alone would accept two expressions that happen to agree on the
+* sample points. Symbolic first, numeric as the fallback, and a minimum count of agreeing FINITE
+* samples so a pair that is undefined everywhere in the window cannot pass by default.
+*
+* Tolerances are relative, not absolute: a 1% window on a quantity of order 10⁵ is not the same
+* marking scheme as a 1% window on 0.3, and only one of those is what an exam means.
+*
+* Pure: no React, no pixels.
+*/
+/** Compile, returning the usable form or null (never the error union). */
+function tryCompile(src) {
+	const c = compileExpr(src);
+	if (c.error !== void 0) return null;
+	return c;
+}
+/** Evaluate a numeric answer string (`3.14`, `pi/2`, `2*sqrt(5)`) → number (NaN if invalid). */
+function parseValue(raw) {
+	const c = tryCompile(normalizeMathInput(raw));
+	return c ? c.fn({}) : NaN;
+}
+/**
+* Make exam-natural input parse: accept implicit multiplication (`2x` → `2*x`,
+* `)(` → `)*(`) and a leading `y =` (`y = 2x − 3` → `2*x - 3`). Conservative ,
+* never inserts `*` before `(` after a letter, so function calls like `sin(x)`
+* survive. Unicode minus → ascii.
+*/
+const SUPERSCRIPT = {
+	"⁰": "0",
+	"¹": "1",
+	"²": "2",
+	"³": "3",
+	"⁴": "4",
+	"⁵": "5",
+	"⁶": "6",
+	"⁷": "7",
+	"⁸": "8",
+	"⁹": "9"
+};
+function normalizeMathInput(raw) {
+	let s = raw.trim().replace(/−/g, "-").replace(/×/g, "*").replace(/÷/g, "/");
+	s = s.replace(/[⁰¹²³⁴⁵⁶⁷⁸⁹]+/g, (m) => "^" + [...m].map((ch) => SUPERSCRIPT[ch]).join(""));
+	s = s.replace(/\*\*/g, "^");
+	s = s.replace(/\s+/g, "");
+	s = s.replace(/^y=/i, "");
+	s = s.replace(/(\d)(?![eE][+-]?\d)([a-zA-Z(])/g, "$1*$2");
+	s = s.replace(/\)([a-zA-Z0-9(])/g, ")*$1");
+	return s;
+}
+/** Numeric match with a relative-ish tolerance (default ~1% of scale). */
+function checkNumber(student, value, tol = .01) {
+	if (!Number.isFinite(student) || !Number.isFinite(value)) return false;
+	return Math.abs(student - value) <= tol * Math.max(1, Math.abs(value));
+}
+const isZeroNode = (n, eps = 1e-9) => n.type === "num" && Math.abs(n.value) < eps;
+/** True if `student` is algebraically equivalent to `answer` (symbolic OR numeric). */
+function checkExpression(student, answer, opts = {}) {
+	const a = tryCompile(normalizeMathInput(student));
+	const b = tryCompile(normalizeMathInput(answer));
+	if (!a || !b) return false;
+	try {
+		if (isZeroNode(simplify(parse(`(${normalizeMathInput(student)}) - (${normalizeMathInput(answer)})`)), opts.tol ?? 1e-9)) return true;
+	} catch {}
+	const vars = opts.vars ?? [...new Set([...a.vars, ...b.vars])];
+	const [lo, hi] = opts.domain ?? [-3.3, 3.7];
+	const tol = opts.tol ?? 1e-6;
+	const samples = opts.samples ?? 32;
+	const PHI = .6180339887498949;
+	const R2 = .4142135623730951;
+	let finite = 0;
+	for (let i = 0; i < samples; i++) {
+		const scope = {};
+		vars.forEach((v, j) => {
+			scope[v] = lo + (hi - lo) * (((i + 1) * PHI + (j + 1) * R2) % 1);
+		});
+		const ya = a.fn(scope);
+		const yb = b.fn(scope);
+		if (!Number.isFinite(ya) || !Number.isFinite(yb)) continue;
+		finite++;
+		if (Math.abs(ya - yb) > tol * Math.max(1, Math.abs(ya), Math.abs(yb))) return false;
+	}
+	return finite >= 5;
+}
+/** Check a raw student string against an authored answer spec. */
+function checkAnswer(spec, raw) {
+	if (!raw || !raw.trim()) return false;
+	if (spec.kind === "number") return checkNumber(parseValue(raw), spec.value, spec.tol);
+	return checkExpression(raw, spec.value, spec);
+}
+
+//#endregion
+export { checkAnswer, checkExpression, checkNumber, normalizeMathInput, parseValue };

package/dist/math/calculus.d.mts

@@ -3,7 +3,23 @@ import { Node } from "./ast.mjs";
 //#region src/math/calculus.d.ts
 /** Exact symbolic derivative, or `null` if a non-differentiable node is present. */
 declare function differentiate(node: Node, x: string): Node | null;
+/**
+ * Exact symbolic antiderivative, trying the expression as written and then multiplied out.
+ *
+ * The second attempt is what makes `∫x(x+1)dx` and `∫(R²−x²)²dx` work: expand distributes, collect
+ * turns the resulting repeated factors back into powers, and then the ordinary power rule applies
+ * term by term. A single retry, because both passes are idempotent on their own output.
+ */
+declare function integrate(node: Node, x: string): Node | null;
+/**
+ * A definite integral evaluated exactly: `F(b) - F(a)`.
+ *
+ * Returned as a NUMBER rather than a node, because that is what a lesson compares a learner's
+ * answer against. Null when the antiderivative is not elementary, or when either limit lands
+ * somewhere the expression is not defined.
+ */
+declare function definiteIntegral(node: Node, x: string, lower: number, upper: number): number | null;
 /** Fold constants and trivial identities so derivative output is readable. */
 declare function simplify(node: Node): Node;
 //#endregion
-export { differentiate, simplify };
+export { definiteIntegral, differentiate, integrate, simplify };

package/dist/math/calculus.mjs

@@ -1,5 +1,5 @@
 import { FN1, FN2 } from "./defs.mjs";
-import { add, call, div, mul, neg, num, pow, sub } from "./ast.mjs";
+import { add, call, div, evaluate, mul, neg, num, pow, sub, variable } from "./ast.mjs";
 
 //#region src/math/calculus.ts
 /**
@@ -70,6 +70,343 @@ function differentiate(node, x) {
 		default: return null;
 	}
 }
+/**
+* Outer antiderivative of a 1-arg function, given its argument node `u`.
+*
+* Mirrors DERIV above. Only the functions whose antiderivative is itself elementary appear:
+* `ln` and the inverse trig functions integrate by parts into forms this table cannot express,
+* so they are absent and `integrate` returns null for them rather than guessing.
+*/
+const INTEG = {
+	sin: (u) => neg(call("cos", u)),
+	cos: (u) => call("sin", u),
+	exp: (u) => call("exp", u),
+	sinh: (u) => call("cosh", u),
+	cosh: (u) => call("sinh", u)
+};
+/** `true` when `node` holds no occurrence of `x`, so it is a constant for this integral. */
+function isConstantIn(node, x) {
+	return !freeVarsHas(node, x);
+}
+function freeVarsHas(node, x) {
+	switch (node.type) {
+		case "num": return false;
+		case "var": return node.name === x;
+		case "neg": return freeVarsHas(node.arg, x);
+		case "binary": return freeVarsHas(node.left, x) || freeVarsHas(node.right, x);
+		case "call": return node.args.some((a) => freeVarsHas(a, x));
+		default: return true;
+	}
+}
+/**
+* The constant `a` when `u` is linear in `x` (that is, `u = a·x + b`), else null.
+*
+* This is what makes the whole linear-substitution family work with one rule instead of a pattern
+* per case: if `du/dx` simplifies to a non-zero NUMBER, then `∫f(u) dx = F(u)/a`. Deriving it from
+* `differentiate` rather than matching `a*x+b` by shape means `(3-2x)^5` and `(-2x+3)^5` and
+* `3-2*x` all work without three separate matchers.
+*/
+/**
+* The `a` in `u = ax + b`, as a NODE, or null when `u` is not linear in `x`.
+*
+* It used to demand a numeric `a`, which made `sin(2x)` integrable and `sin(ωt)` not. That is the
+* wrong line to draw for physics: a coefficient that is a symbol is still a constant with respect
+* to the integration variable, and `exp(-λt)`, `sin(ωt)` and `cos(kx)` are the shape of half the
+* integrals in waves, decay and alternating current. The test is "does d/dx vanish under further
+* differentiation", not "is it a literal number".
+*/
+function linearFactor(u, x) {
+	const d = differentiate(u, x);
+	if (!d) return null;
+	const s = simplify(d);
+	if (freeVarsHas(s, x)) return null;
+	if (s.type === "num" && s.value === 0) return null;
+	return s;
+}
+/** Divide by the linear coefficient, without emitting the noise of `expr / 1`. */
+const overConst = (node, a) => a.type === "num" && a.value === 1 ? node : div(node, a);
+/**
+* Exact symbolic antiderivative with respect to `x`, or `null` when this engine cannot do it.
+*
+* The constant of integration is NOT included. That is deliberate: `+ c` is the single most
+* commonly dropped mark in the topic, so it belongs in the lesson's own working where a learner
+* has to write it, not silently bolted on by the engine.
+*
+* Covers: linearity, the power rule including the `1/x → ln|x|` exception, any of those composed
+* with a linear inner function whose coefficient may be a SYMBOL (`sin(ωt)`, `e^{-λt}`), and any
+* polynomial that becomes one of the above after being multiplied out.
+*
+* Returns null for integration by parts (`x·eˣ`), non-linear substitution (`√(1−x²)`, `x/(1+x²)`)
+* and trigonometric powers (`sin²x`). A caller that must produce a number regardless should fall
+* back to `quadrature` in `analysis.ts` and say that it did, rather than show a wrong formula.
+* `physics/integral-sweep` is the worked example of that pattern.
+*/
+/**
+* Squares and cubes of the trigonometric functions.
+*
+* These are not power-rule cases and they are not substitutions either. Each is a standard identity
+* that turns the power into something already integrable:
+*
+*     ∫sin²u du = u/2 − sin 2u / 4          the double-angle identity, cos 2u = 1 − 2sin²u
+*     ∫cos²u du = u/2 + sin 2u / 4
+*     ∫sin³u du = −cos u + cos³u / 3        writing sin³ as sin·(1 − cos²) and substituting
+*     ∫cos³u du =  sin u − sin³u / 3
+*     ∫tan²u du =  tan u − u                from sec² = 1 + tan²
+*
+* WHY THESE FIVE AND NOT A GENERAL REDUCTION FORMULA. Squares are the ones that actually turn up:
+* mean power in an alternating circuit is `∫sin²`, a spherical shell parameterised by angle is
+* `∫sin³`, and between them they cover the syllabus. A general `sin^n` reduction is a much larger
+* commitment for cases nobody sets, and returning null for `sin⁴` is honest.
+*
+* The inner function may be linear with a symbolic coefficient, so `sin²(ωt)` works, which is the
+* form every alternating-current question is actually written in.
+*/
+function integrateTrigPower(base, n, x) {
+	if (base.type !== "call" || base.args.length !== 1) return null;
+	const u = base.args[0];
+	if (!u) return null;
+	const a = linearFactor(u, x);
+	if (a === null) return null;
+	const sin = (arg) => call("sin", arg);
+	const cos = (arg) => call("cos", arg);
+	if (n === 2) {
+		if (base.fn === "sin") return overConst(sub(div(u, num(2)), div(sin(mul(num(2), u)), num(4))), a);
+		if (base.fn === "cos") return overConst(add(div(u, num(2)), div(sin(mul(num(2), u)), num(4))), a);
+		if (base.fn === "tan") return overConst(sub(call("tan", u), u), a);
+		return null;
+	}
+	if (n === 3) {
+		if (base.fn === "sin") return overConst(add(neg(cos(u)), div(pow(cos(u), num(3)), num(3))), a);
+		if (base.fn === "cos") return overConst(sub(sin(u), div(pow(sin(u), num(3)), num(3))), a);
+		return null;
+	}
+	return null;
+}
+/** How far `expand` will raise a sum before giving up. 8 covers anything at this level. */
+const MAX_EXPAND_POWER = 8;
+/**
+* Multiply out products and integer powers of sums: `(R² − x²)²` becomes `R⁴ − 2R²x² + x⁴`.
+*
+* This exists because of a sharp edge in the integrator. It handles a sum term by term and a power
+* of a LINEAR inner function, so `R⁴ − 2R²x² + x⁴` integrates and the identical `(R² − x²)²` does
+* not. A student writing the moment of inertia of a sphere writes the second form, and being told
+* it is not integrable while its expansion is would be indefensible.
+*
+* Not a general simplifier and not a normal form: it distributes and it raises, and it leaves
+* everything else alone. `simplify` is still what tidies the result.
+*/
+function expand(node) {
+	switch (node.type) {
+		case "neg": return neg(expand(node.arg));
+		case "call": return call(node.fn, ...node.args.map(expand));
+		case "binary": {
+			const left = expand(node.left);
+			const right = expand(node.right);
+			switch (node.op) {
+				case "+": return add(left, right);
+				case "-": return sub(left, right);
+				case "*": return distribute(left, right);
+				case "/": return isSum(left) ? expand(distributeOverSum(left, (t) => div(t, right))) : div(left, right);
+				case "^": {
+					const exponent = simplify(right);
+					if (!isSum(left) || exponent.type !== "num") return pow(left, right);
+					const n = exponent.value;
+					if (!Number.isInteger(n) || n < 2 || n > MAX_EXPAND_POWER) return pow(left, right);
+					let out = left;
+					for (let i = 1; i < n; i++) out = distribute(out, left);
+					return out;
+				}
+				default: return {
+					...node,
+					left,
+					right
+				};
+			}
+		}
+		default: return node;
+	}
+}
+const isSum = (node) => node.type === "binary" && (node.op === "+" || node.op === "-");
+/** Apply `f` to each term of a sum, preserving the signs. */
+function distributeOverSum(sum, f) {
+	if (sum.type === "binary" && sum.op === "+") return add(distributeOverSum(sum.left, f), distributeOverSum(sum.right, f));
+	if (sum.type === "binary" && sum.op === "-") return sub(distributeOverSum(sum.left, f), distributeOverSum(sum.right, f));
+	return f(sum);
+}
+/** `(a + b)(c + d)` term by term, in whichever direction has a sum. */
+function distribute(left, right) {
+	if (isSum(left)) return distributeOverSum(left, (term) => distribute(term, right));
+	if (isSum(right)) return distributeOverSum(right, (term) => distribute(left, term));
+	return mul(left, right);
+}
+/**
+* A structural key for a node, so two occurrences of the same factor can be recognised.
+*
+* Deliberately crude and deliberately not a canonical form: `x*y` and `y*x` get different keys, so
+* they are not merged. Merging them would need an ordering over expressions, which is a much larger
+* commitment than this needs. Failing to merge costs nothing except a missed simplification.
+*/
+function key(node) {
+	switch (node.type) {
+		case "num": return `#${node.value}`;
+		case "var": return `$${node.name}`;
+		case "neg": return `-(${key(node.arg)})`;
+		case "binary": return `(${key(node.left)}${node.op}${key(node.right)})`;
+		case "call": return `${node.fn}(${node.args.map(key).join(",")})`;
+		default: return "?";
+	}
+}
+/**
+* Gather repeated factors into powers: `x·x` becomes `x²`, and `(x+1)/x` becomes `1 + x⁻¹`.
+*
+* Without this, `expand` is almost useless to the integrator. `∫x(x+1)dx` expands to `∫(x·x + x)dx`
+* and the power rule reads `^`, not repeated multiplication, so it would still refuse. Division is
+* folded in as a negative exponent, which is also what lets the `1/x → ln|x|` rule be reached
+* through a quotient that was written as a fraction of sums.
+*/
+function collect(node) {
+	const factors = [];
+	let numeric = 1;
+	let ok = true;
+	const gather = (n, sign) => {
+		if (!ok) return;
+		if (n.type === "binary" && n.op === "*") {
+			gather(n.left, sign);
+			gather(n.right, sign);
+			return;
+		}
+		if (n.type === "binary" && n.op === "/") {
+			gather(n.left, sign);
+			gather(n.right, sign === 1 ? -1 : 1);
+			return;
+		}
+		let base = n;
+		let exponent = 1;
+		if (n.type === "binary" && n.op === "^") {
+			const e = simplify(n.right);
+			if (e.type === "num" && Number.isFinite(e.value)) {
+				base = n.left;
+				exponent = e.value;
+			}
+		}
+		if (base.type === "num") {
+			if (exponent !== 1 && !Number.isInteger(exponent)) ok = false;
+			numeric *= Math.pow(base.value, sign * exponent);
+			return;
+		}
+		const k = key(base);
+		const found = factors.find((f) => key(f.base) === k);
+		if (found) found.exponent += sign * exponent;
+		else factors.push({
+			base,
+			exponent: sign * exponent
+		});
+	};
+	gather(node, 1);
+	if (!ok) return node;
+	const parts = [];
+	for (const { base, exponent } of factors) {
+		if (exponent === 0) continue;
+		parts.push(exponent === 1 ? base : pow(base, num(exponent)));
+	}
+	if (numeric !== 1 || parts.length === 0) parts.unshift(num(numeric));
+	return parts.reduce((a, b) => mul(a, b));
+}
+/** Run `collect` over every product in a sum, leaving the sum's shape alone. */
+function collectAll(node) {
+	if (node.type === "binary" && (node.op === "+" || node.op === "-")) {
+		const left = collectAll(node.left);
+		const right = collectAll(node.right);
+		return node.op === "+" ? add(left, right) : sub(left, right);
+	}
+	if (node.type === "neg") return neg(collectAll(node.arg));
+	if (node.type === "binary" && (node.op === "*" || node.op === "/")) return collect(node);
+	return node;
+}
+/**
+* Exact symbolic antiderivative, trying the expression as written and then multiplied out.
+*
+* The second attempt is what makes `∫x(x+1)dx` and `∫(R²−x²)²dx` work: expand distributes, collect
+* turns the resulting repeated factors back into powers, and then the ordinary power rule applies
+* term by term. A single retry, because both passes are idempotent on their own output.
+*/
+function integrate(node, x) {
+	return integrateDirect(node, x) ?? integrateDirect(collectAll(expand(node)), x);
+}
+function integrateDirect(node, x) {
+	if (isConstantIn(node, x)) return mul(node, variable(x));
+	switch (node.type) {
+		case "var": return div(pow(variable(x), num(2)), num(2));
+		case "neg": {
+			const inner = integrate(node.arg, x);
+			return inner && neg(inner);
+		}
+		case "binary": {
+			const { op, left, right } = node;
+			if (op === "+" || op === "-") {
+				const l = integrate(left, x);
+				const r = integrate(right, x);
+				return l && r && (op === "+" ? add(l, r) : sub(l, r));
+			}
+			if (op === "*") {
+				if (isConstantIn(left, x)) {
+					const r = integrate(right, x);
+					return r && mul(left, r);
+				}
+				if (isConstantIn(right, x)) {
+					const l = integrate(left, x);
+					return l && mul(right, l);
+				}
+				return null;
+			}
+			if (op === "/") {
+				if (isConstantIn(right, x)) {
+					const l = integrate(left, x);
+					return l && div(l, right);
+				}
+				if (isConstantIn(left, x)) {
+					const a = linearFactor(right, x);
+					return a === null ? null : overConst(mul(left, call("ln", call("abs", right))), a);
+				}
+				return null;
+			}
+			if (op === "^") {
+				const exponent = simplify(right);
+				if (exponent.type !== "num") return null;
+				const n = exponent.value;
+				const trig = integrateTrigPower(left, n, x);
+				if (trig) return trig;
+				const a = linearFactor(left, x);
+				if (a === null) return null;
+				if (n === -1) return overConst(call("ln", call("abs", left)), a);
+				return overConst(div(pow(left, num(n + 1)), num(n + 1)), a);
+			}
+			return null;
+		}
+		case "call": {
+			const u = node.args[0];
+			const rule = INTEG[node.fn];
+			if (!rule || !u || node.args.length !== 1) return null;
+			const a = linearFactor(u, x);
+			return a === null ? null : overConst(rule(u), a);
+		}
+		default: return null;
+	}
+}
+/**
+* A definite integral evaluated exactly: `F(b) - F(a)`.
+*
+* Returned as a NUMBER rather than a node, because that is what a lesson compares a learner's
+* answer against. Null when the antiderivative is not elementary, or when either limit lands
+* somewhere the expression is not defined.
+*/
+function definiteIntegral(node, x, lower, upper) {
+	const F = integrate(node, x);
+	if (!F) return null;
+	const at = (v) => evaluate(F, { [x]: v });
+	const result = at(upper) - at(lower);
+	return Number.isFinite(result) ? result : null;
+}
 const isNum = (n, v) => n.type === "num" && (v === void 0 || n.value === v);
 /** A stable structural key, so identical cores group (x and x; x² and x²). */
 function nodeKey(n) {
@@ -192,10 +529,36 @@ function simplify(node) {
 							right: l.left
 						};
 					}
+					/**
+					* Cancel a constant against a fraction's denominator: c·(a/b) → (c/b)·a.
+					*
+					* `∫3x² dx` is the plainest case. The constant comes out of the integral and the power
+					* rule divides by 3, so the honest answer is `3·(x³/3)`. A learner expects `x³`, and
+					* only the fully cancelled form is worth showing as the ANSWER.
+					*/
+					if (l.type === "num" && r.type === "binary" && r.op === "/" && r.right.type === "num") {
+						const k = l.value / r.right.value;
+						if (Number.isInteger(k)) return k === 1 ? r.left : simplify(mul(num(k), r.left));
+					}
+					if (r.type === "num" && l.type === "binary" && l.op === "/" && l.right.type === "num") {
+						const k = r.value / l.right.value;
+						if (Number.isInteger(k)) return k === 1 ? l.left : simplify(mul(num(k), l.left));
+					}
 					break;
 				case "/":
 					if (isNum(r, 1)) return l;
 					if (isNum(l, 0)) return num(0);
+					/**
+					* Collapse a nested fraction: (a/b)/c → a/(bc).
+					*
+					* Integration produces these constantly, because the power rule divides by n+1 and the
+					* linear-substitution rule then divides by a. Left alone, ∫(2x+1)³dx renders as a
+					* fraction inside a fraction, which is correct and unreadable, and unreadable is the
+					* complaint this engine exists to answer.
+					*/
+					if (r.type === "num" && l.type === "binary" && l.op === "/" && l.right.type === "num") return simplify(div(l.left, num(l.right.value * r.value)));
+					if (r.type === "num" && r.value < 0) return simplify(neg(div(l, num(-r.value))));
+					if (l.type === "neg") return neg(simplify(div(l.arg, r)));
 					break;
 				case "^":
 					if (isNum(r, 1)) return l;
@@ -244,4 +607,4 @@ function fold(op, a, b) {
 }
 
 //#endregion
-export { differentiate, simplify };
+export { definiteIntegral, differentiate, integrate, simplify };

package/dist/math/complex.d.mts

@@ -0,0 +1,93 @@
+declare namespace complex_d_exports {
+  export { Complex, DEG2RAD, I, MAX_POW, MAX_ROOTS, ONE, RAD2DEG, TWO_PI, ZERO, abs, add, arg, argDeg, conj, cx, div, eq, fromPolar, iPow, isFiniteC, mul, neg, nthRoots, omega, powInt, rootsOfUnity, scale, sub, toPolar, toStr, toTex };
+}
+/**
+ * Complex-number kernel, the pure engine every complex/Argand/polar lab computes
+ * against (so a lab — or an agent — never hand-rolls a²+b² or atan2). A complex
+ * number is rectangular `{ re, im }`; the polar view (modulus r, argument θ) is
+ * derived, exactly the (x, y) ↔ (r, θ) bridge the vector labs already teach.
+ *
+ * Engineered for CORRECTNESS + SAFETY (no NaN spirals, no overflow, no runaway
+ * loops):
+ *   • modulus uses Math.hypot (no re²+im² overflow);
+ *   • division uses Smith's algorithm (scale by the larger term, avoids overflow
+ *     / underflow), with a near-zero-denominator guard;
+ *   • integer powers use exponentiation-by-squaring, |n| capped (MAX_POW), with a
+ *     finiteness guard so r^n that overflows returns an explicit ∞, not garbage;
+ *   • iⁿ is computed EXACTLY from n mod 4 (no float drift in the i, −1, −i, 1 cycle);
+ *   • rootsOfUnity / nthRoots cap n (MAX_ROOTS) so an author can't request a
+ *     billion-element array.
+ */
+interface Complex {
+  re: number;
+  im: number;
+}
+declare const TWO_PI: number;
+declare const RAD2DEG: number;
+declare const DEG2RAD: number;
+/** Hard caps so an authored value can never blow memory or hang a loop. */
+declare const MAX_POW = 1024;
+declare const MAX_ROOTS = 360;
+declare const cx: (re: number, im?: number) => Complex;
+declare const ZERO: Complex;
+declare const ONE: Complex;
+declare const I: Complex;
+declare const isFiniteC: (z: Complex) => boolean;
+declare const add: (a: Complex, b: Complex) => Complex;
+declare const sub: (a: Complex, b: Complex) => Complex;
+declare const neg: (a: Complex) => Complex;
+declare const conj: (a: Complex) => Complex;
+declare const scale: (a: Complex, k: number) => Complex;
+/** (a+bi)(c+di) = (ac − bd) + (ad + bc)i. */
+declare const mul: (a: Complex, b: Complex) => Complex;
+/**
+ * Complex division via Smith's algorithm: divide through by the LARGER of the
+ * denominator's components so the intermediate ratio stays in [−1, 1] (no
+ * overflow when |b| is huge, no underflow when tiny). Returns an ∞/NaN complex
+ * for a (near-)zero denominator rather than throwing.
+ */
+declare function div(a: Complex, b: Complex): Complex;
+/** Modulus |z| = √(re² + im²), via hypot so large components don't overflow. */
+declare const abs: (z: Complex) => number;
+/** Argument arg(z) in RADIANS, in (−π, π]. arg(0) = 0 by convention. */
+declare const arg: (z: Complex) => number;
+/** Argument in DEGREES, in (−180, 180]. */
+declare const argDeg: (z: Complex) => number;
+/** Polar → rectangular: r·e^{iθ} = r(cosθ + i sinθ), θ in radians. */
+declare const fromPolar: (r: number, theta: number) => Complex;
+/** Rectangular → polar { r, theta(rad) }. */
+declare const toPolar: (z: Complex) => {
+  r: number;
+  theta: number;
+};
+/**
+ * iⁿ for any integer n, EXACTLY (no De Moivre float drift): the 4-cycle
+ * 1, i, −1, −i. Negative n handled by the (n mod 4 + 4) mod 4 normalisation.
+ */
+declare function iPow(n: number): Complex;
+/**
+ * zⁿ for an INTEGER n via exponentiation-by-squaring (negative n inverts).
+ * |n| is capped at MAX_POW; an overflowing magnitude returns an explicit ∞
+ * complex (finite check) instead of looping into garbage.
+ */
+declare function powInt(z: Complex, n: number): Complex;
+/**
+ * The n nth-roots of UNITY: e^{2πik/n}, k = 0…n−1 (so ω = roots[1] is the
+ * primitive root). For n = 2 → {1, −1}; n = 3 → {1, ω, ω²}; n = 4 → {1, i, −1, −i}.
+ * n is clamped to [1, MAX_ROOTS]. The k = n/2 (real −1) and k = 0 (real 1) entries
+ * are snapped to exact values so labels read cleanly.
+ */
+declare function rootsOfUnity(n: number): Complex[];
+/** The n nth-roots of any z: |z|^{1/n} · e^{i(arg z + 2πk)/n}, k = 0…n−1. */
+declare function nthRoots(z: Complex, n: number): Complex[];
+/** The primitive nth root of unity ω (default the CUBE root, n = 3): e^{2πi/n}.
+ *  For n = 3: ω = −½ + (√3/2)i, with ω³ = 1 and 1 + ω + ω² = 0. */
+declare const omega: (n?: number) => Complex;
+/** Equal within a tolerance (default 1e-9), on both components. */
+declare const eq: (a: Complex, b: Complex, eps?: number) => boolean;
+/** Plain string, e.g. "3 − 2i", "i", "−1", "0", "2i". */
+declare function toStr(z: Complex, dp?: number): string;
+/** LaTeX form for <Tex> (uses real minus signs, "i"). */
+declare function toTex(z: Complex, dp?: number): string;
+//#endregion
+export { Complex, complex_d_exports };