roll-parser 2.3.2 → 3.0.0-beta.0

package/dist/errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Common error base class and error codes for roll-parser.
+ *
+ * @module errors
+ */
+/**
+ * All known roll-parser error codes. Single source of truth — the
+ * `RollParserErrorCode` type and the runtime `VALID_CODES` set are
+ * both derived from this array.
+ *
+ * Lexer: `UNEXPECTED_CHARACTER`, `UNEXPECTED_IDENTIFIER`
+ * Parser: `UNEXPECTED_TOKEN`, `UNEXPECTED_END`, `EXPECTED_TOKEN`,
+ *   `INVALID_MODIFIER_TARGET`, `INVALID_EXPLODE_TARGET`, `INVALID_REROLL_TARGET`,
+ *   `INVALID_SUCCESS_COUNT_TARGET`, `INVALID_SORT_TARGET`,
+ *   `INVALID_CRIT_THRESHOLD_TARGET`, `NESTED_VERSUS`, `INVALID_FUNCTION_ARITY`,
+ *   `AMBIGUOUS_DICE_CHAIN`, `MAX_DEPTH_EXCEEDED`
+ * Evaluator: `INVALID_DICE_COUNT`, `INVALID_DICE_SIDES`, `DICE_LIMIT_EXCEEDED`,
+ *   `DIVISION_BY_ZERO`, `MODULO_BY_ZERO`, `UNKNOWN_OPERATOR`, `UNKNOWN_NODE_TYPE`,
+ *   `INVALID_MODIFIER_COUNT`, `EXPLODE_LIMIT_EXCEEDED`, `REROLL_LIMIT_EXCEEDED`,
+ *   `INVALID_THRESHOLD`, `NESTED_VERSUS`, `UNKNOWN_FUNCTION`, `UNDEFINED_VARIABLE`,
+ *   `INVALID_VARIABLE_VALUE`, `NON_FINITE_RESULT`
+ */
+declare const ROLL_PARSER_ERROR_CODES: readonly ["UNEXPECTED_CHARACTER", "UNEXPECTED_IDENTIFIER", "UNEXPECTED_TOKEN", "UNEXPECTED_END", "EXPECTED_TOKEN", "INVALID_DICE_COUNT", "INVALID_DICE_SIDES", "DICE_LIMIT_EXCEEDED", "DIVISION_BY_ZERO", "MODULO_BY_ZERO", "UNKNOWN_OPERATOR", "UNKNOWN_NODE_TYPE", "INVALID_MODIFIER_COUNT", "INVALID_MODIFIER_TARGET", "EXPLODE_LIMIT_EXCEEDED", "INVALID_EXPLODE_TARGET", "REROLL_LIMIT_EXCEEDED", "INVALID_REROLL_TARGET", "INVALID_SUCCESS_COUNT_TARGET", "INVALID_SORT_TARGET", "INVALID_CRIT_THRESHOLD_TARGET", "INVALID_THRESHOLD", "NESTED_VERSUS", "INVALID_FUNCTION_ARITY", "UNKNOWN_FUNCTION", "UNDEFINED_VARIABLE", "INVALID_VARIABLE_VALUE", "AMBIGUOUS_DICE_CHAIN", "MAX_DEPTH_EXCEEDED", "NON_FINITE_RESULT"];
+export type RollParserErrorCode = (typeof ROLL_PARSER_ERROR_CODES)[number];
+/**
+ * Base error class for all roll-parser errors.
+ *
+ * Provides a typed `code` field for programmatic error handling.
+ * All library errors (`LexerError`, `ParseError`, `EvaluatorError`)
+ * extend this class.
+ */
+export declare class RollParserError extends Error {
+    readonly code: RollParserErrorCode;
+    constructor(message: string, code: RollParserErrorCode);
+}
+/**
+ * Type guard for roll-parser errors. Checks `instanceof` first, then
+ * falls back to duck-typing for cross-realm safety.
+ */
+export declare function isRollParserError(value: unknown): value is RollParserError;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,uBAAuB,gsBA+BnB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;gBAEvB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB;CAKvD;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAQ1E"}

package/dist/evaluator/evaluator.d.ts

