@jarenjs/core 0.9.2 → 0.34.0

package/src/math/format.js

@@ -0,0 +1,157 @@
+//@ts-check
+/**
+ * @file Number formatting and parsing. The
+ * one place the suite formats a number for display: notation control
+ * (auto/fixed/sci/eng), thousands grouping and radix output, plus a
+ * radix-aware `parseNumber`. Radix I/O delegates to `math/word.js` so
+ * base conversion is never re-implemented.
+ */
+
+import { toBase, fromBase } from './word.js';
+
+/**
+ * @typedef {object} FormatOptions
+ * @property {'auto'|'fixed'|'sci'|'eng'} [notation] default 'auto'
+ * @property {number} [precision] significant/decimal digits (notation-dependent)
+ * @property {boolean|string} [group] thousands separator: true → ',', or a custom string
+ * @property {number} [radix] 2..36; when not 10, `value` is formatted as an integer word
+ * @property {string} [decimal] decimal mark, default '.'
+ */
+
+/**
+ * Insert a grouping separator every three digits of an integer string
+ * (sign-aware).
+ * @param {string} intPart
+ * @param {string} sep
+ * @returns {string}
+ */
+function groupInteger(intPart, sep) {
+  let neg = '';
+  let s = intPart;
+  if (s.startsWith('-')) { neg = '-'; s = s.slice(1); }
+  const parts = [];
+  for (let i = s.length; i > 0; i -= 3) {
+    parts.unshift(s.slice(Math.max(0, i - 3), i));
+  }
+  return neg + parts.join(sep);
+}
+
+/**
+ * Engineering notation: mantissa in [1, 1000) times 10^(3k).
+ * @param {number} value
+ * @param {number} precision
+ * @returns {string}
+ */
+function toEngineering(value, precision) {
+  if (value === 0) return '0e+0';
+  const exp = Math.floor(Math.log10(Math.abs(value)));
+  const engExp = Math.floor(exp / 3) * 3;
+  const mantissa = value / Math.pow(10, engExp);
+  const m = precision >= 0 ? mantissa.toFixed(precision) : String(mantissa);
+  return `${m}e${engExp >= 0 ? '+' : ''}${engExp}`;
+}
+
+/**
+ * Format a number for display.
+ *
+ * `notation: 'auto'` (the default) is NOT a drop-in for a fixed-unit
+ * readout: the auto branch escapes to exponential once
+ * `abs(value) >= 1e21` or `abs(value) < 1e-6`, so
+ * `formatNumber(v, { precision: 3 })` is not interchangeable with a
+ * plain `Number(v.toPrecision(3))`. A caller that appends its own unit
+ * - `"0.0509 ms"` - wants the value never to become `5.09e-5`, and must
+ * either pass `notation: 'fixed'` or keep its own rounder. See
+ * packages/core/docs/MATH.md.
+ * @param {number} value
+ * @param {FormatOptions} [opts]
+ * @returns {string}
+ */
+export function formatNumber(value, opts = {}) {
+  value = +value;
+  if (Number.isNaN(value)) return 'NaN';
+  if (value === Infinity) return '∞';
+  if (value === -Infinity) return '-∞';
+
+  const notation = opts.notation ?? 'auto';
+  const sep = opts.group === true ? ',' : (typeof opts.group === 'string' ? opts.group : '');
+  const decimal = opts.decimal ?? '.';
+
+  // Radix output: integer word in the requested base.
+  if (opts.radix !== undefined && opts.radix !== 10) {
+    let str = toBase(Math.trunc(value), opts.radix, { upper: true });
+    if (sep) str = groupInteger(str, sep);
+    return str;
+  }
+
+  let out;
+  if (notation === 'fixed') {
+    out = value.toFixed(opts.precision ?? 2);
+  }
+  else if (notation === 'sci') {
+    out = value.toExponential(opts.precision ?? undefined);
+  }
+  else if (notation === 'eng') {
+    out = toEngineering(value, opts.precision ?? 3);
+  }
+  else {
+    // auto: plain decimal for human-scale magnitudes, else scientific.
+    const abs = Math.abs(value);
+    if (value !== 0 && (abs >= 1e21 || abs < 1e-6)) {
+      out = opts.precision !== undefined ? value.toExponential(opts.precision) : value.toExponential();
+    }
+    else if (opts.precision !== undefined) {
+      out = String(Number(value.toPrecision(opts.precision)));
+    }
+    else {
+      out = String(value);
+    }
+  }
+
+  if (sep || decimal !== '.') {
+    const eIdx = out.search(/[eE]/);
+    const exp = eIdx >= 0 ? out.slice(eIdx) : '';
+    const mant = eIdx >= 0 ? out.slice(0, eIdx) : out;
+    const dot = mant.indexOf('.');
+    const intPart = dot >= 0 ? mant.slice(0, dot) : mant;
+    const frac = dot >= 0 ? mant.slice(dot + 1) : '';
+    out = (sep ? groupInteger(intPart, sep) : intPart)
+      + (frac ? decimal + frac : '')
+      + exp;
+  }
+  return out;
+}
+
+/**
+ * Parse a numeric string, radix-aware. Recognizes `0x`/`0o`/`0b`
+ * prefixes, an explicit `radix` option, grouping separators (`,`/`_`/
+ * space) and base-10 scientific notation. Returns `NaN` on failure
+ * rather than throwing.
+ *
+ * @param {string} str
+ * @param {{ radix?: number }} [opts]
+ * @returns {number}
+ */
+export function parseNumber(str, opts = {}) {
+  if (typeof str !== 'number') str = String(str);
+  else return +str;
+  let s = str.trim();
+  if (s === '') return NaN;
+  const lower = s.toLowerCase();
+  if (lower === 'nan') return NaN;
+  if (lower === '∞' || lower === 'infinity' || lower === '+infinity') return Infinity;
+  if (lower === '-∞' || lower === '-infinity') return -Infinity;
+
+  const prefixed = /^[+-]?0[xob]/i.test(s);
+  if (prefixed || (opts.radix !== undefined && opts.radix !== 10)) {
+    try {
+      return Number(fromBase(s, opts.radix ?? 10));
+    }
+    catch {
+      return NaN;
+    }
+  }
+  // Base 10: strip grouping, keep the numeric grammar.
+  const cleaned = s.replace(/[,_ ]/g, '');
+  if (!/^[+-]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i.test(cleaned)) return NaN;
+  return Number(cleaned);
+}

