parseman 0.31.0 → 0.33.0

package/dist/plugin/index.cjs

@@ -130,10 +130,13 @@ function matchesEmpty(p, seen = /* @__PURE__ */ new Set()) {
       return true;
   }
 }
+function isZeroWidthAssertion(p) {
+  return p._def.tag === "not";
+}
 function sequenceFirstSet(parsers) {
   let fs2 = empty();
   for (const p of parsers) {
-    fs2 = union(fs2, p._meta.firstSet);
+    if (!isZeroWidthAssertion(p)) fs2 = union(fs2, p._meta.firstSet);
     if (!matchesEmpty(p)) return fs2;
   }
   return fs2;
@@ -163,7 +166,7 @@ function firstSetOf(p, seen = /* @__PURE__ */ new Set()) {
     case "sequence": {
       let out = empty();
       for (const term of d.parsers) {
-        out = union(out, fs2(term));
+        if (!isZeroWidthAssertion(term)) out = union(out, fs2(term));
         if (!matchesEmpty(term)) return out;
       }
       return out;
@@ -488,9 +491,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) {
@@ -503,9 +506,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;
@@ -519,8 +522,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();
@@ -587,12 +590,35 @@ function shortScanner(source, flags) {
     return minOne && end === pos ? null : end;
   };
 }
+function asciiCaseFold(fs2) {
+  if (fs2.kind !== "ranges") return fs2;
+  const ranges = fs2.ranges.map((r) => ({ lo: r.lo, hi: r.hi }));
+  const add = (lo, hi) => {
+    if (lo <= hi) ranges.push({ lo, hi });
+  };
+  for (const r of fs2.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",
@@ -647,8 +673,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;
@@ -656,18 +682,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;
@@ -683,8 +709,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 "[":
@@ -705,8 +731,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 = () => {
@@ -1139,8 +1165,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);
@@ -1486,11 +1512,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);
       }
     }
   }
@@ -2229,6 +2255,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]);
   }
@@ -2797,6 +2829,413 @@ function leaf(root, fn) {
   };
 }
 
+// src/version.ts
+var PARSEMAN_VERSION = "0.33.0";
+
+// src/analysis/gating.ts
+var isAny = (fs2) => fs2.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(fs2) {
+  if (fs2.kind === "any") return "ANY";
+  if (fs2.kind === "empty") return "(empty)";
+  return fs2.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((fs2, index) => ({ fs: fs2, 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 fs2 = c._meta.firstSet;
+  if (fs2.kind === "empty") return [];
+  if (fs2.kind !== "ranges") return null;
+  const out = [];
+  for (const { lo, hi } of fs2.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) {
@@ -2909,16 +3348,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;
@@ -2997,8 +3436,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++;
@@ -3020,7 +3459,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();
@@ -3049,7 +3488,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;
@@ -3098,9 +3537,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 });
@@ -3277,12 +3716,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] !== "]") {
@@ -3296,8 +3735,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;
@@ -3312,12 +3751,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] !== "]") {
@@ -3328,18 +3767,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++;
@@ -3458,12 +3897,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] !== "]") {
@@ -3474,18 +3913,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;
     }
@@ -3537,12 +3976,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] !== "]") {
@@ -3553,8 +3992,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;
@@ -4226,58 +4665,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 merge = (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;
+      }
+    }
+    return seg(hasRef ? any() : set, nullable2);
+  };
+  const compute = () => {
+    switch (d.tag) {
+      case "lazy": {
+        try {
+          return rec(d.thunk());
+        } catch {
+          return { alts: [[seg(any(), false)]] };
+        }
       }
-    }
-    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 = merge(out, rec(arm));
-      return out;
-    }
-    case "sequence": {
-      let out = { concrete: empty(), refs: [] };
-      for (const term of d.parsers) {
-        out = merge(out, rec(term));
-        if (!matchesEmpty(term)) 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] };
       }