@@ -0,0 +1,121 @@
+/**
+ * AST evaluator - transforms parsed AST into roll results.
+ *
+ * @module evaluator/evaluator
+ */
+import type { RollParserErrorCode } from '../errors.js';
+import { RollParserError } from '../errors.js';
+import type { ASTNode } from '../parser/ast.js';
+import type { RNG } from '../rng/types.js';
+import type { DieResult, EvaluateOptions, RollResult } from '../types.js';
+import { DegreeOfSuccess } from '../types.js';
+import { DEFAULT_MAX_EXPLODE_ITERATIONS } from './modifiers/explode.js';
+import { DEFAULT_MAX_REROLL_ITERATIONS } from './modifiers/reroll.js';
+/**
+ * Error thrown during AST evaluation.
+ */
+export declare class EvaluatorError extends RollParserError {
+    readonly nodeType: string | undefined;
+    /**
+     * Source span of the tightest AST node that was being evaluated when the
+     * error was thrown — stamped by `evalNode` on the way up, so the innermost
+     * node wins. `undefined` when the AST was built without parser spans.
+     */
+    start: number | undefined;
+    end: number | undefined;
+    constructor(message: string, code: RollParserErrorCode, nodeType?: string);
+}
+/** Default maximum total dice allowed per evaluation. */
+export declare const DEFAULT_MAX_DICE = 10000;
+export { DEFAULT_MAX_EXPLODE_ITERATIONS, DEFAULT_MAX_REROLL_ITERATIONS };
+/**
+ * Per-evaluation shared environment (created once, shared across all branches).
+ *
+ * Exported for use by modifier implementations under `./modifiers/*`. Not part
+ * of the public library API.
+ */
+export type EvalEnv = {
+    readonly maxDice: number;
+    readonly maxExplodeIterations: number;
+    readonly maxRerollIterations: number;
+    totalDiceRolled: number;
+    /**
+     * Set to `true` by `evalSuccessCount`. Propagates through the shared env
+     * so `evaluate()` can include `successes`/`failures` fields even when no
+     * die was tagged (impossible threshold).
+     */
+    hasSuccessCount: boolean;
+    /**
+     * `true` while the evaluator is inside a `VersusNode`'s roll or DC
+     * sub-evaluation. `evalVersus` rejects nesting via this flag — catches
+     * paren-nested versus (`1d20 vs (5 vs 3)`) that slip past the parser's
+     * left-chain check.
+     */
+    insideVersus: boolean;
+    /**
+     * User-supplied variable map for `@name` / `@{name}` references. Always
+     * defined — `evaluate()` defaults to an empty object so lookups can be
+     * branch-free on presence.
+     */
+    readonly context: Readonly<Record<string, number>>;
+    /**
+     * Behavior when a referenced variable is missing from `context`. Always
+     * defined — `evaluate()` defaults to `'throw'`.
+     */
+    readonly onMissingVariable: 'throw' | 'zero';
+};
+/**
+ * Per-branch mutable accumulator for tracking rolls and output during recursion.
+ *
+ * @internal exported for targeted `mergeMetaRolls` tests only; not a public API.
+ */
+export type EvalContext = {
+    rolls: DieResult[];
+    expressionParts: string[];
+    renderedParts: string[];
+    /**
+     * Populated by `evalVersus` with the resolved degree and natural value.
+     * `evaluate()` reads this from the top-level ctx to surface `degree` and
+     * `natural` on the final `RollResult`. Only populated when `vs` is the
+     * root of the expression.
+     */
+    versusMetadata?: {
+        degree: DegreeOfSuccess;
+        natural: number | undefined;
+        dcTotal: number;
+    };
+};
+/**
+ * Forwards rolls from a throwaway sub-expression context into the parent
+ * audit trail, tagging them as `'meta'` + `'dropped'`. Meta dice are dice
+ * rolled to compute parameters (dice count, sides, threshold, modifier
+ * count) — they consume RNG and count against `maxDice`, so they must be
+ * inspectable. Tagging them `'dropped'` keeps totals correct via
+ * `sumKeptDice`; `'meta'` lets renderers hide them and lets callers
+ * distinguish them from ordinary pool dice.
+ *
+ * `'success'`/`'failure'` tags are stripped here as defense-in-depth against
+ * a SuccessCount leaking into a meta sub-expression (parser rejects all such
+ * wrappings; this strip ensures a future parse regression cannot leak tags
+ * into the top-level `successes`/`failures` scan).
+ */
+/** @internal exported for targeted defense-in-depth tests only. */
+export declare function mergeMetaRolls(parent: EvalContext, source: EvalContext): void;
+/**
+ * Evaluates a parsed AST and returns the roll result.
+ *
+ * @param ast - The parsed AST node
+ * @param rng - Random number generator to use for dice rolls
+ * @param options - Optional evaluation options
+ * @returns Complete roll result with total and metadata
+ *
+ * @example
+ * ```typescript
+ * const ast = parse('2d6+3');
+ * const rng = new SeededRNG('test');
+ * const result = evaluate(ast, rng);
+ * console.log(result.total); // Sum of dice plus 3
+ * ```
+ */
+export declare function evaluate(ast: ASTNode, rng: RNG, options?: EvaluateOptions): RollResult;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/evaluator/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluator/evaluator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EACV,OAAO,EAkBR,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,KAAK,EAEV,SAAS,EACT,eAAe,EAGf,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAKL,8BAA8B,EAC/B,MAAM,wBAAwB,CAAC;AAShC,OAAO,EAGL,6BAA6B,EAC9B,MAAM,uBAAuB,CAAC;AAI/B;;GAEG;AACH,qBAAa,cAAe,SAAQ,eAAe;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,CAAC,EAAE,MAAM;CAO1E;AAED,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,GAAG,MAAM,CAAC;CAC9C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;OAKG;IACH,cAAc,CAAC,EAAE;QACf,MAAM,EAAE,eAAe,CAAC;QACxB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AA+FF;;;;;;;;;;;;;GAaG;AACH,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAa7E;AA8pCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,GAAE,eAAoB,GAAG,UAAU,CAmF1F"}