package/src/math/index.js

@@ -3,3 +3,8 @@ export * from './vec2i32.js';
 export * from './float64.js';
 export * from './vec2f64.js';
 export * from './vec3f64.js';
+export * from './word.js';
+export * from './solve.js';
+export * from './mat4.js';
+export * from './project.js';
+export * from './format.js';

package/src/math/mat4.js

@@ -0,0 +1,131 @@
+//@ts-check
+/**
+ * @file A minimal 4×4 matrix kernel for the x·y·z plotter and
+ * any future 3D consumer (Mermaid 3D is a candidate — see ROADMAP).
+ *
+ * Matrices are `Float64Array(16)` in **column-major** order (the WebGL /
+ * glMatrix convention): element `m[col * 4 + row]`. Every factory returns
+ * a fresh array; `multiply` composes right-to-left like linear algebra
+ * (`multiply(a, b)` applies `b` then `a` to a column vector).
+ */
+
+/** @typedef {Float64Array} Mat4Array */
+
+export class Mat4 {
+  /** @returns {Mat4Array} the 4×4 identity. */
+  static identity() {
+    const m = new Float64Array(16);
+    m[0] = 1; m[5] = 1; m[10] = 1; m[15] = 1;
+    return m;
+  }
+
+  /**
+   * `a · b` (column-major). Neither operand is mutated.
+   * @param {Mat4Array} a @param {Mat4Array} b
+   * @returns {Mat4Array}
+   */
+  static multiply(a, b) {
+    const out = new Float64Array(16);
+    for (let col = 0; col < 4; col++) {
+      for (let row = 0; row < 4; row++) {
+        let s = 0;
+        for (let k = 0; k < 4; k++) {
+          s += a[k * 4 + row] * b[col * 4 + k];
+        }
+        out[col * 4 + row] = s;
+      }
+    }
+    return out;
+  }
+
+  /** @param {number} rad @returns {Mat4Array} */
+  static rotationX(rad) {
+    const c = Math.cos(rad); const s = Math.sin(rad);
+    const m = Mat4.identity();
+    m[5] = c; m[6] = s; m[9] = -s; m[10] = c;
+    return m;
+  }
+
+  /** @param {number} rad @returns {Mat4Array} */
+  static rotationY(rad) {
+    const c = Math.cos(rad); const s = Math.sin(rad);
+    const m = Mat4.identity();
+    m[0] = c; m[2] = -s; m[8] = s; m[10] = c;
+    return m;
+  }
+
+  /** @param {number} rad @returns {Mat4Array} */
+  static rotationZ(rad) {
+    const c = Math.cos(rad); const s = Math.sin(rad);
+    const m = Mat4.identity();
+    m[0] = c; m[1] = s; m[4] = -s; m[5] = c;
+    return m;
+  }
+
+  /** @param {number} tx @param {number} ty @param {number} tz @returns {Mat4Array} */
+  static translation(tx, ty, tz) {
+    const m = Mat4.identity();
+    m[12] = tx; m[13] = ty; m[14] = tz;
+    return m;
+  }
+
+  /** @param {number} sx @param {number} sy @param {number} sz @returns {Mat4Array} */
+  static scaling(sx, sy, sz) {
+    const m = new Float64Array(16);
+    m[0] = sx; m[5] = sy; m[10] = sz; m[15] = 1;
+    return m;
+  }
+
+  /**
+   * Orthographic projection.
+   * @param {number} l @param {number} r @param {number} b @param {number} t
+   * @param {number} n @param {number} f
+   * @returns {Mat4Array}
+   */
+  static ortho(l, r, b, t, n, f) {
+    const m = new Float64Array(16);
+    m[0] = 2 / (r - l);
+    m[5] = 2 / (t - b);
+    m[10] = -2 / (f - n);
+    m[12] = -(r + l) / (r - l);
+    m[13] = -(t + b) / (t - b);
+    m[14] = -(f + n) / (f - n);
+    m[15] = 1;
+    return m;
+  }
+
+  /**
+   * Perspective projection (right-handed, clip space z in [-1, 1]).
+   * @param {number} fovy vertical field of view, radians
+   * @param {number} aspect width / height
+   * @param {number} n near plane (> 0)
+   * @param {number} f far plane
+   * @returns {Mat4Array}
+   */
+  static perspective(fovy, aspect, n, f) {
+    const t = 1 / Math.tan(fovy / 2);
+    const m = new Float64Array(16);
+    m[0] = t / aspect;
+    m[5] = t;
+    m[10] = (f + n) / (n - f);
+    m[11] = -1;
+    m[14] = (2 * f * n) / (n - f);
+    return m;
+  }
+
+  /**
+   * Transform a 3D point (implicit w = 1) by `m`, returning the
+   * perspective-divided `{ x, y, z, w }` (w is the pre-divide clip w, so
+   * callers can reject points behind the camera).
+   * @param {Mat4Array} m @param {number} x @param {number} y @param {number} z
+   * @returns {{ x: number, y: number, z: number, w: number }}
+   */
+  static transformPoint(m, x, y, z) {
+    const cx = m[0] * x + m[4] * y + m[8] * z + m[12];
+    const cy = m[1] * x + m[5] * y + m[9] * z + m[13];
+    const cz = m[2] * x + m[6] * y + m[10] * z + m[14];
+    const cw = m[3] * x + m[7] * y + m[11] * z + m[15];
+    const w = cw === 0 ? 1 : cw;
+    return { x: cx / w, y: cy / w, z: cz / w, w: cw };
+  }
+}

