parseman 0.33.0 → 0.35.0

package/README.md

@@ -6,29 +6,17 @@
 
 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 compiled on demand at runtime with `compile()`.
+Parser combinators are pleasant to write and usually slow. Parser generators are fast and
+usually mean grammar files, generated code, and extra tooling. Parséman is a TypeScript
+combinator library with an optional compiler: write ordinary TypeScript, and a build-time
+macro turns it into flat JavaScript that behaves like a parser you wrote by hand.
 
-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
+Reach for it when you want normal TypeScript instead of grammar files, CST/AST nodes with
+spans and trivia, error recovery and incremental re-parsing for editor tooling, or simply
+a fast parser for a DSL, config language, formatter, or linter.
 
 > **📖 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
 
 ```bash
@@ -36,8 +24,8 @@ npm install parseman
 # pnpm add parseman
 ```
 
-Parseman is pre-1.0. Minor versions may include breaking changes; check the
-[changelog](./CHANGELOG.md) before upgrading.
+Pre-1.0: minor versions may carry breaking changes — check the [changelog](./CHANGELOG.md)
+before upgrading. Requires Node `^20.19.0 || >=22.12.0`.
 
 ## Quick start
 
@@ -57,64 +45,95 @@ parse(requestLine, 'GET /api/v1 HTTP/1.1')
 // { ok: true, value: { verb: 'GET', path: '/api/v1', version: 'HTTP/1.1' }, span: ... }
 ```
 
+New here? **[What is Parséman?](https://matthew-dean.github.io/parseman/guide/getting-started)**
+walks the same ground more slowly.
+
 ## Three modes, one grammar
 
 The same combinator code runs three ways, with identical results:
 
 - **Interpreter** — zero setup, works anywhere (tests, REPLs, dynamic grammars).
-- **Macro build** — a [bundler plugin](https://matthew-dean.github.io/parseman/guide/macro-mode) evaluates your grammar at build time and replaces it with inline JS. Zero runtime cost; the `parseman` import disappears from the bundle.
-- **`compile()`** — the same optimizer, run on demand at runtime.
+- **Macro build** — a [bundler plugin](https://matthew-dean.github.io/parseman/guide/macro-mode)
+  evaluates your grammar at build time and inlines the result. The combinator import you
+  mark `with { type: 'macro' }` disappears entirely; what ships is flat JavaScript with no
+  parseman import in it. (Executing that parser still goes through `run()`/`parse()`, so an
+  app keeps parseman as an ordinary dependency — see
+  [the three modes](https://matthew-dean.github.io/parseman/guide/modes).)
+- **`compile()`** — the same optimizer, on demand at runtime.
 
 ```ts
 // Add the plugin (vite.config.ts) and one import attribute — that's the whole change:
 import { literal, sequence, choice } from 'parseman' with { type: 'macro' }
 ```
 
-See **[The three modes](https://matthew-dean.github.io/parseman/guide/modes)** for the full story.
+See **[The three modes](https://matthew-dean.github.io/parseman/guide/modes)**.
 
 ## What's in the box
 
-- **[Combinators](https://matthew-dean.github.io/parseman/guide/combinators)** — `literal`, `regex`, `sequence`, `choice`, `many`, `sepBy`, `token`, `not`, and more.
-- **[Whitespace & trivia](https://matthew-dean.github.io/parseman/guide/trivia)** — grammar-defined filler skipping, with per-chunk kind capture.
-- **[Recursive rules](https://matthew-dean.github.io/parseman/guide/recursive-rules)** — `rules()` for mutually recursive grammars; fully macro-compilable.
-- **[CST / AST nodes](https://matthew-dean.github.io/parseman/guide/ast)** — `node()` captures terminals, named `field()` values, and trivia for you, with `unwrap` for AST/value wrappers, `collapse` for grammar-local CST wrappers, and `cstBuildHost({ collapse })` for public CST policies.
-- **[Incremental re-parsing](https://matthew-dean.github.io/parseman/guide/incremental)** — `parseDoc` re-parses just the edited subtree on each keystroke.
-- **[Error recovery](https://matthew-dean.github.io/parseman/guide/error-recovery)** — `recover`, `expect`, and a `{ recover: true }` channel keep parsing broken input and report every error.
-- **[Context-sensitive parsing](https://matthew-dean.github.io/parseman/guide/context)** — `withCtx` / `guard` without mutating shared state.
-
-Full API in the **[reference](https://matthew-dean.github.io/parseman/reference/api)**.
-
----
-
-## 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)
-
----
+**✍️ Writing grammars**
+
+- 🧩 **[Combinators](https://matthew-dean.github.io/parseman/guide/combinators)** — `literal`,
+  `regex`, `sequence`, `choice`, `many`, `sepBy`, `token`, `peek`, `not`, and more.
+- 🌀 **[Recursive rules](https://matthew-dean.github.io/parseman/guide/recursive-rules)** —
+  `rules()` for mutually recursive grammars; fully macro-compilable.
+- 🫧 **[Whitespace & trivia](https://matthew-dean.github.io/parseman/guide/trivia)** —
+  grammar-defined filler skipping, with per-chunk kind capture.
+- 🎯 **[Ordered choice, done right](https://matthew-dean.github.io/parseman/guide/keywords)** —
+  PEG semantics you control by ordering, with keyword boundaries that don't bite.
+- 🪶 **[Grammars the way you write them](https://matthew-dean.github.io/parseman/guide/natural-grammars)** —
+  no FIRST/FOLLOW sets to compute, no left-factoring `choice(a·x, a·y)` into `a·(x | y)`
+  to satisfy the tool. The compiler does that for you.
+- 🧬 **[Extending grammars](https://matthew-dean.github.io/parseman/guide/extending)** —
+  `compose()` a dialect onto a base grammar instead of forking it.
+- 🎛️ **[Context-sensitive parsing](https://matthew-dean.github.io/parseman/guide/context)** —
+  `withCtx` / `gate` without mutating shared state.
+
+**🌳 Getting structure out**
+
+- 🌲 **[CST / AST nodes](https://matthew-dean.github.io/parseman/guide/ast)** — `node()`
+  captures terminals, named fields, and trivia, with policies for wrapping and collapsing.
+- 🩹 **[Error recovery](https://matthew-dean.github.io/parseman/guide/error-recovery)** —
+  keep parsing broken input and report every error.
+- ⚡ **[Incremental re-parsing](https://matthew-dean.github.io/parseman/guide/incremental)** —
+  `parseDoc` re-parses just the edited subtree on each keystroke.
+- 💡 **[Editor / LSP integration](https://matthew-dean.github.io/parseman/guide/editor-integration)** —
+  completions and lint keyed by rule name; the grammar stays pure structure.
+
+**🔬 Seeing what your grammar does**
+
+- 🚂 **[Railroad diagrams & EBNF](https://matthew-dean.github.io/parseman/guide/spec-generation)** —
+  `toRailroadHtml()` and `toEBNF()` generate the grammar reference *from the parser*, so
+  the spec can't drift from what actually parses.
+- 🔎 **[Grammar observability](https://matthew-dean.github.io/parseman/guide/grammar-observability)** —
+  coverage ("which rules and choice arms ran?") and trace ("what did it try, select, and
+  backtrack through?").
+- 🚦 **[First-char gating diagnostics](https://matthew-dean.github.io/parseman/guide/first-char-gating)** —
+  the build tells you which `choice` lost its O(1) dispatch, names the overlapping arms,
+  and says how to fix it.
+- 📈 **[Performance guide](https://matthew-dean.github.io/parseman/guide/performance)** —
+  the levers that actually move a grammar, and [how regexes lower](https://matthew-dean.github.io/parseman/guide/regex-lowering).
+
+Full API in the **[reference](https://matthew-dean.github.io/parseman/reference/api)**; how
+it stacks up against Peggy, Chevrotain, Lezer, tree-sitter, Parsimmon, Nearley and
+hand-written parsers in
+**[How Parséman compares](https://matthew-dean.github.io/parseman/guide/comparison)**.
 
 ## 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**, Parséman's `parseDoc` stores parent-relative spans so in-place value edits are ~110× faster than a full reparse and ~20× ahead of Lezer; structural edits (inserting/removing a whole list element) reuse the collection's untouched tail and land within a few × of Lezer's buffer reuse rather than at full-reparse cost. Full breakdown in the [benchmarks guide](https://matthew-dean.github.io/parseman/guide/benchmarks).
+Benchmarked against [Peggy](https://peggyjs.org/),
+[Parsimmon](https://github.com/jneen/parsimmon), [Chevrotain](https://chevrotain.io/),
+[Nearley](https://nearley.js.org/), [Jison](https://github.com/zaach/jison) and
+[Lezer](https://lezer.codemirror.net/) on JSON, CSV and GraphQL — each building real output
+(objects, row arrays, AST nodes), not validating syntax.
 
-Measured on Apple M4 Pro. Bars show µs per parse — shorter is faster. Refresh: `pnpm bench:svg` (benchmarks chart parsers and updates `assets/bench-*.svg`).
+**Parsing to JS values, the macro build is the fastest general-purpose JS parser in the
+suite** — ahead of every library above at every grammar and size (GraphQL large: **142 µs**
+vs Peggy's 339 µs). Only a purpose-built native edges it out, `JSON.parse` on JSON.
 
-Compared parsers: **Parséman**, [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) (plus `JSON.parse` on JSON). Each implements the same parsing work on the bench fixtures — building JS values / row arrays / GraphQL AST nodes, not syntax-only validation. Peggy grammars in `bench/*.pegjs` are the reference; Nearley JSON uses [kach/nearley `examples/json.ne`](https://github.com/kach/nearley/blob/master/examples/json.ne); other Nearley and Jison grammars are ports of those Peggy files (`bench/vendor/`).
+Two more results worth calling out: the compiled CST path beats Lezer on the JSON CST
+fixture while producing a richer tree carrying spans and trivia, and `parseDoc` stores
+parent-relative spans so an in-place edit costs a fraction of a full reparse rather than a
+multiple of it.
 
 ![JSON parsing benchmarks](https://raw.githubusercontent.com/matthew-dean/parseman/main/assets/bench-json.svg)
 
@@ -124,26 +143,29 @@ Compared parsers: **Parséman**, [Peggy](https://peggyjs.org/), [Parsimmon](http
 
 ![JSON CST parsing benchmarks](https://raw.githubusercontent.com/matthew-dean/parseman/main/assets/bench-cst-json.svg)
 
-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.)
+Per-fixture figures, initialization costs, hardware, grammar provenance and how to reproduce
+any of it: **[benchmarks guide](https://matthew-dean.github.io/parseman/guide/benchmarks)**.
+Results move with grammar shape, input size and runtime — which is why the suite ships with
+the library rather than only its conclusions. Speed levers for your own grammars:
+[performance guide](https://matthew-dean.github.io/parseman/guide/performance).
 
-On JSON, CSV, and GraphQL, Parséman macro beats every other library at every fixture size in the charts above — e.g. GraphQL large **142 µs** vs Peggy **339 µs**, JSON large **141 µs** vs Peggy **466 µs** / Chevrotain **250 µs**. Native `JSON.parse` is the one thing faster on JSON (**54.6 µ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 (**172 µs** vs **619 µ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).
-
----
+The GraphQL fixture is a [real grammar](./examples/graphql/parser.ts), parsing executable
+documents — queries, mutations, fragments, directives, every value type — into typed AST
+nodes, so the numbers come from a spec-shaped language rather than a toy.
 
 ## Developing
 
 ```bash
 pnpm install
-pnpm test                   # Vitest — interpreter + compiler parity + ordered-choice semantics
-pnpm typecheck              # TypeScript 7
-pnpm build                  # ESM + CJS + .d.ts → dist/
-pnpm bench                  # parser-to-parser comparison
-pnpm bench:parseman         # Parseman interpreted vs compiled regression report
-pnpm bench:svg              # chart-only benchmarks + refresh assets/bench-*.svg
-pnpm bench:compile-grammars # regenerate Peggy / Nearley / Jison parser output in bench/
-pnpm docs:dev               # run this documentation site locally
+pnpm test         # interpreter + compiled parity, ordered-choice semantics
+pnpm typecheck
+pnpm build        # ESM + CJS + .d.ts → dist/
+pnpm docs:dev     # this documentation site, locally
 ```
 
+Benchmark and chart tasks (`pnpm bench`, `bench:svg`, `bench:parseman`, …) are described in
+the [benchmarks guide](https://matthew-dean.github.io/parseman/guide/benchmarks#reproducing-the-numbers).
+
 ## License
 
 MIT © [Matthew Dean](https://github.com/matthew-dean)

package/dist/analysis/gating.d.ts

@@ -15,8 +15,16 @@
  * (see `src/compiler/codegen.ts`). Accept a deliberately-ungated choice by listing
  * its `id` in the gating snapshot allowlist (`analyzeGating(entry, { accept })` /
  * `compile(g, { gating: { level, accept } })`) — the single suppression mechanism.
+ *
+ * WHERE the question is asked matters as much as the answer. A SHARED SHAPE — a
+ * `rules()` map referencing a rule it doesn't define (`g.Value`) — has no verdict of
+ * its own: the hole makes every first-set through it `any`, but that configuration is
+ * never executed and its author cannot fix it. Such a choice is `deferred` here, and
+ * re-asked with `resolveRef` at the site that BINDS the name (`runFusedGatingDiagnostic`
+ * in codegen.ts) — the artifact that really runs, whose author really can fix it.
  */
 import type { Combinator, FirstSet } from '../types.ts';
