roll-parser 3.0.0-alpha.0 → 3.0.0

package/src/rng/mock.ts

@@ -4,15 +4,47 @@
  * @module rng/mock
  */
 
-import type { RNG } from './types';
+import type { RNG } from './types.js';
 
 /**
- * Error thrown when MockRNG exhausts its predefined values.
+ * Error thrown when a mock RNG runs out of predefined values.
  *
- * This is intentional behavior to catch incorrect roll counts in tests.
- * If you see this error, your test is consuming more random values than expected.
+ * This is intentional behavior, not a limitation: a mock that wrapped around
+ * would silently pass a test whose expression rolls more dice than the author
+ * thought. Seeing this error means the notation consumed more draws than the
+ * sequence supplied — count the dice, including explosions, rerolls, and
+ * meta-expressions, and check the draw order in the roll-parser README.
+ *
+ * Deliberately outside the `RollParserError` hierarchy — no `code`, and
+ * `isRollParserError` answers `false` for it. An exhausted mock is a bug in the
+ * test fixture, not a failure mode of the notation, so the
+ * `if (!isRollParserError(error)) throw error` line a consumer writes around
+ * `roll()` rethrows it and fails the test instead of routing it to a "bad dice"
+ * message. `instanceof` is the check here — there is no `code` to branch on.
+ *
+ * @example
+ * ```typescript
+ * import { roll } from 'roll-parser';
+ * import { createMockRng, MockRNGExhaustedError } from 'roll-parser/testing';
+ *
+ * try {
+ *   roll('4d6', { rng: createMockRng([1, 2, 3]) });
+ * } catch (error) {
+ *   error instanceof MockRNGExhaustedError; // true
+ *   (error as MockRNGExhaustedError).consumed; // 3
+ *   (error as Error).message;
+ *   // 'MockRNG exhausted: consumed 3 values, no more available'
+ * }
+ * ```
+ *
+ * @category Testing
  */
 export class MockRNGExhaustedError extends Error {
+  /**
+   * How many values the sequence handed out before running dry — equivalently,
+   * the length of the array that was passed to `createMockRng`. Compare it
+   * against the dice you expected to be rolled to find the miscount.
+   */
   readonly consumed: number;
 
   constructor(consumed: number) {
@@ -23,29 +55,58 @@ export class MockRNGExhaustedError extends Error {
 }
 
 /**
- * Creates a mock RNG that returns predefined values in sequence.
+ * Creates a mock {@link RNG} that hands out predefined values in order — the
+ * way to write dice tests with exact expected totals.
+ *
+ * Two deliberate strictnesses, both there to surface a miscounted sequence
+ * instead of hiding it:
  *
- * IMPORTANT: Throws MockRNGExhaustedError when all values are consumed.
- * This behavior catches incorrect roll counts in tests - it never wraps around.
+ * - It never wraps around. Running out throws {@link MockRNGExhaustedError}.
+ * - `nextInt` rejects a scripted value outside the requested `[min, max]`
+ *   with a `RangeError`, so `createMockRng([7])` cannot satisfy a `d6`.
  *
- * @param values - Array of values to return (dice results for nextInt, floats for next)
- * @returns RNG instance returning predefined values
+ * Both are the only failures that reach a caller of `roll()` without a
+ * roll-parser `code`, and only ever when a mock was injected — see
+ * {@link MockRNGExhaustedError} for why they stay outside the hierarchy.
+ *
+ * Draw order matters when the notation contains meta-expressions. Keep/drop
+ * counts (`4d6kh(1d2)`) are drawn *before* the pool; threshold expressions
+ * (`4d6cs>(1d2)`) are drawn *after* it. The README's Randomness section has
+ * the full tables.
+ *
+ * @param values - Values to return, in draw order (die faces for `nextInt`,
+ *   floats in `[0, 1)` for `next`)
+ * @returns An `RNG` that replays `values`
  *
  * @example
  * ```typescript
+ * import { createMockRng } from 'roll-parser/testing';
+ *
  * const rng = createMockRng([4, 2, 6]);
- * rng.nextInt(1, 6);  // Returns 4
- * rng.nextInt(1, 6);  // Returns 2
- * rng.nextInt(1, 6);  // Returns 6
- * rng.nextInt(1, 6);  // Throws MockRNGExhaustedError
+ * rng.nextInt(1, 6);  // 4
+ * rng.nextInt(1, 6);  // 2
+ * rng.nextInt(1, 6);  // 6
+ * rng.nextInt(1, 6);  // throws MockRNGExhaustedError
+ * ```
+ *
+ * @example Pinning a roll
+ * ```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 Testing
  */
 export function createMockRng(values: number[]): RNG {
   let index = 0;
 
   const getNext = (): number => {
     const value = values[index];
-    if (value === undefined) {
+    if (value == null) {
       throw new MockRNGExhaustedError(index);
     }
     index++;

package/src/rng/seeded.ts

@@ -1,122 +1,365 @@
 /**
- * Seedable RNG using xorshift128 algorithm.
+ * Seedable RNG using the xoshiro128** algorithm.
  *
  * @module rng/seeded
  */
 
-import type { RNG } from './types';
+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;
     }
 
-    // Rejection sampling for unbiased distribution
-    // Avoids modulo bias by rejecting values that would cause uneven distribution
-    const threshold = (0x100000000 - range) % range;
+    // 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 > UINT32_SPACE) {
+      return lo + this.nextBoundedWide(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();
@@ -124,4 +367,26 @@ export class SeededRNG implements RNG {
 
     return lo + (value % range);
   }
+
+  /**
+   * Unbiased sampling in `[0, range)` for ranges above 2^32, built from two
+   * uint32 draws combined into a 53-bit integer (the largest width JS numbers
+   * represent exactly). Ranges beyond 2^53 cannot be sampled without bias —
+   * throw instead of silently degrading.
+   */
+  private nextBoundedWide(range: number): number {
+    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 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() * 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)
    */