parseman 0.14.1 → 0.16.0

package/README.md

@@ -4,10 +4,29 @@
 
 # Parséman (PAR-zə-mahn)
 
-Write parsers in TypeScript — fast enough to run as-is, and blazing fast when the bundler macro kicks in. Same grammar either way; no grammar files, no generated output to check in. Drop the plugin in tests or anywhere a bundler isn't around and everything still works.
+Write parsers as TypeScript functions. Ship them like hand-written parsers.
+
+Parséman is a TypeScript parser-combinator library with an optional compiler/macro path that turns your grammar into flat JavaScript. Use the same grammar interpreted in tests and REPLs, macro-compiled at build time in production, or `.compile()`d on demand at runtime.
+
+Use Parséman when you want:
+
+- normal TypeScript instead of grammar files
+- parser-combinator ergonomics without parser-combinator slowness
+- CST/AST nodes with spans and trivia
+- error recovery for editor tooling
+- incremental re-parsing
+- fast parsers for DSLs, config languages, formatters, linters, and language servers
 
 > **📖 Full documentation: [matthew-dean.github.io/parseman](https://matthew-dean.github.io/parseman/)**
 
+## Why Parséman?
+
+Most parser tools make you choose between ergonomics and performance.
+
+Parser combinators are pleasant to write, but often slow. Parser generators can be fast, but usually involve grammar files, generated code, and extra tooling. Hand-written parsers are fast, but expensive to design and maintain.
+
+Parséman aims for the useful middle: write your parser as ordinary TypeScript, then compile it into code that behaves more like a hand-written parser.
+
 ---
 
 ## Install
@@ -64,8 +83,28 @@ Full API in the **[reference](https://matthew-dean.github.io/parseman/reference/
 
 ---
 
+## Compared to other parser tools
+
+Wondering how Parséman compares to Peggy, Chevrotain, Lezer, tree-sitter, Parsimmon, Nearley, or hand-written parsers?
+
+See the full comparison: **[How Parséman compares](https://matthew-dean.github.io/parseman/guide/comparison)**
+
+## Real grammar example: GraphQL
+
+Parséman includes a [GraphQL grammar](./examples/graphql/parser.ts) used in the benchmark suite. It parses executable GraphQL documents (queries, mutations, subscriptions, fragments, directives, variables, all value types) into typed AST nodes — not just syntax-validating them.
+
+This is a real-world example of Parséman on a non-trivial, spec-shaped language, not a toy grammar.
+
+- Source: [`examples/graphql/parser.ts`](./examples/graphql/parser.ts)
+- Benchmark results: [GraphQL benchmarks](https://matthew-dean.github.io/parseman/guide/benchmarks#graphql)
+- Benchmark runner: [`bench/run.ts`](./bench/run.ts)
+
+---
+
 ## Benchmarks
 
+Parséman includes benchmarks against several JavaScript/TypeScript parser libraries across JSON, CSV, and GraphQL fixtures. Benchmarks are not universal truth tablets — results depend on grammar shape, input size, runtime, and what each parser is asked to produce. The benchmark suite is included so results can be inspected and reproduced (see [Reproducing the numbers](https://matthew-dean.github.io/parseman/guide/benchmarks#reproducing-the-numbers)).
+
 **When parsing to JS values** — objects, row arrays, AST nodes — **Parséman's macro build is the fastest general-purpose JS parser we benchmark**, beating [Peggy](https://peggyjs.org/), [Parsimmon](https://github.com/jneen/parsimmon), [Chevrotain](https://chevrotain.io/), [Nearley](https://nearley.js.org/), and [Jison](https://github.com/zaach/jison) at every grammar and size. The only thing that edges it out is a purpose-built native like `JSON.parse`; for anything that *doesn't* have a built-in, Parséman is the one to beat.
 
 For **syntax tree building**, the compiled CST path (macro build) beats [Lezer](https://lezer.codemirror.net/) on the JSON CST fixture too — while producing a richer object tree with spans and trivia. For **incremental re-parse**, the two trade places by edit type: Parséman's `parseDoc` is ~300× faster than a full reparse on in-place value edits (and ahead of Lezer), while Lezer's buffer reuse wins on structural edits. Full breakdown in the [benchmarks guide](https://matthew-dean.github.io/parseman/guide/benchmarks).
@@ -84,7 +123,7 @@ Compared parsers: **Parséman**, [Peggy](https://peggyjs.org/), [Parsimmon](http
 
 Parséman has three modes — **interpreter** (zero setup, works anywhere), **macro build** (compiled by the bundler plugin at build time, zero runtime cost), and **`.compile()`** (optional runtime JIT). Most production use lands on one of the first two. The initialization section only shows parsers with a nonzero setup cost: `.compile()` costs 75–650 µs depending on grammar size; Chevrotain always costs 840–1,400 µs. Parsers not listed there start for free. (Init numbers are pinned on the charts — they're noisy run-to-run; warm-parse bars are the meaningful comparison.)
 
-On JSON, CSV, and GraphQL, Parséman macro beats every other library at every fixture size in the charts above — e.g. GraphQL large **154 µs** vs Peggy **423 µs**, JSON large **125 µs** vs Peggy **472 µs** / Chevrotain **1,946 µs**. Native `JSON.parse` is the one thing faster on JSON (**45 µs** large). Even the zero-setup interpreter is highly competitive: on JSON and CSV it's the fastest option after the macro build — ahead of Peggy and every other generator — with Peggy edging it out only on GraphQL. On the CST chart, macro build beats Lezer at every size (**344 µs** vs **587 µs** large, parse-only). Full write-up and how to refresh the charts: **[benchmarks guide](https://matthew-dean.github.io/parseman/guide/benchmarks)**. Grammar-level speed levers: [performance guide](https://matthew-dean.github.io/parseman/guide/performance); library-level codegen: [PERF_IDEAS.md](./PERF_IDEAS.md).
+On JSON, CSV, and GraphQL, Parséman macro beats every other library at every fixture size in the charts above — e.g. GraphQL large **154 µs** vs Peggy **423 µs**, JSON large **125 µs** vs Peggy **472 µs** / Chevrotain **1,946 µs**. Native `JSON.parse` is the one thing faster on JSON (**45 µs** large). Even the zero-setup interpreter is highly competitive: on JSON and CSV it's the fastest option after the macro build — ahead of Peggy and every other generator — with Peggy edging it out only on GraphQL. On the CST chart, macro build beats Lezer at every size (**344 µs** vs **587 µs** large, parse-only). Full write-up and how to refresh the charts: **[benchmarks guide](https://matthew-dean.github.io/parseman/guide/benchmarks)**. Grammar-level speed levers: [performance guide](https://matthew-dean.github.io/parseman/guide/performance); library-level codegen: [PERF_IDEAS.md](./notes/PERF_IDEAS.md).
 
 ---
 

package/dist/combinators/first-set.d.ts

@@ -1,8 +1,25 @@
-import type { FirstSet } from '../types.ts';
+import type { FirstSet, Combinator } from '../types.ts';
 export declare function union(a: FirstSet, b: FirstSet): FirstSet;
 export declare function intersects(a: FirstSet, b: FirstSet): boolean;
 export declare function fromChar(code: number): FirstSet;
 export declare function fromRange(lo: number, hi: number): FirstSet;
 export declare function any(): FirstSet;
 export declare function empty(): FirstSet;
+/**
+ * Can this parser SUCCEED consuming zero characters (nullable / matches-empty)?
+ * Used to compute a sound sequence first-set: a nullable leading term lets the
+ * NEXT term's first chars start the whole sequence. MUST err toward `true` when
+ * unsure — over-estimating nullability only widens the (over-approximated) first
+ * set, which stays sound; under-estimating would drop valid start chars and make
+ * first-char dispatch skip a matching arm.
+ */
+export declare function matchesEmpty(p: Combinator<unknown>, seen?: Set<Combinator<unknown>>): boolean;
+/**
+ * First-set of a sequence: union each term's first-set through the NULLABLE
+ * PREFIX — a leading `optional(…)` / `many(…)` / nullable term can be skipped, so
+ * the sequence can begin with a LATER term's first char. Stop at (and include)
+ * the first non-nullable term. (`parsers[0].firstSet` alone under-approximates
+ * and silently breaks first-char dispatch — see the InterpolatedSelector bug.)
+ */
+export declare function sequenceFirstSet(parsers: readonly Combinator<unknown>[]): FirstSet;
 //# sourceMappingURL=first-set.d.ts.map

package/dist/combinators/first-set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"first-set.d.ts","sourceRoot":"","sources":["../../src/combinators/first-set.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtD,wBAAgB,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAKxD;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAS5D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAE/C;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,CAE1D;AAED,wBAAgB,GAAG,IAAI,QAAQ,CAE9B;AAED,wBAAgB,KAAK,IAAI,QAAQ,CAEhC"}
+{"version":3,"file":"first-set.d.ts","sourceRoot":"","sources":["../../src/combinators/first-set.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,QAAQ,EAAE,UAAU,EAAa,MAAM,aAAa,CAAA;AAE7E,wBAAgB,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAKxD;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAS5D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAE/C;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,CAE1D;AAED,wBAAgB,GAAG,IAAI,QAAQ,CAE9B;AAED,wBAAgB,KAAK,IAAI,QAAQ,CAEhC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,GAAE,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAa,GAAG,OAAO,CAmCxG;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,QAAQ,CAOlF"}

package/dist/combinators/grammar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/combinators/grammar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAa,MAAM,aAAa,CAAA;AAGnF,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG;IACzC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IACnC,gFAAgF;IAChF,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IACpC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;CACrE;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAwCrF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAElE;AAED,wBAAgB,KAAK,CAAC,CAAC,EACrB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,YAAiB,GACtB,WAAW,CAAC,CAAC,CAAC,CAuBhB"}
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/combinators/grammar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAa,MAAM,aAAa,CAAA;AAInF,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG;IACzC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IACnC,gFAAgF;IAChF,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IACpC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;CACrE;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAwCrF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAElE;AAOD,wBAAgB,KAAK,CAAC,CAAC,EACrB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,YAAiB,GACtB,WAAW,CAAC,CAAC,CAAC,CA2BhB"}

package/dist/combinators/literal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"literal.d.ts","sourceRoot":"","sources":["../../src/combinators/literal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAapF,MAAM,MAAM,cAAc,GAAG;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,UAAU,CAAC,MAAM,CAAC,CA+CpF"}
+{"version":3,"file":"literal.d.ts","sourceRoot":"","sources":["../../src/combinators/literal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAwBpF,MAAM,MAAM,cAAc,GAAG;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,UAAU,CAAC,MAAM,CAAC,CAqDpF"}

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

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/combinators/parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAG7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EACjE,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,GACxB,CAAC,CAwCH"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/combinators/parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAI7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EACjE,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,GACxB,CAAC,CA+CH"}

package/dist/combinators/repeat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repeat.d.ts","sourceRoot":"","sources":["../../src/combinators/repeat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAkDpF,wBAAgB,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAuBlE;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CA2BvE;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,CAoB3E;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAyDhG"}
+{"version":3,"file":"repeat.d.ts","sourceRoot":"","sources":["../../src/combinators/repeat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAkDpF,wBAAgB,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CA4BlE;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CA+BvE;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,CAoB3E;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAyDhG"}

package/dist/combinators/sequence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../../src/combinators/sequence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAoD,MAAM,aAAa,CAAA;AAI/F,KAAK,aAAa,CAAC,CAAC,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI;KACnD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CAC7D,CAAA;AAED,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,EAChF,GAAG,OAAO,EAAE,CAAC,GACZ,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAuD9B"}
+{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../../src/combinators/sequence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAoD,MAAM,aAAa,CAAA;AAI/F,KAAK,aAAa,CAAC,CAAC,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI;KACnD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CAC7D,CAAA;AAED,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,EAChF,GAAG,OAAO,EAAE,CAAC,GACZ,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CA+D9B"}

package/dist/compiler/codegen.d.ts

@@ -6,7 +6,22 @@
  * `break <label>` rather than an IIFE return — no function call, no result
  * object allocation per node.
  */
-import type { Combinator, ParseResult, ParseContext, ParseError } from '../types.ts';
+import type { Combinator, FirstSet, ParseResult, ParseContext, ParseError } from '../types.ts';
+/**
+ * Runtime prelude helper for the structural-node capture gate. Answers "does the
+ * injected `_ctx.build` host read its (n+1)th positional arg?" — `.length` alone
+ * under-counts with rest/default params and can't see through a bound fn, so a
+ * rest/default param or an `arguments` reference forces full capture (output-safe).
+ * Plain positional and bound-native hosts (the common case) trust `.length`.
+ * Emitted (memoized on `_ctx._pmCapTL`/`_pmCapST`) wherever a structural node()
+ * arity-gates host capture; shared, un-namespaced, mirrors `_EMPTY_TL` placement.
+ */
+export declare const HOST_READS_DECL = "const _hostReads = (b, n) => { if (b === undefined) return false; let s; try { s = Function.prototype.toString.call(b) } catch (e) { return true } if (/\\barguments\\b/.test(s)) return true; const m = /^[^(]*\\(([\\s\\S]*?)\\)/.exec(s); if (m && /\\.\\.\\.|=/.test(m[1])) return true; return b.length > n }";
+/** Begin capturing regexes that fall back to `RegExp.exec` (didn't lower). */
+export declare function beginLoweringCapture(): void;
+/** Stop capturing and return the un-lowered regex sources seen since begin. */
+export declare function endLoweringCapture(): string[];
+export declare function firstSetCond(codeVar: string, fs: FirstSet): string;
 export declare function __setForceDisjointIf(on: boolean): void;
 export type CompiledParser<T> = {
     parse(input: string, pos?: number): ParseResult<T>;
@@ -50,35 +65,6 @@ export declare function ruleDependencies(ruleMap: ReadonlyArray<readonly [string
  * @see https://www.greadme.com/blog/security/what-is-content-security-policy-complete-guide
  */
 export declare function compile<T>(combinator: Combinator<T>, mapFnSources?: string[]): CompiledParser<T>;
-/**
- * Compile every entry of a `rules(factory)` map's returned object using ONE
- * shared codegen Ctx (regexes, named functions, map/build-fn arrays) instead
- * of running `compile()` independently per entry.
- *
- * Why this exists: `compile()` per entry gives each entry its own namedParsers
- * cache, so a sub-rule reachable from N different top-level entries (e.g.
- * `valueList` reachable from `Declaration`, `CustomDeclaration`, `Guard`, …)
- * gets fully re-compiled N times — on a richly cross-referential grammar
- * (Less: ~125 rule-map entries, deep mutual reference) this multiplies total
- * compiled size far past what the source grammar actually needs, independent
- * of the per-ref single-use inlining `analyzeLazyUsage` already handles
- * within one compile() call. Sharing one Ctx here means a sub-rule compiles
- * exactly once for the WHOLE rule map, however many entries reach it.
- *
- * Returns a single `replacement` — ONE shared IIFE, evaluated once, whose
- * result is the `{ key: fn, ... }` map — meant to replace the entire
- * `rules(factory)` call-expression (not one expression per key; splicing a
- * separate self-contained expression per key would either re-run the shared
- * prelude once per entry or duplicate its text per entry, undoing the win).
- * `keys` lists every entry compileRuleMap() saw, for the caller to validate
- * against the source's own key list.
- *
- * Returns null (same all-or-nothing contract the per-entry `compile()` +
- * `inlineExpression === null` check gave the plugin before) when the map
- * contains anything that can't be inlined — a runtime-fallback parser, or an
- * uncaptured transform/build closure source. The plugin's existing "warn and
- * leave this rules() call interpreted" fallback covers this case unchanged.
- */
 export declare function compileRuleMap(ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>): {
     keys: string[];
     replacement: string;
@@ -91,7 +77,7 @@ export declare function compileRuleMap(ruleMap: ReadonlyArray<readonly [string,
  * derives it — module identity in the macro, a counter in `compile()`).
  *
  *   prelude  — namespaced hoisted decls (regexes, expected, `_mf`/`_build`, and
- *              private `_pf` helper fns). Sentinels / `_EMPTY_TL` / `_collator`
+ *              private `_pf` helper fns). Sentinels / `_EMPTY_TL`
  *              are NOT here — they are SHARED, emitted once by the linker.
  *   ruleFns  — name → `function _r_<Name>(…) { … }` source (the composition
  *              surface; siblings call these by name).
@@ -106,9 +92,15 @@ export type LinkablePieces = {
     prelude: string[];
     ruleFns: Map<string, string>;
     wrappers: Map<string, string>;
+    /**
+     * Per-rule first-set (this artifact's own rules). fusedBody() uses the WINNING
+     * artifact's entry to resolve `/*@FS:rule:codevar@*​/true` dispatch placeholders
+     * emitted for rule-ref choice arms — sound under compose override.
+     */
+    firstSets: Map<string, FirstSet>;
     deps: Map<string, string[]>;
     needsEmptyTl: boolean;
-    needsCollator: boolean;
+    needsHostReads: boolean;
     /**
      * Transform (`_mf`) / build (`_build`) callback FUNCTIONS, injected into the
      * fused scope via `_env` when their SOURCE isn't available (runtime `compile()`

package/dist/compiler/codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/compiler/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAuB,WAAW,EAAE,YAAY,EAAE,UAAU,EAAkB,MAAM,aAAa,CAAA;AAodzH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAA0B;AAwiDjF,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAClD,kGAAkG;IAClG,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAChF;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG;QAAE,MAAM,EAAE,UAAU,EAAE,CAAA;KAAE,CAAA;IACvF,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC,CAAA;AAoJD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAC7D,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CA+BvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC,CA8GhG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAC7D;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA+FhD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IAC3B,YAAY,EAAE,OAAO,CAAA;IACrB,aAAa,EAAE,OAAO,CAAA;IACtB;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAA;IACrD,QAAQ,EAAE,aAAa,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAA;CACzD,CAAA;AAED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EACjE,EAAE,EAAE,MAAM,GACT,cAAc,GAAG,IAAI,CAwJvB"}
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/compiler/codegen.ts"],"names":[],"mappings":"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"}

package/dist/compiler/linker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linker.d.ts","sourceRoot":"","sources":["../../src/compiler/linker.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAa7C,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EAC7C,EAAE,CAAC,EAAE,MAAM,GACV,cAAc,CAIhB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAChC,YAAY,EAAE,aAAa,CAAC,OAAO,CAAC,EACpC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACpC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,EAC9B,KAAK,CAAC,EAAE,OAAO,GACd,OAAO,CAIT;AAED,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACzB;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAA;AAE3E;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAClB,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EAC7D,KAAK,EAAE,MAAM,EAAE,GACd,cAAc,CA2BhB;AA+CD;qFACqF;AACrF,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAI7E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,CAMhE;AA8BD,wBAAgB,OAAO,CACrB,KAAK,EAAE,KAAK,CAAC,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACrD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAK3B"}
+{"version":3,"file":"linker.d.ts","sourceRoot":"","sources":["../../src/compiler/linker.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAY,MAAM,aAAa,CAAA;AAavD,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EAC7C,EAAE,CAAC,EAAE,MAAM,GACV,cAAc,CAIhB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAChC,YAAY,EAAE,aAAa,CAAC,OAAO,CAAC,EACpC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACpC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,EAC9B,KAAK,CAAC,EAAE,OAAO,GACd,OAAO,CAIT;AAED,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACzB;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAA;AAE3E;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAClB,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EAC7D,KAAK,EAAE,MAAM,EAAE,GACd,cAAc,CA2BhB;AAmED;qFACqF;AACrF,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAI7E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,CAMhE;AA8BD,wBAAgB,OAAO,CACrB,KAAK,EAAE,KAAK,CAAC,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACrD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAK3B"}

package/dist/compiler/scannable-run.d.ts

@@ -105,6 +105,8 @@ export declare const BACKSLASH = 92;
  */
 export declare const SPACE_RANGES: Array<[number, number]>;
 export declare function parseClassRanges(body: string): Array<[number, number]> | null;
+/** ASCII case-insensitive letter check for `i`-flag literal lowering. */
+export declare const foldEq: (cVar: string, cp: number) => string;
 type CharSet = {
     ranges: Array<[number, number]>;
     negated: boolean;

package/dist/compiler/scannable-run.d.ts.map

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

package/dist/compiler/value-usage.d.ts

@@ -0,0 +1,24 @@
+import type { Combinator } from '../types.ts';
+/**
+ * Dead-value analysis (shared by the interpreter and codegen). A container
+ * combinator — `many` / `oneOrMore` / `optional` / `sequence` — builds an
+ * aggregate value (array / tuple / nullable). Under a `node()`, the node builds
+ * from the *captured children*, never from that aggregate, so the aggregate is
+ * built and thrown away. This pass marks those containers `valueUnused`; the
+ * interpreter and the emitter then skip building the aggregate entirely (the
+ * elements still parse and self-capture, so trees are identical).
+ *
+ * Walks ONE combinator tree (a single rule body, or a standalone root), stopping
+ * at `lazy`/ref boundaries — other rules are analyzed on their own root. Starts
+ * `consumed = true` (a rule's own value is assumed read — conservative); `node()`
+ * flips it to false for its inner parser; `transform` forces it true (its map fn
+ * reads the value). Sharing-safe: any `consumed = true` visit wins and is sticky,
+ * so a container reachable from BOTH a consuming and a non-consuming site keeps
+ * its aggregate (never wrongly elided).
+ *
+ * Soundness: a container is marked ONLY when every path to it passes through a
+ * `node()` (value-discarding) without an intervening value-reader — i.e. its
+ * aggregate provably isn't observed. Idempotent; safe to re-run.
+ */
+export declare function markUnusedValues(root: Combinator<unknown>): void;
+//# sourceMappingURL=value-usage.d.ts.map

package/dist/compiler/value-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-usage.d.ts","sourceRoot":"","sources":["../../src/compiler/value-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,aAAa,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI,CAuGhE"}