roll-parser 3.0.0 → 3.1.0

package/src/evaluator/modifiers/sort.ts

@@ -26,17 +26,23 @@ import { isVersusDc } from './flags.js';
  * Relies on `Array.prototype.sort` being stable — equal-valued dice retain
  * their original insertion order.
  */
-export function sortDice(dice: DieResult[], order: 'ascending' | 'descending'): DieResult[] {
+export function sortDice(
+  dice: DieResult[],
+  order: 'ascending' | 'descending',
+  hasVersusDc: boolean,
+): DieResult[] {
   const cmp =
     order === 'ascending'
       ? (a: DieResult, b: DieResult) => a.result - b.result
       : (a: DieResult, b: DieResult) => b.result - a.result;
 
-  const sortable = dice.filter((die) => !isVersusDc(die));
-  if (sortable.length === dice.length) return [...dice].sort(cmp);
+  // Scan before allocating: the `filter` this replaced built a throwaway array
+  // on every sort to serve a case only a `vs` can produce (#281).
+  if (!hasVersusDc || !dice.some(isVersusDc)) return [...dice].sort(cmp);
 
   // Sort only the pool members, then lay them back into the slots they came
   // from, leaving every DC die exactly where it was.
+  const sortable = dice.filter((die) => !isVersusDc(die));
   sortable.sort(cmp);
   let next = 0;
   return dice.map((die) => (isVersusDc(die) ? die : (sortable[next++] as DieResult)));

package/src/evaluator/modifiers/success-count.ts

@@ -10,7 +10,10 @@
  * excluded from counting and are never tagged.
  *
  * Mutates the input pool in place to add `'success'` / `'failure'` modifier
- * flags — mirrors the mutation pattern of explode and reroll modifiers.
+ * flags — mirrors the mutation pattern of explode and reroll modifiers. Each
+ * tag is written at most once per die: a group counted after its members
+ * (`{4d6>=5}>=1`) runs this pass twice over the same dice, and the parse-time
+ * reject that blocks a direct `4d6>=5>=4` does not reach through a group.
  *
  * @module evaluator/modifiers/success-count
  */
@@ -28,17 +31,29 @@ export type SuccessCountResult = {
 export function countSuccesses(
   dice: DieResult[],
   threshold: ResolvedComparePoint,
-  failThreshold?: ResolvedComparePoint,
+  failThreshold: ResolvedComparePoint | undefined,
+  hasVersusDc: boolean,
 ): SuccessCountResult {
   let successes = 0;
   let failures = 0;
 
-  for (const die of dice) {
-    if (isVersusDc(die)) continue;
+  // ! Excluded up front, never inside the loop below. Even short-circuited on a
+  // ! false flag, a `hasVersusDc && isVersusDc(die)` guard in this loop costs
+  // ! ~9% on `10d10>=6f1` — measured, not assumed (#281). Filtering keeps the
+  // ! hot body identical to the pre-exclusion one and pays an allocation only
+  // ! on the `vs` path. The dice are the same objects either way, so the
+  // ! `'success'` / `'failure'` tags written below still land on the pool.
+  const pool = hasVersusDc ? dice.filter((die) => !isVersusDc(die)) : dice;
+
+  // ! The guards below only stop the *same* tag being written twice. A nested
+  // ! count with a different threshold still appends to the first pass's tags,
+  // ! so a die can end up both `'success'` and `'failure'`, and the returned
+  // ! counts then disagree with the tags in `rolls`.
+  for (const die of pool) {
     if (die.modifiers.includes('dropped')) continue;
 
     if (matchesCondition(die.result, threshold.operator, threshold.value)) {
-      die.modifiers.push('success');
+      if (!die.modifiers.includes('success')) die.modifiers.push('success');
       successes += 1;
       continue;
     }
@@ -47,7 +62,7 @@ export function countSuccesses(
       failThreshold != null &&
       matchesCondition(die.result, failThreshold.operator, failThreshold.value)
     ) {
-      die.modifiers.push('failure');
+      if (!die.modifiers.includes('failure')) die.modifiers.push('failure');
       failures += 1;
     }
   }

package/src/parser/ast.ts

@@ -61,8 +61,11 @@ export type DiceNode = NodeSpan & {
  * Fate/Fudge dice node (`dF`).
  * Each die produces a result in {-1, 0, +1}. No configurable sides.
  *
- * Fate dice carry `sides: 0` as a sentinel in their `DieResult`, and are
- * never `critical` or `fumble` — there is no maximum face to hit.
+ * Fate dice carry `sides: 0` as a sentinel in their `DieResult`, so the
+ * default `critical`/`fumble` rule never fires — it is guarded on `sides > 1`,
+ * which also stops a `+1` face from reading as a fumbled 1. An explicit
+ * threshold still applies: `4dFcs>0` and `4dFcf=-1` set the flags, while the
+ * bare `cs`/`cf` forms are rejected at parse time.
  *
  * @category AST
  */
@@ -314,9 +317,10 @@ export type SortNode = NodeSpan & {
 };
 
 /**
- * Sentinel for bare `cs` / `cf` without a ComparePoint. Resolved to
- * `result === sides` (for critical) or `result === 1` (for fumble) at
- * evaluation time, using each die's own `sides`.
+ * Sentinel for bare `cs` / `cf` without a ComparePoint. Resolved at
+ * evaluation time against each die's own `sides` and its natural face
+ * (`initialResult ?? result`): critical when that face equals `sides`,
+ * fumble when it equals 1.
  *
  * @category AST
  */
@@ -325,8 +329,9 @@ export type CritThreshold = ComparePoint | 'default';
 /**
  * Critical threshold modifier node (`cs`, `cf`).
  *
- * Overrides the default `critical`/`fumble` flag logic for the dice
- * produced by `target`. Bare `cs`/`cf` uses the `'default'` sentinel
+ * Overrides the default `critical`/`fumble` flag logic for `target`'s dice
+ * pool — including dice an enclosing `!` or `r` adds to it afterwards, which
+ * `target` never produced. Bare `cs`/`cf` uses the `'default'` sentinel
  * (max face / 1). Custom thresholds accept any ComparePoint. Chaining
  * collapses into a single node — `1d20cs=20cs=1cf>18` has two success
  * and one fail threshold. Display-only: does not change `total`,

package/src/render.ts

@@ -0,0 +1,392 @@
+/**
+ * Breakdown rendering with consumer-supplied markers.
+ *
+ * `RollResult.rendered` bakes one markdown dialect into a string. This module
+ * rebuilds the same breakdown from `RollResult.parts`, letting the caller
+ * decide how each die is marked — HTML spans, ANSI codes, Telegram
+ * MarkdownV2, or nothing at all. Import it from `roll-parser/render`.
+ *
+ * @module render
+ */
+
+import type {
+  DieResult,
+  KeepDropSpec,
+  ResolvedComparePoint,
+  ResolvedCritThreshold,
+  RollPart,
+  RollResult,
+} from './types.js';
+import { DegreeOfSuccess } from './types.js';
+
+/**
+ * Per-die markers. Every slot is optional; an omitted slot leaves the die's
+ * text untouched, so `{}` renders a breakdown with no markup whatsoever.
+ *
+ * `text` arrives as the die's value already wrapped by any inner mark, and
+ * composition order is fixed: `critical` then `fumble` innermost, then
+ * exactly one of `dropped`, `success`, or `failure` outermost — matching the
+ * priority `RollResult.rendered` uses, where a dropped die is never also
+ * shown as a success.
+ *
+ * @example A die that is both critical and dropped
+ * ```typescript
+ * { critical: (_die, text) => `<b>${text}</b>`, dropped: (_die, text) => `<s>${text}</s>` }
+ * // renders <s><b>20</b></s>
+ * ```
+ *
+ * @category Rendering
+ */
+export type DieMarks = {
+  /** Excluded from the total by `kh`/`kl`/`dh`/`dl`, a reroll, or group selection. */
+  dropped?: (die: DieResult, text: string) => string;
+  /** Met a success-count threshold. */
+  success?: (die: DieResult, text: string) => string;
+  /** Met a failure threshold. */
+  failure?: (die: DieResult, text: string) => string;
+  /** `DieResult.critical` — the default rule or an explicit `cs` threshold. */
+  critical?: (die: DieResult, text: string) => string;
+  /** `DieResult.fumble` — the default rule or an explicit `cf` threshold. */
+  fumble?: (die: DieResult, text: string) => string;
+  /**
+   * Wraps a whole sub-roll dropped by group selection (`{1d8, 1d10}kh1`).
+   *
+   * Inside it, `dropped`, `success`, and `failure` are suppressed — the
+   * wrapper already carries the verdict, and marking a dropped die inside a
+   * dropped sub-roll says nothing extra. `critical` and `fumble` still apply:
+   * they describe the face, not the selection. A nested `droppedGroup` also
+   * survives, so `{{1d6, 1d8}kh1, 1d10}kh1` can wrap twice.
+   */
+  droppedGroup?: (inner: string) => string;
+};
+
+/**
+ * The marks `RollResult.rendered` itself uses. Applied when
+ * {@link renderBreakdown} is called without a `marks` argument; spread it to
+ * override one slot while keeping the rest markdown.
+ *
+ * @category Rendering
+ */
+export const MARKDOWN_MARKS: DieMarks = {
+  dropped: (_die, text) => `~~${text}~~`,
+  success: (_die, text) => `**${text}**`,
+  failure: (_die, text) => `__${text}__`,
+  droppedGroup: (inner) => `~~${inner}~~`,
+};
+
+const KEEP_DROP_CODES = {
+  keep: { highest: 'kh', lowest: 'kl' },
+  drop: { highest: 'dh', lowest: 'dl' },
+} as const;
+
+const EXPLODE_MARKERS = {
+  standard: '!',
+  compound: '!!',
+  penetrating: '!p',
+} as const;
+
+const DEGREE_LABELS: Record<DegreeOfSuccess, string> = {
+  [DegreeOfSuccess.CriticalFailure]: 'Critical Failure',
+  [DegreeOfSuccess.Failure]: 'Failure',
+  [DegreeOfSuccess.Success]: 'Success',
+  [DegreeOfSuccess.CriticalSuccess]: 'Critical Success',
+};
+
+/** Bare identifier grammar; anything else was written `@{like this}`. */
+const BARE_VARIABLE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function comparePointCode(point: ResolvedComparePoint): string {
+  return `${point.operator}${point.value}`;
+}
+
+function critCode(prefix: 'cs' | 'cf', threshold: ResolvedCritThreshold): string {
+  return threshold === 'default' ? prefix : `${prefix}${comparePointCode(threshold)}`;
+}
+
+function keepDropCode(spec: KeepDropSpec): string {
+  return `${KEEP_DROP_CODES[spec.kind][spec.selector]}${spec.count}`;
+}
+
+/** `'='` is elided because bare `fN` parses back to it — `f3`, `f<3`, `f>=3`. */
+function failCode(point: ResolvedComparePoint): string {
+  return point.operator === '=' ? `f${point.value}` : `f${comparePointCode(point)}`;
+}
+
+/**
+ * Rebuilds the normalized expression a part contributes to
+ * `RollResult.expression` — the prefix every dice bracket hangs off.
+ *
+ * Meta-expressions are already resolved to numbers here, so `4d6kh(1d2)`
+ * comes back as `4d6kh1`, exactly as the evaluator spells it.
+ */
+function expr(part: RollPart): string {
+  switch (part.type) {
+    case 'literal':
+      return String(part.value);
+    case 'variable':
+      return String(part.value);
+    case 'dice':
+      return `${part.count}d${part.sides}`;
+    case 'fateDice':
+      return `${part.count}dF`;
+    case 'grouped':
+      return `(${expr(part.inner)})`;
+    case 'binaryOp':
+      return `${expr(part.left)} ${part.operator} ${expr(part.right)}`;
+    case 'unaryOp':
+      return `-${expr(part.operand)}`;
+    case 'group':
+      return `{${part.parts.map(expr).join(', ')}}`;
+    case 'functionCall':
+      return `${part.name}(${part.args.map(expr).join(', ')})`;
+    case 'keepDrop':
+      return `${expr(part.target)}${part.specs.map(keepDropCode).join('')}`;
+    case 'explode':
+      return `${expr(part.target)}${explodeCode(part)}`;
+    case 'reroll':
+      return `${expr(part.target)}${part.once ? 'ro' : 'r'}${comparePointCode(part.condition)}`;
+    case 'dieBound':
+      return `${expr(part.target)}${dieBoundCode(part)}`;
+    case 'sort':
+      return `${expr(part.target)}${part.order === 'ascending' ? 's' : 'sd'}`;
+    case 'critThreshold':
+      return `${expr(part.target)}${critThresholdCode(part)}`;
+    case 'successCount':
+      return `${expr(part.target)}${successCountCode(part)}`;
+    case 'versus':
+      return `${expr(part.roll)} vs ${expr(part.dc)}`;
+  }
+}
+
+function explodeCode(part: Extract<RollPart, { type: 'explode' }>): string {
+  const marker = EXPLODE_MARKERS[part.variant];
+  return part.threshold == null ? marker : `${marker}${comparePointCode(part.threshold)}`;
+}
+
+/** Negative bounds are parenthesized so the expression re-parses. */
+function dieBoundCode(part: Extract<RollPart, { type: 'dieBound' }>): string {
+  return part.value < 0 ? `${part.bound}(${part.value})` : `${part.bound}${part.value}`;
+}
+
+function critThresholdCode(part: Extract<RollPart, { type: 'critThreshold' }>): string {
+  return [
+    ...part.successThresholds.map((threshold) => critCode('cs', threshold)),
+    ...part.failThresholds.map((threshold) => critCode('cf', threshold)),
+  ].join('');
+}
+
+function successCountCode(part: Extract<RollPart, { type: 'successCount' }>): string {
+  const fail = part.failThreshold == null ? '' : failCode(part.failThreshold);
+  return `${comparePointCode(part.threshold)}${fail}`;
+}
+
+/**
+ * Collects the dice a part's subtree produced, in evaluation order.
+ *
+ * `sort`, `explode`, `reroll`, and `successCount` carry their own pool and
+ * stop the descent: a sorted pool is reordered, and an exploded or rerolled
+ * one holds dice that exist nowhere under `target`.
+ */
+function collectDice(part: RollPart, out: DieResult[]): void {
+  switch (part.type) {
+    case 'dice':
+    case 'fateDice':
+    case 'sort':
+    case 'explode':
+    case 'reroll':
+    case 'successCount':
+      for (const die of part.rolls) out.push(die);
+      return;
+    case 'grouped':
+      collectDice(part.inner, out);
+      return;
+    case 'unaryOp':
+      collectDice(part.operand, out);
+      return;
+    case 'binaryOp':
+      collectDice(part.left, out);
+      collectDice(part.right, out);
+      return;
+    case 'keepDrop':
+    case 'dieBound':
+    case 'critThreshold':
+      collectDice(part.target, out);
+      return;
+    case 'group':
+      for (const sub of part.parts) collectDice(sub, out);
+      return;
+    case 'functionCall':
+      for (const arg of part.args) collectDice(arg, out);
+      return;
+    case 'versus':
+      collectDice(part.roll, out);
+      collectDice(part.dc, out);
+      return;
+    case 'literal':
+    case 'variable':
+      return;
+  }
+}
+
+function poolOf(part: RollPart): DieResult[] {
+  const dice: DieResult[] = [];
+  collectDice(part, dice);
+  return dice;
+}
+
+/**
+ * Marks one die. `plain` suppresses the three state marks for dice inside a
+ * dropped sub-roll, where the group wrapper already carries the verdict —
+ * crit and fumble survive, since they describe the face, not the selection.
+ */
+function markDie(die: DieResult, marks: DieMarks, plain: boolean): string {
+  let text = String(die.result);
+
+  if (die.critical) text = marks.critical?.(die, text) ?? text;
+  if (die.fumble) text = marks.fumble?.(die, text) ?? text;
+  if (plain) return text;
+
+  const { modifiers } = die;
+  if (modifiers.includes('dropped')) return marks.dropped?.(die, text) ?? text;
+  if (modifiers.includes('success')) return marks.success?.(die, text) ?? text;
+  if (modifiers.includes('failure')) return marks.failure?.(die, text) ?? text;
+
+  return text;
+}
+
+/** `'meta'` dice were rolled to resolve a parameter — they are never shown. */
+function renderPool(dice: readonly DieResult[], marks: DieMarks, plain: boolean): string {
+  const shown: string[] = [];
+
+  for (const die of dice) {
+    if (die.modifiers.includes('meta')) continue;
+    shown.push(markDie(die, marks, plain));
+  }
+
+  return `[${shown.join(', ')}]`;
+}
+
+/**
+ * A modifier renders as `<target expression><code><pool>`, replacing whatever
+ * bracket the target would have shown on its own. An empty pool means the
+ * target rolled nothing at all, and the bracket is dropped with it.
+ */
+function renderModifier(
+  target: RollPart,
+  code: string,
+  dice: readonly DieResult[],
+  marks: DieMarks,
+  plain: boolean,
+): string {
+  const pool = dice.length === 0 ? '' : renderPool(dice, marks, plain);
+  return `${expr(target)}${code}${pool}`;
+}
+
+function renderPart(part: RollPart, marks: DieMarks, plain: boolean): string {
+  switch (part.type) {
+    case 'literal':
+      return String(part.value);
+    case 'variable': {
+      const display = BARE_VARIABLE.test(part.name) ? `@${part.name}` : `@{${part.name}}`;
+      return `${display}[${part.value}]`;
+    }
+    case 'dice':
+    case 'fateDice':
+      return `${expr(part)}${renderPool(part.rolls, marks, plain)}`;
+    case 'grouped':
+      return `(${renderPart(part.inner, marks, plain)})`;
+    case 'binaryOp':
+      return `${renderPart(part.left, marks, plain)} ${part.operator} ${renderPart(part.right, marks, plain)}`;
+    case 'unaryOp':
+      return `-${renderPart(part.operand, marks, plain)}`;
+    case 'functionCall': {
+      const args = part.args.map((arg) => renderPart(arg, marks, plain)).join(', ');
+      return `${part.name}(${args})`;
+    }
+    case 'versus':
+      return `${renderPart(part.roll, marks, plain)} vs ${renderPart(part.dc, marks, plain)}`;
+    case 'group':
+      return renderGroup(part, marks, plain);
+    case 'keepDrop':
+      // Sub-roll selection renders through the group, which strikes whole
+      // sub-rolls; only the flat-pool form collapses into one bracket.
+      return part.target.type === 'group' && part.target.keptIndices != null
+        ? renderPart(part.target, marks, plain)
+        : `${expr(part.target)}${renderPool(poolOf(part.target), marks, plain)}`;
+    case 'explode':
+      return renderModifier(part.target, explodeCode(part), part.rolls, marks, plain);
+    case 'reroll':
+      return renderModifier(
+        part.target,
+        `${part.once ? 'ro' : 'r'}${comparePointCode(part.condition)}`,
+        part.rolls,
+        marks,
+        plain,
+      );
+    case 'successCount':
+      return renderModifier(part.target, successCountCode(part), part.rolls, marks, plain);
+    case 'dieBound':
+      return `${expr(part.target)}${dieBoundCode(part)}${renderPool(poolOf(part.target), marks, plain)}`;
+    case 'sort':
+      return `${expr(part.target)}${part.order === 'ascending' ? 's' : 'sd'}${renderPool(part.rolls, marks, plain)}`;
+    case 'critThreshold':
+      return `${expr(part.target)}${critThresholdCode(part)}${renderPool(poolOf(part.target), marks, plain)}`;
+  }
+}
+
+function renderGroup(
+  part: Extract<RollPart, { type: 'group' }>,
+  marks: DieMarks,
+  plain: boolean,
+): string {
+  const { keptIndices } = part;
+  const subRolls = part.parts.map((sub, index) => {
+    if (keptIndices == null || keptIndices.includes(index)) {
+      return renderPart(sub, marks, plain);
+    }
+    const inner = renderPart(sub, marks, true);
+    return marks.droppedGroup?.(inner) ?? inner;
+  });
+
+  return `{${subRolls.join(', ')}}`;
+}
+
+/**
+ * Rebuilds a roll's breakdown from `RollResult.parts`, applying `marks` to
+ * every die.
+ *
+ * With no `marks` the output is byte-identical to `RollResult.rendered` — a
+ * property test pins that over generated notation. Pass any object to take
+ * over: omitted slots render plain, so `{}` strips markup entirely and
+ * `{ ...MARKDOWN_MARKS, critical: … }` keeps the rest of the markdown.
+ *
+ * The trailing `= <total>` is included, and becomes the degree label for a
+ * `vs` roll, exactly as `rendered` does.
+ *
+ * @param result - A finished result from `roll` or `evaluate`
+ * @param marks - Per-die markers; defaults to {@link MARKDOWN_MARKS}
+ * @returns The rendered breakdown
+ *
+ * @example
+ * ```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); // '4d6[3, 6, ~~2~~, 5] = 14'
+ * renderBreakdown(result, {}); // '4d6[3, 6, 2, 5] = 14'
+ * renderBreakdown(result, {
+ *   dropped: (_die, text) => `<s>${text}</s>`,
+ *   critical: (_die, text) => `<b>${text}</b>`,
+ * }); // '4d6[3, <b>6</b>, <s>2</s>, 5] = 14'
+ * ```
+ *
+ * @category Rendering
+ */
+export function renderBreakdown(result: RollResult, marks: DieMarks = MARKDOWN_MARKS): string {
+  const trailing = result.degree == null ? String(result.total) : DEGREE_LABELS[result.degree];
+
+  return `${renderPart(result.parts, marks, false)} = ${trailing}`;
+}

package/src/types.ts

@@ -42,9 +42,12 @@ export type ResolvedComparePoint = {
 };
 
 /**
- * A resolved crit threshold — `'default'` means the per-die default rule
- * (`result === sides` for critical, `result === 1` for fumble), which is what
- * bare `cs` / `cf` produce.
+ * A resolved crit threshold — `'default'` means the per-die default rule,
+ * which is what bare `cs` / `cf` produce. It reads the natural face
+ * (`initialResult ?? result`): critical when it equals `sides`, fumble when
+ * it equals 1, both only for `sides > 1`. An explicit ComparePoint instead
+ * reads the die's current `result`, so a preceding modifier that rewrote it
+ * is visible to the comparison.
  *
  * @category Results
  */
@@ -70,10 +73,14 @@ export type ResolvedCritThreshold = ResolvedComparePoint | 'default';
  *
  * `'meta'` is the one tag with no counterpart in the notation. Dice counts,
  * sides, modifier counts and computed thresholds may themselves be dice
- * (`(1d4)d6`, `4d6kh(1d2)`, `1d6!>(1d2+3)`). Those inner dice are not part of
- * any pool, so they never appear in a {@link RollPart}; they are appended to
- * `RollResult.rolls` tagged `'meta'` so an audit log can still show what the
- * meta-expression rolled. Filter them out when summing or displaying a pool.
+ * (`(1d4)d6`, `4d6kh(1d2)`, `1d6!>(1d2+3)`). Those inner dice belong to no
+ * pool: they never appear on a `dice` or `fateDice` part, and they are
+ * appended to `RollResult.rolls` tagged `'meta'` so an audit log can still
+ * show what the meta-expression rolled.
+ *
+ * The four whole-pool views — `sort`, `explode`, `reroll`, and `successCount`
+ * `rolls` — are snapshots of an evaluation context rather than of a pool, so
+ * they do carry meta dice. Filter them out when summing or displaying a pool.
  *
  * `'dc'` marks the DC side of a `vs` comparison. Unlike `'meta'` these dice do
  * render — `1d20[3] vs 2d10[5, 6]` shows both sides — but they are not part of
@@ -166,9 +173,19 @@ export type DieResult = {
   initialResult?: number;
   /** Modifiers applied to this die */
   modifiers: DieModifier[];
-  /** True if rolled the maximum value (always false for Fate dice) */
+  /**
+   * True if the die met its critical criteria — by default, rolling the
+   * maximum face on a die with more than one side. That default never fires
+   * on `d1` or on Fate dice (`sides = 0` has no maximum face), but an
+   * explicit `cs` threshold does: `4dFcs>0` flags every `+1`.
+   */
   critical: boolean;
-  /** True if rolled 1 (always false for Fate dice) */
+  /**
+   * True if the die met its fumble criteria — by default, rolling a 1 on a
+   * die with more than one side. As with {@link DieResult.critical}, the
+   * default never fires on `d1` or Fate dice, while an explicit `cf`
+   * threshold does: `4dFcf=-1` flags every `-1`.
+   */
   fumble: boolean;
 };
 
@@ -299,12 +316,30 @@ export type RollPart =
       type: 'explode';
       variant: 'standard' | 'compound' | 'penetrating';
       threshold?: ResolvedComparePoint;
+      /**
+       * The expanded pool. Standard and penetrating explosions append dice
+       * that exist nowhere under `target`, so this is the only view of the
+       * pool the modifier actually produced. Compound explosions accumulate
+       * in place, making it the same dice as `target` carries.
+       *
+       * Like `RollResult.rolls` — and unlike the pool under `target` — this
+       * keeps `'meta'` dice. Filter them out before counting or displaying.
+       */
+      rolls: DieResult[];
       target: RollPart;
     })
   | (RollPartBase & {
       type: 'reroll';
       once: boolean;
       condition: ResolvedComparePoint;
+      /**
+       * The post-reroll pool: discarded intermediates (`'rerolled'` +
+       * `'dropped'`) alongside their replacements. Both are appended rather
+       * than substituted, so neither appears under `target`.
+       *
+       * Keeps `'meta'` dice, as `RollResult.rolls` does.
+       */
+      rolls: DieResult[];
       target: RollPart;
     })
   | (RollPartBase & { type: 'dieBound'; bound: 'min' | 'max'; value: number; target: RollPart })
@@ -312,6 +347,11 @@ export type RollPart =
       type: 'successCount';
       threshold: ResolvedComparePoint;
       failThreshold?: ResolvedComparePoint;
+      /**
+       * The tallied pool, sharing `DieResult` references with `target`.
+       * Keeps `'meta'` dice, as `RollResult.rolls` does.
+       */
+      rolls: DieResult[];
       target: RollPart;
       successes: number;
       failures: number;

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by `bun run generate:version` from package.json — do not edit.
-export const version = '3.0.0';
+export const version = '3.1.0';