package/dist/evaluator/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Evaluator module - AST to roll result transformation.
+ *
+ * @module evaluator
+ */
+export { DEFAULT_MAX_DICE, evaluate, EvaluatorError } from './evaluator.js';
+export { applyDropHighest, applyDropLowest, applyKeepHighest, applyKeepLowest, sumKeptDice, } from './modifiers/keep-drop.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/evaluator/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,WAAW,GACZ,MAAM,0BAA0B,CAAC"}

package/dist/evaluator/modifiers/compare.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared comparison helper for dice-pool modifiers.
+ *
+ * Both reroll and success-counting modifiers compare a die result against a
+ * fixed threshold. Extracting the comparison keeps those modules free of
+ * duplicated logic.
+ *
+ * @module evaluator/modifiers/compare
+ */
+import type { CompareOp } from '../../types.js';
+/**
+ * Compares a die result against a fixed comparison threshold.
+ */
+export declare function matchesCondition(result: number, operator: CompareOp, value: number): boolean;
+//# sourceMappingURL=compare.d.ts.map

package/dist/evaluator/modifiers/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../../src/evaluator/modifiers/compare.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAa5F"}

package/dist/evaluator/modifiers/crit-threshold.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Critical / fumble threshold modifier.
+ *
+ * Overrides the default `critical`/`fumble` flag logic for a dice pool.
+ * `cs` and `cf` are independent (Roll20 semantics): the evaluator passes
+ * `['default']` for a side with no explicit thresholds, so overriding one
+ * side never wipes the other. An empty threshold array (not produced by the
+ * evaluator) would force the corresponding flag to `false` on every die.
+ * Meta dice (rolled to compute counts/sides/modifier args) are skipped so
+ * their bookkeeping stays untouched.
+ *
+ * Display-only: does not alter `total`, explosion triggers, success
+ * counting, or any other modifier flag. Dropped dice still participate —
+ * their `critical`/`fumble` metadata reflects what they rolled, not
+ * whether they contributed to the total.
+ *
+ * @module evaluator/modifiers/crit-threshold
+ */
+import type { DieResult, ResolvedCritThreshold } from '../../types.js';
+export type { ResolvedCritThreshold } from '../../types.js';
+/**
+ * Applies success/fail threshold arrays to a dice pool, overriding each
+ * die's `critical` and `fumble` flags in place. A die matches `'default'`
+ * on the success side when `result === sides && sides > 1`, and on the
+ * fail side when `result === 1`. Meta dice are skipped.
+ */
+export declare function applyCritThresholds(dice: DieResult[], successThresholds: ResolvedCritThreshold[], failThresholds: ResolvedCritThreshold[]): void;
+//# sourceMappingURL=crit-threshold.d.ts.map

package/dist/evaluator/modifiers/crit-threshold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crit-threshold.d.ts","sourceRoot":"","sources":["../../../src/evaluator/modifiers/crit-threshold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAKvE,YAAY,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAE5D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,EAAE,EACjB,iBAAiB,EAAE,qBAAqB,EAAE,EAC1C,cAAc,EAAE,qBAAqB,EAAE,GACtC,IAAI,CAON"}

