roll-parser 3.0.0 → 3.2.0

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
@@ -158,17 +165,28 @@ export type DieResult = {
   /** The rolled value */
   result: number;
   /**
-   * Raw first roll before any mutation (e.g., compound-explode accumulation).
-   * Only populated when `result` has been overwritten with a computed value.
+   * Raw first roll before any mutation — compound-explode accumulation, the
+   * `!p` decrement, or a `minN`/`maxN` clamp. Only populated when `result` has
+   * been overwritten with a computed value.
    * Consumers that need the original face (nat-20 / nat-1 detection) should
    * read `initialResult ?? result`.
    */
   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;
 };
 
@@ -217,7 +235,10 @@ export type RollPartBase = {
  * - `literal.total === value` and `variable.total === value`.
  * - Each part's `rolls[]` shares `DieResult` references with
  *   `RollResult.rolls[]`; both reflect post-evaluation state (explode
- *   accumulation, reroll flags, keep/drop flags). No deep clone.
+ *   accumulation, reroll flags, keep/drop flags, success/failure tags). No deep
+ *   clone. A part's own numbers record what that part computed, so an inner
+ *   `successCount` re-scored by an outer one (`{4d6>=5}<=2f5`) keeps its
+ *   tally while the dice it shares show the outer count's tags.
  *
  * Meta-expression sub-trees (`4d6kh(1d2)`, `(1+1)d6` counts/sides, computed
  * thresholds) are not surfaced as nested parts — their resolved numbers
@@ -299,12 +320,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 +351,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;
@@ -409,6 +453,14 @@ export type RollResult = Readonly<{
    * arithmetic on top of a success count (e.g. `{5d6>=5}+2`) affects `total`
    * but not `successes`. Success counts are terminal, so the group braces are
    * required: `5d6>=5 * 2` is an `INVALID_SUCCESS_COUNT_TARGET` parse error.
+   *
+   * Braces also let a second count re-count the same pool (`{4d6>=5}<=2f5`).
+   * The outermost count owns the outcome: it re-scores the pool against its own
+   * thresholds, so no die is ever both a success and a failure, and dice it
+   * does not count come out untagged rather than keeping the inner count's
+   * tags. The DC side of a `vs` is never tallied here; it keeps whatever tags
+   * an inner count gave it, unless the outer count scores subtotals rather
+   * than dice, which leaves every die untagged.
    */
   successes?: 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.2.0';