roll-parser 3.0.0-beta.0 → 3.1.0

package/src/rng/seeded.ts

@@ -1,128 +1,365 @@
 /**
- * Seedable RNG using xorshift128 algorithm.
+ * Seedable RNG using the xoshiro128** algorithm.
  *
  * @module rng/seeded
  */
 
+import { RollParserError } from '../errors.js';
 import type { RNG } from './types.js';
 
 /**
- * Seedable pseudo-random number generator using xorshift128.
+ * A snapshot of {@link SeededRNG}'s internal state: a format version followed
+ * by the four state words as unsigned 32-bit integers. Pass one back to the
+ * constructor to resume the exact sequence it was taken from.
  *
- * Produces reproducible sequences from identical seeds.
- * Period: 2^128 - 1
+ * Opaque and bound to the major version, the same contract seeds carry: the
+ * words mean nothing outside the engine that produced them, and a release that
+ * changes that engine bumps the leading version. A snapshot from a different
+ * version is rejected with an `INCOMPATIBLE_RNG_STATE` error rather than
+ * resumed under the wrong semantics — safe to hold in memory or serialize for
+ * a save file, and loud rather than silent across an upgrade.
+ *
+ * @category RNG
+ */
+export type RngState = readonly [version: number, s0: number, s1: number, s2: number, s3: number];
+
+/**
+ * Format version stamped into every {@link RngState}. Bumped by any change to
+ * the engine or the word layout, which is what makes a stale snapshot
+ * detectable instead of silently divergent.
+ */
+const RNG_STATE_VERSION = 1;
+
+/** Length of an {@link RngState}: the version word plus four state words. */
+const RNG_STATE_LENGTH = 5;
+
+/**
+ * Rotates the low 32 bits of `value` left by `bits`, returning a signed int32.
+ * Callers that need the unsigned reading apply `>>> 0` themselves.
+ */
+const rotl = (value: number, bits: number): number => (value << bits) | (value >>> (32 - bits));
+
+/**
+ * Draws discarded after seeding. cyrb128's four outputs are XOR-derived from
+ * one another, so a short run-in is a cheap hedge against that correlation
+ * surfacing in the first draws.
+ */
+const WARMUP_DRAWS = 8;
+
+/** 2^32 — the size of the uint32 output space. */
+const UINT32_SPACE = 0x100000000;
+
+/** 2^53 — the widest integer JavaScript numbers represent exactly. */
+const MAX_EXACT_INT = 2 ** 53;
+
+/** 2^21 — shift applied to the high draw when composing a 53-bit value. */
+const HIGH_DRAW_SCALE = 0x200000;
+
+/** Bits discarded from the low draw so the two draws total 53 bits. */
+const LOW_DRAW_SHIFT = 11;
+
+/** cyrb128 offset basis — one per output word. */
+const CYRB128_BASIS_1 = 1779033703;
+const CYRB128_BASIS_2 = 3144134277;
+const CYRB128_BASIS_3 = 1013904242;
+const CYRB128_BASIS_4 = 2773480762;
+
+/** xoshiro128** output-scrambler multipliers and rotations. */
+const SCRAMBLE_MULTIPLIER_1 = 5;
+const SCRAMBLE_ROTATION = 7;
+const SCRAMBLE_MULTIPLIER_2 = 9;
+
+/** xoshiro128** state-transition shift and rotation. */
+const STATE_SHIFT = 9;
+const STATE_ROTATION = 11;
+
+/** cyrb128 mixing multipliers — one per output word. */
+const CYRB128_MULTIPLIER_1 = 597399067;
+const CYRB128_MULTIPLIER_2 = 2869860233;
+const CYRB128_MULTIPLIER_3 = 951274213;
+const CYRB128_MULTIPLIER_4 = 2716044179;
+
+/**
+ * Rejects a snapshot this engine cannot resume — restoring foreign words would
+ * continue a stream that never existed.
+ *
+ * @throws {RollParserError} `INCOMPATIBLE_RNG_STATE` if the snapshot is not a
+ * current-version {@link RngState}
+ */
+function assertRestorable(state: RngState): void {
+  if (state.length !== RNG_STATE_LENGTH) {
+    throw new RollParserError(
+      `Incompatible RngState: expected ${RNG_STATE_LENGTH} values, received ${state.length}`,
+      'INCOMPATIBLE_RNG_STATE',
+    );
+  }
+
+  if (state[0] !== RNG_STATE_VERSION) {
+    throw new RollParserError(
+      `Incompatible RngState version: expected ${RNG_STATE_VERSION}, received ${state[0]}`,
+      'INCOMPATIBLE_RNG_STATE',
+    );
+  }
+}
+
+/**
+ * Seedable pseudo-random number generator using xoshiro128**. The default
+ * randomness source — `roll(notation)` builds one per call, and
+ * `roll(notation, { seed })` builds one from your seed.
+ *
+ * Period 2^128 - 1. Every seed is stringified and hashed with cyrb128 into
+ * the full 128-bit state, so numeric seeds keep all 53 bits and unrelated
+ * strings are overwhelmingly unlikely to share a state; an omitted seed hashes
+ * `Date.now()` together with two `Math.random()` draws, roughly 100 bits of
+ * width rather than 32 — wide enough that concurrently created generators are
+ * very unlikely to collide, though unpredictability stays bounded by the host
+ * engine's `Math.random()` seeding. The first 8 draws are discarded as a run-in.
+ *
+ * Stringifying means `42` and `'42'` are the same seed — the two forms share
+ * one namespace, which matters when seeds arrive from a CLI flag or JSON.
+ *
+ * {@link state} snapshots the state words as a versioned {@link RngState}, and
+ * passing one to the constructor resumes that exact sequence — restore copies
+ * the words verbatim, skipping both the hash and the run-in. A snapshot from
+ * another format version throws `INCOMPATIBLE_RNG_STATE`; within the current
+ * version the type is the contract, and a hand-built tuple is coerced to 32
+ * bits per word rather than rejected.
+ *
+ * Reproducibility guarantee: the same seed and the same notation produce the
+ * same dice for the lifetime of a major version, and `RngState` carries that
+ * binding. The one exception is a genuine distribution bug — bias, faulty
+ * rejection sampling — which may change the mapping in a minor release, never
+ * silently in a patch, and always with a `BREAKING` changelog note. The
+ * sequence is *not* cryptographically secure. To pin a roll beyond that,
+ * persist the {@link RollResult} rather than re-deriving it from a seed.
  *
  * @example
  * ```typescript
+ * import { SeededRNG, roll } from 'roll-parser';
+ *
  * // Same seed = same sequence
- * const rng1 = new SeededRNG('test-seed');
- * const rng2 = new SeededRNG('test-seed');
- * rng1.nextInt(1, 6) === rng2.nextInt(1, 6); // true
+ * const a = new SeededRNG('test-seed');
+ * const b = new SeededRNG('test-seed');
+ * a.nextInt(1, 6) === b.nextInt(1, 6); // true
+ *
+ * // An injected instance keeps advancing across rolls; `{ seed }` restarts
+ * // the stream on every call.
+ * const rng = new SeededRNG('demo');
+ * roll('1d20', { rng }).total; // 1
+ * roll('1d20', { rng }).total; // 20 — the stream moved on
+ * roll('1d20', { seed: 'demo' }).total; // 1, every single time
  * ```
+ *
+ * @category RNG
  */
 export class SeededRNG implements RNG {
+  // ! Signed int32 on purpose. Every read below is bitwise, so the sequence is
+  // ! identical to uint32 words — but normalizing with `>>> 0` on write costs
+  // ! ~2x per draw, since a word above 2^31 leaves V8's Smi representation.
+  // ! Exposing a word to a caller needs `>>> 0` at that boundary.
   private s0: number;
   private s1: number;
   private s2: number;
   private s3: number;
 
-  constructor(seed?: string | number) {
-    // Initialize state to zero, will be set by initState
+  constructor(seed?: string | number | RngState) {
     this.s0 = 0;
     this.s1 = 0;
     this.s2 = 0;
     this.s3 = 0;
 
+    if (seed !== null && typeof seed === 'object') {
+      assertRestorable(seed);
+
+      // ! No hashing and no warm-up — either would diverge the resumed stream.
+      // ! Signed on write to keep the Smi invariant above; `state()` re-widens.
+      this.s0 = seed[1] | 0;
+      this.s1 = seed[2] | 0;
+      this.s2 = seed[3] | 0;
+      this.s3 = seed[4] | 0;
+      this.guardZeroState();
+      return;
+    }
+
     this.initState(seed);
 
-    // Warm-up: discard first 20 values for better initial distribution
-    for (let i = 0; i < 20; i++) {
+    for (let i = 0; i < WARMUP_DRAWS; i++) {
       this.nextUint32();
     }
   }
 
   private initState(seed?: string | number): void {
-    const numSeed =
-      seed == null
-        ? (Date.now() ^ (Math.random() * 0xffffffff)) >>> 0
-        : typeof seed === 'string'
-          ? this.hashString(seed)
-          : seed >>> 0;
-
-    // Split seed into 4 state values using splitmix32
-    let s = numSeed;
-    const state: number[] = [];
-
-    for (let i = 0; i < 4; i++) {
-      s = (s + 0x9e3779b9) >>> 0;
-      let z = s;
-      z = Math.imul(z ^ (z >>> 16), 0x85ebca6b) >>> 0;
-      z = Math.imul(z ^ (z >>> 13), 0xc2b2ae35) >>> 0;
-      state.push((z ^ (z >>> 16)) >>> 0);
-    }
-
-    this.s0 = state[0] ?? 0;
-    this.s1 = state[1] ?? 0;
-    this.s2 = state[2] ?? 0;
-    this.s3 = state[3] ?? 0;
+    this.hashSeed(this.toSeedString(seed));
+    this.guardZeroState();
+  }
 
-    // Ensure non-zero state (xorshift requires at least one non-zero)
+  /** All-zero is a fixed point for xoshiro — at least one word must be non-zero. */
+  private guardZeroState(): void {
     if (this.s0 === 0 && this.s1 === 0 && this.s2 === 0 && this.s3 === 0) {
       this.s0 = 1;
     }
   }
 
-  private hashString(str: string): number {
-    // djb2 hash algorithm
-    let hash = 5381;
+  /**
+   * Returns the current state as a format version followed by four unsigned
+   * 32-bit words. Feeding the snapshot back to the constructor resumes this
+   * exact sequence; the source instance is untouched, and the two then advance
+   * independently.
+   *
+   * The words are {@link RngState} — opaque, restorable within the major
+   * version that produced them, and rejected with `INCOMPATIBLE_RNG_STATE`
+   * outside it.
+   *
+   * @returns A snapshot of the version and the four state words
+   *
+   * @example Replay a roll that was never seeded
+   * ```typescript
+   * import { SeededRNG, roll } from 'roll-parser';
+   *
+   * const rng = new SeededRNG();
+   * const snapshot = rng.state();
+   *
+   * const first = roll('1d20', { rng });
+   * const replay = roll('1d20', { rng: new SeededRNG(snapshot) });
+   * first.total === replay.total; // true
+   * ```
+   *
+   * Not a fork primitive. A restored generator replays the parent's stream, so
+   * children taken at different points are the same sequence at an offset, not
+   * independent substreams — derive a seed per entity instead.
+   *
+   * @example Per-entity streams — derive seeds, do not fork state
+   * ```typescript
+   * import { SeededRNG } from 'roll-parser';
+   *
+   * const goblin = new SeededRNG('world:goblin');
+   * const orc = new SeededRNG('world:orc');
+   * ```
+   */
+  state(): RngState {
+    return [RNG_STATE_VERSION, this.s0 >>> 0, this.s1 >>> 0, this.s2 >>> 0, this.s3 >>> 0];
+  }
+
+  /**
+   * Normalizes the constructor seed into a string. Numbers are stringified
+   * rather than coerced to uint32, so all 53 exact bits reach the hash.
+   */
+  private toSeedString(seed?: string | number): string {
+    // ! The library's one permitted `Math.random()` site — both draws stay here.
+    if (seed == null) return `${Date.now()}-${Math.random()}-${Math.random()}`;
+    return String(seed);
+  }
+
+  /** cyrb128 — hashes the seed into all four state words at once. */
+  private hashSeed(str: string): void {
+    let h1 = CYRB128_BASIS_1;
+    let h2 = CYRB128_BASIS_2;
+    let h3 = CYRB128_BASIS_3;
+    let h4 = CYRB128_BASIS_4;
+
     for (let i = 0; i < str.length; i++) {
-      hash = ((hash << 5) + hash + str.charCodeAt(i)) >>> 0;
+      const k = str.charCodeAt(i);
+      h1 = h2 ^ Math.imul(h1 ^ k, CYRB128_MULTIPLIER_1);
+      h2 = h3 ^ Math.imul(h2 ^ k, CYRB128_MULTIPLIER_2);
+      h3 = h4 ^ Math.imul(h3 ^ k, CYRB128_MULTIPLIER_3);
+      h4 = h1 ^ Math.imul(h4 ^ k, CYRB128_MULTIPLIER_4);
     }
-    return hash;
+
+    h1 = Math.imul(h3 ^ (h1 >>> 18), CYRB128_MULTIPLIER_1);
+    h2 = Math.imul(h4 ^ (h2 >>> 22), CYRB128_MULTIPLIER_2);
+    h3 = Math.imul(h1 ^ (h3 >>> 17), CYRB128_MULTIPLIER_3);
+    h4 = Math.imul(h2 ^ (h4 >>> 19), CYRB128_MULTIPLIER_4);
+
+    // ! Matches reference cyrb128, which folds `h1` first and derives the other
+    // ! three against the folded value. A revision withdrawn in 2023 used the
+    // ! unmixed `h1` and its mirrors still circulate — matching one rewrites
+    // ! every seeded sequence. Pinned by `rng.test.ts`.
+    const mixed = h1 ^ h2 ^ h3 ^ h4;
+
+    this.s0 = mixed;
+    this.s1 = h2 ^ mixed;
+    this.s2 = h3 ^ mixed;
+    this.s3 = h4 ^ mixed;
   }
 
   private nextUint32(): number {
-    // xorshift128 algorithm
-    let t = this.s3;
-    const s = this.s0;
+    // xoshiro128** 1.1 — these constants are part of the algorithm, not tunables.
+    // ! Scrambling `s1`, not `s0`, is what makes this 1.1; 1.0 used `s0` and was
+    // ! withdrawn for it.
+    const scrambled = rotl(Math.imul(this.s1, SCRAMBLE_MULTIPLIER_1), SCRAMBLE_ROTATION);
+    const result = Math.imul(scrambled, SCRAMBLE_MULTIPLIER_2) >>> 0;
 
-    this.s3 = this.s2;
-    this.s2 = this.s1;
-    this.s1 = s;
+    const t = this.s1 << STATE_SHIFT;
 
-    t ^= t << 11;
-    t ^= t >>> 8;
-    this.s0 = (t ^ s ^ (s >>> 19)) >>> 0;
+    this.s2 ^= this.s0;
+    this.s3 ^= this.s1;
+    this.s1 ^= this.s2;
+    this.s0 ^= this.s3;
+    this.s2 ^= t;
+    this.s3 = rotl(this.s3, STATE_ROTATION);
 
-    return this.s0;
+    return result;
   }
 
+  /**
+   * Returns a float in `[0, 1)`, derived from one uint32 draw. Resolution is
+   * 2^-32, not the full 2^-53 a double can hold.
+   *
+   * Not used by the evaluator — dice go through {@link nextInt}.
+   *
+   * @returns A float in `[0, 1)`
+   */
   next(): number {
-    // Convert uint32 to [0, 1) float
-    return this.nextUint32() / 0x100000000;
+    return this.nextUint32() / UINT32_SPACE;
   }
 
+  /**
+   * Returns an integer in the inclusive range `[min, max]`, uniformly
+   * distributed — rejection sampling removes the modulo bias a plain
+   * `% range` would introduce.
+   *
+   * Bounds handling, in order:
+   * - `min > max` is normalized by swapping, so `nextInt(6, 1)` behaves as
+   *   `nextInt(1, 6)`. (The mock RNG throws instead; see {@link RNG.nextInt}.)
+   * - `min === max` returns that value without consuming a draw.
+   * - Ranges wider than 2^32 use two draws composed into a 53-bit value.
+   * - Ranges wider than 2^53 cannot be sampled exactly and throw a
+   *   `RangeError` rather than silently skewing.
+   *
+   * @param min - Lower bound, inclusive
+   * @param max - Upper bound, inclusive
+   * @returns An integer in `[min, max]`
+   * @throws {RangeError} If `max - min + 1` exceeds 2^53
+   *
+   * @example
+   * ```typescript
+   * import { SeededRNG } from 'roll-parser';
+   *
+   * const rng = new SeededRNG('demo');
+   * rng.nextInt(1, 6); // 1..6
+   * rng.nextInt(3, 3); // 3, always
+   * rng.nextInt(1, Number.MAX_SAFE_INTEGER); // fine — two-draw path
+   * ```
+   */
   nextInt(min: number, max: number): number {
-    // Handle inverted bounds
     const lo = min > max ? max : min;
     const hi = min > max ? min : max;
 
     const range = hi - lo + 1;
 
-    // Single value case
     if (range <= 1) {
       return lo;
     }
 
     // Ranges wider than 2^32 need two draws — a single uint32 can never
     // produce the upper part of the range and would silently truncate it.
-    if (range > 0x100000000) {
+    if (range > UINT32_SPACE) {
       return lo + this.nextBoundedWide(range);
     }
 
-    // Rejection sampling for unbiased distribution
-    // Avoids modulo bias by rejecting values that would cause uneven distribution
-    const threshold = (0x100000000 - range) % range;
+    // Rejection sampling: discard the leading `[0, threshold)` values so the
+    // accepted zone `[threshold, 2^32)` is an exact multiple of `range`.
+    const threshold = (UINT32_SPACE - range) % range;
     let value: number;
     do {
       value = this.nextUint32();
@@ -138,18 +375,16 @@ export class SeededRNG implements RNG {
    * throw instead of silently degrading.
    */
   private nextBoundedWide(range: number): number {
-    const MAX_53 = 2 ** 53;
-    if (range > MAX_53) {
+    if (range > MAX_EXACT_INT) {
       throw new RangeError(`nextInt range ${range} exceeds 2^53 and cannot be sampled exactly`);
     }
 
-    // Largest multiple of `range` below 2^53 — values at or above it are
-    // rejected to avoid modulo bias.
-    const limit = Math.floor(MAX_53 / range) * range;
+    // Largest multiple of `range` below 2^53 — values at or above it would bias the modulo.
+    const limit = Math.floor(MAX_EXACT_INT / range) * range;
     let value: number;
     do {
       // 32 high bits shifted up by 21 + top 21 bits of a second draw = 53 bits.
-      value = this.nextUint32() * 0x200000 + (this.nextUint32() >>> 11);
+      value = this.nextUint32() * HIGH_DRAW_SCALE + (this.nextUint32() >>> LOW_DRAW_SHIFT);
     } while (value >= limit);
 
     return value % range;

package/src/rng/types.ts

@@ -8,6 +8,57 @@
 
 /**
  * Random Number Generator interface for dice rolling.
+ *
+ * Guaranteed by every implementation:
+ *
+ * - `next()` returns a float in `[0, 1)`.
+ * - `nextInt(min, max)` returns an integer in `[min, max]` when `min <= max`.
+ * - `nextInt(n, n)` returns `n`.
+ *
+ * Deliberately NOT guaranteed: behavior when `min > max`. The two shipped
+ * implementations differ, and each difference is load-bearing — see
+ * {@link nextInt}. Evaluator code never inverts its bounds, so callers should
+ * treat inverted bounds as a programming error rather than an API.
+ *
+ * The evaluator only ever calls `nextInt`, once per die, left to right;
+ * `next` exists for implementations that want a float source of their own.
+ * Two shipped implementations satisfy the interface — {@link SeededRNG} and
+ * the mock from `roll-parser/testing` — and anything structurally compatible
+ * works, so a crypto-backed or table-driven generator drops straight in.
+ *
+ * @example A crypto-backed RNG
+ * ```typescript
+ * import { roll, type RNG } from 'roll-parser';
+ *
+ * const cryptoRng: RNG = {
+ *   next: () => crypto.getRandomValues(new Uint32Array(1))[0]! / 2 ** 32,
+ *   nextInt: (min, max) => min + Math.floor(cryptoRng.next() * (max - min + 1)),
+ * };
+ *
+ * roll('4d6kh3', { rng: cryptoRng }).total; // 3..18
+ * ```
+ *
+ * @example Wrapping an RNG to log every draw
+ * ```typescript
+ * import { SeededRNG, roll, type RNG } from 'roll-parser';
+ *
+ * function withLog(inner: RNG, log: number[]): RNG {
+ *   return {
+ *     next: () => inner.next(),
+ *     nextInt: (min, max) => {
+ *       const value = inner.nextInt(min, max);
+ *       log.push(value);
+ *       return value;
+ *     },
+ *   };
+ * }
+ *
+ * const draws: number[] = [];
+ * roll('4d6kh3', { rng: withLog(new SeededRNG('demo'), draws) });
+ * draws; // [4, 3, 3, 3] — every face, including the dropped one
+ * ```
+ *
+ * @category RNG
  */
 export type RNG = {
   /**
@@ -18,6 +69,12 @@ export type RNG = {
   /**
    * Returns a random integer in the inclusive range [min, max].
    *
+   * Inverted bounds (`min > max`) are implementation-defined:
+   * `SeededRNG` normalizes by swapping them, so `nextInt(6, 1)` yields the
+   * same sequence as `nextInt(1, 6)`; the mock RNG from `roll-parser/testing`
+   * raises `RangeError`, because a scripted value can never satisfy an empty
+   * range and silently accepting it would hide a miscounted test sequence.
+   *
    * @param min - Minimum value (inclusive)
    * @param max - Maximum value (inclusive)
    */

package/src/roll.ts

@@ -4,71 +4,88 @@
  * @module roll
  */
 
-import type { RNG } from './rng/types.js';
-import type { EvaluateOptions, RollResult } from './types.js';
 import { evaluate } from './evaluator/evaluator.js';
-import { lex } from './lexer/lexer.js';
-import { Parser } from './parser/parser.js';
+import { parse } from './parser/parser.js';
 import { SeededRNG } from './rng/seeded.js';
+import type { RNG } from './rng/types.js';
+import type { EvaluationOptions, RollResult } from './types.js';
 
 /**
- * Options for the roll function.
+ * Everything {@link roll} accepts on top of the shared {@link EvaluationOptions}:
+ * a randomness source, given either as a ready-made {@link RNG} or as a seed.
+ *
+ * @category Core
+ *
+ * @example
+ * ```typescript
+ * import { roll, SeededRNG } from 'roll-parser';
+ *
+ * roll('4d6', { seed: 'character-1' });     // reproducible
+ * roll('4d6', { rng: new SeededRNG(42) });  // rng wins over seed
+ * roll('1d20+@str', { context: { str: 4 } });
+ * ```
  */
-export type RollOptions = {
-  /** Custom RNG instance (takes precedence over seed) */
+export type RollOptions = EvaluationOptions & {
+  /**
+   * Randomness source. Takes precedence over `seed` — when both are given,
+   * `seed` is ignored.
+   */
   rng?: RNG;
-  /** Seed for deterministic rolls (ignored if rng provided) */
+  /**
+   * Seed for a fresh `SeededRNG`. Equal seeds replay the same die sequence for
+   * the same notation. Ignored when `rng` is set.
+   */
   seed?: string | number;
-  /** Maximum total dice allowed per evaluation (default: 10,000) */
-  maxDice?: number;
-  /** Maximum explosion iterations allowed per die (default: 1,000) */
-  maxExplodeIterations?: number;
-  /** Maximum reroll iterations allowed per die (default: 1,000) */
-  maxRerollIterations?: number;
-  /** Variable context for `@name` / `@{name}` references (default: empty) */
-  context?: Record<string, number>;
-  /** Behavior when a referenced variable is missing from context (default: 'throw') */
-  onMissingVariable?: 'throw' | 'zero';
 };
 
 /**
- * Parses and evaluates a dice notation string.
+ * Parses and evaluates a dice notation string in one call — the main entry
+ * point of the library.
  *
- * @param notation - Dice notation (e.g., "2d6+3", "4d6kh3")
- * @param options - Optional configuration (RNG or seed)
- * @returns Complete roll result with total and metadata
+ * Equivalent to `evaluate(parse(notation), rng, { notation })`. Each call
+ * builds a fresh `SeededRNG` unless `options.rng` is supplied, so reuse
+ * {@link parse} + {@link evaluate} directly when rolling the same notation in
+ * a loop.
+ *
+ * @param notation - Dice notation, e.g. `'2d6+3'` or `'4d6kh3'`
+ * @param options - RNG or seed, plus the shared {@link EvaluationOptions}
+ * @returns Complete {@link RollResult} with total, per-die results and the
+ *   structured `parts` tree
+ * @throws {LexerError} On an invalid character
+ * @throws {ParseError} On invalid syntax
+ * @throws {EvaluatorError} On a limit breach or an impossible expression
+ * @throws {RollParserError} `INVALID_EVALUATION_LIMIT` when a supplied limit is
+ *   not an integer in range — raised before any die is rolled
+ * @throws {RollParserError} `INVALID_NOTATION_TYPE` when `notation` is not a
+ *   string, so `isRollParserError` still filters untrusted input completely
  *
  * @example
  * ```typescript
+ * import { roll } from 'roll-parser';
+ *
  * // Random roll
- * const result = roll('2d6+3');
- * console.log(result.total); // 5-15
+ * roll('2d6+3').total; // 5..15
  *
- * // Seeded for reproducibility
- * const r1 = roll('4d6', { seed: 'test' });
- * const r2 = roll('4d6', { seed: 'test' });
- * r1.total === r2.total; // true
+ * // Seeded — same seed, same sequence
+ * roll('2d6+3', { seed: 'demo' }).rendered; // '2d6[1, 6] + 3 = 10'
+ * roll('2d6+3', { seed: 'demo' }).total; // 10
+ * ```
  *
- * // Custom RNG for testing
- * const result = roll('1d20', { rng: createMockRng([15]) });
- * result.total; // 15
+ * @example Deterministic tests with the testing mock
+ * ```typescript
+ * import { roll } from 'roll-parser';
+ * import { createMockRng } from 'roll-parser/testing';
+ *
+ * const result = roll('4d6kh3', { rng: createMockRng([3, 6, 2, 5]) });
+ * result.total; // 14
+ * result.rendered; // '4d6[3, 6, ~~2~~, 5] = 14'
  * ```
+ *
+ * @category Core
  */
 export function roll(notation: string, options: RollOptions = {}): RollResult {
-  const rng = options.rng ?? new SeededRNG(options.seed);
-  const tokens = lex(notation);
-  const ast = new Parser(tokens).parse();
-  const evalOptions: EvaluateOptions = { notation };
-  if (options.maxDice != null) evalOptions.maxDice = options.maxDice;
-  if (options.maxExplodeIterations != null) {
-    evalOptions.maxExplodeIterations = options.maxExplodeIterations;
-  }
-  if (options.maxRerollIterations != null) {
-    evalOptions.maxRerollIterations = options.maxRerollIterations;
-  }
-  if (options.context != null) evalOptions.context = options.context;
-  if (options.onMissingVariable != null) {
-    evalOptions.onMissingVariable = options.onMissingVariable;
-  }
-  return evaluate(ast, rng, evalOptions);
+  // Explicitly-undefined limit keys forward harmlessly — `evaluate` nullish-checks each.
+  const { rng, seed, ...limits } = options;
+
+  return evaluate(parse(notation), rng ?? new SeededRNG(seed), { ...limits, notation });
 }

package/src/testing.ts

@@ -1,16 +1,12 @@
 /**
  * Test utilities for roll-parser consumers.
  *
- * Import from `roll-parser/testing` for deterministic dice testing.
+ * Import from `roll-parser/testing` for deterministic dice testing. The full
+ * TSDoc lives on the implementations in `./rng/mock.ts`; this entry point is
+ * a plain re-export barrel.
  *
  * @module testing
  */
 
-// Direct value exports force the bundler to inline the code
-import {
-  MockRNGExhaustedError as _MockRNGExhaustedError,
-  createMockRng as _createMockRng,
-} from './rng/mock.js';
-
-export const createMockRng = _createMockRng;
-export const MockRNGExhaustedError = _MockRNGExhaustedError;
+export { createMockRng, MockRNGExhaustedError } from './rng/mock.js';
+export type { RNG } from './rng/types.js';