roll-parser 2.3.2 → 3.0.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [3.0.0-beta.0] - 2026-07-07
+
+### Changed
+
+- **BREAKING:** package is now ESM-only. The `require` export condition shipped a file that was actually ESM (`bun build --target node` emits ESM), so it only ever worked via Node ≥22 `require(esm)` — which continues to work. Bundles are built with `--target node` (no `// @bun` pragma) and include linked sourcemaps; type declarations now resolve under `moduleResolution: node16/nodenext`, validated by `@arethetypeswrong/cli` + `publint` in CI ([#119](https://github.com/edloidas/roll-parser/issues/119))
+- **BREAKING:** `cs`/`cf` are now independent overrides (Roll20 semantics). `1d20cf<3` keeps the default nat-20 crit instead of clearing it; `1d20cs>=19` keeps the default nat-1 fumble. The previous replace semantics required chaining `cscf<3` to preserve defaults ([#118](https://github.com/edloidas/roll-parser/issues/118))
+- **BREAKING:** bare `NdXdY` dice chains (e.g. `4d6d1`) are rejected at parse time with `AMBIGUOUS_DICE_CHAIN` instead of silently parsing as `(4d6)d1` — roll 4d6, use the result as a count of d1 dice — which is almost never intended. Use `4d6dl1` to drop dice or `(4d6)d1` for nested dice ([#118](https://github.com/edloidas/roll-parser/issues/118))
+- **BREAKING:** non-finite totals (`Infinity`/`NaN`, e.g. `2**1024`) now throw `NON_FINITE_RESULT` instead of returning a non-finite `total` ([#118](https://github.com/edloidas/roll-parser/issues/118))
+- **BREAKING:** `1d1` no longer reports `fumble: true` — a d1 always rolls 1, so it is neither critical nor fumble, mirroring the existing `critical` guard ([#118](https://github.com/edloidas/roll-parser/issues/118))
+
+### Added
+
+- Rich structured `RollResult.parts` output — a 16-variant discriminated union mirroring the AST 1:1, always built during evaluation. Each part carries its sub-total, resolved thresholds/specs (`ModifierSpec`, `ResolvedComparePoint`, `ResolvedCritThreshold`), source span, and (for dice parts) the same `DieResult` objects as `RollResult.rolls`. Group parts under keep/drop carry `keptIndices`; versus parts carry `degree`; successCount parts carry `successes`/`failures` with `total === successes - failures`. JSON-serializable with `parts.total === result.total` guaranteed ([#84](https://github.com/edloidas/roll-parser/issues/84))
+- Source spans: lexer tokens carry an exclusive `end` offset, and every parser-produced AST node carries `start`/`end` offsets (`NodeSpan`) into the notation. `EvaluatorError` is stamped with the span of the tightest failing sub-expression, and the CLI caret uses it — `2d6+1d0+3` points at `1d0` ([#120](https://github.com/edloidas/roll-parser/issues/120))
+- Root exports for the previously missing `GroupNode`/`SortNode`/`CritThresholdNode` types and `isGroup`/`isSort`/`isCritThreshold` guards ([#120](https://github.com/edloidas/roll-parser/issues/120))
+- Benchmark suite (`bun bench`, mitata) covering parse, evaluate, and end-to-end roll paths ([#119](https://github.com/edloidas/roll-parser/issues/119))
+- Coverage thresholds enforced in CI (100% functions, ≥95% lines per file); coverage was previously disabled in `bunfig.toml` and unmeasurable even with `--coverage` ([#119](https://github.com/edloidas/roll-parser/issues/119))
+- CLI prints the notation with a caret under the error position for lexer/parser errors ([#118](https://github.com/edloidas/roll-parser/issues/118))
+- Lexer hints at modifier splits for merged identifiers: `4d6khs` now suggests `kh1s` ([#118](https://github.com/edloidas/roll-parser/issues/118))
+- `"./package.json"` export and `CHANGELOG.md` in the published tarball ([#119](https://github.com/edloidas/roll-parser/issues/119))
+
+### Fixed
+
+- Dropped group sub-rolls no longer leak `success`/`failure` tags into `RollResult.successes`/`failures` — `{2d6>=4, 2d6>=4}kh1` counted successes from the dropped sub-roll, and the rendered output showed `**bold**` markers inside `~~strikethrough~~` ([#118](https://github.com/edloidas/roll-parser/issues/118))
+- `SeededRNG.nextInt` no longer silently truncates ranges above 2^32 — a 53-bit two-draw sampling path covers up to `Number.MAX_SAFE_INTEGER`, and wider ranges throw `RangeError` instead of degrading ([#118](https://github.com/edloidas/roll-parser/issues/118))
+- Deeply nested input (e.g. 20,000 parens) throws a typed `MAX_DEPTH_EXCEEDED` `ParseError` instead of an uncaught `RangeError` stack overflow that broke the `isRollParserError` contract ([#118](https://github.com/edloidas/roll-parser/issues/118))
+- PF2e nat-20/nat-1 upgrade now survives standard (`!`) and penetrating (`!p`) explosion under `vs` — explosion continuation dice no longer make `extractNatural` bail as ambiguous, matching the compound (`!!`) behavior ([#118](https://github.com/edloidas/roll-parser/issues/118))
+- Entire `package.json` (scripts, devDependencies, author email) is no longer embedded in every bundle via the `VERSION` import ([#119](https://github.com/edloidas/roll-parser/issues/119))
+- CLI verbose output no longer leaks markdown for dropped group sub-rolls — `{1d8, 1d10}kh1 -v` printed `{~~1d8[2]~~, ...}` because only single-number spans were rewritten ([#118](https://github.com/edloidas/roll-parser/issues/118))
+- Lexer errors report full code points for astral characters (`🎲` instead of a lone surrogate `�`); parser `expect()` errors name symbols and say `end of input` instead of `Expected RPAREN but got ''` ([#118](https://github.com/edloidas/roll-parser/issues/118))
+- Parser now rejects `SuccessCount` wrapped in meta-expression positions — modifier count, dice count/sides (infix and prefix), Fate/percentile dice count, SuccessCount threshold and bare `fN` value, and compare-point values used by Explode/Reroll. `mergeMetaRolls` also strips `success`/`failure` modifier tags on meta-forwarded dice as defense-in-depth ([#69](https://github.com/edloidas/roll-parser/issues/69))
+- Parser now rejects `Versus` wrapped in the same meta-expression positions so a PF2e `vs` outcome cannot be silently dropped by `mergeMetaRolls`, and the `parseVersus` chain guard unwraps `Grouped` so `(1d20 vs 15) vs 10` throws `NESTED_VERSUS` at parse time instead of at eval ([#70](https://github.com/edloidas/roll-parser/issues/70))
+- Single-sub-roll Group passthrough on `cs`/`cf` no longer smuggles a buried multi-sub Group past the parser. `{{1d20, 1d20}kh1}cs>18`, `{{1d6, 2d8}+0}cs>5`, `{abs({1d6, 2d8})}cs>5`, and `{floor({1d6, 2d8}/1)}cs>5` now reject with `INVALID_CRIT_THRESHOLD_TARGET` via a new `containsMultiSubGroup` deep-walk in `rejectGroupTarget` ([#109](https://github.com/edloidas/roll-parser/issues/109))
+- Single-sub-roll Group passthrough no longer flips Fate `+1` faces to fumble. `{4dF+1d6}cf`, `({4dF+1d6})cf`, and `{abs(4dF)}cf` now reject via a new `deepContainsFatePool` mirror of `deepContainsDicePool` used inside `containsFatePool`'s Group case ([#109](https://github.com/edloidas/roll-parser/issues/109))
+- Single-sub-roll Group passthrough no longer smuggles `Versus` past the meta-expression rejection, so `{1d20 vs 15}cs>18`, `{1d20 vs 15}s`, `{1d20 vs 15}kh1`, `{1+(1d20 vs 15)}cs>18`, `{abs(1d20 vs 15)}cs>18`, and `4d6>={1d20 vs 15}` now throw `NESTED_VERSUS`. `parseModifier` also gained the `rejectVersusTarget` call it was missing — closing a pre-existing inconsistency where `(1d20 vs 15)kh1` rejected with a different error code while the brace form silently dropped `degree`/`natural` ([#109](https://github.com/edloidas/roll-parser/issues/109))
+
+### Notes
+
+These are intentional behaviours documented for the first time, not changes — semantics are unchanged.
+
+- Sort flattens additive pools: `(2d6+1d8)s` renders as one combined sorted list rather than per-pool brackets. Same applies to wrapped pools like `floor(4d6)s`. Totals are preserved ([#96](https://github.com/edloidas/roll-parser/issues/96))
+- Outer parens drop from `result.expression` when chained `cs`/`cf` thresholds collapse: `(1d20cs>19)cs=1` renders as `1d20cs>19cs=1`. Re-parses to the same AST; only the textual form differs ([#96](https://github.com/edloidas/roll-parser/issues/96))
+
+## [3.0.0-alpha.0] - 2026-04-20
+
+First alpha of the v3 rewrite. Stage 1 (core engine) is complete; Stage 2 (dice mechanics) is largely in place.
+
+### Added
+
+Core engine (Stage 1):
+
+- Lexer and token system ([#3](https://github.com/edloidas/roll-parser/issues/3))
+- Pratt parser and AST types ([#4](https://github.com/edloidas/roll-parser/issues/4))
+- Seedable RNG system with `SeededRNG` (xorshift128) and `MockRNG` helpers ([#5](https://github.com/edloidas/roll-parser/issues/5))
+- AST evaluator with keep/drop modifiers (`kh`, `kl`, `dh`, `dl`) ([#6](https://github.com/edloidas/roll-parser/issues/6))
+- Public `roll(notation, options)` API with `RollResult` / `DieResult` types ([#7](https://github.com/edloidas/roll-parser/issues/7))
+- `roll-parser` CLI with `--help`, `--version`, `--verbose`, `--seed` flags; ESM + CJS dual build ([#8](https://github.com/edloidas/roll-parser/issues/8))
+
+Dice mechanics (Stage 2):
+
+- Percentile dice notation (`d%`) ([#35](https://github.com/edloidas/roll-parser/issues/35))
+- Fate/Fudge dice (`dF`) ([#36](https://github.com/edloidas/roll-parser/issues/36))
+- Math functions: `floor()`, `ceil()`, `round()`, `abs()`, `max()`, `min()` ([#37](https://github.com/edloidas/roll-parser/issues/37))
+- Exploding dice — `!` (standard), `!!` (compound), `!p` (penetrating) — with optional compare points ([#38](https://github.com/edloidas/roll-parser/issues/38))
+- Reroll mechanics (`r`, `ro`) with compare points ([#39](https://github.com/edloidas/roll-parser/issues/39))
+- Success counting / dice pools with `>`, `>=`, `<`, `<=`, `=` operators and `fN` failure tagging ([#40](https://github.com/edloidas/roll-parser/issues/40))
+- PF2e Degrees of Success via the `vs` keyword, with nat-20/1 upgrade/downgrade ([#41](https://github.com/edloidas/roll-parser/issues/41))
+
+### Changed
+
+- **BREAKING:** complete rewrite from v2.x. Public API, semantics, and notation coverage are not compatible with the 2.x line. Pin to `roll-parser@2.3.2` for the legacy implementation.
+- Public API surface trimmed: `Lexer`, `Parser`, `lex`, `TokenType`, `Token`, and mock RNG exports removed from the root entry. `createMockRng` moved to the `roll-parser/testing` subpath. Added typed `RollParserError` base class with `RollParserErrorCode` union and `isRollParserError()` type guard ([#24](https://github.com/edloidas/roll-parser/issues/24))
+
+### Fixed
+
+- Modifier chaining now matches the Roll20 standard: chained modifiers are flattened and each applies independently to the full pool; drop sets are unioned ([#12](https://github.com/edloidas/roll-parser/issues/12))
+- Dice count safety limit via `maxDice` option (default 10,000), enforced across the whole expression to prevent DoS via additive groups like `5000d6+5000d6` ([#19](https://github.com/edloidas/roll-parser/issues/19))
+- Parser and evaluator correctness: duplicate `kept` modifier entries, implicit modifier count defaulting to 1 (`4d6kh` → `4d6kh1`), `critical` flag suppression when `sides === 1`, negative `--seed` CLI values ([#21](https://github.com/edloidas/roll-parser/issues/21))
+
+[Unreleased]: https://github.com/edloidas/roll-parser/compare/v3.0.0-beta.0...HEAD
+[3.0.0-beta.0]: https://github.com/edloidas/roll-parser/releases/tag/v3.0.0-beta.0
+[3.0.0-alpha.0]: https://github.com/edloidas/roll-parser/releases/tag/v3.0.0-alpha.0

package/README.md

@@ -1,210 +1,215 @@
 <h1 align="center">Roll Parser</h1>
 
 <p align="center">
-Parser for classic (2d6+1), simple (2 6 1), and WoD (4d10!>6f1) dice rolls.
+High-performance dice notation parser for tabletop RPGs.<br>
+TypeScript-first, Bun-optimized, Pratt parser architecture.
 </p>
 
-[![Travis Build Status][travis-image]][travis-url]
-[![AppVeyor Build Status][appveyor-image]][appveyor-url]
-[![Coverage Status][coveralls-image]][coveralls-url]
-[![devDependency Status][devdep-image]][devdep-url]
-<!-- [![Dependency Status][dep-image]][dep-url] -->
-
-[![Node.js version][node-image]][node-url]
-[![Project is on npm][npm-image]][npm-url]
-
-## Documentation
-
-Please review the [API documentation](http://edloidas.com/roll-parser/).
-
-## Install
-
-#### Node:
-
-```
-npm install roll-parser
-```
-
-Then in the console or JS file:
-```js
-const rollParser = require('roll-parser');
-```
-
-#### Browser:
-
-```html
-<script src="https://unpkg.com/roll-parser/dist/roll-parser.js"></script>
-```
-Minified version:
-```html
-<script src="https://unpkg.com/roll-parser/dist/roll-parser.min.js"></script>
-```
-
-Then access all functions from `rollParser` object.
+<p align="center">
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-6-blue.svg" alt="TypeScript"></a>
+  <a href="https://bun.sh/"><img src="https://img.shields.io/badge/Bun-1.3+-black.svg" alt="Bun"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-339933.svg" alt="Node.js"></a>
+</p>
 
-#### Console:
+## Status
+
+> **v3 Alpha** — Stages 1–3 (core engine, system compatibility, advanced
+> features incl. rich structured `parts` output) are implemented with 1,000+
+> tests, 100% function coverage, and a property-based test suite.
+>
+> For production use, install [v2.3.2](https://www.npmjs.com/package/roll-parser/v/2.3.2).
+
+## Features
+
+- **Basic dice**: `2d6`, `d20`, `4d6+4`, percentile `d%`, Fate/Fudge `4dF`
+- **Full arithmetic**: `+`, `-`, `*`, `/`, `%`, `**` (also `^`), parentheses
+- **Computed dice**: `(1+1)d(3*2)`, `(1d4)d6`
+- **Keep/Drop**: `4d6kh3`, `2d20kl1`, `4d6dl1`, shorthand `4d6k3`
+- **Exploding dice**: standard `1d6!`, compound `1d6!!`, penetrating `1d6!p`, with compare points `1d6!>=5`
+- **Rerolls**: recursive `2d6r<2`, once `2d6ro<3`
+- **Success counting**: `10d10>=6`, with failure tagging `10d10>=6f1`
+- **PF2e degrees of success**: `1d20+10 vs 25` with nat-20/nat-1 upgrade/downgrade
+- **Math functions**: `floor()`, `ceil()`, `round()`, `abs()`, `max()`, `min()`
+- **Variables**: `1d20+@str`, `1d20+@{sneak attack}`
+- **Grouped rolls**: `{1d8, 1d10}kh1`, `{4d10+5d6}kh2`
+- **Sorting**: `4d6s`, `4d6sd` (display-only)
+- **Crit thresholds**: `1d20cs>=19`, `1d20cf<3` (display-only, independent overrides)
+- **Structured `parts` output**: every result carries a typed evaluation tree mirroring the AST — per-sub-expression totals, dice, resolved thresholds — for chat-log/character-sheet rendering without re-parsing
+- **Source spans**: every AST node and `RollPart` carries `start`/`end` offsets into the notation; evaluator errors point at the exact failing sub-expression
+- **Seedable RNG** (xorshift128) for reproducible rolls, mock RNG for tests
+- **Typed errors** with stable `code`s and input positions
+- **Safety limits**: `maxDice`, `maxExplodeIterations`, `maxRerollIterations`, parse depth cap
+
+## Installation
 
 ```bash
-$ roll-parser [options] [<rolls>]
+bun add roll-parser
+npm install roll-parser
 ```
 
-Run `roll-parser --help` for more details.
+The package is **ESM-only**. On Node.js ≥ 22 (required), CommonJS consumers
+can still `require('roll-parser')` via `require(esm)`.
 
 ## Usage
 
-```js
-const { parse, roll, parseAndRoll, Roll } = require('roll-parser');
-
-// `parse()` function parses any notation and returns `Roll` or `WodRoll` object
-//=> { dice: 6, count: 4, modifier: 1 }
-const parsedRoll = parse('4d6+1');
-
-// `Roll` or `WodRoll` can be stringified
-//=> '4d6+1'
-const rollNotation = parsedRoll.toString();
-
-//=> { notation: '4d6+1', value: 16, rolls: [3, 1, 6, 5] }
-const result1 = roll(parsedRoll);
-//=> { notation: '2d20-3', value: 23, rolls: [11, 15] }
-const result2 = roll(new Roll(20, 2, -3));
-// Can also accept plain objects
-//=> { notation: '2d10>7', value: 1, rolls: [4, 8] }
-const result3 = roll({dice: 10, count: 2, success: 7});
-
-// `parseAndRoll()` function can parse any notation and then roll the dice
-// Any invalid arguments, except `null` or `undefined`, will be parsed as default `Roll`
-//=> { notation: '3d10!>8f1', value: 2, rolls: [3, 10, 7, 9] }
-const result4 = parseAndRoll('3d10!>8f1');
-
-//=> '(3d10!>8f1) 2 [3,10,7,9]'
-const resultNotation = result4.toString();
-```
-
-Specific parsers can be used.
-
-__Classic (D&D):__
-
-```js
-const {
-  parseClassicRoll,
-  rollClassic,
-  parseAndRollClassic,
-  Roll
-} = require('roll-parser');
-
-//=> { dice: 10, count: 1, modifier: 0 }
-const parsedRoll = parseClassicRoll('d10');
-
-//=> { notation: 'd10', value: 7, rolls: [7] }
-const result1 = rollClassic(parsedRoll);
+```typescript
+import { roll } from 'roll-parser';
 
-//=> { notation: '2d20', value: 26, rolls: [11, 15] }
-const result2 = rollClassic(new Roll(20, 2));
-
-//=> { notation: '4d10+1', value: 22, rolls: [4, 6, 2, 9] }
-const result3 = rollClassic({ dice: 10, count: 4, modifier: 1 });
-
-//=> { notation: '3d6', value: 15, rolls: [6, 6, 3] }
-const result4 = parseAndRollClassic('3d6');
+const result = roll('4d6kh3');
+result.total;      // e.g. 14
+result.notation;   // '4d6kh3'
+result.rendered;   // '4d6kh3[3, 6, ~~2~~, 5] = 14'
+result.rolls;      // per-die results with kept/dropped/critical flags
 ```
 
-__WoD (World of Darkness):__
-
-```js
-const {
-  parseWodRoll,
-  rollWod,
-  parseAndRollWod,
-  WodRoll
-} = require('roll-parser');
+### Options
 
-//=> { dice: 10, count: 1, again: false, success: 6, fail: 0 }
-const parsedRoll = parseWodRoll('d10>6');
+```typescript
+import { roll, SeededRNG } from 'roll-parser';
 
-// Returns notation, number of success rolls and list of all dice rolls
-//=> { notation: 'd10', value: 1, rolls: [7] }
-const result1 = rollWod(parsedRoll);
+roll('4d6', { seed: 'character-1' });     // reproducible rolls
+roll('4d6', { rng: new SeededRNG(42) });  // custom RNG instance (takes precedence)
 
-//=> { notation: '4d10>6f1', value: 1, rolls: [4, 10, 5, 2] }
-const result2 = rollWod(new WodRoll(10, 4, false, 6, 1));
+roll('1d20+@str', {
+  context: { str: 4 },                    // variable values
+  onMissingVariable: 'zero',              // or 'throw' (default)
+});
 
-//=> { notation: '4d10!>8f1', value: 22, rolls: [1, 8, 5, 10, 10, 4] }
-const result3 = rollWod({ dice: 10, count: 2, again: true, success: 8, fail: 1 });
-
-//=> { notation: '4d10>7f4', value: 1, rolls: [6, 3, 8, 4] }
-const result4 = parseAndRollWod('4d10>7f4');
+roll('100d6!', {
+  maxDice: 1_000,                         // total dice cap, default 10,000
+  maxExplodeIterations: 100,              // per-die explosion cap, default 1,000
+  maxRerollIterations: 100,               // per-die reroll cap, default 1,000
+});
 ```
 
-__Simple (D&D, space-separated):__
-
-```js
-const { parseSimpleRoll, parseAndRollSimple } = require('roll-parser');
-
-//=> { dice: 10, count: 1, modifier: 0 }
-const parsedRoll = parseSimpleRoll('10');
-
-//=> { notation: '4d10-1', value: 23, rolls: [3, 6, 8, 7] }
-const result = parseAndRollSimple('4 10 -1');
+### Results
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `total` | `number` | Final computed total (always finite — overflow throws) |
+| `notation` | `string` | Original input |
+| `expression` | `string` | Normalized form; meta-expressions render as their resolved values |
+| `rendered` | `string` | Markdown breakdown: `~~n~~` dropped, `**n**` success, `__n__` failure |
+| `rolls` | `DieResult[]` | Every die: `sides`, `result`, `modifiers`, `critical`, `fumble` |
+| `parts` | `RollPart` | Typed evaluation tree mirroring the AST 1:1 (see below) |
+| `successes` / `failures` | `number?` | Present when success counting was used |
+| `degree` / `natural` | `DegreeOfSuccess?` / `number?` | Present for top-level `vs` expressions |
+
+### Structured breakdown (`parts`)
+
+`result.parts` is a discriminated union (16 variants — `dice`, `binaryOp`,
+`modifier`, `versus`, …) where each part holds its own sub-total, resolved
+thresholds/specs, and — for dice parts — the same `DieResult` objects as
+`result.rolls`. JSON-serializable; `parts.total === result.total` always.
+
+```typescript
+const r = roll('4d6kh3 + 2');
+// r.parts = { type: 'binaryOp', operator: '+', total: 16,
+//   left: { type: 'modifier', specs: [{ kind: 'keep', selector: 'highest', count: 3 }],
+//           target: { type: 'dice', count: 4, sides: 6, rolls: [...], ... }, total: 14 },
+//   right: { type: 'literal', value: 2, total: 2 } }
 ```
 
-Random number generator can be used to roll the dice.
+Meta-expressions (`(1d4)d6` counts, computed thresholds) appear as resolved
+numbers in the owning part; their dice live in `result.rolls` tagged `'meta'`.
 
-```js
-const { random } = require('roll-parser');
+### Error handling
 
-//=> 84 - d100-like roll
-random(100);
+All errors extend `RollParserError` with a typed `code`
+(e.g. `DICE_LIMIT_EXCEEDED`, `DIVISION_BY_ZERO`, `AMBIGUOUS_DICE_CHAIN`);
+lexer and parser errors also carry the input `position`.
 
-//=> 7 - d10-like roll
-random(10);
+```typescript
+import { isRollParserError } from 'roll-parser';
 
-//=> [2, 5, 2, 6] - 4d6-like roll
-[...Array(4)].map(() => random(6));
+try {
+  roll(userInput);
+} catch (error) {
+  if (isRollParserError(error)) console.error(error.code, error.message);
+}
 ```
 
-Even so the parse&roll functions uses checks to convert non-standard objects to `Roll` or `WodRoll`, explicit conversion can be used in some cases:
-
-```js
-const { convert } = require('roll-parser');
+### Testing your integrations
 
-//=> new Roll(undefined, 4, -3)
-convert({ count: 4, modifier: -3 });
+```typescript
+import { createMockRng } from 'roll-parser/testing';
 
-//=> new WodRoll(10, 6, true, undefined, 2)
-convert({ dice: 10, count: 6, again: true, fail: 2 });
+const result = roll('3d6', { rng: createMockRng([4, 2, 6]) });
+result.total; // 12 — throws if the roll consumes more values than provided
 ```
 
-## Releases
-
-Please review the [changelog](https://github.com/edloidas/roll-parser/releases).
+### CLI
 
-## Contributing
+```bash
+roll-parser 2d6+3
+roll-parser 4d6kh3 --verbose --seed test
+roll-parser --help
+```
 
-♥ [roll-parser](https://github.com/edloidas/roll-parser) and want to get involved?<br>
-Please, check the [guide](CONTRIBUTING.md) first.
+## Notation reference
+
+| Notation | Meaning |
+|----------|---------|
+| `NdX`, `dX`, `Nd%`, `NdF` | Roll N X-sided / percentile / Fate dice |
+| `khN` `klN` `dhN` `dlN` (`kN`) | Keep/drop highest/lowest N (default 1) |
+| `!` `!!` `!p` | Explode: standard / compound / penetrating (optional `>=T` etc.) |
+| `r<T`, `ro<T` | Reroll recursively / once while condition matches |
+| `>=T`, `>T`, `=T`, `<T`, `<=T` | Count successes against threshold (terminal) |
+| `fT`, `f<T` | Failure threshold after success counting |
+| `vs DC` | PF2e degree of success against a DC |
+| `s`, `sd` | Sort dice ascending/descending (display-only) |
+| `csT`, `cfT` | Override crit/fumble display thresholds independently |
+| `@name`, `@{any name}` | Variable from `context` |
+| `{a, b}khN` | Grouped rolls; keep/drop by sub-roll subtotal |
+| `floor() ceil() round() abs() max() min()` | Math functions |
+
+## Performance
+
+Run `bun bench` for the mitata suite (parse, evaluate, and end-to-end paths).
+Indicative numbers on a modern x86-64 container (Bun 1.3):
+
+| Operation | Time |
+|-----------|------|
+| `parse('2d6+3')` | ~0.4 µs |
+| `roll('1d20+5')` | ~2.5 µs (~400k rolls/s) |
+| `roll('4d6kh3')` | ~5 µs |
+| `evaluate(parse('100d6'))` | ~17 µs |
+
+Numbers include building the structured `parts` tree (always on).
+
+## Known Limitations
+
+- **`4d6d1` is a parse error, not "drop 1".** The bare `d` token is the dice
+  operator, and `4d6d1` reading as "roll 4d6, use the result as a count of
+  d1 dice" is a silent trap — so chaining `d` directly onto a dice expression
+  throws `AMBIGUOUS_DICE_CHAIN`. Use `4d6dl1` to drop dice, or `(4d6)d1` for
+  nested dice.
+- **Threshold comparisons bind tight.** In explode and reroll thresholds,
+  `1d6!>=5+2` parses as `(1d6!>=5)+2` — the comparison binds to the dice
+  pool, not the arithmetic after it. For a computed threshold, parenthesize:
+  `1d6!>=(5+2)`. Success-count thresholds bind the same way, but wrapping the
+  resulting `SuccessCountNode` is a parse error (terminal by design), so
+  `1d6>=5+2` throws — parenthesize: `1d6>=(5+2)`.
+- **Meta-expressions in `result.expression` are substituted with their
+  resolved values.** Dice counts, sides, modifier counts, and threshold
+  expressions are rendered as the integer they evaluated to — so
+  `result.expression` does not round-trip through `parse` when
+  meta-expressions are present.
+
+  ```typescript
+  roll('(1d4)d6').expression;       // '2d6' (if 1d4 rolled 2)
+  roll('1d6!>(1d2+3)').expression;  // '1d6!>5'
+  ```
+
+- **Sort flattens additive pools and drops per-pool brackets.** `(2d6+1d8)s`
+  renders the combined pool as one sorted list — `(2d6 + 1d8)s[3, 4, 5]` —
+  rather than the per-pool form `2d6[3, 4] + 1d8[5]`. Totals are preserved;
+  only the rendered breakdown loses pool boundaries.
+- **Outer parens drop from `result.expression` after threshold collapse.**
+  `(1d20cs>19)cs=1` evaluates with `result.expression = '1d20cs>19cs=1'`
+  because chained `cs` thresholds collapse into a single node. The notation
+  re-parses to the same AST; only the textual form differs.
 
 ## License
 
 [MIT](LICENSE) © [Mikita Taukachou](https://edloidas.com)
-
-<!-- Links -->
-[travis-url]: https://travis-ci.org/edloidas/roll-parser
-[travis-image]: https://img.shields.io/travis/edloidas/roll-parser.svg?label=linux%20build
-
-[appveyor-url]: https://ci.appveyor.com/project/edloidas/roll-parser
-[appveyor-image]: https://img.shields.io/appveyor/ci/edloidas/roll-parser.svg?label=windows%20build
-
-[coveralls-url]: https://coveralls.io/github/edloidas/roll-parser?branch=master
-[coveralls-image]: https://coveralls.io/repos/github/edloidas/roll-parser/badge.svg?branch=master
-
-[dep-url]: https://david-dm.org/edloidas/roll-parser
-[dep-image]: https://david-dm.org/edloidas/roll-parser.svg
-
-[devdep-url]: https://david-dm.org/edloidas/roll-parser#info=devDependencies
-[devdep-image]: https://david-dm.org/edloidas/roll-parser/dev-status.svg
-
-[node-url]: https://nodejs.org
-[node-image]: https://img.shields.io/badge/node-≥%206.0.0-green.svg
-
-[npm-url]: https://www.npmjs.com/package/roll-parser
-[npm-image]: https://img.shields.io/badge/npm-roll--parser-blue.svg

package/dist/cli/args.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CLI argument parser.
+ *
+ * Pure function that parses process.argv-style string arrays into typed options.
+ *
+ * @module cli/args
+ */
+/**
+ * Parsed CLI arguments.
+ */
+export type CliArgs = {
+    notation: string | undefined;
+    verbose: boolean;
+    seed: string | undefined;
+    showHelp: boolean;
+    showVersion: boolean;
+};
+/**
+ * Result of parsing CLI arguments — either success or a usage error.
+ */
+export type ParseArgsResult = {
+    ok: true;
+    args: CliArgs;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parses a raw argument array into typed CLI options.
+ *
+ * @param argv - Arguments to parse (typically `process.argv.slice(2)`)
+ * @returns Parsed result or an error message for usage errors
+ */
+export declare function parseArgs(argv: string[]): ParseArgsResult;
+//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CA0CzD"}

package/dist/cli/format.d.ts

@@ -0,0 +1,20 @@
+/**
+ * CLI output formatting.
+ *
+ * Transforms RollResult into terminal-appropriate strings.
+ *
+ * @module cli/format
+ */
+import type { RollResult } from '../types.js';
+/**
+ * Formats a roll result for terminal display.
+ *
+ * In normal mode, returns just the total. In verbose mode, returns the
+ * rendered breakdown with terminal-safe formatting for dropped dice.
+ *
+ * @param result - The roll result to format
+ * @param verbose - Whether to show the detailed breakdown
+ * @returns Formatted string for terminal output
+ */
+export declare function formatResult(result: RollResult, verbose: boolean): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/cli/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/cli/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAMzE"}

package/dist/cli/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for roll-parser.
+ *
+ * @module cli/index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;;;GAIG"}