roll-parser 3.0.0-beta.0 → 3.1.0

package/src/parser/parser.ts

@@ -15,13 +15,14 @@ import type {
   CritThreshold,
   CritThresholdNode,
   DiceNode,
+  DieBoundNode,
   ExplodeNode,
   FateDiceNode,
   FunctionCallNode,
   GroupedNode,
   GroupNode,
+  KeepDropNode,
   LiteralNode,
-  ModifierNode,
   RerollNode,
   SortNode,
   SuccessCountNode,
@@ -29,29 +30,61 @@ import type {
   VariableNode,
   VersusNode,
 } from './ast.js';
+import { isCritThreshold, isSuccessCount } from './ast.js';
 import {
   containsDicePool,
   containsFatePool,
   containsMultiSubGroup,
   containsVersus,
   deepContainsDicePool,
-  isCritThreshold,
-  isSuccessCount,
-  unwrapTransparent,
-} from './ast.js';
+  unwrapAllTransparent,
+  unwrapGrouped,
+} from './guards.js';
 
 /**
  * Error thrown when the parser encounters invalid syntax.
+ *
+ * `position` is a zero-based UTF-16 offset into the notation. It is
+ * deliberately absent from `message` — read it from the field, or uniformly
+ * across all roll-parser errors via `getErrorSpan`.
+ *
+ * @example
+ * ```typescript
+ * import { ParseError, roll, TokenType } from 'roll-parser';
+ *
+ * try {
+ *   roll('4d6d1');
+ * } catch (error) {
+ *   const typed = error as ParseError;
+ *   typed.code; // 'AMBIGUOUS_DICE_CHAIN'
+ *   typed.position; // 3
+ *   typed.token?.type === TokenType.DICE; // true
+ * }
+ * ```
+ *
+ * @category Errors
  */
 export class ParseError extends RollParserError {
+  /** Zero-based UTF-16 offset in the notation where parsing failed. */
   readonly position: number;
+  /**
+   * The token the parser was looking at. `undefined` when the failure is not
+   * anchored to a token — currently only `UNEXPECTED_END`, raised when the
+   * input stops short.
+   */
   readonly token: Token | undefined;
 
-  constructor(message: string, code: RollParserErrorCode, position: number, token?: Token) {
-    super(`${message} at position ${position}`, code);
+  constructor(
+    message: string,
+    code: RollParserErrorCode,
+    position: number,
+    token?: Token,
+    options?: ErrorOptions,
+  ) {
+    super(message, code, options);
     this.name = 'ParseError';
     this.position = position;
-    this.token = token ?? undefined;
+    this.token = token;
   }
 }
 
@@ -61,6 +94,7 @@ export class ParseError extends RollParserError {
  *
  * Precedence order (lowest to highest):
  * - Versus (`vs`): 2-3 (lowest — full expressions on both sides)
+ * - Comparison (success-count LED): 8
  * - Addition/subtraction: 10
  * - Multiplication/division/modulo: 20
  * - Unary minus: 25 (binds to complete dice expr: -1d4 = -(1d4))
@@ -69,27 +103,24 @@ export class ParseError extends RollParserError {
  * - Dice: 40-41
  */
 const BP = {
-  // Versus (left-associative, lowest precedence — `1d20+10 vs 25+10` = `(1d20+10) vs (25+10)`)
+  // Lowest, so both sides take a full expression: `1d20+10 vs 25+10` =
+  // `(1d20+10) vs (25+10)`.
   VS_LEFT: 2,
   VS_RIGHT: 3,
-  // Comparison operators used as the success-count LED. Must be below
-  // ADD/MUL so `XdY+N>T` parses as `(XdY+N)>T` and fails the pool-target
-  // guard with a clear error, instead of the `>` stealing `N` from the `+`.
+  // Below ADD/MUL so `XdY+N>T` parses as `(XdY+N)>T` and fails the pool-target
+  // guard with a clear error, instead of `>` stealing `N` from the `+`.
   COMPARE: 8,
-  // Addition/subtraction (left-associative)
   ADD_LEFT: 10,
   ADD_RIGHT: 11,
-  // Multiplication/division/modulo (left-associative)
   MUL_LEFT: 20,
   MUL_RIGHT: 21,
-  // Unary minus: between mul and power so -1d4 = -(1d4) not (-1)d4
+  // Between MUL and POW so `-1d4` = `-(1d4)`, not `(-1)d4`.
   UNARY: 25,
-  // Power (right-associative: left > right)
   POW_LEFT: 31,
   POW_RIGHT: 30,
-  // Postfix modifiers: must be < DICE_RIGHT so they bind to complete dice expr
+  // Must stay below DICE_RIGHT so a postfix modifier binds to the whole dice
+  // expression: `4d6kh3` = `(4d6)kh3`.
   MODIFIER: 35,
-  // Dice operator (highest math precedence)
   DICE_LEFT: 40,
   DICE_RIGHT: 41,
 } as const;
@@ -100,17 +131,43 @@ const BP = {
  * `ParseError` instead of an uncaught `RangeError` stack overflow (which
  * would also break the `isRollParserError` contract). Bounding parse depth
  * also bounds AST depth, protecting the recursive AST walkers and evaluator.
+ *
+ * Not configurable — unlike the {@link EvaluationOptions} caps, this one always
+ * applies, so untrusted notation can never blow the stack.
+ *
+ * @example
+ * ```typescript
+ * import { isRollParserError, MAX_PARSE_DEPTH, parse } from 'roll-parser';
+ *
+ * MAX_PARSE_DEPTH; // 128
+ *
+ * try {
+ *   parse('('.repeat(20_000) + '1d6' + ')'.repeat(20_000));
+ * } catch (error) {
+ *   isRollParserError(error) && error.code; // 'MAX_DEPTH_EXCEEDED'
+ * }
+ * ```
+ *
+ * @category Limits
  */
-const MAX_PARSE_DEPTH = 128;
+export const MAX_PARSE_DEPTH = 128;
 
-/** Human-readable symbols for tokens named in `expect()` error messages. */
-const TOKEN_DISPLAY: Partial<Record<TokenType, string>> = {
+/**
+ * Human-readable symbols for the tokens `expect()` can be asked for.
+ *
+ * `satisfies` keeps the key literals, so `ExpectableToken` narrows `expect()`
+ * to exactly these tokens and the lookup can never miss.
+ */
+const TOKEN_DISPLAY = {
   [TokenType.LPAREN]: `'('`,
   [TokenType.RPAREN]: `')'`,
   [TokenType.LBRACE]: `'{'`,
   [TokenType.RBRACE]: `'}'`,
   [TokenType.COMMA]: `','`,
-};
+} satisfies Partial<Record<TokenType, string>>;
+
+/** Token types that carry a display symbol and may be passed to `expect()`. */
+type ExpectableToken = keyof typeof TOKEN_DISPLAY;
 
 /**
  * Arity table for math functions. `min` and `max` are inclusive.
@@ -121,10 +178,26 @@ const FUNCTION_ARITY: Record<string, { min: number; max: number }> = {
   ceil: { min: 1, max: 1 },
   round: { min: 1, max: 1 },
   abs: { min: 1, max: 1 },
+  sqrt: { min: 1, max: 1 },
+  pow: { min: 2, max: 2 },
   max: { min: 2, max: Number.POSITIVE_INFINITY },
   min: { min: 2, max: Number.POSITIVE_INFINITY },
 };
 
+/** Renders an arity range for the `INVALID_FUNCTION_ARITY` message. */
+function formatArity(arity: { min: number; max: number }): string {
+  if (arity.max === Number.POSITIVE_INFINITY) return `at least ${arity.min}`;
+  if (arity.min === arity.max) return `${arity.min}`;
+  return `${arity.min}–${arity.max}`;
+}
+
+/** Explode variant produced by each explode token. */
+const EXPLODE_VARIANTS: Partial<Record<TokenType, ExplodeNode['variant']>> = {
+  [TokenType.EXPLODE]: 'standard',
+  [TokenType.EXPLODE_COMPOUND]: 'compound',
+  [TokenType.EXPLODE_PENETRATING]: 'penetrating',
+};
+
 /**
  * Pratt parser for dice notation.
  *
@@ -150,7 +223,6 @@ export class Parser {
 
     const ast = this.parseExpression(0);
 
-    // Ensure we consumed all tokens
     if (this.peek().type !== TokenType.EOF) {
       const token = this.peek();
       throw new ParseError(
@@ -168,15 +240,9 @@ export class Parser {
    * Parse an expression with minimum binding power.
    */
   private parseExpression(minBp: number): ASTNode {
+    const entryDepth = this.depth;
     this.depth += 1;
-    if (this.depth > MAX_PARSE_DEPTH) {
-      throw new ParseError(
-        `Expression nesting exceeds the maximum depth of ${MAX_PARSE_DEPTH}`,
-        'MAX_DEPTH_EXCEEDED',
-        this.peek().position,
-        this.peek(),
-      );
-    }
+    this.guardDepth();
 
     try {
       let left = this.parseNud();
@@ -189,11 +255,31 @@ export class Parser {
 
         this.advance();
         left = this.parseLed(left, token);
+        // ! Each continuation wraps `left`, so the AST is one level deeper even
+        // ! though this loop never recursed. Drop this and the bound stops
+        // ! holding for left-associative chains.
+        this.depth += 1;
+        this.guardDepth();
       }
 
       return left;
     } finally {
-      this.depth -= 1;
+      this.depth = entryDepth;
+    }
+  }
+
+  /**
+   * Throw once the AST under construction is deeper than the recursive walkers
+   * can safely descend.
+   */
+  private guardDepth(): void {
+    if (this.depth > MAX_PARSE_DEPTH) {
+      throw new ParseError(
+        `Expression nesting exceeds the maximum depth of ${MAX_PARSE_DEPTH}`,
+        'MAX_DEPTH_EXCEEDED',
+        this.peek().position,
+        this.peek(),
+      );
     }
   }
 
@@ -272,7 +358,7 @@ export class Parser {
       case TokenType.KEEP_LOW:
       case TokenType.DROP_HIGH:
       case TokenType.DROP_LOW:
-        return this.parseModifier(left, token);
+        return this.parseKeepDrop(left, token);
 
       case TokenType.EXPLODE:
       case TokenType.EXPLODE_COMPOUND:
@@ -291,6 +377,11 @@ export class Parser {
       case TokenType.CRIT_FAIL:
         return this.parseCritThreshold(left, token);
 
+      case TokenType.FUNCTION:
+        // Only `min`/`max` reach LED position — `getLeftBp` keeps every
+        // other function name at -1, ending the Pratt loop before dispatch.
+        return this.parseDieBound(left, token);
+
       case TokenType.GREATER:
       case TokenType.GREATER_EQUAL:
       case TokenType.LESS:
@@ -311,7 +402,9 @@ export class Parser {
     }
   }
 
+  //
   // * Node parsers
+  //
 
   /**
    * Zero-width span for synthetic nodes (implicit counts, `d%` sides) that
@@ -343,10 +436,9 @@ export class Parser {
   }
 
   private parsePrefixDice(token: Token): DiceNode {
-    // d20 → Dice(1, 20)
     const sides = this.parseExpression(BP.DICE_RIGHT);
     this.rejectSuccessCountTarget(sides, token);
-    this.rejectVersusTarget(sides, token);
+    this.rejectVersusMetaOperand(sides, token);
     return {
       type: 'Dice',
       count: Parser.syntheticLiteral(1, token),
@@ -357,13 +449,12 @@ export class Parser {
   }
 
   private parseInfixDice(left: ASTNode, token: Token): DiceNode {
-    // 4d6 → Dice(4, 6)
     this.rejectSuccessCountTarget(left, token);
-    this.rejectVersusTarget(left, token);
+    this.rejectVersusMetaOperand(left, token);
     this.rejectBareDiceChain(left, token);
     const sides = this.parseExpression(BP.DICE_RIGHT);
     this.rejectSuccessCountTarget(sides, token);
-    this.rejectVersusTarget(sides, token);
+    this.rejectVersusMetaOperand(sides, token);
     return {
       type: 'Dice',
       count: left,
@@ -374,7 +465,6 @@ export class Parser {
   }
 
   private parsePrefixDicePercent(token: Token): DiceNode {
-    // d% → Dice(1, 100)
     return {
       type: 'Dice',
       count: Parser.syntheticLiteral(1, token),
@@ -385,9 +475,8 @@ export class Parser {
   }
 
   private parseInfixDicePercent(left: ASTNode, token: Token): DiceNode {
-    // 2d% → Dice(2, 100)
     this.rejectSuccessCountTarget(left, token);
-    this.rejectVersusTarget(left, token);
+    this.rejectVersusMetaOperand(left, token);
     this.rejectBareDiceChain(left, token);
     return {
       type: 'Dice',
@@ -399,7 +488,6 @@ export class Parser {
   }
 
   private parsePrefixFateDice(token: Token): FateDiceNode {
-    // dF → FateDice(1)
     return {
       type: 'FateDice',
       count: Parser.syntheticLiteral(1, token),
@@ -409,11 +497,10 @@ export class Parser {
   }
 
   private parseInfixFateDice(left: ASTNode, token: Token): FateDiceNode {
-    // 4dF → FateDice(4). Unlike parseInfixDice, there is no sides sub-parse,
-    // so modifiers (`kh`, `dl`, …) naturally bind at the outer Pratt loop
-    // without BP competition against a right-operand.
+    // No sides sub-parse, unlike `parseInfixDice`, so modifiers (`kh`, `dl`, …)
+    // bind at the outer Pratt loop with no BP competition from a right operand.
     this.rejectSuccessCountTarget(left, token);
-    this.rejectVersusTarget(left, token);
+    this.rejectVersusMetaOperand(left, token);
     this.rejectBareDiceChain(left, token);
     return {
       type: 'FateDice',
@@ -430,9 +517,9 @@ export class Parser {
   }
 
   private parseGroup(startToken: Token): GroupNode {
-    // ? `LBRACE`/`RBRACE`/`COMMA` all have `getLeftBp === -1`, so inner
-    //   `parseExpression(0)` calls terminate at the first `,` or `}` without
-    //   competing with modifier/arithmetic BPs.
+    // `LBRACE`/`RBRACE`/`COMMA` all have `getLeftBp === -1`, so inner
+    // `parseExpression(0)` calls stop at the first `,` or `}` without competing
+    // with modifier/arithmetic BPs.
     if (this.peek().type === TokenType.RBRACE) {
       throw new ParseError('Empty group', 'UNEXPECTED_TOKEN', startToken.position, startToken);
     }
@@ -462,9 +549,8 @@ export class Parser {
   }
 
   private parseFunctionCall(token: Token): FunctionCallNode {
-    // `FUNCTION` has BP = -1 so callers stop here; `COMMA` and `RPAREN` also
-    // terminate inner `parseExpression(0)` calls, so argument boundaries are
-    // natural.
+    // `FUNCTION`, `COMMA`, and `RPAREN` all sit at BP -1, so argument boundaries
+    // fall out of the inner `parseExpression(0)` calls terminating on their own.
     this.expect(TokenType.LPAREN);
 
     const args: ASTNode[] = [];
@@ -483,10 +569,9 @@ export class Parser {
     const close = this.expect(TokenType.RPAREN);
 
     const arity = FUNCTION_ARITY[token.value];
-    if (arity === undefined) {
-      // ? Unreachable in practice: lexer only emits FUNCTION for registered
-      // names. Kept defensive to keep parser/evaluator error-code contract
-      // symmetrical.
+    if (arity == null) {
+      // Unreachable: the lexer only emits `FUNCTION` for registered names. Kept
+      // so the parser/evaluator error-code contract stays symmetrical.
       throw new ParseError(
         `Unknown function '${token.value}'`,
         'UNKNOWN_FUNCTION',
@@ -496,12 +581,7 @@ export class Parser {
     }
 
     if (args.length < arity.min || args.length > arity.max) {
-      const expected =
-        arity.max === Number.POSITIVE_INFINITY
-          ? `at least ${arity.min}`
-          : arity.min === arity.max
-            ? `${arity.min}`
-            : `${arity.min}–${arity.max}`;
+      const expected = formatArity(arity);
       throw new ParseError(
         `Function '${token.value}' expects ${expected} argument${arity.min === 1 && arity.max === 1 ? '' : 's'}, got ${args.length}`,
         'INVALID_FUNCTION_ARITY',
@@ -552,7 +632,8 @@ export class Parser {
       case 'FateDice':
       case 'Explode':
       case 'Reroll':
-      case 'Modifier':
+      case 'DieBound':
+      case 'KeepDrop':
       case 'Sort':
       case 'CritThreshold':
         throw new ParseError(
@@ -567,11 +648,10 @@ export class Parser {
   }
 
   private rejectSuccessCountTarget(target: ASTNode, token: Token): void {
-    // ? Narrow unwrap: only `Grouped`. A `SuccessCount` cannot live inside
-    //   `Modifier`/`Sort`/`CritThreshold` because each of those parsers calls
-    //   this same reject on their target before constructing the wrapper —
-    //   so widening the set here would never match.
-    const node = unwrapTransparent(target, ['Grouped']);
+    // Narrow unwrap (only `Grouped`): `KeepDrop`/`Sort`/`CritThreshold` each run
+    // this same reject before building their wrapper, so a `SuccessCount` can
+    // never hide inside one and widening the set would never match.
+    const node = unwrapGrouped(target);
     if (isSuccessCount(node)) {
       throw new ParseError(
         `Cannot apply modifier after success counting`,
@@ -586,12 +666,11 @@ export class Parser {
    * Rejects `GroupNode` (or a wrapper-cloaked group) as the target of `token`.
    * Explode, reroll, and crit-threshold wrap bare dice pools only — a group
    * is a container of sub-expressions, so these modifiers have no defined
-   * semantics. Walks `Grouped`/`Modifier`/`Sort`/`CritThreshold` so wrappers
+   * semantics. Walks `Grouped`/`KeepDrop`/`Sort`/`CritThreshold` so wrappers
    * cannot smuggle a group past the check (`{1d6}kh1cs>5`, `({1d6})!`,
    * `{1d6}scs>5` all reject the same as `{1d6}!`/`{1d6}cs>5`).
    *
-   * `singleSubRollPasses` opts the caller into the Stage 3 single-sub-roll
-   * passthrough rule (STAGE3.md "Group Semantics: Single vs Multi Sub-Roll"):
+   * `singleSubRollPasses` opts the caller into the single-sub-roll passthrough:
    * a `Group` with one expression is the user's explicit flat-pool escape
    * hatch and is equivalent to its unwrapped form. Currently only
    * `parseCritThreshold` opts in — explode/reroll keep the strict reject so
@@ -604,14 +683,14 @@ export class Parser {
     code: RollParserErrorCode,
     singleSubRollPasses = false,
   ): void {
-    const node = unwrapTransparent(target, ['Grouped', 'Modifier', 'Sort', 'CritThreshold']);
+    const node = unwrapAllTransparent(target);
     if (node.type !== 'Group') return;
     if (singleSubRollPasses && node.expressions.length === 1) {
-      // ! Deep-walk the inner sub-expression — `unwrapTransparent` only peels
-      //   `Grouped`/`Modifier`/`Sort`/`CritThreshold`, so a multi-sub Group
-      //   buried under arithmetic (`{{1d6,2d8}+0}cs>5`), function calls
-      //   (`{abs({1d6,2d8})}cs>5`), or unary ops would otherwise revive the
-      //   exact dropped-die-flag bug from #97.
+      // ! Deep-walk the inner sub-expression — `unwrapAllTransparent` only peels
+      // ! `Grouped`/`KeepDrop`/`Sort`/`CritThreshold`, so a multi-sub Group
+      // ! buried under arithmetic (`{{1d6,2d8}+0}cs>5`), a function call
+      // ! (`{abs({1d6,2d8})}cs>5`), or a unary op would reach the evaluator and
+      // ! override `critical`/`fumble` on dice from dropped sub-rolls.
       const inner = node.expressions[0];
       if (inner != null && containsMultiSubGroup(inner)) {
         throw new ParseError(`Cannot ${action} a group`, code, token.position, token);
@@ -621,65 +700,74 @@ export class Parser {
     throw new ParseError(`Cannot ${action} a group`, code, token.position, token);
   }
 
+  /**
+   * Rejects a Versus anywhere inside a meta operand — a dice count, dice sides,
+   * a modifier count, or a threshold/bound value.
+   *
+   * Deep, unlike {@link rejectVersusTarget}: `evalMetaOperand` reduces the
+   * operand to a scalar and forwards rolls but not `versusMetadata`, so
+   * `floor(1d20 vs 15)` or `(1d20 vs 15)+0` buried in a count loses the degree
+   * exactly as a bare one does.
+   */
+  private rejectVersusMetaOperand(operand: ASTNode, token: Token): void {
+    if (containsVersus(operand)) Parser.throwVersusMetaExpression(token);
+  }
+
+  /**
+   * The wording the meta-expression rejections share. Not every `NESTED_VERSUS`
+   * throw — `parseVersus` says "Cannot chain versus operators" for `a vs b vs c`,
+   * a different condition. Routing that one through here would silently rewrite
+   * its message, and `expectRollError` asserts only the code.
+   */
+  private static throwVersusMetaExpression(token: Token): never {
+    throw new ParseError(
+      `Versus cannot be used as a meta-expression`,
+      'NESTED_VERSUS',
+      token.position,
+      token,
+    );
+  }
+
   private rejectVersusTarget(target: ASTNode, token: Token): void {
-    // ? Versus produces a PF2e degree outcome — a terminal scalar, not a
-    //   valid input to dice count/sides/thresholds. Symmetric with
-    //   `rejectSuccessCountTarget`; wrappers like `floor(vs)+0` still
-    //   propagate `versusMetadata` via `mergeContext`, so this only blocks
-    //   `mergeMetaRolls` sites where metadata would silently vanish.
-    // ? Narrow unwrap: only `Grouped`. `Modifier`/`Sort`/`CritThreshold`
-    //   cannot wrap a `Versus` because `containsDicePool` does not recurse
-    //   into `Versus`, so each of those parsers rejects the wrap upstream.
-    const node = unwrapTransparent(target, ['Grouped']);
-    if (node.type === 'Versus') {
-      throw new ParseError(
-        `Versus cannot be used as a meta-expression`,
-        'NESTED_VERSUS',
-        token.position,
-        token,
-      );
-    }
-    // ! Single-sub-roll `Group` passthrough is the new sibling route —
-    //   `containsDicePool` recurses into Group's single sub-expression via
-    //   `deepContainsDicePool`, which traverses Versus's `roll`/`dc`. Deep
-    //   walk for any descendant Versus so `{1d20 vs 15}cs>18`,
-    //   `{1+(1d20 vs 15)}cs>18`, and `4d6>={abs(1d20 vs 15)}` reject too.
+    // A Versus degree is a terminal scalar, never a valid modifier target —
+    // every one of these modifiers drops `versusMetadata` on the way through.
+    // Shallow on purpose: a multi-sub group like `{1d20 vs 15, 1d6}kh1` is
+    // legal, and `evalGroupKeepDrop` propagates the degree from kept sub-rolls.
+    // Narrow unwrap (only `Grouped`): `containsDicePool` does not recurse into
+    // `Versus`, so `KeepDrop`/`Sort`/`CritThreshold` reject the wrap upstream.
+    const node = unwrapGrouped(target);
+    if (node.type === 'Versus') Parser.throwVersusMetaExpression(token);
+    // ! `containsDicePool` recurses into a single-sub-roll Group via
+    // ! `deepContainsDicePool`, which traverses Versus's `roll`/`dc` — so that
+    // ! route gets a Versus past the shallow guards. Deep-walk for any descendant
+    // ! Versus, or `{1d20 vs 15}cs>18`, `{1+(1d20 vs 15)}cs>18`, and
+    // ! `4d6>={abs(1d20 vs 15)}` would parse while `(1d20 vs 15)cs>18` rejects.
     if (node.type === 'Group' && node.expressions.length === 1) {
       const inner = node.expressions[0];
-      if (inner != null && containsVersus(inner)) {
-        throw new ParseError(
-          `Versus cannot be used as a meta-expression`,
-          'NESTED_VERSUS',
-          token.position,
-          token,
-        );
-      }
+      if (inner != null && containsVersus(inner)) Parser.throwVersusMetaExpression(token);
     }
   }
 
-  private parseModifier(target: ASTNode, token: Token): ModifierNode {
+  private parseKeepDrop(target: ASTNode, token: Token): KeepDropNode {
     this.rejectSuccessCountTarget(target, token);
-    // ! Mirror `parseSort`/`parseCritThreshold` — keep/drop applied to a
-    //   Versus target silently drops `degree`/`natural` metadata. Pre-existing
-    //   for `(1d20 vs 15)kh1` (caught upstream by `containsDicePool` with a
-    //   different error code), but the single-sub-roll Group passthrough makes
-    //   `{1d20 vs 15}kh1` reachable past `containsDicePool` (Group's deep
-    //   walk recurses into Versus's roll/dc), so the explicit reject is the
-    //   only thing that closes the metadata-drop hole.
+    // ! Keep/drop on a Versus target silently drops `degree`/`natural` metadata,
+    // ! and `{1d20 vs 15}kh1` gets past `containsDicePool` — whose Group deep
+    // ! walk recurses into Versus's `roll`/`dc` — so this reject is the only
+    // ! thing closing that hole. Mirrors `parseSort`/`parseCritThreshold`.
     this.rejectVersusTarget(target, token);
 
-    // Keep/drop modifiers need a dice pool to select from. Wrapping arithmetic
-    // (e.g. `(1d6+5)kh1`, `4d6+2kh3`) would silently drop user math.
+    // Keep/drop needs a pool to select from; `(1d6+5)kh1` or `4d6+2kh3` would
+    // silently drop the user's arithmetic.
     if (!containsDicePool(target)) {
       throw new ParseError(
         `Keep/drop modifiers require a dice pool target`,
-        'INVALID_MODIFIER_TARGET',
+        'INVALID_KEEP_DROP_TARGET',
         token.position,
         token,
       );
     }
 
-    const modifier =
+    const kind =
       token.type === TokenType.KEEP_HIGH || token.type === TokenType.KEEP_LOW ? 'keep' : 'drop';
 
     const selector =
@@ -687,7 +775,6 @@ export class Parser {
         ? 'highest'
         : 'lowest';
 
-    // Default to 1 when no explicit count follows the modifier (e.g., 4d6kh → 4d6kh1)
     const nextToken = this.peek().type;
     const hasExplicitCount =
       nextToken === TokenType.NUMBER ||
@@ -697,11 +784,11 @@ export class Parser {
       ? this.parseExpression(BP.DICE_LEFT)
       : Parser.syntheticLiteral(1, token);
     this.rejectSuccessCountTarget(count, token);
-    this.rejectVersusTarget(count, token);
+    this.rejectVersusMetaOperand(count, token);
 
     return {
-      type: 'Modifier',
-      modifier,
+      type: 'KeepDrop',
+      kind,
       selector,
       count,
       target,
@@ -713,13 +800,12 @@ export class Parser {
   private parseExplode(target: ASTNode, token: Token): ExplodeNode {
     this.rejectSuccessCountTarget(target, token);
 
-    // Groups have no explode semantics — reject outright. Must come before
-    // `containsDicePool`, which recurses into `Group` and would otherwise
-    // let `{4d6}!` slip through.
+    // Groups have no explode semantics. Must precede `containsDicePool`, which
+    // recurses into `Group` and would let `{4d6}!` slip through.
     this.rejectGroupTarget(target, token, 'explode', 'INVALID_EXPLODE_TARGET');
 
-    // Explode needs a dice pool to explode on. Wrapping arithmetic (e.g.
-    // `(1d6+5)!`, `floor(1d6/2)!`) would silently drop user math.
+    // Arithmetic wrappers like `(1d6+5)!` or `floor(1d6/2)!` would silently drop
+    // the user's math.
     if (!containsDicePool(target)) {
       throw new ParseError(
         `Explode modifier requires a dice pool target`,
@@ -729,9 +815,8 @@ export class Parser {
       );
     }
 
-    // Fate dice (sides = 0) cannot explode — the symmetric -1/0/+1 range has
-    // no natural "max" trigger, so semantics are undefined. Reject at parse
-    // time rather than silently no-op in the evaluator.
+    // Fate's symmetric -1/0/+1 range has no max face to trigger on, so exploding
+    // it has no defined semantics — reject here rather than no-op in the evaluator.
     if (containsFatePool(target)) {
       throw new ParseError(
         `Fate dice cannot explode`,
@@ -741,8 +826,7 @@ export class Parser {
       );
     }
 
-    // ? Reject nested explodes (e.g., `1d6!!!`) — a second explode token atop
-    //   an ExplodeNode has no meaningful semantics and is rejected per spec.
+    // A second explode token atop an `Explode` (`1d6!!!`) has no semantics.
     if (target.type === 'Explode') {
       throw new ParseError(
         `Cannot chain explode modifiers`,
@@ -752,36 +836,36 @@ export class Parser {
       );
     }
 
-    const variant: ExplodeNode['variant'] =
-      token.type === TokenType.EXPLODE
-        ? 'standard'
-        : token.type === TokenType.EXPLODE_COMPOUND
-          ? 'compound'
-          : 'penetrating';
+    // `parseLed` reaches here only for the three explode tokens, so the lookup
+    // always hits; the fallback exists to keep the type non-optional.
+    const variant: ExplodeNode['variant'] = EXPLODE_VARIANTS[token.type] ?? 'penetrating';
 
-    const node: ExplodeNode = {
+    const start = target.start ?? token.position;
+    if (!this.isComparePointAhead()) {
+      return { type: 'Explode', variant, target, start, end: token.end };
+    }
+
+    const threshold = this.parseComparePoint();
+
+    return {
       type: 'Explode',
       variant,
       target,
-      start: target.start ?? token.position,
-      end: token.end,
+      threshold,
+      start,
+      end: threshold.value.end ?? token.end,
     };
-    if (this.isComparePointAhead()) {
-      node.threshold = this.parseComparePoint();
-      node.end = node.threshold.value.end ?? token.end;
-    }
-    return node;
   }
 
   private parseReroll(target: ASTNode, token: Token): RerollNode {
     this.rejectSuccessCountTarget(target, token);
 
-    // Groups have no reroll semantics — reject outright. Must come before
-    // `containsDicePool`, which recurses into `Group`.
+    // Groups have no reroll semantics. Must precede `containsDicePool`, which
+    // recurses into `Group`.
     this.rejectGroupTarget(target, token, 'reroll', 'INVALID_REROLL_TARGET');
 
-    // Reroll needs a dice pool to inspect. Wrapping arithmetic (e.g.
-    // `(1d6+5)r<3`, `floor(1d6/2)ro<3`) would silently drop user math.
+    // Arithmetic wrappers like `(1d6+5)r<3` or `floor(1d6/2)ro<3` would silently
+    // drop the user's math.
     if (!containsDicePool(target)) {
       throw new ParseError(
         `Reroll modifier requires a dice pool target`,
@@ -791,7 +875,6 @@ export class Parser {
       );
     }
 
-    // A reroll token must be followed by a comparison — bare `r` / `ro` is invalid.
     if (!this.isComparePointAhead()) {
       throw new ParseError(
         `Expected comparison operator after '${token.value}'`,
@@ -814,14 +897,73 @@ export class Parser {
     };
   }
 
+  private parseDieBound(target: ASTNode, token: Token): DieBoundNode {
+    this.rejectSuccessCountTarget(target, token);
+    this.rejectVersusTarget(target, token);
+
+    // Groups have no per-die clamp semantics — a group's "dice" are sub-roll
+    // subtotals. Must come before `containsDicePool`, which recurses into
+    // `Group`.
+    this.rejectGroupTarget(target, token, `apply '${token.value}' to`, 'INVALID_DIE_BOUND_TARGET');
+
+    // A clamp needs a dice pool to act on. Wrapping arithmetic (e.g.
+    // `(1d6+5)min3`) would silently drop user math.
+    if (!containsDicePool(target)) {
+      throw new ParseError(
+        `Die bound modifier requires a dice pool target`,
+        'INVALID_DIE_BOUND_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    // Fate dice roll a fixed {-1, 0, +1}; clamping those faces has no
+    // established semantics. Mirrors the Fate-explosion rejection.
+    if (containsFatePool(target)) {
+      throw new ParseError(
+        `Fate dice cannot be clamped`,
+        'INVALID_DIE_BOUND_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    // A bound must be explicit — bare `4d6min` has nothing to clamp to.
+    const nextToken = this.peek().type;
+    const hasExplicitValue =
+      nextToken === TokenType.NUMBER ||
+      nextToken === TokenType.LPAREN ||
+      nextToken === TokenType.AT;
+    if (!hasExplicitValue) {
+      throw new ParseError(
+        `Expected value after '${token.value}'`,
+        'EXPECTED_TOKEN',
+        token.position,
+        token,
+      );
+    }
+
+    const value = this.parseExpression(BP.DICE_LEFT);
+    this.rejectSuccessCountTarget(value, token);
+    this.rejectVersusMetaOperand(value, token);
+
+    return {
+      type: 'DieBound',
+      bound: token.value === 'min' ? 'min' : 'max',
+      value,
+      target,
+      start: target.start ?? token.position,
+      end: value.end ?? token.end,
+    };
+  }
+
   private parseSort(target: ASTNode, token: Token): SortNode {
     this.rejectSuccessCountTarget(target, token);
     this.rejectVersusTarget(target, token);
 
-    // Sort is purely visual but still needs a dice pool to reorder —
-    // `5s`, `(1+2)s`, or `floor(5)s` have no dice to touch. Uses the deep
-    // guard so arithmetic-wrapped pools like `(1d6+2d8)s` are accepted per
-    // Stage 3 spec, while pure literals/arithmetic reject.
+    // Deep guard, unlike explode/reroll: arithmetic-wrapped pools like
+    // `(1d6+2d8)s` are sortable, while `5s`, `(1+2)s`, and `floor(5)s` have no
+    // dice to reorder.
     if (!deepContainsDicePool(target)) {
       throw new ParseError(
         `Sort modifier requires a dice pool target`,
@@ -831,14 +973,12 @@ export class Parser {
       );
     }
 
-    // ! Multi-sub-roll groups (`{a, b}s`, `({a, b})s`) need hierarchical
-    //   sort per Stage 3 spec §3 (sort dice within each sub-roll, then sort
-    //   sub-rolls by total) — `evalSort` only flat-sorts, so accepting the
-    //   syntax would silently ship non-spec behaviour. Reject at parse time
-    //   until the deferred Stage 4 implementation lands. Single-sub Groups
-    //   keep passing through (the unwrap returns a `Group` with one
-    //   expression, which is the user's flat-pool escape hatch).
-    const base = unwrapTransparent(target, ['Grouped', 'Modifier', 'Sort', 'CritThreshold']);
+    // ! Multi-sub-roll groups (`{a, b}s`, `({a, b})s`) require hierarchical sort —
+    // ! dice within each sub-roll, then sub-rolls by total — but `evalSort` only
+    // ! flat-sorts, so accepting the syntax would silently ship wrong output.
+    // ! Single-sub Groups still pass; that is the flat-pool escape hatch.
+    // TODO: Implement hierarchical group sort, then drop this reject.
+    const base = unwrapAllTransparent(target);
     if (base.type === 'Group' && base.expressions.length >= 2) {
       throw new ParseError(
         `Sort modifier does not yet support multi-sub-roll groups`,
@@ -850,9 +990,8 @@ export class Parser {
 
     const order: SortNode['order'] = token.type === TokenType.SORT_ASC ? 'ascending' : 'descending';
 
-    // ? Chained sorts (`4d6ss`, `4d6sasd`) are allowed — sort is idempotent
-    //   when repeated in the same direction; a later `sd` after `s` just
-    //   overrides the order since both pass over the same pool.
+    // Chained sorts (`4d6ss`, `4d6sasd`) are deliberately allowed: repeats are
+    // idempotent and a later `sd` just overrides the order.
     return {
       type: 'Sort',
       order,
@@ -866,12 +1005,11 @@ export class Parser {
     this.rejectSuccessCountTarget(target, token);
     this.rejectVersusTarget(target, token);
 
-    // Multi-sub-roll groups have no crit-threshold semantics per Stage 3 spec
-    // — a group there is a container of sub-roll subtotals, not a dice pool,
-    // and applying cs/cf would override `critical`/`fumble` on dropped
-    // sub-roll dice. Single-sub-roll groups pass through under the documented
-    // flat-pool rule (`{1d20}kh1cs>18` ≡ `(1d20)kh1cs>18`). Must run before
-    // `containsDicePool`, which recurses into `Group`.
+    // A multi-sub-roll group is a container of sub-roll subtotals, not a pool:
+    // `cs`/`cf` there would override `critical`/`fumble` on dropped sub-roll
+    // dice. Single-sub-roll groups pass through as the flat-pool form
+    // (`{1d20}kh1cs>18` ≡ `(1d20)kh1cs>18`). Must run before `containsDicePool`,
+    // which recurses into `Group`.
     this.rejectGroupTarget(
       target,
       token,
@@ -880,10 +1018,9 @@ export class Parser {
       true,
     );
 
-    // Shallow dice-pool check (bare dice only) — rejects `(1d6+2d8)cs>5`,
-    // `5cs`, `(1+2)cs`, `floor(5)cs`. Matches explode/reroll behavior.
-    // Note: if `target` already is a `CritThresholdNode`, `containsDicePool`
-    // recurses into its `target`, so chained `cs`/`cf` naturally pass.
+    // Shallow check like explode/reroll: `(1d6+2d8)cs>5`, `5cs`, `(1+2)cs`, and
+    // `floor(5)cs` reject. Chained `cs`/`cf` still pass, since `containsDicePool`
+    // recurses into a `CritThreshold`'s own target.
     if (!containsDicePool(target)) {
       throw new ParseError(
         `Crit threshold modifier requires a dice pool target`,
@@ -893,11 +1030,9 @@ export class Parser {
       );
     }
 
-    // Bare `cs`/`cf` resolve to a per-die default that assumes max-side / 1
-    // semantics — incompatible with Fate dice (`{-1, 0, +1}`), where the bare
-    // fumble check would flip the best face (`+1`) into a fumble. Custom
-    // thresholds with explicit ComparePoints remain accepted. Mirrors the
-    // Fate-explosion rejection above.
+    // The bare `cs`/`cf` per-die default assumes max-side/1 semantics, which on
+    // Fate's `{-1, 0, +1}` would flag the best face (`+1`) as a fumble. Explicit
+    // ComparePoints stay accepted. Mirrors the Fate-explosion reject above.
     if (!this.isComparePointAhead() && containsFatePool(target)) {
       throw new ParseError(
         `Bare cs/cf cannot apply to Fate dice`,
@@ -912,23 +1047,27 @@ export class Parser {
       : 'default';
     const end = threshold === 'default' ? token.end : (threshold.value.end ?? token.end);
 
-    // ? Unwrap parens so `(1d20cs>19)cs=1` chains into the inner node. Without
-    //   unwrapping, the outer `cs` would create a second CritThresholdNode
-    //   wrapping the Grouped — the collapse-into-single-node design decision
-    //   from STAGE3.md §"CritThreshold Collects Multiple Thresholds" would
-    //   be subtly broken for any user who parenthesizes the chain.
+    // Unwrap parens so `(1d20cs>19)cs=1` collapses into the inner node instead of
+    // nesting a second `CritThreshold` around the `Grouped` — every threshold in
+    // a chain must collect on one node, which parenthesizing would break.
     let chainTarget: ASTNode = target;
     while (chainTarget.type === 'Grouped') {
       chainTarget = chainTarget.expression;
     }
     if (isCritThreshold(chainTarget)) {
-      if (token.type === TokenType.CRIT_SUCCESS) {
-        chainTarget.successThresholds.push(threshold);
-      } else {
-        chainTarget.failThresholds.push(threshold);
-      }
-      chainTarget.end = end;
-      return chainTarget;
+      // Rebuilt, not mutated: `NodeSpan` is readonly, and the discarded `Grouped`
+      // wrapper must not leave a stale `end`.
+      const isSuccess = token.type === TokenType.CRIT_SUCCESS;
+      return {
+        ...chainTarget,
+        successThresholds: isSuccess
+          ? [...chainTarget.successThresholds, threshold]
+          : chainTarget.successThresholds,
+        failThresholds: isSuccess
+          ? chainTarget.failThresholds
+          : [...chainTarget.failThresholds, threshold],
+        end,
+      };
     }
 
     return {
@@ -945,9 +1084,9 @@ export class Parser {
     // Success counting is terminal: chaining (`>=5>=3`) has no semantics.
     this.rejectSuccessCountTarget(target, token);
 
-    // Reject non-pool targets like `1>=3`, `(1+2)>=3`, `(1d6*2)>=10`, or
-    // `(1d20 vs 15)>=1`. Success counting operates on a raw dice pool; any
-    // arithmetic or composition wrapping would be silently ignored.
+    // Success counting reads a raw pool, so arithmetic or composition wrappers
+    // (`1>=3`, `(1+2)>=3`, `(1d6*2)>=10`, `(1d20 vs 15)>=1`) would be silently
+    // ignored.
     if (!containsDicePool(target)) {
       throw new ParseError(
         `Success counting requires a dice pool target`,
@@ -958,42 +1097,49 @@ export class Parser {
     }
 
     const operator = this.getCompareOp(token);
-    // ? Threshold binding: `BP.DICE_LEFT` — see `parseComparePoint` JSDoc.
+    // Threshold binds at `BP.DICE_LEFT` — see `parseComparePoint` TSDoc.
     const value = this.parseExpression(BP.DICE_LEFT);
     this.rejectSuccessCountTarget(value, token);
-    this.rejectVersusTarget(value, token);
-    const node: SuccessCountNode = {
+    this.rejectVersusMetaOperand(value, token);
+    const start = target.start ?? token.position;
+    const end = value.end ?? token.end;
+
+    if (this.peek().type !== TokenType.FAIL) {
+      return { type: 'SuccessCount', target, threshold: { operator, value }, start, end };
+    }
+
+    this.advance();
+    const failThreshold = this.parseFailThreshold(token);
+
+    return {
       type: 'SuccessCount',
       target,
       threshold: { operator, value },
-      start: target.start ?? token.position,
-      end: value.end ?? token.end,
+      failThreshold,
+      start,
+      end: failThreshold.value.end ?? end,
     };
+  }
 
-    if (this.peek().type === TokenType.FAIL) {
-      this.advance();
-      if (this.isComparePointAhead()) {
-        node.failThreshold = this.parseComparePoint();
-      } else {
-        // ? Same threshold binding as above (BP.DICE_LEFT).
-        const failValue = this.parseExpression(BP.DICE_LEFT);
-        this.rejectSuccessCountTarget(failValue, token);
-        this.rejectVersusTarget(failValue, token);
-        node.failThreshold = { operator: '=', value: failValue };
-      }
-      node.end = node.failThreshold.value.end ?? node.end ?? token.end;
-    }
+  /** Parses the `f...` suffix of a success count. Bare `fN` means `f=N`. */
+  private parseFailThreshold(token: Token): ComparePoint {
+    if (this.isComparePointAhead()) return this.parseComparePoint();
+
+    // Same threshold binding as `parseComparePoint` (BP.DICE_LEFT).
+    const failValue = this.parseExpression(BP.DICE_LEFT);
+    this.rejectSuccessCountTarget(failValue, token);
+    this.rejectVersusMetaOperand(failValue, token);
 
-    return node;
+    return { operator: '=', value: failValue };
   }
 
   private parseVersus(left: ASTNode, token: Token): VersusNode {
     this.rejectSuccessCountTarget(left, token);
 
-    // ? Chained `a vs b vs c` has no semantics — a degree is a scalar, not a
-    //   comparable. Unwrap `Grouped` so `(a vs b) vs c` rejects at parse
-    //   time like the bare form; paren-nested DC (`a vs (b vs c)`) is still
-    //   caught by the evaluator via `mergeContext`.
+    // A degree is a scalar, not a comparable, so `a vs b vs c` has no semantics.
+    // Unwrapping `Grouped` makes `(a vs b) vs c` reject here like the bare form;
+    // a paren-nested DC (`a vs (b vs c)`) is caught later by the evaluator's
+    // `mergeContext`.
     let leftChain: ASTNode = left;
     while (leftChain.type === 'Grouped') {
       leftChain = leftChain.expression;
@@ -1014,12 +1160,14 @@ export class Parser {
     };
   }
 
+  //
   // * Compare point utilities
+  //
 
   /**
    * Checks whether the next token is a comparison operator.
    */
-  isComparePointAhead(): boolean {
+  private isComparePointAhead(): boolean {
     const type = this.peek().type;
     return (
       type === TokenType.GREATER ||
@@ -1044,7 +1192,7 @@ export class Parser {
    * @returns A ComparePoint with the operator and value AST node
    * @throws {ParseError} If the next token is not a comparison operator
    */
-  parseComparePoint(): ComparePoint {
+  private parseComparePoint(): ComparePoint {
     const token = this.peek();
     const operator = this.getCompareOp(token);
 
@@ -1052,7 +1200,7 @@ export class Parser {
 
     const value = this.parseExpression(BP.DICE_LEFT);
     this.rejectSuccessCountTarget(value, token);
-    this.rejectVersusTarget(value, token);
+    this.rejectVersusMetaOperand(value, token);
 
     return { operator, value };
   }
@@ -1079,7 +1227,9 @@ export class Parser {
     }
   }
 
+  //
   // * Helpers
+  //
 
   private getOperatorSymbol(token: Token): '+' | '-' | '*' | '/' | '%' | '**' {
     switch (token.type) {
@@ -1136,26 +1286,24 @@ export class Parser {
       case TokenType.CRIT_SUCCESS:
       case TokenType.CRIT_FAIL:
         return BP.MODIFIER;
-      // Comparison operators act as LED-dispatched success-count modifiers
-      // at the Pratt level. Sit below ADD/MUL so arithmetic on a dice pool
-      // completes before success counting wraps it — `5d6+2>4` parses as
-      // `(5d6+2)>4` and then cleanly fails the pool-target guard, rather
-      // than the `>` stealing `2` from the `+`. Inside `parseComparePoint`
-      // (called manually by explode/reroll) this BP is bypassed.
+      // Comparison operators act as LED-dispatched success-count modifiers here;
+      // `parseComparePoint`, called manually by explode/reroll, bypasses this BP.
+      // See `BP.COMPARE` for why it sits below ADD/MUL.
       case TokenType.GREATER:
       case TokenType.GREATER_EQUAL:
       case TokenType.LESS:
       case TokenType.LESS_EQUAL:
       case TokenType.EQUAL:
         return BP.COMPARE;
+      // `min`/`max` double as postfix per-die clamps (`4d6min2`); every
+      // other function name terminates the expression like punctuation.
+      case TokenType.FUNCTION:
+        return token.value === 'min' || token.value === 'max' ? BP.MODIFIER : -1;
       case TokenType.RPAREN:
       case TokenType.EOF:
-      // Punctuation and keywords that terminate expressions
       case TokenType.COMMA:
-      case TokenType.FUNCTION:
-      // Group boundaries: `}` closes the current group (consumed inside
-      // `parseGroup`), and a stray `{` after a complete expression is an
-      // error. Both terminate the outer Pratt loop at -1.
+      // `}` is consumed inside `parseGroup`, and a stray `{` after a complete
+      // expression is an error — both must terminate the outer Pratt loop.
       case TokenType.LBRACE:
       case TokenType.RBRACE:
         return -1;
@@ -1196,10 +1344,10 @@ export class Parser {
     return token;
   }
 
-  private expect(type: TokenType): Token {
+  private expect(type: ExpectableToken): Token {
     const token = this.peek();
     if (token.type !== type) {
-      const expected = TOKEN_DISPLAY[type] ?? TokenType[type];
+      const expected = TOKEN_DISPLAY[type];
       const got = token.type === TokenType.EOF ? 'end of input' : `'${token.value}'`;
       throw new ParseError(
         `Expected ${expected} but got ${got}`,
@@ -1217,20 +1365,49 @@ export class Parser {
 }
 
 /**
- * Parse a dice notation string into an AST.
+ * Parses a dice notation string into an {@link ASTNode} tree, lexing it first.
+ *
+ * {@link evaluate} never mutates the AST, so parse once and evaluate many times
+ * when rolling the same notation repeatedly — that skips the lexer and parser
+ * on every roll after the first. Use `parse` alone to validate notation
+ * without consuming randomness.
  *
  * @param notation - The dice notation to parse
- * @returns The root AST node
+ * @returns The root AST node, with `start`/`end` spans on every node
  * @throws {LexerError} If the input contains invalid characters
  * @throws {ParseError} If the input has invalid syntax
+ * @throws {RollParserError} `INVALID_NOTATION_TYPE` when `notation` is not a
+ *   string — raised before lexing, so it carries no position
  *
  * @example
  * ```typescript
- * const ast = parse('2d6+3');
- * // { type: 'BinaryOp', operator: '+',
- * //   left: { type: 'Dice', count: 2, sides: 6 },
- * //   right: { type: 'Literal', value: 3 } }
+ * import { parse } from 'roll-parser';
+ *
+ * parse('2d6+3');
+ * // {
+ * //   type: 'BinaryOp', operator: '+', start: 0, end: 5,
+ * //   left: {
+ * //     type: 'Dice', start: 0, end: 3,
+ * //     count: { type: 'Literal', value: 2, start: 0, end: 1 },
+ * //     sides: { type: 'Literal', value: 6, start: 2, end: 3 },
+ * //   },
+ * //   right: { type: 'Literal', value: 3, start: 4, end: 5 },
+ * // }
+ * ```
+ *
+ * `count` and `sides` are full nodes, not numbers — that is what makes
+ * computed dice like `(1d4)d6` expressible.
+ *
+ * @example Parse once, roll many
+ * ```typescript
+ * import { evaluate, parse, SeededRNG } from 'roll-parser';
+ *
+ * const ast = parse('4d6kh3');
+ * const rng = new SeededRNG('demo');
+ * const scores = Array.from({ length: 6 }, () => evaluate(ast, rng).total);
  * ```
+ *
+ * @category Core
  */
 export function parse(notation: string): ASTNode {
   const tokens = lex(notation);