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

package/dist/cli.js

@@ -15,14 +15,23 @@ var ROLL_PARSER_ERROR_CODES = [
   "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"
+  "UNKNOWN_FUNCTION",
+  "UNDEFINED_VARIABLE",
+  "INVALID_VARIABLE_VALUE",
+  "AMBIGUOUS_DICE_CHAIN",
+  "MAX_DEPTH_EXCEEDED",
+  "NON_FINITE_RESULT"
 ];
 
 class RollParserError extends Error {
@@ -73,7 +82,14 @@ var TokenType;
   TokenType2[TokenType2["FAIL"] = 27] = "FAIL";
   TokenType2[TokenType2["FUNCTION"] = 28] = "FUNCTION";
   TokenType2[TokenType2["VS"] = 29] = "VS";
-  TokenType2[TokenType2["EOF"] = 30] = "EOF";
+  TokenType2[TokenType2["LBRACE"] = 30] = "LBRACE";
+  TokenType2[TokenType2["RBRACE"] = 31] = "RBRACE";
+  TokenType2[TokenType2["AT"] = 32] = "AT";
+  TokenType2[TokenType2["SORT_ASC"] = 33] = "SORT_ASC";
+  TokenType2[TokenType2["SORT_DESC"] = 34] = "SORT_DESC";
+  TokenType2[TokenType2["CRIT_SUCCESS"] = 35] = "CRIT_SUCCESS";
+  TokenType2[TokenType2["CRIT_FAIL"] = 36] = "CRIT_FAIL";
+  TokenType2[TokenType2["EOF"] = 37] = "EOF";
 })(TokenType ||= {});
 
 // src/lexer/lexer.ts
@@ -103,8 +119,23 @@ var IDENTIFIER_KEYWORDS = {
   round: 28 /* FUNCTION */,
   abs: 28 /* FUNCTION */,
   max: 28 /* FUNCTION */,
-  min: 28 /* FUNCTION */
+  min: 28 /* FUNCTION */,
+  s: 33 /* SORT_ASC */,
+  sa: 33 /* SORT_ASC */,
+  sd: 34 /* SORT_DESC */,
+  cs: 35 /* CRIT_SUCCESS */,
+  cf: 36 /* CRIT_FAIL */
 };
