arbitrary-numbers 1.0.2 → 2.0.0

package/dist/index.js

@@ -9,9 +9,17 @@ var ScientificNotation = class {
    * @returns The formatted string.
    */
   format(coefficient, exponent, decimals) {
-    if (exponent === 0) return coefficient.toFixed(decimals);
-    const sign = exponent < 0 ? "-" : "+";
-    return `${coefficient.toFixed(decimals)}e${sign}${Math.abs(exponent)}`;
+    let c = coefficient;
+    let e = exponent;
+    let fixed = c.toFixed(decimals);
+    if (Math.abs(parseFloat(fixed)) >= 10) {
+      c = c / 10;
+      e = e + 1;
+      fixed = c.toFixed(decimals);
+    }
+    if (e === 0) return fixed;
+    const sign = e < 0 ? "-" : "+";
+    return `${fixed}e${sign}${Math.abs(e)}`;
   }
 };
 var scientificNotation = new ScientificNotation();
@@ -33,10 +41,17 @@ var POW10 = [
   1e12,
   1e13,
   1e14,
-  1e15
+  1e15,
+  1e16,
+  1e17,
+  1e18,
+  1e19,
+  1e20,
+  1e21,
+  1e22
 ];
 function pow10(n) {
-  return n >= 0 && n < 16 ? POW10[n] : Math.pow(10, n);
+  return n >= 0 && n < 23 ? POW10[n] : Math.pow(10, n);
 }
 
 // src/errors.ts
@@ -60,41 +75,27 @@ var ArbitraryNumberDomainError = class extends ArbitraryNumberError {
     this.context = context;
   }
 };
+var ArbitraryNumberMutationError = class extends ArbitraryNumberDomainError {
+  constructor(message) {
+    super(message, {});
+    this.name = "ArbitraryNumberMutationError";
+  }
+};
 
 // src/core/ArbitraryNumber.ts
+var _scaleCutoff = 15;
 var _ArbitraryNumber = class _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.