+import { type RefResolver } from '../combinators/first-set.ts';
 /** Why an arm's (deep) first-set is `any` / over-broad — the poison source. */
 export type FirstSetCause = 'leading-not' | 'nullable-prefix' | 'cross-artifact-ref' | 'broad-recognizer' | 'opaque-wrapper' | 'ref-cycle';
 /** An arm whose deep first-set is `any` / over-broad. */
@@ -32,6 +40,16 @@ export type AnyArm = {
      * genuinely-ungated finding.
      */
     shallowAnyOnly: boolean;
+    /**
+     * True when the poison is a NAMED cross-artifact hole this artifact cannot resolve
+     * (`g.Value` in a shared shape). The author of THIS artifact cannot act on it — the
+     * arm's real first-set only exists once a consumer binds the name — so a choice
+     * whose every `any` arm is one of these is `deferred`, not `ungated`.
+     *
+     * An UNNAMED unresolved `ref()` is NOT this: nobody can bind it by name, so it is a
+     * genuine local finding and stays reportable here.
+     */
+    unresolvedExternal: boolean;
     /** Concrete fix, naming a real primitive. */
     suggestion: string;
 };
@@ -72,6 +90,17 @@ export type ChoiceGating = {
     gates: 'yes' | 'recoverable' | 'no';
     /** True when this ungated choice's `id` is in the accepted-snapshot allowlist. */
     accepted: boolean;
+    /**
+     * `gates: 'no'` was decided by cross-artifact HOLES ONLY — every `any` arm is an
+     * unresolved NAMED `g.Foo` ref and no two finite arms overlap. The verdict is not
+     * this artifact's to make: the shape module can't fix it (the hole has no body
+     * here) and the configuration it describes never runs. The answer belongs to the
+     * FUSED artifact, where the name is bound — see `runFusedGatingDiagnostic`.
+     *
+     * Deferred choices are excluded from `ungated`: they neither warn nor fail the
+     * `'error'` gate at this site.
+     */
+    deferred: boolean;
     combinedFirstSet: {
         shallow: FirstSet;
         deep: FirstSet;
@@ -88,6 +117,22 @@ export type AnalyzeGatingOptions = {
      * SINGLE per-choice suppression mechanism.
      */
     accept?: Iterable<string>;
+    /**
+     * Name to attribute an UNNAMED entry to, instead of the synthetic `<entry>`.
+     * The macro plugin passes the binding's own variable name, so a warning on a
+     * top-level combinator const reads `choice @ directMixinReferenceAhead`
+     * (actionable, and a discriminating `accept` key) rather than `choice @
+     * <entry>` repeated once per const. Ignored when the entry already carries a
+     * `_ruleName`.
+     */
+    entryName?: string;
+    /**
+     * Bind NAMED cross-artifact holes (`g.Foo`) by name — supply the FUSED winner map's
+     * lookup. With it, an arm led by a shared shape's hole reports the first-set it
+     * really has once bound, so `deferred` collapses to a real `yes`/`no` verdict.
+     * Without it (the authoring site) such a choice stays `deferred`.
+     */
+    resolveRef?: RefResolver;
 };
 export type GatingReport = {
     totalChoices: number;
@@ -97,6 +142,12 @@ export type GatingReport = {
     ungated: ChoiceGating[];
     /** Ungated choices whose id was in the accepted allowlist — silent, accepted with intent. */
     accepted: ChoiceGating[];
+    /**
+     * Choices whose verdict is NOT this artifact's to make — every `any` arm is an
+     * unresolved cross-artifact hole (see `ChoiceGating.deferred`). Silent here; the
+     * fused artifact re-asks the question with the hole bound.
+     */
+    deferred: ChoiceGating[];
     /** Accepted ids that matched no ungated choice — stale snapshot entries to prune. */
     acceptedUnused: string[];
     /** Every choice, for full inspection / CI snapshots. */
@@ -105,11 +156,25 @@ export type GatingReport = {
 };
 export declare function firstSetToString(fs: FirstSet): string;
 export declare function analyzeGating(entry: Combinator<unknown>, opts?: AnalyzeGatingOptions): GatingReport;
+/**
+ * Multi-root variant: analyze a WHOLE `rules()` map in one walk, so every choice
+ * is attributed to the rule that owns it.
+ *
+ * The macro build compiles a grammar through `compileRuleMap`/`compileLinkable`,
+ * never through the single-entry `compile()`. Analyzing one entry at a time (or
+ * not at all) is what produced unnamed `choice @ <entry>` warnings and ZERO
+ * anti-patterns for grammars that in fact have dozens: an unnamed warning in a
+ * multi-thousand-line grammar is unactionable. Seeding the walk with EVERY named
+ * root is what recovers the rule names — and, because the walk is shared, each
+ * choice is still analyzed exactly once however many rules reach it.
+ */
+export declare function analyzeGatingRules(ruleMap: ReadonlyArray<readonly [string, Combinator<unknown>]>, opts?: AnalyzeGatingOptions): GatingReport;
 export type GatingWarnLevel = 'off' | 'warn' | 'error';
 /**
  * Format the genuinely-ungated findings + anti-patterns as ready-to-print lines.
  * Precise by design: only 'no'-gated choices NOT in the accepted allowlist, plus
- * the anti-pattern lints. Recoverable / gated / accepted choices produce nothing.
+ * the anti-pattern lints. Recoverable / gated / accepted / DEFERRED choices produce
+ * nothing (a deferred choice's verdict belongs to the fusing artifact, not here).
  */
 export declare function formatGatingWarnings(report: GatingReport): string[];
 //# sourceMappingURL=gating.d.ts.map

package/dist/analysis/gating.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gating.d.ts","sourceRoot":"","sources":["../../src/analysis/gating.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAa,MAAM,aAAa,CAAA;AAGlE,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,gBAAgB,GAChB,WAAW,CAAA;AAEf,yDAAyD;AACzD,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,aAAa,CAAA;IACpB,gGAAgG;IAChG,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAA;IACvB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,oEAAoE;AACpE,MAAM,MAAM,OAAO,GAAG;IACpB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,EAAE,EAAE,QAAQ,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,iFAAiF;AACjF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,YAAY,GAAG,aAAa,GAAG,eAAe,CAAA;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,gBAAgB,GAAG,sBAAsB,GAAG,cAAc,CAAA;AAEzG,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;OAKG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,iBAAiB,CAAA;IAC3B;;;;;;;OAOG;IACH,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,IAAI,CAAA;IACnC,kFAAkF;IAClF,QAAQ,EAAE,OAAO,CAAA;IACjB,gBAAgB,EAAE;QAAE,OAAO,EAAE,QAAQ,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAA;IACvD,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,QAAQ,EAAE,OAAO,EAAE,CAAA;CACpB,CAAA;AAED,qEAAqE;AACrE,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,uFAAuF;IACvF,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,6FAA6F;IAC7F,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,qFAAqF;IACrF,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,wDAAwD;IACxD,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,YAAY,EAAE,WAAW,EAAE,CAAA;CAC5B,CAAA;AAsCD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAIrD;AAgJD,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,YAAY,CAiDnG;AA4CD,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAA;AAEtD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAanE"}
+{"version":3,"file":"gating.d.ts","sourceRoot":"","sources":["../../src/analysis/gating.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAa,MAAM,aAAa,CAAA;AAClE,OAAO,EAA4B,KAAK,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAExF,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,gBAAgB,GAChB,WAAW,CAAA;AAEf,yDAAyD;AACzD,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,aAAa,CAAA;IACpB,gGAAgG;IAChG,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAA;IACvB;;;;;;;;OAQG;IACH,kBAAkB,EAAE,OAAO,CAAA;IAC3B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,oEAAoE;AACpE,MAAM,MAAM,OAAO,GAAG;IACpB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,EAAE,EAAE,QAAQ,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,iFAAiF;AACjF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,YAAY,GAAG,aAAa,GAAG,eAAe,CAAA;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,gBAAgB,GAAG,sBAAsB,GAAG,cAAc,CAAA;AAEzG,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;OAKG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,iBAAiB,CAAA;IAC3B;;;;;;;OAOG;IACH,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,IAAI,CAAA;IACnC,kFAAkF;IAClF,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;;;OASG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB,gBAAgB,EAAE;QAAE,OAAO,EAAE,QAAQ,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAA;IACvD,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,QAAQ,EAAE,OAAO,EAAE,CAAA;CACpB,CAAA;AAED,qEAAqE;AACrE,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACzB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,WAAW,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,uFAAuF;IACvF,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,6FAA6F;IAC7F,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB;;;;OAIG;IACH,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,qFAAqF;IACrF,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,wDAAwD;IACxD,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,YAAY,EAAE,WAAW,EAAE,CAAA;CAC5B,CAAA;AAsCD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAIrD;AAmKD,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,YAAY,CAEnG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAC9D,IAAI,CAAC,EAAE,oBAAoB,GAC1B,YAAY,CA2Dd;AAuDD,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAA;AAEtD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAanE"}

package/dist/combinators/case-fold.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The case-fold CLASS of a code point under ECMAScript's NON-Unicode `/i`
+ * matching — the exact relation `keywords({ caseInsensitive: true })` compiles to.
+ *
+ * A first-set drives O(1) `choice` dispatch, so it MUST be a superset of every
+ * character the combinator can really start with. For a case-insensitive matcher
+ * that means: for every input char X that the matcher would accept as the first
+ * char, X is in the set. Under `/i` WITHOUT `u`, two chars match iff they share a
+ * canonical form, and that relation is NOT simply `{c, toUpperCase(c),
+ * toLowerCase(c)}` — 67 BMP code points sit in classes those three miss:
+ *
+ *   σ (U+03C3) ↔ Σ (U+03A3) ↔ ς (U+03C2)   final sigma is in the class but is
+ *                                            neither the upper- nor lowercase of σ
+ *   µ (U+00B5) ↔ μ (U+03BC) ↔ Μ (U+039C)   micro sign folds into Greek mu
+ *   DŽ (U+01C4) ↔ Dž (U+01C5) ↔ dž (U+01C6)   titlecase digraphs (also LJLjljNJNjnjDZDzdz)
+ *   ͅ (U+0345) ↔ ι (U+03B9) ↔ ι (U+1FBE)   combining iota subscript
+ *
+ * so widening a first-set by upper/lower alone is UNSOUND for them.
+ *
+ * The canonical form below is ECMAScript's `Canonicalize` for non-Unicode mode:
+ * uppercase the char; if that is not exactly one char, or if it would cross the
+ * ASCII boundary INTO Basic Latin, keep the original. That last clause is why
+ * `/s/i` does not match `ſ` (U+017F) and `/k/i` does not match `K` (U+212A) —
+ * cross-boundary folds are refused in BOTH directions, which is what keeps an
+ * ASCII first-set tight and sound for the common all-ASCII keyword set.
+ *
+ * The classes are derived from the RUNNING engine's own `toUpperCase`, not a
+ * frozen table, so they cannot drift from the regex engine that will do the
+ * matching. Verified exhaustively against real `/i` behaviour across the BMP:
+ * 1141 multi-member classes, 2307 members, zero disagreements in either
+ * direction (see `test/unit/case-fold.test.ts`).
+ */
+/**
+ * Every code point that a non-Unicode `/i` matcher treats as equal to `cp`,
+ * INCLUDING `cp` itself. Union these into a first-set to keep case-insensitive
+ * dispatch sound.
+ */
+export declare function caseFoldVariants(cp: number): readonly number[];
+//# sourceMappingURL=case-fold.d.ts.map

package/dist/combinators/case-fold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"case-fold.d.ts","sourceRoot":"","sources":["../../src/combinators/case-fold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAuCH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAc9D"}

package/dist/combinators/expect.d.ts

@@ -7,7 +7,7 @@ export type { ParseError };
  *   literal('}')        -> ['"}"']
  *   keywords(['a','b']) -> ['"a"', '"b"']
  *   choice(x, y)        -> expected(x) ++ expected(y)   (all alternatives)
- *   sequence(a, b, …)   -> expected(a)                  (only the first term can fail first)
+ *   sequence(a, b, …)   -> expected(a) ++ … through the NULLABLE prefix
  *   label('s', x)       -> ['s']                        (an explicit name wins)
  *
  * This is what lets expect() report a meaningful, IDENTICAL expectation in both

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

@@ -1 +1 @@
-{"version":3,"file":"expect.d.ts","sourceRoot":"","sources":["../../src/combinators/expect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,UAAU,EAAE,MAAM,aAAa,CAAA;AAGhG,YAAY,EAAE,UAAU,EAAE,CAAA;AAE1B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,CAsC/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,GAAG,UAAU,CAAC,CA2B/F;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE"}
+{"version":3,"file":"expect.d.ts","sourceRoot":"","sources":["../../src/combinators/expect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,UAAU,EAAE,MAAM,aAAa,CAAA;AAIhG,YAAY,EAAE,UAAU,EAAE,CAAA;AAE1B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,CAE/D;AAkED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,GAAG,UAAU,CAAC,CA2B/F;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE"}

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

@@ -1,4 +1,17 @@
 import type { FirstSet, Combinator } from '../types.ts';
+/**
+ * Resolve a NAMED cross-artifact rule reference (`g.Foo`) whose own thunk does not
+ * resolve — the shared-shape hole, bound by name at fuse time.
+ *
+ * A shape module compiles `Ratio: sequence(g.Value, …)` without defining `Value`, so
+ * that `lazy`'s thunk throws and every first-set through it degrades to `any`. Once
+ * the shape is FUSED with a dialect that defines `Value`, the hole is bound — pass a
+ * resolver over the fused winner map and the first-set is the real one.
+ *
+ * Only NAMED refs are resolvable: an unnamed `ref()` that was never `.define()`d
+ * carries no name for anyone to bind, so it stays `any`.
+ */
+export type RefResolver = (name: string) => Combinator<unknown> | undefined;
 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;
@@ -20,7 +33,7 @@ export declare function empty(): FirstSet;
  * 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;
+export declare function matchesEmpty(p: Combinator<unknown>, seen?: Set<Combinator<unknown>>, resolve?: RefResolver): boolean;
 /**
  * A ZERO-WIDTH ASSERTION never consumes input, so it contributes NOTHING to a
  * sequence's first-set — the first consumed char comes from the following
@@ -33,17 +46,27 @@ export declare function matchesEmpty(p: Combinator<unknown>, seen?: Set<Combinat
  * widens the set of possible first chars beyond Y. So firstSet(Y) is a sound (and
  * tighter) superset.
  *
- * Parseman has NO positive-lookahead combinator (`(?=X)` exists only INSIDE a
- * `regex()` pattern, where the regex first-set analyzer handles it). If one is ever
- * added, its tight first-set is firstSet(body) ∩ firstSet(Y) when `body` is
- * NON-nullable (both must be satisfiable at the same position), else firstSet(Y)
- * (a nullable `(?=body)` succeeds on empty, so it imposes no first-char constraint
- * and intersecting would UNSOUNDLY exclude valid chars). It must NOT be added to
- * this predicate without that intersection logic — a future assertion combinator
- * left out of this set merely contributes its shallow `any` first-set, which stays
- * sound (over-approximation), only losing tightness.
+ * The POSITIVE lookahead `peek(X)` is zero-width too, but it is NOT in this
+ * predicate: unlike `not`, it knows what it requires, so its first-set is a real
+ * constraint that must be INTERSECTED into the sequence's set rather than dropped
+ * (see `isPositiveLookahead` and `sequenceFirstSet`).
  */
 export declare function isZeroWidthAssertion(p: Combinator<unknown>): boolean;
+/**
+ * A POSITIVE zero-width assertion (`peek(X)`). It consumes nothing, so like
+ * `not(X)` it does not contribute a first char of its own — but it does REQUIRE
+ * that X match here, so `peek(X) Y` can only start with a char in
+ * firstSet(X) ∩ firstSet(Y). That intersection is what makes a leading `peek()`
+ * gate its choice arm; `not(not(X))`, the only previous spelling, reports `any()`
+ * and poisons the dispatch instead.
+ *
+ * Soundness: first-sets are SUPERSETS of the true first chars, and
+ * (A ⊇ a) ∧ (B ⊇ b) ⇒ A ∩ B ⊇ a ∩ b — so intersecting stays a superset and can
+ * never skip a real match. A NULLABLE body succeeds on the empty string and
+ * therefore constrains nothing; `peek()` reports `any()` in that case, which the
+ * intersection treats as "no constraint".
+ */
+export declare function isPositiveLookahead(p: 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
@@ -66,6 +89,10 @@ export declare function sequenceFirstSet(parsers: readonly Combinator<unknown>[]
  * SOUND ONLY where refs are FINAL (monolithic compile). Under compose OVERRIDE a
  * referenced rule can be replaced with a WIDER first-set, so a baked deep set
  * would wrongly skip valid input — the compose path defers dispatch to fuse time.
+ *
+ * `resolve` binds NAMED cross-artifact holes (`g.Foo`) against a fused winner map —
+ * see `RefResolver`. Diagnostic-only today: it is what lets the gating analysis ask
+ * the question at the site where the hole actually HAS an answer.
  */
-export declare function firstSetOf(p: Combinator<unknown>, seen?: Set<Combinator<unknown>>): FirstSet;
+export declare function firstSetOf(p: Combinator<unknown>, seen?: Set<Combinator<unknown>>, resolve?: RefResolver): 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,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;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQnG;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,CAqCxG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,OAAO,CAEpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,QAAQ,CAOlF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,GAAE,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAa,GAAG,QAAQ,CA2CvG"}
+{"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;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,UAAU,CAAC,OAAO,CAAC,GAAG,SAAS,CAAA;AAS3E,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;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQnG;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,CAC1B,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EACtB,IAAI,GAAE,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAa,EAC1C,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CA6CT;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,OAAO,CAEpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,OAAO,CAEnE;AA6BD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,QAAQ,CAalF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CACxB,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EACtB,IAAI,GAAE,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAa,EAC1C,OAAO,CAAC,EAAE,WAAW,GACpB,QAAQ,CAsDV"}

package/dist/combinators/keywords.d.ts

@@ -13,10 +13,19 @@ export type KeywordsOptions = {
  * matching `true` inside `trueish`. The boundary defaults to `_0-9A-Za-z`,
  * which covers most programming-language identifiers.
  *
- *   word('true')              // matches "true" but not "trueish"
- *   word('color', 'A-Za-z-') // CSS-style identifier boundary
+ *   word('true')                                    // matches "true" but not "trueish"
+ *   word('color', 'A-Za-z-')                        // CSS-style identifier boundary
+ *   word('media', 'A-Za-z0-9_-', { caseInsensitive: true })
+ *   word('media', { caseInsensitive: true })        // default boundary + options
+ *
+ * `caseInsensitive` matches `keywords()` and exists because it is REQUIRED, not a
+ * nicety: CSS at-keywords, function names and units are ASCII case-insensitive per
+ * spec (CSS Syntax §3). Without it the only conforming spellings were
+ * `regex(/media/i)` — which `analyzeGating` correctly flags as the `keyword-regex`
+ * anti-pattern — or `keywords(['media'], …)` for a single word.
  */
-export declare function word(str: string, boundary?: string): Combinator<string>;
+export declare function word(str: string, boundary?: string, opts?: Omit<KeywordsOptions, 'boundary'>): Combinator<string>;
+export declare function word(str: string, opts: Omit<KeywordsOptions, 'boundary'>): Combinator<string>;
 /**
  * Create a keyword factory with a fixed word-boundary class. Use when many
  * keywords share the same boundary (e.g. CSS identifiers). For a single keyword,

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

@@ -1 +1 @@
-{"version":3,"file":"keywords.d.ts","sourceRoot":"","sources":["../../src/combinators/keywords.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAmD,MAAM,aAAa,CAAA;AAK9F,MAAM,MAAM,eAAe,GAAG;IAC5B,gCAAgC;IAChC,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAe,GAAG,UAAU,CAAC,MAAM,CAAC,CAE7E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,SAAe,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,UAAU,CAAC,MAAM,CAAC,CAErF;AAMD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,GAAE,eAAoB,GAAG,UAAU,CAAC,MAAM,CAAC,CA0CjG"}
+{"version":3,"file":"keywords.d.ts","sourceRoot":"","sources":["../../src/combinators/keywords.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAmD,MAAM,aAAa,CAAA;AAM9F,MAAM,MAAM,eAAe,GAAG;IAC5B,gCAAgC;IAChC,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;AAClH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;AAW9F;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,SAAe,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,UAAU,CAAC,MAAM,CAAC,CAErF;AAMD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,GAAE,eAAoB,GAAG,UAAU,CAAC,MAAM,CAAC,CA8DjG"}

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

@@ -1 +1 @@
-{"version":3,"file":"not.d.ts","sourceRoot":"","sources":["../../src/combinators/not.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAIpF;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CA0BrE"}
+{"version":3,"file":"not.d.ts","sourceRoot":"","sources":["../../src/combinators/not.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAIpF;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAwCrE"}

package/dist/combinators/peek.d.ts

@@ -0,0 +1,27 @@
+import type { Combinator } from '../types.ts';
+/**
+ * Positive lookahead. Succeeds (consuming nothing) when `combinator` matches at
+ * this position; fails when it doesn't. The mirror of `not()`.
+ *
+ *   // "a mixin reference, not a class selector": require the punctuation ahead,
+ *   // then let the real production consume it.
+ *   const mixinRef = sequence(peek(regex(/[.#]/)), mixinCall)
+ *
+ * WHY THIS EXISTS AS A PRIMITIVE (not `not(not(X))`):
+ *
+ * `not(not(X))` is behaviourally a positive lookahead, but `not()` reports
+ * `firstSet: any()` — it cannot know what it forbids — so `not(not(X))` reports
+ * `any()` too. An arm leading with it therefore POISONS its choice's first-char
+ * dispatch (`analyzeGating` flags it as the `double-not` anti-pattern), and among
+ * sibling arms that share a first char the hand-rolled gate miscompiles.
+ *
+ * `peek(X)` carries X's first-set instead, so a leading `peek()` GATES its arm:
+ * `choice(sequence(peek(regex(/[.#]/)), …), …)` still emits O(1) dispatch.
+ *
+ * The first-set is exact only when X is NON-NULLABLE. A nullable `peek(X)`
+ * succeeds on the empty string, so it constrains no first character at all — it
+ * reports `any()`, the sound over-approximation. (Same rule the sequence
+ * first-set uses; see `isPositiveLookahead` in `first-set.ts`.)
+ */
+export declare function peek(combinator: Combinator<unknown>): Combinator<null>;
+//# sourceMappingURL=peek.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"peek.d.ts","sourceRoot":"","sources":["../../src/combinators/peek.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAIpF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAkCtE"}