roll-parser 3.0.0-alpha.0 → 3.0.0-beta.0

package/dist/lexer/lexer.d.ts

@@ -3,9 +3,9 @@
  *
  * @module lexer/lexer
  */
-import type { RollParserErrorCode } from '../errors';
-import { RollParserError } from '../errors';
-import { type Token } from './tokens';
+import type { RollParserErrorCode } from '../errors.js';
+import { RollParserError } from '../errors.js';
+import { type Token } from './tokens.js';
 /**
  * Error thrown when the lexer encounters an invalid character.
  */
@@ -47,6 +47,19 @@ export declare class Lexer {
      *   accumulation loop stops naturally and the post-loop check handles it.
      */
     private scanIdentifier;
+    /**
+     * Scans a variable reference introduced by `@`.
+     *
+     * Two forms:
+     * - Bare: `@name` where `name` matches `[A-Za-z_][A-Za-z0-9_]*` (case preserved).
+     * - Braced: `@{name}` where `name` is any run of printable characters except
+     *   `}` and newline (permits spaces, hyphens, digits).
+     *
+     * Case is preserved — distinct from `scanIdentifier`, which lowercases the
+     * captured value. The emitted token's `value` is the variable name without
+     * the leading `@` or the surrounding braces.
+     */
+    private scanAt;
     private peek;
     private peekNext;
     private advance;
@@ -54,6 +67,8 @@ export declare class Lexer {
     private isAtEnd;
     private isDigit;
     private isAlpha;
+    private isIdentifierStart;
+    private isIdentifierPart;
     private isWhitespace;
     private createToken;
     private createTokenAt;

package/dist/lexer/lexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lexer.d.ts","sourceRoot":"","sources":["../../src/lexer/lexer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,qBAAa,UAAW,SAAQ,eAAe;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM5F;AAsBD;;;;;GAKG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,KAAK,EAAE,MAAM;IAIzB;;OAEG;IACH,QAAQ,IAAI,KAAK,EAAE;IAYnB;;OAEG;IACH,SAAS,IAAI,KAAK;IAyElB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,UAAU;IAoBlB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,cAAc;IAgCtB,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,aAAa;CAGtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,CAE1C"}
+{"version":3,"file":"lexer.d.ts","sourceRoot":"","sources":["../../src/lexer/lexer.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,EAAE,KAAK,KAAK,EAAa,MAAM,aAAa,CAAC;AAEpD;;GAEG;AACH,qBAAa,UAAW,SAAQ,eAAe;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM5F;AA2CD;;;;;GAKG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,KAAK,EAAE,MAAM;IAIzB;;OAEG;IACH,QAAQ,IAAI,KAAK,EAAE;IAYnB;;OAEG;IACH,SAAS,IAAI,KAAK;IAuFlB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,UAAU;IAoBlB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,cAAc;IAqCtB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM;IA+Bd,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,aAAa;CAGtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,CAE1C"}

package/dist/lexer/tokens.d.ts

@@ -70,8 +70,22 @@ export declare enum TokenType {
     FUNCTION = 28,
     /** Versus operator: 'vs' */
     VS = 29,
+    /** Left brace: '{' */
+    LBRACE = 30,
+    /** Right brace: '}' */
+    RBRACE = 31,
+    /** Variable reference prefix: '@' */
+    AT = 32,
+    /** Ascending sort: 's' or 'sa' */
+    SORT_ASC = 33,
+    /** Descending sort: 'sd' */
+    SORT_DESC = 34,
+    /** Critical success threshold: 'cs' */
+    CRIT_SUCCESS = 35,
+    /** Critical failure threshold: 'cf' */
+    CRIT_FAIL = 36,
     /** End of input marker */
-    EOF = 30
+    EOF = 37
 }
 /**
  * A token produced by the lexer.
@@ -81,7 +95,13 @@ export type Token = {
     type: TokenType;
     /** The raw string value from input (lowercased for identifiers) */
     value: string;
-    /** Zero-based position in the input string */
+    /** Zero-based start offset in the input string (UTF-16 code units) */
     position: number;
+    /**
+     * Zero-based end offset (exclusive). Not always `position + value.length` —
+     * braced variables (`@{name}` stores only `name`) and case-normalized
+     * identifiers consume more input than their `value` retains.
+     */
+    end: number;
 };
 //# sourceMappingURL=tokens.d.ts.map

package/dist/lexer/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/lexer/tokens.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,oBAAY,SAAS;IAKnB,0CAA0C;IAC1C,MAAM,IAAI;IAMV,gCAAgC;IAChC,IAAI,IAAI;IACR,sDAAsD;IACtD,YAAY,IAAI;IAChB,qCAAqC;IACrC,SAAS,IAAI;IAMb,6BAA6B;IAC7B,IAAI,IAAI;IACR,gCAAgC;IAChC,KAAK,IAAI;IACT,mCAAmC;IACnC,QAAQ,IAAI;IACZ,6BAA6B;IAC7B,MAAM,IAAI;IACV,2BAA2B;IAC3B,MAAM,IAAI;IACV,kCAAkC;IAClC,KAAK,IAAI;IAMT,wBAAwB;IACxB,OAAO,KAAK;IACZ,kCAAkC;IAClC,aAAa,KAAK;IAClB,qBAAqB;IACrB,IAAI,KAAK;IACT,+BAA+B;IAC/B,UAAU,KAAK;IACf,iBAAiB;IACjB,KAAK,KAAK;IAMV,4BAA4B;IAC5B,MAAM,KAAK;IACX,6BAA6B;IAC7B,MAAM,KAAK;IACX,8BAA8B;IAC9B,KAAK,KAAK;IAMV,yCAAyC;IACzC,SAAS,KAAK;IACd,iCAAiC;IACjC,QAAQ,KAAK;IACb,kCAAkC;IAClC,SAAS,KAAK;IACd,iCAAiC;IACjC,QAAQ,KAAK;IAMb,4BAA4B;IAC5B,OAAO,KAAK;IACZ,gCAAgC;IAChC,gBAAgB,KAAK;IACrB,gCAAgC;IAChC,mBAAmB,KAAK;IAMxB,4BAA4B;IAC5B,MAAM,KAAK;IACX,wBAAwB;IACxB,WAAW,KAAK;IAMhB,uBAAuB;IACvB,IAAI,KAAK;IAMT,mEAAmE;IACnE,QAAQ,KAAK;IAMb,4BAA4B;IAC5B,EAAE,KAAK;IAMP,0BAA0B;IAC1B,GAAG,KAAK;CACT;AAED;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,6BAA6B;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/lexer/tokens.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,oBAAY,SAAS;IAKnB,0CAA0C;IAC1C,MAAM,IAAI;IAMV,gCAAgC;IAChC,IAAI,IAAI;IACR,sDAAsD;IACtD,YAAY,IAAI;IAChB,qCAAqC;IACrC,SAAS,IAAI;IAMb,6BAA6B;IAC7B,IAAI,IAAI;IACR,gCAAgC;IAChC,KAAK,IAAI;IACT,mCAAmC;IACnC,QAAQ,IAAI;IACZ,6BAA6B;IAC7B,MAAM,IAAI;IACV,2BAA2B;IAC3B,MAAM,IAAI;IACV,kCAAkC;IAClC,KAAK,IAAI;IAMT,wBAAwB;IACxB,OAAO,KAAK;IACZ,kCAAkC;IAClC,aAAa,KAAK;IAClB,qBAAqB;IACrB,IAAI,KAAK;IACT,+BAA+B;IAC/B,UAAU,KAAK;IACf,iBAAiB;IACjB,KAAK,KAAK;IAMV,4BAA4B;IAC5B,MAAM,KAAK;IACX,6BAA6B;IAC7B,MAAM,KAAK;IACX,8BAA8B;IAC9B,KAAK,KAAK;IAMV,yCAAyC;IACzC,SAAS,KAAK;IACd,iCAAiC;IACjC,QAAQ,KAAK;IACb,kCAAkC;IAClC,SAAS,KAAK;IACd,iCAAiC;IACjC,QAAQ,KAAK;IAMb,4BAA4B;IAC5B,OAAO,KAAK;IACZ,gCAAgC;IAChC,gBAAgB,KAAK;IACrB,gCAAgC;IAChC,mBAAmB,KAAK;IAMxB,4BAA4B;IAC5B,MAAM,KAAK;IACX,wBAAwB;IACxB,WAAW,KAAK;IAMhB,uBAAuB;IACvB,IAAI,KAAK;IAMT,mEAAmE;IACnE,QAAQ,KAAK;IAMb,4BAA4B;IAC5B,EAAE,KAAK;IAMP,sBAAsB;IACtB,MAAM,KAAK;IACX,uBAAuB;IACvB,MAAM,KAAK;IAMX,qCAAqC;IACrC,EAAE,KAAK;IAMP,kCAAkC;IAClC,QAAQ,KAAK;IACb,4BAA4B;IAC5B,SAAS,KAAK;IAMd,uCAAuC;IACvC,YAAY,KAAK;IACjB,uCAAuC;IACvC,SAAS,KAAK;IAMd,0BAA0B;IAC1B,GAAG,KAAK;CACT;AAED;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,6BAA6B;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;CACb,CAAC"}

package/dist/parser/ast.d.ts

@@ -3,11 +3,23 @@
  *
  * @module parser/ast
  */
-import type { ComparePoint } from '../types';
+import type { ComparePoint } from '../types.js';
+/**
+ * Source span carried by every AST node.
+ *
+ * `start` is inclusive, `end` exclusive, both in UTF-16 code units into the
+ * original notation string. The parser sets both on every node it produces;
+ * they are typed optional so hand-constructed ASTs (tests, programmatic
+ * consumers) remain valid without positions.
+ */
+export type NodeSpan = {
+    start?: number;
+    end?: number;
+};
 /**
  * Numeric literal node.
  */
-export type LiteralNode = {
+export type LiteralNode = NodeSpan & {
     type: 'Literal';
     value: number;
 };
@@ -15,7 +27,7 @@ export type LiteralNode = {
  * Dice roll node.
  * Count and sides can be expressions to support computed dice like (1+1)d(3*2).
  */
-export type DiceNode = {
+export type DiceNode = NodeSpan & {
     type: 'Dice';
     count: ASTNode;
     sides: ASTNode;
@@ -24,14 +36,14 @@ export type DiceNode = {
  * Fate/Fudge dice node (`dF`).
  * Each die produces a result in {-1, 0, +1}. No configurable sides.
  */
-export type FateDiceNode = {
+export type FateDiceNode = NodeSpan & {
     type: 'FateDice';
     count: ASTNode;
 };
 /**
  * Binary operation node.
  */
-export type BinaryOpNode = {
+export type BinaryOpNode = NodeSpan & {
     type: 'BinaryOp';
     operator: '+' | '-' | '*' | '/' | '%' | '**';
     left: ASTNode;
@@ -40,7 +52,7 @@ export type BinaryOpNode = {
 /**
  * Unary operation node.
  */
-export type UnaryOpNode = {
+export type UnaryOpNode = NodeSpan & {
     type: 'UnaryOp';
     operator: '-';
     operand: ASTNode;
@@ -49,7 +61,7 @@ export type UnaryOpNode = {
  * Keep/drop modifier node.
  * Wraps a dice expression with keep highest/lowest or drop highest/lowest.
  */
-export type ModifierNode = {
+export type ModifierNode = NodeSpan & {
     type: 'Modifier';
     modifier: 'keep' | 'drop';
     selector: 'highest' | 'lowest';
@@ -61,7 +73,7 @@ export type ModifierNode = {
  * Wraps a dice expression with a standard, compounding, or penetrating
  * explosion. An absent `threshold` means "explode on the die's maximum face".
  */
-export type ExplodeNode = {
+export type ExplodeNode = NodeSpan & {
     type: 'Explode';
     variant: 'standard' | 'compound' | 'penetrating';
     threshold?: ComparePoint;
@@ -73,7 +85,7 @@ export type ExplodeNode = {
  * keeps the second result regardless of match; `once: false` for `r`
  * re-rolls recursively until the condition no longer matches.
  */
-export type RerollNode = {
+export type RerollNode = NodeSpan & {
     type: 'Reroll';
     once: boolean;
     condition: ComparePoint;
@@ -83,11 +95,12 @@ export type RerollNode = {
  * Success counting node (`>=T`, `>T`, `<T`, `<=T`, `=T`, with optional `f=F`).
  *
  * Transforms a dice pool into a success count: each die meeting `threshold`
- * adds +1, each die meeting `failThreshold` subtracts 1. Terminal — no further
- * postfix modifiers may wrap a `SuccessCountNode`. The `failThreshold`
- * operator is always `=` (fail on an exact value).
+ * adds +1, each die meeting `failThreshold` subtracts 1. Terminal — a
+ * `SuccessCountNode` may not be wrapped by any postfix modifier, binary
+ * operator, unary operator, versus operand, or function argument. The
+ * `failThreshold` accepts any `CompareOp`; bare `fN` defaults to `operator: '='`.
  */
-export type SuccessCountNode = {
+export type SuccessCountNode = NodeSpan & {
     type: 'SuccessCount';
     target: ASTNode;
     threshold: ComparePoint;
@@ -103,7 +116,7 @@ export type SuccessCountNode = {
  * rejected at parse time; nesting via parens (`a vs (b vs c)`) is rejected
  * at evaluation time.
  */
-export type VersusNode = {
+export type VersusNode = NodeSpan & {
     type: 'Versus';
     roll: ASTNode;
     dc: ASTNode;
@@ -116,15 +129,91 @@ export type VersusNode = {
  * parse time against a static table; by the time the evaluator sees a
  * `FunctionCallNode`, `args.length` is guaranteed to match the function.
  */
-export type FunctionCallNode = {
+export type FunctionCallNode = NodeSpan & {
     type: 'FunctionCall';
     name: string;
     args: ASTNode[];
 };
+/**
+ * Parenthesized group node (`(<expr>)`).
+ *
+ * Preserves explicit grouping typed by the user so that
+ * `RollResult.expression` and `RollResult.rendered` round-trip through
+ * `parse` without losing precedence information. Semantically transparent:
+ * evaluation returns the inner expression's value unchanged.
+ */
+export type GroupedNode = NodeSpan & {
+    type: 'Grouped';
+    expression: ASTNode;
+};
+/**
+ * Variable reference node (`@name` or `@{name with spaces}`).
+ *
+ * Resolves to a numeric value from the evaluator's `context` map at
+ * evaluation time. Names are case-sensitive (`@StrMod` ≠ `@strmod`) — the
+ * lexer preserves case in the `AT` token's `value`, distinct from other
+ * identifier tokens which lowercase. Leaf node — no LED, never wraps a
+ * sub-expression.
+ */
+export type VariableNode = NodeSpan & {
+    type: 'Variable';
+    name: string;
+};
+/**
+ * Grouped-roll node (`{expr}`, `{expr1, expr2, ...}`).
+ *
+ * Distinct from `GroupedNode` (parenthesized wrapper) — a `GroupNode`
+ * collects one or more sub-expressions whose evaluation semantics change
+ * with the sub-roll count. `expressions.length === 1` is a passthrough
+ * (flat-pool when wrapped by keep/drop); `expressions.length >= 2` treats
+ * each sub-roll's subtotal as a compound die for keep/drop selection.
+ */
+export type GroupNode = NodeSpan & {
+    type: 'Group';
+    expressions: ASTNode[];
+};
+/**
+ * Sort modifier node (`s`, `sa`, `sd`).
+ *
+ * Cosmetically reorders the dice produced by `target` in ascending or
+ * descending order. Purely visual — does not affect `total`,
+ * `successes`/`failures`, or any die-level flag (`kept`/`dropped`/
+ * `critical`/`fumble`). Dropped dice retain their `dropped` flag and
+ * appear in sorted position alongside kept dice.
+ */
+export type SortNode = NodeSpan & {
+    type: 'Sort';
+    order: 'ascending' | 'descending';
+    target: ASTNode;
+};
+/**
+ * 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`.
+ */
+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
+ * (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`,
+ * explosion triggers, or success counting. `cs` and `cf` are independent
+ * overrides — a side with no explicit thresholds keeps the default rule
+ * (the evaluator substitutes the `'default'` sentinel at apply time).
+ */
+export type CritThresholdNode = NodeSpan & {
+    type: 'CritThreshold';
+    successThresholds: CritThreshold[];
+    failThresholds: CritThreshold[];
+    target: ASTNode;
+};
 /**
  * Union type of all AST nodes.
  */
-export type ASTNode = LiteralNode | DiceNode | FateDiceNode | BinaryOpNode | UnaryOpNode | ModifierNode | ExplodeNode | RerollNode | SuccessCountNode | VersusNode | FunctionCallNode;
+export type ASTNode = LiteralNode | DiceNode | FateDiceNode | BinaryOpNode | UnaryOpNode | ModifierNode | ExplodeNode | RerollNode | SuccessCountNode | VersusNode | FunctionCallNode | GroupedNode | VariableNode | GroupNode | SortNode | CritThresholdNode;
 /**
  * Type guard for LiteralNode.
  */
@@ -170,14 +259,110 @@ export declare function isVersus(node: ASTNode): node is VersusNode;
  */
 export declare function isFunctionCall(node: ASTNode): node is FunctionCallNode;
 /**
- * Returns `true` if the AST contains a `Dice` or `FateDice` node reachable
- * through structural composition (BinaryOp, UnaryOp, keep/drop, explode,
- * reroll, success-count wrappers). Meta-expressions — dice count/sides,
- * modifier counts, and ComparePoint values — are treated as leaves and
- * never recursed into.
+ * Type guard for GroupedNode.
+ */
+export declare function isGrouped(node: ASTNode): node is GroupedNode;
+/**
+ * Type guard for VariableNode.
+ */
+export declare function isVariable(node: ASTNode): node is VariableNode;
+/**
+ * Type guard for GroupNode.
+ */
+export declare function isGroup(node: ASTNode): node is GroupNode;
+/**
+ * Type guard for SortNode.
+ */
+export declare function isSort(node: ASTNode): node is SortNode;
+/**
+ * Type guard for CritThresholdNode.
+ */
+export declare function isCritThreshold(node: ASTNode): node is CritThresholdNode;
+/**
+ * Wrapper kinds that `unwrapTransparent` can peel.
+ *
+ * "Transparent" is relative to the question being asked. `Modifier`/`Sort`/
+ * `CritThreshold` are transparent for "what is the underlying operand?" when
+ * deciding whether to reject a `Group` target — they preserve `containsDicePool`'s
+ * answer for whatever they wrap. They are NOT transparent for "is this a
+ * `SuccessCount`?" or "is this a `Versus`?", because the parsers that build
+ * those wrappers already reject `SuccessCount`/`Versus` operands upstream.
+ */
+export type TransparentWrapperKind = 'Grouped' | 'Modifier' | 'Sort' | 'CritThreshold';
+/**
+ * Walks `node` while its `.type` is in `kinds`, returning the first descendant
+ * that is not one of the listed wrappers. Each caller picks the subset that
+ * matches its rejection semantics — see `TransparentWrapperKind` for guidance.
+ *
+ * Used by parser reject helpers to look past wrappers when deciding whether
+ * an operand violates a rule (e.g., `Group` cannot be the target of `cs`/`cf`,
+ * even when wrapped in `Modifier` like `{1d6}kh1cs>5`).
+ */
+export declare function unwrapTransparent(node: ASTNode, kinds: readonly TransparentWrapperKind[]): ASTNode;
+/**
+ * Returns `true` only when `node`'s direct result is a dice pool —
+ * `Dice`, `FateDice`, or a chained pool modifier (`Modifier` / `Explode` /
+ * `Reroll`). Does NOT recurse through arithmetic wrappers (`BinaryOp`,
+ * `UnaryOp`, `FunctionCall`), so `(1d6+5)` and `floor(1d6/2)` are rejected.
  *
- * Used by the parser to reject success-counting targets that don't actually
- * roll any dice (e.g. `1>=3`, `(1+2)>=3`).
+ * Used by the parser to reject postfix pool-modifier targets (kh/kl/dh/dl,
+ * !/!!/!p, r/ro) that wrap a non-pool expression. Operating on the inner
+ * dice pool would silently drop the surrounding arithmetic.
+ */
+export declare function containsDicePool(node: ASTNode): boolean;
+/**
+ * Deeper variant of `containsDicePool` that recurses through arithmetic and
+ * function wrappers. Used from the `Group` case above (ordinary parenthesized
+ * arithmetic `(1d6+5)kh1` must still reject, so the shallow `containsDicePool`
+ * handles those directly) and from the Sort parser guard (sort accepts
+ * `(1d6+2d8)s` per Stage 3 spec).
+ */
+export declare function deepContainsDicePool(node: ASTNode): boolean;
+/**
+ * Returns `true` if the pool this node resolves to is (or wraps) a `FateDice`
+ * pool. Walks through chained pool modifiers (`Modifier` / `Explode` /
+ * `Reroll`) but not arithmetic wrappers — callers should run
+ * `containsDicePool` first to reject those.
+ *
+ * Used by the parser to reject `!`, `!!`, `!p` applied to Fate pools
+ * (`4dF!`, `(4dF)kh2!`, etc.). Fate explosion semantics are undefined, so
+ * parse-time rejection is preferred over a silent evaluator no-op.
+ *
+ * Inside a `Group`, recursion uses `deepContainsFatePool` to mirror
+ * `containsDicePool`'s deep walk through the same case — otherwise
+ * `{4dF+1d6}cf` slips past the bare-Fate guard and the default fumble
+ * check (`result === 1`) flips `+1` faces into fumbles.
+ */
+export declare function containsFatePool(node: ASTNode): boolean;
+/**
+ * Deeper variant of `containsFatePool` that recurses through arithmetic and
+ * function wrappers. Mirrors `deepContainsDicePool`. Used from
+ * `containsFatePool`'s `Group` case so single-sub-roll groups containing
+ * arithmetic-wrapped Fate (`{4dF+1d6}cf`) still trip the bare-Fate guard.
+ *
+ * Outside a `Group`, ordinary parenthesized arithmetic (`(4dF+1d6)cf`) is
+ * already rejected upstream by shallow `containsDicePool`, so this helper
+ * intentionally stays Group-internal.
+ */
+export declare function deepContainsFatePool(node: ASTNode): boolean;
+/**
+ * Deep-walks a node to find any descendant `Group` with two or more
+ * sub-expressions. Used by `rejectGroupTarget`'s single-sub-roll
+ * passthrough so a multi-sub Group buried under arithmetic
+ * (`{{1d6,2d8}+0}cs>5`), function calls (`{abs({1d6,2d8})}cs>5`), or any
+ * other non-transparent wrapper still rejects with the same error code.
+ *
+ * Without this walk, the unwrap inside `rejectGroupTarget` only peels
+ * `Grouped`/`Modifier`/`Sort`/`CritThreshold` — a multi-sub Group cloaked
+ * in a `BinaryOp`/`UnaryOp`/`FunctionCall` revives issue #97.
+ */
+export declare function containsMultiSubGroup(node: ASTNode): boolean;
+/**
+ * Deep-walks a node to find any descendant `Versus`. Used by
+ * `rejectVersusTarget`'s single-sub-roll Group passthrough so a buried
+ * Versus (`{1+(1d20 vs 15)}cs>18`, `{abs(1d20 vs 15)}cs>18`,
+ * `{-(1d20 vs 15)}kh1`) still rejects with `NESTED_VERSUS` instead of
+ * silently dropping `versusMetadata` at the modifier consumer site.
  */
-export declare function containsDice(node: ASTNode): boolean;
+export declare function containsVersus(node: ASTNode): boolean;
 //# sourceMappingURL=ast.d.ts.map

package/dist/parser/ast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/parser/ast.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/parser/ast.ts"],"names":[],"mappings":"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"}

package/dist/parser/parser.d.ts

@@ -3,11 +3,11 @@
  *
  * @module parser/parser
  */
-import type { RollParserErrorCode } from '../errors';
-import { RollParserError } from '../errors';
-import { type Token } from '../lexer/tokens';
-import type { ComparePoint } from '../types';
-import type { ASTNode } from './ast';
+import type { RollParserErrorCode } from '../errors.js';
+import { RollParserError } from '../errors.js';
+import { type Token } from '../lexer/tokens.js';
+import type { ComparePoint } from '../types.js';
+import type { ASTNode } from './ast.js';
 /**
  * Error thrown when the parser encounters invalid syntax.
  */
@@ -25,6 +25,7 @@ export declare class ParseError extends RollParserError {
 export declare class Parser {
     private readonly tokens;
     private pos;
+    private depth;
     constructor(tokens: Token[]);
     /**
      * Parse the token stream into an AST.
@@ -44,6 +45,11 @@ export declare class Parser {
      * Handles tokens that appear between expressions (infix/postfix position).
      */
     private parseLed;
+    /**
+     * Zero-width span for synthetic nodes (implicit counts, `d%` sides) that
+     * have no source text of their own — anchored at the governing token.
+     */
+    private static syntheticLiteral;
     private parseLiteral;
     private parseUnaryMinus;
     private parsePrefixDice;
@@ -53,12 +59,42 @@ export declare class Parser {
     private parsePrefixFateDice;
     private parseInfixFateDice;
     private parseGrouped;
+    private parseGroup;
+    private parseVariable;
     private parseFunctionCall;
     private parseBinaryOp;
+    /**
+     * Rejects a dice token whose count operand is itself a bare (unparenthesized)
+     * dice expression. `4d6d1` would otherwise silently parse as `(4d6)d1` —
+     * roll 4d6, then use the result as a count of d1 dice — which is almost
+     * never intended: every major dice dialect reads `4d6d1` as "drop lowest 1".
+     * Both meanings stay reachable through explicit forms: `4d6dl1` to drop,
+     * `(4d6)d1` for nested dice.
+     */
+    private rejectBareDiceChain;
     private rejectSuccessCountTarget;
+    /**
+     * Rejects `GroupNode` (or a wrapper-cloaked group) as the target of `token`.
+     * Explode, reroll, and crit-threshold wrap bare dice pools only — a group
+     * is a container of sub-expressions, so these modifiers have no defined
+     * semantics. Walks `Grouped`/`Modifier`/`Sort`/`CritThreshold` so wrappers
+     * cannot smuggle a group past the check (`{1d6}kh1cs>5`, `({1d6})!`,
+     * `{1d6}scs>5` all reject the same as `{1d6}!`/`{1d6}cs>5`).
+     *
+     * `singleSubRollPasses` opts the caller into the Stage 3 single-sub-roll
+     * passthrough rule (STAGE3.md "Group Semantics: Single vs Multi Sub-Roll"):
+     * a `Group` with one expression is the user's explicit flat-pool escape
+     * hatch and is equivalent to its unwrapped form. Currently only
+     * `parseCritThreshold` opts in — explode/reroll keep the strict reject so
+     * existing notation contracts don't shift.
+     */
+    private rejectGroupTarget;
+    private rejectVersusTarget;
     private parseModifier;
     private parseExplode;
     private parseReroll;
+    private parseSort;
+    private parseCritThreshold;
     private parseSuccessCount;
     private parseVersus;
     /**
@@ -69,6 +105,13 @@ export declare class Parser {
      * Parses a comparison operator followed by a value expression.
      * Called by modifier parsers (explode, reroll, success counting).
      *
+     * The threshold value is parsed at `BP.DICE_LEFT`, which binds tighter than
+     * arithmetic. This keeps the comparison bound to the dice pool on the left
+     * rather than letting arithmetic to the right be consumed into the
+     * threshold. As a consequence, `1d6>=5+2` parses as `(1d6>=5)+2` with
+     * threshold `5` — not `7`. Computed thresholds require parens:
+     * `1d6>=(5+2)`. Same binding applies to `parseSuccessCount` below.
+     *
      * @returns A ComparePoint with the operator and value AST node
      * @throws {ParseError} If the next token is not a comparison operator
      */

package/dist/parser/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser/parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,KAAK,EACV,OAAO,EAYR,MAAM,OAAO,CAAC;AAGf;;GAEG;AACH,qBAAa,UAAW,SAAQ,eAAe;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAMxF;AAkDD;;;;;GAKG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,GAAG,CAAK;gBAEJ,MAAM,EAAE,KAAK,EAAE;IAI3B;;OAEG;IACH,KAAK,IAAI,OAAO;IAqBhB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAsChB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAwDhB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,sBAAsB;IAS9B,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,iBAAiB;IAgDzB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,wBAAwB;IAWhC,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,iBAAiB;IAgCzB,OAAO,CAAC,WAAW;IAenB;;OAEG;IACH,mBAAmB,IAAI,OAAO;IAW9B;;;;;;OAMG;IACH,iBAAiB,IAAI,YAAY;IAWjC,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,SAAS;IA8CjB,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,SAAS;CAGlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI/C"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser/parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,OAAO,EAkBR,MAAM,UAAU,CAAC;AAYlB;;GAEG;AACH,qBAAa,UAAW,SAAQ,eAAe;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAMxF;AAwED;;;;;GAKG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,KAAK,CAAK;gBAEN,MAAM,EAAE,KAAK,EAAE;IAI3B;;OAEG;IACH,KAAK,IAAI,OAAO;IAqBhB;;OAEG;IACH,OAAO,CAAC,eAAe;IA8BvB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IA4ChB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAgEhB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAI/B,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,eAAe;IAcvB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,sBAAsB;IAW9B,OAAO,CAAC,qBAAqB;IAc7B,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,kBAAkB;IAe1B,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,UAAU;IA4BlB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,iBAAiB;IA0DzB,OAAO,CAAC,aAAa;IAmBrB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAoB3B,OAAO,CAAC,wBAAwB;IAgBhC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,kBAAkB;IAoC1B,OAAO,CAAC,aAAa;IAqDrB,OAAO,CAAC,YAAY;IA+DpB,OAAO,CAAC,WAAW;IAyCnB,OAAO,CAAC,SAAS;IAgDjB,OAAO,CAAC,kBAAkB;IA+E1B,OAAO,CAAC,iBAAiB;IA8CzB,OAAO,CAAC,WAAW;IA6BnB;;OAEG;IACH,mBAAmB,IAAI,OAAO;IAW9B;;;;;;;;;;;;;OAaG;IACH,iBAAiB,IAAI,YAAY;IAajC,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,SAAS;IA2DjB,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,MAAM;IAed,OAAO,CAAC,SAAS;CAGlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI/C"}

package/dist/rng/index.d.ts

@@ -3,6 +3,6 @@
  *
  * @module rng
  */
-export type { RNG } from './types';
-export { SeededRNG } from './seeded';
+export type { RNG } from './types.js';
+export { SeededRNG } from './seeded.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rng/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rng/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/rng/mock.d.ts

@@ -3,7 +3,7 @@
  *
  * @module rng/mock
  */
-import type { RNG } from './types';
+import type { RNG } from './types.js';
 /**
  * Error thrown when MockRNG exhausts its predefined values.
  *

package/dist/rng/mock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/rng/mock.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAK7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAsBnD"}
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/rng/mock.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAK7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAsBnD"}

package/dist/rng/seeded.d.ts

@@ -3,7 +3,7 @@
  *
  * @module rng/seeded
  */
-import type { RNG } from './types';
+import type { RNG } from './types.js';
 /**
  * Seedable pseudo-random number generator using xorshift128.
  *
@@ -29,5 +29,12 @@ export declare class SeededRNG implements RNG {
     private nextUint32;
     next(): number;
     nextInt(min: number, max: number): number;
+    /**
+     * Unbiased sampling in `[0, range)` for ranges above 2^32, built from two
+     * uint32 draws combined into a 53-bit integer (the largest width JS numbers
+     * represent exactly). Ranges beyond 2^53 cannot be sampled without bias —
+     * throw instead of silently degrading.
+     */
+    private nextBoundedWide;
 }
 //# sourceMappingURL=seeded.d.ts.map

package/dist/rng/seeded.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seeded.d.ts","sourceRoot":"","sources":["../../src/rng/seeded.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,YAAW,GAAG;IACnC,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;gBAEP,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAelC,OAAO,CAAC,SAAS;IA+BjB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,UAAU;IAgBlB,IAAI,IAAI,MAAM;IAKd,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;CAsB1C"}
+{"version":3,"file":"seeded.d.ts","sourceRoot":"","sources":["../../src/rng/seeded.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,YAAW,GAAG;IACnC,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;gBAEP,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAelC,OAAO,CAAC,SAAS;IA+BjB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,UAAU;IAgBlB,IAAI,IAAI,MAAM;IAKd,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IA6BzC;;;;;OAKG;IACH,OAAO,CAAC,eAAe;CAiBxB"}

package/dist/roll.d.ts

@@ -3,8 +3,8 @@
  *
  * @module roll
  */
-import type { RNG } from './rng/types';
-import type { RollResult } from './types';
+import type { RNG } from './rng/types.js';
+import type { RollResult } from './types.js';
 /**
  * Options for the roll function.
  */
@@ -19,6 +19,10 @@ export type RollOptions = {
     maxExplodeIterations?: number;
     /** Maximum reroll iterations allowed per die (default: 1,000) */
     maxRerollIterations?: number;
+    /** Variable context for `@name` / `@{name}` references (default: empty) */
+    context?: Record<string, number>;
+    /** Behavior when a referenced variable is missing from context (default: 'throw') */
+    onMissingVariable?: 'throw' | 'zero';
 };
 /**
  * Parses and evaluates a dice notation string.

package/dist/roll.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roll.d.ts","sourceRoot":"","sources":["../src/roll.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,KAAK,EAAmB,UAAU,EAAE,MAAM,SAAS,CAAC;AAM3D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,uDAAuD;IACvD,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,CAa5E"}
+{"version":3,"file":"roll.d.ts","sourceRoot":"","sources":["../src/roll.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAmB,UAAU,EAAE,MAAM,YAAY,CAAC;AAM9D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,uDAAuD;IACvD,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qFAAqF;IACrF,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,CAiB5E"}

package/dist/testing.d.ts

@@ -5,7 +5,7 @@
  *
  * @module testing
  */
-import { MockRNGExhaustedError as _MockRNGExhaustedError, createMockRng as _createMockRng } from './rng/mock';
+import { MockRNGExhaustedError as _MockRNGExhaustedError, createMockRng as _createMockRng } from './rng/mock.js';
 export declare const createMockRng: typeof _createMockRng;
 export declare const MockRNGExhaustedError: typeof _MockRNGExhaustedError;
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,qBAAqB,IAAI,sBAAsB,EAC/C,aAAa,IAAI,cAAc,EAChC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,aAAa,uBAAiB,CAAC;AAC5C,eAAO,MAAM,qBAAqB,+BAAyB,CAAC"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,qBAAqB,IAAI,sBAAsB,EAC/C,aAAa,IAAI,cAAc,EAChC,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,aAAa,uBAAiB,CAAC;AAC5C,eAAO,MAAM,qBAAqB,+BAAyB,CAAC"}