@pacem/pacem-numerical 1.0.0-bessel → 1.0.0-dirac

package/dist/browser/pacem-numerical.min.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-numerical v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-numerical v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/bundle/pacem-numerical.min.mjs

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-numerical v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-numerical v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/bundle/pacem-numerical.mjs

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-numerical v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-numerical v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -33,9 +33,17 @@ var Vector = class _Vector {
     this.normalize(clone);
     return clone;
   }
+  /**
+   * Returns the squared magnitude (length) of the vector. Cheaper than {@link mag} since it avoids the square root.
+   * @param v
+   */
   static magSqr(v) {
     return v.x * v.x + v.y * v.y;
   }
+  /**
+   * Returns the magnitude (length) of the vector.
+   * @param v
+   */
   static mag(v) {
     return Math.sqrt(_Vector.magSqr(v));
   }
@@ -199,6 +207,13 @@ function delaunayTriangulation(vertices) {
   return indices;
 }
 var Delaunay = class {
+  /**
+   * Computes the Delaunay triangulation of the given points.
+   * @param vertices Points to triangulate.
+   * @returns A flat array of triangle indices into {@link vertices} (each consecutive group of 3
+   * entries identifies one triangle), in the same "vertices + triangle indices" format used by
+   * most graphics/meshing libraries. Returns an empty array if fewer than 3 points are provided.
+   */
   static triangulate(vertices) {
     return delaunayTriangulation(vertices);
   }
@@ -258,6 +273,11 @@ var Utils = class _Utils {
       return null;
     }
   }
+  /**
+   * Computes the axis-aligned bounding box of a set of points.
+   * @param vertices Points to enclose.
+   * @returns The smallest rect containing all provided points.
+   */
   static boundingBox(vertices) {
     let xmin = Number.MAX_VALUE, ymin = Number.MAX_VALUE, xmax = -Number.MAX_VALUE, ymax = -Number.MAX_VALUE;
     const l = vertices.length;
@@ -269,6 +289,15 @@ var Utils = class _Utils {
     }
     return { x: xmin, y: ymin, width: xmax - xmin, height: ymax - ymin };
   }
+  /**
+   * Combines two polygons using a boolean set operator (union, intersection or difference).
+   * Internally triangulates the merged vertex set (via {@link mesh}) and filters the resulting
+   * triangles by whether their barycenter falls inside either source polygon.
+   * @param polygon1 First polygon.
+   * @param polygon2 Second polygon.
+   * @param operator Boolean operator to apply.
+   * @returns The resulting polygon(s), plus the underlying triangulation mesh and triangles used to compute them; or `null` if the operation yields no polygon.
+   */
   static combinePolygons(polygon1, polygon2, operator) {
     return _Utils._mergePolygons(polygon1, polygon2, operator);
   }
@@ -622,6 +651,12 @@ var Utils = class _Utils {
     const minx = Math.min(segment[0].x, segment[1].x), maxx = Math.max(segment[0].x, segment[1].x), miny = Math.min(segment[0].y, segment[1].y), maxy = Math.max(segment[0].y, segment[1].y);
     return p.x >= minx && p.x <= maxx && p.y >= miny && p.y <= maxy && _Utils.inLine(p, segment, precision);
   }