package/dist/evaluator/modifiers/explode.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Exploding dice modifier implementations.
+ *
+ * Standard (`!`): re-roll on match, append each new die to the pool.
+ * Compound (`!!`): re-roll on match, accumulate into the original die's `result`.
+ * Penetrating (`!p`): re-roll on match, append with `result = rawRoll - 1`.
+ *
+ * @module evaluator/modifiers/explode
+ */
+import type { RNG } from '../../rng/types.js';
+import type { CompareOp } from '../../types.js';
+import type { DieResult } from '../../types.js';
+import { type EvalEnv } from '../evaluator.js';
+/** Default maximum explosion iterations per die. */
+export declare const DEFAULT_MAX_EXPLODE_ITERATIONS = 1000;
+/**
+ * Predicate deciding whether a die with the given latest raw roll continues
+ * to explode. `sides` is passed separately because the default predicate
+ * ("explode on max face") uses `result === sides`.
+ */
+export type ShouldExplode = (rawResult: number, sides: number) => boolean;
+/**
+ * Builds an explosion predicate from an optional ComparePoint. When no
+ * threshold is given, explode when the raw result equals the die's max face.
+ */
+export declare function buildShouldExplode(operator: CompareOp | undefined, thresholdValue: number | undefined): ShouldExplode;
+/**
+ * Standard explode: append each new die to the pool. The original die keeps
+ * its modifiers untouched; new dice carry `['exploded', 'kept']`.
+ */
+export declare function applyStandardExplode(pool: DieResult[], shouldExplode: ShouldExplode, rng: RNG, env: EvalEnv): DieResult[];
+/**
+ * Compound explode: pool length stays the same. Each original die's `result`
+ * accumulates every explosion roll, and gains the `'exploded'` modifier once
+ * it actually exploded at least once.
+ *
+ * Mutates exploded dice in place — the same `DieResult` objects are shared
+ * between `RollResult.rolls` and the `RollPart` tree, and both must reflect
+ * post-explosion state.
+ */
+export declare function applyCompoundExplode(pool: DieResult[], shouldExplode: ShouldExplode, rng: RNG, env: EvalEnv): DieResult[];
+/**
+ * Penetrating explode: like standard, but each appended die stores
+ * `result = rawRoll - 1`. The explosion predicate runs on the RAW roll
+ * (pre-decrement), matching rpg-dice-roller convention.
+ */
+export declare function applyPenetratingExplode(pool: DieResult[], shouldExplode: ShouldExplode, rng: RNG, env: EvalEnv): DieResult[];
+//# sourceMappingURL=explode.d.ts.map

package/dist/evaluator/modifiers/explode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explode.d.ts","sourceRoot":"","sources":["../../../src/evaluator/modifiers/explode.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/D,oDAAoD;AACpD,eAAO,MAAM,8BAA8B,OAAQ,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAE1E;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,GAAG,SAAS,EAC/B,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,aAAa,CAgBf;AAyCD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,EAAE,EACjB,aAAa,EAAE,aAAa,EAC5B,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,OAAO,GACX,SAAS,EAAE,CA6Bb;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,EAAE,EACjB,aAAa,EAAE,aAAa,EAC5B,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,OAAO,GACX,SAAS,EAAE,CAiCb;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,EAAE,EACjB,aAAa,EAAE,aAAa,EAC5B,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,OAAO,GACX,SAAS,EAAE,CA8Bb"}

