arbitrary-numbers 1.0.2 → 2.0.0

package/dist/index.d.cts

@@ -1,17 +1,3 @@
-/**
- * A number stored in normalised scientific notation as `coefficient * 10^exponent`,
- * where `1 <= |coefficient| < 10` (or `coefficient === 0`).
- *
- * @example
- * const n: NormalizedNumber = { coefficient: 1.5, exponent: 3 }; // 1500
- * const z: NormalizedNumber = { coefficient: 0,   exponent: 0 }; // 0
- */
-interface NormalizedNumber {
-    /** The significand, always in `[1, 10)` or `0`. */
-    coefficient: number;
-    /** The power of 10 by which the coefficient is scaled. */
-    exponent: number;
-}
 /** The result of a three-way comparison: negative, zero, or positive. */
 type Signum = -1 | 0 | 1;
 /** Remainder after dividing an exponent by 3 - the within-tier offset. */
@@ -27,6 +13,44 @@ interface AnFunction {
     from(value: number): ArbitraryNumber;
 }
 
+/**
+ * A value that can be either a plain `number` or an `ArbitraryNumber`.
+ */
+type ArbitraryNumberish = ArbitraryNumber | number;
+/**
+ * A value that is either `T` or `undefined`.
+ *
+ * Use for genuinely optional values where the absence is meaningful
+ * (e.g. optional names, optional fallback plugins).
+ *
+ * @example
+ * let label: Maybe<string>;   // string | undefined
+ */
+type Maybe<T> = T | undefined;
+/**
+ * A value that is either `T` or `null`.
+ *
+ * Use for explicit "no result" returns from functions that would otherwise throw
+ * (e.g. `tryFrom` at system boundaries where bad input should be handled gracefully).
+ *
+ * @example
+ * function parse(s: string): Nullable<ArbitraryNumber> { ... }
+ */
+type Nullable<T> = T | null;
+/**
+ * A stable, compact JSON representation of an {@link ArbitraryNumber}.
+ *
+ * Keys are intentionally short (`c`/`e`) to keep save-game blobs small.
+ * Produced by {@link ArbitraryNumber.toJSON} and consumed by {@link ArbitraryNumber.fromJSON}.
+ *
+ * @example
+ * const saved: ArbitraryNumberJson = an(1500).toJSON(); // { c: 1.5, e: 3 }
+ */
+type ArbitraryNumberJson = {
+    c: number;
+    e: number;
+};
+
 /**
  * A plugin that formats a normalised scientific notation number into a display string.
  *
@@ -91,7 +115,7 @@ interface SuffixNotationPluginOptions {
      *
      * @example " " -> "1.50 K"  |  "" -> "1.50K"
      */
-    separator?: string;
+    separator?: Maybe<string>;
 }
 /**
  * A display label for one tier of magnitude, used by {@link UnitNotation}.
@@ -108,7 +132,7 @@ interface Unit {
     /** Short symbol displayed after the number, e.g. `"M"`. */
     symbol: string;
     /** Optional full name, e.g. `"Million"`. Used for display purposes only. */
-    name?: string;
+    name?: Maybe<string>;
 }
 /**
  * A tier-indexed array of units for use with {@link UnitNotation}.
@@ -126,7 +150,7 @@ interface Unit {
  *   { symbol: "M" },   // tier 2: millions
  * ];
  */
-type UnitArray = ReadonlyArray<Unit | undefined>;
+type UnitArray = ReadonlyArray<Maybe<Unit>>;
 /**
  * Options for constructing an {@link AlphabetNotation} instance.
  */
@@ -140,7 +164,7 @@ interface AlphabetNotationOptions extends SuffixNotationPluginOptions {
      *
      * @default `"abcdefghijklmnopqrstuvwxyz"`
      */
-    alphabet?: string;
+    alphabet?: Maybe<string>;
 }
 /**
  * Options for constructing a {@link UnitNotation} instance.
@@ -168,234 +192,354 @@ interface UnitNotationOptions extends SuffixNotationPluginOptions {
      *
      * @default undefined
      */
-    fallback?: SuffixProvider;
+    fallback?: Maybe<SuffixProvider>;
+    /**
+     * When `true` (default), the fallback's tier is offset by the last defined tier in `units`
+     * so that fallback suffixes are visually distinct from those the fallback would generate
+     * for low tiers.
+     *
+     * Example with `CLASSIC_UNITS` (last defined tier = 33) and `letterNotation` as fallback:
+     * - `offsetFallback: true`  → exponent 102 (tier 34) → `"a"` (fallback tier 1, distinct from "K")
+     * - `offsetFallback: false` → exponent 102 (tier 34) → `"h"` (fallback tier 34, same as exponent 24)
+     *
+     * Set to `false` only for backwards compatibility with pre-1.1 behaviour.
+     *
+     * @default true
+     */
+    offsetFallback?: Maybe<boolean>;
 }
 
 /**
- * An immutable number with effectively unlimited range, stored as `coefficient * 10^exponent`
+ * Global tunables for `ArbitraryNumber`.
+ *
+ * Mutating these is a process-level change — not per-instance.
+ */
+interface ArbitraryNumberDefaults {
+    /**
+     * Exponent-difference threshold below which the smaller operand is negligible
+     * and silently skipped during addition/subtraction.
+     *
+     * Default: 15 (matches float64 coefficient precision of ~15.95 significant digits).
+     */
+    scaleCutoff: number;
+    /** Default decimal places used by `toString()` when no argument is supplied. */
+    notationDecimals: number;
+}
+/**
+ * A mutable number with effectively unlimited range, stored as `coefficient * 10^exponent`
  * in normalised scientific notation.
  *
- * The coefficient is always in `[1, 10)` (or `0`). Addition short-circuits when the exponent
- * difference between operands exceeds {@link PrecisionCutoff} - the smaller value is below
- * the precision floor of the larger and is silently discarded.
+ * The coefficient is always in `[1, 10)` (or `0`). Arithmetic methods **mutate `this`** and
+ * return `this` — enabling zero-allocation chaining on the hot path:
+ *
+ * ```ts
+ * gold.add(drop).sub(cost).mul(multiplier);
+ * ```
+ *
+ * Call `.clone()` before any operation where you need to preserve the original value.
+ *
+ * Addition short-circuits when the exponent difference between operands exceeds
+ * {@link ArbitraryNumber.defaults.scaleCutoff} — the smaller value is below the precision
+ * floor and is silently discarded.
+ *
+ * **Static = allocate. Instance = mutate.**
+ * Static arithmetic methods (`ArbitraryNumber.add`, etc.) always return a new instance.
+ * Instance methods (`a.add(b)`) mutate `a` and return `a`.
  *
  * @example
- * const a = new ArbitraryNumber(1.5, 3);  // 1,500
- * const b = new ArbitraryNumber(2.5, 3);  // 2,500
- * a.add(b).toString(); // "4.00e+3"
- * a.mul(b).toString(); // "3.75e+6"
+ * const gold = new ArbitraryNumber(1.5, 3);  // 1_500
+ * gold.add(drop).sub(cost).mul(multiplier);  // mutates gold
+ * const snapshot = gold.clone();             // safe copy
  */
