parseman 0.7.1 → 0.9.0

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   choice: () => choice,
   compile: () => compile,
   completionsAt: () => completionsAt,
+  expect: () => expect,
   guard: () => guard,
   isParseError: () => isParseError,
   keywords: () => keywords,
@@ -61,6 +62,7 @@ __export(index_exports, {
   sepBy: () => sepBy,
   sequence: () => sequence,
   skip: () => skip,
+  staticExpected: () => staticExpected,
   transform: () => transform,
   trivia: () => trivia,
   triviaEntries: () => triviaEntries,
@@ -1349,13 +1351,15 @@ function noTrivia(root) {
 function parse(combinator, input, opts = {}) {
   const trackLines = opts.trackLines ?? false;
   const _errors = opts.recover ? [] : void 0;
+  const _probe = opts.recover ? { offset: input.length, best: null } : void 0;
   const ctx = {
     trackLines,
-    ..._errors !== void 0 ? { _errors } : {}
+    ..._errors !== void 0 ? { _errors } : {},
+    ..._probe !== void 0 ? { _probe } : {}
   };
   const result = combinator.parse(input, 0, ctx);
   if (!result.ok) return result;
-  const withErrors = _errors !== void 0 ? { ...result, errors: _errors } : result;
+  const withErrors = _errors !== void 0 ? { ...result, errors: _errors, furthestFail: _probe?.best ?? null } : result;
   if (trackLines) {
     const idx = buildLineIndex(input);
     return { ...withErrors, span: annotateSpan(withErrors.span, idx) };
@@ -1363,14 +1367,140 @@ function parse(combinator, input, opts = {}) {
   return withErrors;
 }
 
+// src/compiler/scannable-run.ts
+var CLASS_ESCAPES = { t: 9, n: 10, r: 13, f: 12, v: 11, "0": 0 };
+var META = new Set("()[]{}*+?|^$.".split(""));
+function parseClassRanges(body) {
+  const ranges = [];
+  let i = 0;
+  const readCp = () => {
+    const ch = body[i];
+    if (ch === void 0) return null;
+    if (ch === "\\") {
+      const e = body[i + 1];
+      if (e === void 0) return null;
+      i += 2;
+      return e in CLASS_ESCAPES ? CLASS_ESCAPES[e] : e.codePointAt(0);
+    }
+    i += ch.length;
+    return ch.codePointAt(0);
+  };
+  while (i < body.length) {
+    const lo = readCp();
+    if (lo === null) return null;
+    if (body[i] === "-" && body[i + 1] !== void 0 && body[i + 1] !== "]") {
+      i += 1;
+      const hi = readCp();
+      if (hi === null) return null;
+      ranges.push([lo, hi]);
+    } else {
+      ranges.push([lo, lo]);
+    }
+  }
+  return ranges.length ? ranges : null;
+}
+function literalCodePoints(frag) {
+  const out = [];
+  let i = 0;
+  while (i < frag.length) {
+    const ch = frag[i];
+    if (ch === "\\") {
+      const e = frag[i + 1];
+      if (e === void 0) return null;
+      out.push(e in CLASS_ESCAPES ? CLASS_ESCAPES[e] : e.codePointAt(0));
+      i += 2;
+      continue;
+    }
+    if (META.has(ch)) return null;
+    out.push(ch.codePointAt(0));
+    i += 1;
+  }
+  return out.length ? out : null;
+}
+function parseScanShape(source) {
+  let m = /^\[((?:\\.|[^\]])+)\]([+*])$/.exec(source);
+  if (m) {
+    if (m[1].startsWith("^")) return null;
+    const ranges = parseClassRanges(m[1]);
+    return ranges ? { kind: "chars", ranges } : null;
+  }
+  m = /^(.*?)\[\^((?:\\.|[^\]])+)\]\*$/.exec(source);
+  if (m) {
+    const open = literalCodePoints(m[1]);
+    const stop = parseClassRanges(m[2]);
+    if (open && stop) return { kind: "until", open, stop };
+    return null;
+  }
+  if (!source.includes("\\\\")) {
+    m = /^(.*?)\((?:\?:)?[\s\S]*\)\*(.*?)$/.exec(source);
+    if (m && m[1] && m[2]) {
+      const open = literalCodePoints(m[1]);
+      const close = literalCodePoints(m[2]);
+      if (open && close) return { kind: "delimited", open, close };
+    }
+  }
+  return null;
+}
+var classCond = (cVar, ranges) => ranges.map(([lo, hi]) => lo === hi ? `${cVar} === ${lo}` : `(${cVar} >= ${lo} && ${cVar} <= ${hi})`).join(" || ");
+var litCond = (base, cps, firstVar) => cps.map(
+  (cp, k) => k === 0 && firstVar ? `${firstVar} === ${cp}` : `input.charCodeAt(${base}${k ? ` + ${k}` : ""}) === ${cp}`
+).join(" && ");
+function advanceExpr(shape) {
+  if (shape.kind === "chars") {
+    return {
+      setup: [
+        `      _e++`,
+        `      while (_e < input.length) { const c2 = input.charCodeAt(_e); if (${classCond("c2", shape.ranges)}) _e++; else break }`
+      ],
+      endVar: "_e"
+    };
+  }
+  if (shape.kind === "until") {
+    return {
+      setup: [
+        `      let j = _e + ${shape.open.length}`,
+        `      while (j < input.length && !(${classCond("input.charCodeAt(j)", shape.stop)})) j++`
+      ],
+      endVar: "j"
+    };
+  }
+  const n = shape.close.length;
+  return {
+    setup: [
+      `      let j = _e + ${shape.open.length}`,
+      `      while (j + ${n - 1} < input.length && !(${litCond("j", shape.close)})) j++`
+    ],
+    endVar: n === 1 ? "(j + 1 <= input.length ? j + 1 : input.length)" : `(j + ${n} <= input.length ? j + ${n} : input.length)`
+  };
+}
+function guardLine(shape) {
+  const cond = shape.kind === "chars" ? classCond("c", shape.ranges) : litCond("_e", shape.open, "c");
+  return `    if (${cond}) {`;
+}
+function scanBranch(shape) {
+  if (shape.kind === "chars") {
+    return `    if (${classCond("c", shape.ranges)}) { _e++; continue }`;
+  }
+  const { setup, endVar } = advanceExpr(shape);
+  return [guardLine(shape), ...setup, `      _e = ${endVar}`, `      continue`, `    }`].join("\n");
+}
+function captureChunk(startVar, kindIndex) {
+  return [
+    `      if (_cap) {`,
+    `        if (_ctx._triviaLog !== undefined) _ctx._triviaLog.push(${startVar}, _e, ${kindIndex})`,
+    `        if (_ctx._cstTriviaLog !== undefined) _ctx._cstTriviaLog.push(${startVar}, _e, _ctx._cstRawChildren ? _ctx._cstRawChildren.length : 0, ${kindIndex})`,
+    `      }`
+  ];
+}
+function scanBranchLabeled(shape, kindIndex) {
+  const { setup, endVar } = advanceExpr(shape);
+  const lines = [guardLine(shape), `      const _cs = _e`, ...setup];
+  if (endVar !== "_e") lines.push(`      _e = ${endVar}`);
+  lines.push(...captureChunk("_cs", kindIndex), `      continue`, `    }`);
+  return lines.join("\n");
+}
+
 // src/compiler/trivia-fast-path.ts
-var BLOCK_COMMENT = String.raw`\/\*(?:[^*]|\*(?!\/))*\*\/`;
-var WS_CLASS_SOURCES = /* @__PURE__ */ new Set([
-  String.raw`[ \t\n\r\f]+`,
-  String.raw`[ \t\n]+`,
-  String.raw`[ \t]+`,
-  String.raw`[\t\n\f\r ]+`
-]);
 function unwrapTrivia2(p) {
   let cur = p;
   while (cur._def.tag === "trivia") cur = cur._def.parser;
@@ -1386,36 +1516,30 @@ function choiceArms(p) {
   if (p._def.tag === "choice") return p._def.parsers;
   return null;
 }
-function isWsClassSource(source) {
-  return WS_CLASS_SOURCES.has(source);
-}
-function isBlockCommentSource(source) {
-  return source === BLOCK_COMMENT;
+function armShape(arm) {
+  const src = getCoreRegexDef(arm)?.source;
+  return src ? parseScanShape(src) : null;
 }
 function analyzeTriviaFastPath(trivia2) {
   const core = unwrapTrivia2(trivia2);
-  const direct = getCoreRegexDef(core)?.source;
-  if (direct) {
-    if (isWsClassSource(direct)) return "wsOnly";
-    return null;
+  const directSrc = getCoreRegexDef(core)?.source;
+  if (directSrc) {
+    const shape = parseScanShape(directSrc);
+    return shape && shape.kind === "chars" ? [shape] : null;
   }
   const inner = oneOrMoreInner(core);
   if (!inner) return null;
-  const innerSrc = getCoreRegexDef(inner)?.source;
-  if (innerSrc && isWsClassSource(innerSrc)) return "wsOnly";
+  const innerShape = armShape(inner);
+  if (innerShape) return innerShape.kind === "chars" ? [innerShape] : null;
   const arms = choiceArms(inner);
-  if (!arms || arms.length !== 2) return null;
-  let hasWs = false;
-  let hasComment = false;
+  if (!arms || arms.length < 2) return null;
+  const shapes = [];
   for (const arm of arms) {
-    const src = getCoreRegexDef(arm)?.source;
-    if (!src) return null;
-    if (isWsClassSource(src)) hasWs = true;
-    else if (isBlockCommentSource(src)) hasComment = true;
-    else return null;
+    const shape = armShape(arm);
+    if (!shape) return null;
+    shapes.push(shape);
   }
-  if (hasWs && hasComment) return "wsComments";
-  return null;
+  return shapes;
 }
 var CAP_RECORD = [
   `  if (_cap && _e > _pos) {`,
@@ -1423,80 +1547,49 @@ var CAP_RECORD = [
   `    if (_ctx._cstTriviaLog !== undefined) _ctx._cstTriviaLog.push(_pos, _e, _ctx._cstRawChildren ? _ctx._cstRawChildren.length : 0)`,
   `  }`
 ].join("\n");
-var WS_ONLY_LOOP = [
-  `  while (_e < input.length) {`,
-  `    const c = input.charCodeAt(_e)`,
-  `    if (c === 32 || c === 9 || c === 10 || c === 13 || c === 12) { _e++; continue }`,
-  `    break`,
-  `  }`
-].join("\n");
-var WS_COMMENTS_LOOP = [
-  `  while (_e < input.length) {`,
-  `    const c = input.charCodeAt(_e)`,
-  `    if (c === 32 || c === 9 || c === 10 || c === 13 || c === 12) { _e++; continue }`,
-  `    if (c === 47 && input.charCodeAt(_e + 1) === 42) {`,
-  `      let j = _e + 2`,
-  `      while (j + 1 < input.length && !(input.charCodeAt(j) === 42 && input.charCodeAt(j + 1) === 47)) j++`,
-  `      _e = j + 2 <= input.length ? j + 2 : input.length`,
-  `      continue`,
-  `    }`,
-  `    break`,
-  `  }`
-].join("\n");
-var CAP_CHUNK = (wsKind, commentKind) => [
-  `    if (c === 32 || c === 9 || c === 10 || c === 13 || c === 12) {`,
-  `      const _cs = _e`,
-  `      _e++`,
-  `      while (_e < input.length) {`,
-  `        const c2 = input.charCodeAt(_e)`,
-  `        if (c2 === 32 || c2 === 9 || c2 === 10 || c2 === 13 || c2 === 12) _e++`,
-  `        else break`,
-  `      }`,
-  `      if (_cap) {`,
-  `        if (_ctx._triviaLog !== undefined) _ctx._triviaLog.push(_cs, _e, ${wsKind})`,
-  `        if (_ctx._cstTriviaLog !== undefined) _ctx._cstTriviaLog.push(_cs, _e, _ctx._cstRawChildren ? _ctx._cstRawChildren.length : 0, ${wsKind})`,
-  `      }`,
-  `      continue`,
-  `    }`,
-  `    if (c === 47 && input.charCodeAt(_e + 1) === 42) {`,
-  `      const _cs = _e`,
-  `      let j = _e + 2`,
-  `      while (j + 1 < input.length && !(input.charCodeAt(j) === 42 && input.charCodeAt(j + 1) === 47)) j++`,
-  `      _e = j + 2 <= input.length ? j + 2 : input.length`,
-  `      if (_cap) {`,
-  `        if (_ctx._triviaLog !== undefined) _ctx._triviaLog.push(_cs, _e, ${commentKind})`,
-  `        if (_ctx._cstTriviaLog !== undefined) _ctx._cstTriviaLog.push(_cs, _e, _ctx._cstRawChildren ? _ctx._cstRawChildren.length : 0, ${commentKind})`,
-  `      }`,
-  `      continue`,
-  `    }`
-].join("\n");
-var WS_COMMENTS_LOOP_LABELED = (wsKind, commentKind) => [
-  `  while (_e < input.length) {`,
-  `    const c = input.charCodeAt(_e)`,
-  CAP_CHUNK(wsKind, commentKind),
-  `    break`,
-  `  }`
-].join("\n");
-function buildFastTriviaFnDecl(fnName, kind, kindIndices) {
-  const loop = kind === "wsComments" && kindIndices ? WS_COMMENTS_LOOP_LABELED(kindIndices.ws, kindIndices.comment) : kind === "wsComments" ? WS_COMMENTS_LOOP : WS_ONLY_LOOP;
-  const cap = kindIndices ? "" : CAP_RECORD;
-  const lines = [
+function composeFastLoop(shapes) {
+  return [
+    `  while (_e < input.length) {`,
+    `    const c = input.charCodeAt(_e)`,
+    ...shapes.map(scanBranch),
+    `    break`,
+    `  }`
+  ].join("\n");
+}
+function buildFastTriviaFnDecl(fnName, shapes) {
+  return [
     `function ${fnName}(input, _pos, _ctx, _cap) {`,
     `  let _e = _pos`,
-    loop
-  ];
-  if (cap) lines.push(cap);
-  lines.push(`  return _e`, `}`);
-  return lines.join("\n");
+    composeFastLoop(shapes),
+    CAP_RECORD,
+    `  return _e`,
+    `}`
+  ].join("\n");
 }
-function regexArmIndex(spec, isComment) {
+function analyzeLabeledScannableRun(trivia2) {
+  const spec = analyzeLabeledTrivia(trivia2);
+  if (!spec) return null;
+  const out = [];
   for (const arm of spec.arms) {
     const src = getCoreRegexDef(arm.parser)?.source;
-    if (!src) return null;
-    const comment = src.includes("\\*") || src.startsWith("\\/\\/");
-    if (comment === isComment) return arm.kindIndex;
+    const shape = src ? parseScanShape(src) : null;
+    if (!shape) return null;
+    out.push({ shape, kindIndex: arm.kindIndex });
   }
-  return null;
+  return out;
+}
+function buildLabeledScannableTriviaFnDecl(fnName, arms) {
+  return [
+    `function ${fnName}(input, _pos, _ctx, _cap) {`,
+    `  let _e = _pos`,
+    `  while (_e < input.length) {`,
+    `    const c = input.charCodeAt(_e)`,
+    ...arms.map((a) => scanBranchLabeled(a.shape, a.kindIndex)),
+    `    break`,
+    `  }`,
+    `  return _e`,
+    `}`
+  ].join("\n");
 }
 function buildLabeledRegexTriviaFnDecl(fnName, spec, reNames) {
   const tryArms = spec.arms.map((arm, i) => {
@@ -1529,14 +1622,6 @@ function buildLabeledRegexTriviaFnDecl(fnName, spec, reNames) {
     `}`
   ].join("\n");
 }
-function labeledTriviaKindIndices(trivia2) {
-  const spec = analyzeLabeledTrivia(trivia2);
-  if (!spec || spec.arms.length !== 2) return null;
-  const ws = regexArmIndex(spec, false);
-  const comment = regexArmIndex(spec, true);
-  if (ws === null || comment === null) return null;
-  return { ws, comment };
-}
 function labeledTriviaRegexArms(trivia2) {
   const spec = analyzeLabeledTrivia(trivia2);
   if (!spec) return null;
@@ -1784,14 +1869,19 @@ function ensureTriviaFn(ctx) {
   const fnName = `_tf${ctx.triviaFnNames.size}`;
   ctx.triviaFnNames.set(trivia2, fnName);
   ctx.triviaCaptureNames.set(trivia2, fnName);
-  const fastKind = analyzeTriviaFastPath(trivia2);
-  const kindIndices = labeledTriviaKindIndices(trivia2);
-  if (fastKind) {
-    ctx.namedFnDecls.push(buildFastTriviaFnDecl(fnName, fastKind, kindIndices ?? void 0));
-    return fnName;
-  }
   const labeledSpec = analyzeLabeledTrivia(trivia2);
-  if (labeledSpec) {
+  if (!labeledSpec) {
+    const fastShapes = analyzeTriviaFastPath(trivia2);
+    if (fastShapes) {
+      ctx.namedFnDecls.push(buildFastTriviaFnDecl(fnName, fastShapes));
+      return fnName;
+    }
+  } else {
+    const labeledShapes = analyzeLabeledScannableRun(trivia2);
+    if (labeledShapes) {
+      ctx.namedFnDecls.push(buildLabeledScannableTriviaFnDecl(fnName, labeledShapes));
+      return fnName;
+    }
     const regexSpec = labeledTriviaRegexArms(trivia2);
     if (regexSpec) {
       const reNames = [];
@@ -1851,6 +1941,119 @@ function firstSetCond(codeVar, fs) {
     (r) => r.lo === r.hi ? `${codeVar} === ${r.lo}` : `(${codeVar} >= ${r.lo} && ${codeVar} <= ${r.hi})`
   ).join(" || ");
 }
+function captureRestoreBody(mL, mR, mTl, mLg) {
+  const base = `if (_ctx._cstLeaves) _ctx._cstLeaves.length = ${mL}; if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${mR}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${mTl}`;
+  return mLg ? `${base}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${mLg}` : base;
+}
+function mayLeavePartialCapture(p, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(p)) return false;
+  seen.add(p);
+  const d = p._def;
+  switch (d.tag) {
+    // Atomic / non-capturing-then-failing: a failure happens before any push.
+    case "literal":
+    case "regex":
+    case "keywords":
+    case "guard":
+    case "not":
+    case "trivia":
+    case "scanTo":
+    case "unknown":
+      return false;
+    // node() captures into its own private buffers and rolls them back on
+    // failure (emitNode restores _ctx.* and never pushes on the !ok path).
+    case "node":
+      return false;
+    // choice/firstMatch already roll back each failed arm; on overall failure
+    // nothing committed remains.
+    case "choice":
+      return false;
+    // optional never fails; many/oneOrMore only "fail" with zero captured items.
+    case "optional":
+    case "many":
+    case "oneOrMore":
+      return false;
+    // sepBy emits its own per-iteration rollback in emitSepBy.
+    case "sepBy":
+      return false;
+    // A sequence is the real case: an earlier capturing term followed by a term
+    // that can fail leaves the earlier captures buffered.
+    case "sequence": {
+      const parts = d.parsers;
+      if (parts.length < 2) return parts.some((x) => mayLeavePartialCapture(x, seen));
+      for (let i = 0; i < parts.length - 1; i++) {
+        if (hasNodeDef(parts[i]) || capturesLeaf(parts[i])) return true;
+      }
+      return false;
+    }
+    // Delegating wrappers: defer to the wrapped parser.
+    case "transform":
+    case "label":
+    case "expect":
+    case "withCtx":
+    case "grammar":
+      return mayLeavePartialCapture(d.parser, seen);
+    case "skip":
+      return mayLeavePartialCapture(d.main, seen);
+    case "recover":
+      return mayLeavePartialCapture(d.parser, seen);
+    case "lazy": {
+      try {
+        return mayLeavePartialCapture(d.thunk(), seen);
+      } catch {
+        return true;
+      }
+    }
+    // Unknown shapes: be safe and keep the rollback.
+    default:
+      return true;
+  }
+}
+function capturesLeaf(p, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(p)) return false;
+  seen.add(p);
+  const d = p._def;
+  switch (d.tag) {
+    case "literal":
+    case "regex":
+    case "keywords":
+    case "node":
+      return true;
+    case "not":
+    case "guard":
+    case "trivia":
+    case "unknown":
+      return false;
+    case "sequence":
+    case "choice":
+      return d.parsers.some((x) => capturesLeaf(x, seen));
+    case "sepBy":
+      return capturesLeaf(d.parser, seen) || capturesLeaf(d.separator, seen);
+    case "many":
+    case "oneOrMore":
+    case "optional":
+    case "transform":
+    case "label":
+    case "expect":
+    case "withCtx":
+    case "grammar":
+    case "recover":
+      return capturesLeaf(d.parser, seen);
+    case "skip":
+      return capturesLeaf(d.main, seen);
+    case "scanTo":
+      return true;
+    case "lazy": {
+      try {
+        return capturesLeaf(d.thunk(), seen);
+      } catch {
+        return true;
+      }
+    }
+    default:
+      return true;
+  }
+}
 function emitFallible(inner, ctx, pos) {
   const lbl = v(ctx, "_lbl");
   const okV = `${lbl}ok`;
@@ -1864,26 +2067,23 @@ function emitFallible(inner, ctx, pos) {
   ctx.failLabel = savedLabel;
   ctx.indent = savedIndent;
   const ind0 = ind(ctx);
-  const mL = ctx.capturing ? v(ctx, "_fcl") : null;
-  const mR = ctx.capturing ? v(ctx, "_fcr") : null;
-  const mTl = ctx.capturing ? v(ctx, "_fctl") : null;
-  const mLg = ctx.capturing ? v(ctx, "_fclg") : null;
+  const needsRollback = ctx.capturing && mayLeavePartialCapture(inner);
+  const mL = needsRollback ? v(ctx, "_fcl") : null;
+  const mR = needsRollback ? v(ctx, "_fcr") : null;
+  const mTl = needsRollback ? v(ctx, "_fctl") : null;
   const stmts = [
     `${ind0}let ${okV} = false, ${valV}, ${endV} = ${pos}`,
     ...mL ? [
       `${ind0}const ${mL} = _ctx._cstLeaves?.length ?? 0`,
       `${ind0}const ${mR} = _ctx._cstRawChildren?.length ?? 0`,
-      `${ind0}const ${mTl} = _ctx._cstTriviaLog?.length ?? 0`,
-      `${ind0}const ${mLg} = _ctx._triviaLog?.length ?? 0`
+      `${ind0}const ${mTl} = _ctx._cstTriviaLog?.length ?? 0`
     ] : [],
     `${ind0}${lbl}: {`,
     ...r.stmts,
-    `${ind0}  ${valV} = ${r.valueVar}`,
-    `${ind0}  ${endV} = ${r.endVar}`,
-    `${ind0}  ${okV} = true`,
+    `${ind0}  ${valV} = ${r.valueVar}; ${endV} = ${r.endVar}; ${okV} = true`,
     `${ind0}}`,
     ...mL ? [
-      `${ind0}if (!${okV}) { if (_ctx._cstLeaves) _ctx._cstLeaves.length = ${mL}; if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${mR}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${mTl}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${mLg} }`
+      `${ind0}if (!${okV}) { ${captureRestoreBody(mL, mR, mTl, null)} }`
     ] : []
   ];
   return { stmts, okVar: okV, valVar: valV, endVar: endV };
@@ -2119,11 +2319,11 @@ function emitLiteralsLongestFirst(def, sortedIndices, allExpected, ctx, pos) {
     const p = def.parsers[idx];
     const litVal = getCoreLiteralValue(p);
     const litLen = litVal.length;
-    const litCond = emitLiteralCondition(litVal, pos);
+    const litCond2 = emitLiteralCondition(litVal, pos);
     const kw = first ? "if" : "else if";
     first = false;
     const litEnd = `${pos} + ${litLen}`;
-    stmts.push(`${ind(ctx)}${kw} (${litCond}) {`);
+    stmts.push(`${ind(ctx)}${kw} (${litCond2}) {`);
     ctx.indent++;
     const tR = emitTransformChain(p, JSON.stringify(litVal), litEnd, pos, ctx);
     stmts.push(
@@ -2157,11 +2357,13 @@ function emitFirstMatch(def, allExpected, ctx, pos) {
       gateCond = `_mf[${gateIdx}](_ctx.state)`;
     }
     const skipCond = gateCond ? `!${resOkV} && ${gateCond}` : `!${resOkV}`;
-    const markLeaves = ctx.capturing ? v(ctx, "_cml") : null;
-    const markRaw = ctx.capturing ? v(ctx, "_cmr") : null;
-    const markTl = ctx.capturing ? v(ctx, "_cmtl") : null;
-    const markLog = ctx.capturing ? v(ctx, "_cmlg") : null;
-    const rollback = markLeaves ? `if (_ctx._cstLeaves) _ctx._cstLeaves.length = ${markLeaves}; if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${markRaw}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${markTl}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${markLog}` : "";
+    const armHasAutoNot = !!(autoNot && autoNot.length > 0);
+    const armNeedsRollback = ctx.capturing && (mayLeavePartialCapture(p) || armHasAutoNot && capturesLeaf(p));
+    const markLeaves = armNeedsRollback ? v(ctx, "_cml") : null;
+    const markRaw = armNeedsRollback ? v(ctx, "_cmr") : null;
+    const markTl = armNeedsRollback ? v(ctx, "_cmtl") : null;
+    const markLog = armNeedsRollback ? v(ctx, "_cmlg") : null;
+    const rollback = markLeaves ? captureRestoreBody(markLeaves, markRaw, markTl, markLog) : "";
     stmts.push(`${ind0}if (${skipCond}) {`);
     ctx.indent++;
     const ind1 = ind(ctx);
@@ -2191,11 +2393,7 @@ function emitFirstMatch(def, allExpected, ctx, pos) {
       stmts.push(`${ind0}  }`);
       if (rollback) stmts.push(`${ind0}  if (!${resOkV}) { ${rollback} }`);
     } else {
-      stmts.push(`${ind0}  if (${okVar}) {`);
-      stmts.push(`${ind0}    ${resValV} = ${valVar}`);
-      stmts.push(`${ind0}    ${resEndV} = ${endVar}`);
-      stmts.push(`${ind0}    ${resOkV} = true`);
-      stmts.push(`${ind0}  }`);
+      stmts.push(`${ind0}  if (${okVar}) { ${resValV} = ${valVar}; ${resEndV} = ${endVar}; ${resOkV} = true }`);
       if (rollback) stmts.push(`${ind0}  else { ${rollback} }`);
     }
     stmts.push(`${ind0}}`);
@@ -2493,6 +2691,16 @@ function emitRuntimeFallback(parser2, ctx, pos) {
   return { stmts, valueVar: vv, endVar: ev };
 }
 function emitLazy(p, def, ctx, pos) {
+  const usage = ctx.lazyUsage;
+  if (usage && (usage.counts.get(p) ?? 0) <= 1 && !usage.recursive.has(p)) {
+    let resolved;
+    try {
+      resolved = def.thunk();
+    } catch {
+      return emitRuntimeFallback(p, ctx, pos);
+    }
+    return emit(resolved, ctx, pos);
+  }
   if (!ctx.namedParsers.has(p)) {
     const fnName2 = `_pf${ctx.namedParsers.size}`;
     ctx.namedParsers.set(p, fnName2);
@@ -2540,6 +2748,22 @@ function emitRecover(def, ctx, pos) {
   ];
   return { stmts, valueVar: valVar, endVar };
 }
+function emitExpect(def, ctx, pos) {
+  const { stmts: innerStmts, okVar, valVar, endVar } = emitFallible(def.parser, ctx, pos);
+  const ind0 = ind(ctx);
+  const errV = v(ctx, "_err");
+  const stmts = [
+    ...innerStmts,
+    `${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})`,
+    `${ind0}  ${valVar} = ${errV}`,
+    `${ind0}  ${endVar} = ${pos}`,
+    `${ind0}  ${okVar} = true`,
+    `${ind0}}`
+  ];
+  return { stmts, valueVar: valVar, endVar };
+}
 function emit(p, ctx, pos) {
   const def = p._def;
   switch (def.tag) {
@@ -2648,6 +2872,8 @@ function emit(p, ctx, pos) {
       return emitScanTo(def, ctx, pos);
     case "recover":
       return emitRecover(def, ctx, pos);
+    case "expect":
+      return emitExpect(def, ctx, pos);
     case "guard": {
       const fnIdx = ctx.mapFns.length;
       ctx.mapFns.push(def.predicate);
@@ -2731,12 +2957,88 @@ function hasNodeDef(p, seen = /* @__PURE__ */ new Set()) {
       return hasNodeDef(d.sentinel, seen) || d.skip.some((x) => hasNodeDef(x, seen));
     case "recover":
       return hasNodeDef(d.parser, seen) || hasNodeDef(d.sentinel, seen);
+    case "expect":
+      return hasNodeDef(d.parser, seen);
     case "withCtx":
       return hasNodeDef(d.parser, seen);
     default:
       return false;
   }
 }
+function childrenOf(def) {
+  switch (def.tag) {
+    case "sequence":
+    case "choice":
+      return def.parsers;
+    case "many":
+    case "optional":
+    case "transform":
+    case "trivia":
+    case "label":
+    case "grammar":
+    case "not":
+    case "node":
+    case "withCtx":
+    case "expect":
+      return [def.parser];
+    // emitMany's oneOrMore branch and emitSepBy both codegen `def.parser` TWICE
+    // (a mandatory first match, then again inside the repeat loop) — two real
+    // emit() call sites, so the usage analysis must see two edges here or it
+    // undercounts a single-use `parser` ref as inline-safe when it's actually
+    // referenced from two positions within this one compiled function.
+    case "oneOrMore":
+      return [def.parser, def.parser];
+    case "sepBy":
+      return [def.parser, def.parser, def.separator];
+    case "skip":
+      return [def.main, def.skipped];
+    case "recover":
+      return [def.parser, def.sentinel];
+    case "scanTo":
+      return [def.sentinel, ...def.skip];
+    case "lazy":
+    case "literal":
+    case "regex":
+    case "keywords":
+    case "guard":
+    case "unknown":
+      return [];
+  }
+}
+function analyzeLazyUsage(root) {
+  return analyzeLazyUsageMulti([root]);
+}
+function analyzeLazyUsageMulti(roots) {
+  const counts = /* @__PURE__ */ new Map();
+  const recursive = /* @__PURE__ */ new Set();
+  const descended = /* @__PURE__ */ new Set();
+  const active = /* @__PURE__ */ new Set();
+  function walk(p) {
+    const def = p._def;
+    if (def.tag === "lazy") {
+      counts.set(p, (counts.get(p) ?? 0) + 1);
+      if (active.has(p)) {
+        recursive.add(p);
+        return;
+      }
+      if (descended.has(p)) return;
+      descended.add(p);
+      let resolved;
+      try {
+        resolved = def.thunk();
+      } catch {
+        return;
+      }
+      active.add(p);
+      walk(resolved);
+      active.delete(p);
+      return;
+    }
+    for (const child of childrenOf(def)) walk(child);
+  }
+  for (const root of roots) walk(root);
+  return { counts, recursive };
+}
 function compile(combinator, mapFnSources) {
   const ctx = {
     vars: 0,
@@ -2753,7 +3055,8 @@ function compile(combinator, mapFnSources) {
     triviaCaptureNames: /* @__PURE__ */ new Map(),
     triviaFnNames: /* @__PURE__ */ new Map(),
     namedFnDecls: [],
-    capturing: hasNodeDef(combinator)
+    capturing: hasNodeDef(combinator),
+    lazyUsage: analyzeLazyUsage(combinator)
   };
   const r = emit(combinator, ctx, "_pos");
   const collatorDecl = ctx.needsCollator ? `const _collator = new Intl.Collator(undefined, { sensitivity: 'accent' })
@@ -2799,6 +3102,11 @@ 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
+    // 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
+    // (span.end < input.length) instead, which is mode-agnostic.
     parseWithErrors(input, pos = 0) {
       const errors = [];
       const result = fn(input, pos, ctx.runtimeParsers, ctx.mapFns, ctx.buildFns, { ...defaultCtx, _errors: errors });
@@ -2910,6 +3218,58 @@ function isParseError(value) {
   return typeof value === "object" && value !== null && value._tag === "parseError";
 }
 
+// src/combinators/expect.ts
+function staticExpected(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(staticExpected);
+    case "sequence":
+      return def.parsers.length > 0 ? staticExpected(def.parsers[0]) : [];
+    case "node":
+    case "grammar":
+    case "trivia":
+    case "optional":
+    case "many":
+    case "oneOrMore":
+    case "transform":
+    case "not":
+      return staticExpected(def.parser);
+    case "lazy":
+      return staticExpected(def.thunk());
+    default:
+      return [];
+  }
+}
+function expect(combinator, label2) {
+  const expected = label2 !== void 0 ? [label2] : staticExpected(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/combinators/completions.ts
 function completionsAt(combinator, input, offset) {
   const probe = { offset, best: null };
@@ -2938,7 +3298,11 @@ function scanTo(sentinel, { skip: skip2 = [], orEOF = false } = {}) {
     _def: { tag: "scanTo", sentinel, skip: skip2, orEOF },
     parse(input, pos, ctx) {
       let cur = pos;
-      const probeCtx = { trackLines: ctx.trackLines, state: ctx.state };
+      const probeCtx = {
+        trackLines: ctx.trackLines,
+        state: ctx.state,
+        ...ctx._errors !== void 0 ? { _errors: ctx._errors } : {}
+      };
       const emit2 = (end) => {
         if (end > pos && cstCaptureActive(ctx)) {
           const leaf = { _tag: "leaf", value: input.slice(pos, end), span: { start: pos, end } };
@@ -2974,20 +3338,46 @@ function scanTo(sentinel, { skip: skip2 = [], orEOF = false } = {}) {
 }
 function balanced(open, close, options = {}) {
   const self = ref();
-  const inner = scanTo(literal(close), {
-    ...options,
-    skip: [self, ...options.skip ?? []]
-  });
+  const skips = options.skip ?? [];
+  const stop = /* @__PURE__ */ new Set([open, close]);
+  let bounded = true;
+  for (const sk of skips) {
+    const cs = firstSetClassChars(sk);
+    if (cs === null) {
+      bounded = false;
+      break;
+    }
+    for (const ch of cs) stop.add(ch);
+  }
+  const cls = [...stop].map(escapeClassChar).join("");
+  const content = bounded ? regex(new RegExp(`[^${cls}]+`)) : regex(new RegExp(`[^${escapeClassChar(open)}${escapeClassChar(close)}]`));
+  const inner = many(choice(self, ...skips, content));
   const combi = transform(
-    sequence(literal(open), inner, literal(close)),
-    ([o, content, c]) => o + content + c
+    sequence(literal(open), inner, expect(literal(close), close)),
+    // parts: strings (content/self) or arrays (a sequence-shaped skip) or a
+    // ParseError (recovered close). `c` is the close string or a ParseError.
+    ([o, parts, c]) => o + parts.map((p) => typeof p === "string" ? p : Array.isArray(p) ? p.join("") : "").join("") + (typeof c === "string" ? c : "")
   );
   if (combi._def.tag === "transform") {
-    combi._def.fnSrc = "([o, content, c]) => o + content + c";
+    combi._def.fnSrc = '([o, parts, c]) => o + parts.map(p => typeof p === "string" ? p : Array.isArray(p) ? p.join("") : "").join("") + (typeof c === "string" ? c : "")';
   }
   self.define(combi);
   return combi;
 }
+function firstSetClassChars(c) {
+  const fs = c._meta.firstSet;
+  if (fs.kind === "empty") return [];
+  if (fs.kind !== "ranges") return null;
+  const out = [];
+  for (const { lo, hi } of fs.ranges) {
+    if (hi - lo > 8) return null;
+    for (let cp = lo; cp <= hi; cp++) out.push(String.fromCodePoint(cp));
+  }
+  return out;
+}
+function escapeClassChar(ch) {
+  return ch.replace(/[\\\]^-]/g, "\\$&");
+}
 
 // src/functional/doc.ts
 function isNode(x) {