parseman 0.31.0 → 0.32.0

package/dist/index.js

@@ -87,10 +87,13 @@ function matchesEmpty(p, seen = /* @__PURE__ */ new Set()) {
       return true;
   }
 }
+function isZeroWidthAssertion(p) {
+  return p._def.tag === "not";
+}
 function sequenceFirstSet(parsers) {
   let fs = empty();
   for (const p of parsers) {
-    fs = union(fs, p._meta.firstSet);
+    if (!isZeroWidthAssertion(p)) fs = union(fs, p._meta.firstSet);
     if (!matchesEmpty(p)) return fs;
   }
   return fs;
@@ -120,7 +123,7 @@ function firstSetOf(p, seen = /* @__PURE__ */ new Set()) {
     case "sequence": {
       let out = empty();
       for (const term of d.parsers) {
-        out = union(out, fs(term));
+        if (!isZeroWidthAssertion(term)) out = union(out, fs(term));
         if (!matchesEmpty(term)) return out;
       }
       return out;
@@ -408,9 +411,9 @@ var SPACE_RANGES = [
   [12288, 12288],
   [65279, 65279]
 ];
-function shorthandRanges(ch) {
-  if (ch === "d") return [[48, 57]];
-  if (ch === "s") return SPACE_RANGES;
+function shorthandRanges(ch2) {
+  if (ch2 === "d") return [[48, 57]];
+  if (ch2 === "s") return SPACE_RANGES;
   return [[48, 57], [65, 90], [97, 122], [95, 95]];
 }
 function readUnicodeEscape(body, i) {
@@ -423,9 +426,9 @@ function parseClassRanges(body) {
   const ranges = [];
   let i = 0;
   const readAtom = () => {
-    const ch = body[i];
-    if (ch === void 0) return null;
-    if (ch === "\\") {
+    const ch2 = body[i];
+    if (ch2 === void 0) return null;
+    if (ch2 === "\\") {
       const uni = readUnicodeEscape(body, i);
       if (uni) {
         i = uni.next;
@@ -439,8 +442,8 @@ function parseClassRanges(body) {
       if (e >= "a" && e <= "z" || e >= "A" && e <= "Z") return null;
       return { cp: e.codePointAt(0) };
     }
-    i += ch.length;
-    return { cp: ch.codePointAt(0) };
+    i += ch2.length;
+    return { cp: ch2.codePointAt(0) };
   };
   while (i < body.length) {
     const lo = readAtom();
@@ -507,12 +510,35 @@ function shortScanner(source, flags) {
     return minOne && end === pos ? null : end;
   };
 }
+function asciiCaseFold(fs) {
+  if (fs.kind !== "ranges") return fs;
+  const ranges = fs.ranges.map((r) => ({ lo: r.lo, hi: r.hi }));
+  const add = (lo, hi) => {
+    if (lo <= hi) ranges.push({ lo, hi });
+  };
+  for (const r of fs.ranges) {
+    const uLo = Math.max(r.lo, 65), uHi = Math.min(r.hi, 90);
+    add(uLo + 32, uHi + 32);
+    const lLo = Math.max(r.lo, 97), lHi = Math.min(r.hi, 122);
+    add(lLo - 32, lHi - 32);
+  }
+  ranges.sort((a, b) => a.lo - b.lo);
+  const merged = [];
+  for (const r of ranges) {
+    const last = merged[merged.length - 1];
+    if (last && r.lo <= last.hi + 1) last.hi = Math.max(last.hi, r.hi);
+    else merged.push({ lo: r.lo, hi: r.hi });
+  }
+  return { kind: "ranges", ranges: merged };
+}
 function regex(pattern, flags = "") {
   const source = typeof pattern === "string" ? pattern : pattern.source;
   const resolvedFlags = typeof pattern === "string" ? flags : pattern.flags;
   const anchored = new RegExp(source, "y" + resolvedFlags.replace(/[gy]/g, ""));
   const scan = shortScanner(source, resolvedFlags);
-  const { firstSet: firstSet2, canMatchNewline } = (firstSetAnalyzer ?? permissiveFirstSet)(source);
+  const raw = (firstSetAnalyzer ?? permissiveFirstSet)(source);
+  const firstSet2 = !resolvedFlags.includes("i") ? raw.firstSet : resolvedFlags.includes("u") || resolvedFlags.includes("v") ? any() : asciiCaseFold(raw.firstSet);
+  const canMatchNewline = raw.canMatchNewline;
   const meta = { firstSet: firstSet2, canMatchNewline, isTrivia: false };
   return {
     _tag: "regex",
@@ -567,8 +593,8 @@ function parseRegex(src) {
   const parseSeq = () => {
     const parts = [];
     while (i < src.length) {
-      const ch = src[i];
-      if (ch === "|" || ch === ")") break;
+      const ch2 = src[i];
+      if (ch2 === "|" || ch2 === ")") break;
       parts.push(parseQuantified());
     }
     if (parts.length === 0) return EMPTY2;
@@ -576,18 +602,18 @@ function parseRegex(src) {
   };
   const parseQuantified = () => {
     const atom = parseAtom();
-    const ch = src[i];
+    const ch2 = src[i];
     let min = null;
-    if (ch === "*") {
+    if (ch2 === "*") {
       min = 0;
       i++;
-    } else if (ch === "+") {
+    } else if (ch2 === "+") {
       min = 1;
       i++;
-    } else if (ch === "?") {
+    } else if (ch2 === "?") {
       min = 0;
       i++;
-    } else if (ch === "{") {
+    } else if (ch2 === "{") {
       min = parseBraceQuantifier();
     }
     if (min === null) return atom;
@@ -603,8 +629,8 @@ function parseRegex(src) {
     return Number.parseInt(m[1], 10);
   };
   const parseAtom = () => {
-    const ch = src[i];
-    switch (ch) {
+    const ch2 = src[i];
+    switch (ch2) {
       case "(":
         return parseGroup();
       case "[":
@@ -625,8 +651,8 @@ function parseRegex(src) {
         return charNode(fromRange(123, 123), false);
       // a `{` with nothing to quantify is a literal brace
       default:
-        i += ch.length;
-        return charNode(fromRange(ch.codePointAt(0), ch.codePointAt(0)), ch === "\n");
+        i += ch2.length;
+        return charNode(fromRange(ch2.codePointAt(0), ch2.codePointAt(0)), ch2 === "\n");
     }
   };
   const parseGroup = () => {
@@ -1066,8 +1092,8 @@ function choice(...args) {
           }
         }
         if (idx >= 0) {
-          const gate = gates[idx];
-          if (gate && !gate(ctx.state)) {
+          const gate2 = gates[idx];
+          if (gate2 && !gate2(ctx.state)) {
             return { ok: false, expected: deriveExpected(parsers[idx]), span: { start: pos, end: pos } };
           }
           const result = parsers[idx].parse(input, pos, ctx);
@@ -1413,11 +1439,11 @@ function tryFastLabeledScan(input, cur, trivia2) {
 function recordTriviaChunks(ctx, chunks) {
   const kinds = ctx.triviaKindLabels;
   const mask = ctx._triviaCaptureMask;
-  for (const ch of chunks) {
-    pushTriviaLogEntry(ctx, ch.start, ch.end, kinds ? ch.kindIndex : void 0);
+  for (const ch2 of chunks) {
+    pushTriviaLogEntry(ctx, ch2.start, ch2.end, kinds ? ch2.kindIndex : void 0);
     if (ctx.captureTrivia && (ctx._cstBuf !== void 0 || ctx._cstTriviaLog !== void 0)) {
-      if (mask === void 0 || kinds === void 0 || (mask & 1 << ch.kindIndex) !== 0) {
-        pushCstTriviaEntry(ctx, ch.start, ch.end, kinds ? ch.kindIndex : void 0);
+      if (mask === void 0 || kinds === void 0 || (mask & 1 << ch2.kindIndex) !== 0) {
+        pushCstTriviaEntry(ctx, ch2.start, ch2.end, kinds ? ch2.kindIndex : void 0);
       }
     }
   }
@@ -2193,6 +2219,12 @@ function rules(a, b) {
       if (rule && !rule._meta.isTrivia) rule._meta.grammarTrivia = options.trivia;
     }
   }
+  if (options?.scanSkip != null) {
+    for (const key of Object.keys(definitions)) {
+      const rule = cache[key];
+      if (rule && !rule._meta.isTrivia) rule._meta.grammarScanSkip = options.scanSkip;
+    }
+  }
   for (const key of Object.keys(definitions)) {
     markUnusedValues(cache[key]);
   }
@@ -2675,9 +2707,11 @@ function parse(combinator, input, opts = {}) {
   const _errors = opts.recover ? [] : void 0;
   const _probe = opts.recover ? { offset: input.length, best: null } : void 0;
   const grammarTrivia = combinator._meta.grammarTrivia;
+  const grammarScanSkip = combinator._meta.grammarScanSkip;
   const ctx = {
     trackLines,
     ...grammarTrivia !== void 0 ? { trivia: grammarTrivia, ...grammarTrivia._meta.triviaKindLabels ? { triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {} } : {},
+    ...grammarScanSkip !== void 0 ? { scanSkip: grammarScanSkip } : {},
     ..._errors !== void 0 ? { _errors } : {},
     ..._probe !== void 0 ? { _probe } : {}
   };
@@ -2786,6 +2820,413 @@ function leaf(root, fn) {
   };
 }
 
+// src/version.ts
+var PARSEMAN_VERSION = "0.32.0";
+
+// src/analysis/gating.ts
+var isAny = (fs) => fs.kind === "any";
+function intersects2(a, b) {
+  if (a.kind === "any" || b.kind === "any") return true;
+  if (a.kind === "empty" || b.kind === "empty") return false;
+  for (const ra of a.ranges) for (const rb of b.ranges) if (ra.lo <= rb.hi && rb.lo <= ra.hi) return true;
+  return false;
+}
+function intersection(a, b) {
+  if (a.kind === "any") return b;
+  if (b.kind === "any") return a;
+  if (a.kind === "empty" || b.kind === "empty") return { kind: "empty" };
+  const ranges = [];
+  for (const ra of a.ranges) for (const rb of b.ranges) {
+    const lo = Math.max(ra.lo, rb.lo);
+    const hi = Math.min(ra.hi, rb.hi);
+    if (lo <= hi) ranges.push({ lo, hi });
+  }
+  return ranges.length === 0 ? { kind: "empty" } : { kind: "ranges", ranges };
+}
+function combine(sets) {
+  let acc = { kind: "empty" };
+  for (const s of sets) {
+    if (s.kind === "any") return { kind: "any" };
+    if (s.kind === "empty") continue;
+    acc = acc.kind === "ranges" ? { kind: "ranges", ranges: [...acc.ranges, ...s.ranges] } : s;
+  }
+  return acc;
+}
+var ch = (c) => c >= 32 && c < 127 ? `'${String.fromCharCode(c)}'` : `\\u${c}`;
+function firstSetToString(fs) {
+  if (fs.kind === "any") return "ANY";
+  if (fs.kind === "empty") return "(empty)";
+  return fs.ranges.map((r) => r.lo === r.hi ? ch(r.lo) : `${ch(r.lo)}-${ch(r.hi)}`).join(",");
+}
+var ruleNameOf = (p) => p._ruleName;
+var SUGGESTIONS = {
+  "broad-recognizer": "if this arm leads with a keyword regex, use word('kw', boundary) / keywords([...]) \u2014 they expose an EXACT, gating first-set and lower to the same charCodeAt scan. A genuine scanTo fallback is fine; accept it in the gating snapshot if intentional.",
+  "leading-not": "let the arm lead with its actual consuming terminal (first-sets gate it automatically); keep not(...) only as a TRAILING boundary. Do not hand-roll not(not(...)) to fake gating.",
+  "nullable-prefix": "a leading optional/many lets a later, broad term start the arm. Split the empty case into its own arm, or gate on the prefix first char.",
+  "cross-artifact-ref": "parseman >=0.32.0 resolves a g.Foo ref first-set at fuse time; if still ANY the target rule is itself ungated \u2014 analyze it and give it a concrete non-nullable lead.",
+  "opaque-wrapper": "this wrapper (guard/withCtx/recover) contributes no first char; put a concrete leading terminal before it.",
+  "ref-cycle": "a recursive ref resolved to ANY; ensure the recursion has a concrete terminal lead on the base case."
+};
+function classifyBroadArm(arm) {
+  const seen = /* @__PURE__ */ new Set();
+  const walk2 = (p) => {
+    if (seen.has(p)) return { cause: "ref-cycle", detail: "ref cycle" };
+    seen.add(p);
+    const d = p._def;
+    switch (d.tag) {
+      case "literal":
+      case "regex":
+      case "keywords":
+        return isAny(p._meta.firstSet) ? { cause: "broad-recognizer", detail: `broad recognizer (${d.tag})` } : null;
+      case "not":
+        return { cause: "leading-not", detail: "leading not(...) (first-set ANY)" };
+      case "scanTo":
+        return { cause: "broad-recognizer", detail: "scanTo (any first char)" };
+      // `guard` (the `gate()` state predicate) has a genuinely-`any` first-set of
+      // its own — it is the poison. `withCtx`/`recover` FORWARD their inner
+      // first-set (see firstSetOf), so a broad result comes from the inner parser:
+      // walk into it for a precise cause.
+      case "guard":
+        return { cause: "opaque-wrapper", detail: `opaque wrapper (${d.tag})` };
+      // attempt/withCtx/recover FORWARD their inner first-set (transparent for
+      // dispatch), so a broad result comes from the inner parser — walk into it.
+      case "attempt":
+      case "withCtx":
+      case "recover":
+        return walk2(d.parser);
+      case "lazy": {
+        const name = p._ruleName;
+        try {
+          const inner = walk2(d.thunk());
+          if (name !== void 0) return inner ? { cause: "cross-artifact-ref", detail: `via ref g.${name} \u2192 ${inner.detail}` } : null;
+          return inner;
+        } catch {
+          return { cause: "cross-artifact-ref", detail: `unresolved ref${name ? ` g.${name}` : ""}` };
+        }
+      }
+      case "optional":
+      case "many": {
+        const inner = walk2(d.parser);
+        return { cause: "nullable-prefix", detail: inner ? `nullable prefix \u2192 ${inner.detail}` : "nullable prefix to broad term" };
+      }
+      case "oneOrMore":
+      case "transform":
+      case "label":
+      case "field":
+      case "trivia":
+      case "token":
+      case "leaf":
+      case "node":
+      case "grammar":
+      case "expect":
+        return walk2(d.parser);
+      case "skip":
+        return walk2(d.main);
+      case "sequence": {
+        let sawNullablePrefix = false;
+        for (const t of d.parsers) {
+          if (t._def.tag === "not") {
+            sawNullablePrefix = true;
+            continue;
+          }
+          if (isAny(firstSetOf(t))) {
+            const inner = walk2(t);
+            if (sawNullablePrefix)
+              return { cause: "nullable-prefix", detail: inner ? `nullable prefix \u2192 ${inner.detail}` : "nullable prefix to broad term" };
+            return inner ?? { cause: "broad-recognizer", detail: "sequence leading term is broad" };
+          }
+          if (matchesEmpty(t)) {
+            sawNullablePrefix = true;
+            continue;
+          }
+          return null;
+        }
+        return { cause: "broad-recognizer", detail: "sequence of only nullable/zero-width terms" };
+      }
+      case "choice": {
+        for (const a of d.parsers) {
+          const r = walk2(a);
+          if (r) return { cause: r.cause, detail: `choice arm \u2192 ${r.detail}` };
+        }
+        return null;
+      }
+      default:
+        return { cause: "broad-recognizer", detail: `unmodeled construct (${d.tag})` };
+    }
+  };
+  return walk2(arm) ?? { cause: "broad-recognizer", detail: "broad (cause not localized)" };
+}
+function peelToLeading(arm) {
+  let d = arm._def;
+  let cur = arm;
+  for (; ; ) {
+    if (d.tag === "node" || d.tag === "grammar" || d.tag === "transform" || d.tag === "label" || d.tag === "attempt") {
+      cur = d.parser;
+      d = cur._def;
+      continue;
+    }
+    break;
+  }
+  if (d.tag === "sequence" && d.parsers.length >= 1) return d.parsers[0];
+  return cur;
+}
+var KEYWORD_REGEX_RE = /^\^?[@#.-]?[A-Za-z][\w-]*(\(\?![^)]*\))?\$?$/;
+function detectAntiPatterns(rule, arms) {
+  const out = [];
+  arms.forEach((arm, i) => {
+    const lead = peelToLeading(arm);
+    const ld = lead._def;
+    if (ld.tag === "not") {
+      const inner = ld.parser;
+      if (inner._def.tag === "not") {
+        out.push({
+          kind: "double-not",
+          rule,
+          armIndex: i,
+          message: "not(not(...)) hand-rolls automatic first-char gating and MISCOMPILES among shared-first-char sibling arms (its first-set is ANY, poisoning dispatch). Remove it; let the arm lead with its consuming terminal, or use word()/keywords() for an exact first-set."
+        });
+      } else {
+        out.push({
+          kind: "leading-not",
+          rule,
+          armIndex: i,
+          message: "a leading not(...) on a choice arm hand-rolls gating and poisons the choice first-set (not() is ANY). Reorder so a consuming terminal leads; keep not(...) as a TRAILING boundary only."
+        });
+      }
+    }
+    if (ld.tag === "regex" && KEYWORD_REGEX_RE.test(ld.source)) {
+      out.push({
+        kind: "keyword-regex",
+        rule,
+        armIndex: i,
+        message: `regex(/${ld.source}/) leads this arm but is a keyword \u2014 use word('\u2026', boundary) / keywords([\u2026]) for an EXACT resolvable first-set (they lower to the same charCodeAt scan).`
+      });
+    }
+  });
+  return out;
+}
+function analyzeGating(entry, opts) {
+  const raw = [];
+  const antiPatterns = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (p, enclosingRule) => {
+    if (visited.has(p)) return;
+    visited.add(p);
+    const d = p._def;
+    const rule = ruleNameOf(p) ?? enclosingRule;
+    if (d.tag === "choice") {
+      raw.push({ g: analyzeChoice(p, d, rule), rule });
+      antiPatterns.push(...detectAntiPatterns(rule, d.parsers));
+    }
+    const rec = d;
+    const kids = [];
+    if (Array.isArray(rec.parsers)) kids.push(...rec.parsers);
+    for (const k of ["parser", "main", "skipped", "separator", "sentinel"])
+      if (rec[k]) kids.push(rec[k]);
+    if (Array.isArray(rec.skip)) kids.push(...rec.skip);
+    if (d.tag === "lazy") {
+      try {
+        kids.push(d.thunk());
+      } catch {
+      }
+    }
+    for (const k of kids) visit(k, rule);
+  };
+  visit(entry, ruleNameOf(entry) ?? "<entry>");
+  const perRule = /* @__PURE__ */ new Map();
+  for (const r of raw) perRule.set(r.rule, (perRule.get(r.rule) ?? 0) + 1);
+  const seenInRule = /* @__PURE__ */ new Map();
+  const accept = new Set(opts?.accept ?? []);
+  const usedAccept = /* @__PURE__ */ new Set();
+  const choices = raw.map(({ g, rule }) => {
+    const n = seenInRule.get(rule) ?? 0;
+    seenInRule.set(rule, n + 1);
+    const id = (perRule.get(rule) ?? 1) === 1 ? rule : `${rule}#${n}`;
+    const isAccepted = g.gates === "no" && accept.has(id);
+    if (isAccepted) usedAccept.add(id);
+    return { ...g, id, accepted: isAccepted };
+  });
+  const gated = choices.filter((c) => c.gates === "yes").length;
+  const recoverable = choices.filter((c) => c.gates === "recoverable").length;
+  const ungated = choices.filter((c) => c.gates === "no" && !c.accepted);
+  const accepted = choices.filter((c) => c.gates === "no" && c.accepted);
+  const acceptedUnused = [...accept].filter((id) => !usedAccept.has(id));
+  return { totalChoices: choices.length, gated, recoverable, ungated, accepted, acceptedUnused, choices, antiPatterns };
+}
+function analyzeChoice(p, d, rule) {
+  const arms = d.parsers;
+  const shallow = arms.map((a) => a._meta.firstSet);
+  const deep = arms.map((a) => firstSetOf(a));
+  const anyArms = deep.map((fs, index) => ({ fs, index })).filter((x) => isAny(x.fs)).map(({ index }) => {
+    const { cause, detail } = classifyBroadArm(arms[index]);
+    return { index, cause, detail, shallowAnyOnly: false, suggestion: SUGGESTIONS[cause] };
+  });
+  const overlaps = [];
+  for (let i = 0; i < deep.length; i++)
+    for (let j = i + 1; j < deep.length; j++)
+      if (!isAny(deep[i]) && !isAny(deep[j]) && intersects2(deep[i], deep[j]))
+        overlaps.push({
+          a: i,
+          b: j,
+          on: intersection(deep[i], deep[j]),
+          suggestion: "arms share a first char \u2014 left-factor. parseman auto-detects the sharedPrefix strategy for bare sequences (choice.ts); make the arms bare sequences with a common leading terminal, or restructure."
+        });
+  let gates;
+  if (d.disjoint) gates = "yes";
+  else if (anyArms.length === 0 && overlaps.length === 0) gates = "recoverable";
+  else gates = "no";
+  return {
+    rule,
+    strategy: d.strategy?.tag ?? "firstMatch",
+    gates,
+    combinedFirstSet: { shallow: combine(shallow), deep: combine(deep) },
+    anyArms,
+    overlaps
+  };
+}
+function formatGatingWarnings(report) {
+  const lines = [];
+  for (const c of report.ungated) {
+    lines.push(`parseman gating: choice @ ${c.id} is UNGATED [${c.strategy}] \u2014 no first-char dispatch; every position speculatively enters doomed arms.`);
+    for (const a of c.anyArms)
+      lines.push(`  \xB7 arm[${a.index}] first-set ANY (${a.cause}): ${a.detail}
+    fix: ${a.suggestion}`);
+    for (const o of c.overlaps)
+      lines.push(`  \xB7 arm[${o.a}] \u2229 arm[${o.b}] overlap on ${firstSetToString(o.on)}
+    fix: ${o.suggestion}`);
+    lines.push(`    (intentional? accept it in the gating snapshot: { accept: ['${c.id}'] }.)`);
+  }
+  for (const ap of report.antiPatterns)
+    lines.push(`parseman anti-pattern [${ap.kind}] @ ${ap.rule} arm[${ap.armIndex}]: ${ap.message}`);
+  return lines;
+}
+
+// src/combinators/scanTo.ts
+function resolveScanSkip(explicitSkip, raw, ctx) {
+  if (raw) return [];
+  const trivia2 = ctx.trivia;
+  const ambient = ctx.scanSkip;
+  if (!trivia2 && !ambient) return explicitSkip;
+  const out = [];
+  if (trivia2) out.push(trivia2);
+  if (ambient) out.push(...ambient);
+  out.push(...explicitSkip);
+  return out;
+}
+function scanTo(sentinel, { skip: skip2, raw = false, orEOF = false } = {}) {
+  const meta = {
+    firstSet: any(),
+    canMatchNewline: true,
+    isTrivia: false
+  };
+  const explicitSkip = skip2 ?? [];
+  return {
+    _tag: "scanTo",
+    _meta: meta,
+    _def: { tag: "scanTo", sentinel, skip: explicitSkip, raw, orEOF },
+    parse(input, pos, ctx) {
+      let cur = pos;
+      const skip3 = resolveScanSkip(explicitSkip, raw, ctx);
+      const probeCtx = {
+        trackLines: ctx.trackLines,
+        state: ctx.state,
+        ...ctx._errors !== void 0 ? { _errors: ctx._errors } : {}
+      };
+      const emit2 = (end) => {
+        if (end > pos && cstCaptureActive(ctx)) {
+          const leaf2 = { _tag: "leaf", value: input.slice(pos, end), span: { start: pos, end } };
+          pushCstLeaf(ctx, leaf2);
+        }
+      };
+      while (cur < input.length) {
+        const s = sentinel.parse(input, cur, probeCtx);
+        if (s.ok) {
+          emit2(cur);
+          return { ok: true, value: input.slice(pos, cur), span: { start: pos, end: cur } };
+        }
+        let advanced = false;
+        for (const skipper of skip3) {
+          const r = skipper.parse(input, cur, probeCtx);
+          if (r.ok && r.span.end > cur) {
+            cur = r.span.end;
+            advanced = true;
+            break;
+          }
+        }
+        if (!advanced) cur++;
+      }
+      if (orEOF) {
+        emit2(cur);
+        return { ok: true, value: input.slice(pos, cur), span: { start: pos, end: cur } };
+      }
+      const sentDef = sentinel._def;
+      const expected = sentDef.tag === "literal" ? [JSON.stringify(sentDef.value)] : ["sentinel"];
+      return { ok: false, expected, span: { start: pos, end: cur } };
+    }
+  };
+}
+function balanced(open, close, options = {}) {
+  const ownSkip = options.skip ?? [];
+  const combi = buildBalancedInterior(open, close, ownSkip);
+  if (options.raw) return combi;
+  const eagerParse = combi.parse.bind(combi);
+  const cache = /* @__PURE__ */ new Map();
+  combi._balancedAmbient = { open, close, ownSkip };
+  combi.parse = (input, pos, ctx) => {
+    const amb = ctx.scanSkip;
+    if (!amb || amb.length === 0) return eagerParse(input, pos, ctx);
+    let interior = cache.get(amb);
+    if (!interior) {
+      interior = buildBalancedInterior(open, close, [...amb, ...ownSkip]);
+      cache.set(amb, interior);
+    }
+    return interior.parse(input, pos, ctx);
+  };
+  return combi;
+}
+function buildBalancedInterior(open, close, skips) {
+  const self = ref();
+  const stop = /* @__PURE__ */ new Set([open, close]);
+  let bounded = true;
+  for (const sk of skips) {
+    const cs = firstSetClassChars(sk);
+    if (cs === null) {
+      bounded = false;
+      break;
+    }
+    for (const ch2 of cs) stop.add(ch2);
+  }
+  const cls = [...stop].map(escapeClassChar).join("");
+  const content = bounded ? regex(new RegExp(`[^${cls}]+`)) : regex(new RegExp(`[^${escapeClassChar(open)}${escapeClassChar(close)}]`));
+  const inner = many(choice(self, ...skips, content));
+  const combi = transform(
+    sequence(literal(open), inner, expect(literal(close))),
+    // parts: strings (content/self) or arrays (a sequence-shaped skip) or a
+    // ParseError (recovered close). `c` is the close string or a ParseError.
+    ([o, parts, c]) => o + parts.map((p) => typeof p === "string" ? p : Array.isArray(p) ? p.join("") : "").join("") + (typeof c === "string" ? c : "")
+  );
+  if (combi._def.tag === "transform") {
+    combi._def.fnSrc = '([o, parts, c]) => o + parts.map(p => typeof p === "string" ? p : Array.isArray(p) ? p.join("") : "").join("") + (typeof c === "string" ? c : "")';
+    combi._def.recognitionOnly = true;
+  }
+  self.define(combi);
+  return combi;
+}
+function firstSetClassChars(c) {
+  const fs = c._meta.firstSet;
+  if (fs.kind === "empty") return [];
+  if (fs.kind !== "ranges") return null;
+  const out = [];
+  for (const { lo, hi } of fs.ranges) {
+    if (hi - lo > 8) return null;
+    for (let cp = lo; cp <= hi; cp++) out.push(String.fromCodePoint(cp));
+  }
+  return out;
+}
+function escapeClassChar(ch2) {
+  return ch2.replace(/[\\\]^-]/g, "\\$&");
+}
+
 // src/compiler/grammar-coverage-ids.ts
 function children(def, winners) {
   switch (def.tag) {
@@ -2898,16 +3339,16 @@ function literalCodePoints(frag) {
   const out = [];
   let i = 0;
   while (i < frag.length) {
-    const ch = frag[i];
-    if (ch === "\\") {
+    const ch2 = frag[i];
+    if (ch2 === "\\") {
       const e = frag[i + 1];
       if (e === void 0) return null;
       out.push(e in CLASS_ESCAPES ? CLASS_ESCAPES[e] : e.codePointAt(0));
       i += 2;
       continue;
     }
-    if (META.has(ch)) return null;
-    out.push(ch.codePointAt(0));
+    if (META.has(ch2)) return null;
+    out.push(ch2.codePointAt(0));
     i += 1;
   }
   return out.length ? out : null;
@@ -2986,8 +3427,8 @@ function parseSeqParts(source) {
   };
   let i = 0;
   while (i < source.length) {
-    const ch = source[i];
-    if (ch === "[") {
+    const ch2 = source[i];
+    if (ch2 === "[") {
       let k = i + 1;
       const neg = source[k] === "^";
       if (neg) k++;
@@ -3009,7 +3450,7 @@ function parseSeqParts(source) {
       i += runFrom(ranges, neg, i);
       continue;
     }
-    if (ch === "\\") {
+    if (ch2 === "\\") {
       const e = source[i + 1];
       if (e === "d" || e === "w" || e === "s") {
         flush();
@@ -3038,7 +3479,7 @@ function parseSeqParts(source) {
       } else lit.push(cp2);
       continue;
     }
-    if (ch === "(") {
+    if (ch2 === "(") {
       if (source[i + 1] !== "?" || source[i + 2] !== ":") return null;
       let k = i + 3;
       let depth = 1;
@@ -3087,9 +3528,9 @@ function parseSeqParts(source) {
       }
       continue;
     }
-    if (META.has(ch)) return null;
-    const cp = ch.codePointAt(0);
-    i += ch.length;
+    if (META.has(ch2)) return null;
+    const cp = ch2.codePointAt(0);
+    i += ch2.length;
     if (source[i] === "?") {
       flush();
       parts.push({ part: "lit", cps: [cp], optional: true });
@@ -3266,12 +3707,12 @@ function unwrapOuterGroup(source) {
     let i = 3;
     let ok = true;
     while (i < source.length && depth > 0) {
-      const ch = source[i];
-      if (ch === "\\") {
+      const ch2 = source[i];
+      if (ch2 === "\\") {
         i += 2;
         continue;
       }
-      if (ch === "[") {
+      if (ch2 === "[") {
         let j = i + 1;
         if (source[j] === "^") j++;
         while (j < source.length && source[j] !== "]") {
@@ -3285,8 +3726,8 @@ function unwrapOuterGroup(source) {
         i = j + 1;
         continue;
       }
-      if (ch === "(") depth++;
-      else if (ch === ")") depth--;
+      if (ch2 === "(") depth++;
+      else if (ch2 === ")") depth--;
       i++;
     }
     if (!ok || depth !== 0 || i !== source.length) break;
@@ -3301,12 +3742,12 @@ function splitTopLevelAlternation(source) {
   let last = 0;
   let i = 0;
   while (i < body.length) {
-    const ch = body[i];
-    if (ch === "\\") {
+    const ch2 = body[i];
+    if (ch2 === "\\") {
       i += 2;
       continue;
     }
-    if (ch === "[") {
+    if (ch2 === "[") {
       let j = i + 1;
       if (body[j] === "^") j++;
       while (j < body.length && body[j] !== "]") {
@@ -3317,18 +3758,18 @@ function splitTopLevelAlternation(source) {
       i = j + 1;
       continue;
     }
-    if (ch === "(") {
+    if (ch2 === "(") {
       depth++;
       i++;
       continue;
     }
-    if (ch === ")") {
+    if (ch2 === ")") {
       depth--;
       if (depth < 0) return null;
       i++;
       continue;
     }
-    if (ch === "|" && depth === 0) {
+    if (ch2 === "|" && depth === 0) {
       parts.push(body.slice(last, i));
       last = i + 1;
       i++;
@@ -3447,12 +3888,12 @@ function splitDelimArms(body) {
   let last = 0;
   let i = 0;
   while (i < body.length) {
-    const ch = body[i];
-    if (ch === "\\") {
+    const ch2 = body[i];
+    if (ch2 === "\\") {
       i += 2;
       continue;
     }
-    if (ch === "[") {
+    if (ch2 === "[") {
       let j = i + 1;
       if (body[j] === "^") j++;
       while (j < body.length && body[j] !== "]") {
@@ -3463,18 +3904,18 @@ function splitDelimArms(body) {
       i = j + 1;
       continue;
     }
-    if (ch === "(") {
+    if (ch2 === "(") {
       depth++;
       i++;
       continue;
     }
-    if (ch === ")") {
+    if (ch2 === ")") {
       depth--;
       if (depth < 0) return null;
       i++;
       continue;
     }
-    if (ch === "|" && depth === 0) {
+    if (ch2 === "|" && depth === 0) {
       arms.push(body.slice(last, i));
       last = i + 1;
     }
@@ -3526,12 +3967,12 @@ function parseDelimited(source) {
   let k = i + 3;
   let depth = 1;
   while (k < source.length && depth > 0) {
-    const ch = source[k];
-    if (ch === "\\") {
+    const ch2 = source[k];
+    if (ch2 === "\\") {
       k += 2;
       continue;
     }
-    if (ch === "[") {
+    if (ch2 === "[") {
       let j = k + 1;
       if (source[j] === "^") j++;
       while (j < source.length && source[j] !== "]") {
@@ -3542,8 +3983,8 @@ function parseDelimited(source) {
       k = j + 1;
       continue;
     }
-    if (ch === "(") depth++;
-    else if (ch === ")") depth--;
+    if (ch2 === "(") depth++;
+    else if (ch2 === ")") depth--;
     k++;
   }
   if (depth !== 0) return null;
@@ -4215,58 +4656,88 @@ function tryInlineDestructureTransform(src, valueVars) {
 
 // src/compiler/codegen.ts
 function leadingFirstSetRecipe(p, seen = /* @__PURE__ */ new Set()) {
-  if (seen.has(p)) return { concrete: empty(), refs: [] };
-  seen.add(p);
   const d = p._def;
+  if (d.tag === "lazy") {
+    const name = p._ruleName;
+    if (name !== void 0) return { alts: [[{ set: empty(), nullable: false, ref: name }]] };
+  }
+  if (seen.has(p)) return { alts: [[]] };
+  seen.add(p);
   const rec = (c) => leadingFirstSetRecipe(c, seen);
-  const merge2 = (a, b) => ({ concrete: union(a.concrete, b.concrete), refs: [...a.refs, ...b.refs] });
-  switch (d.tag) {
-    case "lazy": {
-      const name = p._ruleName;
-      if (name !== void 0) return { concrete: empty(), refs: [name] };
-      try {
-        return rec(d.thunk());
-      } catch {
-        return { concrete: any(), refs: [] };
+  const seg = (set, nullable2) => ({ set, nullable: nullable2 });
+  const forceNullable = (r) => ({ alts: r.alts.map((alt) => alt.map((s) => ({ ...s, nullable: true }))) });
+  const collapse = (r, nullable2) => {
+    let set = empty();
+    let hasRef = false;
+    for (const alt of r.alts) {
+      for (const s of alt) {
+        if (s.ref !== void 0) hasRef = true;
+        set = union(set, s.set);
+        if (!s.nullable) break;
       }
     }
-    case "literal":
-    case "regex":
-    case "keywords":
-      return { concrete: p._meta.firstSet, refs: [] };
-    case "choice": {
-      let out = { concrete: empty(), refs: [] };
-      for (const arm of d.parsers) out = merge2(out, rec(arm));
-      return out;
-    }
-    case "sequence": {
-      let out = { concrete: empty(), refs: [] };
-      for (const term of d.parsers) {
-        out = merge2(out, rec(term));
-        if (!matchesEmpty(term)) return out;
+    return seg(hasRef ? any() : set, nullable2);
+  };
+  const compute = () => {
+    switch (d.tag) {
+      case "lazy": {
+        try {
+          return rec(d.thunk());
+        } catch {
+          return { alts: [[seg(any(), false)]] };
+        }
       }
-      return out;
+      case "literal":
+      case "regex":
+      case "keywords":
+        return { alts: [[seg(p._meta.firstSet, matchesEmpty(p))]] };
+      case "choice": {
+        const alts = [];
+        for (const arm of d.parsers) alts.push(...rec(arm).alts);
+        return { alts };
+      }
+      case "sequence": {
+        const chain = [];
+        for (const term of d.parsers) {
+          if (!isZeroWidthAssertion(term)) {
+            const tr = rec(term);
+            if (tr.alts.length === 1) chain.push(...tr.alts[0]);
+            else chain.push(collapse(tr, matchesEmpty(term)));
+          }
+          if (!matchesEmpty(term)) return { alts: [chain] };
+        }
+        return { alts: [chain] };
+      }
+      // `many`/`optional` are skippable as a whole → their leading chars start the
+      // sequence but the chain must continue past them (force nullable). `oneOrMore`
+      // requires at least one repetition, so it is NOT made nullable here.
+      case "many":
+      case "optional":
+        return forceNullable(rec(d.parser));
+      case "oneOrMore":
+      case "transform":
+      case "label":
+      case "field":
+      case "trivia":
+      case "token":
+      case "leaf":
+      case "node":
+      case "grammar":
+      case "expect":
+        return rec(d.parser);
+      case "sepBy":
+        return rec(d.parser);
+      case "skip":
+        return rec(d.main);
+      // not / scanTo / guard / withCtx / recover / unknown → shallow set (safe).
+      default:
+        return { alts: [[seg(p._meta.firstSet, matchesEmpty(p))]] };
     }
-    case "oneOrMore":
-    case "many":
-    case "optional":
-    case "transform":
-    case "label":
-    case "field":
-    case "trivia":
-    case "token":
-    case "leaf":
-    case "node":
-    case "grammar":
-    case "expect":
-      return rec(d.parser);
-    case "sepBy":
-      return rec(d.parser);
-    case "skip":
-      return rec(d.main);
-    // not / scanTo / guard / withCtx / recover / unknown → shallow set (safe).
-    default:
-      return { concrete: p._meta.firstSet, refs: [] };
+  };
+  try {
+    return compute();
+  } finally {
+    seen.delete(p);
   }
 }
 var 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 }";
@@ -4462,16 +4933,19 @@ function ensureTriviaFn(ctx) {
   const savedIndent = ctx.indent;
   const savedFailLabel = ctx.failLabel;
   const savedTrivia = ctx.activeTrivia;
+  const savedScanSkip = ctx.activeScanSkip;
   const savedCapAsTrivia = ctx.capAsTrivia;
   ctx.indent = 2;
   ctx.failLabel = "_triv";
   ctx.capAsTrivia = true;
   ctx.activeTrivia = void 0;
+  ctx.activeScanSkip = void 0;
   const r = emit(trivia2, ctx, "_pos");
   ctx.indent = savedIndent;
   ctx.failLabel = savedFailLabel;
   ctx.capAsTrivia = savedCapAsTrivia;
   ctx.activeTrivia = savedTrivia;
+  ctx.activeScanSkip = savedScanSkip;
   ctx.namedFnDecls.push([
     `function ${fnName}(input, _pos, _ctx, _cap) {`,
     `  let _e = _pos`,
@@ -4749,7 +5223,7 @@ function emitKeywordsFast(def, ctx, pos) {
   const bodyInd = ind(ctx) + "  ";
   const tries = [];
   for (const w of def.words) {
-    const cps = Array.from(w, (ch) => ch.codePointAt(0));
+    const cps = Array.from(w, (ch2) => ch2.codePointAt(0));
     let shape = def.caseInsensitive ? { kind: "litFold", open: cps } : { kind: "seq", parts: [{ part: "lit", cps, optional: false }] };
     if (boundary) {
       shape = { kind: "lookahead", inner: shape, ranges: boundary.ranges, classNegated: boundary.negated, negative: true };
@@ -4942,7 +5416,7 @@ function canMatchEmptyAtStart(p) {
   const d = p._def;
   switch (d.tag) {
     case "regex":
-      return /(?:[*?]|\{0,|\{\d*,)/.test(d.source);
+      return regexMatchesEmpty(d.source, d.flags);
     case "optional":
       return true;
     case "many":
@@ -4994,10 +5468,10 @@ function emitDisjointArm(p, ctx, pos, valV, endV, coverageId) {
 }
 function emitDisjointArmGated(def, i, ctx, pos, valV, endV, coverageId) {
   const p = def.parsers[i];
-  const gate = def.gates[i];
-  if (!gate) return emitDisjointArm(p, ctx, pos, valV, endV, coverageId);
+  const gate2 = def.gates[i];
+  if (!gate2) return emitDisjointArm(p, ctx, pos, valV, endV, coverageId);
   const gateIdx = ctx.mapFns.length;
-  ctx.mapFns.push(gate);
+  ctx.mapFns.push(gate2);
   ctx.mapFnSrcs.push(def.gateSrcs?.[i] ?? null);
   const gateCond = `${mfRef(ctx)}[${gateIdx}](_ctx.state)`;
   const stmts = [`${ind(ctx)}if (${gateCond}) {`];
@@ -5155,7 +5629,7 @@ function emitFirstMatch(def, ctx, pos, coverageBase, preStmts, armGuardPrefix) {
   if (preStmts) stmts.push(...preStmts);
   for (let i = 0; i < def.parsers.length; i++) {
     const p = def.parsers[i];
-    const gate = def.gates[i];
+    const gate2 = def.gates[i];
     const autoNot = def.autoNot[i];
     const atStart = failsAtStart(p);
     const staticFx = armStaticExpected(ctx, p);
@@ -5167,9 +5641,9 @@ function emitFirstMatch(def, ctx, pos, coverageBase, preStmts, armGuardPrefix) {
     })();
     const fsGuard = armGuardPrefix === void 0 ? baseFsGuard : baseFsGuard === null ? armGuardPrefix : `${armGuardPrefix} && (${baseFsGuard})`;
     let gateCond = null;
-    if (gate) {
+    if (gate2) {
       const gateIdx = ctx.mapFns.length;
-      ctx.mapFns.push(gate);
+      ctx.mapFns.push(gate2);
       ctx.mapFnSrcs.push(def.gateSrcs?.[i] ?? null);
       gateCond = `${mfRef(ctx)}[${gateIdx}](_ctx.state)`;
     }
@@ -5586,10 +6060,15 @@ function emitScanTo(def, ctx, pos) {
   const probeCtx = { ...ctx, capturing: false, noHoist: true };
   const { stmts: sentStmts, okVar: sentOk } = emitFallible(def.sentinel, probeCtx, curV);
   stmts.push(...sentStmts, `${ind(ctx)}if (${sentOk}) { ${foundV} = true; break }`);
-  if (def.skip.length > 0) {
+  const effectiveSkip = def.raw ? def.skip : [
+    ...ctx.activeTrivia ? [ctx.activeTrivia] : [],
+    ...ctx.activeScanSkip ?? [],
+    ...def.skip
+  ];
+  if (effectiveSkip.length > 0) {
     const advV = v(ctx, "_stadv");
     stmts.push(`${ind(ctx)}let ${advV} = false`);
-    for (const skipper of def.skip) {
+    for (const skipper of effectiveSkip) {
       const { stmts: skStmts, okVar: skOk, endVar: skEnd } = emitFallible(skipper, probeCtx, curV);
       stmts.push(
         `${ind(ctx)}if (!${advV}) {`,
@@ -6059,6 +6538,24 @@ function emit(p, ctx, pos) {
   return instrument(dispatch());
 }
 function emitDispatch(p, ctx, pos) {
+  const bal = p._balancedAmbient;
+  if (bal && ctx.activeScanSkip && ctx.activeScanSkip.length > 0 && !ctx.balancedRebuildStack?.has(p)) {
+    const interior = buildBalancedInterior(bal.open, bal.close, [...ctx.activeScanSkip, ...bal.ownSkip]);
+    markUnusedValues(interior);
+    if (ctx.lazyUsage) {
+      const u = analyzeLazyUsage(interior);
+      for (const [k, n] of u.counts) ctx.lazyUsage.counts.set(k, (ctx.lazyUsage.counts.get(k) ?? 0) + n);
+      for (const k of u.recursive) ctx.lazyUsage.recursive.add(k);
+      for (const [k, s] of u.sizes) ctx.lazyUsage.sizes.set(k, s);
+    }
+    const stack = ctx.balancedRebuildStack ?? (ctx.balancedRebuildStack = /* @__PURE__ */ new Set());
+    stack.add(p);
+    try {
+      return emit(interior, ctx, pos);
+    } finally {
+      stack.delete(p);
+    }
+  }
   const def = p._def;
   switch (def.tag) {
     case "literal":
@@ -6480,9 +6977,36 @@ function ruleDependencies(ruleMap) {
   }
   return deps;
 }
+function resolveGatingLevel(opt) {
+  const explicit = typeof opt === "string" ? opt : opt?.level;
+  if (explicit !== void 0) return explicit;
+  const env = typeof process !== "undefined" ? process.env?.PARSEMAN_GATING : void 0;
+  if (env === "off" || env === "warn" || env === "error") return env;
+  return "warn";
+}
+function runGatingDiagnostic(combinator, opt) {
+  const level = resolveGatingLevel(opt);
+  if (level === "off") return void 0;
+  const accept = opt !== null && typeof opt === "object" ? opt.accept : void 0;
+  let report;
+  try {
+    report = analyzeGating(combinator, accept ? { accept } : void 0);
+  } catch {
+    return void 0;
+  }
+  const lines = formatGatingWarnings(report);
+  if (lines.length > 0) {
+    if (level === "error") throw new Error(`parseman: ${report.ungated.length} ungated hot choice(s) / ${report.antiPatterns.length} anti-pattern(s)
+${lines.join("\n")}`);
+    for (const l of lines) console.warn(l);
+  }
+  return report;
+}
 function compile(combinator, mapFnSources, opts) {
+  const gatingReport = runGatingDiagnostic(combinator, opts?.gating);
   markUnusedValues(combinator);
   const grammarTrivia = combinator._meta.grammarTrivia;
+  const grammarScanSkip = combinator._meta.grammarScanSkip;
   const ctx = {
     vars: 0,
     indent: 1,
@@ -6504,7 +7028,8 @@ function compile(combinator, mapFnSources, opts) {
     recovery: opts?.recovery ?? false,
     ...opts?.coverage ? { coverage: { plan: buildGrammarPlan(combinator), entry: combinator } } : {},
     lazyUsage: analyzeLazyUsage(combinator),
-    ...grammarTrivia ? { activeTrivia: grammarTrivia, triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {}
+    ...grammarTrivia ? { activeTrivia: grammarTrivia, triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {},
+    ...grammarScanSkip ? { activeScanSkip: grammarScanSkip } : {}
   };
   const r = emit(combinator, ctx, "_pos");
   const coverageRootRuleId = ctx.coverage?.plan.rules.get(combinator);
@@ -6568,6 +7093,7 @@ function compile(combinator, mapFnSources, opts) {
     source,
     inlineExpression,
     ...ctx.coverage === void 0 ? {} : { coverageDefinitions: ctx.coverage.plan.definitions },
+    ...gatingReport === void 0 ? {} : { gating: gatingReport },
     parse(input, pos = 0) {
       return fn(input, pos, ctx.runtimeParsers, ctx.mapFns, ctx.buildFns, defaultCtx);
     },
@@ -6603,6 +7129,7 @@ function compileLinkable(ruleMapArg, ns, opts) {
   if (!ns) throw new Error("compileLinkable: ns must be a non-empty namespace");
   for (const [, rule] of ruleMapArg) markUnusedValues(rule);
   const grammarTrivia = opts?.trivia ?? ruleMapArg.map(([, r]) => r._meta.grammarTrivia).find(Boolean);
+  const grammarScanSkip = opts?.scanSkip ?? ruleMapArg.map(([, r]) => r._meta.grammarScanSkip).find(Boolean);
   const ruleMap = ruleMapArg.filter(([, val]) => {
     const d = val._def;
     if (d.tag !== "lazy") return true;
@@ -6640,7 +7167,8 @@ function compileLinkable(ruleMapArg, ns, opts) {
     lazyUsage: analyzeLazyUsageMulti(ruleMap.map(([, rule]) => rule)),
     ns,
     deferFirstSetRefs: true,
-    ...grammarTrivia ? { activeTrivia: grammarTrivia, triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {}
+    ...grammarTrivia ? { activeTrivia: grammarTrivia, triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {},
+    ...grammarScanSkip ? { activeScanSkip: grammarScanSkip } : {}
   };
   const seen = /* @__PURE__ */ new Map();
   const ruleNames = /* @__PURE__ */ new Map();
@@ -6704,9 +7232,14 @@ function compileLinkable(ruleMapArg, ns, opts) {
       ctx.failLabel = "_pfail";
       ctx.recordFail = true;
       const savedTrivia = ctx.activeTrivia;
-      if (rule._meta.isTrivia) ctx.activeTrivia = void 0;
+      const savedScanSkip = ctx.activeScanSkip;
+      if (rule._meta.isTrivia) {
+        ctx.activeTrivia = void 0;
+        ctx.activeScanSkip = void 0;
+      }
       const body = emit(resolved, ctx, "_pos");
       ctx.activeTrivia = savedTrivia;
+      ctx.activeScanSkip = savedScanSkip;
       ctx.indent = savedIndent;
       ctx.failLabel = savedFail;
       ctx.recordFail = savedRec;
@@ -6753,6 +7286,7 @@ function compileLinkable(ruleMapArg, ns, opts) {
   }
   const firstSets = /* @__PURE__ */ new Map();
   const firstSetRecipes = /* @__PURE__ */ new Map();
+  const nullable2 = /* @__PURE__ */ new Map();
   for (const [key, rule] of ruleMap) {
     let resolved = rule;
     const d = rule._def;
@@ -6764,15 +7298,18 @@ function compileLinkable(ruleMapArg, ns, opts) {
       }
     }
     firstSets.set(key, canMatchEmptyAtStart(resolved) ? { kind: "any" } : resolved._meta.firstSet);
-    firstSetRecipes.set(key, canMatchEmptyAtStart(resolved) ? { concrete: any(), refs: [] } : leadingFirstSetRecipe(resolved));
+    nullable2.set(key, matchesEmpty(resolved));
+    firstSetRecipes.set(key, canMatchEmptyAtStart(resolved) ? { alts: [[{ set: any(), nullable: false }]] } : leadingFirstSetRecipe(resolved));
   }
   return {
+    v: PARSEMAN_VERSION,
     ns,
     keys: perEntry.map((e) => e.key),
     prelude,
     ruleFns,
     wrappers,
     firstSets,
+    nullable: nullable2,
     firstSetRecipes,
     deps: ruleDependencies(ruleMap),
     needsEmptyTl: !!ctx.needsEmptyTl,
@@ -6851,101 +7388,6 @@ function buildInlineExpression(ctx, r, mapFnSources, buildSources, coverageRootR
   ].join("\n");
 }
 
-// src/combinators/scanTo.ts
-function scanTo(sentinel, { skip: skip2 = [], orEOF = false } = {}) {
-  const meta = {
-    firstSet: any(),
-    canMatchNewline: true,
-    isTrivia: false
-  };
-  return {
-    _tag: "scanTo",
-    _meta: meta,
-    _def: { tag: "scanTo", sentinel, skip: skip2, orEOF },
-    parse(input, pos, ctx) {
-      let cur = pos;
-      const probeCtx = {
-        trackLines: ctx.trackLines,
-        state: ctx.state,
-        ...ctx._errors !== void 0 ? { _errors: ctx._errors } : {}
-      };
-      const emit2 = (end) => {
-        if (end > pos && cstCaptureActive(ctx)) {
-          const leaf2 = { _tag: "leaf", value: input.slice(pos, end), span: { start: pos, end } };
-          pushCstLeaf(ctx, leaf2);
-        }
-      };
-      while (cur < input.length) {
-        const s = sentinel.parse(input, cur, probeCtx);
-        if (s.ok) {
-          emit2(cur);
-          return { ok: true, value: input.slice(pos, cur), span: { start: pos, end: cur } };
-        }
-        let advanced = false;
-        for (const skipper of skip2) {
-          const r = skipper.parse(input, cur, probeCtx);
-          if (r.ok && r.span.end > cur) {
-            cur = r.span.end;
-            advanced = true;
-            break;
-          }
-        }
-        if (!advanced) cur++;
-      }
-      if (orEOF) {
-        emit2(cur);
-        return { ok: true, value: input.slice(pos, cur), span: { start: pos, end: cur } };
-      }
-      const sentDef = sentinel._def;
-      const expected = sentDef.tag === "literal" ? [JSON.stringify(sentDef.value)] : ["sentinel"];
-      return { ok: false, expected, span: { start: pos, end: cur } };
-    }
-  };
-}
-function balanced(open, close, options = {}) {
-  const self = ref();
-  const skips = options.skip ?? [];
-  const stop = /* @__PURE__ */ new Set([open, close]);
-  let bounded = true;
-  for (const sk of skips) {
-    const cs = firstSetClassChars(sk);
-    if (cs === null) {
-      bounded = false;
-      break;
-    }
-    for (const ch of cs) stop.add(ch);
-  }
-  const cls = [...stop].map(escapeClassChar).join("");
-  const content = bounded ? regex(new RegExp(`[^${cls}]+`)) : regex(new RegExp(`[^${escapeClassChar(open)}${escapeClassChar(close)}]`));
-  const inner = many(choice(self, ...skips, content));
-  const combi = transform(
-    sequence(literal(open), inner, expect(literal(close))),
-    // parts: strings (content/self) or arrays (a sequence-shaped skip) or a
-    // ParseError (recovered close). `c` is the close string or a ParseError.
-    ([o, parts, c]) => o + parts.map((p) => typeof p === "string" ? p : Array.isArray(p) ? p.join("") : "").join("") + (typeof c === "string" ? c : "")
-  );
-  if (combi._def.tag === "transform") {
-    combi._def.fnSrc = '([o, parts, c]) => o + parts.map(p => typeof p === "string" ? p : Array.isArray(p) ? p.join("") : "").join("") + (typeof c === "string" ? c : "")';
-    combi._def.recognitionOnly = true;
-  }
-  self.define(combi);
-  return combi;
-}
-function firstSetClassChars(c) {
-  const fs = c._meta.firstSet;
-  if (fs.kind === "empty") return [];
-  if (fs.kind !== "ranges") return null;
-  const out = [];
-  for (const { lo, hi } of fs.ranges) {
-    if (hi - lo > 8) return null;
-    for (let cp = lo; cp <= hi; cp++) out.push(String.fromCodePoint(cp));
-  }
-  return out;
-}
-function escapeClassChar(ch) {
-  return ch.replace(/[\\\]^-]/g, "\\$&");
-}
-
 // src/combinators/withCtx.ts
 function withCtx(extra, combinator) {
   const meta = {
@@ -7002,7 +7444,7 @@ function childrenOf2(def) {
       return [];
   }
 }
-var ruleNameOf = (c) => c._ruleName;
+var ruleNameOf2 = (c) => c._ruleName;
 function lazyTarget(c) {
   if (c._def.tag !== "lazy") return null;
   try {
@@ -7069,15 +7511,15 @@ function evalRuleMapIR(ir) {
       if (Array.isArray(it)) {
         const [src, comb] = it;
         gateSrcs.push(src);
-        let gate;
+        let gate2;
         try {
-          gate = (0, eval)(`(${src})`);
+          gate2 = (0, eval)(`(${src})`);
         } catch {
-          gate = () => {
+          gate2 = () => {
             throw new Error("IR gate fn not materialized");
           };
         }
-        return { gate, combinator: comb };
+        return { gate: gate2, combinator: comb };
       }
       gateSrcs.push(null);
       return it;
@@ -7184,7 +7626,7 @@ var Serializer = class {
    * its target (compileLinkable unwraps the same way). A ref INSIDE a body stays a
    * `g[name]` ref — only the top-level entry is unwrapped. */
   body(c) {
-    return c._def.tag === "lazy" && ruleNameOf(c) !== void 0 ? lazyTarget(c) ?? c : c;
+    return c._def.tag === "lazy" && ruleNameOf2(c) !== void 0 ? lazyTarget(c) ?? c : c;
   }
   run() {
     for (const [, c] of this.ruleMap) this.analyze(this.body(c), /* @__PURE__ */ new Set());
@@ -7209,7 +7651,7 @@ ${body}
   analyze(c, active) {
     const def = c._def;
     if (def.tag === "lazy") {
-      if (ruleNameOf(c) !== void 0) return;
+      if (ruleNameOf2(c) !== void 0) return;
       const target = lazyTarget(c);
       if (!target) throw new Unserializable("unresolved unnamed ref");
       if (active.has(target)) {
@@ -7261,7 +7703,7 @@ ${body}
     const kid = (x) => this.ref(x, selfOf);
     switch (def.tag) {
       case "lazy": {
-        if (ruleNameOf(c) !== void 0) return `g[${JSON.stringify(ruleNameOf(c))}]`;
+        if (ruleNameOf2(c) !== void 0) return `g[${JSON.stringify(ruleNameOf2(c))}]`;
         const target = lazyTarget(c);
         if (selfOf && target === selfOf.comb) return selfOf.var;
         return this.ref(target, selfOf);
@@ -7315,7 +7757,7 @@ ${body}
       case "skip":
         return `skip(${kid(def.main)}, ${kid(def.skipped)})`;
       case "scanTo":
-        return `scanTo(${kid(def.sentinel)}, { skip: [${def.skip.map(kid).join(", ")}], orEOF: ${def.orEOF} })`;
+        return `scanTo(${kid(def.sentinel)}, { skip: [${def.skip.map(kid).join(", ")}]${def.raw ? ", raw: true" : ""}, orEOF: ${def.orEOF} })`;
       case "transform": {
         if (def.fnSrc === void 0) throw new Unserializable("transform without fnSrc");
         return `_tf(${kid(def.parser)}, ${JSON.stringify(def.fnSrc)}${def.recognitionOnly ? ", true" : ""})`;
@@ -7385,6 +7827,18 @@ function cstBuildHost(typeOrOptions, children2, _fields, span, rawChildren, triv
 }
 cstBuildHost._parsemanCstOutput = true;
 function fusedBody(pieces) {
+  for (const p of pieces) {
+    if (p.v === void 0) {
+      throw new Error(
+        `parseman: artifact "${p.ns}" is UNSTAMPED (compiled before the version-lock invariant). Recompile the grammar with parseman ${PARSEMAN_VERSION}; parseman does not fuse unversioned or cross-version artifacts.`
+      );
+    }
+    if (p.v !== PARSEMAN_VERSION) {
+      throw new Error(
+        `parseman: artifact "${p.ns}" was compiled with parseman ${p.v}, but is being fused with parseman ${PARSEMAN_VERSION}. Compiled grammar artifacts are version-locked \u2014 recompile the grammar with parseman ${PARSEMAN_VERSION}; parseman does not fuse across versions.`
+      );
+    }
+  }
   const winner = /* @__PURE__ */ new Map();
   for (const p of pieces) for (const k of p.keys) winner.set(k, p);
   for (const [k, p] of winner) {
@@ -7410,23 +7864,38 @@ function fusedBody(pieces) {
   const wrapperEntries = [...winner].map(([k, p]) => `${JSON.stringify(k)}: ${p.wrappers.get(k)}`);
   const rawBody = [...lines, "return {", wrapperEntries.join(",\n"), "}"].join("\n");
   const ANY2 = { kind: "any" };
+  const EMPTY3 = { kind: "empty" };
   const recipes = /* @__PURE__ */ new Map();
   const shallow = /* @__PURE__ */ new Map();
+  const nullable2 = /* @__PURE__ */ new Map();
   for (const [k, p] of winner) {
     const r = p.firstSetRecipes?.get(k);
     if (r) recipes.set(k, r);
     const fs = p.firstSets?.get(k);
     if (fs) shallow.set(k, fs);
-  }
+    const nu = p.nullable?.get(k);
+    if (nu !== void 0) nullable2.set(k, nu);
+  }
+  const knownRef = (ref2) => recipes.has(ref2) || shallow.has(ref2);
+  const refFS = (ref2) => knownRef(ref2) ? finalFS.get(ref2) ?? ANY2 : ANY2;
+  const refNullable = (ref2) => knownRef(ref2) ? nullable2.get(ref2) ?? true : true;
+  const resolveRecipe = (r) => {
+    let out = EMPTY3;
+    for (const chain of r.alts) {
+      for (const seg of chain) {
+        out = union(out, seg.ref !== void 0 ? refFS(seg.ref) : seg.set);
+        const skippable = seg.ref !== void 0 ? seg.nullable || refNullable(seg.ref) : seg.nullable;
+        if (!skippable) break;
+      }
+    }
+    return out;
+  };
   const finalFS = /* @__PURE__ */ new Map();
-  for (const [k] of winner) finalFS.set(k, recipes.get(k)?.concrete ?? shallow.get(k) ?? ANY2);
+  for (const [k] of winner) finalFS.set(k, recipes.has(k) ? EMPTY3 : shallow.get(k) ?? ANY2);
   for (let iter = 0; iter <= recipes.size; iter++) {
     let changed = false;
     for (const [k, r] of recipes) {
-      let fs = r.concrete;
-      for (const ref2 of r.refs) {
-        fs = union(fs, recipes.has(ref2) || shallow.has(ref2) ? finalFS.get(ref2) ?? ANY2 : ANY2);
-      }
+      const fs = resolveRecipe(r);
       if (JSON.stringify(finalFS.get(k)) !== JSON.stringify(fs)) {
         finalFS.set(k, fs);
         changed = true;
@@ -7558,8 +8027,8 @@ function composeLeaf(_items) {
   throw new Error("composeLeaf(): requires Parseman macro lowering; runtime composition is forbidden");
 }
 
-// src/combinators/guard.ts
-function guard(predicate) {
+// src/combinators/gate.ts
+function gate(predicate) {
   const meta = {
     firstSet: { kind: "any" },
     canMatchNewline: false,
@@ -7577,6 +8046,9 @@ function guard(predicate) {
   };
 }
 
+// src/combinators/guard.ts
+var guard = gate;
+
 // src/combinators/completions.ts
 function completionsAt(target, input, offset, options = {}) {
   const probe = { offset, best: null };
@@ -8108,12 +8580,14 @@ function runOnce(entry, input, options, phase, profileState) {
   const profile = profileState ?? (phase === void 0 ? void 0 : { phase, nodes: 0, childSlots: 0, rawSlots: 0, triviaSlots: 0, fieldSlots: 0, hostCalls: 0 });
   const skipGlobalSinks = phase === "recognizer" || phase === "capture";
   const grammarTrivia = typeof entry !== "function" ? entry._meta.grammarTrivia : void 0;
+  const grammarScanSkip = typeof entry !== "function" ? entry._meta.grammarScanSkip : void 0;
   const ctx = {
     trackLines: false,
     ...skipGlobalSinks ? { _pmProfile: profile } : { _triviaLog: triviaLog, _errors: errors, ...profile === void 0 ? {} : { _pmProfile: profile } },
     build: options.build,
     state: options.state,
     ...grammarTrivia !== void 0 ? { trivia: grammarTrivia, ...grammarTrivia._meta.triviaKindLabels ? { triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {} } : {},
+    ...grammarScanSkip !== void 0 ? { scanSkip: grammarScanSkip } : {},
     ...options.triviaCaptureMask !== void 0 ? { _triviaCaptureMask: options.triviaCaptureMask } : {},
     ...options.tolerant ? { _tolerant: true, _rec: REC } : {},
     ...options.instrumentation === void 0 ? {} : options.instrumentation
@@ -8399,7 +8873,7 @@ function coverageEntry(entry, collector, maps, trace) {
           return def.type === void 0 ? node(build(def.parser), def.build, opts) : node(def.type, build(def.parser), def.build, opts);
         }
         case "guard":
-          return guard(def.predicate);
+          return gate(def.predicate);
         case "withCtx":
           return withCtx(def.extra, build(def.parser));
         case "expect":
@@ -8454,9 +8928,9 @@ function buildTriviaIndex(root, input = "", opts) {
         if (prev) merge(after, prev.span.end, run2);
       }
     }
-    const ch = node2.children;
-    if (ch) {
-      for (const c of ch) {
+    const ch2 = node2.children;
+    if (ch2) {
+      for (const c of ch2) {
         if (typeof c === "object" && c !== null && c.children !== void 0) {
           visit(c);
         }
@@ -8767,6 +9241,7 @@ export {
   absoluteSpanCST,
   absolutize,
   absolutizeCST,
+  analyzeGating,
   annotateSpan,
   applyEdit,
   attempt,
@@ -8791,8 +9266,11 @@ export {
   cstBuildHost,
   expect,
   field,
+  firstSetToString,
+  formatGatingWarnings,
   gapIsSignificant,
   gapText,
+  gate,
   grammarCoverageDefinitions,
   guard,
   indentMixed,