package/dist/evaluator/modifiers/keep-drop.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Keep/drop modifier implementations for dice pools.
+ *
+ * @module evaluator/modifiers/keep-drop
+ */
+import type { DieResult } from '../../types.js';
+/**
+ * Marks all eligible dice as `'kept'`. Dice that already carry `'dropped'`
+ * (e.g., intermediate rerolls, or the loser of a prior modifier) are left
+ * untouched so those drops cannot be silently revived.
+ */
+export declare function markAllKept(dice: DieResult[]): DieResult[];
+/**
+ * Applies keep highest modifier - keeps the N highest eligible dice, marks
+ * others as dropped. Dice already marked `'dropped'` are left unchanged.
+ *
+ * @param dice - Array of die results
+ * @param count - Number of dice to keep
+ * @returns New array with appropriate modifiers applied
+ */
+export declare function applyKeepHighest(dice: DieResult[], count: number): DieResult[];
+/**
+ * Applies keep lowest modifier - keeps the N lowest eligible dice, marks
+ * others as dropped. Dice already marked `'dropped'` are left unchanged.
+ */
+export declare function applyKeepLowest(dice: DieResult[], count: number): DieResult[];
+/**
+ * Applies drop highest modifier - drops the N highest eligible dice, keeps
+ * the rest. Dice already marked `'dropped'` are left unchanged.
+ */
+export declare function applyDropHighest(dice: DieResult[], count: number): DieResult[];
+/**
+ * Applies drop lowest modifier - drops the N lowest eligible dice, keeps
+ * the rest. Dice already marked `'dropped'` are left unchanged.
+ */
+export declare function applyDropLowest(dice: DieResult[], count: number): DieResult[];
+/**
+ * Calculates total from dice, excluding dropped dice.
+ *
+ * @param dice - Array of die results
+ * @returns Sum of non-dropped dice
+ */
+export declare function sumKeptDice(dice: DieResult[]): number;
+//# sourceMappingURL=keep-drop.d.ts.map

package/dist/evaluator/modifiers/keep-drop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keep-drop.d.ts","sourceRoot":"","sources":["../../../src/evaluator/modifiers/keep-drop.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAQ1D;AAmDD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,CAU9E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,CAU7E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,CAU9E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,CAU7E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,CAIrD"}

package/dist/evaluator/modifiers/reroll.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Reroll modifier implementations.
+ *
+ * Recursive (`r`): re-roll matching dice until the condition no longer holds,
+ *   or the per-die iteration limit is reached.
+ * Reroll-once (`ro`): re-roll matching dice exactly once, keeping the second
+ *   result regardless of whether it matches.
+ *
+ * @module evaluator/modifiers/reroll
+ */
+import type { RNG } from '../../rng/types.js';
+import type { CompareOp, DieResult } from '../../types.js';
+import { type EvalEnv } from '../evaluator.js';
+import { matchesCondition } from './compare.js';
+/** Default maximum reroll iterations per die. */
+export declare const DEFAULT_MAX_REROLL_ITERATIONS = 1000;
+export { matchesCondition };
+/**
+ * Applies recursive reroll: re-roll each matching die until it no longer
+ * matches or the per-die iteration limit is reached. Intermediate dice are
+ * appended to the output pool with `['rerolled', 'dropped']` so they:
+ * 1. Render as strikethrough (via `renderDice`'s `'dropped'` check).
+ * 2. Are excluded from `sumKeptDice`.
+ * 3. Are ignored by subsequent keep/drop modifiers.
+ */
+export declare function applyRecursiveReroll(pool: DieResult[], operator: CompareOp, value: number, rng: RNG, env: EvalEnv): DieResult[];
+/**
+ * Applies reroll-once: re-roll each matching die exactly once, keeping the
+ * second result regardless of whether it matches. Non-matching dice pass
+ * through with the `'kept'` slot flag.
+ */
+export declare function applyRerollOnce(pool: DieResult[], operator: CompareOp, value: number, rng: RNG, env: EvalEnv): DieResult[];
+//# sourceMappingURL=reroll.d.ts.map

package/dist/evaluator/modifiers/reroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reroll.d.ts","sourceRoot":"","sources":["../../../src/evaluator/modifiers/reroll.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,iDAAiD;AACjD,eAAO,MAAM,6BAA6B,OAAQ,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,CAAC;AA8D5B;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,EAAE,EACjB,QAAQ,EAAE,SAAS,EACnB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,OAAO,GACX,SAAS,EAAE,CA+Bb;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,EAAE,EACjB,QAAQ,EAAE,SAAS,EACnB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,OAAO,GACX,SAAS,EAAE,CAyBb"}

package/dist/evaluator/modifiers/sort.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Sort modifier implementation.
+ *
+ * Sort is purely cosmetic — it reorders the dice produced by its target in
+ * ascending or descending order of `result` without touching any flag
+ * (`kept`, `dropped`, `critical`, `fumble`, `rerolled`, `meta`) or the total.
+ * Dropped dice stay in the pool and sort alongside kept dice so readers can
+ * see where the dropped value landed in the ordered sequence.
+ *
+ * @module evaluator/modifiers/sort
+ */
+import type { DieResult } from '../../types.js';
+/**
+ * Returns a sorted copy of `dice` in the given order, preserving every die's
+ * original flags and metadata. Comparison is on `.result` — the raw face
+ * value is what the user sees in rendered output, so ordering by raw value
+ * matches the visual intent regardless of any `kept`/`dropped` flagging.
+ *
+ * Relies on `Array.prototype.sort` being stable — equal-valued dice retain
+ * their original insertion order.
+ */
+export declare function sortDice(dice: DieResult[], order: 'ascending' | 'descending'): DieResult[];
+//# sourceMappingURL=sort.d.ts.map

