parseman 0.24.0 → 0.26.0

package/dist/index.cjs

@@ -22,7 +22,9 @@ var index_exports = {};
 __export(index_exports, {
   OffsetIndex: () => OffsetIndex,
   absoluteSpanAt: () => absoluteSpanAt,
+  absoluteSpanCST: () => absoluteSpanCST,
   absolutize: () => absolutize,
+  absolutizeCST: () => absolutizeCST,
   annotateSpan: () => annotateSpan,
   applyEdit: () => applyEdit,
   balanced: () => balanced,
@@ -53,7 +55,6 @@ __export(index_exports, {
   literal: () => literal,
   makeWord: () => makeWord,
   many: () => many,
-  manyRecover: () => manyRecover,
   noTrivia: () => noTrivia,
   node: () => node,
   not: () => not,
@@ -63,15 +64,14 @@ __export(index_exports, {
   parse: () => parse,
   parseDoc: () => parseDoc,
   parser: () => parser,
-  recover: () => recover,
   ref: () => ref,
   regex: () => regex,
   relativize: () => relativize,
+  relativizeCST: () => relativizeCST,
   rules: () => rules,
   run: () => run,
   scanTo: () => scanTo,
   sepBy: () => sepBy,
-  sepByRecover: () => sepByRecover,
   sequence: () => sequence,
   shiftAbsolute: () => shiftAbsolute,
   skip: () => skip,
@@ -341,7 +341,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) {
@@ -357,6 +363,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);
@@ -1303,10 +1310,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) {
@@ -1540,6 +1547,94 @@ function scanBlockComment(input, cur) {
   return close === -1 ? cur : close + 2;
 }
 
+// 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(fs) {
+  if (fs.kind !== "ranges" || fs.ranges.length === 0) return null;
+  const ranges = fs.ranges;
+  return {
+    _tag: "firstSetSentinel",
+    _meta: { firstSet: fs, 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);
+}
+var REC = { scan: recoverScan, at: matchesAt, or: orSentinel, sentinel: firstSetSentinel, capture: captureError };
+
 // src/combinators/sequence.ts
 function sequence(...parsers) {
   const meta = {
@@ -1550,11 +1645,59 @@ function sequence(...parsers) {
     isTrivia: false
   };
   const def = { tag: "sequence", parsers };
+  let followSentinels;
+  function parseTolerant(input, pos, ctx) {
+    followSentinels ??= parsers.map((_, i) => {
+      const fs = parsers.slice(i + 1).reduce(
+        (acc, p) => union(acc, firstSetOf(p)),
+        { kind: "empty" }
+      );
+      return firstSetSentinel(fs);
+    });
+    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++) {
@@ -1593,6 +1736,69 @@ function sequence(...parsers) {
   };
 }
 
+// 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 } };
+    }
+  };
+}
+function isParseError(value) {
+  return typeof value === "object" && value !== null && value._tag === "parseError";
+}
+
 // src/combinators/repeat.ts
 function repItem(combinator, input, cur, ctx) {
   const mark = saveTriviaMark(ctx);
@@ -1613,7 +1819,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);
@@ -1628,6 +1834,7 @@ function many(combinator) {
     isTrivia: false
   };
   const def = { tag: "many", parser: combinator, min: 0 };
+  let expected;
   return {
     _tag: "many",
     _meta: meta,
@@ -1637,7 +1844,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;
       }
@@ -1652,6 +1870,7 @@ function oneOrMore(combinator) {
     isTrivia: false
   };
   const def = { tag: "oneOrMore", parser: combinator, min: 1 };
+  let expected;
   return {
     _tag: "oneOrMore",
     _meta: meta,
@@ -1663,7 +1882,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;
       }
@@ -1709,15 +1939,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;
@@ -1747,6 +1991,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;
         }
@@ -1920,7 +2173,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;
@@ -1950,7 +2203,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 } };
       }
@@ -2064,7 +2319,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()');
@@ -2342,65 +2597,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(""));
@@ -2472,20 +2668,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;
@@ -2510,7 +2725,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 === "\\") {
@@ -2518,7 +2733,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);
@@ -2607,7 +2822,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);
@@ -2618,9 +2833,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;
     }
@@ -2677,8 +2891,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;
     }
@@ -2730,7 +2944,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);
@@ -2867,7 +3081,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;
   }