-declare class ArbitraryNumber implements NormalizedNumber {
+declare class ArbitraryNumber {
     /** The significand, always in `[1, 10)` or `0`. */
-    readonly coefficient: number;
+    coefficient: number;
     /** The power of 10 by which the coefficient is scaled. */
-    readonly exponent: number;
+    exponent: number;
+    /** Global tunables. Mutating these is a process-level change. */
+    static readonly defaults: ArbitraryNumberDefaults;
+    /** The additive identity: `0`. Frozen — calling mutating methods throws. */
+    static readonly Zero: FrozenArbitraryNumber;
+    /** The multiplicative identity: `1`. Frozen — calling mutating methods throws. */
+    static readonly One: FrozenArbitraryNumber;
+    /** `10`. Frozen — calling mutating methods throws. */
+    static readonly Ten: FrozenArbitraryNumber;
     /**
-     * Precision cutoff: exponent-difference threshold below which the smaller operand
-     * is negligible and silently skipped during addition/subtraction.
+     * Constructs a new `ArbitraryNumber` and immediately normalises it so that
+     * `1 <= |coefficient| < 10` (or `coefficient === 0`).
      *
-     * When |exponent_diff| > PrecisionCutoff, the smaller operand contributes less than
-     * 10^-PrecisionCutoff of the result - below float64 coefficient precision for the default of 15.
+     * Always two numeric arguments — this keeps the constructor monomorphic so V8
+     * locks in a hidden class on first use (~5 ns allocation).
      *
-     * Default: 15 (matches float64 coefficient precision of ~15.95 significant digits).
-     * Game patterns: diffs 0-8 (exact), prestige 15-25 (loss <0.0001%), idle 20-50 (~0.1% loss).
+     * @example
+     * new ArbitraryNumber(15, 3); // stored as { coefficient: 1.5, exponent: 4 }
      *
-     * Override globally via assignment, or use {@link withPrecision} for a scoped block.
+     * @throws `ArbitraryNumberInputError` for `NaN`/`Infinity` coefficient or exponent.
      */
-    static PrecisionCutoff: number;
-    /** The additive identity: `0`. */
-    static readonly Zero: ArbitraryNumber;
-    /** The multiplicative identity: `1`. */
-    static readonly One: ArbitraryNumber;
-    /** `10`. */
-    static readonly Ten: ArbitraryNumber;
+    constructor(coefficient: number, exponent: number);
+    /**
+     * @internal Fast-path factory for already-normalised values. Not exported from `index.ts`.
+     *
+     * Allocates a new instance and writes the two fields directly — bypasses validation
+     * and normalisation. Only valid when `|coefficient|` is already in `[1, 10)` (or 0)
+     * and `exponent` is correct.
+     */
+    static unsafe(coefficient: number, exponent: number): ArbitraryNumber;
+    /** @internal Normalise an arbitrary `(c, e)` pair into a new instance. */
+    private static _normalizeNew;
+    /** @internal Normalise `(c, e)` into `this` (mutates). Returns `this`. */
+    private _normalizeInto;
+    /**
+     * Returns a fresh, unfrozen copy of this number. The canonical way to preserve
+     * a value before mutating it:
+     *
+     * ```ts
+     * const before = gold.clone();
+     * gold.add(drop);
+     * ```
+     */
+    clone(): ArbitraryNumber;
     /**
      * Creates an `ArbitraryNumber` from a plain JavaScript `number`.
      *
-     * Prefer this over `new ArbitraryNumber(value, 0)` when working with
-     * ordinary numeric literals - it reads clearly at the call site and
-     * validates the input.
+     * @throws `ArbitraryNumberInputError` for `NaN`, `Infinity`, or `-Infinity`.
      *
      * @example
-     * ArbitraryNumber.from(1500);   // { coefficient: 1.5, exponent: 3 }
-     * ArbitraryNumber.from(0.005);  // { coefficient: 5,   exponent: -3 }
-     * ArbitraryNumber.from(0);      // ArbitraryNumber.Zero
-     *
-     * @param value - Any finite number.
-     * @throws `"ArbitraryNumber.from: value must be finite"` for `NaN`, `Infinity`, or `-Infinity`.
+     * ArbitraryNumber.from(1500);  // { coefficient: 1.5, exponent: 3 }
      */
     static from(value: number): ArbitraryNumber;
     /**
-     * Constructs a new `ArbitraryNumber` and immediately normalises it so that
-     * `1 <= |coefficient| < 10` (or `coefficient === 0`).
+     * Like `from`, but returns `null` instead of throwing for non-finite inputs.
      *
-     * @example
-     * new ArbitraryNumber(15, 3); // stored as { coefficient: 1.5, exponent: 4 }
+     * Use at system boundaries (form inputs, external APIs) where bad input should
+     * be handled gracefully.
      *
-     * @param coefficient - The significand. Must be a finite number; will be normalised.
-     * @param exponent - The power of 10. Must be a finite number.
-     * @throws `"ArbitraryNumber: coefficient must be finite"` for `NaN`, `Infinity`, or `-Infinity`.
-     * @throws `"ArbitraryNumber: exponent must be finite"` for non-finite exponents.
+     * @example
+     * ArbitraryNumber.tryFrom(Infinity) // null
+     * ArbitraryNumber.tryFrom(1500)     // ArbitraryNumber { coefficient: 1.5, exponent: 3 }
      */
-    constructor(coefficient: number, exponent: number);
+    static tryFrom(value: number): Nullable<ArbitraryNumber>;
     /**
-     * @internal Fast-path factory for already-normalised values.
+     * Returns a **new** instance equal to `a + b`.
      *
-     * Uses Object.create() to bypass the constructor (zero normalisation cost).
-     * Only valid when |coefficient| is already in [1, 10) and exponent is correct.
-     * Do NOT use for unnormalised inputs - call new ArbitraryNumber(c, e) instead.
+     * Static methods always allocate — use instance `.add()` on hot paths.
      */
-    private static createNormalized;
+    static add(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
     /**
-     * Normalises raw (coefficient, exponent) into a new ArbitraryNumber.
+     * Returns a **new** instance equal to `a - b`.
+     */
+    static sub(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * Returns a **new** instance equal to `a * b`.
+     */
+    static mul(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * Returns a **new** instance equal to `a / b`.
      *
-     * INVARIANT: all ArbitraryNumber values must have coefficient in [1, 10).
-     * Algorithm: shift = floor(log10(|c|)); scale c by 10^-shift; adjust exponent.
-     * Cost: one Math.log10 call (~3-4 ns). This is the fundamental cost floor - logarithm
-     * is the only way to compute magnitude in JavaScript.
+     * @throws `"Division by zero"` when `b` is zero.
      */
-    private static normalizeFrom;
+    static div(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
     /**
-     * Returns `this + other`.
+     * Adds `other` to this number in-place.
+     *
+     * When the exponent difference exceeds `defaults.scaleCutoff`, the smaller
+     * operand has no effect and `this` is returned unchanged.
      *
-     * When the exponent difference exceeds {@link PrecisionCutoff}, the smaller
-     * operand has no effect and the larger is returned as-is.
+     * **Mutates `this`. Returns `this`.**
      *
      * @example
-     * new ArbitraryNumber(1.5, 3).add(new ArbitraryNumber(2.5, 3)); // 4*10^3
+     * gold.add(drop); // gold is mutated
      */
-    add(other: ArbitraryNumber): ArbitraryNumber;
+    add(other: ArbitraryNumber): this;
     /**
-     * Returns `this - other`.
+     * Subtracts `other` from this number in-place.
      *
-     * @example
-     * new ArbitraryNumber(3.5, 3).sub(new ArbitraryNumber(1.5, 3)); // 2*10^3
+     * **Mutates `this`. Returns `this`.**
      */
-    sub(other: ArbitraryNumber): ArbitraryNumber;
+    sub(other: ArbitraryNumber): this;
     /**
-     * Returns `this * other`.
+     * Multiplies this number by `other` in-place.
      *
-     * @example
-     * new ArbitraryNumber(2, 3).mul(new ArbitraryNumber(3, 4)); // 6*10^7
+     * **Mutates `this`. Returns `this`.**
      */
-    mul(other: ArbitraryNumber): ArbitraryNumber;
+    mul(other: ArbitraryNumber): this;
     /**
-     * Returns `this / other`.
+     * Divides this number by `other` in-place.
      *
-     * @example
-     * new ArbitraryNumber(6, 7).div(new ArbitraryNumber(3, 4)); // 2*10^3
+     * **Mutates `this`. Returns `this`.**
      *
      * @throws `"Division by zero"` when `other` is zero.
      */
-    div(other: ArbitraryNumber): ArbitraryNumber;
+    div(other: ArbitraryNumber): this;
     /**
-     * Returns the arithmetic negation of this number (`-this`).
+     * Negates this number in-place.
      *
-     * @example
-     * new ArbitraryNumber(1.5, 3).negate(); // -1.5*10^3
+     * **Mutates `this`. Returns `this`.**
      */
-    negate(): ArbitraryNumber;
+    negate(): this;
     /**
-     * Returns the absolute value of this number (`|this|`).
-     *
-     * Returns `this` unchanged when the number is already non-negative.
+     * Sets this number to its absolute value in-place.
      *
-     * @example
-     * new ArbitraryNumber(-1.5, 3).abs(); // 1.5*10^3
+     * **Mutates `this`. Returns `this`.**
      */
-    abs(): ArbitraryNumber;
+    abs(): this;
     /**
-     * Returns `this^n`.
+     * Raises this number to the power `n` in-place.
      *
      * Supports integer, fractional, and negative exponents.
-     * `x^0` always returns {@link One}, including `0^0` (by convention).
+     * `x^0` always sets `this` to `1`, including `0^0` (by convention).
      *
-     * @example
-     * new ArbitraryNumber(2, 3).pow(2);  // 4*10^6
-     * new ArbitraryNumber(2, 0).pow(-1); // 5*10^-1  (= 0.5)
+     * **Mutates `this`. Returns `this`.**
      *
-     * @param n - The exponent to raise this number to.
      * @throws `"Zero cannot be raised to a negative power"` when this is zero and `n < 0`.
      */
-    pow(n: number): ArbitraryNumber;
+    pow(n: number): this;
     /**
-     * Fused multiply-add: `(this * multiplier) + addend`.
+     * Fused multiply-add in-place: `this = (this * multiplier) + addend`.
      *
-     * Faster than `.mul(multiplier).add(addend)` because it avoids allocating an
-     * intermediate ArbitraryNumber for the product. One normalisation pass total.
+     * Faster than `.mul(multiplier).add(addend)` — one normalisation pass total, no
+     * intermediate allocation.
      *
-     * Common pattern - prestige loop: `value = value.mulAdd(prestigeMultiplier, prestigeBoost)`
+     * **Mutates `this`. Returns `this`.**
+     */
+    mulAdd(multiplier: ArbitraryNumber, addend: ArbitraryNumber): this;
+    /**
+     * @internal
+     * Computes `(this + sign * addendC * 10^addendE)` and writes the normalised
+     * result back into `this`. Used by `addMul` and `subMul` to share the alignment
+     * logic without duplication.
      *
-     * @example
-     * // Equivalent to value.mul(mult).add(boost) but ~35-50% faster
-     * const prestiged = currentValue.mulAdd(multiplier, boost);
+     * Returns the sign-adjusted addend coefficient so callers can detect the
+     * zero-result case. Writes the intermediate normalised sum into `this.coefficient`
+     * / `this.exponent` ready for the subsequent multiply step.
      */
-    mulAdd(multiplier: ArbitraryNumber, addend: ArbitraryNumber): ArbitraryNumber;
+    private _addScaledInto;
     /**
-     * Fused add-multiply: `(this + addend) * multiplier`.
+     * Fused add-multiply in-place: `this = (this + addend) * multiplier`.
      *
-     * Faster than `.add(addend).mul(multiplier)` because it avoids allocating an
-     * intermediate ArbitraryNumber for the sum. One normalisation pass total.
+     * **Mutates `this`. Returns `this`.**
+     */
+    addMul(addend: ArbitraryNumber, multiplier: ArbitraryNumber): this;
+    /**
+     * Fused multiply-subtract in-place: `this = (this * multiplier) - subtrahend`.
      *
-     * Common pattern - upgrade calculation: `newValue = baseValue.addMul(bonus, multiplier)`
+     * **Mutates `this`. Returns `this`.**
+     */
+    mulSub(multiplier: ArbitraryNumber, subtrahend: ArbitraryNumber): this;
+    /**
+     * Fused subtract-multiply in-place: `this = (this - subtrahend) * multiplier`.
      *
-     * @example
-     * // Equivalent to base.add(bonus).mul(multiplier) but ~20-25% faster
-     * const upgraded = baseValue.addMul(bonus, multiplier);
+     * **Mutates `this`. Returns `this`.**
      */
-    addMul(addend: ArbitraryNumber, multiplier: ArbitraryNumber): ArbitraryNumber;
+    subMul(subtrahend: ArbitraryNumber, multiplier: ArbitraryNumber): this;
     /**
-     * Fused multiply-subtract: `(this * multiplier) - subtrahend`.
+     * Fused divide-add in-place: `this = (this / divisor) + addend`.
      *
-     * Avoids one intermediate allocation vs `.mul(multiplier).sub(subtrahend)`.
+     * **Mutates `this`. Returns `this`.**
      *
-     * Common pattern - resource drain: `income.mulSub(rate, upkeepCost)`
+     * @throws `"Division by zero"` when divisor is zero.
      */
-    mulSub(multiplier: ArbitraryNumber, subtrahend: ArbitraryNumber): ArbitraryNumber;
+    divAdd(divisor: ArbitraryNumber, addend: ArbitraryNumber): this;
     /**
-     * Fused subtract-multiply: `(this - subtrahend) * multiplier`.
+     * Fused multiply-divide in-place: `this = (this * multiplier) / divisor`.
      *
-     * Avoids one intermediate allocation vs `.sub(subtrahend).mul(multiplier)`.
+     * **Mutates `this`. Returns `this`.**
      *
-     * Common pattern - upgrade after penalty: `health.subMul(damage, multiplier)`
+     * @throws `"Division by zero"` when divisor is zero.
      */
-    subMul(subtrahend: ArbitraryNumber, multiplier: ArbitraryNumber): ArbitraryNumber;
+    mulDiv(multiplier: ArbitraryNumber, divisor: ArbitraryNumber): this;
     /**
-     * Fused divide-add: `(this / divisor) + addend`.
+     * Efficiently sums an array of `ArbitraryNumber`s in a single pass.
      *
-     * Avoids one intermediate allocation vs `.div(divisor).add(addend)`.
+     * Maintains a running pivot exponent and rescales the accumulator when a larger
+     * exponent is encountered — one pass, no pre-scan needed.
      *
-     * Common pattern - efficiency bonus: `damage.divAdd(armor, flat)`
+     * Empty array returns `Zero`. Single element returned as-is (no clone).
+     */
+    static sumArray(numbers: ArbitraryNumber[]): ArbitraryNumber;
+    /**
+     * Multiplies an array of `ArbitraryNumber`s in a single pass.
      *
-     * @throws `"Division by zero"` when divisor is zero.
+     * Empty array returns `One`. Single element returned as-is.
+     */
+    static productArray(numbers: ArbitraryNumber[]): ArbitraryNumber;
+    /**
+     * Returns the largest value in an array. Empty array returns `Zero`.
+     */
+    static maxOfArray(numbers: ArbitraryNumber[]): ArbitraryNumber;
+    /**
+     * Returns the smallest value in an array. Empty array returns `Zero`.
      */
-    divAdd(divisor: ArbitraryNumber, addend: ArbitraryNumber): ArbitraryNumber;
+    static minOfArray(numbers: ArbitraryNumber[]): ArbitraryNumber;
     /**
-     * Efficiently sums an array of ArbitraryNumbers in a single normalisation pass.
+     * Rounds down to the nearest integer in-place (floor toward −∞).
      *
-     * **Why it's fast:** standard chained `.add()` normalises after every element (N log10 calls).
-     * `sumArray` aligns all coefficients to the largest exponent (pivot), sums them,
-     * then normalises once - regardless of array size.
+     * **Mutates `this`. Returns `this`.**
+     */
+    floor(): this;
+    /**
+     * Rounds up to the nearest integer in-place (ceil toward +∞).
      *
-     * For 50 elements: chained add ~ 50 log10 calls + 50 allocations;
-     * sumArray ~ 50 divisions + 1 log10 call + 1 allocation -> ~9* faster.
+     * **Mutates `this`. Returns `this`.**
+     */
+    ceil(): this;
+    /**
+     * Rounds to the nearest integer in-place.
      *
-     * Common pattern - income aggregation: `total = ArbitraryNumber.sumArray(incomeSourcesPerTick)`
+     * Uses `Math.round` semantics: half-values round toward positive infinity
+     * (`0.5 → 1`, `-0.5 → 0`). This matches JavaScript's built-in convention.
      *
-     * @example
-     * const total = ArbitraryNumber.sumArray(incomeSources); // far faster than .reduce((a, b) => a.add(b))
+     * **Mutates `this`. Returns `this`.**
+     */
+    round(): this;
+    /**
+     * Truncates toward zero in-place.
      *
-     * @param numbers - Array to sum. Empty array returns {@link Zero}. Single element returned as-is.
+     * **Mutates `this`. Returns `this`.**
      */
-    static sumArray(numbers: ArbitraryNumber[]): ArbitraryNumber;
+    trunc(): this;
+    /**
+     * Returns √this in-place.
+     *
+     * **Mutates `this`. Returns `this`.**
+     *
+     * @throws `"Square root of negative number"` when this is negative.
+     */
+    sqrt(): this;
+    /**
+     * Returns ∛this in-place.
+     *
+     * **Mutates `this`. Returns `this`.**
+     */
+    cbrt(): this;
+    /**
+     * Returns `log10(this)` as a plain `number`.
+     *
+     * @throws `"Logarithm of zero is undefined"` when this is zero.
+     * @throws `"Logarithm of a negative number is undefined"` when this is negative.
+     */
+    log10(): number;
+    /**
+     * Returns `log_base(this)` as a plain `number`.
+     *
+     * @param base - Must be positive and not 1.
+     * @throws `"Logarithm base must be positive and not 1"` for invalid base.
+     */
+    log(base: number): number;
+    /**
+     * Returns `ln(this)` as a plain `number`.
+     */
+    ln(): number;
+    /**
+     * Returns `10^n` as a new `ArbitraryNumber`.
+     *
+     * @throws `"ArbitraryNumber.exp10: n must be finite"` for non-finite `n`.
+     */
+    static exp10(n: number): ArbitraryNumber;
     /**
      * Compares this number to `other`.
      *
      * @returns `1` if `this > other`, `-1` if `this < other`, `0` if equal.
-     *
-     * @example
-     * new ArbitraryNumber(1, 4).compareTo(new ArbitraryNumber(9, 3)); // 1  (10000 > 9000)
-     * new ArbitraryNumber(-1, 4).compareTo(new ArbitraryNumber(1, 3)); // -1 (-10000 < 1000)
      */
     compareTo(other: ArbitraryNumber): number;
     /** Returns `true` if `this > other`. */
@@ -409,156 +553,134 @@ declare class ArbitraryNumber implements NormalizedNumber {
     /** Returns `true` if `this === other` in value. */
     equals(other: ArbitraryNumber): boolean;
     /**
-     * Returns the largest integer less than or equal to this number (floor toward -Infinity).
-     *
-     * Numbers with `exponent >= PrecisionCutoff` are already integers at that scale
-     * and are returned unchanged.
-     *
-     * @example
-     * new ArbitraryNumber(1.7, 0).floor();  // 1
-     * new ArbitraryNumber(-1.7, 0).floor(); // -2
-     */
-    floor(): ArbitraryNumber;
-    /**
-     * Returns the smallest integer greater than or equal to this number (ceil toward +Infinity).
-     *
-     * Numbers with `exponent >= PrecisionCutoff` are already integers at that scale
-     * and are returned unchanged.
-     *
-     * @example
-     * new ArbitraryNumber(1.2, 0).ceil();  // 2
-     * new ArbitraryNumber(-1.7, 0).ceil(); // -1
+     * Clamps `value` to the inclusive range `[min, max]`. Returns one of the three
+     * inputs (no allocation).
      */
-    ceil(): ArbitraryNumber;
+    static clamp(value: ArbitraryNumber, min: ArbitraryNumber, max: ArbitraryNumber): ArbitraryNumber;
+    /** Returns the smaller of `a` and `b`. */
+    static min(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
+    /** Returns the larger of `a` and `b`. */
+    static max(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
     /**
-     * Clamps `value` to the inclusive range `[min, max]`.
-     *
-     * @example
-     * ArbitraryNumber.clamp(new ArbitraryNumber(5, 2), new ArbitraryNumber(1, 3), new ArbitraryNumber(2, 3)); // 1*10^3  (500 clamped to [1000, 2000])
+     * Linear interpolation: `a + (b - a) * t`.
      *
-     * @param value - The value to clamp.
-     * @param min - Lower bound (inclusive).
-     * @param max - Upper bound (inclusive).
+     * Returns `a` unchanged when `t === 0`, `b` unchanged when `t === 1`.
+     * All other values of `t` allocate and return a fresh instance.
      */
-    static clamp(value: ArbitraryNumber, min: ArbitraryNumber, max: ArbitraryNumber): ArbitraryNumber;
+    static lerp(a: ArbitraryNumber, b: ArbitraryNumber, t: number): ArbitraryNumber;
     /**
-     * Returns the smaller of `a` and `b`.
-     * @example ArbitraryNumber.min(a, b)
+     * Runs `fn` with `defaults.scaleCutoff` temporarily set to `cutoff`, then restores it.
      */
-    static min(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
+    static withPrecision<T>(cutoff: number, fn: () => T): T;
+    /** Returns `true` when this number is zero. */
+    isZero(): boolean;
+    /** Returns `true` when this number is strictly positive. */
+    isPositive(): boolean;
+    /** Returns `true` when this number is strictly negative. */
+    isNegative(): boolean;
     /**
-     * Returns the larger of `a` and `b`.
-     * @example ArbitraryNumber.max(a, b)
+     * Returns `true` when this number has no fractional part.
+     * Numbers with `exponent >= scaleCutoff` are always considered integers.
      */
-    static max(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
+    isInteger(): boolean;
     /**
-     * Linear interpolation: `a + (b - a) * t` where `t in [0, 1]` is a plain number.
-     *
-     * Used for smooth animations and tweening in game UIs.
-     * `t = 0` returns `a`; `t = 1` returns `b`.
-     *
-     * @param t - Interpolation factor as a plain `number`. Values outside [0, 1] are allowed (extrapolation).
-     * @example
-     * ArbitraryNumber.lerp(an(100), an(200), 0.5); // 150
+     * Returns `1` if positive, `-1` if negative, `0` if zero.
      */
-    static lerp(a: ArbitraryNumber, b: ArbitraryNumber, t: number): ArbitraryNumber;
+    sign(): Signum;
     /**
-     * Runs `fn` with `PrecisionCutoff` temporarily set to `cutoff`, then restores the previous value.
+     * Returns a `FrozenArbitraryNumber` wrapping the same value.
      *
-     * Useful when one section of code needs different precision than the rest.
-     *
-     * @example
-     * // Run financial calculation with higher precision
-     * const result = ArbitraryNumber.withPrecision(50, () => a.add(b));
+     * Mutating methods on the frozen instance throw `ArbitraryNumberMutationError`.
+     * Call `.clone()` on the frozen instance to get a fresh, mutable copy.
      */
-    static withPrecision<T>(cutoff: number, fn: () => T): T;
+    freeze(): FrozenArbitraryNumber;
     /**
-     * Returns `log10(this)` as a plain JavaScript `number`.
-     *
-     * Because the number is stored as `c * 10^e`, this is computed exactly as
-     * `log10(c) + e` - no precision loss from the exponent.
-     *
-     * @example
-     * new ArbitraryNumber(1, 6).log10();    // 6
-     * new ArbitraryNumber(1.5, 3).log10();  // log10(1.5) + 3  ~ 3.176
+     * Converts to a plain JavaScript `number`.
      *
-     * @throws `"Logarithm of zero is undefined"` when this is zero.
-     * @throws `"Logarithm of a negative number is undefined"` when this is negative.
+     * Returns `Infinity` for exponents beyond float64 range (>=308).
+     * Returns `0` for exponents below float64 range (<=-324).
      */
-    log10(): number;
+    toNumber(): number;
     /**
-     * Returns √this.
+     * Returns a stable, minimal JSON representation: `{ c: number, e: number }`.
      *
-     * Computed as pure coefficient math - no `Math.log10` call. Cost: one `Math.sqrt`.
-     * For even exponents: `sqrt(c) * 10^(e/2)`.
-     * For odd exponents: `sqrt(c * 10) * 10^((e-1)/2)`.
-     *
-     * @throws `"Square root of negative number"` when this is negative.
-     * @example
-     * new ArbitraryNumber(4, 0).sqrt();   // 2
-     * new ArbitraryNumber(1, 4).sqrt();   // 1*10^2  (= 100)
+     * Round-trip guarantee: `ArbitraryNumber.fromJSON(x.toJSON()).equals(x)` is always `true`.
      */
-    sqrt(): ArbitraryNumber;
+    toJSON(): ArbitraryNumberJson;
     /**
-     * Returns the nearest integer value (rounds half-up).
+     * Returns a compact string representation: `"<coefficient>|<exponent>"`.
      *
-     * Numbers with `exponent >= PrecisionCutoff` are already integers at that scale
-     * and are returned unchanged.
+     * Shorter than JSON for save-game serialisation. Reconstruct via `ArbitraryNumber.parse`.
      *
      * @example
-     * new ArbitraryNumber(1.5, 0).round();  // 2
-     * new ArbitraryNumber(1.4, 0).round();  // 1
-     * new ArbitraryNumber(-1.5, 0).round(); // -1 (half-up toward positive infinity)
+     * an(1500).toRawString() // "1.5|3"
      */
-    round(): ArbitraryNumber;
+    toRawString(): string;
     /**
-     * Returns `1` if positive, `-1` if negative, `0` if zero.
+     * Reconstructs an `ArbitraryNumber` from a `toJSON()` blob.
      *
-     * @example
-     * new ArbitraryNumber(1.5, 3).sign();  // 1
-     * new ArbitraryNumber(-1.5, 3).sign(); // -1
-     * ArbitraryNumber.Zero.sign();         // 0
+     * @throws `ArbitraryNumberInputError` when the object shape is invalid or values are non-finite.
      */
-    sign(): Signum;
+    static fromJSON(obj: unknown): ArbitraryNumber;
     /**
-     * Converts to a plain JavaScript `number`.
+     * Parses a string into an `ArbitraryNumber`.
      *
-     * Precision is limited to float64 (~15 significant digits).
-     * Returns `Infinity` for exponents beyond the float64 range (>=308).
-     * Returns `0` for exponents below the float64 range (<=-324).
+     * Accepted formats:
+     * - Raw pipe format: `"1.5|3"`, `"-2.5|-6"`
+     * - Scientific notation: `"1.5e+3"`, `"1.5E3"`
+     * - Plain decimal: `"1500"`, `"-0.003"`, `"0"`
      *
-     * @example
-     * new ArbitraryNumber(1.5, 3).toNumber();  // 1500
-     * new ArbitraryNumber(1, 400).toNumber();  // Infinity
+     * @throws `ArbitraryNumberInputError` for invalid or non-finite input.
      */
-    toNumber(): number;
-    /** Returns `true` when this number is zero. */
-    isZero(): boolean;
-    /** Returns `true` when this number is strictly positive. */
-    isPositive(): boolean;
-    /** Returns `true` when this number is strictly negative. */
-    isNegative(): boolean;
+    static parse(s: string): ArbitraryNumber;
     /**
-     * Returns `true` when this number has no fractional part.
-     * Numbers with `exponent >= PrecisionCutoff` are always considered integers.
+     * Allows implicit coercion via `+an(1500)` (returns `toNumber()`) and
+     * template literals / string concatenation (returns `toString()`).
      */
-    isInteger(): boolean;
+    [Symbol.toPrimitive](hint: string): number | string;
     /**
      * Formats this number as a string using the given notation plugin.
      *
-     * Defaults to {@link scientificNotation} when no plugin is provided.
-     * `decimals` controls the number of decimal places passed to the plugin and defaults to `2`.
-     *
-     * @example
-     * new ArbitraryNumber(1.5, 3).toString();                  // "1.50e+3"
-     * new ArbitraryNumber(1.5, 3).toString(unitNotation);       // "1.50 K"
-     * new ArbitraryNumber(1.5, 3).toString(unitNotation, 4);    // "1.5000 K"
-     *
-     * @param notation - The formatting plugin to use.
-     * @param decimals - Number of decimal places to render. Defaults to `2`.
+     * Defaults to `scientificNotation` when no plugin is provided.
+     * `decimals` controls decimal places and defaults to `defaults.notationDecimals`.
      */
     toString(notation?: NotationPlugin, decimals?: number): string;
 }
+/**
+ * An immutable wrapper around `ArbitraryNumber`.
+ *
+ * Created via `number.freeze()`. All mutating methods throw `ArbitraryNumberMutationError`.
+ * Call `.clone()` to get a fresh, mutable `ArbitraryNumber`.
+ *
+ * @example
+ * const frozen = gold.freeze();
+ * frozen.add(drop);  // throws ArbitraryNumberMutationError
+ * const mutable = frozen.clone(); // fresh mutable copy
+ */
+declare class FrozenArbitraryNumber extends ArbitraryNumber {
+    /** @internal */
+    constructor(coefficient: number, exponent: number);
+    private _throwMutation;
+    add(_other: ArbitraryNumber): never;
+    sub(_other: ArbitraryNumber): never;
+    mul(_other: ArbitraryNumber): never;
+    div(_other: ArbitraryNumber): never;
+    negate(): never;
+    abs(): never;
+    pow(_n: number): never;
+    mulAdd(_m: ArbitraryNumber, _a: ArbitraryNumber): never;
+    addMul(_a: ArbitraryNumber, _m: ArbitraryNumber): never;
+    mulSub(_m: ArbitraryNumber, _s: ArbitraryNumber): never;
+    subMul(_s: ArbitraryNumber, _m: ArbitraryNumber): never;
+    divAdd(_d: ArbitraryNumber, _a: ArbitraryNumber): never;
+    mulDiv(_m: ArbitraryNumber, _d: ArbitraryNumber): never;
+    floor(): never;
+    ceil(): never;
+    round(): never;
+    trunc(): never;
+    sqrt(): never;
+    cbrt(): never;
+}
 
 /**
  * Base class for all errors thrown by the arbitrary-numbers library.
@@ -602,111 +724,38 @@ declare class ArbitraryNumberDomainError extends ArbitraryNumberError {
     readonly context: Record<string, number>;
     constructor(message: string, context: Record<string, number>);
 }
-
-declare const an: AnFunction;
-
 /**
- * Fluent builder for multi-step `ArbitraryNumber` expressions.
- *
- * Each method mutates the accumulated value in-place and returns `this`,
- * enabling a readable left-to-right pipeline with no expression-tree
- * overhead.  Every step delegates directly to the underlying
- * `ArbitraryNumber` method - fused variants (`mulAdd`, `mulSub`, etc.)
- * are available here too.
+ * Thrown when a mutating method is called on a frozen `ArbitraryNumber`.
  *
  * @example
- * // Damage formula: ((base - armour) * mult) + flatBonus
- * const result = chain(base)
- *     .subMul(armour, multiplier)
- *     .add(flatBonus)
- *     .done();
- *
- * @remarks
- * No deferred execution - each call runs immediately.  Overhead vs direct
- * method chaining is a single extra method call + `return this` per step
- * (~1-2 ns).  Use fused ops for hot inner loops; the builder is optimised
- * for readability in complex multi-step formulas.
+ * try {
+ *     frozen.add(other);
+ * } catch (e) {
+ *     if (e instanceof ArbitraryNumberMutationError) { ... }
+ * }
  */
-declare class AnChain {
-    private value;
-    private constructor();
-    /** Creates an `AnChain` from an `ArbitraryNumber` or a plain `number`. */
-    static from(value: ArbitraryNumber | number): AnChain;
-    /** Adds `other` to the accumulated value. */
-    add(other: ArbitraryNumber): this;
-    /** Subtracts `other` from the accumulated value. */
-    sub(other: ArbitraryNumber): this;
-    /** Multiplies the accumulated value by `other`. */
-    mul(other: ArbitraryNumber): this;
-    /** Divides the accumulated value by `other`. */
-    div(other: ArbitraryNumber): this;
-    /** Raises the accumulated value to `exp`. */
-    pow(exp: number): this;
-    /** `(this * mult) + add` */
-    mulAdd(mult: ArbitraryNumber, add: ArbitraryNumber): this;
-    /** `(this + add) * mult` */
-    addMul(add: ArbitraryNumber, mult: ArbitraryNumber): this;
-    /** `(this * mult) - sub` */
-    mulSub(mult: ArbitraryNumber, sub: ArbitraryNumber): this;
-    /** `(this - sub) * mult` */
-    subMul(sub: ArbitraryNumber, mult: ArbitraryNumber): this;
-    /** `(this / div) + add` */
-    divAdd(div: ArbitraryNumber, add: ArbitraryNumber): this;
-    /** Absolute value. */
-    abs(): this;
-    /** Negates the accumulated value. */
-    neg(): this;
-    /** Square root of the accumulated value. */
-    sqrt(): this;
-    /** Rounds down to the nearest integer. */
-    floor(): this;
-    /** Rounds up to the nearest integer. */
-    ceil(): this;
-    /** Rounds to the nearest integer. */
-    round(): this;
-    /** Returns the accumulated `ArbitraryNumber` result. */
-    done(): ArbitraryNumber;
+declare class ArbitraryNumberMutationError extends ArbitraryNumberDomainError {
+    constructor(message: string);
 }
-/**
- * Creates an {@link AnChain} builder starting from `value`.
- *
- * Mirrors the `an` factory shorthand.
- *
- * @example
- * import { chain, an } from 'arbitrary-numbers';
- *
- * const result = chain(an(1.5, 6))
- *     .mulAdd(multiplier, bonus)
- *     .floor()
- *     .done();
- */
-declare function chain(value: ArbitraryNumber | number): AnChain;
 
-type FormulaStep = (value: ArbitraryNumber) => ArbitraryNumber;
+declare const an: AnFunction;
+
+type FormulaStep = (value: ArbitraryNumber) => void;
 /**
  * A reusable, named pipeline of `ArbitraryNumber` operations.
  *
- * Unlike {@link AnChain}, which executes each step immediately against an
- * accumulated value, `AnFormula` stores the operations as a list of closures
- * and runs them only when {@link apply} is called.  The same formula can be
- * applied to any number of values without re-defining the pipeline.
+ * `AnFormula` stores operations as closures and runs them on `.apply()` or `.applyInPlace()`.
+ * The same formula can be applied to any number of values without re-defining the pipeline.
  *
- * Each builder method returns a **new** `AnFormula` - the original is
- * unchanged.  This makes branching and composition safe:
+ * Each builder method returns a **new** `AnFormula` — the original is unchanged.
  *
  * @example
- * const base      = formula().mul(an(2));
- * const withFloor = base.floor();   // new formula - base is unchanged
- * const withCeil  = base.ceil();    // another branch from base
- *
- * @example
- * // Define once, apply to many values
  * const armorReduction = formula("Armor Reduction")
  *     .subMul(armor, an(0.75))
  *     .floor();
  *
- * const physDamage = armorReduction.apply(physBase);
- * const magDamage  = armorReduction.apply(magBase);
+ * const physDamage = armorReduction.apply(physBase);   // physBase unchanged
+ * armorReduction.applyInPlace(enemyAtk);               // enemyAtk mutated
  *
  * @example
  * // Compose formulas
@@ -715,23 +764,14 @@ type FormulaStep = (value: ArbitraryNumber) => ArbitraryNumber;
  * const result    = full.apply(baseDamage);
  */
 declare class AnFormula {
-    private readonly _name?;
+    private readonly _name;
     private readonly steps;
-    /**
-     * Prefer the {@link formula} factory function over calling this directly.
-     */
-    constructor(name?: string, steps?: ReadonlyArray<FormulaStep>);
+    /** Prefer the {@link formula} factory function over calling this directly. */
+    constructor(name?: Maybe<string>, steps?: ReadonlyArray<FormulaStep>);
     /** The name passed to {@link formula}, if any. */
-    get name(): string | undefined;
+    get name(): Maybe<string>;
     /**
      * Returns a copy of this formula with a new name, leaving the original unchanged.
-     *
-     * @param name - The new name.
-     * @example
-     * const base  = formula().mul(an(2));
-     * const named = base.named("Double");
-     * named.name   // "Double"
-     * base.name    // undefined
      */
     named(name: string): AnFormula;
     private step;
@@ -757,7 +797,7 @@ declare class AnFormula {
     divAdd(div: ArbitraryNumber, add: ArbitraryNumber): AnFormula;
     /** Appends `abs()` to the pipeline. */
     abs(): AnFormula;
-    /** Appends `neg()` to the pipeline. */
+    /** Appends `negate()` to the pipeline. */
     neg(): AnFormula;
     /** Appends `sqrt()` to the pipeline. */
     sqrt(): AnFormula;
@@ -771,52 +811,44 @@ declare class AnFormula {
      * Returns a new formula that first applies `this`, then applies `next`.
      *
      * Neither operand is mutated.
-     *
-     * @param next - The formula to apply after `this`.
-     * @example
-     * const full   = armorReduction.then(critBonus);
-     * const result = full.apply(baseDamage);
      */
     then(next: AnFormula): AnFormula;
     /**
-     * Runs this formula's pipeline against `value` and returns the result.
+     * Clones `value` once, runs the pipeline against the clone, and returns it.
      *
-     * The formula itself is unchanged - call `apply` as many times as needed.
+     * The original `value` is never mutated.
      *
-     * @param value - The starting value. Plain `number` is coerced via `ArbitraryNumber.from`.
-     * @throws `"ArbitraryNumber.from: value must be finite"` when a plain `number` is non-finite.
      * @example
-     * const damage = damageFormula.apply(baseDamage);
-     * const scaled = damageFormula.apply(boostedBase);
+     * const damage = damageFormula.apply(playerAtk); // playerAtk unchanged
      */
     apply(value: ArbitraryNumber | number): ArbitraryNumber;
+    /**
+     * Runs the pipeline directly against `value`, mutating it in-place.
+     *
+     * Use on hot paths where you don't need to preserve the original value.
+     *
+     * @example
+     * damageFormula.applyInPlace(enemyAtk); // enemyAtk is mutated
+     */
+    applyInPlace(value: ArbitraryNumber): void;
 }
 /**
  * Creates an {@link AnFormula} pipeline, optionally named.
  *
- * Build the pipeline by chaining methods - each returns a new `AnFormula`
- * so the original is always safe to branch or reuse.  Call {@link AnFormula.apply}
- * to run the pipeline against a value.
+ * Build the pipeline by chaining methods — each returns a new `AnFormula`.
+ * Call {@link AnFormula.apply} or {@link AnFormula.applyInPlace} to run it.
  *
- * @param name - Optional label, available via {@link AnFormula.name} for debugging.
  * @example
  * import { formula, an } from 'arbitrary-numbers';
  *
  * const armorReduction = formula("Armor Reduction")
- *     .subMul(armor, an(0.75))   // (base - armor) * 0.75
+ *     .subMul(armor, an(0.75))
  *     .floor();
  *
- * const critBonus = formula("Crit Bonus").mul(critMult).ceil();
- *
- * // Reuse across many values
  * const physDmg = armorReduction.apply(physBase);
- * const magDmg  = armorReduction.apply(magBase);
- *
- * // Compose
- * const full   = armorReduction.then(critBonus);
- * const result = full.apply(baseDamage);
+ * armorReduction.applyInPlace(tempValue);
  */
-declare function formula(name?: string): AnFormula;
+declare function formula(name?: Maybe<string>): AnFormula;
 
 /**
  * Formats numbers using standard scientific notation: `"1.50e+3"`, `"1.50e-5"`.
@@ -988,14 +1020,23 @@ declare const letterNotation: AlphabetNotation;
 declare class UnitNotation extends SuffixNotationBase {
     protected readonly fallback?: SuffixProvider;
     protected readonly units: UnitArray;
+    /** The highest tier index that has a defined unit in `units`. Used to offset fallback calls. */
+    private readonly lastDefinedTier;
+    private readonly offsetFallback;
     /**
      * @param options - Tier-indexed unit array, optional suffix fallback plugin, and separator.
      *   `separator` defaults to `" "` (a space between number and unit symbol).
+     *   `offsetFallback` defaults to `true` — the fallback tier is offset so its suffixes
+     *   are visually distinct from any low-tier suffixes the same fallback would produce.
      */
     constructor(options: UnitNotationOptions);
     /**
      * Returns the suffix for the given tier: the own unit symbol if defined,
-     * otherwise the fallback's suffix, otherwise `""`.
+     * otherwise the fallback's suffix (offset by the last defined tier when
+     * `offsetFallback` is `true`), otherwise `""`.
+     *
+     * The offset ensures fallback suffixes start at tier 1 of the fallback's sequence,
+     * avoiding visual ambiguity with low-tier suffixes from the same fallback plugin.
      *
      * @param tier - The exponent tier (`Math.floor(exponent / 3)`).
      * @returns The suffix string, or `""` if neither own units nor fallback cover this tier.
@@ -1051,18 +1092,15 @@ declare class ArbitraryNumberGuard {
      */
     static isArbitraryNumber(obj: unknown): obj is ArbitraryNumber;
     /**
-     * Returns `true` if `obj` has the shape of a {@link NormalizedNumber}
-     * (i.e. has numeric `coefficient` and `exponent` properties).
-     *
-     * Note: both `ArbitraryNumber` instances and plain objects with the right
-     * shape will pass this check. Use {@link isArbitraryNumber} when you need
-     * to distinguish between the two.
+     * Returns `true` if `obj` has the shape `{ coefficient: number; exponent: number }`.
      *
-     * @param obj - The value to test.
-     * @returns `true` when `obj` has `typeof coefficient === "number"` and
-     *   `typeof exponent === "number"`.
+     * Both `ArbitraryNumber` instances and plain objects with the right shape pass this
+     * check. Use {@link isArbitraryNumber} to distinguish the two.
      */
-    static isNormalizedNumber(obj: unknown): obj is NormalizedNumber;
+    static isNormalizedNumber(obj: unknown): obj is {
+        coefficient: number;
+        exponent: number;
+    };
     /**
      * Returns `true` if `obj` is an {@link ArbitraryNumber} with a value of zero.
      *
@@ -1072,102 +1110,10 @@ declare class ArbitraryNumberGuard {
     static isZero(obj: unknown): boolean;
 }
 
-/**
- * A value that can be either a plain `number` or an `ArbitraryNumber`.
- */
-type ArbitraryNumberish = ArbitraryNumber | number;
-
-/**
- * Convenience helpers for mixed `number | ArbitraryNumber` inputs.
- *
- * Each method accepts either type and coerces plain `number` values via
- * {@link ArbitraryNumber.from} before delegating to the corresponding instance method.
- *
- * Prefer `ArbitraryNumber` instance methods directly on hot paths - this class is
- * intended for system boundaries (event handlers, serialisation, UI callbacks) where
- * the input type is unknown.
- *
- * @example
- * import { ArbitraryNumberOps as ops } from "arbitrary-numbers";
- * ops.add(1500, 2500)              // ArbitraryNumber (4000)
- * ops.mul(an(2, 0), 5)            // ArbitraryNumber (10)
- * ops.from(1_500_000)             // ArbitraryNumber { coefficient: 1.5, exponent: 6 }
- */
-declare class ArbitraryNumberOps {
-    /**
-     * Converts `value` to an `ArbitraryNumber`, returning it unchanged if it already is one.
-     *
-     * @param value - A plain `number` or an existing `ArbitraryNumber`.
-     * @returns The corresponding `ArbitraryNumber`.
-     */
-    static from(value: ArbitraryNumberish): ArbitraryNumber;
-    /**
-     * Returns `left + right`, coercing both operands as needed.
-     *
-     * @param left - The augend.
-     * @param right - The addend.
-     * @example
-     * ops.add(1500, 2500) // ArbitraryNumber (4000)
-     */
-    static add(left: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
-    /**
-     * Returns `left - right`, coercing both operands as needed.
-     *
-     * @param left - The minuend.
-     * @param right - The subtrahend.
-     * @example
-     * ops.sub(5000, 1500) // ArbitraryNumber (3500)
-     */
-    static sub(left: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
-    /**
-     * Returns `left * right`, coercing both operands as needed.
-     *
-     * @param left - The multiplicand.
-     * @param right - The multiplier.
-     * @example
-     * ops.mul(an(1, 3), 5) // ArbitraryNumber (5000)
-     */
-    static mul(left: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
-    /**
-     * Returns `left / right`, coercing both operands as needed.
-     *
-     * @param left - The dividend.
-     * @param right - The divisor.
-     * @throws `"Division by zero"` when `right` is zero.
-     * @example
-     * ops.div(an(1, 6), 1000) // ArbitraryNumber (1000)
-     */
-    static div(left: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
-    /**
-     * Compares `left` to `right`.
-     *
-     * @param left - The left operand.
-     * @param right - The right operand.
-     * @returns `1` if `left > right`, `-1` if `left < right`, `0` if equal.
-     * @example
-     * ops.compare(5000, 1500) // 1
-     */
-    static compare(left: ArbitraryNumberish, right: ArbitraryNumberish): number;
-    /**
-     * Clamps `value` to the inclusive range `[min, max]`, coercing all inputs as needed.
-     *
-     * @param value - The value to clamp.
-     * @param min - The lower bound (inclusive).
-     * @param max - The upper bound (inclusive).
-     * @example
-     * ops.clamp(500, 1000, 2000) // ArbitraryNumber (1000)  - below min, returns min
-     */
-    static clamp(value: ArbitraryNumberish, min: ArbitraryNumberish, max: ArbitraryNumberish): ArbitraryNumber;
-}
-
 /**
  * Domain-level helpers for common game and simulation patterns.
  *
- * These sit above the core arithmetic layer - each method accepts
- * mixed input (`number | ArbitraryNumber`) via
- * {@link ArbitraryNumberOps.from} so they work at system boundaries
- * where you may receive raw numbers.
- *
+ * Accepts mixed input (`number | ArbitraryNumber`) via `ArbitraryNumber.from`.
  * For hot-path code, use `ArbitraryNumber` methods directly.
  */
 declare class ArbitraryNumberHelpers {
@@ -1175,9 +1121,6 @@ declare class ArbitraryNumberHelpers {
     /**
      * Returns `true` when `value >= threshold`.
      *
-     * @param value - The value to test.
-     * @param threshold - The minimum required value.
-     * @returns `true` when `value >= threshold`.
      * @example
      * ArbitraryNumberHelpers.meetsOrExceeds(gold, upgradeCost)
      */
@@ -1187,9 +1130,6 @@ declare class ArbitraryNumberHelpers {
      *
      * Equivalent to `floor(total / step)`.
      *
-     * @param total - The total available amount.
-     * @param step - The cost or size of one unit. Must be greater than zero.
-     * @returns The number of whole units that fit, as an `ArbitraryNumber`.
      * @throws `"step must be greater than zero"` when `step <= 0`.
      * @example
      * const canBuy = ArbitraryNumberHelpers.wholeMultipleCount(gold, upgradeCost);
@@ -1198,14 +1138,10 @@ declare class ArbitraryNumberHelpers {
     /**
      * Returns `value - delta`, clamped to a minimum of `floor` (default `0`).
      *
-     * @param value - The starting value.
-     * @param delta - The amount to subtract.
-     * @param floor - The minimum result. Defaults to `ArbitraryNumber.Zero`.
-     * @returns `max(value - delta, floor)`.
      * @example
      * health = ArbitraryNumberHelpers.subtractWithFloor(health, damage);
      */
     static subtractWithFloor(value: ArbitraryNumberish, delta: ArbitraryNumberish, floor?: ArbitraryNumberish): ArbitraryNumber;
 }
 
-export { AlphabetNotation, type AlphabetNotationOptions, AnChain, AnFormula, type AnFunction, ArbitraryNumber, ArbitraryNumberDomainError, ArbitraryNumberError, ArbitraryNumberGuard, ArbitraryNumberHelpers, ArbitraryNumberInputError, ArbitraryNumberOps, type ArbitraryNumberish, CLASSIC_UNITS, COMPACT_UNITS, type Mod3, type NormalizedNumber, type NotationPlugin, ScientificNotation, type Signum, SuffixNotationBase, type SuffixNotationPlugin, type SuffixNotationPluginOptions, type SuffixProvider, type Unit, type UnitArray, UnitNotation, type UnitNotationOptions, alphabetSuffix, an, chain, formula, ArbitraryNumberGuard as guard, ArbitraryNumberHelpers as helpers, letterNotation, ArbitraryNumberOps as ops, scientificNotation, unitNotation };
+export { AlphabetNotation, type AlphabetNotationOptions, AnFormula, type AnFunction, ArbitraryNumber, type ArbitraryNumberDefaults, ArbitraryNumberDomainError, ArbitraryNumberError, ArbitraryNumberGuard, ArbitraryNumberHelpers, ArbitraryNumberInputError, type ArbitraryNumberJson, ArbitraryNumberMutationError, type ArbitraryNumberish, CLASSIC_UNITS, COMPACT_UNITS, FrozenArbitraryNumber, type Maybe, type Mod3, type NotationPlugin, type Nullable, ScientificNotation, type Signum, SuffixNotationBase, type SuffixNotationPlugin, type SuffixNotationPluginOptions, type SuffixProvider, type Unit, type UnitArray, UnitNotation, type UnitNotationOptions, alphabetSuffix, an, formula, ArbitraryNumberGuard as guard, ArbitraryNumberHelpers as helpers, letterNotation, scientificNotation, unitNotation };