roll-parser 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ 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
@@ -217,7 +241,8 @@ 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.1.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

package/MIGRATION.md

@@ -1,8 +1,227 @@
 # Migration notes
 
-Newest first. [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)
+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
 
@@ -48,8 +267,8 @@ group sub-roll nested inside another one used to emit mismatched delimiters —
 `{{(1d6[1]), 1d8[4]}, ({(1d10[1]), 1d12[3]})}`. Anything parsing that output
 should be reading `--json` instead.
 
-**New, optional: `roll-parser/render`.** A subpath export whose
-`renderBreakdown(result, marks?)` rebuilds the breakdown from `result.parts`
+**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:
@@ -100,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

package/README.md

@@ -68,8 +68,9 @@ roll('4d6kh3', { rng: createMockRng([3, 6, 2, 5]) }).total; // 14, every run
 - **Safe on untrusted input.** Dice count, explosion depth, reroll depth, and
   parse depth are all bounded, and every failure is a typed error with a stable
   code and a source span.
-- **Small and fast.** ≈11.9 kB brotli for the whole library, ≈5.5 kB for just
-  `parse`, ≈213 B for the testing entry point. Zero runtime dependencies, zero
+- **Small and fast.** ≈12.7 kB brotli for the whole library, ≈5.5 kB for just
+  `parse`, ≈1.4 kB for `roll-parser/render`, ≈213 B for the testing entry
+  point. Zero runtime dependencies, zero
   `node:` imports. A `1d20` round trip takes about 0.5 µs.
 - **Tested.** 1,500+ tests behind CI-enforced coverage floors — 100% of
   functions, 98% of lines — including every code example in this README, which
@@ -84,22 +85,28 @@ roll('4d6kh3', { rng: createMockRng([3, 6, 2, 5]) }).total; // 14, every run
 
 ## Contents
 