@@ -3282,7 +3496,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}++`);
@@ -3292,8 +3512,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) {
@@ -3752,21 +3972,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} } }`;
@@ -4266,6 +4494,10 @@ function emitRegex(def, ctx, pos) {
   stmts.push(...emitLeafCapture(ctx, vv, pos, endVar));
   return { stmts, valueVar: vv, endVar };
 }
+function syncSentinelExpr(fs) {
+  if (fs.kind !== "ranges" || fs.ranges.length === 0) return null;
+  return `_ctx._rec.sentinel({ kind: 'ranges', ranges: ${JSON.stringify(fs.ranges)} })`;
+}
 function emitSeqValues(def, ctx, pos) {
   const startV = v(ctx, "_start");
   const curV = v(ctx, "_cur");
@@ -4274,7 +4506,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 fs = def.parsers.slice(i + 1).reduce((acc, p) => union(acc, firstSetOf(p)), { kind: "empty" });
+    const ref2 = syncSentinelExpr(fs);
+    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);
@@ -4299,7 +4541,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);
@@ -4529,7 +4781,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}`;
@@ -4634,6 +4886,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);
@@ -4667,10 +4921,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--;
@@ -4692,20 +4962,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) {
@@ -4731,8 +5037,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}`
       );
@@ -4748,7 +5053,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}`
       );
@@ -4768,7 +5073,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}`
     );
@@ -5025,7 +5330,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 };
 }
@@ -5115,6 +5420,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`,
@@ -5281,7 +5590,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: [
@@ -5296,7 +5605,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}`;
@@ -5540,7 +5849,7 @@ function ruleDependencies(ruleMap) {
   }
   return deps;
 }
-function compile(combinator, mapFnSources) {
+function compile(combinator, mapFnSources, opts) {
   markUnusedValues(combinator);
   const grammarTrivia = combinator._meta.grammarTrivia;
   const ctx = {
@@ -5561,6 +5870,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 } : {}
   };
@@ -5613,7 +5923,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
@@ -5670,6 +5980,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,
@@ -6415,46 +6726,13 @@ function withCtx(extra, combinator) {
   };
 }
 
-// src/combinators/recover.ts
-function recover(combinator, sentinel) {
-  const meta = {
-    firstSet: { kind: "any" },
-    canMatchNewline: true,
-    isTrivia: false
-  };
-  const expected = deriveExpected(combinator);
-  return {
-    _tag: "recover",
-    _meta: meta,
-    _def: { tag: "recover", parser: combinator, sentinel },
-    parse(input, pos, ctx) {
-      const result = combinator.parse(input, pos, ctx);
-      if (result.ok) return result;
-      let scanPos = pos;
-      while (scanPos < input.length) {
-        if (sentinel.parse(input, scanPos, ctx).ok) break;
-        scanPos++;
-      }
-      const error = {
-        _tag: "parseError",
-        span: { start: pos, end: scanPos },
-        expected
-      };
-      ctx._errors?.push(error);
-      return { ok: true, value: error, span: { start: pos, end: scanPos } };
-    }
-  };
-}
-function isParseError(value) {
-  return typeof value === "object" && value !== null && value._tag === "parseError";
-}
-
 // src/combinators/completions.ts