+  /**
+   * Checks whether a point lies inside (or on the boundary of) a triangle, by verifying that it
+   * is on the same rotational side of all three edges.
+   * @param p Point to test.
+   * @param triangle Triangle vertices.
+   */
   static inTriangle(p, triangle) {
     let last;
     for (let j = 0; j < 3; j++) {
@@ -740,22 +775,49 @@ var Polygon = class _Polygon {
   static {
     this._eps = 1e-12;
   }
+  /**
+   * Type guard checking whether the provided value is a valid {@link Polygon} (has at least 3 point vertices).
+   * @param obj
+   */
   static isPolygon(obj) {
     return isPolygon(obj);
   }
+  /**
+   * Builds a polygon from the provided vertices, in order.
+   * @param points Vertices of the polygon.
+   */
   static from(...points) {
     return { vertices: Array.from(points) };
   }
+  /**
+   * Checks whether a point lies inside the polygon.
+   * @param polygon
+   * @param p Point to test.
+   */
   static contains(polygon, p) {
     return Utils.inPolygon(p, polygon.vertices, 12);
   }
+  /**
+   * Returns the center of the polygon's bounding box.
+   * Note: this is not the geometric centroid (center of mass) for non-symmetric polygons.
+   * @param polygon
+   */
   static centroid(polygon) {
     const bbox = _Polygon.boundingBox(polygon);
     return { x: bbox.x + bbox.width / 2, y: bbox.y + bbox.height / 2 };
   }
+  /**
+   * Computes the axis-aligned bounding box of the polygon.
+   * @param polygon
+   */
   static boundingBox(polygon) {
     return Utils.boundingBox(polygon.vertices);
   }
+  /**
+   * Returns the polygon's edges as an ordered list of segments, each joining a vertex to the next
+   * (the last one wrapping back to the first).
+   * @param polygon
+   */
   static sides(polygon) {
     const { vertices } = polygon;
     const retval = [];
@@ -765,6 +827,10 @@ var Polygon = class _Polygon {
     }
     return retval;
   }
+  /**
+   * Checks whether the polygon is convex, i.e. all its interior angles turn in the same rotational direction.
+   * @param polygon
+   */
   static isConvex(polygon) {
     const { vertices } = polygon, l = vertices.length;
     if (l <= 3) {
@@ -853,6 +919,12 @@ var Polygon = class _Polygon {
   static area(polygon) {
     return Utils.area(polygon.vertices);
   }
+  /**
+   * Computes the intersection area(s) between two polygons.
+   * @param polygon1
+   * @param polygon2
+   * @returns The overlapping area(s) as one or more polygons.
+   */
   static intersect(polygon1, polygon2) {
     return Utils.intersect(polygon1, polygon2);
   }
@@ -872,6 +944,11 @@ import { parseAsNumericalArray } from "@pacem/pacem-foundation";
 var RAD2DEG2 = 180 / Math.PI;
 var DEG2RAD = 1 / RAD2DEG2;
 var Vector3D = class _Vector3D {
+  /**
+   * Builds a {@link Vector3D} from its x, y, z components, in that order.
+   * @param args Exactly 3 numbers: x, y, z.
+   * @throws If the number of arguments is not exactly 3.
+   */
   static from(...args) {
     const l = 3;
     if (args.length !== l) {
@@ -879,6 +956,11 @@ var Vector3D = class _Vector3D {
     }
     return { x: args[0], y: args[1], z: args[2] };
   }
+  /**
+   * Parses a string representation (e.g. `"1 2 3"` or `"1,2,3"`) into a {@link Vector3D}.
+   * @param input String to parse.
+   * @throws If the input cannot be parsed as exactly 3 numbers.
+   */
   static parse(input) {
     const arr = parseAsNumericalArray(input);
     if (arr && arr.length === 3) {
@@ -887,15 +969,19 @@ var Vector3D = class _Vector3D {
     throw new Error(`Cannot parse "${input}" as a valid Vector3D.`);
   }
   // notable vectors
+  /** Returns the unit vector along the x axis: `(1, 0, 0)`. */
   static i() {
     return { x: 1, y: 0, z: 0 };
   }
+  /** Returns the unit vector along the y axis: `(0, 1, 0)`. */
   static j() {
     return { x: 0, y: 1, z: 0 };
   }
+  /** Returns the unit vector along the z axis: `(0, 0, 1)`. */
   static k() {
     return { x: 0, y: 0, z: 1 };
   }
+  /** Returns the zero vector: `(0, 0, 0)`. */
   static zero() {
     return { x: 0, y: 0, z: 0 };
   }
@@ -943,6 +1029,10 @@ var Vector3D = class _Vector3D {
   static scale(v, fx, fy = fx, fz = fx) {
     return { x: v.x * fx, y: v.y * fy, z: v.z * fz };
   }
+  /**
+   * Returns the squared magnitude (length) of the vector. Cheaper than {@link mag} since it avoids the square root.
+   * @param v
+   */
   static magSqr(v) {
     return v.x * v.x + v.y * v.y + v.z * v.z;
   }
@@ -955,9 +1045,17 @@ var Vector3D = class _Vector3D {
   static areClose(v1, v2) {
     return (v2.x - v1.x).isCloseTo(0) && (v2.y - v1.y).isCloseTo(0) && (v2.z - v1.z).isCloseTo(0);
   }
+  /**
+   * Returns the magnitude (length) of the vector.
+   * @param v
+   */
   static mag(v) {
     return Math.sqrt(_Vector3D.magSqr(v));
   }
+  /**
+   * Returns the opposite vector (each component negated).
+   * @param v
+   */
   static negate(v) {
     return { x: -v.x, y: -v.y, z: -v.z };
   }
@@ -1028,6 +1126,10 @@ var Spherical = class _Spherical {
     const theta = Math.atan2(v.x, v.z), phi = Math.acos((v.y / rho).clamp(-1, 1));
     return _Spherical.from(rho, theta * RAD2DEG2, phi * RAD2DEG2);
   }
+  /**
+   * Converts {@link Spherical} coordinates back into cartesian {@link Vector3D} coordinates.
+   * @param coords
+   */
   static toVector(coords) {
     const { rho, theta: thetaDeg, phi: phiDeg } = coords;
     const phi = phiDeg * DEG2RAD;
@@ -1114,6 +1216,11 @@ var Matrix3D = class _Matrix3D {
     };
   }
   //#endregion
+  /**
+   * Builds a {@link Matrix3D} from its 16 components, in row-major order.
+   * @param args Exactly 16 numbers.
+   * @throws If the number of arguments is not exactly 16.
+   */
   static from(...args) {
     const l = 16;
     if (args.length !== l) {
@@ -1138,9 +1245,17 @@ var Matrix3D = class _Matrix3D {
       m44: args[15]
     };
   }
+  /**
+   * Returns the transpose of the given matrix (rows and columns swapped).
+   * @param m
+   */
   static transpose(m) {
     return _Matrix3D.from(m.m11, m.m21, m.m31, m.offsetX, m.m12, m.m22, m.m32, m.offsetY, m.m13, m.m23, m.m33, m.offsetZ, m.m14, m.m24, m.m34, m.m44);
   }
+  /**
+   * Flattens the matrix into a 16-number array, in row-major order (the same order accepted by {@link from}).
+   * @param m
+   */
   static toArray(m) {
     return [
       m.m11,
@@ -1179,6 +1294,11 @@ var Matrix3D = class _Matrix3D {
       s.m33 *= z;
     });
   }
+  /**
+   * Returns a copy of the matrix translated (offset) by the given vector.
+   * @param m
+   * @param offset
+   */
   static translate(m, offset) {
     return Matrix3DUtils.modify(m, (s) => {
       s.offsetX += offset.x;
@@ -1186,6 +1306,11 @@ var Matrix3D = class _Matrix3D {
       s.offsetZ += offset.z;
     });
   }
+  /**
+   * Parses a string representation of a matrix (16 numbers) into a {@link Matrix3D}.
+   * @param input String to parse.
+   * @throws If the input cannot be parsed as exactly 16 numbers.
+   */
   static parse(input) {
     const arr = parseAsNumericalArray(input);
     if (arr && arr.length === 16) {
@@ -1193,12 +1318,25 @@ var Matrix3D = class _Matrix3D {
     }
     throw new Error(`Cannot parse "${input}" as a valid Matrix3D.`);
   }
+  /**
+   * Checks whether the matrix is the identity matrix.
+   * @param m
+   */
   static isIdentity(m) {
     return m.m11 == 1 && m.m12 == 0 && m.m13 == 0 && m.m14 == 0 && m.m21 == 0 && m.m22 == 1 && m.m23 == 0 && m.m24 == 0 && m.m31 == 0 && m.m32 == 0 && m.m33 == 1 && m.m34 == 0 && m.offsetX == 0 && m.offsetY == 0 && m.offsetZ == 0 && m.m44 == 1;
   }
+  /**
+   * Checks whether the matrix represents a pure affine transform, i.e. it has no perspective
+   * component (its 4th column is `(0, 0, 0, 1)`).
+   * @param m
+   */
   static isAffine(m) {
     return m.m14 == 0 && m.m24 == 0 && m.m34 == 0 && m.m44 == 1;
   }
+  /**
+   * Computes the determinant of the matrix.
+   * @param m
+   */
   static determinant(m) {
     if (_Matrix3D.isIdentity(m)) {
       return 1;
@@ -1235,6 +1373,12 @@ var Matrix3D = class _Matrix3D {
     }
     return m;
   }
+  /**
+   * Computes the inverse of the matrix, using the cofactor/adjugate method (with a specialized,
+   * cheaper path for affine matrices).
+   * @param m
+   * @returns The inverse matrix, or `null` if the matrix is singular (determinant is 0).
+   */
   static invert(m) {
     if (_Matrix3D.isAffine(m)) {
       const determinant = _Matrix3D.determinant(m);
@@ -1337,9 +1481,15 @@ var Matrix3D = class _Matrix3D {
   }
 };
 var Quaternion = class _Quaternion {
+  /** Returns the identity quaternion (no rotation). */
   static identity() {
     return _Quaternion.from(0, 0, 0, 1);
   }
+  /**
+   * Builds a {@link Quaternion} from its x, y, z, w components, in that order.
+   * @param args Exactly 4 numbers: x, y, z, w.
+   * @throws If the number of arguments is not exactly 4.
+   */
   static from(...args) {
     const l = 4;
     if (args.length !== l) {
@@ -1352,6 +1502,11 @@ var Quaternion = class _Quaternion {
       w: args[3]
     };
   }
+  /**
+   * Parses a string representation of a quaternion (4 numbers) into a {@link Quaternion}.
+   * @param input String to parse.
+   * @throws If the input cannot be parsed as exactly 4 numbers.
+   */
   static parse(input) {
     const arr = parseAsNumericalArray(input);
     if (arr && arr.length === 4) {
@@ -1359,6 +1514,12 @@ var Quaternion = class _Quaternion {
     }
     throw new Error(`Cannot parse "${input}" as a valid Quaternion.`);
   }
+  /**
+   * Builds the (shortest-arc) quaternion representing the rotation that takes one unit vector onto another.
+   * Normalizes both input vectors in place as a side effect.
+   * @param from Source direction.
+   * @param to Target direction.
+   */
   static fromVectors(from, to) {
     Vector3D.normalize(from);
     Vector3D.normalize(to);
@@ -1471,6 +1632,11 @@ var Quaternion = class _Quaternion {
       }
     }
   }
+  /**
+   * Returns the conjugate of the quaternion (vector part negated). For a unit quaternion, this
+   * represents the inverse rotation.
+   * @param q
+   */
   static conjugate(q) {
     return _Quaternion.from(-q.x, -q.y, -q.z, q.w);
   }
@@ -1481,15 +1647,29 @@ var Quaternion = class _Quaternion {
   static mag(q) {
     return Math.sqrt(q.x * q.x + q.y * q.y + q.z * q.z + q.w * q.w);
   }
+  /**
+   * Returns the squared magnitude of the vector (imaginary) part of the quaternion.
+   * @param q
+   */
   static norm(q) {
     return q.x * q.x + q.y * q.y + q.z * q.z;
   }
+  /**
+   * Returns the (unit) rotation axis represented by the quaternion, defaulting to the y axis
+   * when the quaternion has no vector part (i.e. represents no rotation).
+   * @param q
+   */
   static axis(q) {
     if (q.x == 0 && q.y == 0 && q.z == 0) {
       return Vector3D.j();
     }
     return Vector3D.unit(q);
   }
+  /**
+   * Rotates a vector by the given quaternion (normalizes the quaternion in place as a side effect).
+   * @param v Vector to rotate.
+   * @param q Rotation quaternion.
+   */
   static transform(v, q) {
     _Quaternion.normalize(q);
     const cross = Vector3D.cross(q, v);
@@ -1518,6 +1698,10 @@ var Quaternion = class _Quaternion {
     }
     return Math.atan2(y, x) * 114.59155902616465;
   }
+  /**
+   * Builds the rotation matrix equivalent to the given quaternion.
+   * @param q
+   */
   static toRotationMatrix(q) {
     var m = Matrix3D.identity();
     var X = q.x;
@@ -1535,6 +1719,10 @@ var Quaternion = class _Quaternion {
     m.m33 = 1 - 2 * X * X - 2 * Y * Y;
     return m;
   }
+  /**
+   * Returns the inverse rotation of the given quaternion (the conjugate of its normalized form).
+   * @param q
+   */
   static invert(q) {
     const n = _Quaternion.unit(q);
     return _Quaternion.conjugate(n);
@@ -1642,14 +1830,29 @@ var Complex = class {
     }
     return buildComplex(real, img || 0);
   }
+  /**
+   * Adds two complex numbers (real numbers are treated as having a zero imaginary part).
+   * @param a First addend.
+   * @param b Second addend.
+   */
   static add(a, b) {
     const ac = complex(a), bc = complex(b);
     return buildComplex(ac.real + bc.real, ac.img + bc.img);
   }
+  /**
+   * Subtracts one complex number from another.
+   * @param from Minuend.
+   * @param what Subtrahend.
+   */
   static subtract(from, what) {
     const ac = complex(from), bc = complex(what);
     return buildComplex(ac.real - bc.real, ac.img - bc.img);
   }
+  /**
+   * Multiplies two complex numbers.
+   * @param a First factor.
+   * @param b Second factor.
+   */
   static multiply(a, b) {
     const ac = complex(a), bc = complex(b);
     return buildComplex(
@@ -1659,6 +1862,12 @@ var Complex = class {
       ac.real * bc.img + ac.img * bc.real
     );
   }
+  /**
+   * Divides one complex number by another.
+   * @param a Dividend.
+   * @param b Divisor.
+   * @returns The quotient, or {@link Complex.NaC} if the divisor is (close to) zero.
+   */
   static divide(a, b) {
     const ac = complex(a), bc = complex(b);
     const div = this.absSquare(bc).roundoff();
@@ -1673,20 +1882,42 @@ var Complex = class {
       inv_div * (ac.img * bc.real - ac.real * bc.img)
     );
   }
+  /**
+   * Returns the squared modulus (|z|²) of the complex number, i.e. real² + img².
+   * Cheaper than {@link modulus} since it avoids the square root.
+   * @param c
+   */
   static absSquare(c) {
     const ac = complex(c);
     return Math.pow(ac.real, 2) + Math.pow(ac.img, 2);
   }
+  /**
+   * Returns the modulus (magnitude) of the complex number.
+   * @param c
+   */
   static modulus(c) {
     return Math.sqrt(this.absSquare(c));
   }
+  /**
+   * Type guard checking whether the provided value is a {@link Complex} number.
+   * @param c
+   */
   static isComplex(c) {
     return c != null && typeof c === "object" && "real" in c && "img" in c && typeof c.real === "number" && typeof c.img === "number";
   }
+  /**
+   * Returns the complex conjugate: same real part, negated imaginary part.
+   * @param a
+   */
   static conjugate(a) {
     a = complex(a);
     return buildComplex(a.real, Math.abs(a.img) == 0 ? 0 : -a.img);
   }
+  /**
+   * Checks whether two complex numbers have the same real and imaginary parts.
+   * @param c1
+   * @param c2
+   */
   static equals(c1, c2) {
     const c_1 = this.build(c1), c_2 = this.build(c2);
     if (!this.isComplex(c1) || !this.isComplex(c2)) {
@@ -1706,6 +1937,7 @@ var Complex = class {
   //            if (!this.isComplex(  c)
   //    }
   //}
+  /** The "Not a Complex" sentinel value (`NaN + NaNi`), returned by operations on invalid input. */
   static get NaC() {
     return nac();
   }
@@ -1817,11 +2049,17 @@ function erfc(x) {
   return x >= 0 ? ans : 2 - ans;
 }
 var Gaussian = class {
+  /**
+   * Creates a new {@link Gaussian} distribution with the given mean and standard deviation.
+   * @param mean Mean (μ) of the distribution.
+   * @param stdev Standard deviation (σ) of the distribution (its absolute value is used).
+   */
   constructor(mean2, stdev2) {
     this.mean = mean2;
     this.stdev = Math.abs(stdev2);
     this.variance = Math.pow(stdev2, 2);
   }
+  /** The standard normal distribution (mean 0, standard deviation 1). */
   static get normal() {
     return _normal;
   }
@@ -1856,6 +2094,7 @@ var _normal = new Gaussian(0, 1);
 
 // packages/numerical/dist/esm/math/interpolation.js
 var Lagrange = class _Lagrange {
+  /** Use {@link Lagrange.create} to build an instance. */
   constructor(points) {
     this.#set = points;
   }
@@ -1924,6 +2163,11 @@ var Lagrange = class _Lagrange {
   }
   // Iterative/global Lagrange computation removed — barycentric is used
   // exclusively for interpolation.
+  /**
+   * Evaluates the Lagrange interpolating polynomial at the given x, using barycentric weights.
+   * @param x Input value.
+   * @returns The interpolated y value (the exact node y if x coincides with a node).
+   */
   interpolate(x) {
     return this._computeBarycentric(x);
   }
@@ -1944,6 +2188,7 @@ var Lagrangian = {
   create: Lagrange.create
 };
 var Pchip = class _Pchip {
+  /** Use {@link Pchip.create} to build an instance. */
   constructor(points) {
     if (!points || points.length < 2)
       throw new Error("Need at least 2 points");
@@ -1990,6 +2235,12 @@ var Pchip = class _Pchip {
     }
     return m;
   }
+  /**
+   * Evaluates the PCHIP curve at the given x, using cubic Hermite interpolation on the enclosing segment.
+   * Values outside the node range are linearly extrapolated using the boundary derivative.
+   * @param x Input value.
+   * @returns The interpolated y value.
+   */
   interpolate(x) {
     const xs = this.xs, ys = this.ys, ms = this.ms;
     const n = xs.length;
@@ -2032,6 +2283,7 @@ var Pchip = class _Pchip {
   }
 };
 var Newton = class _Newton {
+  /** Use {@link Newton.create} to build an instance. */
   constructor(points) {
     if (!points || points.length === 0)
       throw new Error("Need at least 1 point");
@@ -2049,6 +2301,11 @@ var Newton = class _Newton {
     }
     this.coeffs = a;
   }
+  /**
+   * Evaluates the Newton form of the interpolating polynomial at the given x, via nested multiplication.
+   * @param x Input value.
+   * @returns The interpolated y value (`NaN` if the interpolator has no points).
+   */
   interpolate(x) {
     const xs = this.xs, a = this.coeffs;
     const n = a.length;
@@ -2285,6 +2542,12 @@ import { Numbers, NullChecker as NullChecker3 } from "@pacem/pacem-foundation";
 var ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
 var OUT_OF_RANGE = `Radix out of range: possible values go between positive 1 exclusive and ${ALPHABET.length} inclusive`;
 var Utils3 = class _Utils {
+  /**
+   * Computes the least common multiple (LCM) of the given numbers (each rounded to the nearest integer).
+   * @param args Two or more numbers.
+   * @returns The least common multiple.
+   * @throws If fewer than two numbers are provided.
+   */
   static lcd(...args) {
     if (NullChecker3.isNullOrEmpty(args) || args.length <= 1) {
       throw "Insufficient set of numbers.";
@@ -2303,6 +2566,12 @@ var Utils3 = class _Utils {
     }
     return result;
   }
+  /**
+   * Computes the greatest common divisor (GCD) of two numbers (each rounded to the nearest integer)
+   * using the Euclidean algorithm.
+   * @param a
+   * @param b
+   */
   static gcd(a, b) {
     a = Math.round(a), b = Math.round(b);
     if (a === 0) {
@@ -2310,9 +2579,26 @@ var Utils3 = class _Utils {
     }
     return _Utils.gcd(b % a, a);
   }
+  /**
+   * Converts an integer value from one numeric base (radix) to another.
+   * @param v Value to convert, in the source radix.
+   * @param from Source radix.
+   * @param to Target radix.
+   * @returns The value re-expressed in the target radix, as a string.
+   */
   static rebaseInt(v, from, to) {
     return Numbers.rebase(v, from, to);
   }
+  /**
+   * Converts a (possibly fractional) numeric value from one radix to another, dispatching to the
+   * appropriate specialized conversion routine depending on whether base-10 is the source, the
+   * target, or neither.
+   * @param v Value to convert, in the source radix.
+   * @param fromRadix Source radix.
+   * @param toRadix Target radix.
+   * @param precision Maximum number of digits to compute for the fractional part (default 12).
+   * @returns The converted value: a number when converting to base 10, otherwise a string.
+   */
   static rebaseFloat(v, fromRadix, toRadix, precision = 12) {
     const from10 = _Utils.rebaseFloat10ToN, to10 = _Utils.rebaseFloatNTo10;
     if (fromRadix === 10) {
@@ -2328,6 +2614,14 @@ var Utils3 = class _Utils {
     const _10 = to10(v.toString(), fromRadix, precision + 1);
     return from10(_10, toRadix, precision);
   }
+  /**
+   * Converts a numeric string expressed in the given radix into its base-10 (decimal) value.
+   * @param v Value to convert, expressed in the source radix (digits from `0-9a-z`).
+   * @param radix Source radix (must be greater than 1 and no larger than the size of the digit alphabet).
+   * @param precision Unused for the integer part; reserved for symmetry with the sibling conversion methods.
+   * @returns The base-10 numeric value, or `NaN` if the input contains invalid digits.
+   * @throws If radix is out of range.
+   */
   static rebaseFloatNTo10(v, radix, precision = 12) {
     const alphabet = ALPHABET;
     if (radix <= 1 || radix > alphabet.length) {
@@ -2353,6 +2647,14 @@ var Utils3 = class _Utils {
     }
     return sign * retval;
   }
+  /**
+   * Converts a base-10 number into its representation in another **integer** radix.
+   * @param v Base-10 value to convert.
+   * @param radix Target integer radix (must be greater than 1 and no larger than the size of the digit alphabet).
+   * @param precision Maximum number of digits to compute for the fractional part (default 12).
+   * @returns The value re-expressed in the target radix, as a string.
+   * @throws If radix is out of range.
+   */
   static rebaseFloat10ToNIntBase(v, radix, precision = 12) {
     const alphabet = ALPHABET;
     if (radix <= 1 || radix > alphabet.length) {
@@ -2401,6 +2703,14 @@ var Utils3 = class _Utils {
     }
     return (Math.sign(v) < 0 ? "-" : "") + output + "." + rebasedFrac.replace(/0+$/, "");
   }
+  /**
+   * Converts a base-10 number into its representation in another (possibly non-integer) radix.
+   * @param v Base-10 value to convert.
+   * @param radix Target radix, possibly fractional (must be greater than 1 and no larger than the size of the digit alphabet).
+   * @param precision Maximum number of digits to compute for the fractional part (default 12).
+   * @returns The value re-expressed in the target radix, as a string.
+   * @throws If radix is out of range.
+   */
   static rebaseFloat10ToN(v, radix, precision = 12) {
     const alphabet = ALPHABET;
     if (radix <= 1 || radix > alphabet.length) {