roll-parser 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.4.0] - 2026-09-11
+
+CLI release: `--json` becomes a complete record. A payload now names the seed
+and version that produced it, so any roll — seeded or not — can be replayed from
+its own output, and every diagnostic the CLI raises now arrives as one JSON line
+instead of an `Error:` prefix and a caret diagram. The library, its public types
+and its serialized shape are untouched; the `--json` success payload only gains
+keys at the end, so existing field access is unaffected.
+
+### Added
+
+- `--json` output ends in `seed` and `version`, making a payload re-derivable from itself. The CLI mints its own seed with `crypto.randomUUID()` rather than letting `SeededRNG` auto-seed and discard the value, so the emitted seed is one that can be handed straight back to `--seed`; `version` rides along because the seed-to-dice mapping is only fixed within a major. Minting is unconditional, so the plain and verbose paths draw from the same source. Both keys are appended, so every existing key keeps its position ([#342](https://github.com/edloidas/roll-parser/issues/342))
+- Every diagnostic raised after `--json` is parsed is now one JSON line on stderr, carrying the error's stable `code` and the `span` that `getErrorSpan` normalizes, plus the `notation` and `seed` that produced the failure. Machine consumers no longer have to regex the message and count caret spaces for a position the process already held. The record reports `span` rather than a flat position because the evaluator carries a start and an end. A failing unseeded roll is now reproducible too — the minted seed was declared inside the `try` and the `catch` never echoed it. Exit codes and empty-stdout-on-failure are unchanged ([#343](https://github.com/edloidas/roll-parser/issues/343))
+
+### Changed
+
+- `--json` now covers the two usage errors that escaped it. `Unknown option: <x>` and `Missing value for --seed` were raised at the offending token, before the flag was known, so they printed as plain text; `parseArgs` now records the first usage error and runs the loop to the end, so the flag survives alongside it. Detection stays positional: `--seed --json` binds `--json` as the seed value and `roll-parser -- --json` makes it notation, and neither emits JSON. The record is `{"error":{"message":...},"version":...}` — a usage error never reached the dice, so it carries no `code`, `span`, `notation` or `seed`. Exit code 2 is unchanged ([#351](https://github.com/edloidas/roll-parser/issues/351))
+- A failed run whose notation was passed after `--` now ends with a hint saying the terminator makes everything after it part of the notation. It is gated on what the parser did rather than on `argv` containing a `--`: `--seed` takes any non-empty next argument, so `--seed --` binds that `--` as a seed value and no terminator ever runs. `parseArgs` carries `terminated` on its success arm to express that. The `--json` path is untouched — every diagnostic there stays one JSON line ([#344](https://github.com/edloidas/roll-parser/issues/344))
+
+### Fixed
+
+- `roll-parser --seed -- --help` prints the manual instead of exiting 2 with `Unknown option`. The scan that finds `--help`, `-h` and `--version` broke at the first literal `--`, but `readSeedValue` takes any non-empty next argument, so in `--seed --` that `--` is the seed value and never reaches the terminator branch of the main loop. The scan now consumes a `--seed` value the way the loop does, exempting an informational flag from the skip so `--seed --help` still resolves to help ([#364](https://github.com/edloidas/roll-parser/issues/364))
+
+### Documentation
+
+- `HELP_TEXT` and the README CLI section no longer teach `--` as the way to write negative notation. `roll-parser -1d6+3` works on its own — `-1d6`, `-d6`, `-dF`, `-(2d6)`, `-{2d6}` and `-@str` are all accepted as positionals — and teaching the terminator there walked users into its real semantics, where a trailing `--verbose` becomes part of the notation and the lexer rejects it as an identifier. The `--` option line now names what the terminator is actually for ([#344](https://github.com/edloidas/roll-parser/issues/344))
+- The README `--json` sample no longer pins a `"version":"3.3.1"` literal that nothing checks, and the prose states that `version` is a bare semver with no `v` prefix ([#348](https://github.com/edloidas/roll-parser/issues/348))
+- The README performance table is re-measured under Bun 1.4 as the per-record median of eight `bench:json` passes: `roll` runs 8-18% faster on the light expressions and flat on the heavy pools, while `lex` and `parse` land within 10% of the old figures in both directions. The measurement protocol records the non-idle session and its wider pass-to-pass spread ([#340](https://github.com/edloidas/roll-parser/issues/340))
+
+## [3.3.1] - 2026-08-20
+
+### Changed
+
+- performance: the evaluator does less work per node and per die. `EvalContext`'s `expression` and `rendered` fragment arrays are single strings carried on `EvalResult`, so no branch can omit one; `rewriteFlags` is one loop instead of a closure, a filter array and a spread; a modifier's target context no longer renders the pool it discards, with every pool render routed through `renderedPool`; and `renderGroup` looks kept indices up in a `Set` rather than an array. No notation evaluates differently and no public type changed ([#336](https://github.com/edloidas/roll-parser/issues/336))
+
+### Documentation
+
+- `package.json` metadata is tuned for npm search: the `description` leads with queryable nouns and names the systems, `roller`, `die`, `notation`, `pathfinder` and the space-separated `dice notation` join the keywords, and seven keywords that ranked outside the top 100 for their own chip are gone. `README.md` gains a `min+brotli ≤13.5 kB` badge linking to the size breakdown ([#333](https://github.com/edloidas/roll-parser/issues/333))
+
 ## [3.3.0] - 2026-08-17
 
 Error-message work throughout: nine parse and lex errors now name the rule they
@@ -295,7 +334,9 @@ Dice mechanics (Stage 2):
 - Dice count safety limit via `maxDice` option (default 10,000), enforced across the whole expression to prevent DoS via additive groups like `5000d6+5000d6` ([#19](https://github.com/edloidas/roll-parser/issues/19))
 - Parser and evaluator correctness: duplicate `kept` modifier entries, implicit modifier count defaulting to 1 (`4d6kh` → `4d6kh1`), `critical` flag suppression when `sides === 1`, negative `--seed` CLI values ([#21](https://github.com/edloidas/roll-parser/issues/21))
 
-[Unreleased]: https://github.com/edloidas/roll-parser/compare/v3.3.0...HEAD
+[Unreleased]: https://github.com/edloidas/roll-parser/compare/v3.4.0...HEAD
+[3.4.0]: https://github.com/edloidas/roll-parser/releases/tag/v3.4.0
+[3.3.1]: https://github.com/edloidas/roll-parser/releases/tag/v3.3.1
 [3.3.0]: https://github.com/edloidas/roll-parser/releases/tag/v3.3.0
 [3.2.2]: https://github.com/edloidas/roll-parser/releases/tag/v3.2.2
 [3.2.1]: https://github.com/edloidas/roll-parser/releases/tag/v3.2.1

package/README.md

@@ -13,6 +13,7 @@ Dice notation for tabletop RPGs, rolled into structured results.
   <a href="https://github.com/edloidas/roll-parser/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/edloidas/roll-parser/ci.yml?branch=master&label=CI" alt="CI status"></a>
   <a href="https://github.com/edloidas/roll-parser/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/roll-parser?color=blue" alt="MIT license"></a>
   <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/roll-parser?color=5fa04e" alt="Node.js >= 22.12"></a>
+  <a href="https://github.com/edloidas/roll-parser#why-roll-parser"><img src="https://img.shields.io/badge/min%2Bbrotli-%E2%89%A413.5%20kB-8b5cf6" alt="min+brotli ≤13.5 kB"></a>
 </p>
 
 <p align="center">
@@ -51,11 +52,11 @@ roll('4d6kh3', { rng: createMockRng([3, 6, 2, 5]) }).total; // 14, every run
 
 ## Why roll-parser
 
-- **Complete notation.** Keep/drop, three flavours of exploding dice, rerolls,
-  min/max clamps, success pools, crit thresholds, sorting, grouped rolls, PF2e
-  degrees of success, math functions, variables, computed dice — enough for D&D 5e,
-  Pathfinder, World of Darkness, Shadowrun, Fate, Savage Worlds, and Call of
-  Cthulhu without escape hatches. Spelled the way
+- **Complete notation.** A dice roller that takes keep/drop, three flavours of
+  exploding dice, rerolls, min/max clamps, success pools, crit thresholds,
+  sorting, grouped rolls, PF2e degrees of success, math functions, variables,
+  computed dice — enough for D&D 5e, Pathfinder, World of Darkness, Shadowrun,
+  Fate, Savage Worlds, and Call of Cthulhu without escape hatches. Spelled the way
   [Roll20](https://help.roll20.net/hc/en-us/articles/360037773133-Dice-Reference)
   spells it wherever the two overlap, so the notation your table already uses
   keeps working.
@@ -314,8 +315,9 @@ pool.total; // 5 — successes minus failures
 | `successes` / `failures` | `number?` | Present only when success counting was used |
 | `degree` / `natural` | `DegreeOfSuccess?` / `number?` | Present only for a top-level `vs` |
 
-`Readonly` at the top level and fully JSON-serializable — this is exactly what
-the CLI's `--json` flag prints.
+`Readonly` at the top level and fully JSON-serializable. The CLI's `--json`
+flag prints these fields and appends two of its own, `seed` and `version` —
+see [CLI](#cli).
 
 ```typescript
 JSON.stringify(roll('3d6', { rng: createMockRng([4, 2, 6]) }));
@@ -1002,7 +1004,7 @@ Options:
   -v, --verbose    Show detailed roll breakdown
   --json           Print the whole result as compact JSON (wins over --verbose)
   --seed <value>   Use seed for reproducible rolls
-  --               Treat every following argument as notation
+  --               Notation that looks like an option — put options before it
 ```
 
 ```bash
@@ -1020,15 +1022,48 @@ Error: Invalid dice sides: 0
   2d6+1d0+3
       ^
 
-$ roll-parser --seed demo -- -1d6+3
+$ roll-parser "2d6+1d0+3" --json --seed demo
+{"error":{"message":"Invalid dice sides: 0","code":"INVALID_DICE_SIDES","span":{"start":4,"end":7}},"notation":"2d6+1d0+3","seed":"demo",...}
+
+$ roll-parser -1d6+3 --seed demo
 2
 ```
 
+That payload is cut short; in full it ends:
+
+```json
+{"total":8,"notation":"1d20+7 vs 15", …, "seed":"demo","version":"…"}
+```
+
 Verbose mode rewrites the markdown markers for plain terminals: `~~n~~` becomes
 `(n)`, `**n**` becomes `[n]`, `__n__` becomes `{n}`. `--seed` takes both
 `--seed value` and `--seed=value`, and accepts any non-empty value including a
-dash-prefixed one. `--help` and `--version` win over any usage error that
-precedes them. Errors go to stderr; only the result goes to stdout.
+dash-prefixed one. The `--json` payload ends with two fields the library
+result does not carry: the `seed` that produced the roll and the `version` (a
+bare semver, no `v` prefix) that fixes the seed-to-dice mapping — feed that
+seed back through `--seed` on the same major and the dice repeat. Omitting
+`--seed` mints one, so an unplanned roll stays reproducible too. `--help` and
+`--version` win over any usage error that precedes them. Errors go to stderr;
+only the result goes to stdout.
+
+Leading-minus notation needs no `--`: `-1d6+3`, `-d6`, `-dF`, `-(2d6)`,
+`-{2d6}` and `-@str` are all read as notation. `--` is the escape hatch for
+notation that would otherwise parse as an option, and everything after it is
+notation — flags included — so options go before it, never after. A failed roll
+whose notation swallowed one prints `Hint: options must come before "--"` after
+the caret diagram.
+
+Once `--json` is parsed, every diagnostic is one JSON line on stderr instead
+of the caret diagram. `code` is the same stable `RollParserErrorCode` the
+library throws, and `span` is what `getErrorSpan` returns — `{ start }` for a
+lexer or parser error, `{ start, end }` for an evaluator one, absent when the
+failure carries no position. A roll error also repeats the `notation` and
+`seed` that produced it, so a failure replays through `--seed` exactly as a
+result does. Branch on `code`, not on `message`, which is free to change
+between releases. Usage errors are covered too — an unknown option and a
+missing `--seed` value carry a `message` and nothing else. Detection honours
+what `--json` actually binds to, so `--seed --json` reads the flag as the seed
+value and `roll-parser -- --json` reads it as notation; neither emits JSON.
 
 | Exit code | Meaning |
 |----------:|---------|
@@ -1040,36 +1075,29 @@ precedes them. Errors go to stderr; only the result goes to stdout.
 
 | Notation | `lex` | `parse` | `roll` (end to end) |
 |----------|------:|--------:|--------------------:|
-| `1d20` | 85 ns | 164 ns | **0.49 µs** (~2.0M rolls/s) |
-| `2d6+3` | 98 ns | 215 ns | **0.77 µs** |
-| `4d6kh3` | 122 ns | 245 ns | **1.2 µs** |
-| `4d6sd` | 101 ns | 211 ns | **0.84 µs** |
-| `10d10>=6f1` | 161 ns | 336 ns | **1.6 µs** |
-| `100d6` | 82 ns | 168 ns | **2.6 µs** |
+| `1d20` | 86 ns | 166 ns | **0.43 µs** (~2.3M rolls/s) |
+| `2d6+3` | 104 ns | 230 ns | **0.64 µs** |
+| `4d6kh3` | 127 ns | 262 ns | **0.98 µs** |
+| `4d6sd` | 112 ns | 232 ns | **0.77 µs** |
+| `10d10>=6f1` | 165 ns | 361 ns | **1.6 µs** |
+| `100d6` | 81 ns | 162 ns | **2.6 µs** |
 
 The `roll` column pays for a fresh `SeededRNG` per call, which an injected RNG
 avoids. Every roll also builds the `parts` tree; there is no opt-out and these
-numbers include it. A 1000-die pool costs roughly 47x a `1d20` (~23 µs here),
-while lexing and parsing stay flat at ~84 / ~168 ns.
+numbers include it. A 1000-die pool costs roughly 56x a `1d20` (~24 µs here),
+while lexing and parsing stay flat at ~83 / ~164 ns.
 
 <details>
 <summary>Measurement protocol</summary>
 
 Values are **p50**, from
 [mitata](https://github.com/evanwashere/mitata) with forced per-iteration GC
-(`.gc('inner')`), taken as the per-record median of four full
-`bun run bench:json` passes, every row agreeing within 5% except
-`lex / 4d6kh3` at 7%. Measured 2026-08-05 on Bun
-1.3.14, Apple M2 Pro, macOS, idle and on AC power. Read them as
-two significant digits: another machine shifts every row, and a busy one
-inflates the heavy cases most.
-
-The `4d6sd` row and the `10d10>=6f1` `roll` figure come from a later five-pass
-measurement on the same machine, after the per-die `'dc'` tag checks were
-hoisted out of the keep/drop, success-count, and sort loops. That session was
-not idle and those two read bimodally with roughly 10% between the modes, so
-take them as a recovered range rather than point values. Every other row is as
-first measured.
+(`.gc('inner')`), taken as the per-record median of eight full
+`bun run bench:json` passes. Measured 2026-09-03 on Bun 1.4.0, Apple M2 Pro,
+macOS, on AC power but not on an idle machine — pass-to-pass spread runs 7-11%
+on the `lex` and `parse` rows and up to 10% on `roll`, against 5% for the idle
+session these numbers replace. Read them as two significant digits: another
+machine shifts every row, and a busy one inflates the heavy cases most.
 
 p50 rather than mean, because the mean here is effectively a GC-pause
 histogram and swings ±40% between processes. Every bench body is JIT-primed

package/dist/cli/args.d.ts

@@ -17,15 +17,25 @@ export type CliArgs = {
     showVersion: boolean;
 };
 /**
- * Result of parsing CLI arguments — either success or a usage error.
+ * Result of parsing CLI arguments — either success or a usage error. The
+ * failure arm carries `json` so a usage error renders in the format the
+ * caller asked for; the success arm carries `terminated`, true only when a
+ * `--` was consumed as the terminator rather than as a `--seed` value.
  */
 export type ParseArgsResult = {
     ok: true;
     args: CliArgs;
+    terminated: boolean;
 } | {
     ok: false;
     error: string;
+    json: boolean;
 };
+/**
+ * True for an argument this parser accepts as a *valid* option outside a `--`
+ * terminator — `--typo` is read as an option and rejected, and is not one here.
+ */
+export declare function isKnownOption(arg: string): boolean;
 /**
  * Parses a raw argument array into typed CLI options.
  *

package/dist/cli/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA0CzF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CAyDzD"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,GAChD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AA6DhD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAElD;AAyDD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CA0CzD"}

package/dist/cli/args.js

@@ -7,26 +7,77 @@ const BASE_ARGS = {
     showHelp: false,
     showVersion: false,
 };
+function informationalKind(arg) {
+    if (arg === '--help' || arg === '-h')
+        return 'help';
+    if (arg === '--version')
+        return 'version';
+    return undefined;
+}
 function findInformationalFlag(argv) {
     let flag;
-    for (const arg of argv) {
-        if (arg === TERMINATOR)
-            break;
-        if (arg === '--help' || arg === '-h')
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const kind = informationalKind(arg);
+        if (kind === 'help')
             return 'help';
-        if (arg === '--version')
+        if (kind === 'version')
             flag = 'version';
+        else if (arg === TERMINATOR)
+            break;
+        else if (arg === '--seed' && informationalKind(argv[i + 1]) == null)
+            i += 1;
     }
     return flag;
 }
 function isNegativeNotation(arg) {
-    return arg.length > 1 && /^[\ddD({@]/.test(arg.slice(1));
+    return /^[\ddD({@]/.test(arg.slice(1));
+}
+const KNOWN_OPTIONS = new Set(['--verbose', '-v', '--json', '--help', '-h', '--version', '--seed']);
+export function isKnownOption(arg) {
+    return KNOWN_OPTIONS.has(arg) || arg.startsWith('--seed=');
+}
+function readSeedValue(arg, next) {
+    if (arg === '--seed') {
+        return next == null || next === '' ? null : { seed: next, consumed: 1 };
+    }
+    const value = arg.slice('--seed='.length);
+    return value === '' ? null : { seed: value, consumed: 0 };
+}
+function failWith(acc, message) {
+    acc.error ??= message;
+}
+function applyArg(arg, next, acc) {
+    if (arg === '--verbose' || arg === '-v') {
+        acc.verbose = true;
+    }
+    else if (arg === '--json') {
+        acc.json = true;
+    }
+    else if (arg === '--seed' || arg.startsWith('--seed=')) {
+        const read = readSeedValue(arg, next);
+        if (read == null) {
+            failWith(acc, 'Missing value for --seed');
+        }
+        else {
+            acc.seed = read.seed;
+            return read.consumed;
+        }
+    }
+    else if (arg.startsWith('--') || (arg.startsWith('-') && !isNegativeNotation(arg))) {
+        failWith(acc, `Unknown option: ${arg}`);
+    }
+    else {
+        acc.positional.push(arg);
+    }
+    return 0;
 }
 export function parseArgs(argv) {
     const informational = findInformationalFlag(argv);
     if (informational != null) {
         return {
             ok: true,
+            terminated: false,
             args: {
                 ...BASE_ARGS,
                 showHelp: informational === 'help',
@@ -34,48 +85,22 @@ export function parseArgs(argv) {
             },
         };
     }
-    let verbose = false;
-    let json = false;
-    let seed;
-    const positional = [];
+    const acc = { verbose: false, json: false, positional: [] };
+    let terminated = false;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === TERMINATOR) {
-            positional.push(...argv.slice(i + 1));
+            acc.positional.push(...argv.slice(i + 1));
+            terminated = true;
             break;
         }
-        else if (arg === '--verbose' || arg === '-v') {
-            verbose = true;
-        }
-        else if (arg === '--json') {
-            json = true;
-        }
-        else if (arg === '--seed') {
-            const next = argv[i + 1];
-            if (next == null || next === '') {
-                return { ok: false, error: 'Missing value for --seed' };
-            }
-            seed = next;
-            i++;
-        }
-        else if (arg.startsWith('--seed=')) {
-            const value = arg.slice('--seed='.length);
-            if (value === '') {
-                return { ok: false, error: 'Missing value for --seed' };
-            }
-            seed = value;
-        }
-        else if (arg.startsWith('--')) {
-            return { ok: false, error: `Unknown option: ${arg}` };
-        }
-        else if (arg.startsWith('-') && !isNegativeNotation(arg)) {
-            return { ok: false, error: `Unknown option: ${arg}` };
-        }
-        else {
-            positional.push(arg);
-        }
+        i += applyArg(arg, argv[i + 1], acc);
+    }
+    const { verbose, json, seed, error, positional } = acc;
+    if (error != null) {
+        return { ok: false, error, json };
     }
     const notation = positional.length > 0 ? positional.join(' ') : undefined;
-    return { ok: true, args: { ...BASE_ARGS, notation, verbose, json, seed } };
+    return { ok: true, terminated, args: { ...BASE_ARGS, notation, verbose, json, seed } };
 }
 //# sourceMappingURL=args.js.map

package/dist/cli/args.js.map

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

package/dist/cli/format.d.ts

@@ -14,6 +14,8 @@ export type FormatOptions = {
     json?: boolean;
     /** Show the detailed roll breakdown instead of the bare total. */
     verbose?: boolean;
+    /** Seed that produced the result. Emitted in JSON mode only. */
+    seed: string;
 };
 /**
  * Formats a roll result for terminal display.
@@ -24,9 +26,14 @@ export type FormatOptions = {
  * tree — as a single-line `JSON.stringify` payload, where `degree` appears as
  * its numeric `DegreeOfSuccess` value.
  *
+ * The JSON payload appends two fields the library result does not carry: the
+ * `seed` that produced the result and the `version` that fixes the
+ * seed-to-dice mapping. Together they let the payload replay through `--seed`
+ * on the same major.
+ *
  * @param result - The roll result to format
  * @param options - Output mode; JSON wins when combined with verbose
  * @returns Formatted string for terminal output
  */
-export declare function formatResult(result: RollResult, options?: FormatOptions): string;
+export declare function formatResult(result: RollResult, options: FormatOptions): string;
 //# sourceMappingURL=format.d.ts.map

package/dist/cli/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/cli/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAe9C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAYpF"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/cli/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAe9C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAY/E"}

package/dist/cli/format.js

@@ -1,3 +1,4 @@
+import { VERSION } from '../index.js';
 import { renderBreakdown } from '../render.js';
 const TERMINAL_MARKS = {
     dropped: (_die, text) => `(${text})`,
@@ -5,10 +6,10 @@ const TERMINAL_MARKS = {
     failure: (_die, text) => `{${text}}`,
     droppedGroup: (inner) => `(${inner})`,
 };
-export function formatResult(result, options = {}) {
-    const { json = false, verbose = false } = options;
+export function formatResult(result, options) {
+    const { json, verbose, seed } = options;
     if (json) {
-        return JSON.stringify(result);
+        return JSON.stringify({ ...result, seed, version: VERSION });
     }
     if (!verbose) {
         return String(result.total);

package/dist/cli/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/cli/format.ts"],"names":[],"mappings":"AAQA,OAAO,EAAiB,eAAe,EAAE,MAAM,cAAc,CAAC;AAS9D,MAAM,cAAc,GAAa;IAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG;IACpC,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG;IACpC,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG;IACpC,YAAY,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG;CACtC,CAAC;AAyBF,MAAM,UAAU,YAAY,CAAC,MAAkB,EAAE,OAAO,GAAkB,EAAE;IAC1E,MAAM,EAAE,IAAI,GAAG,KAAK,EAAE,OAAO,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IAElD,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO,eAAe,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACjD,CAAC"}
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/cli/format.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAiB,eAAe,EAAE,MAAM,cAAc,CAAC;AAS9D,MAAM,cAAc,GAAa;IAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG;IACpC,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG;IACpC,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG;IACpC,YAAY,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG;CACtC,CAAC;AAgCF,MAAM,UAAU,YAAY,CAAC,MAAkB,EAAE,OAAsB;IACrE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IAExC,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO,eAAe,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACjD,CAAC"}

package/dist/cli/main.d.ts

@@ -28,9 +28,9 @@ export declare function writeErrorContext(notation: string, error: unknown, writ
  * `1` for a roll-parser error, `2` for a usage error. Anything that is not a
  * `RollParserError` propagates so the runtime reports it with a stack.
  *
- * `--json` swaps the success payload only — diagnostics stay plain text on
- * stderr and the exit codes are identical, so scripts can branch on the code
- * before parsing stdout.
+ * `--json` swaps the success payload on stdout and every diagnostic on
+ * stderr, usage errors included. Exit codes are identical either way, so
+ * scripts can still branch on the code before reading a stream.
  */
 export declare function main(env: CliEnv): number;
 //# sourceMappingURL=main.d.ts.map

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsCH,iDAAiD;AACjD,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAE7C,qDAAqD;AACrD,MAAM,MAAM,MAAM,GAAG;IACnB,iFAAiF;IACjF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAWxF;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA2CxC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyDH,iDAAiD;AACjD,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAE7C,qDAAqD;AACrD,MAAM,MAAM,MAAM,GAAG;IACnB,iFAAiF;IACjF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAWxF;AAmDD;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkDxC"}

package/dist/cli/main.js

@@ -1,7 +1,7 @@
-import { getErrorSpan, isRollParserError } from '../errors.js';
+import { getErrorSpan, isRollParserError, } from '../errors.js';
 import { VERSION } from '../index.js';
 import { roll } from '../roll.js';
-import { parseArgs } from './args.js';
+import { isKnownOption, parseArgs } from './args.js';
 import { formatResult } from './format.js';
 const HELP_TEXT = `roll-parser v${VERSION}
 
@@ -13,12 +13,23 @@ Options:
   -v, --verbose    Show detailed roll breakdown
   --json           Print the whole result as compact JSON (wins over --verbose)
   --seed <value>   Use seed for reproducible rolls
-  --               Treat every following argument as notation
+  --               Notation that looks like an option — put options before it
 
 JSON output:
-  Emits the complete result, including the structured "parts" tree. The
-  "degree" field (DegreeOfSuccess) serializes as a number: 0 critical failure,
-  1 failure, 2 success, 3 critical success. Errors stay plain text on stderr.
+  Emits the complete result, including the structured "parts" tree, plus the
+  "seed" that produced it and the "version" that fixes the seed-to-dice
+  mapping — rerun with --seed <seed> on the same major to replay the roll.
+  When --seed is omitted the CLI mints one. The "degree" field
+  (DegreeOfSuccess) serializes as a number: 0 critical failure, 1 failure,
+  2 success, 3 critical success.
+
+JSON errors:
+  Every diagnostic is one JSON line on stderr:
+  {"error":{"message":...,"code":...,"span":{"start":N}},...}. A roll error
+  adds the "notation" and "seed" that produced it, so a failure replays like
+  a result does; "code" and "span" are absent when the failure carries
+  neither. Usage errors are covered too, but only where --json still reads as
+  the flag: it is a seed value in --seed --json, and notation after --.
 
 Exit codes:
   0  Success
@@ -30,7 +41,7 @@ Examples:
   roll-parser 4d6kh3 --verbose
   roll-parser 4d6dl1 --seed "character-str"
   roll-parser "1d20+7 vs 25" --json
-  roll-parser -- -1d6+3
+  roll-parser -1d6+3
 `;
 export function writeErrorContext(notation, error, write) {
     const span = getErrorSpan(error);
@@ -42,15 +53,31 @@ export function writeErrorContext(notation, error, write) {
     write(`  ${notation}\n`);
     write(`  ${' '.repeat(column)}^\n`);
 }
+function writeOptionHint(terminated, notation, write) {
+    if (terminated && notation.split(' ').some(isKnownOption)) {
+        write('Hint: options must come before "--"\n');
+    }
+}
+function writeJsonError(write, error, context) {
+    write(`${JSON.stringify({ error, ...context, version: VERSION })}\n`);
+}
+function failUsage(stderr, message, json) {
+    if (json) {
+        writeJsonError(stderr, { message });
+    }
+    else {
+        stderr(`Error: ${message}\n`);
+        stderr('Run "roll-parser --help" for usage.\n');
+    }
+    return 2;
+}
 export function main(env) {
     const { argv, stdout, stderr } = env;
     const parsed = parseArgs(argv);
     if (!parsed.ok) {
-        stderr(`Error: ${parsed.error}\n`);
-        stderr('Run "roll-parser --help" for usage.\n');
-        return 2;
+        return failUsage(stderr, parsed.error, parsed.json);
     }
-    const { args } = parsed;
+    const { args, terminated } = parsed;
     if (args.showHelp) {
         stdout(HELP_TEXT);
         return 0;
@@ -60,20 +87,24 @@ export function main(env) {
         return 0;
     }
     if (args.notation == null) {
-        stderr('Error: No dice notation provided.\n');
-        stderr('Run "roll-parser --help" for usage.\n');
-        return 2;
+        return failUsage(stderr, 'No dice notation provided.', args.json);
     }
+    const seed = args.seed ?? crypto.randomUUID();
     try {
-        const options = args.seed != null ? { seed: args.seed } : {};
-        const result = roll(args.notation, options);
-        const output = formatResult(result, { json: args.json, verbose: args.verbose });
+        const result = roll(args.notation, { seed });
+        const output = formatResult(result, { json: args.json, verbose: args.verbose, seed });
         stdout(`${output}\n`);
     }
     catch (error) {
         if (isRollParserError(error)) {
-            stderr(`Error: ${error.message}\n`);
-            writeErrorContext(args.notation, error, stderr);
+            if (args.json) {
+                writeJsonError(stderr, { message: error.message, code: error.code, span: getErrorSpan(error) }, { notation: args.notation, seed });
+            }
+            else {
+                stderr(`Error: ${error.message}\n`);
+                writeErrorContext(args.notation, error, stderr);
+                writeOptionHint(terminated, args.notation, stderr);
+            }
             return 1;
         }
         throw error;

package/dist/cli/main.js.map

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