-function completionsAt(combinator, input, offset) {
+function completionsAt(target, input, offset, options = {}) {
   const probe = { offset, best: null };
-  const ctx = { trackLines: false, _probe: probe };
-  const result = combinator.parse(input.slice(0, offset), 0, ctx);
-  if (result.ok) return [];
+  const ctx = { trackLines: false, _probe: probe, ...options.tolerant ? { _tolerant: true, _rec: REC } : {} };
+  const sliced = input.slice(0, offset);
+  const result = "parseWithContext" in target ? target.parseWithContext(sliced, ctx, 0) : target.parse(sliced, 0, ctx);
+  if (result.ok) return options.tolerant ? probe.best?.expected ?? [] : [];
   const best = deeperFail(probe.best, result);
   return best?.expected ?? [];
 }
@@ -6464,34 +6742,162 @@ function deeperFail(a, b) {
   return a.span.start >= b.span.start ? a : b;
 }
 
-// src/combinators/recover-list.ts
-function tolerantElement(item, sentinel, until) {
-  const el = transform(
-    sequence(not(until), recover(item, sentinel)),
-    ([, value]) => value
-  );
-  if (el._def.tag === "transform") el._def.fnSrc = "([, value]) => value";
-  return el;
+// src/cst/relative-spans.ts
+function relativize(node2, parentBase = 0) {
+  return {
+    start: node2.start - parentBase,
+    end: node2.end - parentBase,
+    children: node2.children.map((c) => relativize(c, node2.start))
+  };
+}
+function absolutize(node2, parentBase = 0) {
+  const start = parentBase + node2.start;
+  return {
+    start,
+    end: parentBase + node2.end,
+    children: node2.children.map((c) => absolutize(c, start))
+  };
+}
+function absoluteSpanAt(root, path) {
+  let base = 0;
+  let node2 = root;
+  for (const idx of path) {
+    base += node2.start;
+    const child = node2.children[idx];
+    if (!child) throw new RangeError(`absoluteSpanAt: no child ${idx} on path ${path.join(".")}`);
+    node2 = child;
+  }
+  return { start: base + node2.start, end: base + node2.end };
+}
+function relativizeCST(node2, parentBase = 0) {
+  const span = { start: node2.span.start - parentBase, end: node2.span.end - parentBase };
+  if (node2.children) {
+    const base = node2.span.start;
+    return { ...node2, span, children: node2.children.map((c) => relativizeCST(c, base)) };
+  }
+  return { ...node2, span };
+}
+function absolutizeCST(node2, parentBase = 0) {
+  const start = parentBase + node2.span.start;
+  const span = { start, end: parentBase + node2.span.end };
+  if (node2.children) {
+    return { ...node2, span, children: node2.children.map((c) => absolutizeCST(c, start)) };
+  }
+  return { ...node2, span };
+}
+function absoluteSpanCST(root, path) {
+  let base = 0;
+  let node2 = root;
+  for (const idx of path) {
+    base += node2.span.start;
+    const child = node2.children?.[idx];
+    if (!child) throw new RangeError(`absoluteSpanCST: no child ${idx} on path ${path.join(".")}`);
+    node2 = child;
+  }
+  return { start: base + node2.span.start, end: base + node2.span.end };
 }
-function sepByRecover(item, separator, until) {
-  const sentinel = choice(separator, until);
-  return sepBy(tolerantElement(item, sentinel, until), separator);
+function shiftAbsolute(node2, at, delta) {
+  const s = node2.start >= at ? node2.start + delta : node2.start;
+  const e = node2.end >= at ? node2.end + delta : node2.end;
+  return {
+    start: s,
+    end: e,
+    children: node2.children.map((c) => shiftAbsolute(c, at, delta))
+  };
 }
-function manyRecover(item, until) {
-  return many(tolerantElement(item, until, until));
+function applyEdit(root, at, delta, stats) {
+  return editNode(root, at, delta, 0, 0, stats);
+}
+function editNode(node2, at, delta, parentBase, parentShift, stats) {
+  const absStart = parentBase + node2.start;
+  const absEnd = parentBase + node2.end;
+  if (absEnd < at) return node2;
+  const startShifts = absStart >= at;
+  if (startShifts && parentShift === delta) return node2;
+  if (stats) stats.allocated++;
+  const newAbsStart = startShifts ? absStart + delta : absStart;
+  const newAbsEnd = absEnd + delta;
+  const newParentBase = parentBase + parentShift;
+  const newStart = newAbsStart - newParentBase;
+  const newEnd = newAbsEnd - newParentBase;
+  const ownShift = newAbsStart - absStart;
+  let changed = false;
+  const newChildren = [];
+  for (const c of node2.children) {
+    const nc = editNode(c, at, delta, absStart, ownShift, stats);
+    if (nc !== c) changed = true;
+    newChildren.push(nc);
+  }
+  return {
+    start: newStart,
+    end: newEnd,
+    children: changed ? newChildren : node2.children
+  };
 }
 
 // src/functional/doc.ts
+function mkCtx(state, build, tolerant) {
+  return tolerant ? { trackLines: false, state, build, _tolerant: true, _rec: REC, _errors: [] } : { trackLines: false, state, build };
+}
+function asRuleFn(entry) {
+  return typeof entry === "function" ? entry : (input, pos, ctx) => entry.parse(input, pos, ctx);
+}
+function defOf(entry) {
+  return typeof entry === "object" && entry !== null && "_def" in entry ? entry._def : void 0;
+}
+function producesRepetition(def, depth = 0) {
+  if (!def || depth > 24) return false;
+  const d = def;
+  switch (d.tag) {
+    case "sepBy":
+    case "many":
+    case "oneOrMore":
+      return true;
+    // Rule entries and `ref`s wrap their body in a `lazy` thunk — resolve it. The
+    // `depth` cap bounds any self-referential cycle (a repetition, if present, is
+    // found shallowly before recursion goes deep).
+    case "lazy": {
+      const thunk = d.thunk;
+      let inner;
+      try {
+        inner = typeof thunk === "function" ? thunk() : void 0;
+      } catch {
+        return false;
+      }
+      return producesRepetition(inner?._def, depth + 1);
+    }
+    // Transparent wrappers — look through to the inner parser.
+    case "node":
+    case "transform":
+    case "token":
+    case "label":
+    case "field":
+    case "expect":
+    case "withCtx":
+    case "grammar":
+    case "optional":
+      return producesRepetition(defOf(d.parser), depth + 1);
+    case "skip":
+      return producesRepetition(defOf(d.main), depth + 1);
+    // A bracketed/anchored list is a sequence whose element run is a repetition.
+    case "sequence":
+      return d.parsers.some((p) => producesRepetition(defOf(p), depth + 1));
+    default:
+      return false;
+  }
+}
 var REENTRY_MAX_SPAN_FRACTION = 0.5;
 function isNode(x) {
   return typeof x === "object" && x !== null && x._tag === "node";
 }
-function findContaining(node2, pos, path = []) {
+function findContaining(node2, nodeAbsStart, pos, path = []) {
   for (let i = 0; i < node2.children.length; i++) {
     const child = node2.children[i];
     if (!isNode(child)) continue;
-    if (child.span.start <= pos && pos < child.span.end) {
-      const inner = findContaining(child, pos, [...path, i]);
+    const childAbsStart = nodeAbsStart + child.span.start;
+    const childAbsEnd = nodeAbsStart + child.span.end;
+    if (childAbsStart <= pos && pos < childAbsEnd) {
+      const inner = findContaining(child, childAbsStart, pos, [...path, i]);
       return inner ?? { node: child, path: [...path, i] };
     }
   }
@@ -6518,24 +6924,20 @@ function replaceAtPath(rebuild, root, path, newNode) {
 function defaultRebuild(node2, children) {
   return { ...node2, children };
 }
-function shiftSpans(child, delta) {
+function shiftRelStart(child, delta) {
   const c = child;
-  const span = { start: c.span.start + delta, end: c.span.end + delta };
-  if (Array.isArray(c.children)) {
-    return { ...c, span, children: c.children.map((g) => shiftSpans(g, delta)) };
-  }
-  return { ...c, span };
+  return { ...c, span: { start: c.span.start + delta, end: c.span.end + delta } };
 }
-function graftAndShift(root, path, newNode, delta) {
+function graftRelative(root, path, newNode, delta) {
   if (path.length === 0) return newNode;
   const [idx, ...rest] = path;
   const oldChildren = root.children;
   const newChildren = oldChildren.map((child, i) => {
     if (i < idx) return child;
     if (i === idx) {
-      return rest.length === 0 ? newNode : graftAndShift(child, rest, newNode, delta);
+      return rest.length === 0 ? newNode : graftRelative(child, rest, newNode, delta);
     }
-    return shiftSpans(child, delta);
+    return shiftRelStart(child, delta);
   });
   return {
     ...root,
@@ -6543,6 +6945,96 @@ function graftAndShift(root, path, newNode, delta) {
     children: newChildren
   };
 }
+function parseMiddle(input, reStart, reEnd, cStart, ruleFn, separator, build, tolerant) {
+  const ctx = mkCtx(null, build, tolerant);
+  const out = [];
+  let pos = reStart;
+  let guard2 = 0;
+  while (pos < reEnd) {
+    if (++guard2 > reEnd - reStart + 2) return null;
+    if (separator && out.length > 0 && out[out.length - 1]._tag === "node") {
+      if (pos + separator.length > reEnd || !input.startsWith(separator, pos)) return null;
+      out.push({ _tag: "leaf", value: separator, span: { start: pos - cStart, end: pos + separator.length - cStart } });
+      pos += separator.length;
+      continue;
+    }
+    let r;
+    try {
+      r = ruleFn(input, pos, ctx);
+    } catch {
+      return null;
+    }
+    if (!r.ok || r.span.end <= pos || r.span.end > reEnd) return null;
+    out.push(relativizeCST(r.value, cStart));
+    pos = r.span.end;
+  }
+  return pos === reEnd ? out : null;
+}
+function tryListSplice(root, path, C, cStart, newInput, from, to, delta, registry, build, tolerant) {
+  const kids = C.children;
+  if (kids.length === 0) return null;
+  let h = 0;
+  while (h < kids.length && cStart + kids[h].span.end <= from) h++;
+  while (h > 0 && kids[h - 1]._tag === "node") h--;
+  let t = kids.length;
+  while (t > h && cStart + kids[t - 1].span.start >= to) t--;
+  while (t < kids.length && kids[t]._tag !== "node") t++;
+  if (t >= kids.length) return null;
+  for (let i = t; i < kids.length; i++) {
+    if (kids[i]._tag === "node" && kids[i].state != null) return null;
+  }
+  let elemType;
+  let elemCount = 0;
+  for (const k of kids) {
+    if (k._tag !== "node") continue;
+    elemCount++;
+    if (elemType === void 0) elemType = k.type;
+    else if (k.type !== elemType) return null;
+  }
+  if (elemType === void 0 || elemCount < 2) return null;
+  const ruleFn = registry[elemType];
+  if (!ruleFn) return null;
+  let separator = null;
+  for (let i = 1; i < kids.length - 1; i++) {
+    if (kids[i - 1]._tag === "node" && kids[i + 1]._tag === "node") {
+      if (kids[i]._tag !== "leaf") return null;
+      const sep = kids[i].value ?? null;
+      if (separator === null) separator = sep;
+      else if (sep !== separator) return null;
+    }
+  }
+  if (separator === null) return null;
+  const first = kids[0];
+  const last = kids[kids.length - 1];
+  if (first._tag === "leaf" && first.value !== separator && from < cStart + first.span.end) return null;
+  if (last._tag === "leaf" && last.value !== separator && to > cStart + last.span.start) return null;
+  const reStart = h > 0 ? cStart + kids[h - 1].span.end : cStart;
+  const reEnd = cStart + kids[t].span.start + delta;
+  if (reEnd < reStart) return null;
+  const middle = parseMiddle(newInput, reStart, reEnd, cStart, ruleFn, separator, build, tolerant);
+  if (!middle) return null;
+  if (middle.length > 0) {
+    const last2 = middle[middle.length - 1];
+    if (!(last2._tag === "leaf" && last2.value === separator)) return null;
+  }
+  if (reEnd < newInput.length) {
+    for (const sentinel of [" ", "\uFFFF"]) {
+      if (newInput[reEnd] === sentinel) continue;
+      const probed = newInput.slice(0, reEnd) + sentinel.repeat(newInput.length - reEnd);
+      const probe = parseMiddle(probed, reStart, reEnd, cStart, ruleFn, separator, build, tolerant);
+      if (!probe || probe.length !== middle.length) return null;
+      for (let i = 0; i < middle.length; i++) if (!structurallyEqual(probe[i], middle[i])) return null;
+    }
+  }
+  const head = kids.slice(0, h);
+  const tail = kids.slice(t).map((k) => shiftRelStart(k, delta));
+  const newC = {
+    ...C,
+    span: { start: C.span.start, end: C.span.end + delta },
+    children: [...head, ...middle, ...tail]
+  };
+  return graftRelative(root, path, newC, delta);
+}
 function structurallyEqual(a, b) {
   if (a === b) return true;
   if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
@@ -6557,6 +7049,11 @@ function structurallyEqual(a, b) {
   if (at === "leaf" || at === "trivia") {
     return a.value === b.value;
   }
+  if (at === "parseError") {
+    const ae = a.expected ?? [];
+    const be = b.expected ?? [];
+    return ae.length === be.length && ae.every((x, i) => x === be[i]);
+  }
   if (a.type !== b.type) return false;
   const ac = a.children;
   const bc = b.children;
@@ -6566,13 +7063,13 @@ function structurallyEqual(a, b) {
   }
   return true;
 }
-function boundaryIsSafe(ruleFn, newInput, start, boundary, state, build, produced) {
+function boundaryIsSafe(ruleFn, newInput, start, boundary, state, build, produced, tolerant) {
   if (!produced.ok) return false;
   if (boundary >= newInput.length) return true;
   for (const sentinel of [" ", "\uFFFF"]) {
     if (newInput[boundary] === sentinel) continue;
     const probed = newInput.slice(0, boundary) + sentinel.repeat(newInput.length - boundary);
-    const ctx = { trackLines: false, state, build };
+    const ctx = mkCtx(state, build, tolerant);
     let r;
     try {
       r = ruleFn(probed, start, ctx);
@@ -6586,27 +7083,83 @@ function boundaryIsSafe(ruleFn, newInput, start, boundary, state, build, produce
 }
 var ParseDocImpl = class _ParseDocImpl {
   _registry;
+  /** Registry entries normalized to callable parse functions (memoized once). */
+  _fns;
+  /** Rule names the grammar proves are genuine repetitions — the ONLY splice-safe types. */
+  _reps;
   _rootRule;
   _opts;
-  tree;
+  /**
+   * The tree, held in whichever coordinate system it arrived in. A fresh parse
+   * arrives ABSOLUTE (`_abs` set); an incremental graft arrives PARENT-RELATIVE
+   * (`_rel` set). The public `tree` is always the RELATIVE form (so untouched
+   * subtrees stay shared by identity across edits and reads are O(1)); it's
+   * materialized from `_abs` once, on demand, and memoized. `undefined` = not yet
+   * computed; `null` = failed parse. A fresh parse that's never edited nor
+   * tree-read pays no conversion — important for the full-reparse fallback path.
+   */
+  _abs;
+  _rel;
   errors;
+  unconsumedFrom;
   input;
-  constructor(registry, rootRule, opts, tree, errors, input) {
+  constructor(registry, rootRule, opts, trees, errors, unconsumedFrom, input) {
     this._registry = registry;
+    this._fns = {};
+    this._reps = /* @__PURE__ */ new Set();
+    for (const [name, entry] of Object.entries(registry)) {
+      this._fns[name] = asRuleFn(entry);
+      if (producesRepetition(defOf(entry))) this._reps.add(name);
+    }
     this._rootRule = rootRule;
     this._opts = opts;
-    this.tree = tree;
+    this._abs = trees.abs;
+    this._rel = trees.rel;
     this.errors = errors;
+    this.unconsumedFrom = unconsumedFrom;
     this.input = input;
   }
+  /**
+   * The parse tree with PARENT-RELATIVE spans — a node's `span` is relative to
+   * its parent's start (root base 0). This is the shareable representation:
+   * untouched subtrees keep the same identity across `.edit()`s, and reading the
+   * tree after a length-changing edit is O(1) (no offset rewrite). For absolute
+   * positions use the O(depth) cursor `spanAt(path)`, or `absolutizeCST(tree)` to
+   * materialize the whole absolute tree. (A fresh non-incremental `node().parse()`
+   * result is unchanged — still absolute.)
+   */
+  get tree() {
+    if (this._rel === void 0) {
+      this._rel = this._abs ? relativizeCST(this._abs, 0) : null;
+    }
+    return this._rel;
+  }
+  spanAt(path) {
+    const rel = this.tree;
+    if (!rel) throw new Error("spanAt on a failed parse (tree is null)");
+    return absoluteSpanCST(rel, path);
+  }
+  /**
+   * Wrap a reused (grafted/spliced) RELATIVE tree, recomputing `errors` and
+   * `unconsumedFrom` from it so both stay consistent with the tree across the
+   * edit (the flat errors are recovered errors embedded in the reused subtrees;
+   * unconsumedFrom re-derives trailing junk over the new input).
+   */
+  wrapReuse(newTree, newInput) {
+    const trivia2 = triviaOf(this._registry[this._rootRule], this._opts);
+    const end = newTree.span.end;
+    const errors = collectEmbeddedErrors(newTree, 0, []);
+    const unconsumedFrom = unconsumedAfter(end, newInput, trivia2);
+    return new _ParseDocImpl(this._registry, this._rootRule, this._opts, { rel: newTree }, errors, unconsumedFrom, newInput);
+  }
   edit(from, to, replacement) {
     const newInput = this.input.slice(0, from) + replacement + this.input.slice(to);
     const reparse = () => parseDoc(this._registry, this._rootRule, newInput, this._opts);
-    if (!this.tree) return reparse();
+    const root = this.tree;
+    if (!root) return reparse();
     const delta = replacement.length - (to - from);
-    const found = findContaining(this.tree, from);
-    if (!found) return reparse();
-    const ancestors = ancestorsAt(this.tree, found.path);
+    const found = findContaining(root, 0, from) ?? { node: root, path: [] };
+    const ancestors = ancestorsAt(root, found.path);
     const candidates = [found];
     const pathCopy = [...found.path];
     for (let i = ancestors.length - 2; i >= 0; i--) {
@@ -6615,37 +7168,78 @@ var ParseDocImpl = class _ParseDocImpl {
     }
     const rebuild = this._opts.rebuild ?? defaultRebuild;
     for (const { node: node2, path } of candidates) {
-      if (node2.span.end - node2.span.start > this.input.length * REENTRY_MAX_SPAN_FRACTION) break;
-      const ruleFn = this._registry[node2.type];
+      const { start: absStart, end: absEnd } = absoluteSpanCST(root, path);
+      if (absEnd - absStart > this.input.length * REENTRY_MAX_SPAN_FRACTION) break;
+      const ruleFn = this._fns[node2.type];
       if (!ruleFn) continue;
-      if (!(node2.span.start <= from && to <= node2.span.end)) continue;
-      const ctx = { trackLines: false, state: node2.state, build: this._opts.build };
-      const r = ruleFn(newInput, node2.span.start, ctx);
+      if (!(absStart <= from && to <= absEnd)) continue;
+      const ctx = mkCtx(node2.state, this._opts.build, !!this._opts.tolerant);
+      const r = ruleFn(newInput, absStart, ctx);
       if (!r.ok) continue;
-      if (r.span.end !== node2.span.end + delta) continue;
-      if (!boundaryIsSafe(ruleFn, newInput, node2.span.start, node2.span.end + delta, node2.state, this._opts.build, r)) {
+      if (r.span.end !== absEnd + delta) continue;
+      if (!boundaryIsSafe(ruleFn, newInput, absStart, absEnd + delta, node2.state, this._opts.build, r, !!this._opts.tolerant)) {
         continue;
       }
+      const parentBase = absStart - node2.span.start;
+      const newRel = relativizeCST(r.value, parentBase);
       if (delta === 0) {
-        const newTree2 = replaceAtPath(rebuild, this.tree, path, r.value);
-        return new _ParseDocImpl(this._registry, this._rootRule, this._opts, newTree2, [], newInput);
+        const newTree2 = replaceAtPath(rebuild, root, path, newRel);
+        return this.wrapReuse(newTree2, newInput);
       }
       if (this._opts.rebuild) return reparse();
-      const newTree = graftAndShift(this.tree, path, r.value, delta);
-      return new _ParseDocImpl(this._registry, this._rootRule, this._opts, newTree, [], newInput);
+      const newTree = graftRelative(root, path, newRel, delta);
+      return this.wrapReuse(newTree, newInput);
+    }
+    if (this._opts.structuralReuse && delta !== 0 && !this._opts.rebuild) {
+      const spliceCandidates = [...candidates, { node: root, path: [] }];
+      for (const { node: node2, path } of spliceCandidates) {
+        if (!this._reps.has(node2.type)) continue;
+        const { start: cStart, end: cEnd } = absoluteSpanCST(root, path);
+        if (!(cStart <= from && to <= cEnd)) continue;
+        const spliced = tryListSplice(root, path, node2, cStart, newInput, from, to, delta, this._fns, this._opts.build, !!this._opts.tolerant);
+        if (spliced) return this.wrapReuse(spliced, newInput);
+      }
     }
     return reparse();
   }
 };
+function triviaOf(entry, opts) {
+  if (opts.trivia) return opts.trivia;
+  if (entry === void 0 || typeof entry === "function") return void 0;
+  const meta = entry._meta;
+  return meta ? meta.grammarTrivia : void 0;
+}
+function unconsumedAfter(end, input, trivia2) {
+  let pos = end;
+  if (trivia2 && pos < input.length) {
+    const t = trivia2.parse(input, pos, { trackLines: false });
+    if (t.ok && t.span.end > pos) pos = t.span.end;
+  }
+  return pos < input.length ? pos : null;
+}
+function collectEmbeddedErrors(node2, base, out) {
+  const c = node2;
+  if (!c || typeof c !== "object" || !c.span) return out;
+  const start = base + c.span.start;
+  if (c._tag === "parseError") {
+    out.push({ _tag: "parseError", span: { start, end: base + c.span.end }, expected: c.expected ?? [] });
+    return out;
+  }
+  if (Array.isArray(c.children)) for (const k of c.children) collectEmbeddedErrors(k, start, out);
+  return out;
+}
 function parseDoc(registry, rootRule, input, opts = {}) {
-  const ruleFn = registry[rootRule];
-  if (!ruleFn) throw new Error(`No rule '${rootRule}' in registry`);
-  const ctx = { trackLines: false, state: opts.state, build: opts.build };
-  const r = ruleFn(input, 0, ctx);
+  const entry = registry[rootRule];
+  if (!entry) throw new Error(`No rule '${rootRule}' in registry`);
+  const ctx = mkCtx(opts.state, opts.build, !!opts.tolerant);
+  const r = asRuleFn(entry)(input, 0, ctx);
   if (r.ok) {
-    return new ParseDocImpl(registry, rootRule, opts, r.value, [], input);
+    const errors = ctx._errors ? [...ctx._errors] : [];
+    const unconsumedFrom = unconsumedAfter(r.span.end, input, triviaOf(entry, opts));
+    return new ParseDocImpl(registry, rootRule, opts, { abs: r.value }, errors, unconsumedFrom, input);
   }
-  return new ParseDocImpl(registry, rootRule, opts, null, [{ ok: false, expected: r.expected, span: r.span }], input);
+  const fail = { _tag: "parseError", span: r.span, expected: r.expected };
+  return new ParseDocImpl(registry, rootRule, opts, { abs: null }, [fail], null, input);
 }
 
 // src/functional/run.ts
@@ -6666,7 +7260,8 @@ function run(entry, input, options = {}) {
     build: options.build,
     state: options.state,
     ...grammarTrivia !== void 0 ? { trivia: grammarTrivia, ...grammarTrivia._meta.triviaKindLabels ? { triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {} } : {},
-    ...options.triviaCaptureMask !== void 0 ? { _triviaCaptureMask: options.triviaCaptureMask } : {}
+    ...options.triviaCaptureMask !== void 0 ? { _triviaCaptureMask: options.triviaCaptureMask } : {},
+    ...options.tolerant ? { _tolerant: true, _rec: REC } : {}
   };
   const r = invoke(entry, input, 0, ctx);
   let unconsumedFrom = null;
@@ -7014,72 +7609,6 @@ function buildOffsetIndex(root, input = "") {
   return new OffsetIndex(collectLeafSlots(root), 0, input.length);
 }
 
-// src/cst/relative-spans.ts
-function relativize(node2, parentBase = 0) {
-  return {
-    start: node2.start - parentBase,
-    end: node2.end - parentBase,
-    children: node2.children.map((c) => relativize(c, node2.start))
-  };
-}
-function absolutize(node2, parentBase = 0) {
-  const start = parentBase + node2.start;
-  return {
-    start,
-    end: parentBase + node2.end,
-    children: node2.children.map((c) => absolutize(c, start))
-  };
-}
-function absoluteSpanAt(root, path) {
-  let base = 0;
-  let node2 = root;
-  for (const idx of path) {
-    base += node2.start;
-    const child = node2.children[idx];
-    if (!child) throw new RangeError(`absoluteSpanAt: no child ${idx} on path ${path.join(".")}`);
-    node2 = child;
-  }
-  return { start: base + node2.start, end: base + node2.end };
-}
-function shiftAbsolute(node2, at, delta) {
-  const s = node2.start >= at ? node2.start + delta : node2.start;
-  const e = node2.end >= at ? node2.end + delta : node2.end;
-  return {
-    start: s,
-    end: e,
-    children: node2.children.map((c) => shiftAbsolute(c, at, delta))
-  };
-}
-function applyEdit(root, at, delta, stats) {
-  return editNode(root, at, delta, 0, 0, stats);
-}
-function editNode(node2, at, delta, parentBase, parentShift, stats) {
-  const absStart = parentBase + node2.start;
-  const absEnd = parentBase + node2.end;
-  if (absEnd < at) return node2;
-  const startShifts = absStart >= at;
-  if (startShifts && parentShift === delta) return node2;
-  if (stats) stats.allocated++;
-  const newAbsStart = startShifts ? absStart + delta : absStart;
-  const newAbsEnd = absEnd + delta;
-  const newParentBase = parentBase + parentShift;
-  const newStart = newAbsStart - newParentBase;
-  const newEnd = newAbsEnd - newParentBase;
-  const ownShift = newAbsStart - absStart;
-  let changed = false;
-  const newChildren = [];
-  for (const c of node2.children) {
-    const nc = editNode(c, at, delta, absStart, ownShift, stats);
-    if (nc !== c) changed = true;
-    newChildren.push(nc);
-  }
-  return {
-    start: newStart,
-    end: newEnd,
-    children: changed ? newChildren : node2.children
-  };
-}
-
 // src/index.ts
 registerRegexAnalyzer(firstSetFromRegex);
 //# sourceMappingURL=index.cjs.map