roll-parser 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.2.0] - 2026-08-09
+
+Every entry below is a correctness fix, but several change what a working
+expression returns and five group forms that used to evaluate now throw.
+[MIGRATION.md](MIGRATION.md#upgrading-from-310-to-320) walks each one with a
+rewrite. Seeds are untouched: the same seed and notation roll the same faces
+they did in 3.1.0.
+
+### Fixed
+
+- Success counting a multi-sub-roll group now scores one success per sub-roll subtotal, the way keep/drop on the same node always did, so `{2d6, 2d6}>=10` finds the 11 it was missing. The dice stop being the units: `rendered` shows each sub-roll's own bracket, `rolls[].modifiers` comes back untagged, and `fT` thresholds weigh subtotals too. Targets whose arithmetic no per-die comparison ever reaches — `{3d20+5}>=21`, `{2d6*2}>=4`, `{2d6, 2d8}kh1>=4` — throw `INVALID_SUCCESS_COUNT_TARGET` instead of comparing faces against a number the sub-roll's math never produced ([#303](https://github.com/edloidas/roll-parser/issues/303))
+- A second success count reaching the same pool through group braces (`{4d6>=5f1}<=2f6`) now re-scores it outright rather than appending to the inner pass's tags, so no die comes back both `'success'` and `'failure'` and `successes`/`failures` describe `total` again. The outermost count owns the tags; dropped dice come out untagged, while the DC side of a `vs` keeps tags from an inner count, since no pool pass may tally it. `total` never moved ([#297](https://github.com/edloidas/roll-parser/issues/297))
+- Success counting a group that can never roll a die (`{3, 5, 7}>=4`, `{3, 5, 7}kh1>=4`) now throws `INVALID_SUCCESS_COUNT_TARGET` instead of returning the group's sum with `successes: 0`, which read the documented `successCount.total === successes - failures` invariant as `15 === 0`. A pool that is empty only at run time (`{3, 0d6}>=4`) totals 0 rather than the literal sum ([#304](https://github.com/edloidas/roll-parser/issues/304))
+- Keep/drop on a single-sub-roll group whose total is not the sum of its kept faces now throws `INVALID_KEEP_DROP_TARGET` instead of silently discarding the rest of the arithmetic. `{2d6+3}kh2` lost the `+3`, and `{2d6-1d4}kh3` — which drops nothing — flipped the `1d4` from `-3` to `+3`; `{2d6*2}kh2` and `{abs(1d6-1d8)}kh1` are refused for the same reason `(2d6+3)kh2` already was. The check is structural, so identity terms (`{2d6+0}kh2`) go with them. Additive pools (`{4d6+2d8}kh3`) and multi-sub-roll groups, which select on subtotals, are untouched. A brace-wrapped success count now reports `INVALID_SUCCESS_COUNT_TARGET` at any nesting depth, matching what `(4d6>=5)kh1` always did ([#302](https://github.com/edloidas/roll-parser/issues/302))
+- Penetrating explosion now records the face it rolled in `initialResult` on every die it appends, so the `initialResult ?? result` idiom `DieResult` documents recovers the natural face instead of the stored `raw - 1` — a natural 20 was indistinguishable from a 19. Bare `cs`/`cf` consequently judges a `!p` continuation by that face, so `1d6cf>5!p` and `1d6!pcf>5` agree where the README documented them as disagreeing. Separately, a `vs` roll whose explosion dice are clamped by `minN`/`maxN` (`1d20!min5 vs 30`) stops misreading the continuation as a second primary d20, which had been suppressing the natural-20/1 step ([#300](https://github.com/edloidas/roll-parser/issues/300))
+- `cs`, `cf`, `s`, and `sd` adjacent to another modifier now keep a space in `expression` and `rendered`, so the normalized string re-parses. Those four codes end in a letter the lexer scans as an identifier, so maximal munch swallowed whatever followed: `1d20cs cf` normalized to `1d20cscf` and `4d6 s kh2` to `4d6s kh2`, neither of which round-trips through `parse`. `4dF` and `!p` end in letters but are their own tokens and stay flush ([#299](https://github.com/edloidas/roll-parser/issues/299))
+- Demo site: the equation chip keeps explode and reroll dice. It read only `sort` out of the part tree, so any other pool-bearing modifier's dice went missing from the chip ([#313](https://github.com/edloidas/roll-parser/issues/313))
+
+### Documentation
+
+- `MIGRATION.md` gains a 3.1.0 → 3.2.0 section covering all five newly rejected forms with a rewrite for each, plus the values that moved: `initialResult` on `!p` dice, one `vs` degree, the `expression`/`rendered` spacing, and the totals and tags of nested and grouped success counts ([#300](https://github.com/edloidas/roll-parser/issues/300), [#293](https://github.com/edloidas/roll-parser/issues/293))
+- README gains a `Reading crit and fumble` subsection showing the per-die loop over `result.rolls`, with `site/src/dice.ts` named as the working in-repo example. It documents the four traps such a loop hits — `'meta'` dice must be filtered, `'dc'` dice need a deliberate choice, `rendered` must never be spliced by bracket position, and the default crit rule fires on every pool's max face — and names `rendered`'s markdown as Discord-flavored, pointing at `renderBreakdown` for other dialects ([#293](https://github.com/edloidas/roll-parser/issues/293))
+- README's `## Contents` is a grouped two-level index, and the seven overlapping notation-rejection bullets are folded into one table with a `Write instead` column. The nested-count tag-ownership rule moved to `RollResult`, where the fields it describes live ([#293](https://github.com/edloidas/roll-parser/issues/293))
+
+## [3.1.0] - 2026-08-08
+
+### Added
+
+- `roll-parser/render`, a subpath export holding `renderBreakdown(result, marks?)`, `DieMarks`, and `MARKDOWN_MARKS`. It rebuilds the `RollResult.rendered` breakdown from `RollResult.parts` with markers the caller chooses, so consumers targeting anything other than Discord markdown no longer regex-parse the baked string. Six slots — `dropped`, `success`, `failure`, `critical`, `fumble`, and `droppedGroup` — compose in a fixed order; `critical`/`fumble` read the `DieResult` booleans, which `rendered` has no marker for. With no `marks` the output is byte-identical to `rendered`, pinned by a property test. Budgeted separately at 2 kB, leaving the `index.js` and `{ roll }` budgets to the library ([#292](https://github.com/edloidas/roll-parser/issues/292))
+
+### Changed
+
+- The `explode`, `reroll`, and `successCount` members of `RollPart` now carry `rolls: DieResult[]`, the pool the modifier produced — mirroring what `sort` already did. Standard and penetrating explosions and both reroll forms append dice that appear nowhere under `target`, so the part tree could not previously describe its own output ([#292](https://github.com/edloidas/roll-parser/issues/292))
+
+  Reading `parts` is unaffected. Three things do change:
+
+  - Code that **constructs** one of those three parts stops compiling — `TS2322: Property 'rolls' is missing in type … but required`. Add the pool, or widen the annotation.
+  - Deep-equality assertions against those parts need the new field.
+  - `--json` and `JSON.stringify(result)` payloads grow for expressions using explode, reroll, or success counting, since the pool is serialized on the modifier as well as its target — roughly +40% to +96% depending on pool size. Expressions without those modifiers are unchanged.
+
+- performance: the per-die `isVersusDc` check is now skipped entirely for notation that cannot carry a `'dc'` tag, `sortDice` scans before allocating instead of running an unconditional `filter`, and `countSuccesses` filters DC dice up front rather than guarding inside the loop. Sort notation had no benchmark coverage, which is why the regression shipped unseen; `4d6sd`, `10d10sd`, `100d6sa`, and `10d10sd>=6f1` now have bench cases ([#281](https://github.com/edloidas/roll-parser/issues/281))
+
+### Fixed
+
+- Bare `cs`/`cf` now judge the natural face (`initialResult ?? result`) rather than a value a preceding modifier rewrote, matching what the documentation always claimed. Compound explode also stopped clobbering the raw face recorded by an earlier `minN`/`maxN` clamp, which made `1d6min6!!cs` report a false critical. Explicit thresholds deliberately keep reading `result`, so the two kinds can disagree on one die ([#288](https://github.com/edloidas/roll-parser/issues/288))
+- `cs`/`cf` thresholds now apply to dice minted by explode and reroll, which previously fell back to the built-in default rule. Each resolved rule is recorded per die and inherited by appended and replacement dice, so a further explode or reroll inherits it in turn. Overriding one side no longer moves the other: `1d6cf>5!p` keeps the `critical` that plain `1d6!p` gives the appended die ([#289](https://github.com/edloidas/roll-parser/issues/289))
+- Chained same-kind bounds (`1d6min2min3`) no longer push duplicate `'min'`/`'max'` modifiers onto a die, and `initialResult` still comes from the first bound that moved it. The same duplication is fixed for `'success'`/`'failure'` on a group counted after its members (`{4d6>=5}>=1`) and for `'meta'` on nested meta operands (`((1d2)d4)d6`) ([#290](https://github.com/edloidas/roll-parser/issues/290))
+- CLI `--verbose` no longer mangles a dropped group sub-roll nested inside another dropped group sub-roll. `{{1d6, 1d8}kh1, {1d10, 1d12}kh1}kh1` rendered as `({)1d10[1](, 1d12[3]})`; the marker rewrite was a regex over the flat string and stopped at the first inner `~~`. It now reads the structure and emits `({(1d10[1]), 1d12[3]})` ([#292](https://github.com/edloidas/roll-parser/issues/292))
+- Demo site: fractional totals are rounded to four decimals — falling back to exponential where rounding would show a non-zero total as `0` — with the exact value on a `title` attribute, instead of overflowing the result card ([#285](https://github.com/edloidas/roll-parser/issues/285))
+- Demo site: the total count-up is gated on `Number.isSafeInteger`, so an astronomical total lands without animating rather than interpolating through to `0` ([#286](https://github.com/edloidas/roll-parser/issues/286))
+
+### Documentation
+
+- `MIGRATION.md` gains a 3.0.0 → 3.1.0 section covering the `RollPart` field, the three ways it can surface, and the new render subpath. The file is now ordered newest-first with an index, and `README.md` points at it for every upgrade path rather than only for 2.x ([#292](https://github.com/edloidas/roll-parser/issues/292))
+- `DieResult.critical` and `DieResult.fumble` now scope the max-face/1 default to `sides > 1`, so neither claims to fire on `d1` or Fate dice, and the `FateDiceNode` / `createFateDieResult` TSDoc no longer states the flags are never set on Fate dice — an explicit `4dFcs>0` or `4dFcf=-1` does set them ([#291](https://github.com/edloidas/roll-parser/issues/291))
+- The README no longer implies success counting rejects every enclosing expression — it is terminal only against direct wrapping
+- The README performance table gained a `4d6sd` row and links the published benchmark trend, and the Node badge reads from the published `engines` range
+
 ## [3.0.0] - 2026-08-06
 
 First stable release of the v3 rewrite. This section covers what changed since
@@ -183,7 +241,9 @@ Dice mechanics (Stage 2):
 - 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...HEAD
+[Unreleased]: https://github.com/edloidas/roll-parser/compare/v3.2.0...HEAD
+[3.2.0]: https://github.com/edloidas/roll-parser/releases/tag/v3.2.0
+[3.1.0]: https://github.com/edloidas/roll-parser/releases/tag/v3.1.0
 [3.0.0]: https://github.com/edloidas/roll-parser/releases/tag/v3.0.0
 [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/MIGRATION.md

@@ -1,4 +1,295 @@
-# Migrating from v2 to v3
+# Migration notes
+
+Newest first.
+
+- [Upgrading from 3.1.0 to 3.2.0](#upgrading-from-310-to-320)
+- [Upgrading from 3.0.0 to 3.1.0](#upgrading-from-300-to-310)
+- [Migrating from v2 to v3](#migrating-from-v2-to-v3)
+- [Upgrading from a v3 pre-release](#upgrading-from-a-v3-pre-release)
+
+## Upgrading from 3.1.0 to 3.2.0
+
+Nothing was removed from the API, no type changed, and the seed → dice mapping
+is untouched — the same seed and notation roll the same faces they did in
+3.1.0. What moves falls in two buckets. Several group forms that used to
+evaluate now throw a parse error — `{3, 5, 7}>=4`, `{2d6+3}kh2`, `{2d6*2}kh2`,
+`{3d20+5}>=21`, and `{2d6, 2d8}kh1>=4` — each listed below with a rewrite. The
+rest are values that moved: `initialResult` on `!p` dice, one `vs` degree, the
+`expression` and `rendered` strings, and the totals and tags of nested and
+grouped success counts.
+
+**`!p` continuation dice now carry `initialResult`.** A penetrating explosion
+stores `raw - 1` on each die it appends, and used to record the face it
+replaced nowhere, so the `initialResult ?? result` idiom `DieResult` documents
+returned the decremented value and a natural 20 was indistinguishable from a
+19.
+
+```typescript
+import { roll } from 'roll-parser';
+import { createMockRng } from 'roll-parser/testing';
+
+const die = roll('1d20!p', { rng: createMockRng([20, 20, 5]) }).rolls[1];
+
+die.result; // 19
+die.initialResult; // 20 — was `undefined`
+```
+
+Standard `!` is unchanged: its appended dice store what they rolled, so they
+still carry no `initialResult`. Two things can bite:
+
+- **Deep-equality assertions against a `!p` pool fail.** The appended dice gain
+  a field. Assert on what you care about, or add `initialResult` to the
+  expected die.
+- **`--json` and `JSON.stringify(result)` payloads grow** by one number per
+  appended `!p` die. Expressions without `!p` are unchanged.
+
+**Bare `cs`/`cf` judges a `!p` die by the face it rolled.** The side you do not
+override reads the natural face, which now exists on these dice — so a
+continuation that rolled its maximum is critical even though it displays one
+less, matching the flags plain `1d6!p` already set.
+
+```typescript
+const result = roll('1d6!pcf>5', { rng: createMockRng([6, 6, 3]) });
+
+result.rendered; // '1d6!pcf>5[6, 5, 2] = 13'
+result.rolls[1].critical; // true — was `false`, judged by the stored 5
+```
+
+If you assert `critical` or `fumble` on `!p` continuation dice, re-derive the
+expected flag from `initialResult ?? result`. Order stops mattering here:
+`1d6cf>5!p` and `1d6!pcf>5` now agree, where 3.1.0's README documented them as
+disagreeing, and [Modifiers](README.md#modifiers) is rewritten to match. An
+explicit threshold is still a predicate over a die's current `result`, so `!!`,
+`minN`, and `maxN` remain order-sensitive.
+
+**Adjacent bare modifiers keep a space in `expression` and `rendered`.** `cs`,
+`cf`, `s`, and `sd` with no threshold or count end in a letter the lexer scans
+as an identifier, so the normalized form used to re-lex as one token and no
+longer round-tripped through `parse`.
+
+```typescript
+roll('1d20cs cf', { rng: createMockRng([20]) }).expression; // '1d20cs cf' — was '1d20cscf'
+roll('4d6 s kh2', { rng: createMockRng([1, 2, 3, 4]) }).rendered;
+// '4d6s[~~1~~, ~~2~~, 3, 4] = 7' — the prefix was '4d6skh2'
+```
+
+Only those four codes are affected; `4dF` and `!p` end in letters but are their
+own tokens, so they stay flush. Snapshot assertions over `expression` or
+`rendered` for an affected expression need re-recording.
+
+**One `vs` case stops discarding its natural face.** Only `vs` expressions
+whose roll side both appends explosion dice and clamps them — `!` or `!!`
+combined with `minN`/`maxN` — are affected: a clamped continuation used to be
+counted as a second primary d20, and two primaries suppress the natural 20 /
+natural 1 step. Without the clamp (`1d20! vs 30`) the continuation never looked
+like a primary, and those degrees are unchanged.
+
+```typescript
+import { DegreeOfSuccess } from 'roll-parser';
+
+const result = roll('1d20!min5 vs 30', { rng: createMockRng([20, 2, 12]) });
+
+result.natural; // 20 — was `undefined`
+result.degree === DegreeOfSuccess.Success; // true — was `Failure`
+```
+
+If you pinned `natural` or `degree` on such a roll, re-record it.
+
+**Success counting a dice-less group is now a parse error.** `{3, 5, 7}>=4`
+used to return the group's sum with `successes: 0`, so the
+`successCount.total === successes - failures` invariant the README offers read
+`15 === 0`. There are no dice to tally, and whether a group's units should be
+its subtotals is undecided, so the form is refused instead.
+
+```typescript
+roll('{3, 5, 7}>=4'); // throws 'INVALID_SUCCESS_COUNT_TARGET' — was 15
+roll('{3, 5, 7}kh1>=4'); // throws 'INVALID_SUCCESS_COUNT_TARGET' — was 7
+roll('{3, 0d6}>=4').total; // 0 — was 3
+```
+
+Groups holding at least one pool are untouched — `{3, 1d6}>=4` counts the `1d6`
+exactly as it did. `0d6>=4` also still parses and totals 0; only targets that
+can never roll a die are rejected. There is no in-notation rewrite for a
+literal-only group: replace the literals with the pool they stood in for
+(`3d6>=4`), or drop the count and keep the group's sum (`{3, 5, 7}`).
+
+**A second success count re-scores the pool instead of adding to it.** Group
+braces let one count wrap another (`{4d6>=5f1}<=2f6`), which the parse-time
+reject on a direct `4d6>=5>=1` never reached. The inner pass used to leave its
+tags behind, so a die could come back both `'success'` and `'failure'` and the
+top-level counts stopped describing the total. The outermost count now owns the
+tags outright.
+
+```typescript
+const result = roll('{4d6>=5f1}<=2f6', { rng: createMockRng([6, 5, 2, 1]) });
+
+result.total; // 1
+result.successes; // 2 — was 4
+result.failures; // 1 — was 0
+result.rendered; // '{4d6>=5f1}<=2f6[__6__, 5, **2**, **1**] = 1'
+```
+
+`total` never moved — it always came from the outermost count, so a test
+asserting only `total` needs no change. What changed is `successes`,
+`failures`, `rolls[].modifiers`, and `rendered`, which now agree with it, so
+`successCount.total === successes - failures` holds again. A lone
+count is untouched, and so is a nested pair whose thresholds agree
+(`{4d6>=5}>=5`). Dropped dice come out untagged; only the DC side of a `vs`
+keeps tags from an inner count, since no pool pass may tally it.
+
+**Keep/drop on a single-sub-roll group now takes added dice terms only.** The
+flat-pool form totals the faces it kept, so any term in the sub-roll that is not
+an added die face was discarded from the total with no error and no marker.
+`{2d6+3}kh2` lost the `+3`, and `{2d6-1d4}kh3` — which drops nothing — flipped
+the `1d4` from `-3` to `+3`. The parser already refused `(2d6+3)kh2` for exactly
+this reason; the brace form now does too.
+
+```typescript
+roll('{2d6+3}kh2', { rng: createMockRng([4, 5]) }); // throws 'INVALID_KEEP_DROP_TARGET' — was 9
+roll('{2d6-1d4}kh3', { rng: createMockRng([4, 5, 3]) }); // throws 'INVALID_KEEP_DROP_TARGET' — was 12
+roll('{2d6*2}kh2', { rng: createMockRng([4, 5]) }); // throws 'INVALID_KEEP_DROP_TARGET'
+roll('{2d6+0}kh2', { rng: createMockRng([4, 5]) }); // throws 'INVALID_KEEP_DROP_TARGET' — identity terms too
+roll('{4d6+2d8}kh3', { rng: createMockRng([6, 6, 6, 1, 8, 1]) }).total; // 20 — unchanged
+```
+
+Also newly rejected, same cause: a function-wrapped pool (`{abs(1d6-1d8)}kh1`),
+and a success count, which returned the face sum rather than the tally.
+`{4d6>=5}kh1` throws `INVALID_SUCCESS_COUNT_TARGET`, not the keep/drop code — a
+single-sub-roll group used to hide the count from the reject that `(4d6>=5)kh1`
+has always hit, and both spellings now report the same thing.
+
+The check is structural rather than arithmetic, so identity terms are refused
+with the rest even though their total was already right: `{2d6+0}kh2`,
+`{2d6*1}kh2`, and `{2d6+1d8-0}kh3` all throw.
+
+Additive pools are the form this syntax exists for and are untouched —
+`{4d6+2d8}kh3`, `{2d6kh1+1d8}kh2`, `{{1d6, 1d8}+2d6}kh2`. Multi-sub-roll groups
+never had the bug, since keep/drop compares subtotals there: `{2d6+3, 1d8}kh1`
+still works. To keep a rejected expression, move the arithmetic outside the
+selection (`{2d6}kh2+3`) or give each term its own sub-roll.
+
+**Success counting a multi-sub-roll group now scores subtotals, not dice.**
+`{2d6, 2d6}>=10` used to compare all four faces against 10 and find nothing,
+while `{2d6, 2d6}kh1` on the same node saw two compound dice worth 11 and 3.
+Roll20 counts one success per sub-roll total, and that is what the count does
+now.
+
+```typescript
+const result = roll('{2d6, 2d6}>=10', { rng: createMockRng([6, 5, 2, 1]) });
+
+result.total; // 1 — was 0
+result.successes; // 1 — was 0
+result.rendered; // '{2d6[6, 5], 2d6[2, 1]}>=10 = 1'
+```
+
+Four things move with it:
+
+- **`rendered`** shows each sub-roll's own bracket instead of one flat pool —
+  the dice are no longer the units.
+- **`rolls[].modifiers`** comes back untagged: no `'success'` or `'failure'` on
+  any die, for the same reason. Read `successes` / `failures` instead.
+- **`fT` thresholds** score subtotals too, so `{4d6+2d8, 3d20+3,
+  5d10+1}>=40f<=10` weighs three subtotals rather than 21 faces.
+- **A literal sub-roll** is a subtotal like any other, so it is scored rather
+  than skipped.
+
+```typescript
+const literal = roll('{3, 1d6}>=4f<=3', { rng: createMockRng([6]) });
+
+literal.successes; // 1
+literal.failures; // 1 — was 0
+literal.total; // 0 — was 1
+```
+
+Single-sub-roll groups (`{4d6}>=5`, `{2d6+1d8}>=5`) are the flat-pool form and
+are unchanged.
+
+**Two group spellings of a success count are now parse errors.** Both used to
+reach the flat counter with the subtotals already gone.
+
+```typescript
+roll('{3d20+5}>=21'); // throws 'INVALID_SUCCESS_COUNT_TARGET' — was a count of bare faces
+roll('{2d6, 2d8}kh1>=4'); // throws 'INVALID_SUCCESS_COUNT_TARGET' — was a count of loose dice
+roll('({2d6, 2d8})>=4'); // throws 'INVALID_SUCCESS_COUNT_TARGET'
+```
+
+- **`{3d20+5}>=21`** hits the single-sub-roll rule keep/drop already has: that
+  form compares one face at a time, so a scalar term never reaches the
+  comparison. A scaled or function-wrapped pool goes with it — `{2d6*2}>=4` and
+  `{floor(2d6/2)}>=2` throw too, exactly as `{2d6*2}kh2` does. To keep it, fold
+  the scalar into the threshold: `3d20>=16` counts the same dice.
+- **`{2d6, 2d8}kh1>=4`** covers every way a multi-sub-roll group can arrive
+  somewhere other than as the count's direct target — `{{2d6, 2d8}}>=4` and
+  `({2d6, 2d8})>=4` throw the same code. To keep it, count the group directly:
+  `{2d6, 2d8}>=4`.
+
+## Upgrading from 3.0.0 to 3.1.0
+
+Nothing was removed and no behaviour changed: `total`, `expression`, `rendered`,
+`rolls`, and `degree` are byte-identical to 3.0.0 for every expression. The
+whole of this section is about one added field.
+
+**`RollPart` gained `rolls` on three variants.** The `explode`, `reroll`, and
+`successCount` members now carry `rolls: DieResult[]` — the pool the modifier
+produced — joining `sort`, which always had it. They needed it: standard and
+penetrating explosions and both reroll forms *append* dice, and those dice
+appeared nowhere in the part tree, so a part could not describe its own output.
+
+<!-- readme-test: skip -->
+```typescript
+// 3.0.0 — the explosion die is missing from the tree
+roll('2d6!').parts.target.rolls.length; // 2, but `rendered` shows three dice
+
+// 3.1.0 — the modifier carries the pool it actually rendered
+roll('2d6!').parts.rolls.length; // 3
+```
+
+Per the [versioning policy](README.md#versioning), adding a field to a returned
+object is a minor. Reading `parts` is unaffected and needs no change. Three
+things can still bite:
+
+- **Constructing one of those parts stops compiling** — `TS2322: Property
+  'rolls' is missing in type … but required`. This is only reachable in test
+  fixtures and mocks, since no library function accepts a `RollPart`. Add the
+  pool, or widen the annotation.
+- **Deep-equality assertions against those parts fail.** Add `rolls` to the
+  expected object, or assert on the fields you care about instead of the whole
+  part.
+- **`--json` and `JSON.stringify(result)` payloads grow** for expressions using
+  explode, reroll, or success counting, because the pool is serialized on the
+  modifier as well as on its target — roughly +40% to +96% depending on pool
+  size. Expressions without those modifiers are unchanged. Budget for it if you
+  log, cache, or ship results over a wire.
+
+**The CLI renders nested dropped sub-rolls correctly.** `--verbose` on a dropped
+group sub-roll nested inside another one used to emit mismatched delimiters —
+`{{(1d6[1]), 1d8[4]}, ({)1d10[1](, 1d12[3]})}`. It now emits
+`{{(1d6[1]), 1d8[4]}, ({(1d10[1]), 1d12[3]})}`. Anything parsing that output
+should be reading `--json` instead.
+
+**New, optional: `renderBreakdown` from `roll-parser/render`.** A subpath
+export whose `renderBreakdown(result, marks?)` rebuilds the breakdown from `result.parts`
+with markers you choose, so you no longer have to regex the markdown out of
+`rendered`. With no marks its output is byte-identical to `rendered`, which
+makes it a drop-in starting point:
+
+```typescript
+import { roll } from 'roll-parser';
+import { renderBreakdown } from 'roll-parser/render';
+import { createMockRng } from 'roll-parser/testing';
+
+const result = roll('4d6kh3', { rng: createMockRng([3, 6, 2, 5]) });
+
+renderBreakdown(result) === result.rendered; // true
+renderBreakdown(result, { dropped: (_die, text) => `(${text})` });
+// '4d6[3, 6, (2), 5] = 14'
+```
+
+See [Custom markers](README.md#custom-markers) for the six slots and the order
+they compose in. Nothing forces you to adopt it — `rendered` is unchanged and
+is not deprecated.
+
+## Migrating from v2 to v3
 
 v3 is a full rewrite. Nothing in the 2.x API carries over — the entry points,
 the result shape, the error behaviour, and parts of the notation all changed. To
@@ -28,9 +319,7 @@ classes. v3 has `roll(notation, options)` for the common path, and
 | `convert(obj)`, `Roll`, `WodRoll`, `Result` | removed — there are no roll-description objects to build or convert |
 
 **Result fields moved.** v2 returned `Result { notation, value, rolls }` where
-`rolls` was a plain `number[]`. The v3 snippets below draw from
-`createMockRng` (exported by `roll-parser/testing`) so their numbers are exact
-rather than whatever the dice happened to do:
+`rolls` was a plain `number[]`.
 
 <!-- readme-test: skip -->
 ```typescript