-   *
-   * @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`.
-   */
-  static from(value) {
-    if (!isFinite(value)) {
-      throw new ArbitraryNumberInputError("ArbitraryNumber.from: value must be finite", value);
-    }
-    return new _ArbitraryNumber(value, 0);
-  }
   /**
    * Constructs a new `ArbitraryNumber` and immediately normalises it so that
    * `1 <= |coefficient| < 10` (or `coefficient === 0`).
    *
+   * Always two numeric arguments — this keeps the constructor monomorphic so V8
+   * locks in a hidden class on first use (~5 ns allocation).
+   *
    * @example
    * new ArbitraryNumber(15, 3); // stored as { coefficient: 1.5, exponent: 4 }
    *
-   * @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.
+   * @throws `ArbitraryNumberInputError` for `NaN`/`Infinity` coefficient or exponent.
    */
   constructor(coefficient, exponent) {
     if (coefficient === 0) {
@@ -120,185 +121,329 @@ var _ArbitraryNumber = class _ArbitraryNumber {
     this.exponent = exponent + shift;
   }
   /**
-   * @internal Fast-path factory for already-normalised values.
+   * @internal Fast-path factory for already-normalised values. Not exported from `index.ts`.
    *
-   * 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.
+   * 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 createNormalized(coefficient, exponent) {
-    const n = Object.create(_ArbitraryNumber.prototype);
+  static unsafe(coefficient, exponent) {
+    const n = new _ArbitraryNumber(0, 0);
     n.coefficient = coefficient;
     n.exponent = exponent;
     return n;
   }
-  /**
-   * Normalises raw (coefficient, exponent) into a new ArbitraryNumber.
-   *
-   * 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.
-   */
-  static normalizeFrom(c, e) {
+  /** @internal Normalise an arbitrary `(c, e)` pair into a new instance. */
+  static _normalizeNew(c, e) {
     if (c === 0) return _ArbitraryNumber.Zero;
     const abs = Math.abs(c);
     const shift = Math.floor(Math.log10(abs));
     const scale = pow10(shift);
     if (scale === 0) return _ArbitraryNumber.Zero;
-    return _ArbitraryNumber.createNormalized(c / scale, e + shift);
+    return _ArbitraryNumber.unsafe(c / scale, e + shift);
+  }
+  /** @internal Normalise `(c, e)` into `this` (mutates). Returns `this`. */
+  _normalizeInto(c, e) {
+    if (c === 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return this;
+    }
+    const abs = c < 0 ? -c : c;
+    if (abs < 10) {
+      if (abs >= 1) {
+        this.coefficient = c;
+        this.exponent = e;
+        return this;
+      }
+      this.coefficient = c * 10;
+      this.exponent = e - 1;
+      return this;
+    }
+    if (abs < 100) {
+      this.coefficient = c / 10;
+      this.exponent = e + 1;
+      return this;
+    }
+    if (!isFinite(c)) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return this;
+    }
+    const shift = Math.floor(Math.log10(abs));
+    const scale = pow10(shift);
+    if (scale === 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return this;
+    }
+    this.coefficient = c / scale;
+    this.exponent = e + shift;
+    return this;
   }
+  // ── Factories ──────────────────────────────────────────────────────────────
   /**
-   * Returns `this + other`.
+   * Returns a fresh, unfrozen copy of this number. The canonical way to preserve
+   * a value before mutating it:
    *
-   * When the exponent difference exceeds {@link PrecisionCutoff}, the smaller
-   * operand has no effect and the larger is returned as-is.
+   * ```ts
+   * const before = gold.clone();
+   * gold.add(drop);
+   * ```
+   */
+  clone() {
+    return _ArbitraryNumber.unsafe(this.coefficient, this.exponent);
+  }
+  /**
+   * Creates an `ArbitraryNumber` from a plain JavaScript `number`.
+   *
+   * @throws `ArbitraryNumberInputError` for `NaN`, `Infinity`, or `-Infinity`.
+   *
+   * @example
+   * ArbitraryNumber.from(1500);  // { coefficient: 1.5, exponent: 3 }
+   */
+  static from(value) {
+    if (!isFinite(value)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.from: value must be finite", value);
+    }
+    return new _ArbitraryNumber(value, 0);
+  }
+  /**
+   * Like `from`, but returns `null` instead of throwing for non-finite inputs.
+   *
+   * Use at system boundaries (form inputs, external APIs) where bad input should
+   * be handled gracefully.
+   *
+   * @example
+   * ArbitraryNumber.tryFrom(Infinity) // null
+   * ArbitraryNumber.tryFrom(1500)     // ArbitraryNumber { coefficient: 1.5, exponent: 3 }
+   */
+  static tryFrom(value) {
+    if (!isFinite(value)) return null;
+    return new _ArbitraryNumber(value, 0);
+  }
+  // ── Static arithmetic (allocate) ───────────────────────────────────────────
+  /**
+   * Returns a **new** instance equal to `a + b`.
+   *
+   * Static methods always allocate — use instance `.add()` on hot paths.
+   */
+  static add(a, b) {
+    return a.clone().add(b);
+  }
+  /**
+   * Returns a **new** instance equal to `a - b`.
+   */
+  static sub(a, b) {
+    return a.clone().sub(b);
+  }
+  /**
+   * Returns a **new** instance equal to `a * b`.
+   */
+  static mul(a, b) {
+    return a.clone().mul(b);
+  }
+  /**
+   * Returns a **new** instance equal to `a / b`.
+   *
+   * @throws `"Division by zero"` when `b` is zero.
+   */
+  static div(a, b) {
+    return a.clone().div(b);
+  }
+  // ── Instance arithmetic (mutate this) ──────────────────────────────────────
+  /**
+   * 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.
+   *
+   * **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) {
-    if (this.coefficient === 0) return other;
     if (other.coefficient === 0) return this;
+    if (this.coefficient === 0) {
+      this.coefficient = other.coefficient;
+      this.exponent = other.exponent;
+      return this;
+    }
+    const cutoff = _scaleCutoff;
     const diff = this.exponent - other.exponent;
-    if (diff > _ArbitraryNumber.PrecisionCutoff) return this;
-    if (diff < -_ArbitraryNumber.PrecisionCutoff) return other;
-    let c;
-    let e;
+    if (diff > cutoff) return this;
+    if (diff < -cutoff) {
+      this.coefficient = other.coefficient;
+      this.exponent = other.exponent;
+      return this;
+    }
+    const oc = other.coefficient;
+    const oe = other.exponent;
+    let c, e;
     if (diff >= 0) {
-      c = this.coefficient + other.coefficient / pow10(diff);
+      c = this.coefficient + oc / pow10(diff);
       e = this.exponent;
     } else {
-      c = other.coefficient + this.coefficient / pow10(-diff);
-      e = other.exponent;
+      c = oc + this.coefficient / pow10(-diff);
+      e = oe;
     }
-    return _ArbitraryNumber.normalizeFrom(c, e);
+    return this._normalizeInto(c, e);
   }
   /**
-   * 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) {
     if (other.coefficient === 0) return this;
-    const negC = -other.coefficient;
-    if (this.coefficient === 0) return _ArbitraryNumber.createNormalized(negC, other.exponent);
-    const diff = this.exponent - other.exponent;
-    if (diff > _ArbitraryNumber.PrecisionCutoff) return this;
-    if (diff < -_ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(negC, other.exponent);
-    let c;
-    let e;
+    const oc = other.coefficient;
+    const oe = other.exponent;
+    const negOc = -oc;
+    if (this.coefficient === 0) {
+      this.coefficient = negOc;
+      this.exponent = oe;
+      return this;
+    }
+    const cutoff = _scaleCutoff;
+    const diff = this.exponent - oe;
+    if (diff > cutoff) return this;
+    if (diff < -cutoff) {
+      this.coefficient = negOc;
+      this.exponent = oe;
+      return this;
+    }
+    let c, e;
     if (diff >= 0) {
-      c = this.coefficient + negC / pow10(diff);
+      c = this.coefficient + negOc / pow10(diff);
       e = this.exponent;
     } else {
-      c = negC + this.coefficient / pow10(-diff);
-      e = other.exponent;
+      c = negOc + this.coefficient / pow10(-diff);
+      e = oe;
     }
-    return _ArbitraryNumber.normalizeFrom(c, e);
+    return this._normalizeInto(c, e);
   }
   /**
-   * 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) {
-    if (this.coefficient === 0 || other.coefficient === 0) return _ArbitraryNumber.Zero;
+    if (this.coefficient === 0) return this;
+    if (other.coefficient === 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return this;
+    }
     const c = this.coefficient * other.coefficient;
     const e = this.exponent + other.exponent;
     const absC = c < 0 ? -c : c;
-    if (absC >= 10) return _ArbitraryNumber.createNormalized(c / 10, e + 1);
-    return _ArbitraryNumber.createNormalized(c, e);
+    if (absC >= 10) {
+      this.coefficient = c / 10;
+      this.exponent = e + 1;
+    } else {
+      this.coefficient = c;
+      this.exponent = e;
+    }
+    return 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) {
-    if (other.coefficient === 0) throw new ArbitraryNumberDomainError("Division by zero", { dividend: this.toNumber(), divisor: 0 });
+    if (other.coefficient === 0) {
+      throw new ArbitraryNumberDomainError("Division by zero", { dividend: this.toNumber(), divisor: 0 });
+    }
+    if (this.coefficient === 0) return this;
     const c = this.coefficient / other.coefficient;
     const e = this.exponent - other.exponent;
-    if (c === 0) return _ArbitraryNumber.Zero;
+    if (c === 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return this;
+    }
     const absC = c < 0 ? -c : c;
-    if (absC < 1) return _ArbitraryNumber.createNormalized(c * 10, e - 1);
-    return _ArbitraryNumber.createNormalized(c, e);
+    if (absC < 1) {
+      this.coefficient = c * 10;
+      this.exponent = e - 1;
+    } else {
+      this.coefficient = c;
+      this.exponent = e;
+    }
+    return 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() {
-    if (this.coefficient === 0) return _ArbitraryNumber.Zero;
-    return _ArbitraryNumber.createNormalized(-this.coefficient, this.exponent);
+    this.coefficient = -this.coefficient;
+    return 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() {
-    if (this.coefficient >= 0) return this;
-    return _ArbitraryNumber.createNormalized(-this.coefficient, this.exponent);
+    if (this.coefficient < 0) this.coefficient = -this.coefficient;
+    return 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) {
     if (n === 0) {
-      return _ArbitraryNumber.One;
+      this.coefficient = 1;
+      this.exponent = 0;
+      return this;
     }
     if (this.coefficient === 0) {
       if (n < 0) {
         throw new ArbitraryNumberDomainError("Zero cannot be raised to a negative power", { exponent: n });
       }
-      return _ArbitraryNumber.Zero;
+      return this;
     }
     if (this.coefficient < 0 && !Number.isInteger(n)) {
-      throw new ArbitraryNumberDomainError("ArbitraryNumber.pow: fractional exponent of a negative base is not supported", { base: this.toNumber(), exponent: n });
+      throw new ArbitraryNumberDomainError(
+        "ArbitraryNumber.pow: fractional exponent of a negative base is not supported",
+        { base: this.toNumber(), exponent: n }
+      );
     }
     const rawExp = this.exponent * n;
     const intExp = Math.floor(rawExp);
     const fracExp = rawExp - intExp;
-    return new _ArbitraryNumber(
-      Math.pow(this.coefficient, n) * pow10(fracExp),
-      intExp
-    );
+    const newC = Math.pow(this.coefficient, n) * pow10(fracExp);
+    return this._normalizeInto(newC, intExp);
   }
   /**
-   * Fused multiply-add: `(this * multiplier) + addend`.
-   *
-   * Faster than `.mul(multiplier).add(addend)` because it avoids allocating an
-   * intermediate ArbitraryNumber for the product. One normalisation pass total.
+   * Fused multiply-add in-place: `this = (this * multiplier) + addend`.
    *
-   * Common pattern - prestige loop: `value = value.mulAdd(prestigeMultiplier, prestigeBoost)`
+   * Faster than `.mul(multiplier).add(addend)` — one normalisation pass total, no
+   * intermediate allocation.
    *
-   * @example
-   * // Equivalent to value.mul(mult).add(boost) but ~35-50% faster
-   * const prestiged = currentValue.mulAdd(multiplier, boost);
+   * **Mutates `this`. Returns `this`.**
    */
   mulAdd(multiplier, addend) {
-    if (this.coefficient === 0 || multiplier.coefficient === 0) return addend;
+    if (this.coefficient === 0 || multiplier.coefficient === 0) {
+      this.coefficient = addend.coefficient;
+      this.exponent = addend.exponent;
+      return this;
+    }
+    const ac = addend.coefficient;
+    const ae = addend.exponent;
     let cp = this.coefficient * multiplier.coefficient;
     let ep = this.exponent + multiplier.exponent;
     const absCp = cp < 0 ? -cp : cp;
@@ -306,87 +451,144 @@ var _ArbitraryNumber = class _ArbitraryNumber {
       cp /= 10;
       ep += 1;
     }
-    if (addend.coefficient === 0) return _ArbitraryNumber.createNormalized(cp, ep);
-    const diff = ep - addend.exponent;
-    if (diff > _ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(cp, ep);
-    if (diff < -_ArbitraryNumber.PrecisionCutoff) return addend;
+    if (ac === 0) {
+      this.coefficient = cp;
+      this.exponent = ep;
+      return this;
+    }
+    const cutoff = _scaleCutoff;
+    const diff = ep - ae;
+    if (diff > cutoff) {
+      this.coefficient = cp;
+      this.exponent = ep;
+      return this;
+    }
+    if (diff < -cutoff) {
+      this.coefficient = ac;
+      this.exponent = ae;
+      return this;
+    }
     let c, e;
     if (diff >= 0) {
-      c = cp + addend.coefficient / pow10(diff);
+      c = cp + ac / pow10(diff);
       e = ep;
     } else {
-      c = addend.coefficient + cp / pow10(-diff);
-      e = addend.exponent;
+      c = ac + cp / pow10(-diff);
+      e = ae;
     }
-    return _ArbitraryNumber.normalizeFrom(c, e);
+    return this._normalizeInto(c, e);
   }
   /**
-   * Fused add-multiply: `(this + addend) * multiplier`.
-   *
-   * Faster than `.add(addend).mul(multiplier)` because it avoids allocating an
-   * intermediate ArbitraryNumber for the sum. One normalisation pass total.
-   *
-   * Common pattern - upgrade calculation: `newValue = baseValue.addMul(bonus, multiplier)`
-   *
-   * @example
-   * // Equivalent to base.add(bonus).mul(multiplier) but ~20-25% faster
-   * const upgraded = baseValue.addMul(bonus, multiplier);
+   * @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.
+   *
+   * 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.
    */
-  addMul(addend, multiplier) {
-    if (multiplier.coefficient === 0) return _ArbitraryNumber.Zero;
-    let cs, es;
-    if (this.coefficient === 0 && addend.coefficient === 0) return _ArbitraryNumber.Zero;
+  _addScaledInto(addendC, addendE) {
     if (this.coefficient === 0) {
-      cs = addend.coefficient;
-      es = addend.exponent;
-    } else if (addend.coefficient === 0) {
-      cs = this.coefficient;
+      this.coefficient = addendC;
+      this.exponent = addendE;
+      return;
+    }
+    if (addendC === 0) return;
+    const cutoff = _scaleCutoff;
+    const diff = this.exponent - addendE;
+    if (diff > cutoff) return;
+    if (diff < -cutoff) {
+      this.coefficient = addendC;
+      this.exponent = addendE;
+      return;
+    }
+    let cs, es;
+    if (diff >= 0) {
+      cs = this.coefficient + addendC / pow10(diff);
       es = this.exponent;
     } else {
-      const diff = this.exponent - addend.exponent;
-      if (diff > _ArbitraryNumber.PrecisionCutoff) {
-        cs = this.coefficient;
-        es = this.exponent;
-      } else if (diff < -_ArbitraryNumber.PrecisionCutoff) {
-        cs = addend.coefficient;
-        es = addend.exponent;
-      } else {
-        if (diff >= 0) {
-          cs = this.coefficient + addend.coefficient / pow10(diff);
-          es = this.exponent;
-        } else {
-          cs = addend.coefficient + this.coefficient / pow10(-diff);
-          es = addend.exponent;
-        }
-        if (cs === 0) return _ArbitraryNumber.Zero;
-        const abs = Math.abs(cs);
-        const shift = Math.floor(Math.log10(abs));
-        const scale = pow10(shift);
-        if (scale === 0) return _ArbitraryNumber.Zero;
-        cs /= scale;
-        es += shift;
+      cs = addendC + this.coefficient / pow10(-diff);
+      es = addendE;
+    }
+    if (cs === 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return;
+    }
+    const abs = cs < 0 ? -cs : cs;
+    if (abs < 10) {
+      if (abs >= 1) {
+        this.coefficient = cs;
+        this.exponent = es;
+        return;
       }
+      this.coefficient = cs * 10;
+      this.exponent = es - 1;
+      return;
+    }
+    if (abs < 100) {
+      this.coefficient = cs / 10;
+      this.exponent = es + 1;
+      return;
     }
-    let cp = cs * multiplier.coefficient;
-    const ep = es + multiplier.exponent;
+    if (!isFinite(cs)) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return;
+    }
+    const shift = Math.floor(Math.log10(abs));
+    const scale = pow10(shift);
+    if (scale === 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return;
+    }
+    this.coefficient = cs / scale;
+    this.exponent = es + shift;
+  }
+  /**
+   * Fused add-multiply in-place: `this = (this + addend) * multiplier`.
+   *
+   * **Mutates `this`. Returns `this`.**
+   */
+  addMul(addend, multiplier) {
+    if (multiplier.coefficient === 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return this;
+    }
+    const ac = addend.coefficient;
+    const ae = addend.exponent;
+    const mc = multiplier.coefficient;
+    const me = multiplier.exponent;
+    this._addScaledInto(ac, ae);
+    if (this.coefficient === 0) return this;
+    let cp = this.coefficient * mc;
+    const ep = this.exponent + me;
     const absCp = cp < 0 ? -cp : cp;
     if (absCp >= 10) {
       cp /= 10;
-      return _ArbitraryNumber.createNormalized(cp, ep + 1);
+      this.coefficient = cp;
+      this.exponent = ep + 1;
+      return this;
     }
-    return _ArbitraryNumber.createNormalized(cp, ep);
+    this.coefficient = cp;
+    this.exponent = ep;
+    return this;
   }
   /**
-   * Fused multiply-subtract: `(this * multiplier) - subtrahend`.
-   *
-   * Avoids one intermediate allocation vs `.mul(multiplier).sub(subtrahend)`.
+   * Fused multiply-subtract in-place: `this = (this * multiplier) - subtrahend`.
    *
-   * Common pattern - resource drain: `income.mulSub(rate, upkeepCost)`
+   * **Mutates `this`. Returns `this`.**
    */
   mulSub(multiplier, subtrahend) {
+    const sc = subtrahend.coefficient;
+    const se = subtrahend.exponent;
     if (this.coefficient === 0 || multiplier.coefficient === 0) {
-      if (subtrahend.coefficient === 0) return _ArbitraryNumber.Zero;
-      return _ArbitraryNumber.createNormalized(-subtrahend.coefficient, subtrahend.exponent);
+      this.coefficient = sc === 0 ? 0 : -sc;
+      this.exponent = sc === 0 ? 0 : se;
+      return this;
     }
     let cp = this.coefficient * multiplier.coefficient;
     let ep = this.exponent + multiplier.exponent;
@@ -395,85 +597,81 @@ var _ArbitraryNumber = class _ArbitraryNumber {
       cp /= 10;
       ep += 1;
     }
-    if (subtrahend.coefficient === 0) return _ArbitraryNumber.createNormalized(cp, ep);
-    const diff = ep - subtrahend.exponent;
-    if (diff > _ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(cp, ep);
-    if (diff < -_ArbitraryNumber.PrecisionCutoff) {
-      return _ArbitraryNumber.createNormalized(-subtrahend.coefficient, subtrahend.exponent);
+    if (sc === 0) {
+      this.coefficient = cp;
+      this.exponent = ep;
+      return this;
+    }
+    const cutoff = _scaleCutoff;
+    const diff = ep - se;
+    if (diff > cutoff) {
+      this.coefficient = cp;
+      this.exponent = ep;
+      return this;
+    }
+    if (diff < -cutoff) {
+      this.coefficient = -sc;
+      this.exponent = se;
+      return this;
     }
     let c, e;
     if (diff >= 0) {
-      c = cp - subtrahend.coefficient / pow10(diff);
+      c = cp - sc / pow10(diff);
       e = ep;
     } else {
-      c = -subtrahend.coefficient + cp / pow10(-diff);
-      e = subtrahend.exponent;
+      c = -sc + cp / pow10(-diff);
+      e = se;
     }
-    return _ArbitraryNumber.normalizeFrom(c, e);
+    return this._normalizeInto(c, e);
   }
   /**
-   * Fused subtract-multiply: `(this - subtrahend) * multiplier`.
-   *
-   * Avoids one intermediate allocation vs `.sub(subtrahend).mul(multiplier)`.
+   * Fused subtract-multiply in-place: `this = (this - subtrahend) * multiplier`.
    *
-   * Common pattern - upgrade after penalty: `health.subMul(damage, multiplier)`
+   * **Mutates `this`. Returns `this`.**
    */
   subMul(subtrahend, multiplier) {
-    if (multiplier.coefficient === 0) return _ArbitraryNumber.Zero;
-    let cs, es;
-    if (this.coefficient === 0 && subtrahend.coefficient === 0) return _ArbitraryNumber.Zero;
-    if (this.coefficient === 0) {
-      cs = -subtrahend.coefficient;
-      es = subtrahend.exponent;
-    } else if (subtrahend.coefficient === 0) {
-      cs = this.coefficient;
-      es = this.exponent;
-    } else {
-      const diff = this.exponent - subtrahend.exponent;
-      if (diff > _ArbitraryNumber.PrecisionCutoff) {
-        cs = this.coefficient;
-        es = this.exponent;
-      } else if (diff < -_ArbitraryNumber.PrecisionCutoff) {
-        cs = -subtrahend.coefficient;
-        es = subtrahend.exponent;
-      } else {
-        if (diff >= 0) {
-          cs = this.coefficient - subtrahend.coefficient / pow10(diff);
-          es = this.exponent;
-        } else {
-          cs = -subtrahend.coefficient + this.coefficient / pow10(-diff);
-          es = subtrahend.exponent;
-        }
-        if (cs === 0) return _ArbitraryNumber.Zero;
-        const abs = Math.abs(cs);
-        const shift = Math.floor(Math.log10(abs));
-        const scale = pow10(shift);
-        if (scale === 0) return _ArbitraryNumber.Zero;
-        cs /= scale;
-        es += shift;
-      }
+    if (multiplier.coefficient === 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return this;
     }
-    let cp = cs * multiplier.coefficient;
-    const ep = es + multiplier.exponent;
+    const sc = subtrahend.coefficient;
+    const se = subtrahend.exponent;
+    const mc = multiplier.coefficient;
+    const me = multiplier.exponent;
+    this._addScaledInto(-sc, se);
+    if (this.coefficient === 0) return this;
+    let cp = this.coefficient * mc;
+    const ep = this.exponent + me;
     const absCp = cp < 0 ? -cp : cp;
     if (absCp >= 10) {
       cp /= 10;
-      return _ArbitraryNumber.createNormalized(cp, ep + 1);
+      this.coefficient = cp;
+      this.exponent = ep + 1;
+      return this;
     }
-    return _ArbitraryNumber.createNormalized(cp, ep);
+    this.coefficient = cp;
+    this.exponent = ep;
+    return this;
   }
   /**
-   * Fused divide-add: `(this / divisor) + addend`.
+   * Fused divide-add in-place: `this = (this / divisor) + addend`.
    *
-   * Avoids one intermediate allocation vs `.div(divisor).add(addend)`.
-   *
-   * Common pattern - efficiency bonus: `damage.divAdd(armor, flat)`
+   * **Mutates `this`. Returns `this`.**
    *
    * @throws `"Division by zero"` when divisor is zero.
    */
   divAdd(divisor, addend) {
-    if (divisor.coefficient === 0) throw new ArbitraryNumberDomainError("Division by zero", { dividend: this.toNumber(), divisor: 0 });
-    if (this.coefficient === 0) return addend;
+    if (divisor.coefficient === 0) {
+      throw new ArbitraryNumberDomainError("Division by zero", { dividend: this.toNumber(), divisor: 0 });
+    }
+    const ac = addend.coefficient;
+    const ae = addend.exponent;
+    if (this.coefficient === 0) {
+      this.coefficient = ac;
+      this.exponent = ae;
+      return this;
+    }
     let cd = this.coefficient / divisor.coefficient;
     let ed = this.exponent - divisor.exponent;
     const absC = cd < 0 ? -cd : cd;
@@ -481,69 +679,318 @@ var _ArbitraryNumber = class _ArbitraryNumber {
       cd *= 10;
       ed -= 1;
     }
-    if (addend.coefficient === 0) return _ArbitraryNumber.createNormalized(cd, ed);
-    const diff = ed - addend.exponent;
-    if (diff > _ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(cd, ed);
-    if (diff < -_ArbitraryNumber.PrecisionCutoff) return addend;
+    if (ac === 0) {
+      this.coefficient = cd;
+      this.exponent = ed;
+      return this;
+    }
+    const cutoff = _scaleCutoff;
+    const diff = ed - ae;
+    if (diff > cutoff) {
+      this.coefficient = cd;
+      this.exponent = ed;
+      return this;
+    }
+    if (diff < -cutoff) {
+      this.coefficient = ac;
+      this.exponent = ae;
+      return this;
+    }
     let c, e;
     if (diff >= 0) {
-      c = cd + addend.coefficient / pow10(diff);
+      c = cd + ac / pow10(diff);
       e = ed;
     } else {
-      c = addend.coefficient + cd / pow10(-diff);
-      e = addend.exponent;
+      c = ac + cd / pow10(-diff);
+      e = ae;
     }
-    return _ArbitraryNumber.normalizeFrom(c, e);
+    return this._normalizeInto(c, e);
   }
   /**
-   * Efficiently sums an array of ArbitraryNumbers in a single normalisation pass.
+   * Fused multiply-divide in-place: `this = (this * multiplier) / divisor`.
+   *
+   * **Mutates `this`. Returns `this`.**
    *
-   * **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.
+   * @throws `"Division by zero"` when divisor is zero.
+   */
+  mulDiv(multiplier, divisor) {
+    if (divisor.coefficient === 0) {
+      throw new ArbitraryNumberDomainError("Division by zero", { dividend: this.toNumber(), divisor: 0 });
+    }
+    if (this.coefficient === 0) return this;
+    if (multiplier.coefficient === 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return this;
+    }
+    const c = this.coefficient * multiplier.coefficient / divisor.coefficient;
+    const e = this.exponent + multiplier.exponent - divisor.exponent;
+    const absC = c < 0 ? -c : c;
+    if (absC >= 10) {
+      this.coefficient = c / 10;
+      this.exponent = e + 1;
+    } else if (absC < 1) {
+      this.coefficient = c * 10;
+      this.exponent = e - 1;
+    } else {
+      this.coefficient = c;
+      this.exponent = e;
+    }
+    return this;
+  }
+  // ── Batch (static, allocate) ───────────────────────────────────────────────
+  /**
+   * Efficiently sums an array of `ArbitraryNumber`s in a single pass.
    *
-   * For 50 elements: chained add ~ 50 log10 calls + 50 allocations;
-   * sumArray ~ 50 divisions + 1 log10 call + 1 allocation -> ~9* faster.
+   * Maintains a running pivot exponent and rescales the accumulator when a larger
+   * exponent is encountered — one pass, no pre-scan needed.
    *
-   * Common pattern - income aggregation: `total = ArbitraryNumber.sumArray(incomeSourcesPerTick)`
+   * Empty array returns `Zero`. Single element returned as-is (no clone).
+   */
+  static sumArray(numbers) {
+    const len = numbers.length;
+    if (len === 0) return _ArbitraryNumber.Zero;
+    if (len === 1) return numbers[0];
+    const cutoff = _scaleCutoff;
+    let pivot = -Infinity;
+    let total = 0;
+    for (let i = 0; i < len; i++) {
+      const n = numbers[i];
+      if (n.coefficient === 0) continue;
+      if (n.exponent > pivot) {
+        if (pivot !== -Infinity) {
+          const drop = n.exponent - pivot;
+          total = drop > cutoff ? 0 : total / pow10(drop);
+        }
+        pivot = n.exponent;
+        total += n.coefficient;
+      } else {
+        const diff = pivot - n.exponent;
+        if (diff <= cutoff) total += n.coefficient / pow10(diff);
+      }
+    }
+    if (total === 0 || pivot === -Infinity) return _ArbitraryNumber.Zero;
+    const abs = total < 0 ? -total : total;
+    if (abs < 10) {
+      if (abs >= 1) return _ArbitraryNumber.unsafe(total, pivot);
+      return _ArbitraryNumber.unsafe(total * 10, pivot - 1);
+    }
+    if (abs < 100) return _ArbitraryNumber.unsafe(total / 10, pivot + 1);
+    const shift = Math.floor(Math.log10(abs));
+    const scale = pow10(shift);
+    if (scale === 0) return _ArbitraryNumber.Zero;
+    return _ArbitraryNumber.unsafe(total / scale, pivot + shift);
+  }
+  /**
+   * Multiplies an array of `ArbitraryNumber`s in a single pass.
    *
-   * @example
-   * const total = ArbitraryNumber.sumArray(incomeSources); // far faster than .reduce((a, b) => a.add(b))
+   * Empty array returns `One`. Single element returned as-is.
+   */
+  static productArray(numbers) {
+    const len = numbers.length;
+    if (len === 0) return _ArbitraryNumber.One;
+    if (len === 1) return numbers[0];
+    let c = 1;
+    let e = 0;
+    for (let i = 0; i < len; i++) {
+      const n = numbers[i];
+      if (n.coefficient === 0) return _ArbitraryNumber.Zero;
+      c *= n.coefficient;
+      e += n.exponent;
+      if (c >= 10 || c <= -10) {
+        c /= 10;
+        e += 1;
+      }
+    }
+    return _ArbitraryNumber._normalizeNew(c, e);
+  }
+  /**
+   * Returns the largest value in an array. Empty array returns `Zero`.
+   */
+  static maxOfArray(numbers) {
+    if (numbers.length === 0) return _ArbitraryNumber.Zero;
+    let max = numbers[0];
+    for (let i = 1; i < numbers.length; i++) {
+      if (numbers[i].greaterThan(max)) max = numbers[i];
+    }
+    return max;
+  }
+  /**
+   * Returns the smallest value in an array. Empty array returns `Zero`.
+   */
+  static minOfArray(numbers) {
+    if (numbers.length === 0) return _ArbitraryNumber.Zero;
+    let min = numbers[0];
+    for (let i = 1; i < numbers.length; i++) {
+      if (numbers[i].lessThan(min)) min = numbers[i];
+    }
+    return min;
+  }
+  // ── Rounding (mutate) ──────────────────────────────────────────────────────
+  /**
+   * Rounds down to the nearest integer in-place (floor toward −∞).
+   *
+   * **Mutates `this`. Returns `this`.**
+   */
+  floor() {
+    if (this.coefficient === 0) return this;
+    if (this.exponent >= _scaleCutoff) return this;
+    if (this.exponent < 0) {
+      this.coefficient = this.coefficient >= 0 ? 0 : -1;
+      this.exponent = 0;
+      return this;
+    }
+    return this._normalizeInto(Math.floor(this.coefficient * pow10(this.exponent)), 0);
+  }
+  /**
+   * Rounds up to the nearest integer in-place (ceil toward +∞).
+   *
+   * **Mutates `this`. Returns `this`.**
+   */
+  ceil() {
+    if (this.coefficient === 0) return this;
+    if (this.exponent >= _scaleCutoff) return this;
+    if (this.exponent < 0) {
+      const ceiled = this.coefficient > 0 ? 1 : 0;
+      this.coefficient = ceiled;
+      this.exponent = 0;
+      return this;
+    }
+    return this._normalizeInto(Math.ceil(this.coefficient * pow10(this.exponent)), 0);
+  }
+  /**
+   * Rounds to the nearest integer in-place.
+   *
+   * Uses `Math.round` semantics: half-values round toward positive infinity
+   * (`0.5 → 1`, `-0.5 → 0`). This matches JavaScript's built-in convention.
+   *
+   * **Mutates `this`. Returns `this`.**
+   */
+  round() {
+    if (this.coefficient === 0) return this;
+    if (this.exponent >= _scaleCutoff) return this;
+    if (this.exponent < 0) {
+      if (this.exponent <= -2) {
+        this.coefficient = 0;
+        this.exponent = 0;
+        return this;
+      }
+      const rounded = Math.round(this.coefficient * 0.1) || 0;
+      this.coefficient = rounded;
+      this.exponent = 0;
+      return this;
+    }
+    return this._normalizeInto(Math.round(this.coefficient * pow10(this.exponent)), 0);
+  }
+  /**
+   * Truncates toward zero in-place.
+   *
+   * **Mutates `this`. Returns `this`.**
+   */
+  trunc() {
+    if (this.coefficient === 0) return this;
+    if (this.exponent >= _scaleCutoff) return this;
+    if (this.exponent < 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return this;
+    }
+    return this._normalizeInto(Math.trunc(this.coefficient * pow10(this.exponent)), 0);
+  }
+  // ── Roots & logs ───────────────────────────────────────────────────────────
+  /**
+   * Returns √this in-place.
+   *
+   * **Mutates `this`. Returns `this`.**
+   *
+   * @throws `"Square root of negative number"` when this is negative.
+   */
+  sqrt() {
+    if (this.coefficient < 0) {
+      throw new ArbitraryNumberDomainError("Square root of negative number", { value: this.toNumber() });
+    }
+    if (this.coefficient === 0) return this;
+    if (this.exponent % 2 !== 0) {
+      this.coefficient = Math.sqrt(this.coefficient * 10);
+      this.exponent = (this.exponent - 1) / 2;
+    } else {
+      this.coefficient = Math.sqrt(this.coefficient);
+      this.exponent = this.exponent / 2;
+    }
+    return this;
+  }
+  /**
+   * Returns ∛this in-place.
+   *
+   * **Mutates `this`. Returns `this`.**
+   */
+  cbrt() {
+    if (this.coefficient === 0) return this;
+    const rem = (this.exponent % 3 + 3) % 3;
+    const baseExp = (this.exponent - rem) / 3;
+    if (rem === 0) {
+      this.coefficient = Math.cbrt(this.coefficient);
+      this.exponent = baseExp;
+    } else if (rem === 1) {
+      this.coefficient = Math.cbrt(this.coefficient * 10);
+      this.exponent = baseExp;
+    } else {
+      this.coefficient = Math.cbrt(this.coefficient * 100);
+      this.exponent = baseExp;
+    }
+    return 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() {
+    if (this.coefficient === 0) {
+      throw new ArbitraryNumberDomainError("Logarithm of zero is undefined", { value: 0 });
+    }
+    if (this.coefficient < 0) {
+      throw new ArbitraryNumberDomainError("Logarithm of a negative number is undefined", { value: this.toNumber() });
+    }
+    return Math.log10(this.coefficient) + this.exponent;
+  }
+  /**
+   * 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) {
+    if (base <= 0 || base === 1 || !isFinite(base)) {
+      throw new ArbitraryNumberDomainError("Logarithm base must be positive and not 1", { base });
+    }
+    return this.log10() / Math.log10(base);
+  }
+  /**
+   * Returns `ln(this)` as a plain `number`.
+   */
+  ln() {
+    return this.log10() / Math.LOG10E;
+  }
+  /**
+   * Returns `10^n` as a new `ArbitraryNumber`.
    *
-   * @param numbers - Array to sum. Empty array returns {@link Zero}. Single element returned as-is.
+   * @throws `"ArbitraryNumber.exp10: n must be finite"` for non-finite `n`.
    */
-  static sumArray(numbers) {
-    const len = numbers.length;
-    if (len === 0) return _ArbitraryNumber.Zero;
-    if (len === 1) return numbers[0];
-    let pivotExp = numbers[0].exponent;
-    for (let i = 1; i < len; i++) {
-      const n = numbers[i];
-      if (n.exponent > pivotExp) pivotExp = n.exponent;
-    }
-    let total = 0;
-    for (let i = 0; i < len; i++) {
-      const n = numbers[i];
-      if (n.coefficient === 0) continue;
-      const diff = pivotExp - n.exponent;
-      if (diff > _ArbitraryNumber.PrecisionCutoff) continue;
-      total += n.coefficient / pow10(diff);
+  static exp10(n) {
+    if (!isFinite(n)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.exp10: n must be finite", n);
     }
-    if (total === 0) return _ArbitraryNumber.Zero;
-    const abs = Math.abs(total);
-    const shift = Math.floor(Math.log10(abs));
-    const scale = pow10(shift);
-    if (scale === 0) return _ArbitraryNumber.Zero;
-    return _ArbitraryNumber.createNormalized(total / scale, pivotExp + shift);
+    const intPart = Math.floor(n);
+    const fracPart = n - intPart;
+    return _ArbitraryNumber.unsafe(Math.pow(10, fracPart), intPart);
   }
+  // ── Comparisons (read-only) ────────────────────────────────────────────────
   /**
    * 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) {
     const thisNegative = this.coefficient < 0;
@@ -554,8 +1001,8 @@ var _ArbitraryNumber = class _ArbitraryNumber {
     if (this.exponent !== other.exponent) {
       if (this.coefficient === 0) return otherNegative ? 1 : -1;
       if (other.coefficient === 0) return thisNegative ? -1 : 1;
-      const thisExponentIsHigher = this.exponent > other.exponent;
-      return thisNegative ? thisExponentIsHigher ? -1 : 1 : thisExponentIsHigher ? 1 : -1;
+      const thisExpHigher = this.exponent > other.exponent;
+      return thisNegative ? thisExpHigher ? -1 : 1 : thisExpHigher ? 1 : -1;
     }
     if (this.coefficient !== other.coefficient) {
       return this.coefficient > other.coefficient ? 1 : -1;
@@ -582,375 +1029,288 @@ var _ArbitraryNumber = class _ArbitraryNumber {
   equals(other) {
     return this.compareTo(other) === 0;
   }
+  // ── Clamp / min / max (static, allocate) ──────────────────────────────────
   /**
-   * 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() {
-    if (this.coefficient === 0) {
-      return _ArbitraryNumber.Zero;
-    }
-    if (this.exponent >= _ArbitraryNumber.PrecisionCutoff) {
-      return this;
-    }
-    if (this.exponent < 0) {
-      return this.coefficient >= 0 ? _ArbitraryNumber.Zero : new _ArbitraryNumber(-1, 0);
-    }
-    return new _ArbitraryNumber(Math.floor(this.coefficient * pow10(this.exponent)), 0);
-  }
-  /**
-   * 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
-   */
-  ceil() {
-    if (this.coefficient === 0) {
-      return _ArbitraryNumber.Zero;
-    }
-    if (this.exponent >= _ArbitraryNumber.PrecisionCutoff) {
-      return this;
-    }
-    if (this.exponent < 0) {
-      return this.coefficient > 0 ? _ArbitraryNumber.One : _ArbitraryNumber.Zero;
-    }
-    return new _ArbitraryNumber(Math.ceil(this.coefficient * pow10(this.exponent)), 0);
-  }
-  /**
-   * 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])
-   *
-   * @param value - The value to clamp.
-   * @param min - Lower bound (inclusive).
-   * @param max - Upper bound (inclusive).
+   * Clamps `value` to the inclusive range `[min, max]`. Returns one of the three
+   * inputs (no allocation).
    */
   static clamp(value, min, max) {
     if (value.lessThan(min)) return min;
     if (value.greaterThan(max)) return max;
     return value;
   }
-  /**
-   * Returns the smaller of `a` and `b`.
-   * @example ArbitraryNumber.min(a, b)
-   */
+  /** Returns the smaller of `a` and `b`. */
   static min(a, b) {
     return a.lessThan(b) ? a : b;
   }
-  /**
-   * Returns the larger of `a` and `b`.
-   * @example ArbitraryNumber.max(a, b)
-   */
+  /** Returns the larger of `a` and `b`. */
   static max(a, b) {
     return a.greaterThan(b) ? a : b;
   }
   /**
-   * Linear interpolation: `a + (b - a) * t` where `t in [0, 1]` is a plain number.
+   * Linear interpolation: `a + (b - a) * t`.
    *
-   * 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 `a` unchanged when `t === 0`, `b` unchanged when `t === 1`.
+   * All other values of `t` allocate and return a fresh instance.
    */
   static lerp(a, b, t) {
     if (t === 0) return a;
     if (t === 1) return b;
-    return a.add(b.sub(a).mul(_ArbitraryNumber.from(t)));
+    return a.clone().add(b.clone().sub(a).mul(_ArbitraryNumber.from(t)));
   }
   /**
-   * Runs `fn` with `PrecisionCutoff` temporarily set to `cutoff`, then restores the previous 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));
+   * Runs `fn` with `defaults.scaleCutoff` temporarily set to `cutoff`, then restores it.
    */
   static withPrecision(cutoff, fn) {
-    const prev = _ArbitraryNumber.PrecisionCutoff;
-    _ArbitraryNumber.PrecisionCutoff = cutoff;
+    const prev = _ArbitraryNumber.defaults.scaleCutoff;
+    _ArbitraryNumber.defaults.scaleCutoff = cutoff;
+    _scaleCutoff = cutoff;
     try {
       return fn();
     } finally {
-      _ArbitraryNumber.PrecisionCutoff = prev;
+      _ArbitraryNumber.defaults.scaleCutoff = prev;
+      _scaleCutoff = prev;
     }
   }
+  // ── Predicates (read-only) ─────────────────────────────────────────────────
+  /** Returns `true` when this number is zero. */
+  isZero() {
+    return this.coefficient === 0;
+  }
+  /** Returns `true` when this number is strictly positive. */
+  isPositive() {
+    return this.coefficient > 0;
+  }
+  /** Returns `true` when this number is strictly negative. */
+  isNegative() {
+    return this.coefficient < 0;
+  }
   /**
-   * 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
+   * Returns `true` when this number has no fractional part.
+   * Numbers with `exponent >= scaleCutoff` are always considered integers.
+   */
+  isInteger() {
+    if (this.coefficient === 0) return true;
+    if (this.exponent >= _scaleCutoff) return true;
+    if (this.exponent < 0) return false;
+    return Number.isInteger(this.coefficient * pow10(this.exponent));
+  }
+  /**
+   * Returns `1` if positive, `-1` if negative, `0` if zero.
+   */
+  sign() {
+    return Math.sign(this.coefficient);
+  }
+  // ── Freeze ─────────────────────────────────────────────────────────────────
+  /**
+   * Returns a `FrozenArbitraryNumber` wrapping the same value.
    *
-   * @throws `"Logarithm of zero is undefined"` when this is zero.
-   * @throws `"Logarithm of a negative number is undefined"` when this is negative.
+   * Mutating methods on the frozen instance throw `ArbitraryNumberMutationError`.
+   * Call `.clone()` on the frozen instance to get a fresh, mutable copy.
    */
-  log10() {
-    if (this.coefficient === 0) {
-      throw new ArbitraryNumberDomainError("Logarithm of zero is undefined", { value: 0 });
-    }
-    if (this.coefficient < 0) {
-      throw new ArbitraryNumberDomainError("Logarithm of a negative number is undefined", { value: this.toNumber() });
-    }
-    return Math.log10(this.coefficient) + this.exponent;
+  freeze() {
+    return new FrozenArbitraryNumber(this.coefficient, this.exponent);
   }
+  // ── Serialization ──────────────────────────────────────────────────────────
   /**
-   * Returns √this.
+   * Converts to a plain JavaScript `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)`.
+   * Returns `Infinity` for exponents beyond float64 range (>=308).
+   * Returns `0` for exponents below float64 range (<=-324).
+   */
+  toNumber() {
+    return this.coefficient * pow10(this.exponent);
+  }
+  /**
+   * Returns a stable, minimal JSON representation: `{ c: number, e: number }`.
    *
-   * @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() {
-    if (this.coefficient < 0) throw new ArbitraryNumberDomainError("Square root of negative number", { value: this.toNumber() });
-    if (this.coefficient === 0) return _ArbitraryNumber.Zero;
-    if (this.exponent % 2 !== 0) {
-      return _ArbitraryNumber.createNormalized(Math.sqrt(this.coefficient * 10), (this.exponent - 1) / 2);
-    }
-    return _ArbitraryNumber.createNormalized(Math.sqrt(this.coefficient), this.exponent / 2);
+  toJSON() {
+    return { c: this.coefficient, e: this.exponent };
   }
   /**
-   * 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() {
-    if (this.coefficient === 0) return _ArbitraryNumber.Zero;
-    if (this.exponent >= _ArbitraryNumber.PrecisionCutoff) return this;
-    if (this.exponent < 0) {
-      if (this.exponent <= -2) return _ArbitraryNumber.Zero;
-      const rounded = Math.round(this.coefficient * 0.1);
-      return rounded === 0 ? _ArbitraryNumber.Zero : new _ArbitraryNumber(rounded, 0);
-    }
-    return new _ArbitraryNumber(Math.round(this.coefficient * pow10(this.exponent)), 0);
+  toRawString() {
+    return `${this.coefficient}|${this.exponent}`;
   }
   /**
-   * 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() {
-    return Math.sign(this.coefficient);
+  static fromJSON(obj) {
+    if (obj === null || typeof obj !== "object" || !("c" in obj) || !("e" in obj) || typeof obj.c !== "number" || typeof obj.e !== "number") {
+      throw new ArbitraryNumberInputError(
+        "ArbitraryNumber.fromJSON: expected { c: number, e: number }",
+        String(obj)
+      );
+    }
+    const { c, e } = obj;
+    if (!isFinite(c)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.fromJSON: c must be finite", c);
+    }
+    if (!isFinite(e)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.fromJSON: e must be finite", e);
+    }
+    return _ArbitraryNumber._normalizeNew(c, e);
   }
   /**
-   * 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() {
-    return this.coefficient * pow10(this.exponent);
-  }
-  /** Returns `true` when this number is zero. */
-  isZero() {
-    return this.coefficient === 0;
-  }
-  /** Returns `true` when this number is strictly positive. */
-  isPositive() {
-    return this.coefficient > 0;
-  }
-  /** Returns `true` when this number is strictly negative. */
-  isNegative() {
-    return this.coefficient < 0;
+  static parse(s) {
+    if (typeof s !== "string" || s.trim() === "") {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.parse: input must be a non-empty string", s);
+    }
+    const trimmed = s.trim();
+    const pipeIdx = trimmed.indexOf("|");
+    if (pipeIdx !== -1) {
+      const cStr = trimmed.slice(0, pipeIdx);
+      const eStr = trimmed.slice(pipeIdx + 1);
+      const c = Number(cStr);
+      const e = Number(eStr);
+      if (!isFinite(c) || !isFinite(e) || cStr === "" || eStr === "") {
+        throw new ArbitraryNumberInputError("ArbitraryNumber.parse: invalid pipe format", s);
+      }
+      return _ArbitraryNumber._normalizeNew(c, e);
+    }
+    const n = Number(trimmed);
+    if (!isFinite(n)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.parse: value is not finite", s);
+    }
+    return new _ArbitraryNumber(n, 0);
   }
+  // ── String coercion ────────────────────────────────────────────────────────
   /**
-   * 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() {
-    if (this.coefficient === 0) return true;
-    if (this.exponent >= _ArbitraryNumber.PrecisionCutoff) return true;
-    if (this.exponent < 0) return false;
-    return Number.isInteger(this.coefficient * pow10(this.exponent));
+  [Symbol.toPrimitive](hint) {
+    return hint === "number" ? this.toNumber() : this.toString();
+  }
+  /** Custom Node.js inspect output so `console.log(an(1500))` renders `"1.50e+3"`. */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
   }
   /**
    * 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 = scientificNotation, decimals = 2) {
+  toString(notation = scientificNotation, decimals = _ArbitraryNumber.defaults.notationDecimals) {
     return notation.format(this.coefficient, this.exponent, decimals);
   }
 };
-/**
- * Precision cutoff: exponent-difference threshold below which the smaller operand
- * is negligible and silently skipped during addition/subtraction.
- *
- * When |exponent_diff| > PrecisionCutoff, the smaller operand contributes less than
- * 10^-PrecisionCutoff of the result - below float64 coefficient precision for the default of 15.
- *
- * 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).
- *
- * Override globally via assignment, or use {@link withPrecision} for a scoped block.
- */
-_ArbitraryNumber.PrecisionCutoff = 15;
-/** The additive identity: `0`. */
+/** Global tunables. Mutating these is a process-level change. */
+_ArbitraryNumber.defaults = {
+  scaleCutoff: 15,
+  notationDecimals: 2
+};
+/** The additive identity: `0`. Frozen — calling mutating methods throws. */
 _ArbitraryNumber.Zero = new _ArbitraryNumber(0, 0);
-/** The multiplicative identity: `1`. */
+/** The multiplicative identity: `1`. Frozen — calling mutating methods throws. */
 _ArbitraryNumber.One = new _ArbitraryNumber(1, 0);
-/** `10`. */
+/** `10`. Frozen — calling mutating methods throws. */
 _ArbitraryNumber.Ten = new _ArbitraryNumber(1, 1);
 var ArbitraryNumber = _ArbitraryNumber;
-
-// src/core/an.ts
-var createAn = ((coefficient, exponent = 0) => new ArbitraryNumber(coefficient, exponent));
-createAn.from = (value) => ArbitraryNumber.from(value);
-var an = createAn;
-
-// src/core/AnChain.ts
-var AnChain = class _AnChain {
-  constructor(start) {
-    this.value = start;
+var FrozenArbitraryNumber = class extends ArbitraryNumber {
+  /** @internal */
+  constructor(coefficient, exponent) {
+    super(0, 0);
+    this.coefficient = coefficient;
+    this.exponent = exponent;
   }
-  // ── Construction ────────────────────────────────────────────────────
-  /** Creates an `AnChain` from an `ArbitraryNumber` or a plain `number`. */
-  static from(value) {
-    if (value instanceof ArbitraryNumber) return new _AnChain(value);
-    return new _AnChain(ArbitraryNumber.from(value));
+  _throwMutation(method) {
+    throw new ArbitraryNumberMutationError(
+      `Cannot call mutating method '${method}' on a frozen ArbitraryNumber`
+    );
   }
-  // ── Arithmetic ───────────────────────────────────────────────────────
-  /** Adds `other` to the accumulated value. */
-  add(other) {
-    this.value = this.value.add(other);
-    return this;
+  // Every public mutating method on ArbitraryNumber must have an override here.
+  // If you add a new mutating method above, add a matching override below.
+  add(_other) {
+    this._throwMutation("add");
   }
-  /** Subtracts `other` from the accumulated value. */
-  sub(other) {
-    this.value = this.value.sub(other);
-    return this;
+  sub(_other) {
+    this._throwMutation("sub");
   }
-  /** Multiplies the accumulated value by `other`. */
-  mul(other) {
-    this.value = this.value.mul(other);
-    return this;
+  mul(_other) {
+    this._throwMutation("mul");
   }
-  /** Divides the accumulated value by `other`. */
-  div(other) {
-    this.value = this.value.div(other);
-    return this;
+  div(_other) {
+    this._throwMutation("div");
   }
-  /** Raises the accumulated value to `exp`. */
-  pow(exp) {
-    this.value = this.value.pow(exp);
-    return this;
+  negate() {
+    this._throwMutation("negate");
   }
-  // ── Fused (avoids one intermediate allocation per call) ──────────────
-  /** `(this * mult) + add` */
-  mulAdd(mult, add) {
-    this.value = this.value.mulAdd(mult, add);
-    return this;
+  abs() {
+    this._throwMutation("abs");
   }
-  /** `(this + add) * mult` */
-  addMul(add, mult) {
-    this.value = this.value.addMul(add, mult);
-    return this;
+  pow(_n) {
+    this._throwMutation("pow");
   }
-  /** `(this * mult) - sub` */
-  mulSub(mult, sub) {
-    this.value = this.value.mulSub(mult, sub);
-    return this;
+  mulAdd(_m, _a) {
+    this._throwMutation("mulAdd");
   }
-  /** `(this - sub) * mult` */
-  subMul(sub, mult) {
-    this.value = this.value.subMul(sub, mult);
-    return this;
+  addMul(_a, _m) {
+    this._throwMutation("addMul");
   }
-  /** `(this / div) + add` */
-  divAdd(div, add) {
-    this.value = this.value.divAdd(div, add);
-    return this;
+  mulSub(_m, _s) {
+    this._throwMutation("mulSub");
   }
-  // ── Unary ────────────────────────────────────────────────────────────
-  /** Absolute value. */
-  abs() {
-    this.value = this.value.abs();
-    return this;
+  subMul(_s, _m) {
+    this._throwMutation("subMul");
   }
-  /** Negates the accumulated value. */
-  neg() {
-    this.value = this.value.negate();
-    return this;
+  divAdd(_d, _a) {
+    this._throwMutation("divAdd");
   }
-  /** Square root of the accumulated value. */
-  sqrt() {
-    this.value = this.value.sqrt();
-    return this;
+  mulDiv(_m, _d) {
+    this._throwMutation("mulDiv");
   }
-  /** Rounds down to the nearest integer. */
   floor() {
-    this.value = this.value.floor();
-    return this;
+    this._throwMutation("floor");
   }
-  /** Rounds up to the nearest integer. */
   ceil() {
-    this.value = this.value.ceil();
-    return this;
+    this._throwMutation("ceil");
   }
-  /** Rounds to the nearest integer. */
   round() {
-    this.value = this.value.round();
-    return this;
+    this._throwMutation("round");
+  }
+  trunc() {
+    this._throwMutation("trunc");
   }
-  // ── Terminal ─────────────────────────────────────────────────────────
-  /** Returns the accumulated `ArbitraryNumber` result. */
-  done() {
-    return this.value;
+  sqrt() {
+    this._throwMutation("sqrt");
+  }
+  cbrt() {
+    this._throwMutation("cbrt");
   }
 };
-function chain(value) {
-  return AnChain.from(value);
-}
+ArbitraryNumber.Zero = new FrozenArbitraryNumber(0, 0);
+ArbitraryNumber.One = new FrozenArbitraryNumber(1, 0);
+ArbitraryNumber.Ten = new FrozenArbitraryNumber(1, 1);
+
+// src/core/an.ts
+var createAn = ((coefficient, exponent = 0) => new ArbitraryNumber(coefficient, exponent));
+createAn.from = (value) => ArbitraryNumber.from(value);
+var an = createAn;
 
 // src/core/AnFormula.ts
 var AnFormula = class _AnFormula {
-  /**
-   * Prefer the {@link formula} factory function over calling this directly.
-   */
+  /** Prefer the {@link formula} factory function over calling this directly. */
   constructor(name, steps = []) {
     this._name = name;
     this.steps = steps;
@@ -961,18 +1321,10 @@ var AnFormula = class _AnFormula {
   }
   /**
    * 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) {
     return new _AnFormula(name, this.steps);
   }
-  // ── Private helper ────────────────────────────────────────────────────────
   step(fn) {
     return new _AnFormula(this._name, [...this.steps, fn]);
   }
@@ -997,7 +1349,7 @@ var AnFormula = class _AnFormula {
   pow(exp) {
     return this.step((v) => v.pow(exp));
   }
-  // ── Fused (avoids one intermediate allocation per call) ───────────────────
+  // ── Fused ─────────────────────────────────────────────────────────────────
   /** Appends `(value * mult) + add` to the pipeline. */
   mulAdd(mult, add) {
     return this.step((v) => v.mulAdd(mult, add));
@@ -1023,7 +1375,7 @@ var AnFormula = class _AnFormula {
   abs() {
     return this.step((v) => v.abs());
   }
-  /** Appends `neg()` to the pipeline. */
+  /** Appends `negate()` to the pipeline. */
   neg() {
     return this.step((v) => v.negate());
   }
@@ -1048,34 +1400,39 @@ var AnFormula = 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) {
     return new _AnFormula(this._name, [...this.steps, ...next.steps]);
   }
   // ── Terminal ──────────────────────────────────────────────────────────────
   /**
-   * 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) {
-    let result = value instanceof ArbitraryNumber ? value : ArbitraryNumber.from(value);
+    const result = value instanceof ArbitraryNumber ? value.clone() : ArbitraryNumber.from(value);
     for (const step of this.steps) {
-      result = step(result);
+      step(result);
     }
     return result;
   }
+  /**
+   * 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) {
+    for (const step of this.steps) {
+      step(value);
+    }
+  }
 };
 function formula(name) {
   return new AnFormula(name, []);
@@ -1103,7 +1460,7 @@ var SuffixNotationBase = class {
    */
   format(coefficient, exponent, decimals) {
     if (exponent < 0) {
-      return (coefficient * Math.pow(10, exponent)).toFixed(decimals);
+      return (coefficient / pow10(-exponent)).toFixed(decimals);
     }
     const tier = Math.floor(exponent / 3);
     const remainder = exponent - tier * 3;
@@ -1118,6 +1475,7 @@ var SuffixNotationBase = class {
 function alphabetSuffix(tier, alphabet = "abcdefghijklmnopqrstuvwxyz") {
   if (alphabet.length === 0) throw new ArbitraryNumberInputError("alphabet must not be empty", alphabet);
   if (tier <= 0) return "";
+  if (alphabet.length === 1) return alphabet.repeat(tier);
   const index = tier - 1;
   let length = 1;
   let capacity = alphabet.length;
@@ -1276,21 +1634,40 @@ var UnitNotation = class extends SuffixNotationBase {
   /**
    * @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) {
     super({ separator: " ", ...options });
     this.units = options.units;
     this.fallback = options.fallback;
+    this.offsetFallback = options.offsetFallback !== false;
+    let last = 0;
+    for (let i = options.units.length - 1; i >= 0; i--) {
+      if (options.units[i] !== void 0) {
+        last = i;
+        break;
+      }
+    }
+    this.lastDefinedTier = last;
   }
   /**
    * 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.
    */
   getSuffix(tier) {
-    return this.units[tier]?.symbol ?? this.fallback?.getSuffix(tier) ?? "";
+    const ownSymbol = this.units[tier]?.symbol;
+    if (ownSymbol !== void 0) return ownSymbol;
+    if (this.fallback === void 0) return "";
+    const fallbackTier = this.offsetFallback ? tier - this.lastDefinedTier : tier;
+    return this.fallback.getSuffix(fallbackTier) ?? "";
   }
 };
 var unitNotation = new UnitNotation({
@@ -1310,19 +1687,13 @@ var ArbitraryNumberGuard = class _ArbitraryNumberGuard {
     return obj instanceof 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) {
-    return obj != null && typeof obj?.coefficient === "number" && typeof obj?.exponent === "number";
+    return obj != null && typeof obj.coefficient === "number" && typeof obj.exponent === "number";
   }
   /**
    * Returns `true` if `obj` is an {@link ArbitraryNumber} with a value of zero.
@@ -1335,103 +1706,14 @@ var ArbitraryNumberGuard = class _ArbitraryNumberGuard {
   }
 };
 
-// src/utility/ArbitraryNumberOps.ts
-var ArbitraryNumberOps = 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) {
-    return value instanceof ArbitraryNumber ? value : ArbitraryNumber.from(value);
-  }
-  /**
-   * 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, right) {
-    return _ArbitraryNumberOps.from(left).add(_ArbitraryNumberOps.from(right));
-  }
-  /**
-   * 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, right) {
-    return _ArbitraryNumberOps.from(left).sub(_ArbitraryNumberOps.from(right));
-  }
-  /**
-   * 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, right) {
-    return _ArbitraryNumberOps.from(left).mul(_ArbitraryNumberOps.from(right));
-  }
-  /**
-   * 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, right) {
-    return _ArbitraryNumberOps.from(left).div(_ArbitraryNumberOps.from(right));
-  }
-  /**
-   * 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, right) {
-    return _ArbitraryNumberOps.from(left).compareTo(_ArbitraryNumberOps.from(right));
-  }
-  /**
-   * 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, min, max) {
-    return ArbitraryNumber.clamp(
-      _ArbitraryNumberOps.from(value),
-      _ArbitraryNumberOps.from(min),
-      _ArbitraryNumberOps.from(max)
-    );
-  }
-};
-
 // src/utility/ArbitraryNumberHelpers.ts
 var ArbitraryNumberHelpers = class _ArbitraryNumberHelpers {
   static coerce(value) {
-    return ArbitraryNumberOps.from(value);
+    return value instanceof ArbitraryNumber ? value : ArbitraryNumber.from(value);
   }
   /**
    * 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)
    */
@@ -1443,9 +1725,6 @@ var ArbitraryNumberHelpers = 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);
@@ -1459,15 +1738,11 @@ var ArbitraryNumberHelpers = class _ArbitraryNumberHelpers {
     if (numTotal.lessThanOrEqual(ArbitraryNumber.Zero)) {
       return ArbitraryNumber.Zero;
     }
-    return numTotal.div(numStep).floor();
+    return numTotal.clone().div(numStep).floor();
   }
   /**
    * 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);
    */
@@ -1475,10 +1750,11 @@ var ArbitraryNumberHelpers = class _ArbitraryNumberHelpers {
     const numValue = _ArbitraryNumberHelpers.coerce(value);
     const numDelta = _ArbitraryNumberHelpers.coerce(delta);
     const numFloor = _ArbitraryNumberHelpers.coerce(floor);
-    return ArbitraryNumber.clamp(numValue.sub(numDelta), numFloor, numValue);
+    const result = numValue.clone().sub(numDelta);
+    return result.lessThan(numFloor) ? numFloor : result;
   }
 };
 
-export { AlphabetNotation, AnChain, AnFormula, ArbitraryNumber, ArbitraryNumberDomainError, ArbitraryNumberError, ArbitraryNumberGuard, ArbitraryNumberHelpers, ArbitraryNumberInputError, ArbitraryNumberOps, CLASSIC_UNITS, COMPACT_UNITS, ScientificNotation, SuffixNotationBase, UnitNotation, alphabetSuffix, an, chain, formula, ArbitraryNumberGuard as guard, ArbitraryNumberHelpers as helpers, letterNotation, ArbitraryNumberOps as ops, scientificNotation, unitNotation };
+export { AlphabetNotation, AnFormula, ArbitraryNumber, ArbitraryNumberDomainError, ArbitraryNumberError, ArbitraryNumberGuard, ArbitraryNumberHelpers, ArbitraryNumberInputError, ArbitraryNumberMutationError, CLASSIC_UNITS, COMPACT_UNITS, FrozenArbitraryNumber, ScientificNotation, SuffixNotationBase, UnitNotation, alphabetSuffix, an, formula, ArbitraryNumberGuard as guard, ArbitraryNumberHelpers as helpers, letterNotation, scientificNotation, unitNotation };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map