package/src/math/project.js

@@ -0,0 +1,49 @@
+//@ts-check
+/**
+ * @file 3D → 2D projection helpers, built on `Mat4` and the
+ * existing `Vec3f64`. Used by the x·y·z plotter to turn a rotated grid
+ * of surface points into screen coordinates and to shade faces.
+ */
+
+import { Mat4 } from './mat4.js';
+import { Vec3f64 } from './vec3f64.js';
+
+/**
+ * @typedef {object} Viewport
+ * @property {number} x left edge in pixels
+ * @property {number} y top edge in pixels
+ * @property {number} width
+ * @property {number} height
+ */
+
+/**
+ * Project a 3D point through `mat` (model·view·projection) and map the
+ * resulting normalized device coordinates into `viewport` pixels. The Y
+ * axis is flipped so that +Y is up in world space but down in screen
+ * space, as SVG expects.
+ *
+ * @param {{ x: number, y: number, z: number } | import('./vec3f64.js').Vec3f64} point3
+ * @param {import('./mat4.js').Mat4Array} mat
+ * @param {Viewport} viewport
+ * @returns {{ x: number, y: number, z: number, w: number }}
+ */
+export function project3dTo2d(point3, mat, viewport) {
+  const clip = Mat4.transformPoint(mat, +point3.x, +point3.y, +point3.z);
+  const sx = viewport.x + (clip.x * 0.5 + 0.5) * viewport.width;
+  const sy = viewport.y + (0.5 - clip.y * 0.5) * viewport.height;
+  return { x: sx, y: sy, z: clip.z, w: clip.w };
+}
+
+/**
+ * The (un-normalized) surface normal of triangle `a→b→c`, right-hand
+ * winding. Returns a `Vec3f64`.
+ * @param {import('./vec3f64.js').Vec3f64} a
+ * @param {import('./vec3f64.js').Vec3f64} b
+ * @param {import('./vec3f64.js').Vec3f64} c
+ * @returns {import('./vec3f64.js').Vec3f64}
+ */
+export function surfaceNormal(a, b, c) {
+  const ab = Vec3f64.sub(b, a);
+  const ac = Vec3f64.sub(c, a);
+  return Vec3f64.cross(ab, ac);
+}