package/dist/evaluator/modifiers/sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort.d.ts","sourceRoot":"","sources":["../../../src/evaluator/modifiers/sort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS,EAAE,CAM1F"}

package/dist/evaluator/modifiers/success-count.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Success counting modifier.
+ *
+ * Transforms a dice pool into a signed success count: each die matching the
+ * success `threshold` contributes +1, each die matching the optional
+ * `failThreshold` contributes -1. When a single die matches both thresholds,
+ * success wins (checked first).
+ *
+ * Dropped dice (from a preceding keep/drop or intermediate reroll) are
+ * 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.
+ *
+ * @module evaluator/modifiers/success-count
+ */
+import type { CompareOp, DieResult } from '../../types.js';
+export type ResolvedThreshold = {
+    operator: CompareOp;
+    value: number;
+};
+export type SuccessCountResult = {
+    total: number;
+    successes: number;
+    failures: number;
+};
+export declare function countSuccesses(dice: DieResult[], threshold: ResolvedThreshold, failThreshold?: ResolvedThreshold): SuccessCountResult;
+//# sourceMappingURL=success-count.d.ts.map

package/dist/evaluator/modifiers/success-count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"success-count.d.ts","sourceRoot":"","sources":["../../../src/evaluator/modifiers/success-count.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,EAAE,EACjB,SAAS,EAAE,iBAAiB,EAC5B,aAAa,CAAC,EAAE,iBAAiB,GAChC,kBAAkB,CAuBpB"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Roll Parser - Dice notation parser for tabletop RPGs.
+ *
+ * @module roll-parser
+ */
+export { RollParserError, isRollParserError } from './errors.js';
+export type { RollParserErrorCode } from './errors.js';
+export { LexerError } from './lexer/lexer.js';
+export { parse, ParseError } from './parser/parser.js';
+export type { ASTNode, BinaryOpNode, DiceNode, NodeSpan, ExplodeNode, FateDiceNode, FunctionCallNode, GroupedNode, LiteralNode, ModifierNode, RerollNode, SuccessCountNode, SortNode, CritThresholdNode, GroupNode, UnaryOpNode, VariableNode, VersusNode, } from './parser/ast.js';
+export { isBinaryOp, isCritThreshold, isDice, isExplode, isFateDice, isFunctionCall, isGroup, isGrouped, isLiteral, isModifier, isReroll, isSort, isSuccessCount, isUnaryOp, isVariable, isVersus, } from './parser/ast.js';
+export type { RNG } from './rng/types.js';
+export { SeededRNG } from './rng/seeded.js';
+export { DEFAULT_MAX_DICE, DEFAULT_MAX_EXPLODE_ITERATIONS, DEFAULT_MAX_REROLL_ITERATIONS, evaluate, EvaluatorError, } from './evaluator/evaluator.js';
+export type { CompareOp, ComparePoint, DieModifier, DieResult, EvaluateOptions, ModifierSpec, ResolvedComparePoint, ResolvedCritThreshold, RollPart, RollPartType, RollResult, } from './types.js';
+export { DegreeOfSuccess } from './types.js';
+export { roll } from './roll.js';
+export type { RollOptions } from './roll.js';
+export declare const VERSION: string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EACV,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,YAAY,EACZ,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,UAAU,EACV,eAAe,EACf,MAAM,EACN,SAAS,EACT,UAAU,EACV,cAAc,EACd,OAAO,EACP,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,MAAM,EACN,cAAc,EACd,SAAS,EACT,UAAU,EACV,QAAQ,GACT,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,OAAO,EACL,gBAAgB,EAChB,8BAA8B,EAC9B,6BAA6B,EAC7B,QAAQ,EACR,cAAc,GACf,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,SAAS,EACT,eAAe,EACf,YAAY,EACZ,oBAAoB,EACpB,qBAAqB,EACrB,QAAQ,EACR,YAAY,EACZ,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAM7C,eAAO,MAAM,OAAO,EAAE,MAAgB,CAAC"}