-- [Install](#install)
-- [Notation reference](#notation-reference)
+**Start here**
+
+- [Install](#install) — [CDN](#cdn--browser-without-a-bundler) · [Upgrading](#upgrading)
+- [Notation reference](#notation-reference) — [Dice](#dice) · [Arithmetic](#arithmetic-and-functions) · [Modifiers](#modifiers) · [Pools and checks](#pools-and-checks)
 - [Recipes by game system](#recipes-by-game-system)
-- [Working with results](#working-with-results)
-- [Randomness](#randomness)
-- [Options](#options)
-- [Error handling](#error-handling)
-- [Using the parser directly](#using-the-parser-directly)
-- [TypeScript](#typescript)
-- [CLI](#cli)
-- [Performance](#performance)
-- [Known limitations](#known-limitations)
-- [Versioning](#versioning)
-- [Upgrading](#upgrading)
-- [Contributing](#contributing)
-- [License](#license)
+
+**Using results**
+
+- [Working with results](#working-with-results) — [RollResult](#rollresult) · [The parts tree](#the-parts-tree)
+- [Rendering](#rendering) — [Custom markers](#custom-markers) · [Reading crit and fumble](#reading-crit-and-fumble)
+
+**Configuring a roll**
+
+- [Options](#options) — [Safety limits](#safety-limits)
+- [Randomness](#randomness) — [Seeded rolls](#seeded-rolls) · [Replay](#replay-and-saveresume) · [Custom RNGs](#custom-rngs) · [Testing](#testing)
+
+**Reference**
+
+- [Error handling](#error-handling) — [Notation errors](#notation-errors) · [Error classes](#error-classes) · [Error codes](#error-codes)
+- [Using the parser directly](#using-the-parser-directly) · [TypeScript](#typescript)
+- [CLI](#cli) · [Performance](#performance) · [Known limitations](#known-limitations)
+- [Versioning](#versioning) · [Contributing](#contributing) · [License](#license)
 
 ## Install
 
@@ -145,9 +152,9 @@ as one request:
 
 ### Upgrading
 
-[MIGRATION.md](MIGRATION.md) covers every upgrade path, newest first — 3.0.0 to
-3.1.0, v2 to v3, and the v3 pre-releases. v3 is a complete rewrite and the 2.x
-API is not compatible; to stay on the old line, pin `roll-parser@2.3.2`.
+[MIGRATION.md](MIGRATION.md) covers every upgrade path, newest first. v3 is a
+complete rewrite and the 2.x API is not compatible; to stay on the old line,
+pin `roll-parser@2.3.2`.
 
 ## Notation reference
 
@@ -157,8 +164,9 @@ wherever the two overlap: `kh`/`kl`/`dh`/`dl`, `!`/`!!`/`!p`, `r`/`ro`, success
 and failure counting, `cs`/`cf`, grouped rolls, and `floor`/`ceil`/`round`/`abs`
 all use Roll20's spelling and semantics. It is not a strict superset — sorting
 (`s`), PF2e `vs` checks, `max`/`min`, and computed dice counts and sides are
-additions, and two Roll20 forms are deliberately rejected (`4d6d1`, arithmetic
-after a success count) — see [Known limitations](#known-limitations).
+additions, and three Roll20 forms are deliberately rejected (`4d6d1`, arithmetic
+after a success count, and a counted single-sub-roll group folding its own math
+into each die, `{3d20+5}>=21`) — see [Known limitations](#known-limitations).
 
 Notation is case-insensitive and whitespace-tolerant — `2 D 20 KH 1` and
 `2d20kh1` are the same expression, newlines included. The one exception is
@@ -220,15 +228,17 @@ Chained keep/drop modifiers do **not** nest. `4d6kh3dl1` flattens into two
 specs applied independently to the same pool, with the dropped sets unioned —
 the Roll20 rule.
 
-`cs` / `cf` covers the whole pool, including dice that `!`, `!p`, `r`, and `ro`
-add after it — `1d6cs<2!` and `1d6!cs<2` flag the same dice. Two cases stay
-order-sensitive. Modifiers that rewrite a die's value rather than add one (`!!`,
-`minN`, `maxN`) are judged on whatever that value is when the threshold runs:
-with `[6, 6, 3]`, `1d6cs>10!!` reports no critical while `1d6!!cs>10` reports
-one, judging the compounded 15. And because `!p`'s added dice store one less
-than they rolled, the side you *don't* override moves with position —
-`1d6cf>5!p` keeps the critical that plain `1d6!p` gives the added 6, where
-`1d6!pcf>5` does not.
+`cs` / `cf` covers the whole pool, dice that `!`, `!p`, `r`, and `ro` add
+included, and position does not matter — `1d6cs<2!` and `1d6!cs<2` flag the
+same dice. The side you leave alone keeps the default rule, reading each die's
+natural face, so writing `cf>5` does not disturb `critical`: `1d6cf>5!p` and
+`1d6!pcf>5` both agree with plain `1d6!p` on the appended die.
+
+One case stays order-sensitive: an explicit threshold reads a die's current
+value, so modifiers that rewrite it rather than add a die (`!!`, `minN`,
+`maxN`) are judged on whatever that value is when the threshold runs. With
+`[6, 6, 3]`, `1d6cs>10!!` reports no critical while `1d6!!cs>10` reports one,
+judging the compounded 15.
 
 ### Pools and checks
 
@@ -238,13 +248,19 @@ than they rolled, the side you *don't* override moves with position —
 | `fT` / `f<cmp>T` | Subtract dice meeting the failure threshold — `10d10>=6f1`, `10d10>=6f<=2` |
 | `<roll> vs <dc>` | PF2e degree of success, with nat-20/nat-1 upgrade and downgrade |
 | `{a, b}khN` | Grouped roll: each sub-roll's subtotal competes as one compound die |
-| `{a+b}khN` | Single-sub-roll group: keep/drop selects across the flattened pool |
+| `{a+b}khN` | Single-sub-roll group: keep/drop selects across the flattened pool — `+`-joined pools only, a literal or any math throws |
+| `{a, b}<cmp>T` | Grouped roll: each sub-roll's subtotal is counted, not its dice — `{2d6, 2d6}>=10` |
+| `{a+b}<cmp>T` | Single-sub-roll group: counts across the flattened pool — `+`-joined pools only, a literal or any math throws |
 
 > [!IMPORTANT]
 > Success counting is **terminal** — no modifier or arithmetic applies to it
 > directly, so `10d10>=6 + 2` is a parse error. Put the arithmetic inside the
 > threshold, `10d10>=(4+2)`, or wrap the count in group braces to operate on its
 > result: `{10d10>=6}+2`.
+>
+> Braces also let a second count re-score the same pool — `{4d6>=5}<=2f5`. The
+> outermost count owns the result; see
+> [RollResult](#rollresult) for what that means for the fields you read.
 
 > [!WARNING]
 > A bare `d` after a dice expression is rejected: `4d6d1` throws
@@ -293,7 +309,7 @@ pool.total; // 5 — successes minus failures
 | `notation` | `string` | Exactly what you passed in |
 | `expression` | `string` | Normalized form; meta-expressions appear as their resolved values |
 | `rendered` | `string` | Markdown breakdown with per-die markers |
-| `rolls` | `DieResult[]` | Every die in order: `sides`, `result`, `modifiers`, `critical`, `fumble` |
+| `rolls` | `DieResult[]` | Every die in order, meta-expression dice included: `sides`, `result`, `modifiers`, `critical`, `fumble` |
 | `parts` | `RollPart` | Typed evaluation tree mirroring the AST 1:1 |
 | `successes` / `failures` | `number?` | Present only when success counting was used |
 | `degree` / `natural` | `DegreeOfSuccess?` / `number?` | Present only for a top-level `vs` |
@@ -324,6 +340,12 @@ JSON.stringify(roll('3d6', { rng: createMockRng([4, 2, 6]) }));
 > `rolls[]` and the `rolls[]` inside `parts` hold the *same* `DieResult`
 > objects — no deep clone, so annotating a die is visible through both views.
 
+When counts nest through braces (`{4d6>=5}<=2f5`), the outermost one owns the
+result: every die is judged against its thresholds alone, so `successes`,
+`failures`, `rolls[].modifiers`, and `rendered` all agree with it, and dice it
+does not count come out untagged. The DC side of a `vs` is the exception — it
+sits outside every pool pass and keeps whatever tagged it.
+
 ### The parts tree
 
 `result.parts` is a 16-variant discriminated union mirroring the AST one-to-one.
@@ -379,7 +401,9 @@ dice land in `result.rolls` tagged `'meta'` so an audit log can still show them.
 
 `result.rendered` uses markdown markers, so a Discord bot or chat log can print
 it as-is: `~~n~~` for a die dropped by keep/drop or group selection, `**n**` for
-a success, `__n__` for a failure.
+a success, `__n__` for a failure. The dialect is Discord's, not a universal one
+— Telegram MarkdownV2 rejects `**bold**` and spells strike `~n~` — so expect a
+transform, or emit your own dialect with [`renderBreakdown`](#custom-markers).
 
 ```typescript
 roll('4d6kh3', { seed: 'demo' }).rendered; // '4d6[1, 6, ~~1~~, 3] = 10'
@@ -424,6 +448,79 @@ exactly one of `dropped`, `success`, or `failure` — a dropped die is never
 also shown as a success. With no marks the output is byte-identical to
 `result.rendered`; a property test pins that.
 
+#### Reading crit and fumble
+
+`rendered` carries no marker for a crit or a fumble — those live on the dice.
+`die.critical` and `die.fumble` already reflect any `cs` / `cf` override, so a
+UI that builds its own elements reads the booleans rather than the string.
+
+```typescript
+const result = roll('4d20cs>=19', { rng: createMockRng([20, 19, 7, 1]) });
+
+const marked = result.rolls
+  .filter((die) => !die.modifiers.includes('meta'))
+  .map((die) => {
+    let text = String(die.result);
+    if (die.critical) text = `<b>${text}</b>`;
+    if (die.fumble) text = `<i>${text}</i>`;
+    return text;
+  });
+
+marked.join(', '); // '<b>20</b>, <b>19</b>, 7, <i>1</i>'
+```
+
+The 19 is critical only because `cs>=19` said so — the booleans are where the
+override lands. Compose the two marks rather than branching on one: overlapping
+thresholds set both, and `1d6cs>=3cf<=4` rolling a 3 does exactly that.
+
+The [playground](https://roll-parser.edloidas.io/) does exactly this — its
+[source](https://github.com/edloidas/roll-parser/blob/master/site/src/dice.ts)
+turns the same booleans into CSS classes, a tooltip, and a legend.
+
+That loop is right for a plain pool. Four decisions it cannot dodge:
+
+- **`'meta'` dice are not yours to show.** They resolve counts, sides, and
+  modifier arguments, and they carry ordinary crit flags — in `4d6kh(1d2)` the
+  `1d2` rolling a 2 hits its max face and arrives `critical: true`. The filter
+  above is not optional.
+- **`'dc'` dice are a judgment call.** They do render — `1d20 vs 2d10` shows
+  `1d20[5] vs 2d10[10, 10]` — but they sit outside the roll-side pool while
+  still taking the default crit rule, so that `[10, 10]` arrives as two crits
+  nobody rolled for. Drop them and a per-die zip has no dice left for a
+  two-number bracket; keep them and the DC side lights up on its own faces.
+  [`renderBreakdown`](#custom-markers) does not decide this for you — it marks
+  every flagged die — but its callbacks receive the die, so gate on the tag.
+  For a hand-rolled walk, `result.parts` keeps the two sides apart: the
+  `versus` part carries `roll` and `dc` as separate subtrees.
+- **Never splice `rendered` by bracket position.** `{2d6, 2d8}kh1` strikes the
+  dropped sub-roll as a whole, `{2d6[6, 6], ~~2d8[1, 1]~~}`, yet its inner dice
+  each carry `'dropped'` too — marking every `'dropped'` die into that string
+  yields `~~2d8[~~1~~, ~~1~~]~~`. Rebuild with
+  [`renderBreakdown`](#custom-markers) instead of patching the baked string.
+- **Density is your call.** The default rule flags the max face of any pool,
+  not just d20s — `3d6` rolling a 6 is `critical: true` — so marking it
+  unconditionally makes ordinary pools glitter. Gate on `die.sides === 20`, or
+  on whatever your table's rule is. `d1` and Fate dice are the exceptions:
+  having no exceptional face, they stay `false` unless `cs` / `cf` says so.
+
+The claims above, in code:
+
+```typescript
+import { renderBreakdown } from 'roll-parser/render';
+
+roll('1d6cs>=3cf<=4', { rng: createMockRng([3]) }).rolls[0]?.fumble; // true
+roll('4d6kh(1d2)', { rng: createMockRng([2, 3, 6, 2, 5]) }).rolls[0]?.critical; // true
+roll('1d20 vs 2d10', { rng: createMockRng([5, 10, 10]) }).rolls[2]?.critical; // true
+roll('3dF', { rng: createMockRng([1, 0, -1]) }).rolls[0]?.critical; // false
+roll('{2d6, 2d8}kh1', { rng: createMockRng([6, 6, 1, 1]) }).rendered;
+// '{2d6[6, 6], ~~2d8[1, 1]~~} = 12'
+
+// Gating a mark on the `'dc'` tag keeps the DC side unmarked
+renderBreakdown(roll('1d20 vs 2d10', { rng: createMockRng([5, 10, 10]) }), {
+  critical: (die, text) => (die.modifiers.includes('dc') ? text : `<b>${text}</b>`),
+}); // '1d20[5] vs 2d10[10, 10] = Critical Failure'
+```
+
 ## Randomness
 
 Every die is drawn through the `RNG` interface — no roll path bypasses the RNG
@@ -967,16 +1064,12 @@ Values are **p50**, from
 two significant digits: another machine shifts every row, and a busy one
 inflates the heavy cases most.
 
-The `10d10>=6f1` `roll` figure and the `4d6sd` row come from a later
-five-pass measurement on the same machine, after the per-die `'dc'` tag checks
-that had entered the keep/drop, success-count, and sort paths were hoisted out
-of those loops. That session was not idle: `evaluate / 10d10>=6f1` and
-`evaluate / 10d10sd` each read bimodally across passes with roughly 10% between
-the two modes, so those two are quoted as "recovered to the pre-exclusion
-range" rather than to a point value. The rows this hoist does not touch
-(`1d20`, `2d6+3`, `4d6kh3`, `100d6`) re-measured within noise of the figures
-above and are left as first measured, since the earlier idle session is the
-better data for them.
+The `4d6sd` row and the `10d10>=6f1` `roll` figure come from a later five-pass
+measurement on the same machine, after the per-die `'dc'` tag checks were
+hoisted out of the keep/drop, success-count, and sort loops. That session was
+not idle and those two read bimodally with roughly 10% between the modes, so
+take them as a recovered range rather than point values. Every other row is as
+first measured.
 
 p50 rather than mean, because the mean here is effectively a GC-pause
 histogram and swings ±40% between processes. Every bench body is JIT-primed
@@ -996,32 +1089,64 @@ any commit that regresses a case past 1.75x. Bundle size is gated in CI by
 
 ## Known limitations
 
-- **Keep/drop does not echo into the render prefix.** `4d6kh3` renders as
-  `4d6[1, 6, ~~1~~, 3] = 10`, while every other modifier family does echo
-  (`8d6![…]`, `4d6sd[…]`, `10d10>=6f1[…]`). The dropped die is still marked;
-  only the `kh3` is missing, and `result.expression` has it.
-- **`4d6d1` is a parse error, not "drop 1".** The bare `d` is the dice
-  operator, and reading `4d6d1` as "roll 4d6, then roll that many d1" is a
-  silent trap, so it throws `AMBIGUOUS_DICE_CHAIN`.
-- **Threshold comparisons bind tight.** `1d6!>=5+2` parses as `(1d6!>=5)+2`;
-  parenthesize for a computed threshold, `1d6!>=(5+2)`. Success counts bind the
-  same way but are terminal, so `1d6>=5+2` errors outright — write
-  `1d6>=(5+2)`, or `{1d6>=5}+2` to add to the count itself.
+### Notation the parser rejects
+
+| Form | Throws | Write instead |
+|------|--------|---------------|
+| `{2d6+3}kh2`, `{2d6-1d4}kh3`, `{2d6*2}kh2`, `{2d6+0}kh2` | `INVALID_KEEP_DROP_TARGET` | `{2d6}kh2 + 3`, or one sub-roll per term: `{2d6+3, 1d8}kh1` |
+| `{3d20+5}>=21`, `{2d6-1d4}>=3`, `{2d6*2}>=4`, `{floor(2d6/2)}>=2` | `INVALID_SUCCESS_COUNT_TARGET` | fold the scalar into the threshold: `3d20>=16` |
+| `{3, 5, 7}>=4` | `INVALID_SUCCESS_COUNT_TARGET` | give the group a pool: `3d6>=4` |
+| `{{2d6, 2d8}}>=4`, `({2d6, 2d8})>=4`, `{2d6, 2d8}kh1>=4` | `INVALID_SUCCESS_COUNT_TARGET` | count the group directly: `{2d6, 2d8}>=4` |
+| `{4d6>=5}kh1` | `INVALID_SUCCESS_COUNT_TARGET` | the count is already terminal — select first, `{4d6kh1}>=5` |
+| `{2d6, 1d8}s` | `INVALID_SORT_TARGET` | flatten to one sub-roll: `{2d6+1d8}s` |
+| `4d6d1` | `AMBIGUOUS_DICE_CHAIN` | `4d6dl1` to drop a die, `(4d6)d1` for nested dice |
+
+The first two rows share one cause: a single-sub-roll group compares dice one
+face at a time, so a literal, a subtracted or scaled pool, or a function wrapper
+never reaches the comparison. The check is structural rather than arithmetic, so
+an identity term (`{2d6+0}kh2`) is refused with the rest. Adding pools
+(`{4d6+2d8}kh3`, `{2d6+1d8}>=5`) is the form these braces exist for and always
+works.
+
+A counted group needs at least one die somewhere in it — one real pool is
+enough, and the other sub-rolls may be literals: `{3, 1d6}>=4` scores both
+subtotals, the literal `3` included. A pool that is merely empty at run time
+(`0d6>=4`) still parses and totals 0. Subtotals exist only while the count holds
+the group directly, which is why the fourth row throws rather than falling back
+to loose faces; the DC side of a `vs` is exempt (`{1d20 vs {2d6, 2d8}}>=5`
+counts the d20), since no pool pass tallies a DC.
+
+Sorting a multi-sub-roll group is refused rather than shipped wrong: spec-correct
+sorting there is hierarchical — dice within each sub-roll, then sub-rolls by
+total — and the evaluator only flat-sorts.
+
+### Rendering and `expression`
+
+- **Keep/drop does not echo into the render prefix** — see
+  [Rendering](#rendering). The dropped die is still marked; only the `kh3` is
+  missing, and `result.expression` has it.
 - **`result.expression` substitutes meta-expressions with their resolved
   values,** so it does not round-trip through `parse` when they are present:
   `roll('(1d4)d6').expression` is `'4d6'` when the `1d4` rolled 4, and
   `roll('1d6!>(1d2+3)').expression` is `'1d6!>5'`.
+- **Adjacent bare modifiers keep a space.** `cs`, `cf`, `s`, and `sd` without a
+  threshold or count end an identifier the lexer would extend into whatever
+  follows, so `expression` and `rendered` separate them the way the input had
+  to: `roll('1d20cs cf').expression` is `'1d20cs cf'`, and `4d6 s kh2` comes
+  back as `'4d6s kh2'`. Everything else stays flush — `4d6cs>4cf<2`.
 - **Sort flattens additive pools.** `(2d6+1d8)s` renders as one combined sorted
   list, `(2d6 + 1d8)s[2, 3, 6] = 11`, rather than `2d6[2, 6] + 1d8[3]`. Totals
   are unaffected; only the breakdown loses pool boundaries.
 - **Outer parentheses drop when crit thresholds collapse.** `(1d20cs>19)cs=1`
   reports `expression: '1d20cs>19cs=1'` because chained `cs`/`cf` fold into one
   node. It re-parses to the same AST; only the text differs.
-- **Sorting a multi-sub-roll group is rejected.** `{2d6, 1d8}s` throws
-  `INVALID_SORT_TARGET`. Spec-correct sorting there is hierarchical — dice
-  within each sub-roll, then sub-rolls by total — and the evaluator only
-  flat-sorts, so the syntax is refused rather than shipped wrong. Single
-  sub-roll groups (`{2d6+1d8}s`) still work as the flat-pool escape hatch.
+
+### Arithmetic and precedence
+
+- **Threshold comparisons bind tight.** `1d6!>=5+2` parses as `(1d6!>=5)+2`;
+  parenthesize for a computed threshold, `1d6!>=(5+2)`. Success counts bind the
+  same way but are terminal, so `1d6>=5+2` errors outright — write
+  `1d6>=(5+2)`, or `{1d6>=5}+2` to add to the count itself.
 - **Division does not floor.** `7/2` totals `3.5`, not `3` — arithmetic is plain
   IEEE-754 throughout. Wrap it when you need an integer: `floor(7/2)` totals `3`.
 - **The power operator has no overflow guard.** `2**999` totals `5.357…e+300`.