package/src/math/solve.js

@@ -0,0 +1,112 @@
+//@ts-check
+/**
+ * @file Generic, domain-free numeric root finders. No finance
+ * or geometry lives here; `@jarenjs/core/finance` builds NPV/IRR/rate on
+ * top of these, the calculator's equation helpers on top of them too.
+ *
+ * Each solver returns a `{ root, iterations, converged }` record instead
+ * of throwing on non-convergence — callers decide how to react (finance
+ * falls back from Newton to bisection, for example).
+ */
+
+/**
+ * @typedef {object} SolveResult
+ * @property {number} root the best estimate found
+ * @property {number} iterations iterations actually run
+ * @property {boolean} converged whether `tol` was reached
+ */
+
+const DEFAULT_TOL = 1e-10;
+const DEFAULT_MAX_ITER = 100;
+
+/**
+ * Newton–Raphson using an explicit derivative. Falls back to reporting
+ * non-convergence (rather than diverging silently) when the derivative
+ * vanishes or the step explodes.
+ *
+ * @param {(x: number) => number} f
+ * @param {(x: number) => number} df
+ * @param {number} x0
+ * @param {{ tol?: number, maxIter?: number }} [opts]
+ * @returns {SolveResult}
+ */
+export function newtonRaphson(f, df, x0, opts = {}) {
+  const tol = opts.tol ?? DEFAULT_TOL;
+  const maxIter = opts.maxIter ?? DEFAULT_MAX_ITER;
+  let x = +x0;
+  for (let i = 1; i <= maxIter; i++) {
+    const fx = +f(x);
+    if (Math.abs(fx) <= tol) return { root: x, iterations: i, converged: true };
+    const dfx = +df(x);
+    if (dfx === 0 || !isFinite(dfx)) return { root: x, iterations: i, converged: false };
+    const next = x - fx / dfx;
+    if (!isFinite(next)) return { root: x, iterations: i, converged: false };
+    if (Math.abs(next - x) <= tol) return { root: next, iterations: i, converged: true };
+    x = next;
+  }
+  return { root: x, iterations: maxIter, converged: false };
+}
+
+/**
+ * Bisection on a sign-changing bracket `[a, b]`. Guaranteed to converge
+ * when `f(a)` and `f(b)` straddle a root; returns `converged: false` if
+ * the bracket does not (rather than throwing).
+ *
+ * @param {(x: number) => number} f
+ * @param {number} a
+ * @param {number} b
+ * @param {{ tol?: number, maxIter?: number }} [opts]
+ * @returns {SolveResult}
+ */
+export function bisect(f, a, b, opts = {}) {
+  const tol = opts.tol ?? DEFAULT_TOL;
+  const maxIter = opts.maxIter ?? DEFAULT_MAX_ITER;
+  let lo = +a;
+  let hi = +b;
+  let flo = +f(lo);
+  let fhi = +f(hi);
+  if (flo === 0) return { root: lo, iterations: 0, converged: true };
+  if (fhi === 0) return { root: hi, iterations: 0, converged: true };
+  if (flo * fhi > 0) return { root: (lo + hi) / 2, iterations: 0, converged: false };
+  let mid = (lo + hi) / 2;
+  for (let i = 1; i <= maxIter; i++) {
+    mid = (lo + hi) / 2;
+    const fmid = +f(mid);
+    if (Math.abs(fmid) <= tol || (hi - lo) / 2 <= tol) {
+      return { root: mid, iterations: i, converged: true };
+    }
+    if (flo * fmid < 0) { hi = mid; fhi = fmid; }
+    else { lo = mid; flo = fmid; }
+  }
+  return { root: mid, iterations: maxIter, converged: false };
+}
+
+/**
+ * The secant method (Newton without an explicit derivative). Needs two
+ * starting points.
+ *
+ * @param {(x: number) => number} f
+ * @param {number} x0
+ * @param {number} x1
+ * @param {{ tol?: number, maxIter?: number }} [opts]
+ * @returns {SolveResult}
+ */
+export function secant(f, x0, x1, opts = {}) {
+  const tol = opts.tol ?? DEFAULT_TOL;
+  const maxIter = opts.maxIter ?? DEFAULT_MAX_ITER;
+  let a = +x0;
+  let b = +x1;
+  let fa = +f(a);
+  let fb = +f(b);
+  for (let i = 1; i <= maxIter; i++) {
+    if (Math.abs(fb) <= tol) return { root: b, iterations: i, converged: true };
+    const denom = fb - fa;
+    if (denom === 0 || !isFinite(denom)) return { root: b, iterations: i, converged: false };
+    const next = b - fb * (b - a) / denom;
+    if (!isFinite(next)) return { root: b, iterations: i, converged: false };
+    if (Math.abs(next - b) <= tol) return { root: next, iterations: i, converged: true };
+    a = b; fa = fb;
+    b = next; fb = +f(b);
+  }
+  return { root: b, iterations: maxIter, converged: false };
+}

