parseman 0.25.0 → 0.26.1

package/dist/plugin/index.js

@@ -297,7 +297,13 @@ function saveCstMark(ctx) {
     raw: cstRawLen(ctx),
     tlog: cstTlLen(ctx),
     leaves: cstLeavesLen(ctx),
-    fields: ctx._fields?.length ?? 0
+    fields: ctx._fields?.length ?? 0,
+    // Speculative rollback must truncate the flat recovery-error sink in lockstep
+    // with the CST leaves: a branch that recovered (pushing a ParseError to
+    // ctx._errors AND embedding it as a CST child via captureError) then failed
+    // must remove BOTH, or the flat error survives as a GHOST that a tree walk
+    // can't see (flat run().errors would disagree with the embedded set).
+    errors: ctx._errors?.length ?? 0
   };
 }
 function rollbackBufList(b, keyMulti, keySingle, len) {
@@ -313,6 +319,7 @@ function rollbackBufList(b, keyMulti, keySingle, len) {
   if (len === 0) b[keySingle] = void 0;
 }
 function rollbackCstCapture(ctx, mark) {
+  if (ctx._errors && mark.errors !== void 0) ctx._errors.length = mark.errors;
   const b = ctx._cstBuf;
   if (b) {
     rollbackBufList(b, "raw", "rawSingle", mark.raw);
@@ -870,12 +877,159 @@ function keywords(words, opts = {}) {
   };
 }
 
+// src/recovery/scan.ts
+function probeAt(sentinel, input, pos, ctx) {
+  const s = {
+    _probe: ctx._probe,
+    _errors: ctx._errors,
+    _cstLeaves: ctx._cstLeaves,
+    _cstChildren: ctx._cstChildren,
+    _cstRawChildren: ctx._cstRawChildren,
+    _cstTriviaLog: ctx._cstTriviaLog,
+    _triviaLog: ctx._triviaLog,
+    _fields: ctx._fields,
+    _cstBuf: ctx._cstBuf,
+    _tolerant: ctx._tolerant,
+    _sync: ctx._sync
+  };
+  ctx._probe = void 0;
+  ctx._errors = void 0;
+  ctx._cstLeaves = void 0;
+  ctx._cstChildren = void 0;
+  ctx._cstRawChildren = void 0;
+  ctx._cstTriviaLog = void 0;
+  ctx._triviaLog = void 0;
+  ctx._fields = void 0;
+  ctx._cstBuf = void 0;
+  ctx._tolerant = void 0;
+  ctx._sync = void 0;
+  try {
+    return sentinel.parse(input, pos, ctx).ok;
+  } finally {
+    ctx._probe = s._probe;
+    ctx._errors = s._errors;
+    ctx._cstLeaves = s._cstLeaves;
+    ctx._cstChildren = s._cstChildren;
+    ctx._cstRawChildren = s._cstRawChildren;
+    ctx._cstTriviaLog = s._cstTriviaLog;
+    ctx._triviaLog = s._triviaLog;
+    ctx._fields = s._fields;
+    ctx._cstBuf = s._cstBuf;
+    ctx._tolerant = s._tolerant;
+    ctx._sync = s._sync;
+  }
+}
+function orSentinel(a, b) {
+  if (b === void 0) return a;
+  return {
+    _tag: "orSentinel",
+    _meta: { firstSet: { kind: "any" }, canMatchNewline: false, isTrivia: false },
+    _def: { tag: "unknown" },
+    parse(input, pos, ctx) {
+      const ra = a.parse(input, pos, ctx);
+      if (ra.ok) return ra;
+      return b.parse(input, pos, ctx);
+    }
+  };
+}
+function firstSetSentinel(fs2) {
+  if (fs2.kind !== "ranges" || fs2.ranges.length === 0) return null;
+  const ranges = fs2.ranges;
+  return {
+    _tag: "firstSetSentinel",
+    _meta: { firstSet: fs2, canMatchNewline: false, isTrivia: false },
+    _def: { tag: "unknown" },
+    parse(input, pos) {
+      const code = pos < input.length ? input.codePointAt(pos) : void 0;
+      if (code !== void 0) {
+        for (const r of ranges) {
+          if (code >= r.lo && code <= r.hi) return { ok: true, value: null, span: { start: pos, end: pos } };
+        }
+      }
+      return { ok: false, expected: [], span: { start: pos, end: pos } };
+    }
+  };
+}
+function recoverScan(input, from, ctx, sync, expected) {
+  let scanPos = from;
+  while (scanPos < input.length && !probeAt(sync, input, scanPos, ctx)) scanPos++;
+  const error = { _tag: "parseError", span: { start: from, end: scanPos }, expected };
+  ctx._errors?.push(error);
+  return { error, end: scanPos };
+}
+function matchesAt(sentinel, input, pos, ctx) {
+  return probeAt(sentinel, input, pos, ctx);
+}
+function captureError(ctx, error) {
+  if (cstCaptureActive(ctx)) pushCstChild(ctx, error, error);
+}
+
+// src/combinators/expect.ts
+function deriveExpected(c) {
+  const def = c._def;
+  switch (def.tag) {
+    case "literal":
+      return [JSON.stringify(def.value)];
+    case "regex":
+      return [`/${def.source}/`];
+    case "keywords":
+      return def.words.map((w) => JSON.stringify(w));
+    case "label":
+      return [def.label];
+    case "choice":
+      return def.parsers.flatMap(deriveExpected);
+    case "sequence":
+      return def.parsers.length > 0 ? deriveExpected(def.parsers[0]) : [];
+    case "node":
+    case "grammar":
+    case "trivia":
+    case "token":
+    case "optional":
+    case "many":
+    case "oneOrMore":
+    case "transform":
+    case "not":
+      return deriveExpected(def.parser);
+    case "lazy": {
+      const name = c._ruleName;
+      try {
+        return deriveExpected(def.thunk());
+      } catch {
+        return name ? [name] : [];
+      }
+    }
+    default:
+      return [];
+  }
+}
+function expect(combinator, label2) {
+  const expected = label2 !== void 0 ? [label2] : deriveExpected(combinator);
+  const meta = {
+    firstSet: combinator._meta.firstSet,
+    canMatchNewline: combinator._meta.canMatchNewline,
+    isTrivia: false
+  };
+  return {
+    _tag: "expect",
+    _meta: meta,
+    _def: { tag: "expect", parser: combinator, label: label2, expected },
+    parse(input, pos, ctx) {
+      const result = combinator.parse(input, pos, ctx);
+      if (result.ok) return result;
+      const error = { _tag: "parseError", span: { start: pos, end: pos }, expected };
+      ctx._errors?.push(error);
+      if (ctx._tolerant) captureError(ctx, error);
+      return { ok: true, value: error, span: { start: pos, end: pos } };
+    }
+  };
+}
+
 // src/combinators/choice.ts
 function choice(...args) {
   const parsers = args.map((a) => "gate" in a ? a.combinator : a);
   const gates = args.map((a) => "gate" in a ? a.gate : null);
   const hasGates = gates.some((g) => g !== null);
-  const disjoint = !hasGates && areDisjoint(parsers.map((p) => p._meta.firstSet));
+  const disjoint = areDisjoint(parsers.map((p) => p._meta.firstSet)) && parsers.every((p) => !matchesEmpty(p));
   let combined = { kind: "empty" };
   for (const p of parsers) combined = union(combined, p._meta.firstSet);
   const meta = {
@@ -914,17 +1068,21 @@ function choice(...args) {
       const expected = [];
       if (disjoint && pos < input.length) {
         const code = input.codePointAt(pos);
-        let parser2 = code < 128 ? asciiDispatch?.[code] ?? null : null;
-        if (!parser2) {
-          for (const p of parsers) {
-            if (inFirstSet(code, p._meta.firstSet)) {
-              parser2 = p;
+        let idx = code < 128 ? asciiDispatch[code] : -1;
+        if (idx < 0) {
+          for (let i = 0; i < parsers.length; i++) {
+            if (inFirstSet(code, parsers[i]._meta.firstSet)) {
+              idx = i;
               break;
             }
           }
         }
-        if (parser2) {
-          const result = parser2.parse(input, pos, ctx);
+        if (idx >= 0) {
+          const gate = gates[idx];
+          if (gate && !gate(ctx.state)) {
+            return { ok: false, expected: deriveExpected(parsers[idx]), span: { start: pos, end: pos } };
+          }
+          const result = parsers[idx].parse(input, pos, ctx);
           if (result.ok) return result;
           expected.push(...result.expected);
           return { ok: false, expected, span: { start: pos, end: pos } };
@@ -1105,13 +1263,13 @@ function areDisjoint(sets) {
   return true;
 }
 function buildAsciiDispatch(parsers) {
-  const table = Array(128).fill(null);
-  for (const parser2 of parsers) {
-    const fs2 = parser2._meta.firstSet;
+  const table = Array(128).fill(-1);
+  for (let i = 0; i < parsers.length; i++) {
+    const fs2 = parsers[i]._meta.firstSet;
     if (fs2.kind !== "ranges") continue;
     for (const { lo, hi } of fs2.ranges) {
       for (let code = Math.max(0, lo); code <= Math.min(127, hi); code++) {
-        table[code] = parser2;
+        table[code] = i;
       }
     }
   }
@@ -1256,10 +1414,10 @@ function needsDeferredTriviaCommit(ctx) {
 }
 function saveTriviaMark(ctx) {
   const m = saveCstMark(ctx);
-  return { raw: m.raw, tlog: m.tlog, leaves: m.leaves, fields: m.fields, log: ctx._triviaLog ? ctx._triviaLog.length : 0 };
+  return { raw: m.raw, tlog: m.tlog, leaves: m.leaves, fields: m.fields, errors: m.errors, log: ctx._triviaLog ? ctx._triviaLog.length : 0 };
 }
 function rollbackTrivia(ctx, mark) {
-  rollbackCstCapture(ctx, { raw: mark.raw, tlog: mark.tlog, leaves: mark.leaves, fields: mark.fields });
+  rollbackCstCapture(ctx, { raw: mark.raw, tlog: mark.tlog, leaves: mark.leaves, fields: mark.fields, errors: mark.errors });
   if (ctx._triviaLog) ctx._triviaLog.length = mark.log;
 }
 function scanWithLabels(input, cur, ctx) {
@@ -1503,11 +1661,59 @@ function sequence(...parsers) {
     isTrivia: false
   };
   const def = { tag: "sequence", parsers };
+  let followSentinels;
+  function parseTolerant(input, pos, ctx) {
+    followSentinels ??= parsers.map((_, i) => {
+      const fs2 = parsers.slice(i + 1).reduce(
+        (acc, p) => union(acc, firstSetOf(p)),
+        { kind: "empty" }
+      );
+      return firstSetSentinel(fs2);
+    });
+    const values = def.valueUnused ? void 0 : [];
+    let cur = pos;
+    const inheritedSync = ctx._sync;
+    try {
+      for (let i = 0; i < parsers.length; i++) {
+        ctx._sync = followSentinels[i] ?? inheritedSync;
+        if (ctx.trivia && i > 0) {
+          const mark = saveTriviaMark(ctx);
+          let scanEnd;
+          if (needsDeferredTriviaCommit(ctx)) {
+            const scan = scanTrivia(input, cur, ctx);
+            scan.commit();
+            scanEnd = scan.end;
+          } else {
+            scanEnd = advanceTrivia(input, cur, ctx);
+          }
+          const result2 = parsers[i].parse(input, scanEnd, ctx);
+          if (!result2.ok) return result2;
+          if (result2.span.end > scanEnd) cur = result2.span.end;
+          else rollbackTrivia(ctx, mark);
+          if (values !== void 0) values.push(result2.value);
+          continue;
+        }
+        const result = parsers[i].parse(input, cur, ctx);
+        if (!result.ok) return result;
+        if (values !== void 0) values.push(result.value);
+        cur = result.span.end;
+      }
+    } finally {
+      ctx._sync = inheritedSync;
+    }
+    return {
+      ok: true,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      value: values ?? void 0,
+      span: { start: pos, end: cur }
+    };
+  }
   return {
     _tag: "sequence",
     _meta: meta,
     _def: def,
     parse(input, pos, ctx) {
+      if (ctx._tolerant) return parseTolerant(input, pos, ctx);
       const values = def.valueUnused ? void 0 : [];
       let cur = pos;
       for (let i = 0; i < parsers.length; i++) {
@@ -1566,7 +1772,7 @@ function repItem(combinator, input, cur, ctx) {
   const result = combinator.parse(input, pos, ctx);
   if (!result.ok) {
     rollbackTrivia(ctx, mark);
-    return { fail: result };
+    return { fail: result, failPos: pos };
   }
   if (result.span.end === pos) {
     rollbackTrivia(ctx, mark);
@@ -1581,6 +1787,7 @@ function many(combinator) {
     isTrivia: false
   };
   const def = { tag: "many", parser: combinator, min: 0 };
+  let expected;
   return {
     _tag: "many",
     _meta: meta,
@@ -1590,7 +1797,18 @@ function many(combinator) {
       let cur = pos;
       while (cur < input.length) {
         const item = repItem(combinator, input, cur, ctx);
-        if (item === "stop" || "fail" in item) break;
+        if (item === "stop") break;
+        if ("fail" in item) {
+          const sync = ctx._tolerant ? ctx._sync : void 0;
+          if (sync === void 0) break;
+          if (matchesAt(sync, input, item.failPos, ctx)) break;
+          expected ??= deriveExpected(combinator);
+          const { error, end } = recoverScan(input, item.failPos, ctx, sync, expected);
+          if (values !== void 0) values.push(error);
+          captureError(ctx, error);
+          cur = end;
+          continue;
+        }
         if (values !== void 0) values.push(item.value);
         cur = item.end;
       }
@@ -1605,6 +1823,7 @@ function oneOrMore(combinator) {
     isTrivia: false
   };
   const def = { tag: "oneOrMore", parser: combinator, min: 1 };
+  let expected;
   return {
     _tag: "oneOrMore",
     _meta: meta,
@@ -1616,7 +1835,18 @@ function oneOrMore(combinator) {
       let cur = first.span.end;
       while (cur < input.length) {
         const item = repItem(combinator, input, cur, ctx);
-        if (item === "stop" || "fail" in item) break;
+        if (item === "stop") break;
+        if ("fail" in item) {
+          const sync = ctx._tolerant ? ctx._sync : void 0;
+          if (sync === void 0) break;
+          if (matchesAt(sync, input, item.failPos, ctx)) break;
+          expected ??= deriveExpected(combinator);
+          const { error, end } = recoverScan(input, item.failPos, ctx, sync, expected);
+          if (values !== void 0) values.push(error);
+          captureError(ctx, error);
+          cur = end;
+          continue;
+        }
         if (values !== void 0) values.push(item.value);
         cur = item.end;
       }
@@ -1662,15 +1892,29 @@ function sepBy(combinator, separator) {
     canMatchNewline: combinator._meta.canMatchNewline || separator._meta.canMatchNewline,
     isTrivia: false
   };
+  let expected;
   return {
     _tag: "sepBy",
     _meta: meta,
     _def: { tag: "sepBy", parser: combinator, separator },
     parse(input, pos, ctx) {
       const first = combinator.parse(input, pos, ctx);
-      if (!first.ok) return { ok: true, value: [], span: { start: pos, end: pos } };
-      const values = [first.value];
-      let cur = first.span.end;
+      const values = [];
+      let cur;
+      if (first.ok) {
+        values.push(first.value);
+        cur = first.span.end;
+      } else {
+        const term = ctx._tolerant ? ctx._sync : void 0;
+        if (term === void 0 || matchesAt(term, input, pos, ctx)) {
+          return { ok: true, value: [], span: { start: pos, end: pos } };
+        }
+        expected ??= deriveExpected(combinator);
+        const rec = recoverScan(input, pos, ctx, orSentinel(separator, term), expected);
+        values.push(rec.error);
+        captureError(ctx, rec.error);
+        cur = rec.end;
+      }
       while (cur < input.length) {
         const loopMark = saveTriviaMark(ctx);
         let sepPos = cur;
@@ -1700,6 +1944,15 @@ function sepBy(combinator, separator) {
         }
         const next = combinator.parse(input, nextPos, ctx);
         if (!next.ok) {
+          const term = ctx._tolerant ? ctx._sync : void 0;
+          if (term !== void 0 && !matchesAt(term, input, nextPos, ctx)) {
+            expected ??= deriveExpected(combinator);
+            const rec = recoverScan(input, nextPos, ctx, orSentinel(separator, term), expected);
+            values.push(rec.error);
+            captureError(ctx, rec.error);
+            cur = rec.end;
+            continue;
+          }
           rollbackTrivia(ctx, loopMark);
           break;
         }
@@ -1836,7 +2089,7 @@ function rules(a, b) {
       cache[key] = parser2;
     }
   }
-  if (options?.trivia !== void 0) {
+  if (options?.trivia != null) {
     for (const key of Object.keys(definitions)) {
       const rule = cache[key];
       if (rule && !rule._meta.isTrivia) rule._meta.grammarTrivia = options.trivia;
@@ -1866,7 +2119,9 @@ function not(combinator) {
     _meta: meta,
     _def: { tag: "not", parser: combinator },
     parse(input, pos, ctx) {
+      const mark = saveCstMark(ctx);
       const result = combinator.parse(input, pos, ctx);
+      rollbackCstCapture(ctx, mark);
       if (result.ok) {
         return { ok: false, expected: [`not(${combinator._tag})`], span: { start: pos, end: pos } };
       }
@@ -1980,7 +2235,7 @@ function unwrapChild(child) {
   return child !== null && typeof child === "object" && child._tag === "leaf" ? child.value : child;
 }
 function isCstChild(value) {
-  return typeof value === "object" && value !== null && (value._tag === "node" || value._tag === "leaf" || value._tag === "error");
+  return typeof value === "object" && value !== null && (value._tag === "node" || value._tag === "leaf" || value._tag === "parseError");
 }
 function missingInferredType() {
   throw new Error('node(): inferred node type requires a rules() key; pass node("Type", parser) outside rules()');
@@ -2233,65 +2488,6 @@ function token(root) {
   };
 }
 
-// src/combinators/expect.ts
-function deriveExpected(c) {
-  const def = c._def;
-  switch (def.tag) {
-    case "literal":
-      return [JSON.stringify(def.value)];
-    case "regex":
-      return [`/${def.source}/`];
-    case "keywords":
-      return def.words.map((w) => JSON.stringify(w));
-    case "label":
-      return [def.label];
-    case "choice":
-      return def.parsers.flatMap(deriveExpected);
-    case "sequence":
-      return def.parsers.length > 0 ? deriveExpected(def.parsers[0]) : [];
-    case "node":
-    case "grammar":
-    case "trivia":
-    case "token":
-    case "optional":
-    case "many":
-    case "oneOrMore":
-    case "transform":
-    case "not":
-      return deriveExpected(def.parser);
-    case "lazy": {
-      const name = c._ruleName;
-      try {
-        return deriveExpected(def.thunk());
-      } catch {
-        return name ? [name] : [];
-      }
-    }
-    default:
-      return [];
-  }
-}
-function expect(combinator, label2) {
-  const expected = label2 !== void 0 ? [label2] : deriveExpected(combinator);
-  const meta = {
-    firstSet: combinator._meta.firstSet,
-    canMatchNewline: combinator._meta.canMatchNewline,
-    isTrivia: false
-  };
-  return {
-    _tag: "expect",
-    _meta: meta,
-    _def: { tag: "expect", parser: combinator, label: label2, expected },
-    parse(input, pos, ctx) {
-      const result = combinator.parse(input, pos, ctx);
-      if (result.ok) return result;
-      const error = { _tag: "parseError", span: { start: pos, end: pos }, expected };
-      ctx._errors?.push(error);
-      return { ok: true, value: error, span: { start: pos, end: pos } };
-    }
-  };
-}
-
 // src/compiler/scannable-run.ts
 var BACKSLASH = 92;
 var META = new Set("()[]{}*+?|^$.".split(""));
@@ -2363,20 +2559,39 @@ function parseSeqParts(source) {
       lit = [];
     }
   };
-  const runFrom = (ranges, negated, q) => {
+  const braceQuant = (at) => {
+    const close = source.indexOf("}", at);
+    if (close === -1) return null;
+    const body = source.slice(at + 1, close);
+    const m = /^(\d+)(,(\d*)?)?$/.exec(body);
+    if (!m) return null;
+    const min = Number(m[1]);
+    const max = m[2] === void 0 ? min : m[3] ? Number(m[3]) : Infinity;
+    if (max < 1 || min > max) return null;
+    return { min, max, len: close - at + 1 };
+  };
+  const runFrom = (ranges, negated, at) => {
+    const q = source[at];
     if (q === "+") {
-      parts.push({ part: "run", ranges, negated, min: 1, unbounded: true });
+      parts.push({ part: "run", ranges, negated, min: 1, max: Infinity });
       return 1;
     }
     if (q === "*") {
-      parts.push({ part: "run", ranges, negated, min: 0, unbounded: true });
+      parts.push({ part: "run", ranges, negated, min: 0, max: Infinity });
       return 1;
     }
     if (q === "?") {
-      parts.push({ part: "run", ranges, negated, min: 0, unbounded: false });
+      parts.push({ part: "run", ranges, negated, min: 0, max: 1 });
       return 1;
     }
-    parts.push({ part: "run", ranges, negated, min: 1, unbounded: false });
+    if (q === "{") {
+      const b = braceQuant(at);
+      if (b) {
+        parts.push({ part: "run", ranges, negated, min: b.min, max: b.max });
+        return b.len;
+      }
+    }
+    parts.push({ part: "run", ranges, negated, min: 1, max: 1 });
     return 0;
   };
   let i = 0;
@@ -2401,7 +2616,7 @@ function parseSeqParts(source) {
       if (!ranges) return null;
       flush();
       i = k + 1;
-      i += runFrom(ranges, neg, source[i]);
+      i += runFrom(ranges, neg, i);
       continue;
     }
     if (ch === "\\") {
@@ -2409,7 +2624,7 @@ function parseSeqParts(source) {
       if (e === "d" || e === "w" || e === "s") {
         flush();
         i += 2;
-        i += runFrom(shorthandRanges(e), false, source[i]);
+        i += runFrom(shorthandRanges(e), false, i);
         continue;
       }
       const uni = readUnicodeEscape(source, i);
@@ -2498,7 +2713,7 @@ function seqIsUnambiguous(parts) {
   let hasMandatory = false;
   for (let k = 0; k < parts.length; k++) {
     const p = parts[k];
-    const mandatory = p.part === "lit" ? !p.optional : p.min === 1;
+    const mandatory = p.part === "lit" ? !p.optional : p.min >= 1;
     if (mandatory) hasMandatory = true;
     if (p.part === "group") {
       const exposure = groupPartExposure(p);
@@ -2509,9 +2724,8 @@ function seqIsUnambiguous(parts) {
         if (!firstSetsDisjoint(exposure, seqFirstAccept(parts.slice(k + 1)))) return false;
       }
     }
-    const skippableSingle = p.part === "lit" && p.optional || p.part !== "lit" && !p.unbounded && p.min === 0;
-    const isUnboundedRepeat = p.part !== "lit" && p.unbounded;
-    if (skippableSingle || isUnboundedRepeat) {
+    const needsDisjoint = p.part === "lit" ? p.optional : p.part === "run" ? p.max > p.min : p.unbounded || p.min === 0;
+    if (needsDisjoint) {
       const rest = seqFirstAccept(parts.slice(k + 1));
       if (!firstSetsDisjoint(partFirstAccept(p), rest)) return false;
     }
@@ -2568,8 +2782,8 @@ function fixedClassSeq(shape) {
     if (p.part === "lit") {
       if (p.optional) return null;
       for (const cp of p.cps) out.push({ ranges: [[cp, cp]], negated: false });
-    } else if (p.part === "run" && !p.unbounded && p.min === 1) {
-      out.push({ ranges: p.ranges, negated: p.negated });
+    } else if (p.part === "run" && p.max === p.min && Number.isFinite(p.max)) {
+      for (let c = 0; c < p.max; c++) out.push({ ranges: p.ranges, negated: p.negated });
     } else {
       return null;
     }
@@ -2621,7 +2835,7 @@ function trailingBacktrackClass(shape) {
     const last = shape.parts[shape.parts.length - 1];
     if (last.part === "lit") return null;
     if (last.part === "run") {
-      if (last.unbounded || last.min === 0) return { ranges: last.ranges, negated: last.negated };
+      if (last.max > last.min) return { ranges: last.ranges, negated: last.negated };
       return null;
     }
     return groupPartExposure(last);
@@ -2758,7 +2972,7 @@ function partFirstAccept(part) {
 function seqFirstAccept(parts) {
   const sets = [];
   for (const p of parts) {
-    const mandatory = p.part === "lit" ? !p.optional : p.min === 1;
+    const mandatory = p.part === "lit" ? !p.optional : p.min >= 1;
     sets.push(partFirstAccept(p));
     if (mandatory) break;
   }
@@ -3173,7 +3387,13 @@ function emitShapeMatch(shape, start, mint, ind2, firstChar) {
           lines.push(`${ind2}  if (!(${endV2} + ${L} <= input.length && (${cond}))) break`);
           lines.push(`${ind2}  ${endV2} += ${L}`);
         }
-      } else if (p.part === "run" && !p.unbounded) {
+      } else if (p.part === "run" && p.max === Infinity) {
+        const s = mint("_s");
+        lines.push(`${ind2}  const ${s} = ${endV2}`);
+        lines.push(`${ind2}  while (${endV2} < input.length && ${runCond(p, endV2)}) ${endV2}++`);
+        if (p.min === 1) lines.push(`${ind2}  if (${endV2} === ${s}) break`);
+        else if (p.min > 1) lines.push(`${ind2}  if (${endV2} - ${s} < ${p.min}) break`);
+      } else if (p.part === "run" && p.max === 1) {
         if (p.min === 1) {
           lines.push(`${ind2}  if (!(${endV2} < input.length && ${runCond(p, endV2)})) break`);
           lines.push(`${ind2}  ${endV2}++`);
@@ -3183,8 +3403,8 @@ function emitShapeMatch(shape, start, mint, ind2, firstChar) {
       } else if (p.part === "run") {
         const s = mint("_s");
         lines.push(`${ind2}  const ${s} = ${endV2}`);
-        lines.push(`${ind2}  while (${endV2} < input.length && ${runCond(p, endV2)}) ${endV2}++`);
-        if (p.min === 1) lines.push(`${ind2}  if (${endV2} === ${s}) break`);
+        lines.push(`${ind2}  while (${endV2} - ${s} < ${p.max} && ${endV2} < input.length && ${runCond(p, endV2)}) ${endV2}++`);
+        if (p.min > 0) lines.push(`${ind2}  if (${endV2} - ${s} < ${p.min}) break`);
       } else {
         const inner = emitShapeMatch(p.inner, endV2, mint, `${ind2}  `, first ? firstChar : void 0);
         if (!p.unbounded) {
@@ -3651,21 +3871,29 @@ function hoistExpected(ctx, constArrSource) {
   }
   return name;
 }
+function probeUpdate(ctx, expectedArr, posExpr, constant = true) {
+  if (!ctx.recovery) return "";
+  const fx = constant ? hoistExpected(ctx, expectedArr) : expectedArr;
+  const pb = v(ctx, "_pb");
+  return `if (_ctx._probe !== undefined && ${posExpr} <= _ctx._probe.offset) { const ${pb} = _ctx._probe.best; if (${pb} === null || ${posExpr} > ${pb}.span.start) _ctx._probe.best = { ok: false, expected: [...${fx}], span: { start: ${posExpr}, end: ${posExpr} } }; else if (${posExpr} === ${pb}.span.start) _ctx._probe.best = { ok: false, expected: [...${pb}.expected, ...${fx}], span: { start: ${posExpr}, end: ${posExpr} } } } `;
+}
 function failBody(ctx, expected, posExpr) {
+  const probe = probeUpdate(ctx, `[${expected}]`, posExpr);
   if (ctx.failLabel) {
-    if (!ctx.recordFail) return `break ${ctx.failLabel}`;
-    return `{ _ctx._fe = ${posExpr}; _ctx._fx = ${hoistExpected(ctx, `[${expected}]`)}; break ${ctx.failLabel} }`;
+    if (!ctx.recordFail) return probe ? `{ ${probe}break ${ctx.failLabel} }` : `break ${ctx.failLabel}`;
+    return `{ ${probe}_ctx._fe = ${posExpr}; _ctx._fx = ${hoistExpected(ctx, `[${expected}]`)}; break ${ctx.failLabel} }`;
   }
-  return failReturn(expected, posExpr);
+  return probe + failReturn(expected, posExpr);
 }
 function failArrBody(ctx, expectedArr, posExpr, constant = true) {
+  const probe = probeUpdate(ctx, expectedArr, posExpr, constant);
   if (ctx.failLabel) {
-    if (!ctx.recordFail) return `break ${ctx.failLabel}`;
+    if (!ctx.recordFail) return probe ? `{ ${probe}break ${ctx.failLabel} }` : `break ${ctx.failLabel}`;
     const fx = constant ? hoistExpected(ctx, expectedArr) : expectedArr;
-    return `{ _ctx._fe = ${posExpr}; _ctx._fx = ${fx}; break ${ctx.failLabel} }`;
+    return `{ ${probe}_ctx._fe = ${posExpr}; _ctx._fx = ${fx}; break ${ctx.failLabel} }`;
   }
-  if (!constant) return `return { ok: false, expected: [...${expectedArr}], span: { start: ${posExpr}, end: ${posExpr} } }`;
-  return failReturnArr(expectedArr, posExpr);
+  if (!constant) return `${probe}return { ok: false, expected: [...${expectedArr}], span: { start: ${posExpr}, end: ${posExpr} } }`;
+  return probe + failReturnArr(expectedArr, posExpr);
 }
 function resultFromRecorded(feExpr = "_ctx._fe", fxExpr = "_ctx._fx") {
   return `return { ok: false, expected: [...${fxExpr}], span: { start: ${feExpr}, end: ${feExpr} } }`;
@@ -4165,6 +4393,10 @@ function emitRegex(def, ctx, pos) {
   stmts.push(...emitLeafCapture(ctx, vv, pos, endVar));
   return { stmts, valueVar: vv, endVar };
 }
+function syncSentinelExpr(fs2) {
+  if (fs2.kind !== "ranges" || fs2.ranges.length === 0) return null;
+  return `_ctx._rec.sentinel({ kind: 'ranges', ranges: ${JSON.stringify(fs2.ranges)} })`;
+}
 function emitSeqValues(def, ctx, pos) {
   const startV = v(ctx, "_start");
   const curV = v(ctx, "_cur");
@@ -4173,7 +4405,17 @@ function emitSeqValues(def, ctx, pos) {
     `${ind(ctx)}let ${curV} = ${pos}`
   ];
   const valueVars = [];
+  const syncInV = ctx.recovery ? v(ctx, "_syncIn") : "";
+  if (ctx.recovery) stmts.push(`${ind(ctx)}const ${syncInV} = _ctx._sync`);
+  const publishSync = (i) => {
+    if (!ctx.recovery) return "";
+    const fs2 = def.parsers.slice(i + 1).reduce((acc, p) => union(acc, firstSetOf(p)), { kind: "empty" });
+    const ref2 = syncSentinelExpr(fs2);
+    return `${ind(ctx)}if (_ctx._tolerant) _ctx._sync = ${ref2 ?? syncInV}`;
+  };
   for (let i = 0; i < def.parsers.length; i++) {
+    const syncPub = publishSync(i);
+    if (syncPub) stmts.push(syncPub);
     if (i > 0 && ctx.activeTrivia) {
       if (ctx.capturing) {
         const capFn = ensureTriviaCaptureFn(ctx);
@@ -4198,7 +4440,17 @@ function emitSeqValues(def, ctx, pos) {
         continue;
       } else {
         const trivFn = ensureTriviaFn(ctx);
-        stmts.push(`${ind(ctx)}${curV} = ${trivFn}(input, ${curV}, _ctx)`);
+        const scanEndV = v(ctx, "_sne");
+        stmts.push(`${ind(ctx)}const ${scanEndV} = ${trivFn}(input, ${curV}, _ctx)`);
+        const r2 = emit(def.parsers[i], ctx, scanEndV);
+        stmts.push(...r2.stmts);
+        const endAfterV = v(ctx, "_sea");
+        stmts.push(
+          `${ind(ctx)}const ${endAfterV} = ${r2.endVar}`,
+          `${ind(ctx)}if (${endAfterV} > ${scanEndV}) ${curV} = ${endAfterV}`
+        );
+        valueVars.push(r2.valueVar);
+        continue;
       }
     }
     const r = emit(def.parsers[i], ctx, curV);
@@ -4276,6 +4528,21 @@ function emitDisjointArm(p, ctx, pos, valV, endV) {
     `${ind(ctx)}${endV} = ${endVar}`
   ];
 }
+function emitDisjointArmGated(def, i, ctx, pos, valV, endV) {
+  const p = def.parsers[i];
+  const gate = def.gates[i];
+  if (!gate) return emitDisjointArm(p, ctx, pos, valV, endV);
+  const gateIdx = ctx.mapFns.length;
+  ctx.mapFns.push(gate);
+  ctx.mapFnSrcs.push(def.gateSrcs?.[i] ?? null);
+  const gateCond = `${mfRef(ctx)}[${gateIdx}](_ctx.state)`;
+  const stmts = [`${ind(ctx)}if (${gateCond}) {`];
+  ctx.indent++;
+  stmts.push(...emitDisjointArm(p, ctx, pos, valV, endV));
+  ctx.indent--;
+  stmts.push(`${ind(ctx)}} else { ${failArrBody(ctx, deriveExpectedArr([p]), pos)} }`);
+  return stmts;
+}
 function emitChoice(def, ctx, pos) {
   const allExpected = deriveExpectedArr(def.parsers);
   if (def.disjoint) {
@@ -4291,12 +4558,11 @@ function emitChoice(def, ctx, pos) {
       stmts.push(`${ind(ctx)}switch (${codeV}) {`);
       ctx.indent++;
       for (let i = 0; i < def.parsers.length; i++) {
-        const p = def.parsers[i];
         for (const cp of plan.cases[i]) stmts.push(`${ind(ctx)}case ${cp}:`);
         stmts.push(`${ind(ctx)}{`);
         ctx.indent++;
         stmts.push(
-          ...emitDisjointArm(p, ctx, pos, valV, endV),
+          ...emitDisjointArmGated(def, i, ctx, pos, valV, endV),
           `${ind(ctx)}break`
         );
         ctx.indent--;
@@ -4308,13 +4574,14 @@ function emitChoice(def, ctx, pos) {
       return { stmts, valueVar: valV, endVar: endV };
     }
     let first = true;
-    for (const p of def.parsers) {
+    for (let i = 0; i < def.parsers.length; i++) {
+      const p = def.parsers[i];
       const cond = firstSetCond(codeV, p._meta.firstSet);
       const kw = first ? "if" : "else if";
       first = false;
       stmts.push(`${ind(ctx)}${kw} (${cond}) {`);
       ctx.indent++;
-      stmts.push(...emitDisjointArm(p, ctx, pos, valV, endV));
+      stmts.push(...emitDisjointArmGated(def, i, ctx, pos, valV, endV));
       ctx.indent--;
       stmts.push(`${ind(ctx)}}`);
     }
@@ -4428,7 +4695,7 @@ function emitFirstMatch(def, ctx, pos) {
     if (gate) {
       const gateIdx = ctx.mapFns.length;
       ctx.mapFns.push(gate);
-      ctx.mapFnSrcs.push(null);
+      ctx.mapFnSrcs.push(def.gateSrcs?.[i] ?? null);
       gateCond = `${mfRef(ctx)}[${gateIdx}](_ctx.state)`;
     }
     const skipCond = gateCond ? `!${resOkV} && ${gateCond}` : `!${resOkV}`;
@@ -4533,6 +4800,8 @@ function emitMany(def, ctx, pos) {
     ...wantValue ? [`${ind(ctx)}const ${arrV} = []`] : [],
     `${ind(ctx)}let ${curV} = ${pos}`
   ];
+  const mySyncV = ctx.recovery ? v(ctx, "_mysy") : "";
+  if (ctx.recovery) stmts.push(`${ind(ctx)}const ${mySyncV} = _ctx._sync`);
   if (def.min === 1) {
     const firstR = emit(def.parser, ctx, curV);
     stmts.push(...firstR.stmts);
@@ -4566,10 +4835,26 @@ function emitMany(def, ctx, pos) {
     }
   }
   const { stmts: iterStmts, okVar: iterOk, valVar: iterVal, endVar: iterEnd } = emitFallible(def.parser, ctx, itemPos, true);
-  stmts.push(
-    ...iterStmts,
-    `${ind(ctx)}if (!${iterOk} || ${iterEnd} <= ${itemPos}) { ${rollback}break }`
-  );
+  stmts.push(...iterStmts);
+  if (ctx.recovery) {
+    const rrV = v(ctx, "_rr");
+    const exp = hoistExpected(ctx, deriveExpectedArr([def.parser]));
+    stmts.push(
+      `${ind(ctx)}if (!${iterOk}) {`,
+      `${ind(ctx)}  ${rollback}if (_ctx._tolerant && ${mySyncV} !== undefined && !_ctx._rec.at(${mySyncV}, input, ${itemPos}, _ctx)) {`,
+      `${ind(ctx)}    const ${rrV} = _ctx._rec.scan(input, ${itemPos}, _ctx, ${mySyncV}, ${exp})`,
+      ...wantValue ? [`${ind(ctx)}    ${arrV}.push(${rrV}.error)`] : [],
+      `${ind(ctx)}    _ctx._rec.capture(_ctx, ${rrV}.error)`,
+      `${ind(ctx)}    ${curV} = ${rrV}.end`,
+      `${ind(ctx)}    continue`,
+      `${ind(ctx)}  }`,
+      `${ind(ctx)}  break`,
+      `${ind(ctx)}}`,
+      `${ind(ctx)}if (${iterEnd} <= ${itemPos}) { ${rollback}break }`
+    );
+  } else {
+    stmts.push(`${ind(ctx)}if (!${iterOk} || ${iterEnd} <= ${itemPos}) { ${rollback}break }`);
+  }
   if (wantValue) stmts.push(`${ind(ctx)}${arrV}.push(${iterVal})`);
   stmts.push(`${ind(ctx)}${curV} = ${iterEnd}`);
   ctx.indent--;
@@ -4591,20 +4876,56 @@ function emitOptional(def, ctx, pos) {
 function emitSepBy(_p, def, ctx, pos) {
   const arrV = v(ctx, "_arr");
   const curV = v(ctx, "_cur");
+  const rec = !!ctx.recovery;
+  const mySyncV = rec ? v(ctx, "_mysy") : "";
+  const exp = rec ? hoistExpected(ctx, deriveExpectedArr([def.parser])) : "";
+  const sepSent = rec ? syncSentinelExpr(firstSetOf(def.separator)) : null;
+  const scanSync = sepSent ? `_ctx._rec.or(${sepSent}, ${mySyncV})` : mySyncV;
   const { stmts: firstStmts, okVar: firstOk, valVar: firstVal, endVar: firstEnd } = emitFallible(def.parser, ctx, pos, true);
   const stmts = [
     `${ind(ctx)}const ${arrV} = []`,
     `${ind(ctx)}let ${curV} = ${pos}`,
-    ...firstStmts,
-    `${ind(ctx)}if (${firstOk}) {`
+    ...rec ? [`${ind(ctx)}const ${mySyncV} = _ctx._sync`] : [],
+    ...firstStmts
   ];
-  ctx.indent++;
-  stmts.push(
-    `${ind(ctx)}${arrV}.push(${firstVal})`,
-    `${ind(ctx)}${curV} = ${firstEnd}`,
-    `${ind(ctx)}while (${curV} < input.length) {`
-  );
-  ctx.indent++;
+  const failItem = (nextOkVar, itemPosVar, rb, originalFail) => {
+    if (!rec) return [originalFail];
+    const rr = v(ctx, "_rr");
+    return [
+      `${ind(ctx)}if (!${nextOkVar}) {`,
+      `${ind(ctx)}  if (_ctx._tolerant && ${mySyncV} !== undefined && !_ctx._rec.at(${mySyncV}, input, ${itemPosVar}, _ctx)) {`,
+      `${ind(ctx)}    const ${rr} = _ctx._rec.scan(input, ${itemPosVar}, _ctx, ${scanSync}, ${exp})`,
+      `${ind(ctx)}    ${arrV}.push(${rr}.error); _ctx._rec.capture(_ctx, ${rr}.error); ${curV} = ${rr}.end; continue`,
+      `${ind(ctx)}  }`,
+      `${ind(ctx)}  ${rb}break`,
+      `${ind(ctx)}}`
+    ];
+  };
+  if (rec) {
+    const rr0 = v(ctx, "_rr0");
+    const didV = v(ctx, "_did");
+    stmts.push(
+      `${ind(ctx)}let ${didV} = false`,
+      `${ind(ctx)}if (${firstOk}) { ${arrV}.push(${firstVal}); ${curV} = ${firstEnd}; ${didV} = true }`,
+      `${ind(ctx)}else if (_ctx._tolerant && ${mySyncV} !== undefined && !_ctx._rec.at(${mySyncV}, input, ${pos}, _ctx)) {`,
+      `${ind(ctx)}  const ${rr0} = _ctx._rec.scan(input, ${pos}, _ctx, ${scanSync}, ${exp})`,
+      `${ind(ctx)}  ${arrV}.push(${rr0}.error); _ctx._rec.capture(_ctx, ${rr0}.error); ${curV} = ${rr0}.end; ${didV} = true`,
+      `${ind(ctx)}}`,
+      `${ind(ctx)}if (${didV}) {`
+    );
+    ctx.indent++;
+    stmts.push(`${ind(ctx)}while (${curV} < input.length) {`);
+    ctx.indent++;
+  } else {
+    stmts.push(`${ind(ctx)}if (${firstOk}) {`);
+    ctx.indent++;
+    stmts.push(
+      `${ind(ctx)}${arrV}.push(${firstVal})`,
+      `${ind(ctx)}${curV} = ${firstEnd}`,
+      `${ind(ctx)}while (${curV} < input.length) {`
+    );
+    ctx.indent++;
+  }
   let sepAtPos = curV;
   if (ctx.activeTrivia) {
     if (ctx.capturing) {
@@ -4630,8 +4951,7 @@ function emitSepBy(_p, def, ctx, pos) {
       const { stmts: nextStmts, okVar: nextOk, valVar: nextVal, endVar: nextEnd } = emitFallible(def.parser, ctx, npV, true);
       stmts.push(
         ...nextStmts,
-        // item failed → unwind the separator too, back to the end of the last item
-        `${ind(ctx)}if (!${nextOk}) { ${rollbackToSep}break }`,
+        ...failItem(nextOk, npV, rollbackToSep, `${ind(ctx)}if (!${nextOk}) { ${rollbackToSep}break }`),
         `${ind(ctx)}${arrV}.push(${nextVal})`,
         `${ind(ctx)}${curV} = ${nextEnd}`
       );
@@ -4647,7 +4967,7 @@ function emitSepBy(_p, def, ctx, pos) {
       const { stmts: nextStmts, okVar: nextOk, valVar: nextVal, endVar: nextEnd } = emitFallible(def.parser, ctx, npV, true);
       stmts.push(
         ...nextStmts,
-        `${ind(ctx)}if (!${nextOk}) break`,
+        ...failItem(nextOk, npV, "", `${ind(ctx)}if (!${nextOk}) break`),
         `${ind(ctx)}${arrV}.push(${nextVal})`,
         `${ind(ctx)}${curV} = ${nextEnd}`
       );
@@ -4667,7 +4987,7 @@ function emitSepBy(_p, def, ctx, pos) {
     const { stmts: nextStmts, okVar: nextOk, valVar: nextVal, endVar: nextEnd } = emitFallible(def.parser, ctx, sepEnd, true);
     stmts.push(
       ...nextStmts,
-      `${ind(ctx)}if (!${nextOk}) { ${nextRb}break }`,
+      ...failItem(nextOk, sepEnd, nextRb, `${ind(ctx)}if (!${nextOk}) { ${nextRb}break }`),
       `${ind(ctx)}${arrV}.push(${nextVal})`,
       `${ind(ctx)}${curV} = ${nextEnd}`
     );
@@ -4924,7 +5244,7 @@ ${i}const ${chV} = [], ${rawV} = [], ${tlV} = ${capTLv} ? [] : _EMPTY_TL` : capt
   stmts.push(
     `${i}const ${ndV} = ${finalExpr}`,
     `${i}if (${sc}) ${sc}.push(${ndV})`,
-    `${i}if (${sr}) ${sr}.push((typeof ${ndV} === 'object' && ${ndV} !== null && (${ndV}._tag === 'node' || ${ndV}._tag === 'leaf' || ${ndV}._tag === 'error')) ? ${ndV} : { _tag: 'leaf', value: typeof ${ndV} === 'string' ? ${ndV} : '', span: { start: ${pos}, end: ${endVar} } })`
+    `${i}if (${sr}) ${sr}.push((typeof ${ndV} === 'object' && ${ndV} !== null && (${ndV}._tag === 'node' || ${ndV}._tag === 'leaf' || ${ndV}._tag === 'parseError')) ? ${ndV} : { _tag: 'leaf', value: typeof ${ndV} === 'string' ? ${ndV} : '', span: { start: ${pos}, end: ${endVar} } })`
   );
   return { stmts, valueVar: ndV, endVar };
 }
@@ -5014,6 +5334,10 @@ function emitExpect(def, ctx, pos) {
     `${ind0}if (!${okVar}) {`,
     `${ind0}  const ${errV} = { _tag: 'parseError', span: { start: ${pos}, end: ${pos} }, expected: ${JSON.stringify(def.expected)} }`,
     `${ind0}  if (_ctx._errors) _ctx._errors.push(${errV})`,
+    // Embed the missing-token error as a `parseError` CST child, mirroring the
+    // interpreter (expect.ts) and the list-recovery emit sites — guarded on
+    // `_ctx._tolerant`, under which the driver always installs `_ctx._rec`.
+    `${ind0}  if (_ctx._tolerant) _ctx._rec.capture(_ctx, ${errV})`,
     `${ind0}  ${valVar} = ${errV}`,
     `${ind0}  ${endVar} = ${pos}`,
     `${ind0}  ${okVar} = true`,
@@ -5180,7 +5504,7 @@ function emitDispatch(p, ctx, pos) {
     case "guard": {
       const fnIdx = ctx.mapFns.length;
       ctx.mapFns.push(def.predicate);
-      ctx.mapFnSrcs.push(null);
+      ctx.mapFnSrcs.push(def.predSrc ?? null);
       const vv = v(ctx);
       return {
         stmts: [
@@ -5195,7 +5519,7 @@ function emitDispatch(p, ctx, pos) {
       const evIdx = ctx.mapFns.length;
       const extra = def.extra;
       ctx.mapFns.push((() => extra));
-      ctx.mapFnSrcs.push(null);
+      ctx.mapFnSrcs.push(def.extraSrc !== void 0 ? `() => (${def.extraSrc})` : null);
       const innerParser = def.parser;
       if (!ctx.namedParsers.has(innerParser)) {
         const fnName = `_wcf${ctx.namedParsers.size}`;
@@ -5439,7 +5763,7 @@ function ruleDependencies(ruleMap) {
   }
   return deps;
 }
-function compile(combinator, mapFnSources) {
+function compile(combinator, mapFnSources, opts) {
   markUnusedValues(combinator);
   const grammarTrivia = combinator._meta.grammarTrivia;
   const ctx = {
@@ -5460,6 +5784,7 @@ function compile(combinator, mapFnSources) {
     triviaFnNames: /* @__PURE__ */ new Map(),
     namedFnDecls: [],
     capturing: hasNodeDef(combinator),
+    recovery: opts?.recovery ?? false,
     lazyUsage: analyzeLazyUsage(combinator),
     ...grammarTrivia ? { activeTrivia: grammarTrivia, triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {}
   };
@@ -5512,7 +5837,7 @@ function compile(combinator, mapFnSources) {
     parseWithContext(input, parseCtx, pos = 0) {
       return fn(input, pos, ctx.runtimeParsers, ctx.mapFns, ctx.buildFns, parseCtx);
     },
-    // Note: collects recover()/expect() errors via _errors. Unlike interpreter
+    // Note: collects expect() errors via _errors. Unlike interpreter
     // parse({recover:true}) it does NOT populate furthestFail — the compiled path
     // inlines failures for throughput and deliberately skips _probe bookkeeping.
     // Callers wanting a furthest-position diagnostic detect unconsumed input
@@ -5558,6 +5883,7 @@ function compileRuleMap(ruleMap, opts) {
     triviaFnNames: /* @__PURE__ */ new Map(),
     namedFnDecls: [],
     capturing: ruleMap.some(([, rule]) => hasNodeDef(rule)),
+    recovery: opts?.recovery ?? false,
     lazyUsage: analyzeLazyUsageMulti(ruleMap.map(([, rule]) => rule)),
     ...grammarTrivia ? { activeTrivia: grammarTrivia, triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {}
   };
@@ -5653,6 +5979,7 @@ function compileLinkable(ruleMapArg, ns, opts) {
     triviaFnNames: /* @__PURE__ */ new Map(),
     namedFnDecls: [],
     capturing: ruleMap.some(([, rule]) => hasNodeDef(rule)),
+    recovery: opts?.recovery ?? false,
     lazyUsage: analyzeLazyUsageMulti(ruleMap.map(([, rule]) => rule)),
     ns,
     deferFirstSetRefs: true,
@@ -6300,6 +6627,42 @@ function materializePiece(p, trivia2) {
   return pieces;
 }
 
+// src/combinators/guard.ts
+function guard(predicate) {
+  const meta = {
+    firstSet: { kind: "any" },
+    canMatchNewline: false,
+    isTrivia: false
+  };
+  return {
+    _tag: "guard",
+    _meta: meta,
+    _def: { tag: "guard", predicate },
+    parse(_input, pos, ctx) {
+      if (predicate(ctx.state))
+        return { ok: true, value: null, span: { start: pos, end: pos } };
+      return { ok: false, expected: ["guard"], span: { start: pos, end: pos } };
+    }
+  };
+}
+
+// src/combinators/withCtx.ts
+function withCtx(extra, combinator) {
+  const meta = {
+    firstSet: combinator._meta.firstSet,
+    canMatchNewline: combinator._meta.canMatchNewline,
+    isTrivia: false
+  };
+  return {
+    _tag: "withCtx",
+    _meta: meta,
+    _def: { tag: "withCtx", extra, parser: combinator },
+    parse(input, pos, ctx) {
+      return combinator.parse(input, pos, { ...ctx, state: extra });
+    }
+  };
+}
+
 // src/cst/offset-model.ts
 var { isFinite } = Number;
 
@@ -6331,6 +6694,35 @@ var SUPPORTED = {
 function isScopeEntry(v2) {
   return !!v2 && typeof v2 === "object" && "combi" in v2 && "mfSrcs" in v2;
 }
+function propName(p) {
+  if (p.computed) return null;
+  const key = p.key;
+  return key.type === "Identifier" ? key.name ?? null : key.type === "Literal" ? String(key.value) : null;
+}
+function isGatedArmExpr(e) {
+  if (e.type !== "ObjectExpression") return false;
+  let hasGate = false, hasCombinator = false;
+  for (const prop of e.properties) {
+    if (prop.type !== "Property") continue;
+    const name = propName(prop);
+    if (name === "gate") hasGate = true;
+    else if (name === "combinator") hasCombinator = true;
+  }
+  return hasGate && hasCombinator;
+}
+function gatedArmParts(e) {
+  let gate;
+  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;
+    else if (name === "combinator") combinator = op.value;
+    else return null;
+  }
+  return gate && combinator ? { gate, combinator } : null;
+}
 function isCombinator(v2) {
   return !!v2 && typeof v2 === "object" && "_def" in v2;
 }
@@ -6512,6 +6904,72 @@ function exprToCombi(node2, scope, code, mfs) {
       return null;
     }
   }
+  if (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 = code.slice(predArg.start, predArg.end);
+    mfs.push(predSrc);
+    try {
+      const combi = guard(() => true);
+      if (combi._def.tag !== "guard") return null;
+      combi._def.predSrc = predSrc;
+      return combi;
+    } catch {
+      return null;
+    }
+  }
+  if (callee.name === "withCtx") {
+    if (code === void 0 || mfs === void 0) return null;
+    const [extraArg, innerArg] = node2.arguments;
+    if (!extraArg || !innerArg || extraArg.type === "SpreadElement" || innerArg.type === "SpreadElement") return null;
+    const extraSrc = code.slice(extraArg.start, extraArg.end);
+    mfs.push(extraSrc);
+    const inner = anyValue(innerArg, scope, code, mfs);
+    if (!isCombinator(inner)) return null;
+    try {
+      const combi = withCtx({}, inner);
+      if (combi._def.tag !== "withCtx") return null;
+      combi._def.extraSrc = extraSrc;
+      return combi;
+    } catch {
+      return null;
+    }
+  }
+  if (callee.name === "choice" && node2.arguments.some((a) => a.type !== "SpreadElement" && isGatedArmExpr(a))) {
+    if (code === void 0 || mfs === void 0) return null;
+    const arms = [];
+    const gateSrcs = [];
+    for (const argNode of node2.arguments) {
+      if (argNode.type === "SpreadElement") return null;
+      if (isGatedArmExpr(argNode)) {
+        const parts = gatedArmParts(argNode);
+        if (!parts) return null;
+        const gateSrc = code.slice(parts.gate.start, parts.gate.end);
+        mfs.push(gateSrc);
+        const combi = anyValue(parts.combinator, scope, code, mfs);
+        if (!isCombinator(combi)) return null;
+        arms.push({ gate: () => true, combinator: combi });
+        gateSrcs.push(gateSrc);
+      } else {
+        const combi = anyValue(argNode, scope, code, mfs);
+        if (!isCombinator(combi)) return null;
+        arms.push(combi);
+        gateSrcs.push(null);
+      }
+    }
+    try {
+      const combi = choice(...arms);
+      if (combi._def.tag !== "choice") return null;
+      combi._def.gateSrcs = gateSrcs;
+      for (let i = 0; i < combi._def.gates.length; i++) {
+        if (combi._def.gates[i] !== null !== (gateSrcs[i] !== null)) return null;
+      }
+      return combi;
+    } catch {
+      return null;
+    }
+  }
   const factory = SUPPORTED[callee.name];
   if (!factory) return null;
   const args = node2.arguments.map((arg) => {
@@ -6574,9 +7032,9 @@ function anyValue(node2, scope, code, mfs) {
       if (typeof key !== "string" && typeof key !== "number") return null;
       return obj[key] ?? null;
     }
-    const propName = mem.property.name;
-    if (!propName) return null;
-    return obj[propName] ?? null;
+    const propName2 = mem.property.name;
+    if (!propName2) return null;
+    return obj[propName2] ?? null;
   }
   if (node2.type === "CallExpression") {
     const callee = node2.callee;
@@ -6821,7 +7279,7 @@ var plugin_default = createUnplugin((opts = {}) => ({
     if (!code.includes("parseman")) return null;
     if (!code.includes("macro")) return null;
     const moduleAliases = /* @__PURE__ */ new Set([PARSEMAN_MODULE, ...opts.moduleAliases ?? []]);
-    const result = transformMacro(code, id, moduleAliases, opts.warnUnloweredRegex === true);
+    const result = transformMacro(code, id, moduleAliases, opts.warnUnloweredRegex === true, opts.recovery === true);
     if (result?.warnings.length) {
       for (const w of result.warnings) {
         if (typeof this?.warn === "function") this.warn(`[parseman] ${w}`);
@@ -6925,7 +7383,7 @@ function extractImportBindings(body) {
   }
   return out;
 }
-function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSEMAN_MODULE]), warnUnloweredRegex = false) {
+function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSEMAN_MODULE]), warnUnloweredRegex = false, recovery = false) {
   let result;
   try {
     result = parseSync(id, code);
@@ -6996,7 +7454,7 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
       (p) => p.key?.name === "trivia"
     )?.value : void 0;
     const gTrivia = triviaValue ? evaluateExpr(triviaValue, scope, code, []) : void 0;
-    const compiled = compileRuleMap([...ruleMap], gTrivia ? { trivia: gTrivia } : void 0);
+    const compiled = compileRuleMap([...ruleMap], { ...gTrivia ? { trivia: gTrivia } : {}, recovery });
     if (!compiled) {
       warn(init.start, `${label2}: rule map couldn't be inlined`);
       return null;
@@ -7094,7 +7552,7 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
     const ns = nsFor(label2);
     const ir = serializeRuleMap(entries);
     if (ir) return { carried: [{ ns, ir }] };
-    const p = compileLinkable(entries, ns, composing ? { trivia: composing } : void 0);
+    const p = compileLinkable(entries, ns, { ...composing ? { trivia: composing } : {}, recovery });
     return p ? { carried: [p] } : null;
   };
   const argPieces = (arg, label2, composing) => {
@@ -7270,7 +7728,7 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
           const refEntry = scope.get(varName);
           const refCombi = refEntry?.combi ?? null;
           if (refCombi) {
-            const compiled2 = compile(refCombi);
+            const compiled2 = compile(refCombi, void 0, { recovery });
             if (compiled2.inlineExpression === null) {
               warn(init.start, `"${varName}" is a ref() that couldn't be inlined (was .define() called with a static combinator?)`);
               continue;
@@ -7287,7 +7745,7 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
           let replacement = compiledRules.replacement;
           if (exportPrefix) {
             const ns = nsFor(varName);
-            const pieces = compileLinkable([...compiledRules.ruleMap], ns);
+            const pieces = compileLinkable([...compiledRules.ruleMap], ns, { recovery });
             if (pieces && !pieces.mfFns.length && !pieces.buildFns.length) {
               const ir = serializeRuleMap([...compiledRules.ruleMap]);
               replacement = withCarriedPieces(replacement, [ir ? { ns, ir } : pieces]);
@@ -7323,7 +7781,7 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
           warn(init.start, `"${varName}" references a parseman macro import but isn't a statically-evaluable combinator`);
           continue;
         }
-        const compiled = compile(parser2);
+        const compiled = compile(parser2, void 0, { recovery });
         if (compiled.inlineExpression === null) {
           warn(init.start, `"${varName}" couldn't be inlined (likely closes over a runtime value)`);
           continue;