-      return out;
+      // `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 }";
@@ -4481,16 +4950,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`,
@@ -4768,7 +5240,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 };
@@ -4961,7 +5433,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":
@@ -5013,10 +5485,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}) {`];
@@ -5174,7 +5646,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);
@@ -5186,9 +5658,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)`;
     }
@@ -5605,10 +6077,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}) {`,
@@ -6078,6 +6555,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":
@@ -6499,9 +6994,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,
@@ -6523,7 +7045,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);
@@ -6587,6 +7110,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);
     },
@@ -6622,6 +7146,7 @@ function compileRuleMap(ruleMap, opts) {
   for (const [, rule] of ruleMap) markUnusedValues(rule);
   const coverageWinners = opts?.coverage ? Object.fromEntries(ruleMap.filter(([, rule]) => rule._def.tag !== "lazy")) : void 0;
   const grammarTrivia = opts?.trivia;
+  const grammarScanSkip = opts?.scanSkip ?? ruleMap.map(([, r]) => r._meta.grammarScanSkip).find(Boolean);
   const ctx = {
     vars: 0,
     indent: 1,
@@ -6643,7 +7168,8 @@ function compileRuleMap(ruleMap, opts) {
     recovery: opts?.recovery ?? false,
     ...opts?.coverage ? { coverage: { plan: buildGrammarPlan(ruleMap.map(([, rule]) => rule), coverageWinners) } } : {},
     lazyUsage: analyzeLazyUsageMulti(ruleMap.map(([, rule]) => rule)),
-    ...grammarTrivia ? { activeTrivia: grammarTrivia, triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {}
+    ...grammarTrivia ? { activeTrivia: grammarTrivia, triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {},
+    ...grammarScanSkip ? { activeScanSkip: grammarScanSkip } : {}
   };
   const seenNames = /* @__PURE__ */ new Map();
   const ruleNames = /* @__PURE__ */ new Map();
@@ -6657,9 +7183,14 @@ function compileRuleMap(ruleMap, opts) {
   ctx.ruleNames = ruleNames;
   const perEntry = ruleMap.map(([key, rule]) => {
     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 r = emit(rule, ctx, "_pos");
     ctx.activeTrivia = savedTrivia;
+    ctx.activeScanSkip = savedScanSkip;
     return { key, rule, r };
   });
   const derivedSrcs = ctx.mapFnSrcs.length === ctx.mapFns.length && ctx.mapFnSrcs.every((s) => s !== null) ? ctx.mapFnSrcs : void 0;
@@ -6732,6 +7263,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;
@@ -6769,7 +7301,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();
@@ -6833,9 +7366,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;
@@ -6882,6 +7420,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;
@@ -6893,15 +7432,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,
@@ -6980,101 +7522,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 fs2 = c._meta.firstSet;
-  if (fs2.kind === "empty") return [];
-  if (fs2.kind !== "ranges") return null;
-  const out = [];
-  for (const { lo, hi } of fs2.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 = {
@@ -7131,7 +7578,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 {
@@ -7142,9 +7589,9 @@ function lazyTarget(c) {
 }
 var Unserializable = class extends Error {
 };
-function serializeRuleMap(ruleMap) {
+function serializeRuleMap(ruleMap, scanSkip) {
   try {
-    return new Serializer(ruleMap).run();
+    return new Serializer(ruleMap, scanSkip ?? []).run();
   } catch (e) {
     if (e instanceof Unserializable) {
       if (process.env.PARSEMAN_IR_DEBUG) console.error(`[ir] fallback: ${e.message}`);
@@ -7198,15 +7645,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;
@@ -7305,40 +7752,75 @@ var Serializer = class {
   decls = [];
   ruleValues = /* @__PURE__ */ new Set();
   ruleMap;
-  constructor(ruleMap) {
+  scanSkip;
+  constructor(ruleMap, scanSkip = []) {
     this.ruleMap = ruleMap;
+    this.scanSkip = scanSkip;
     for (const [, c] of ruleMap) this.ruleValues.add(this.body(c));
   }
+  /** A grammar-level `scanSkip` unit is an opaque TERMINAL (a string, a balanced
+   * bracket) — it must not reach a grammar-rule ref (`g[name]`), because the
+   * serialized `scanSkip` array sits in the `rules({ scanSkip })` OPTIONS position,
+   * outside the `(g) => …` factory where `g` is bound. A unit that does reference a
+   * rule can't be carried in options; bail to the full-pieces fallback. */
+  assertNoRuleRef(c, seen) {
+    if (seen.has(c)) return;
+    seen.add(c);
+    if (c._def.tag === "lazy") {
+      if (ruleNameOf2(c) !== void 0) throw new Unserializable("scanSkip unit references a grammar rule");
+      const target = lazyTarget(c);
+      if (target) this.assertNoRuleRef(target, seen);
+      return;
+    }
+    for (const child of childrenOf2(c._def)) this.assertNoRuleRef(child, seen);
+  }
   /** A `rules()` map wraps each rule value in a named `lazy` proxy; the real body is
    * 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());
+    for (const c of this.scanSkip) {
+      this.assertNoRuleRef(c, /* @__PURE__ */ new Set());
+      this.analyze(c, /* @__PURE__ */ new Set());
+    }
     let n = 0;
     for (const [c, count] of this.counts) {
       if (this.ruleValues.has(c)) continue;
       if (count >= 2 || this.selfRef.has(c)) this.constName.set(c, `_s${n++}`);
     }
+    const outerDecls = [];
+    const innerDecls = [];
+    let optionsArg = "";
+    if (this.scanSkip.length > 0) {
+      this.decls = outerDecls;
+      const units = this.scanSkip.map((c) => this.ref(c, null));
+      optionsArg = `{ scanSkip: [${units.join(", ")}] }, `;
+    }
+    this.decls = innerDecls;
     const body = this.ruleMap.map(([name, c]) => `  ${JSON.stringify(name)}: ${this.wrap(this.body(c))}`).join(",\n");
-    if (this.decls.length === 0) return `rules((g) => ({
+    const factory = innerDecls.length === 0 ? `(g) => ({
 ${body}
-}))`;
-    return `rules((g) => {
-${this.decls.map((d) => "  " + d).join("\n")}
+})` : `(g) => {
+${innerDecls.map((d) => "  " + d).join("\n")}
   return ({
 ${body}
 })
-})`;
+}`;
+    const call = `rules(${optionsArg}${factory})`;
+    return outerDecls.length === 0 ? call : `(() => {
+${outerDecls.map((d) => "  " + d).join("\n")}
+  return ${call}
+})()`;
   }
   /** Count identity references and flag self-referential subtrees. `active` is the
    * set of combinators on the current DFS path (to detect a lazy pointing back). */
   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)) {
@@ -7390,7 +7872,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);
@@ -7444,7 +7926,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" : ""})`;
@@ -7525,6 +8007,18 @@ function pickPieces(pieces, names) {
   return pieces.map((pc) => ({ ...pc, keys: pc.keys.filter((k) => keep.has(k) && winner.get(k) === pc), ruleFns: filt(pc.ruleFns, pc), wrappers: filt(pc.wrappers, pc), deps: filt(pc.deps, pc) })).filter((pc) => pc.keys.length > 0);
 }
 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) {
@@ -7550,23 +8044,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 fs2 = p.firstSets?.get(k);
     if (fs2) shallow.set(k, fs2);
+    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 fs2 = r.concrete;
-      for (const ref2 of r.refs) {
-        fs2 = union(fs2, recipes.has(ref2) || shallow.has(ref2) ? finalFS.get(ref2) ?? ANY2 : ANY2);
-      }
+      const fs2 = resolveRecipe(r);
       if (JSON.stringify(finalFS.get(k)) !== JSON.stringify(fs2)) {
         finalFS.set(k, fs2);
         changed = true;
@@ -7614,8 +8123,8 @@ function materializePiece(p, trivia2, captureTerminals = false) {
   return pieces;
 }
 
-// src/combinators/guard.ts
-function guard(predicate) {
+// src/combinators/gate.ts
+function gate(predicate) {
   const meta = {
     firstSet: { kind: "any" },
     canMatchNewline: false,
@@ -7872,17 +8381,17 @@ function isGatedArmExpr(e) {
   return hasGate && hasCombinator;
 }
 function gatedArmParts(e) {
-  let gate;
+  let gate2;
   let combinator;
   for (const prop of e.properties) {
     if (prop.type !== "Property") return null;
     const op = prop;
     const name = propName(op);
-    if (name === "gate") gate = op.value;
+    if (name === "gate") gate2 = op.value;
     else if (name === "combinator") combinator = op.value;
     else return null;
   }
-  return gate && combinator ? { gate, combinator } : null;
+  return gate2 && combinator ? { gate: gate2, combinator } : null;
 }
 function isCombinator(v2) {
   return !!v2 && typeof v2 === "object" && "_def" in v2;
@@ -8084,14 +8593,14 @@ function exprToCombi(node2, scope, code, mfs) {
       return null;
     }
   }
-  if (callee.name === "guard") {
+  if (callee.name === "gate" || callee.name === "guard") {
     if (code === void 0 || mfs === void 0) return null;
     const [predArg] = node2.arguments;
     if (!predArg || predArg.type === "SpreadElement") return null;
     const predSrc = stripTsFromSource(predArg, code);
     mfs.push(predSrc);
     try {
-      const combi = guard(() => true);
+      const combi = gate(() => true);
       if (combi._def.tag !== "guard") return null;
       combi._def.predSrc = predSrc;
       return combi;
@@ -8715,21 +9224,32 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
       return null;
     }
     const optionsArg = optionsFirst ? arg0 : arg1;
-    const triviaValue = optionsArg?.type === "ObjectExpression" ? (optionsArg.properties ?? []).find(
-      (p) => p.key?.name === "trivia"
+    const optionValue = (name) => optionsArg?.type === "ObjectExpression" ? (optionsArg.properties ?? []).find(
+      (p) => p.key?.name === name
     )?.value : void 0;
+    const triviaValue = optionValue("trivia");
     const gTrivia = triviaValue ? evaluateExpr(triviaValue, scope, code, []) : void 0;
-    return { ruleMap, ...gTrivia ? { trivia: gTrivia } : {} };
+    const scanSkipValue = optionValue("scanSkip");
+    const gScanSkip = scanSkipValue ? evaluateCombinatorArray(scanSkipValue, scope, code) ?? void 0 : void 0;
+    if (gScanSkip) {
+      for (const rule of ruleMap.values()) {
+        if (rule && !rule._meta.isTrivia) {
+          ;
+          rule._meta.grammarScanSkip = gScanSkip;
+        }
+      }
+    }
+    return { ruleMap, ...gTrivia ? { trivia: gTrivia } : {}, ...gScanSkip ? { scanSkip: gScanSkip } : {} };
   };
   const compileRulesFactory = (init, label2) => {
     const evaluated = evaluateRulesFactory(init, label2);
     if (!evaluated) return null;
-    const compiled = compileRuleMap([...evaluated.ruleMap], { ...evaluated.trivia ? { trivia: evaluated.trivia } : {}, recovery, coverage: grammarCoverage });
+    const compiled = compileRuleMap([...evaluated.ruleMap], { ...evaluated.trivia ? { trivia: evaluated.trivia } : {}, ...evaluated.scanSkip ? { scanSkip: evaluated.scanSkip } : {}, recovery, coverage: grammarCoverage });
     if (!compiled) {
       warn(init.start, `${label2}: rule map couldn't be inlined`);
       return null;
     }
-    return { replacement: compiled.replacement, ruleMap: evaluated.ruleMap, ...compiled.coverageDefinitions ? { coverageDefinitions: compiled.coverageDefinitions } : {}, ...evaluated.trivia ? { trivia: evaluated.trivia } : {} };
+    return { replacement: compiled.replacement, ruleMap: evaluated.ruleMap, ...compiled.coverageDefinitions ? { coverageDefinitions: compiled.coverageDefinitions } : {}, ...evaluated.trivia ? { trivia: evaluated.trivia } : {}, ...evaluated.scanSkip ? { scanSkip: evaluated.scanSkip } : {} };
   };
   const isRulesCall = (init) => init.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "rules";
   const isComposeCall = (init) => init.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "compose";
@@ -8737,13 +9257,14 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
   const isPickCall = (init) => init.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "pick";
   const localRuleMaps = /* @__PURE__ */ new Map();
   const localGrammarTrivia = /* @__PURE__ */ new Map();
+  const localGrammarScanSkip = /* @__PURE__ */ new Map();
   const nsFor = (label2) => `_${(0, import_node_crypto.createHash)("sha1").update(`${id}#${label2}`).digest("hex").slice(0, 8)}_`;
   const stripIndent = (s) => s.replace(/\n[ \t]+/g, "\n");
   const serializePieces = (p) => {
     const mapLit = (m, stripVals = false) => `new Map([${[...m].map(
       ([k, v2]) => `[${JSON.stringify(k)}, ${JSON.stringify(stripVals && typeof v2 === "string" ? stripIndent(v2) : v2)}]`
     ).join(", ")}])`;
-    return `{ ns: ${JSON.stringify(p.ns)}, keys: ${JSON.stringify(p.keys)}, prelude: ${JSON.stringify(p.prelude.map(stripIndent))}, ruleFns: ${mapLit(p.ruleFns, true)}, wrappers: ${mapLit(p.wrappers, true)}, firstSets: ${mapLit(p.firstSets)}, firstSetRecipes: ${p.firstSetRecipes ? mapLit(p.firstSetRecipes) : "new Map()"}, deps: ${mapLit(p.deps)}, needsEmptyTl: ${p.needsEmptyTl}, needsHostReads: ${p.needsHostReads}, hasDirectBuilders: ${p.hasDirectBuilders === true}, isRecognitionOnly: ${p.isRecognitionOnly === true}, mfFns: [], buildFns: [] }`;
+    return `{ v: ${JSON.stringify(p.v)}, ns: ${JSON.stringify(p.ns)}, keys: ${JSON.stringify(p.keys)}, prelude: ${JSON.stringify(p.prelude.map(stripIndent))}, ruleFns: ${mapLit(p.ruleFns, true)}, wrappers: ${mapLit(p.wrappers, true)}, firstSets: ${mapLit(p.firstSets)}, nullable: ${p.nullable ? mapLit(p.nullable) : "new Map()"}, firstSetRecipes: ${p.firstSetRecipes ? mapLit(p.firstSetRecipes) : "new Map()"}, deps: ${mapLit(p.deps)}, needsEmptyTl: ${p.needsEmptyTl}, needsHostReads: ${p.needsHostReads}, hasDirectBuilders: ${p.hasDirectBuilders === true}, isRecognitionOnly: ${p.isRecognitionOnly === true}, mfFns: [], buildFns: [] }`;
   };
   const isSpread = (it) => "__spreadLocal" in it;
   const isIR = (it) => "ir" in it && !("ruleFns" in it);
@@ -8854,12 +9375,12 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
     }
     return pieces;
   };
-  const localCarried = (rm, label2, composing) => {
+  const localCarried = (rm, label2, composing, scanSkip) => {
     const entries = [...rm];
     const ns = nsFor(label2);
-    const ir = serializeRuleMap(entries);
+    const ir = serializeRuleMap(entries, scanSkip);
     if (ir) return { carried: [{ ns, ir }] };
-    const p = compileLinkable(entries, ns, { ...composing ? { trivia: composing } : {}, recovery });
+    const p = compileLinkable(entries, ns, { ...composing ? { trivia: composing } : {}, ...scanSkip ? { scanSkip } : {}, recovery });
     return p ? { carried: [p] } : null;
   };
   const argPieces = (arg, label2, composing) => {
@@ -8884,18 +9405,13 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
       }
     }
     if (isRulesCall(arg)) {
-      const rulesArgs = arg.arguments;
-      const a0 = rulesArgs[0];
-      const a1 = rulesArgs[1];
-      const optionsFirst = a0?.type === "ObjectExpression";
-      const factory = optionsFirst ? a1 : a0;
-      const rm = factory ? evaluateParserFactory(factory, scope, code, []) : null;
-      return rm ? localCarried(rm, label2, composing) : null;
+      const evaluated = evaluateRulesFactory(arg, label2);
+      return evaluated ? localCarried(evaluated.ruleMap, label2, composing, evaluated.scanSkip) : null;
     }
     if (arg.type === "Identifier") {
       const name = arg.name;
       const rm = localRuleMaps.get(name);
-      if (rm) return localCarried(rm, label2, composing);
+      if (rm) return localCarried(rm, label2, composing, localGrammarScanSkip.get(name));
       const composed = localComposedCarried.get(name);
       if (composed) return { carried: composed };
       const pieces = importedPieces(name);
@@ -8983,11 +9499,15 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
     }
     const localArg = elements[elements.length - 1];
     let localRules = null;
+    let localScanSkip;
     if (isRulesCall(localArg)) {
       const evaluated = evaluateRulesFactory(localArg, `composeLeaf${init.start}`);
       localRules = evaluated?.ruleMap ?? null;
+      localScanSkip = evaluated?.scanSkip;
     } else if (localArg.type === "Identifier") {
-      localRules = localRuleMaps.get(localArg.name) ?? null;
+      const name = localArg.name;
+      localRules = localRuleMaps.get(name) ?? null;
+      localScanSkip = localGrammarScanSkip.get(name);
     }
     if (!localRules) {
       warn(init.start, "composeLeaf(): final argument must be a local rules() map");
@@ -9005,7 +9525,7 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
     }
     try {
       const localNs = nsFor(`composeLeaf${init.start}`);
-      const plainLocalPiece = compileLinkable([...localRules], localNs, { ...composing ? { trivia: composing } : {}, recovery });
+      const plainLocalPiece = compileLinkable([...localRules], localNs, { ...composing ? { trivia: composing } : {}, ...localScanSkip ? { scanSkip: localScanSkip } : {}, recovery });
       if (!plainLocalPiece) {
         warn(init.start, "composeLeaf(): local rules could not be statically compiled");
         return null;
@@ -9107,15 +9627,19 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
           if (!compiledRules) continue;
           localRuleMaps.set(varName, compiledRules.ruleMap);
           if (compiledRules.trivia) localGrammarTrivia.set(varName, compiledRules.trivia);
+          if (compiledRules.scanSkip) localGrammarScanSkip.set(varName, compiledRules.scanSkip);
           let replacement = withCoverageDefinitions(
             compiledRules.replacement,
             compiledRules.coverageDefinitions?.length ? compiledRules.coverageDefinitions : emittedCoverageDefinitions(compiledRules.replacement)
           );
           if (exportPrefix) {
             const ns = nsFor(varName);
-            const pieces = compileLinkable([...compiledRules.ruleMap], ns, { recovery });
+            const pieces = compileLinkable([...compiledRules.ruleMap], ns, {
+              ...compiledRules.scanSkip ? { scanSkip: compiledRules.scanSkip } : {},
+              recovery
+            });
             if (pieces && !pieces.mfFns.length && !pieces.buildFns.length) {
-              const ir = serializeRuleMap([...compiledRules.ruleMap]);
+              const ir = serializeRuleMap([...compiledRules.ruleMap], compiledRules.scanSkip);
               replacement = withCarriedPieces(replacement, [ir ? { ns, ir } : pieces]);
             }
           }
@@ -9235,9 +9759,18 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
       ms.overwrite(imp.start, imp.end, stripped);
     }
   }
-  for (const { start, end, replacement } of (runtimeComposeFallback ? [] : replacements).sort((a, b) => b.start - a.start)) {
+  const applied = runtimeComposeFallback ? [] : replacements;
+  for (const { start, end, replacement } of applied.slice().sort((a, b) => b.start - a.start)) {
     ms.overwrite(start, end, replacement);
   }
+  if (applied.length > 0) {
+    ms.prepend(
+      `// Generated by parseman v${PARSEMAN_VERSION} \u2014 DO NOT EDIT.
+// Version-locked: compile AND fuse/link this artifact with parseman v${PARSEMAN_VERSION} ONLY.
+// Parseman does not read artifacts across versions; recompile if the version differs.
+`
+    );
+  }
   const unlowered = endLoweringCapture();
   if (warnUnloweredRegex) {
     for (const src of unlowered) {