package/src/math/word.js

@@ -0,0 +1,177 @@
+//@ts-check
+/**
+ * @file BigInt fixed-width word math. The programmer-calculator
+ * kernel: two's-complement integers of a fixed bit width (8/16/32/64),
+ * signed or unsigned, with the bitwise/shift/rotate operators and
+ * radix-string I/O a HEX/DEC/OCT/BIN calculator needs.
+ *
+ * Everything is native `BigInt` — zero dependencies, exact at any width.
+ * Values crossing the module boundary are plain `BigInt`s already reduced
+ * to the requested word (mask + sign-extend), so operators compose
+ * without re-normalizing.
+ */
+
+/** Supported word sizes, in bits. */
+export const WORD_BITS = Object.freeze([8, 16, 32, 64]);
+
+/**
+ * The unsigned mask for a word of `bits` bits: `2**bits - 1`.
+ * @param {number} bits
+ * @returns {bigint}
+ */
+export function wordMask(bits) {
+  return (1n << BigInt(bits | 0)) - 1n;
+}
+
+/**
+ * Reduce any integer to a fixed-width word. Unsigned words wrap into
+ * `[0, 2**bits)`; signed words are the two's-complement interpretation,
+ * so the high bit becomes the sign and the result lands in
+ * `[-2**(bits-1), 2**(bits-1))`.
+ *
+ * @param {bigint|number|string} value
+ * @param {number} [bits]
+ * @param {boolean} [signed]
+ * @returns {bigint}
+ */
+export function toWord(value, bits = 32, signed = false) {
+  const b = BigInt(bits | 0);
+  const mask = (1n << b) - 1n;
+  let v = (typeof value === 'bigint' ? value : BigInt(Math.trunc(Number(value)))) & mask;
+  if (signed) {
+    const signBit = 1n << (b - 1n);
+    if ((v & signBit) !== 0n) v -= (1n << b);
+  }
+  return v;
+}
+
+/** @param {bigint} a @param {bigint} b @param {number} [bits] @param {boolean} [signed] */
+export function wAnd(a, b, bits = 32, signed = false) {
+  return toWord(toWord(a, bits, false) & toWord(b, bits, false), bits, signed);
+}
+/** @param {bigint} a @param {bigint} b @param {number} [bits] @param {boolean} [signed] */
+export function wOr(a, b, bits = 32, signed = false) {
+  return toWord(toWord(a, bits, false) | toWord(b, bits, false), bits, signed);
+}
+/** @param {bigint} a @param {bigint} b @param {number} [bits] @param {boolean} [signed] */
+export function wXor(a, b, bits = 32, signed = false) {
+  return toWord(toWord(a, bits, false) ^ toWord(b, bits, false), bits, signed);
+}
+/** @param {bigint} a @param {number} [bits] @param {boolean} [signed] */
+export function wNot(a, bits = 32, signed = false) {
+  return toWord(~toWord(a, bits, false), bits, signed);
+}
+/** @param {bigint} a @param {bigint} n @param {number} [bits] @param {boolean} [signed] */
+export function wShl(a, n, bits = 32, signed = false) {
+  return toWord(toWord(a, bits, false) << (BigInt(n) % BigInt(bits)), bits, signed);
+}
+/**
+ * Logical right shift (zero fill) over the unsigned representation, then
+ * reinterpreted per `signed`.
+ * @param {bigint} a @param {bigint} n @param {number} [bits] @param {boolean} [signed]
+ */
+export function wShr(a, n, bits = 32, signed = false) {
+  return toWord(toWord(a, bits, false) >> (BigInt(n) % BigInt(bits)), bits, signed);
+}
+/** Rotate left. @param {bigint} a @param {bigint} n @param {number} [bits] @param {boolean} [signed] */
+export function wRol(a, n, bits = 32, signed = false) {
+  const b = BigInt(bits | 0);
+  const u = toWord(a, bits, false);
+  const s = ((BigInt(n) % b) + b) % b;
+  const mask = (1n << b) - 1n;
+  return toWord(((u << s) | (u >> (b - s))) & mask, bits, signed);
+}
+/** Rotate right. @param {bigint} a @param {bigint} n @param {number} [bits] @param {boolean} [signed] */
+export function wRor(a, n, bits = 32, signed = false) {
+  const b = BigInt(bits | 0);
+  const u = toWord(a, bits, false);
+  const s = ((BigInt(n) % b) + b) % b;
+  const mask = (1n << b) - 1n;
+  return toWord(((u >> s) | (u << (b - s))) & mask, bits, signed);
+}
+/**
+ * Euclidean-flavoured modulo that follows the sign of the divisor,
+ * reduced back into the word.
+ * @param {bigint} a @param {bigint} b @param {number} [bits] @param {boolean} [signed]
+ */
+export function wMod(a, b, bits = 32, signed = false) {
+  const x = toWord(a, bits, signed);
+  const y = toWord(b, bits, signed);
+  if (y === 0n) throw new RangeError('wMod: division by zero');
+  return toWord(x % y, bits, signed);
+}
+
+/** @param {number} radix @returns {string} */
+function radixDigits(radix) {
+  return '0123456789abcdefghijklmnopqrstuvwxyz'.slice(0, radix);
+}
+
+/**
+ * Format an integer as a radix string (no prefix). Groups digits with an
+ * optional separator and left-pads to `pad` digits.
+ *
+ * @param {bigint|number} int
+ * @param {number} [radix] 2..36
+ * @param {{ group?: number, sep?: string, pad?: number, upper?: boolean }} [opts]
+ * @returns {string}
+ */
+export function toBase(int, radix = 10, opts = {}) {
+  const r = radix | 0;
+  if (r < 2 || r > 36) throw new RangeError(`toBase: radix ${radix} out of range 2..36`);
+  let v = typeof int === 'bigint' ? int : BigInt(Math.trunc(Number(int)));
+  const neg = v < 0n;
+  if (neg) v = -v;
+  const R = BigInt(r);
+  const digits = radixDigits(r);
+  let out = v === 0n ? '0' : '';
+  while (v > 0n) {
+    out = digits[Number(v % R)] + out;
+    v /= R;
+  }
+  if (opts.pad && out.length < opts.pad) out = out.padStart(opts.pad, '0');
+  if (opts.group && opts.group > 0) {
+    const sep = opts.sep ?? ' ';
+    const parts = [];
+    for (let i = out.length; i > 0; i -= opts.group) {
+      parts.unshift(out.slice(Math.max(0, i - opts.group), i));
+    }
+    out = parts.join(sep);
+  }
+  if (opts.upper) out = out.toUpperCase();
+  return neg ? '-' + out : out;
+}
+
+/**
+ * Parse a radix string back to a BigInt. Tolerates group separators
+ * (space/underscore), a leading sign, and an optional `0x`/`0o`/`0b`
+ * prefix (which must agree with `radix` when both are given).
+ *
+ * @param {string} str
+ * @param {number} [radix] 2..36
+ * @returns {bigint}
+ */
+export function fromBase(str, radix = 10) {
+  let s = String(str).trim().replace(/[ _]/g, '');
+  let neg = false;
+  if (s.startsWith('-')) { neg = true; s = s.slice(1); }
+  else if (s.startsWith('+')) s = s.slice(1);
+  const m = /^0([xob])/i.exec(s);
+  if (m) {
+    const pfx = m[1].toLowerCase();
+    const pfxRadix = pfx === 'x' ? 16 : pfx === 'o' ? 8 : 2;
+    radix = pfxRadix;
+    s = s.slice(2);
+  }
+  const r = radix | 0;
+  if (r < 2 || r > 36) throw new RangeError(`fromBase: radix ${radix} out of range 2..36`);
+  if (s.length === 0) throw new SyntaxError('fromBase: empty digit string');
+  const R = BigInt(r);
+  const digits = radixDigits(r);
+  let acc = 0n;
+  for (const ch of s.toLowerCase()) {
+    const d = digits.indexOf(ch);
+    if (d < 0) throw new SyntaxError(`fromBase: '${ch}' is not a base-${r} digit`);
+    acc = acc * R + BigInt(d);
+  }
+  return neg ? -acc : acc;
+}