+function buildIdentifierHint(identifier) {
+  for (let length = identifier.length - 1;length >= 1; length--) {
+    const prefix = identifier.slice(0, length);
+    if (IDENTIFIER_KEYWORDS[prefix] == null)
+      continue;
+    const rest = identifier.slice(length);
+    return ` (did you mean '${prefix}' followed by '${rest}'? separate modifiers with a count or space, e.g. '${prefix}1${rest}')`;
+  }
+  return "";
+}
 
 class Lexer {
   pos = 0;
@@ -117,7 +148,7 @@ class Lexer {
     while (true) {
       const token = this.nextToken();
       tokens.push(token);
-      if (token.type === 30 /* EOF */)
+      if (token.type === 37 /* EOF */)
         break;
     }
     return tokens;
@@ -125,7 +156,7 @@ class Lexer {
   nextToken() {
     this.skipWhitespace();
     if (this.isAtEnd()) {
-      return this.createToken(30 /* EOF */, "");
+      return this.createToken(37 /* EOF */, "");
     }
     const startPos = this.pos;
     const char = this.peek();
@@ -135,6 +166,9 @@ class Lexer {
     if (this.isAlpha(char)) {
       return this.scanIdentifier();
     }
+    if (char === "@") {
+      return this.scanAt();
+    }
     this.advance();
     switch (char) {
       case "+":
@@ -158,6 +192,10 @@ class Lexer {
         return this.createTokenAt(16 /* RPAREN */, char, startPos);
       case ",":
         return this.createTokenAt(17 /* COMMA */, char, startPos);
+      case "{":
+        return this.createTokenAt(30 /* LBRACE */, char, startPos);
+      case "}":
+        return this.createTokenAt(31 /* RBRACE */, char, startPos);
       case ">":
         if (this.match("=")) {
           return this.createTokenAt(11 /* GREATER_EQUAL */, ">=", startPos);
@@ -179,8 +217,11 @@ class Lexer {
           return this.createTokenAt(24 /* EXPLODE_PENETRATING */, "!p", startPos);
         }
         return this.createTokenAt(22 /* EXPLODE */, char, startPos);
-      default:
-        throw new LexerError("Unexpected character", "UNEXPECTED_CHARACTER", startPos, char);
+      default: {
+        const codePoint = this.input.codePointAt(startPos);
+        const display = codePoint == null ? char : String.fromCodePoint(codePoint);
+        throw new LexerError("Unexpected character", "UNEXPECTED_CHARACTER", startPos, display);
+      }
     }
   }
   skipWhitespace() {
@@ -224,7 +265,36 @@ class Lexer {
     if (tokenType != null) {
       return this.createTokenAt(tokenType, lower, startPos);
     }
-    throw new LexerError("Unexpected identifier", "UNEXPECTED_IDENTIFIER", startPos, lower);
+    throw new LexerError(`Unexpected identifier${buildIdentifierHint(lower)}`, "UNEXPECTED_IDENTIFIER", startPos, lower);
+  }
+  scanAt() {
+    const startPos = this.pos;
+    this.advance();
+    let name;
+    if (!this.isAtEnd() && this.peek() === "{") {
+      this.advance();
+      const nameStart = this.pos;
+      while (!this.isAtEnd() && this.peek() !== "}" && this.peek() !== `
+`) {
+        this.advance();
+      }
+      if (this.isAtEnd() || this.peek() !== "}") {
+        throw new LexerError("Unterminated @{...} variable", "UNEXPECTED_CHARACTER", startPos, "@");
+      }
+      name = this.input.slice(nameStart, this.pos);
+      this.advance();
+    } else {
+      const nameStart = this.pos;
+      if (this.isAtEnd() || !this.isIdentifierStart(this.peek())) {
+        throw new LexerError("Empty @ variable name", "UNEXPECTED_CHARACTER", startPos, "@");
+      }
+      this.advance();
+      while (!this.isAtEnd() && this.isIdentifierPart(this.peek())) {
+        this.advance();
+      }
+      name = this.input.slice(nameStart, this.pos);
+    }
+    return this.createTokenAt(32 /* AT */, name, startPos);
   }
   peek() {
     return this.input[this.pos] ?? "";
@@ -253,15 +323,21 @@ class Lexer {
     const c = char.toLowerCase();
     return c >= "a" && c <= "z";
   }
+  isIdentifierStart(char) {
+    return this.isAlpha(char) || char === "_";
+  }
+  isIdentifierPart(char) {
+    return this.isAlpha(char) || this.isDigit(char) || char === "_";
+  }
   isWhitespace(char) {
     return char === " " || char === "\t" || char === `
 ` || char === "\r";
   }
   createToken(type, value) {
-    return { type, value, position: this.pos };
+    return { type, value, position: this.pos, end: this.pos };
   }
   createTokenAt(type, value, position) {
-    return { type, value, position };
+    return { type, value, position, end: this.pos };
   }
 }
 function lex(input) {
@@ -275,26 +351,178 @@ function isModifier(node) {
 function isSuccessCount(node) {
   return node.type === "SuccessCount";
 }
-function containsDice(node) {
+function isCritThreshold(node) {
+  return node.type === "CritThreshold";
+}
+function unwrapTransparent(node, kinds) {
+  let current = node;
+  while (true) {
+    switch (current.type) {
+      case "Grouped":
+        if (!kinds.includes("Grouped"))
+          return current;
+        current = current.expression;
+        break;
+      case "Modifier":
+        if (!kinds.includes("Modifier"))
+          return current;
+        current = current.target;
+        break;
+      case "Sort":
+        if (!kinds.includes("Sort"))
+          return current;
+        current = current.target;
+        break;
+      case "CritThreshold":
+        if (!kinds.includes("CritThreshold"))
+          return current;
+        current = current.target;
+        break;
+      default:
+        return current;
+    }
+  }
+}
+function containsDicePool(node) {
+  switch (node.type) {
+    case "Dice":
+    case "FateDice":
+    case "Modifier":
+    case "Explode":
+    case "Reroll":
+      return true;
+    case "Sort":
+    case "CritThreshold":
+      return containsDicePool(node.target);
+    case "Grouped":
+      return containsDicePool(node.expression);
+    case "Group":
+      return node.expressions.length >= 2 || node.expressions.some(deepContainsDicePool);
+    default:
+      return false;
+  }
+}
+function deepContainsDicePool(node) {
   switch (node.type) {
     case "Dice":
     case "FateDice":
       return true;
-    case "Literal":
+    case "BinaryOp":
+      return deepContainsDicePool(node.left) || deepContainsDicePool(node.right);
+    case "UnaryOp":
+      return deepContainsDicePool(node.operand);
+    case "Modifier":
+    case "Explode":
+    case "Reroll":
+    case "SuccessCount":
+    case "Sort":
+    case "CritThreshold":
+      return deepContainsDicePool(node.target);
+    case "Versus":
+      return deepContainsDicePool(node.roll) || deepContainsDicePool(node.dc);
+    case "FunctionCall":
+      return node.args.some(deepContainsDicePool);
+    case "Grouped":
+      return deepContainsDicePool(node.expression);
+    case "Group":
+      return node.expressions.length >= 2 || node.expressions.some(deepContainsDicePool);
+    default:
       return false;
+  }
+}
+function containsFatePool(node) {
+  switch (node.type) {
+    case "FateDice":
+      return true;
+    case "Modifier":
+    case "Explode":
+    case "Reroll":
+    case "Sort":
+    case "CritThreshold":
+      return containsFatePool(node.target);
+    case "Grouped":
+      return containsFatePool(node.expression);
+    case "Group":
+      return node.expressions.some(deepContainsFatePool);
+    default:
+      return false;
+  }
+}
+function deepContainsFatePool(node) {
+  switch (node.type) {
+    case "FateDice":
+      return true;
     case "BinaryOp":
-      return containsDice(node.left) || containsDice(node.right);
+      return deepContainsFatePool(node.left) || deepContainsFatePool(node.right);
     case "UnaryOp":
-      return containsDice(node.operand);
+      return deepContainsFatePool(node.operand);
     case "Modifier":
     case "Explode":
     case "Reroll":
     case "SuccessCount":
-      return containsDice(node.target);
+    case "Sort":
+    case "CritThreshold":
+      return deepContainsFatePool(node.target);
     case "Versus":
-      return containsDice(node.roll) || containsDice(node.dc);
+      return deepContainsFatePool(node.roll) || deepContainsFatePool(node.dc);
     case "FunctionCall":
-      return node.args.some(containsDice);
+      return node.args.some(deepContainsFatePool);
+    case "Grouped":
+      return deepContainsFatePool(node.expression);
+    case "Group":
+      return node.expressions.some(deepContainsFatePool);
+    default:
+      return false;
+  }
+}
+function containsMultiSubGroup(node) {
+  switch (node.type) {
+    case "Group":
+      return node.expressions.length >= 2 || node.expressions.some(containsMultiSubGroup);
+    case "BinaryOp":
+      return containsMultiSubGroup(node.left) || containsMultiSubGroup(node.right);
+    case "UnaryOp":
+      return containsMultiSubGroup(node.operand);
+    case "Modifier":
+    case "Explode":
+    case "Reroll":
+    case "SuccessCount":
+    case "Sort":
+    case "CritThreshold":
+      return containsMultiSubGroup(node.target);
+    case "Versus":
+      return containsMultiSubGroup(node.roll) || containsMultiSubGroup(node.dc);
+    case "FunctionCall":
+      return node.args.some(containsMultiSubGroup);
+    case "Grouped":
+      return containsMultiSubGroup(node.expression);
+    default:
+      return false;
+  }
+}
+function containsVersus(node) {
+  switch (node.type) {
+    case "Versus":
+      return true;
+    case "BinaryOp":
+      return containsVersus(node.left) || containsVersus(node.right);
+    case "UnaryOp":
+      return containsVersus(node.operand);
+    case "Modifier":
+    case "Explode":
+    case "Reroll":
+    case "SuccessCount":
+    case "Sort":
+    case "CritThreshold":
+      return containsVersus(node.target);
+    case "FunctionCall":
+      return node.args.some(containsVersus);
+    case "Grouped":
+      return containsVersus(node.expression);
+    case "Group":
+      return node.expressions.some(containsVersus);
+    default:
+      return false;
   }
 }
 
@@ -312,6 +540,7 @@ class ParseError extends RollParserError {
 var BP = {
   VS_LEFT: 2,
   VS_RIGHT: 3,
+  COMPARE: 8,
   ADD_LEFT: 10,
   ADD_RIGHT: 11,
   MUL_LEFT: 20,
@@ -323,6 +552,14 @@ var BP = {
   DICE_LEFT: 40,
   DICE_RIGHT: 41
 };
+var MAX_PARSE_DEPTH = 128;
+var TOKEN_DISPLAY = {
+  [15 /* LPAREN */]: `'('`,
+  [16 /* RPAREN */]: `')'`,
+  [30 /* LBRACE */]: `'{'`,
+  [31 /* RBRACE */]: `'}'`,
+  [17 /* COMMA */]: `','`
+};
 var FUNCTION_ARITY = {
   floor: { min: 1, max: 1 },
   ceil: { min: 1, max: 1 },
@@ -335,31 +572,40 @@ var FUNCTION_ARITY = {
 class Parser {
   tokens;
   pos = 0;
+  depth = 0;
   constructor(tokens) {
     this.tokens = tokens;
   }
   parse() {
-    if (this.peek().type === 30 /* EOF */) {
+    if (this.peek().type === 37 /* EOF */) {
       throw new ParseError("Unexpected end of input", "UNEXPECTED_END", this.peek().position);
     }
     const ast = this.parseExpression(0);
-    if (this.peek().type !== 30 /* EOF */) {
+    if (this.peek().type !== 37 /* EOF */) {
       const token = this.peek();
       throw new ParseError(`Unexpected token '${token.value}'`, "UNEXPECTED_TOKEN", token.position, token);
     }
     return ast;
   }
   parseExpression(minBp) {
-    let left = this.parseNud();
-    while (this.hasTokens()) {
-      const token = this.peek();
-      const leftBp = this.getLeftBp(token);
-      if (leftBp < minBp)
-        break;
-      this.advance();
-      left = this.parseLed(left, token);
+    this.depth += 1;
+    if (this.depth > MAX_PARSE_DEPTH) {
+      throw new ParseError(`Expression nesting exceeds the maximum depth of ${MAX_PARSE_DEPTH}`, "MAX_DEPTH_EXCEEDED", this.peek().position, this.peek());
+    }
+    try {
+      let left = this.parseNud();
+      while (this.hasTokens()) {
+        const token = this.peek();
+        const leftBp = this.getLeftBp(token);
+        if (leftBp < minBp)
+          break;
+        this.advance();
+        left = this.parseLed(left, token);
+      }
+      return left;
+    } finally {
+      this.depth -= 1;
     }
-    return left;
   }
   parseNud() {
     const token = this.advance();
@@ -367,18 +613,22 @@ class Parser {
       case 0 /* NUMBER */:
         return this.parseLiteral(token);
       case 5 /* MINUS */:
-        return this.parseUnaryMinus();
+        return this.parseUnaryMinus(token);
       case 1 /* DICE */:
-        return this.parsePrefixDice();
+        return this.parsePrefixDice(token);
       case 2 /* DICE_PERCENT */:
-        return this.parsePrefixDicePercent();
+        return this.parsePrefixDicePercent(token);
       case 3 /* DICE_FATE */:
-        return this.parsePrefixFateDice();
+        return this.parsePrefixFateDice(token);
       case 15 /* LPAREN */:
-        return this.parseGrouped();
+        return this.parseGrouped(token);
+      case 30 /* LBRACE */:
+        return this.parseGroup(token);
       case 28 /* FUNCTION */:
         return this.parseFunctionCall(token);
-      case 30 /* EOF */:
+      case 32 /* AT */:
+        return this.parseVariable(token);
+      case 37 /* EOF */:
         throw new ParseError("Unexpected end of input", "UNEXPECTED_END", token.position);
       default:
         throw new ParseError(`Unexpected token '${token.value}'`, "UNEXPECTED_TOKEN", token.position, token);
@@ -387,11 +637,11 @@ class Parser {
   parseLed(left, token) {
     switch (token.type) {
       case 1 /* DICE */:
-        return this.parseInfixDice(left);
+        return this.parseInfixDice(left, token);
       case 2 /* DICE_PERCENT */:
-        return this.parseInfixDicePercent(left);
+        return this.parseInfixDicePercent(left, token);
       case 3 /* DICE_FATE */:
-        return this.parseInfixFateDice(left);
+        return this.parseInfixFateDice(left, token);
       case 4 /* PLUS */:
       case 5 /* MINUS */:
       case 6 /* MULTIPLY */:
@@ -411,6 +661,12 @@ class Parser {
       case 25 /* REROLL */:
       case 26 /* REROLL_ONCE */:
         return this.parseReroll(left, token);
+      case 33 /* SORT_ASC */:
+      case 34 /* SORT_DESC */:
+        return this.parseSort(left, token);
+      case 35 /* CRIT_SUCCESS */:
+      case 36 /* CRIT_FAIL */:
+        return this.parseCritThreshold(left, token);
       case 10 /* GREATER */:
       case 11 /* GREATER_EQUAL */:
       case 12 /* LESS */:
@@ -423,78 +679,134 @@ class Parser {
         throw new ParseError(`Unexpected infix token '${token.value}'`, "UNEXPECTED_TOKEN", token.position, token);
     }
   }
+  static syntheticLiteral(value, token) {
+    return { type: "Literal", value, start: token.position, end: token.position };
+  }
   parseLiteral(token) {
     return {
       type: "Literal",
-      value: Number.parseFloat(token.value)
+      value: Number.parseFloat(token.value),
+      start: token.position,
+      end: token.end
     };
   }
-  parseUnaryMinus() {
+  parseUnaryMinus(token) {
     const operand = this.parseExpression(BP.UNARY);
+    this.rejectSuccessCountTarget(operand, token);
     return {
       type: "UnaryOp",
       operator: "-",
-      operand
+      operand,
+      start: token.position,
+      end: operand.end ?? token.end
     };
   }
-  parsePrefixDice() {
+  parsePrefixDice(token) {
     const sides = this.parseExpression(BP.DICE_RIGHT);
+    this.rejectSuccessCountTarget(sides, token);
+    this.rejectVersusTarget(sides, token);
     return {
       type: "Dice",
-      count: { type: "Literal", value: 1 },
-      sides
+      count: Parser.syntheticLiteral(1, token),
+      sides,
+      start: token.position,
+      end: sides.end ?? token.end
     };
   }
-  parseInfixDice(left) {
+  parseInfixDice(left, token) {
+    this.rejectSuccessCountTarget(left, token);
+    this.rejectVersusTarget(left, token);
+    this.rejectBareDiceChain(left, token);
     const sides = this.parseExpression(BP.DICE_RIGHT);
+    this.rejectSuccessCountTarget(sides, token);
+    this.rejectVersusTarget(sides, token);
     return {
       type: "Dice",
       count: left,
-      sides
+      sides,
+      start: left.start ?? token.position,
+      end: sides.end ?? token.end
     };
   }
-  parsePrefixDicePercent() {
+  parsePrefixDicePercent(token) {
     return {
       type: "Dice",
-      count: { type: "Literal", value: 1 },
-      sides: { type: "Literal", value: 100 }
+      count: Parser.syntheticLiteral(1, token),
+      sides: Parser.syntheticLiteral(100, token),
+      start: token.position,
+      end: token.end
     };
   }
-  parseInfixDicePercent(left) {
+  parseInfixDicePercent(left, token) {
+    this.rejectSuccessCountTarget(left, token);
+    this.rejectVersusTarget(left, token);
+    this.rejectBareDiceChain(left, token);
     return {
       type: "Dice",
       count: left,
-      sides: { type: "Literal", value: 100 }
+      sides: Parser.syntheticLiteral(100, token),
+      start: left.start ?? token.position,
+      end: token.end
     };
   }
-  parsePrefixFateDice() {
+  parsePrefixFateDice(token) {
     return {
       type: "FateDice",
-      count: { type: "Literal", value: 1 }
+      count: Parser.syntheticLiteral(1, token),
+      start: token.position,
+      end: token.end
     };
   }
-  parseInfixFateDice(left) {
+  parseInfixFateDice(left, token) {
+    this.rejectSuccessCountTarget(left, token);
+    this.rejectVersusTarget(left, token);
+    this.rejectBareDiceChain(left, token);
     return {
       type: "FateDice",
-      count: left
+      count: left,
+      start: left.start ?? token.position,
+      end: token.end
     };
   }
-  parseGrouped() {
-    const expr = this.parseExpression(0);
-    this.expect(16 /* RPAREN */);
-    return expr;
+  parseGrouped(token) {
+    const expression = this.parseExpression(0);
+    const close = this.expect(16 /* RPAREN */);
+    return { type: "Grouped", expression, start: token.position, end: close.end };
+  }
+  parseGroup(startToken) {
+    if (this.peek().type === 31 /* RBRACE */) {
+      throw new ParseError("Empty group", "UNEXPECTED_TOKEN", startToken.position, startToken);
+    }
+    const expressions = [this.parseExpression(0)];
+    while (this.peek().type === 17 /* COMMA */) {
+      this.advance();
+      expressions.push(this.parseExpression(0));
+    }
+    if (this.peek().type !== 31 /* RBRACE */) {
+      const unterminated = this.peek();
+      throw new ParseError(`Unterminated group: expected '}' or ','`, "EXPECTED_TOKEN", unterminated.position, unterminated);
+    }
+    const close = this.advance();
+    return { type: "Group", expressions, start: startToken.position, end: close.end };
+  }
+  parseVariable(token) {
+    return { type: "Variable", name: token.value, start: token.position, end: token.end };
   }
   parseFunctionCall(token) {
     this.expect(15 /* LPAREN */);
     const args = [];
     if (this.peek().type !== 16 /* RPAREN */) {
-      args.push(this.parseExpression(0));
+      const first = this.parseExpression(0);
+      this.rejectSuccessCountTarget(first, token);
+      args.push(first);
       while (this.peek().type === 17 /* COMMA */) {
         this.advance();
-        args.push(this.parseExpression(0));
+        const next = this.parseExpression(0);
+        this.rejectSuccessCountTarget(next, token);
+        args.push(next);
       }
     }
-    this.expect(16 /* RPAREN */);
+    const close = this.expect(16 /* RPAREN */);
     const arity = FUNCTION_ARITY[token.value];
     if (arity === undefined) {
       throw new ParseError(`Unknown function '${token.value}'`, "UNKNOWN_FUNCTION", token.position, token);
@@ -503,84 +815,244 @@ class Parser {
       const expected = arity.max === Number.POSITIVE_INFINITY ? `at least ${arity.min}` : arity.min === arity.max ? `${arity.min}` : `${arity.min}–${arity.max}`;
       throw new ParseError(`Function '${token.value}' expects ${expected} argument${arity.min === 1 && arity.max === 1 ? "" : "s"}, got ${args.length}`, "INVALID_FUNCTION_ARITY", token.position, token);
     }
-    return { type: "FunctionCall", name: token.value, args };
+    return {
+      type: "FunctionCall",
+      name: token.value,
+      args,
+      start: token.position,
+      end: close.end
+    };
   }
   parseBinaryOp(left, token) {
+    this.rejectSuccessCountTarget(left, token);
     const operator = this.getOperatorSymbol(token);
     const rightBp = this.getRightBp(token);
     const right = this.parseExpression(rightBp);
+    this.rejectSuccessCountTarget(right, token);
     return {
       type: "BinaryOp",
       operator,
       left,
-      right
+      right,
+      start: left.start ?? token.position,
+      end: right.end ?? token.end
     };
   }
+  rejectBareDiceChain(left, token) {
+    switch (left.type) {
+      case "Dice":
+      case "FateDice":
+      case "Explode":
+      case "Reroll":
+      case "Modifier":
+      case "Sort":
+      case "CritThreshold":
+        throw new ParseError(`Ambiguous dice chain: use 'dl'/'dh' to drop dice (4d6dl1) or parentheses for nested dice ((4d6)d1)`, "AMBIGUOUS_DICE_CHAIN", token.position, token);
+      default:
+        return;
+    }
+  }
   rejectSuccessCountTarget(target, token) {
-    if (isSuccessCount(target)) {
+    const node = unwrapTransparent(target, ["Grouped"]);
+    if (isSuccessCount(node)) {
       throw new ParseError(`Cannot apply modifier after success counting`, "INVALID_SUCCESS_COUNT_TARGET", token.position, token);
     }
   }
+  rejectGroupTarget(target, token, action, code, singleSubRollPasses = false) {
+    const node = unwrapTransparent(target, ["Grouped", "Modifier", "Sort", "CritThreshold"]);
+    if (node.type !== "Group")
+      return;
+    if (singleSubRollPasses && node.expressions.length === 1) {
+      const inner = node.expressions[0];
+      if (inner != null && containsMultiSubGroup(inner)) {
+        throw new ParseError(`Cannot ${action} a group`, code, token.position, token);
+      }
+      return;
+    }
+    throw new ParseError(`Cannot ${action} a group`, code, token.position, token);
+  }
+  rejectVersusTarget(target, token) {
+    const node = unwrapTransparent(target, ["Grouped"]);
+    if (node.type === "Versus") {
+      throw new ParseError(`Versus cannot be used as a meta-expression`, "NESTED_VERSUS", token.position, token);
+    }
+    if (node.type === "Group" && node.expressions.length === 1) {
+      const inner = node.expressions[0];
+      if (inner != null && containsVersus(inner)) {
+        throw new ParseError(`Versus cannot be used as a meta-expression`, "NESTED_VERSUS", token.position, token);
+      }
+    }
+  }
   parseModifier(target, token) {
     this.rejectSuccessCountTarget(target, token);
+    this.rejectVersusTarget(target, token);
+    if (!containsDicePool(target)) {
+      throw new ParseError(`Keep/drop modifiers require a dice pool target`, "INVALID_MODIFIER_TARGET", token.position, token);
+    }
     const modifier = token.type === 18 /* KEEP_HIGH */ || token.type === 19 /* KEEP_LOW */ ? "keep" : "drop";
     const selector = token.type === 18 /* KEEP_HIGH */ || token.type === 20 /* DROP_HIGH */ ? "highest" : "lowest";
     const nextToken = this.peek().type;
-    const count = nextToken === 0 /* NUMBER */ || nextToken === 15 /* LPAREN */ ? this.parseExpression(BP.DICE_LEFT) : { type: "Literal", value: 1 };
+    const hasExplicitCount = nextToken === 0 /* NUMBER */ || nextToken === 15 /* LPAREN */ || nextToken === 32 /* AT */;
+    const count = hasExplicitCount ? this.parseExpression(BP.DICE_LEFT) : Parser.syntheticLiteral(1, token);
+    this.rejectSuccessCountTarget(count, token);
+    this.rejectVersusTarget(count, token);
     return {
       type: "Modifier",
       modifier,
       selector,
       count,
-      target
+      target,
+      start: target.start ?? token.position,
+      end: hasExplicitCount ? count.end ?? token.end : token.end
     };
   }
   parseExplode(target, token) {
     this.rejectSuccessCountTarget(target, token);
+    this.rejectGroupTarget(target, token, "explode", "INVALID_EXPLODE_TARGET");
+    if (!containsDicePool(target)) {
+      throw new ParseError(`Explode modifier requires a dice pool target`, "INVALID_EXPLODE_TARGET", token.position, token);
+    }
+    if (containsFatePool(target)) {
+      throw new ParseError(`Fate dice cannot explode`, "INVALID_EXPLODE_TARGET", token.position, token);
+    }
     if (target.type === "Explode") {
       throw new ParseError(`Cannot chain explode modifiers`, "INVALID_EXPLODE_TARGET", token.position, token);
     }
     const variant = token.type === 22 /* EXPLODE */ ? "standard" : token.type === 23 /* EXPLODE_COMPOUND */ ? "compound" : "penetrating";
-    const node = { type: "Explode", variant, target };
+    const node = {
+      type: "Explode",
+      variant,
+      target,
+      start: target.start ?? token.position,
+      end: token.end
+    };
     if (this.isComparePointAhead()) {
       node.threshold = this.parseComparePoint();
+      node.end = node.threshold.value.end ?? token.end;
     }
     return node;
   }
   parseReroll(target, token) {
     this.rejectSuccessCountTarget(target, token);
+    this.rejectGroupTarget(target, token, "reroll", "INVALID_REROLL_TARGET");
+    if (!containsDicePool(target)) {
+      throw new ParseError(`Reroll modifier requires a dice pool target`, "INVALID_REROLL_TARGET", token.position, token);
+    }
     if (!this.isComparePointAhead()) {
       throw new ParseError(`Expected comparison operator after '${token.value}'`, "EXPECTED_TOKEN", token.position, token);
     }
     const once = token.type === 26 /* REROLL_ONCE */;
     const condition = this.parseComparePoint();
-    return { type: "Reroll", once, condition, target };
+    return {
+      type: "Reroll",
+      once,
+      condition,
+      target,
+      start: target.start ?? token.position,
+      end: condition.value.end ?? token.end
+    };
+  }
+  parseSort(target, token) {
+    this.rejectSuccessCountTarget(target, token);
+    this.rejectVersusTarget(target, token);
+    if (!deepContainsDicePool(target)) {
+      throw new ParseError(`Sort modifier requires a dice pool target`, "INVALID_SORT_TARGET", token.position, token);
+    }
+    const base = unwrapTransparent(target, ["Grouped", "Modifier", "Sort", "CritThreshold"]);
+    if (base.type === "Group" && base.expressions.length >= 2) {
+      throw new ParseError(`Sort modifier does not yet support multi-sub-roll groups`, "INVALID_SORT_TARGET", token.position, token);
+    }
+    const order = token.type === 33 /* SORT_ASC */ ? "ascending" : "descending";
+    return {
+      type: "Sort",
+      order,
+      target,
+      start: target.start ?? token.position,
+      end: token.end
+    };
+  }
+  parseCritThreshold(target, token) {
+    this.rejectSuccessCountTarget(target, token);
+    this.rejectVersusTarget(target, token);
+    this.rejectGroupTarget(target, token, "apply crit threshold to", "INVALID_CRIT_THRESHOLD_TARGET", true);
+    if (!containsDicePool(target)) {
+      throw new ParseError(`Crit threshold modifier requires a dice pool target`, "INVALID_CRIT_THRESHOLD_TARGET", token.position, token);
+    }
+    if (!this.isComparePointAhead() && containsFatePool(target)) {
+      throw new ParseError(`Bare cs/cf cannot apply to Fate dice`, "INVALID_CRIT_THRESHOLD_TARGET", token.position, token);
+    }
+    const threshold = this.isComparePointAhead() ? this.parseComparePoint() : "default";
+    const end = threshold === "default" ? token.end : threshold.value.end ?? token.end;
+    let chainTarget = target;
+    while (chainTarget.type === "Grouped") {
+      chainTarget = chainTarget.expression;
+    }
+    if (isCritThreshold(chainTarget)) {
+      if (token.type === 35 /* CRIT_SUCCESS */) {
+        chainTarget.successThresholds.push(threshold);
+      } else {
+        chainTarget.failThresholds.push(threshold);
+      }
+      chainTarget.end = end;
+      return chainTarget;
+    }
+    return {
+      type: "CritThreshold",
+      successThresholds: token.type === 35 /* CRIT_SUCCESS */ ? [threshold] : [],
+      failThresholds: token.type === 36 /* CRIT_FAIL */ ? [threshold] : [],
+      target,
+      start: target.start ?? token.position,
+      end
+    };
   }
   parseSuccessCount(target, token) {
     this.rejectSuccessCountTarget(target, token);
-    if (!containsDice(target)) {
-      throw new ParseError(`Success counting requires a dice expression`, "INVALID_SUCCESS_COUNT_TARGET", token.position, token);
+    if (!containsDicePool(target)) {
+      throw new ParseError(`Success counting requires a dice pool target`, "INVALID_SUCCESS_COUNT_TARGET", token.position, token);
     }
     const operator = this.getCompareOp(token);
     const value = this.parseExpression(BP.DICE_LEFT);
+    this.rejectSuccessCountTarget(value, token);
+    this.rejectVersusTarget(value, token);
     const node = {
       type: "SuccessCount",
       target,
-      threshold: { operator, value }
+      threshold: { operator, value },
+      start: target.start ?? token.position,
+      end: value.end ?? token.end
     };
     if (this.peek().type === 27 /* FAIL */) {
       this.advance();
-      const failValue = this.parseExpression(BP.DICE_LEFT);
-      node.failThreshold = { operator: "=", value: failValue };
+      if (this.isComparePointAhead()) {
+        node.failThreshold = this.parseComparePoint();
+      } else {
+        const failValue = this.parseExpression(BP.DICE_LEFT);
+        this.rejectSuccessCountTarget(failValue, token);
+        this.rejectVersusTarget(failValue, token);
+        node.failThreshold = { operator: "=", value: failValue };
+      }
+      node.end = node.failThreshold.value.end ?? node.end ?? token.end;
     }
     return node;
   }
   parseVersus(left, token) {
-    if (left.type === "Versus") {
+    this.rejectSuccessCountTarget(left, token);
+    let leftChain = left;
+    while (leftChain.type === "Grouped") {
+      leftChain = leftChain.expression;
+    }
+    if (leftChain.type === "Versus") {
       throw new ParseError("Cannot chain versus operators", "NESTED_VERSUS", token.position, token);
     }
     const dc = this.parseExpression(BP.VS_RIGHT);
-    return { type: "Versus", roll: left, dc };
+    this.rejectSuccessCountTarget(dc, token);
+    return {
+      type: "Versus",
+      roll: left,
+      dc,
+      start: left.start ?? token.position,
+      end: dc.end ?? token.end
+    };
   }
   isComparePointAhead() {
     const type = this.peek().type;
@@ -591,6 +1063,8 @@ class Parser {
     const operator = this.getCompareOp(token);
     this.advance();
     const value = this.parseExpression(BP.DICE_LEFT);
+    this.rejectSuccessCountTarget(value, token);
+    this.rejectVersusTarget(value, token);
     return { operator, value };
   }
   getCompareOp(token) {
@@ -653,16 +1127,23 @@ class Parser {
       case 24 /* EXPLODE_PENETRATING */:
       case 25 /* REROLL */:
       case 26 /* REROLL_ONCE */:
+      case 33 /* SORT_ASC */:
+      case 34 /* SORT_DESC */:
+      case 35 /* CRIT_SUCCESS */:
+      case 36 /* CRIT_FAIL */:
+        return BP.MODIFIER;
       case 10 /* GREATER */:
       case 11 /* GREATER_EQUAL */:
       case 12 /* LESS */:
       case 13 /* LESS_EQUAL */:
       case 14 /* EQUAL */:
-        return BP.MODIFIER;
+        return BP.COMPARE;
       case 16 /* RPAREN */:
-      case 30 /* EOF */:
+      case 37 /* EOF */:
       case 17 /* COMMA */:
       case 28 /* FUNCTION */:
+      case 30 /* LBRACE */:
+      case 31 /* RBRACE */:
         return -1;
       default:
         return 0;
@@ -688,7 +1169,7 @@ class Parser {
     }
   }
   peek() {
-    return this.tokens[this.pos] ?? { type: 30 /* EOF */, value: "", position: this.pos };
+    return this.tokens[this.pos] ?? { type: 37 /* EOF */, value: "", position: this.pos, end: this.pos };
   }
   advance() {
     const token = this.peek();
@@ -698,13 +1179,14 @@ class Parser {
   expect(type) {
     const token = this.peek();
     if (token.type !== type) {
-      const expected = TokenType[type];
-      throw new ParseError(`Expected ${expected} but got '${token.value}'`, "EXPECTED_TOKEN", token.position, token);
+      const expected = TOKEN_DISPLAY[type] ?? TokenType[type];
+      const got = token.type === 37 /* EOF */ ? "end of input" : `'${token.value}'`;
+      throw new ParseError(`Expected ${expected} but got ${got}`, "EXPECTED_TOKEN", token.position, token);
     }
     return this.advance();
   }
   hasTokens() {
-    return this.peek().type !== 30 /* EOF */;
+    return this.peek().type !== 37 /* EOF */;
   }
 }
 
@@ -771,6 +1253,9 @@ class SeededRNG {
     if (range <= 1) {
       return lo;
     }
+    if (range > 4294967296) {
+      return lo + this.nextBoundedWide(range);
+    }
     const threshold = (4294967296 - range) % range;
     let value;
     do {
@@ -778,6 +1263,56 @@ class SeededRNG {
     } while (value < threshold);
     return lo + value % range;
   }
+  nextBoundedWide(range) {
+    const MAX_53 = 2 ** 53;
+    if (range > MAX_53) {
+      throw new RangeError(`nextInt range ${range} exceeds 2^53 and cannot be sampled exactly`);
+    }
+    const limit = Math.floor(MAX_53 / range) * range;
+    let value;
+    do {
+      value = this.nextUint32() * 2097152 + (this.nextUint32() >>> 11);
+    } while (value >= limit);
+    return value % range;
+  }
+}
+
+// src/evaluator/modifiers/compare.ts
+function matchesCondition(result, operator, value) {
+  switch (operator) {
+    case ">":
+      return result > value;
+    case ">=":
+      return result >= value;
+    case "<":
+      return result < value;
+    case "<=":
+      return result <= value;
+    case "=":
+      return result === value;
+  }
+}
+
+// src/evaluator/modifiers/crit-threshold.ts
+function applyCritThresholds(dice, successThresholds, failThresholds) {
+  for (const die of dice) {
+    if (die.modifiers.includes("meta"))
+      continue;
+    die.critical = successThresholds.some((t) => matchesCrit(t, die));
+    die.fumble = failThresholds.some((t) => matchesFumble(t, die));
+  }
+}
+function matchesCrit(threshold, die) {
+  if (threshold === "default") {
+    return die.result === die.sides && die.sides > 1;
+  }
+  return matchesCondition(die.result, threshold.operator, threshold.value);
+}
+function matchesFumble(threshold, die) {
+  if (threshold === "default") {
+    return die.result === 1 && die.sides > 1;
+  }
+  return matchesCondition(die.result, threshold.operator, threshold.value);
 }
 
 // src/evaluator/modifiers/explode.ts
@@ -835,7 +1370,7 @@ function applyStandardExplode(pool, shouldExplode, rng, env) {
         result: next,
         modifiers: ["exploded", "kept"],
         critical: next === sides && sides > 1,
-        fumble: next === 1
+        fumble: next === 1 && sides > 1
       });
       last = next;
       iterations += 1;
@@ -844,9 +1379,9 @@ function applyStandardExplode(pool, shouldExplode, rng, env) {
   return result;
 }
 function applyCompoundExplode(pool, shouldExplode, rng, env) {
-  return pool.map((original) => {
+  for (const original of pool) {
     if (!canExplode(original))
-      return original;
+      continue;
     const sides = original.sides;
     let accumulated = original.result;
     let last = original.result;
@@ -863,15 +1398,14 @@ function applyCompoundExplode(pool, shouldExplode, rng, env) {
       iterations += 1;
     }
     if (!exploded)
-      return original;
-    return {
-      sides,
-      result: accumulated,
-      modifiers: original.modifiers.includes("exploded") ? original.modifiers : [...original.modifiers, "exploded"],
-      critical: original.critical,
-      fumble: original.fumble
-    };
-  });
+      continue;
+    original.initialResult = original.result;
+    original.result = accumulated;
+    if (!original.modifiers.includes("exploded")) {
+      original.modifiers = [...original.modifiers, "exploded"];
+    }
+  }
+  return pool;
 }
 function applyPenetratingExplode(pool, shouldExplode, rng, env) {
   const result = [];
@@ -893,7 +1427,7 @@ function applyPenetratingExplode(pool, shouldExplode, rng, env) {
         result: stored,
         modifiers: ["exploded", "kept"],
         critical: raw === sides && sides > 1,
-        fumble: raw === 1
+        fumble: raw === 1 && sides > 1
       });
       lastRaw = raw;
       iterations += 1;
@@ -983,22 +1517,6 @@ function sumKeptDice(dice) {
   return dice.filter((die) => !die.modifiers.includes("dropped")).reduce((sum, die) => sum + die.result, 0);
 }
 
-// src/evaluator/modifiers/compare.ts
-function matchesCondition(result, operator, value) {
-  switch (operator) {
-    case ">":
-      return result > value;
-    case ">=":
-      return result >= value;
-    case "<":
-      return result < value;
-    case "<=":
-      return result <= value;
-    case "=":
-      return result === value;
-  }
-}
-
 // src/evaluator/modifiers/reroll.ts
 var DEFAULT_MAX_REROLL_ITERATIONS = 1000;
 function rollReplacement(sides, rng, env) {
@@ -1022,7 +1540,7 @@ function rollReplacement(sides, rng, env) {
     result,
     modifiers: [],
     critical: result === sides && sides > 1,
-    fumble: result === 1
+    fumble: result === 1 && sides > 1
   };
 }
 function rerollLimitError(maxIterations) {
@@ -1047,17 +1565,13 @@ function applyRecursiveReroll(pool, operator, value, rng, env) {
       if (iterations >= env.maxRerollIterations) {
         throw rerollLimitError(env.maxRerollIterations);
       }
-      result.push({
-        ...current,
-        modifiers: [...stripSlotFlags(current.modifiers), "rerolled", "dropped"]
-      });
+      current.modifiers = [...stripSlotFlags(current.modifiers), "rerolled", "dropped"];
+      result.push(current);
       current = rollReplacement(current.sides, rng, env);
       iterations += 1;
     }
-    result.push({
-      ...current,
-      modifiers: [...stripSlotFlags(current.modifiers), "kept"]
-    });
+    current.modifiers = [...stripSlotFlags(current.modifiers), "kept"];
+    result.push(current);
   }
   return result;
 }
@@ -1069,25 +1583,25 @@ function applyRerollOnce(pool, operator, value, rng, env) {
       continue;
     }
     if (!matchesCondition(original.result, operator, value)) {
-      result.push({
-        ...original,
-        modifiers: [...stripSlotFlags(original.modifiers), "kept"]
-      });
+      original.modifiers = [...stripSlotFlags(original.modifiers), "kept"];
+      result.push(original);
       continue;
     }
-    result.push({
-      ...original,
-      modifiers: [...stripSlotFlags(original.modifiers), "rerolled", "dropped"]
-    });
+    original.modifiers = [...stripSlotFlags(original.modifiers), "rerolled", "dropped"];
+    result.push(original);
     const replacement = rollReplacement(original.sides, rng, env);
-    result.push({
-      ...replacement,
-      modifiers: [...stripSlotFlags(replacement.modifiers), "kept"]
-    });
+    replacement.modifiers = [...stripSlotFlags(replacement.modifiers), "kept"];
+    result.push(replacement);
   }
   return result;
 }
 
+// src/evaluator/modifiers/sort.ts
+function sortDice(dice, order) {
+  const cmp = order === "ascending" ? (a, b) => a.result - b.result : (a, b) => b.result - a.result;
+  return [...dice].sort(cmp);
+}
+
 // src/evaluator/modifiers/success-count.ts
 function countSuccesses(dice, threshold, failThreshold) {
   let successes = 0;
@@ -1111,20 +1625,32 @@ function countSuccesses(dice, threshold, failThreshold) {
 // src/evaluator/evaluator.ts
 class EvaluatorError extends RollParserError {
   nodeType;
+  start;
+  end;
   constructor(message, code, nodeType) {
     super(message, code);
     this.name = "EvaluatorError";
     this.nodeType = nodeType ?? undefined;
+    this.start = undefined;
+    this.end = undefined;
   }
 }
 var DEFAULT_MAX_DICE = 1e4;
+function partSpan(node) {
+  if (node.start === undefined || node.end === undefined)
+    return {};
+  return { start: node.start, end: node.end };
+}
+function toPublicSpecs(specs) {
+  return specs.map((spec) => ({ kind: spec.modifier, selector: spec.selector, count: spec.count }));
+}
 function createDieResult(sides, result) {
   return {
     sides,
     result,
     modifiers: [],
     critical: result === sides && sides > 1,
-    fumble: result === 1
+    fumble: result === 1 && sides > 1
   };
 }
 function createFateDieResult(result) {
@@ -1137,7 +1663,7 @@ function createFateDieResult(result) {
   };
 }
 function renderDice(dice) {
-  const parts = dice.map((die) => {
+  const parts = dice.filter((die) => !die.modifiers.includes("meta")).map((die) => {
     if (die.modifiers.includes("dropped")) {
       return `~~${die.result}~~`;
     }
@@ -1151,10 +1677,33 @@ function renderDice(dice) {
   });
   return `[${parts.join(", ")}]`;
 }
+function mergeMetaRolls(parent, source) {
+  for (const die of source.rolls) {
+    parent.rolls.push({
+      ...die,
+      modifiers: [
+        ...die.modifiers.filter((m) => m !== "kept" && m !== "dropped" && m !== "success" && m !== "failure"),
+        "meta",
+        "dropped"
+      ]
+    });
+  }
+}
 function evalNode(node, rng, ctx, env) {
+  try {
+    return evalNodeInner(node, rng, ctx, env);
+  } catch (error) {
+    if (error instanceof EvaluatorError && error.start === undefined && node.start !== undefined) {
+      error.start = node.start;
+      error.end = node.end;
+    }
+    throw error;
+  }
+}
+function evalNodeInner(node, rng, ctx, env) {
   switch (node.type) {
     case "Literal":
-      return evalLiteral(node.value, ctx);
+      return evalLiteral(node, ctx);
     case "Dice":
       return evalDice(node, rng, ctx, env);
     case "FateDice":
@@ -1175,20 +1724,64 @@ function evalNode(node, rng, ctx, env) {
       return evalVersus(node, rng, ctx, env);
     case "FunctionCall":
       return evalFunctionCall(node, rng, ctx, env);
+    case "Grouped":
+      return evalGrouped(node, rng, ctx, env);
+    case "Group":
+      return evalGroup(node, rng, ctx, env);
+    case "Sort":
+      return evalSort(node, rng, ctx, env);
+    case "CritThreshold":
+      return evalCritThreshold(node, rng, ctx, env);
+    case "Variable":
+      return evalVariable(node, ctx, env);
     default: {
       const exhaustive = node;
       throw new EvaluatorError(`Unknown node type: ${exhaustive.type}`, "UNKNOWN_NODE_TYPE", exhaustive.type);
     }
   }
 }
-function evalLiteral(value, ctx) {
+function evalLiteral(node, ctx) {
+  const { value } = node;
   ctx.expressionParts.push(String(value));
   ctx.renderedParts.push(String(value));
-  return value;
+  return { total: value, part: { type: "literal", value, total: value, ...partSpan(node) } };
+}
+function variableNeedsBraces(name) {
+  return !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
+}
+function evalVariable(node, ctx, env) {
+  const present = Object.hasOwn(env.context, node.name);
+  if (!present) {
+    if (env.onMissingVariable === "throw") {
+      throw new EvaluatorError(`Undefined variable: ${node.name}`, "UNDEFINED_VARIABLE", "Variable");
+    }
+    const display2 = variableNeedsBraces(node.name) ? `@{${node.name}}` : `@${node.name}`;
+    ctx.expressionParts.push("0");
+    ctx.renderedParts.push(`${display2}[0]`);
+    return {
+      total: 0,
+      part: { type: "variable", name: node.name, value: 0, total: 0, ...partSpan(node) }
+    };
+  }
+  const value = env.context[node.name];
+  if (!Number.isFinite(value)) {
+    throw new EvaluatorError(`Invalid variable value: ${node.name} = ${value}`, "INVALID_VARIABLE_VALUE", "Variable");
+  }
+  const display = variableNeedsBraces(node.name) ? `@{${node.name}}` : `@${node.name}`;
+  ctx.expressionParts.push(String(value));
+  ctx.renderedParts.push(`${display}[${value}]`);
+  return {
+    total: value,
+    part: { type: "variable", name: node.name, value, total: value, ...partSpan(node) }
+  };
 }
 function evalDice(node, rng, ctx, env) {
-  const count = evalNode(node.count, rng, { rolls: [], expressionParts: [], renderedParts: [] }, env);
-  const sides = evalNode(node.sides, rng, { rolls: [], expressionParts: [], renderedParts: [] }, env);
+  const countCtx = { rolls: [], expressionParts: [], renderedParts: [] };
+  const count = evalNode(node.count, rng, countCtx, env).total;
+  mergeMetaRolls(ctx, countCtx);
+  const sidesCtx = { rolls: [], expressionParts: [], renderedParts: [] };
+  const sides = evalNode(node.sides, rng, sidesCtx, env).total;
+  mergeMetaRolls(ctx, sidesCtx);
   if (!Number.isInteger(count) || count < 0) {
     throw new EvaluatorError(`Invalid dice count: ${count}`, "INVALID_DICE_COUNT", "Dice");
   }
@@ -1210,10 +1803,15 @@ function evalDice(node, rng, ctx, env) {
   const notation = `${count}d${sides}`;
   ctx.expressionParts.push(notation);
   ctx.renderedParts.push(`${notation}${renderDice(markedDice)}`);
-  return total;
+  return {
+    total,
+    part: { type: "dice", count, sides, rolls: markedDice, total, ...partSpan(node) }
+  };
 }
 function evalFateDice(node, rng, ctx, env) {
-  const count = evalNode(node.count, rng, { rolls: [], expressionParts: [], renderedParts: [] }, env);
+  const countCtx = { rolls: [], expressionParts: [], renderedParts: [] };
+  const count = evalNode(node.count, rng, countCtx, env).total;
+  mergeMetaRolls(ctx, countCtx);
   if (!Number.isInteger(count) || count < 0) {
     throw new EvaluatorError(`Invalid dice count: ${count}`, "INVALID_DICE_COUNT", "FateDice");
   }
@@ -1232,21 +1830,51 @@ function evalFateDice(node, rng, ctx, env) {
   const notation = `${count}dF`;
   ctx.expressionParts.push(notation);
   ctx.renderedParts.push(`${notation}${renderDice(markedDice)}`);
-  return total;
+  return {
+    total,
+    part: { type: "fateDice", count, rolls: markedDice, total, ...partSpan(node) }
+  };
+}
+function propagateMetadata(parent, metadata) {
+  if (!metadata)
+    return;
+  if (parent.versusMetadata) {
+    throw new EvaluatorError("Multiple versus operators in the same expression", "NESTED_VERSUS", "Versus");
+  }
+  parent.versusMetadata = metadata;
+}
+function mergeContext(parent, child) {
+  parent.rolls.push(...child.rolls);
+  propagateMetadata(parent, child.versusMetadata);
 }
 function evalBinaryOp(node, rng, ctx, env) {
   const leftCtx = { rolls: [], expressionParts: [], renderedParts: [] };
   const rightCtx = { rolls: [], expressionParts: [], renderedParts: [] };
   const left = evalNode(node.left, rng, leftCtx, env);
   const right = evalNode(node.right, rng, rightCtx, env);
-  ctx.rolls.push(...leftCtx.rolls, ...rightCtx.rolls);
+  mergeContext(ctx, leftCtx);
+  mergeContext(ctx, rightCtx);
   const leftExpr = leftCtx.expressionParts.join("");
   const rightExpr = rightCtx.expressionParts.join("");
   const leftRendered = leftCtx.renderedParts.join("");
   const rightRendered = rightCtx.renderedParts.join("");
   ctx.expressionParts.push(`${leftExpr} ${node.operator} ${rightExpr}`);
   ctx.renderedParts.push(`${leftRendered} ${node.operator} ${rightRendered}`);
-  switch (node.operator) {
+  const total = applyBinaryOperator(node.operator, left.total, right.total);
+  return {
+    total,
+    part: {
+      type: "binaryOp",
+      operator: node.operator,
+      left: left.part,
+      right: right.part,
+      total,
+      ...partSpan(node)
+    }
+  };
+}
+function applyBinaryOperator(operator, left, right) {
+  switch (operator) {
     case "+":
       return left + right;
     case "-":
@@ -1266,37 +1894,80 @@ function evalBinaryOp(node, rng, ctx, env) {
     case "**":
       return left ** right;
     default: {
-      const exhaustive = node.operator;
+      const exhaustive = operator;
       throw new EvaluatorError(`Unknown operator: ${exhaustive}`, "UNKNOWN_OPERATOR", "BinaryOp");
     }
   }
 }
 function evalUnaryOp(node, rng, ctx, env) {
   const innerCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-  const value = evalNode(node.operand, rng, innerCtx, env);
-  ctx.rolls.push(...innerCtx.rolls);
+  const inner = evalNode(node.operand, rng, innerCtx, env);
+  mergeContext(ctx, innerCtx);
   const innerExpr = innerCtx.expressionParts.join("");
   const innerRendered = innerCtx.renderedParts.join("");
   ctx.expressionParts.push(`-${innerExpr}`);
   ctx.renderedParts.push(`-${innerRendered}`);
-  return -value;
+  const total = -inner.total;
+  return {
+    total,
+    part: { type: "unaryOp", operator: "-", operand: inner.part, total, ...partSpan(node) }
+  };
+}
+function evalGrouped(node, rng, ctx, env) {
+  const innerCtx = { rolls: [], expressionParts: [], renderedParts: [] };
+  const inner = evalNode(node.expression, rng, innerCtx, env);
+  mergeContext(ctx, innerCtx);
+  ctx.expressionParts.push(`(${innerCtx.expressionParts.join("")})`);
+  ctx.renderedParts.push(`(${innerCtx.renderedParts.join("")})`);
+  return {
+    total: inner.total,
+    part: { type: "grouped", inner: inner.part, total: inner.total, ...partSpan(node) }
+  };
+}
+function evalGroup(node, rng, ctx, env) {
+  const subExprs = [];
+  const subRendered = [];
+  const subParts = [];
+  let total = 0;
+  for (const expr of node.expressions) {
+    const subCtx = { rolls: [], expressionParts: [], renderedParts: [] };
+    const sub = evalNode(expr, rng, subCtx, env);
+    mergeContext(ctx, subCtx);
+    subExprs.push(subCtx.expressionParts.join(""));
+    subRendered.push(subCtx.renderedParts.join(""));
+    subParts.push(sub.part);
+    total += sub.total;
+  }
+  ctx.expressionParts.push(`{${subExprs.join(", ")}}`);
+  ctx.renderedParts.push(`{${subRendered.join(", ")}}`);
+  return { total, part: { type: "group", parts: subParts, total, ...partSpan(node) } };
 }
 function evalFunctionCall(node, rng, ctx, env) {
   const argCtxs = [];
-  const values = [];
+  const argResults = [];
   for (const arg of node.args) {
     const argCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-    values.push(evalNode(arg, rng, argCtx, env));
+    argResults.push(evalNode(arg, rng, argCtx, env));
     argCtxs.push(argCtx);
   }
   for (const argCtx of argCtxs) {
-    ctx.rolls.push(...argCtx.rolls);
+    mergeContext(ctx, argCtx);
   }
   const argExprs = argCtxs.map((c) => c.expressionParts.join(""));
   const argRendereds = argCtxs.map((c) => c.renderedParts.join(""));
   ctx.expressionParts.push(`${node.name}(${argExprs.join(", ")})`);
   ctx.renderedParts.push(`${node.name}(${argRendereds.join(", ")})`);
-  return applyFunction(node.name, values);
+  const total = applyFunction(node.name, argResults.map((r) => r.total));
+  return {
+    total,
+    part: {
+      type: "functionCall",
+      name: node.name,
+      args: argResults.map((r) => r.part),
+      total,
+      ...partSpan(node)
+    }
+  };
 }
 function applyFunction(name, values) {
   switch (name) {
@@ -1323,12 +1994,13 @@ function requireUnaryArg(name, values) {
   }
   return x;
 }
-function flattenModifierChain(node, rng, env) {
+function flattenModifierChain(node, rng, ctx, env) {
   const specs = [];
   let current = node;
   while (isModifier(current)) {
     const countCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-    const modCount = evalNode(current.count, rng, countCtx, env);
+    const modCount = evalNode(current.count, rng, countCtx, env).total;
+    mergeMetaRolls(ctx, countCtx);
     if (!Number.isInteger(modCount) || modCount < 0) {
       throw new EvaluatorError(`Invalid modifier count: ${modCount}`, "INVALID_MODIFIER_COUNT", "Modifier");
     }
@@ -1355,10 +2027,10 @@ function mergeDropSets(baseDice, specs) {
       }
     }
   }
-  return baseDice.map((die, index) => ({
-    ...die,
-    modifiers: droppedIndices.has(index) ? [...die.modifiers.filter((m) => m !== "kept" && m !== "dropped"), "dropped"] : [...die.modifiers.filter((m) => m !== "dropped" && m !== "kept"), "kept"]
-  }));
+  baseDice.forEach((die, index) => {
+    die.modifiers = droppedIndices.has(index) ? [...die.modifiers.filter((m) => m !== "kept" && m !== "dropped"), "dropped"] : [...die.modifiers.filter((m) => m !== "dropped" && m !== "kept"), "kept"];
+  });
+  return baseDice;
 }
 function formatExplodeCode(variant, threshold, thresholdValue) {
   const marker = variant === "standard" ? "!" : variant === "compound" ? "!!" : "!p";
@@ -1368,48 +2040,154 @@ function formatExplodeCode(variant, threshold, thresholdValue) {
 }
 function evalExplode(node, rng, ctx, env) {
   const targetCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-  const targetValue = evalNode(node.target, rng, targetCtx, env);
+  const target = evalNode(node.target, rng, targetCtx, env);
   const targetExpr = targetCtx.expressionParts.join("");
   let thresholdValue;
   if (node.threshold != null) {
     const thresholdCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-    thresholdValue = evalNode(node.threshold.value, rng, thresholdCtx, env);
+    thresholdValue = evalNode(node.threshold.value, rng, thresholdCtx, env).total;
+    mergeMetaRolls(ctx, thresholdCtx);
   }
   const code = formatExplodeCode(node.variant, node.threshold, thresholdValue);
+  const buildPart = (total2) => {
+    const part = {
+      type: "explode",
+      variant: node.variant,
+      target: target.part,
+      total: total2,
+      ...partSpan(node)
+    };
+    if (node.threshold != null && thresholdValue !== undefined) {
+      part.threshold = { operator: node.threshold.operator, value: thresholdValue };
+    }
+    return part;
+  };
   if (targetCtx.rolls.length === 0) {
     ctx.expressionParts.push(`${targetExpr}${code}`);
     ctx.renderedParts.push(`${targetExpr}${code}`);
-    return targetValue;
+    return { total: target.total, part: buildPart(target.total) };
   }
   const shouldExplode = buildShouldExplode(node.threshold?.operator, thresholdValue);
   const expanded = node.variant === "standard" ? applyStandardExplode(targetCtx.rolls, shouldExplode, rng, env) : node.variant === "compound" ? applyCompoundExplode(targetCtx.rolls, shouldExplode, rng, env) : applyPenetratingExplode(targetCtx.rolls, shouldExplode, rng, env);
   ctx.rolls.push(...expanded);
   ctx.expressionParts.push(`${targetExpr}${code}`);
   ctx.renderedParts.push(`${targetExpr}${code}${renderDice(expanded)}`);
-  return sumKeptDice(expanded);
+  const total = sumKeptDice(expanded);
+  return { total, part: buildPart(total) };
 }
 function evalReroll(node, rng, ctx, env) {
   const targetCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-  evalNode(node.target, rng, targetCtx, env);
+  const target = evalNode(node.target, rng, targetCtx, env);
   const targetExpr = targetCtx.expressionParts.join("");
   const thresholdCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-  const thresholdValue = evalNode(node.condition.value, rng, thresholdCtx, env);
+  const thresholdValue = evalNode(node.condition.value, rng, thresholdCtx, env).total;
+  mergeMetaRolls(ctx, thresholdCtx);
   const code = `${node.once ? "ro" : "r"}${node.condition.operator}${thresholdValue}`;
+  const condition = {
+    operator: node.condition.operator,
+    value: thresholdValue
+  };
   if (targetCtx.rolls.length === 0) {
     ctx.expressionParts.push(`${targetExpr}${code}`);
     ctx.renderedParts.push(`${targetExpr}${code}`);
-    return sumKeptDice(targetCtx.rolls);
+    const total2 = sumKeptDice(targetCtx.rolls);
+    return {
+      total: total2,
+      part: {
+        type: "reroll",
+        once: node.once,
+        condition,
+        target: target.part,
+        total: total2,
+        ...partSpan(node)
+      }
+    };
   }
   const pool = node.once ? applyRerollOnce(targetCtx.rolls, node.condition.operator, thresholdValue, rng, env) : applyRecursiveReroll(targetCtx.rolls, node.condition.operator, thresholdValue, rng, env);
   ctx.rolls.push(...pool);
   ctx.expressionParts.push(`${targetExpr}${code}`);
   ctx.renderedParts.push(`${targetExpr}${code}${renderDice(pool)}`);
-  return sumKeptDice(pool);
+  const total = sumKeptDice(pool);
+  return {
+    total,
+    part: {
+      type: "reroll",
+      once: node.once,
+      condition,
+      target: target.part,
+      total,
+      ...partSpan(node)
+    }
+  };
+}
+function evalSort(node, rng, ctx, env) {
+  const targetCtx = { rolls: [], expressionParts: [], renderedParts: [] };
+  const target = evalNode(node.target, rng, targetCtx, env);
+  const sortedRolls = sortDice(targetCtx.rolls, node.order);
+  ctx.rolls.push(...sortedRolls);
+  propagateMetadata(ctx, targetCtx.versusMetadata);
+  const code = node.order === "ascending" ? "s" : "sd";
+  const targetExpr = targetCtx.expressionParts.join("");
+  ctx.expressionParts.push(`${targetExpr}${code}`);
+  ctx.renderedParts.push(`${targetExpr}${code}${renderDice(sortedRolls)}`);
+  return {
+    total: target.total,
+    part: {
+      type: "sort",
+      order: node.order,
+      target: target.part,
+      total: target.total,
+      ...partSpan(node)
+    }
+  };
+}
+function evalCritThreshold(node, rng, ctx, env) {
+  const targetCtx = { rolls: [], expressionParts: [], renderedParts: [] };
+  const target = evalNode(node.target, rng, targetCtx, env);
+  const successResolved = node.successThresholds.map((t) => resolveCritThreshold(t, rng, ctx, env));
+  const failResolved = node.failThresholds.map((t) => resolveCritThreshold(t, rng, ctx, env));
+  const successApplied = successResolved.length > 0 ? successResolved : ["default"];
+  const failApplied = failResolved.length > 0 ? failResolved : ["default"];
+  applyCritThresholds(targetCtx.rolls, successApplied, failApplied);
+  ctx.rolls.push(...targetCtx.rolls);
+  propagateMetadata(ctx, targetCtx.versusMetadata);
+  const targetExpr = targetCtx.expressionParts.join("");
+  const codes = [
+    ...successResolved.map((t) => t === "default" ? "cs" : `cs${t.operator}${t.value}`),
+    ...failResolved.map((t) => t === "default" ? "cf" : `cf${t.operator}${t.value}`)
+  ].join("");
+  ctx.expressionParts.push(`${targetExpr}${codes}`);
+  ctx.renderedParts.push(`${targetExpr}${codes}${renderDice(targetCtx.rolls)}`);
+  return {
+    total: target.total,
+    part: {
+      type: "critThreshold",
+      successThresholds: successResolved,
+      failThresholds: failResolved,
+      target: target.part,
+      total: target.total,
+      ...partSpan(node)
+    }
+  };
+}
+function resolveCritThreshold(threshold, rng, ctx, env) {
+  if (threshold === "default")
+    return "default";
+  const thresholdCtx = { rolls: [], expressionParts: [], renderedParts: [] };
+  const resolved = evalNode(threshold.value, rng, thresholdCtx, env).total;
+  mergeMetaRolls(ctx, thresholdCtx);
+  if (!Number.isFinite(resolved)) {
+    throw new EvaluatorError(`Invalid crit threshold: ${resolved}`, "INVALID_THRESHOLD", "CritThreshold");
+  }
+  return { operator: threshold.operator, value: resolved };
 }
 function evalModifier(node, rng, ctx, env) {
-  const { specs, baseTarget } = flattenModifierChain(node, rng, env);
+  const { specs, baseTarget } = flattenModifierChain(node, rng, ctx, env);
+  if (baseTarget.type === "Group" && baseTarget.expressions.length >= 2) {
+    return evalGroupModifier(node, baseTarget, specs, rng, ctx, env);
+  }
   const targetCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-  evalNode(baseTarget, rng, targetCtx, env);
+  const target = evalNode(baseTarget, rng, targetCtx, env);
   const mergedDice = mergeDropSets(targetCtx.rolls, specs);
   ctx.rolls.push(...mergedDice);
   const total = sumKeptDice(mergedDice);
@@ -1417,38 +2195,141 @@ function evalModifier(node, rng, ctx, env) {
   const modifierCodes = specs.map((s) => `${s.code}${s.count}`).join("");
   ctx.expressionParts.push(`${targetExpr}${modifierCodes}`);
   ctx.renderedParts.push(`${targetExpr}${renderDice(mergedDice)}`);
-  return total;
+  return {
+    total,
+    part: {
+      type: "modifier",
+      specs: toPublicSpecs(specs),
+      target: target.part,
+      total,
+      ...partSpan(node)
+    }
+  };
+}
+function stripInnerMarkers(rendered) {
+  return rendered.replace(/\*\*(-?\d+)\*\*/g, "$1").replace(/__(-?\d+)__/g, "$1").replace(/~~(-?\d+)~~/g, "$1");
+}
+function evalGroupModifier(node, group, specs, rng, ctx, env) {
+  const subRolls = group.expressions.map((expr) => {
+    const subCtx = { rolls: [], expressionParts: [], renderedParts: [] };
+    const sub = evalNode(expr, rng, subCtx, env);
+    return {
+      subtotal: sub.total,
+      part: sub.part,
+      rolls: subCtx.rolls,
+      expr: subCtx.expressionParts.join(""),
+      rendered: subCtx.renderedParts.join(""),
+      versusMetadata: subCtx.versusMetadata
+    };
+  });
+  const syntheticDice = subRolls.map((sub) => ({
+    sides: 0,
+    result: sub.subtotal,
+    modifiers: [],
+    critical: false,
+    fumble: false
+  }));
+  const mergedSynthetic = mergeDropSets(syntheticDice, specs);
+  const outerRendered = [];
+  const keptIndices = [];
+  let total = 0;
+  for (let i = 0;i < subRolls.length; i++) {
+    const sub = subRolls[i];
+    const synth = mergedSynthetic[i];
+    const isDropped = synth.modifiers.includes("dropped");
+    if (isDropped) {
+      for (const die of sub.rolls) {
+        die.modifiers = [
+          ...die.modifiers.filter((m) => m !== "kept" && m !== "dropped" && m !== "success" && m !== "failure"),
+          "dropped"
+        ];
+      }
+      ctx.rolls.push(...sub.rolls);
+      outerRendered.push(`~~${stripInnerMarkers(sub.rendered)}~~`);
+    } else {
+      keptIndices.push(i);
+      ctx.rolls.push(...sub.rolls);
+      outerRendered.push(sub.rendered);
+      total += sub.subtotal;
+    }
+    if (!isDropped) {
+      propagateMetadata(ctx, sub.versusMetadata);
+    }
+  }
+  const subExprStrs = subRolls.map((s) => s.expr);
+  const modifierCodes = specs.map((s) => `${s.code}${s.count}`).join("");
+  ctx.expressionParts.push(`{${subExprStrs.join(", ")}}${modifierCodes}`);
+  ctx.renderedParts.push(`{${outerRendered.join(", ")}}`);
+  const groupPart = {
+    type: "group",
+    parts: subRolls.map((s) => s.part),
+    keptIndices,
+    total,
+    ...partSpan(group)
+  };
+  return {
+    total,
+    part: {
+      type: "modifier",
+      specs: toPublicSpecs(specs),
+      target: groupPart,
+      total,
+      ...partSpan(node)
+    }
+  };
 }
-function resolveThreshold(value, rng, env, role) {
+function resolveThreshold(value, rng, ctx, env, role) {
   const thresholdCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-  const resolved = evalNode(value, rng, thresholdCtx, env);
+  const resolved = evalNode(value, rng, thresholdCtx, env).total;
+  mergeMetaRolls(ctx, thresholdCtx);
   if (!Number.isFinite(resolved)) {
     throw new EvaluatorError(`Invalid ${role}: ${resolved}`, "INVALID_THRESHOLD", "SuccessCount");
   }
   return resolved;
 }
 function evalSuccessCount(node, rng, ctx, env) {
+  env.hasSuccessCount = true;
   const targetCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-  const targetValue = evalNode(node.target, rng, targetCtx, env);
+  const target = evalNode(node.target, rng, targetCtx, env);
   const targetExpr = targetCtx.expressionParts.join("");
-  const thresholdValue = resolveThreshold(node.threshold.value, rng, env, "threshold");
-  const failValue = node.failThreshold != null ? resolveThreshold(node.failThreshold.value, rng, env, "fail threshold") : undefined;
+  const thresholdValue = resolveThreshold(node.threshold.value, rng, ctx, env, "threshold");
+  const failValue = node.failThreshold != null ? resolveThreshold(node.failThreshold.value, rng, ctx, env, "fail threshold") : undefined;
   const code = `${node.threshold.operator}${thresholdValue}${failValue != null ? `f${failValue}` : ""}`;
+  const buildPart = (total, successes, failures) => {
+    const part = {
+      type: "successCount",
+      threshold: { operator: node.threshold.operator, value: thresholdValue },
+      target: target.part,
+      successes,
+      failures,
+      total,
+      ...partSpan(node)
+    };
+    if (failValue != null && node.failThreshold != null) {
+      part.failThreshold = { operator: node.failThreshold.operator, value: failValue };
+    }
+    return part;
+  };
   if (targetCtx.rolls.length === 0) {
     ctx.expressionParts.push(`${targetExpr}${code}`);
     ctx.renderedParts.push(`${targetExpr}${code}`);
-    return targetValue;
+    return { total: target.total, part: buildPart(target.total, 0, 0) };
   }
   const result = countSuccesses(targetCtx.rolls, { operator: node.threshold.operator, value: thresholdValue }, failValue != null && node.failThreshold != null ? { operator: node.failThreshold.operator, value: failValue } : undefined);
-  env.hasSuccessCount = true;
   ctx.rolls.push(...targetCtx.rolls);
   ctx.expressionParts.push(`${targetExpr}${code}`);
   ctx.renderedParts.push(`${targetExpr}${code}${renderDice(targetCtx.rolls)}`);
-  return result.total;
+  return {
+    total: result.total,
+    part: buildPart(result.total, result.successes, result.failures)
+  };
 }
 function extractNatural(rolls) {
-  const keptD20s = rolls.filter((d) => d.sides === 20 && !d.modifiers.includes("dropped") && !d.modifiers.includes("rerolled"));
-  return keptD20s.length === 1 ? keptD20s[0]?.result : undefined;
+  const primaries = rolls.filter((d) => d.sides === 20 && !d.modifiers.includes("dropped") && !(d.modifiers.includes("exploded") && d.initialResult === undefined));
+  if (primaries.length !== 1)
+    return;
+  const die = primaries[0];
+  return die?.initialResult ?? die?.result;
 }
 function calculateDegree(total, dc, natural) {
   let degree;
@@ -1485,11 +2366,11 @@ function evalVersus(node, rng, ctx, env) {
   env.insideVersus = true;
   try {
     const rollCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-    const rollTotal = evalNode(node.roll, rng, rollCtx, env);
+    const rollResult = evalNode(node.roll, rng, rollCtx, env);
     const natural = extractNatural(rollCtx.rolls);
     const dcCtx = { rolls: [], expressionParts: [], renderedParts: [] };
-    const dcTotal = evalNode(node.dc, rng, dcCtx, env);
-    const degree = calculateDegree(rollTotal, dcTotal, natural);
+    const dcResult = evalNode(node.dc, rng, dcCtx, env);
+    const degree = calculateDegree(rollResult.total, dcResult.total, natural);
     ctx.rolls.push(...rollCtx.rolls, ...dcCtx.rolls);
     const rollExpr = rollCtx.expressionParts.join("");
     const dcExpr = dcCtx.expressionParts.join("");
@@ -1497,8 +2378,18 @@ function evalVersus(node, rng, ctx, env) {
     const dcRendered = dcCtx.renderedParts.join("");
     ctx.expressionParts.push(`${rollExpr} vs ${dcExpr}`);
     ctx.renderedParts.push(`${rollRendered} vs ${dcRendered}`);
-    ctx.versusMetadata = { degree, natural, dcTotal };
-    return rollTotal;
+    ctx.versusMetadata = { degree, natural, dcTotal: dcResult.total };
+    return {
+      total: rollResult.total,
+      part: {
+        type: "versus",
+        roll: rollResult.part,
+        dc: dcResult.part,
+        degree,
+        total: rollResult.total,
+        ...partSpan(node)
+      }
+    };
   } finally {
     env.insideVersus = false;
   }
@@ -1507,20 +2398,27 @@ function evaluate(ast, rng, options = {}) {
   const maxDice = options.maxDice != null && Number.isFinite(options.maxDice) && options.maxDice > 0 ? Math.floor(options.maxDice) : DEFAULT_MAX_DICE;
   const maxExplodeIterations = options.maxExplodeIterations != null && Number.isFinite(options.maxExplodeIterations) && options.maxExplodeIterations >= 0 ? Math.floor(options.maxExplodeIterations) : DEFAULT_MAX_EXPLODE_ITERATIONS;
   const maxRerollIterations = options.maxRerollIterations != null && Number.isFinite(options.maxRerollIterations) && options.maxRerollIterations >= 0 ? Math.floor(options.maxRerollIterations) : DEFAULT_MAX_REROLL_ITERATIONS;
+  const context = options.context ?? {};
+  const onMissingVariable = options.onMissingVariable ?? "throw";
   const env = {
     maxDice,
     maxExplodeIterations,
     maxRerollIterations,
     totalDiceRolled: 0,
     hasSuccessCount: false,
-    insideVersus: false
+    insideVersus: false,
+    context,
+    onMissingVariable
   };
   const ctx = {
     rolls: [],
     expressionParts: [],
     renderedParts: []
   };
-  const total = evalNode(ast, rng, ctx, env);
+  const { total, part } = evalNode(ast, rng, ctx, env);
+  if (!Number.isFinite(total)) {
+    throw new EvaluatorError(`Result is not a finite number: ${total}`, "NON_FINITE_RESULT", ast.type);
+  }
   const expression = ctx.expressionParts.join("");
   const trailing = ctx.versusMetadata ? degreeLabel(ctx.versusMetadata.degree) : String(total);
   const rendered = `${ctx.renderedParts.join("")} = ${trailing}`;
@@ -1529,7 +2427,8 @@ function evaluate(ast, rng, options = {}) {
     notation: options.notation ?? expression,
     expression,
     rendered,
-    rolls: ctx.rolls
+    rolls: ctx.rolls,
+    parts: part
   };
   if (env.hasSuccessCount) {
     let successes = 0;
@@ -1566,100 +2465,18 @@ function roll(notation, options = {}) {
   if (options.maxRerollIterations != null) {
     evalOptions.maxRerollIterations = options.maxRerollIterations;
   }
+  if (options.context != null)
+    evalOptions.context = options.context;
+  if (options.onMissingVariable != null) {
+    evalOptions.onMissingVariable = options.onMissingVariable;
+  }
   return evaluate(ast, rng, evalOptions);
 }
 // package.json
-var package_default = {
-  name: "roll-parser",
-  version: "3.0.0-alpha.0",
-  description: "High-performance dice notation parser for tabletop RPGs. TypeScript-first, Bun-optimized.",
-  type: "module",
-  main: "./dist/index.js",
-  module: "./dist/index.mjs",
-  types: "./dist/index.d.ts",
-  bin: { "roll-parser": "./dist/cli.js" },
-  sideEffects: false,
-  exports: {
-    ".": {
-      types: "./dist/index.d.ts",
-      import: "./dist/index.mjs",
-      require: "./dist/index.js"
-    },
-    "./testing": {
-      types: "./dist/testing.d.ts",
-      import: "./dist/testing.mjs",
-      require: "./dist/testing.js"
-    }
-  },
-  files: [
-    "dist",
-    "src",
-    "!src/**/*.test.ts"
-  ],
-  keywords: [
-    "parser",
-    "dice",
-    "roll",
-    "rpg",
-    "dnd",
-    "d20",
-    "pratt-parser",
-    "typescript",
-    "bun"
-  ],
-  homepage: "https://github.com/edloidas/roll-parser#readme",
-  bugs: {
-    url: "https://github.com/edloidas/roll-parser/issues"
-  },
-  license: "MIT",
-  author: "Mikita Taukachou <edloidas@gmail.com> (https://edloidas.com)",
-  repository: {
-    type: "git",
-    url: "git+https://github.com/edloidas/roll-parser.git"
-  },
-  publishConfig: {
-    access: "public"
-  },
-  scripts: {
-    typecheck: "tsc --noEmit",
-    lint: "biome lint .",
-    "lint:fix": "biome lint --write .",
-    format: "biome format --write .",
-    "format:check": "biome format .",
-    check: "bun typecheck && bun lint && bun format:check",
-    "check:fix": "bun typecheck && bun lint:fix && bun format",
-    "check:version": "bun scripts/check-version.ts",
-    "check:changelog": "bun scripts/check-changelog.ts",
-    clean: "rm -rf dist coverage",
-    build: "bun run clean && bun run build:esm && bun run build:cjs && bun run build:esm:testing && bun run build:cjs:testing && bun run build:cli && bun run build:types",
-    "build:esm": "bun build src/index.ts --outfile dist/index.mjs --target bun",
-    "build:cjs": "bun build src/index.ts --outfile dist/index.js --target node",
-    "build:esm:testing": "bun build src/testing.ts --outfile dist/testing.mjs --target bun",
-    "build:cjs:testing": "bun build src/testing.ts --outfile dist/testing.js --target node",
-    "build:cli": "bun build src/cli/index.ts --outfile dist/cli.js --target node",
-    "build:types": "tsc --emitDeclarationOnly -p tsconfig.build.json",
-    test: "bun test",
-    "test:node": `node -e "import('./dist/index.mjs').then(m => { const r = m.roll('1d6'); if (!(r.total >= 1 && r.total <= 6)) throw new Error('ESM smoke failed: total=' + r.total); console.log('Node.js ESM smoke: ok'); })" && node -e "const m = require('./dist/index.js'); const r = m.roll('1d6'); if (!(r.total >= 1 && r.total <= 6)) throw new Error('CJS smoke failed: total=' + r.total); console.log('Node.js CJS smoke: ok');"`,
-    "test:watch": "bun test --watch",
-    "test:ci": "bun test --bail",
-    validate: "bun run check && bun run build && bun test:ci",
-    coverage: "bun test --coverage",
-    "release:dry": "bun run check:version && bun run check:changelog && bun run check && bun run build && bun test",
-    prepublishOnly: "bun run release:dry"
-  },
-  devDependencies: {
-    "@biomejs/biome": "^2.4.9",
-    "@types/bun": "^1.3.0",
-    "fast-check": "^4.6.0",
-    typescript: "^6.0.2"
-  },
-  engines: {
-    node: ">= 22.0.0"
-  }
-};
+var version = "3.0.0-beta.0";
 
 // src/index.ts
-var VERSION = package_default.version;
+var VERSION = version;
 
 // src/cli/args.ts
 function parseArgs(argv) {
@@ -1691,7 +2508,7 @@ function parseArgs(argv) {
       seed = value;
     } else if (arg.startsWith("--")) {
       return { ok: false, error: `Unknown option: ${arg}` };
-    } else if (arg.startsWith("-") && arg.length > 1 && !/^\d/.test(arg.slice(1))) {
+    } else if (arg.startsWith("-") && arg.length > 1 && !/^[\ddD(]/.test(arg.slice(1))) {
       return { ok: false, error: `Unknown option: ${arg}` };
     } else {
       positional.push(arg);
@@ -1709,7 +2526,7 @@ function formatResult(result, verbose) {
   return formatRendered(result.rendered);
 }
 function formatRendered(rendered) {
-  return rendered.replace(/~~(-?\d+)~~/g, "($1)").replace(/\*\*(-?\d+)\*\*/g, "[$1]").replace(/__(-?\d+)__/g, "{$1}");
+  return rendered.replace(/\*\*(-?\d+)\*\*/g, "[$1]").replace(/__(-?\d+)__/g, "{$1}").replace(/~~([^~]+)~~/g, "($1)");
 }
 
 // src/cli/index.ts
@@ -1728,6 +2545,18 @@ Examples:
   roll-parser 4d6kh3 --verbose
   roll-parser 4d6dl1 --seed "character-str"
 `;
+function writeErrorContext(notation, error) {
+  const position = "position" in error ? error.position : ("start" in error) ? error.start : undefined;
+  if (typeof position !== "number" || !Number.isInteger(position))
+    return;
+  if (notation.includes(`
+`) || position < 0 || position > notation.length)
+    return;
+  process.stderr.write(`  ${notation}
+`);
+  process.stderr.write(`  ${" ".repeat(position)}^
+`);
+}
 function main() {
   const parsed = parseArgs(process.argv.slice(2));
   if (!parsed.ok) {
@@ -1766,6 +2595,7 @@ function main() {
     if (isRollParserError(error)) {
       process.stderr.write(`Error: ${error.message}
 `);
+      writeErrorContext(args.notation, error);
       process.exitCode = 1;
       return;
     }
@@ -1773,3 +2603,6 @@ function main() {
   }
 }
 main();
+
+//# debugId=E5D058E5C568B60B64756E2164756E21
+//# sourceMappingURL=cli.js.map