parseman 0.7.0 → 0.8.0

package/dist/combinators/expect.d.ts

@@ -0,0 +1,36 @@
+import type { Combinator, ParseError } from '../types.ts';
+export type { ParseError };
+/**
+ * Statically derive the "expected" token set from a combinator's structure,
+ * so a failure can name what it wanted without running anything:
+ *
+ *   literal('}')        -> ['"}"']
+ *   keywords(['a','b']) -> ['"a"', '"b"']
+ *   choice(x, y)        -> expected(x) ++ expected(y)   (all alternatives)
+ *   sequence(a, b, …)   -> expected(a)                  (only the first term can fail first)
+ *   label('s', x)       -> ['s']                        (an explicit name wins)
+ *
+ * This is what lets expect() report a meaningful, IDENTICAL expectation in both
+ * the interpreter and the compiled output (the compiled path does not rebuild the
+ * runtime `expected` array, so it reads this precomputed set instead).
+ */
+export declare function staticExpected(c: Combinator<unknown>): string[];
+/**
+ * Required-token combinator. Tries `combinator`; on success returns it verbatim.
+ * On failure it does NOT fail — it records a {@link ParseError} (the statically
+ * derived expected set, or `label` when given) into `ctx._errors` and RECOVERS IN
+ * PLACE, returning a zero-width success so the enclosing sequence continues as if
+ * the token were present.
+ *
+ * Use it to mark required delimiters/terminators (`}` `)` `;`, a selector before a
+ * block) so a missing one is reported with position + expectation rather than
+ * aborting the whole parse or being silently swallowed by a catch-all.
+ *
+ *   sequence(literal('{'), declList, expect(literal('}'), '}'))
+ *
+ * Errors are only collected when the parse runs with `{ recover: true }`; without
+ * it, expect() still recovers in place but records nothing (zero overhead beyond
+ * the inner attempt).
+ */
+export declare function expect<T>(combinator: Combinator<T>, label?: string): Combinator<T | ParseError>;
+//# sourceMappingURL=expect.d.ts.map

package/dist/combinators/expect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expect.d.ts","sourceRoot":"","sources":["../../src/combinators/expect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,UAAU,EAAE,MAAM,aAAa,CAAA;AAEhG,YAAY,EAAE,UAAU,EAAE,CAAA;AAE1B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,CAoB/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,GAAG,UAAU,CAAC,CAmB/F"}

package/dist/combinators/grammar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/combinators/grammar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAGxE,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG;IACzC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IACnC,gFAAgF;IAChF,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IACpC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;CACrE;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAwCrF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAElE;AAED,wBAAgB,KAAK,CAAC,CAAC,EACrB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,YAAiB,GACtB,WAAW,CAAC,CAAC,CAAC,CAehB"}
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/combinators/grammar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAa,MAAM,aAAa,CAAA;AAGnF,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG;IACzC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IACnC,gFAAgF;IAChF,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IACpC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;CACrE;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAwCrF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAElE;AAED,wBAAgB,KAAK,CAAC,CAAC,EACrB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,YAAiB,GACtB,WAAW,CAAC,CAAC,CAAC,CAuBhB"}

package/dist/combinators/scanTo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanTo.d.ts","sourceRoot":"","sources":["../../src/combinators/scanTo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAOpF,MAAM,MAAM,aAAa,GAAG;IAC1B,uGAAuG;IACvG,IAAI,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAA;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CACpB,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,EAC7B,EAAE,IAAS,EAAE,KAAa,EAAE,GAAE,aAAkB,GAC/C,UAAU,CAAC,MAAM,CAAC,CA8DpB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,UAAU,CAAC,MAAM,CAAC,CAYpB"}
+{"version":3,"file":"scanTo.d.ts","sourceRoot":"","sources":["../../src/combinators/scanTo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAYpF,MAAM,MAAM,aAAa,GAAG;IAC1B,uGAAuG;IACvG,IAAI,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAA;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CACpB,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,EAC7B,EAAE,IAAS,EAAE,KAAa,EAAE,GAAE,aAAkB,GAC/C,UAAU,CAAC,MAAM,CAAC,CAoEpB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,UAAU,CAAC,MAAM,CAAC,CA0CpB"}

package/dist/compiler/codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/compiler/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAuB,WAAW,EAAE,YAAY,EAAE,UAAU,EAAkB,MAAM,aAAa,CAAA;AAm1CzH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAClD,kGAAkG;IAClG,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAChF;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG;QAAE,MAAM,EAAE,UAAU,EAAE,CAAA;KAAE,CAAA;IACvF,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC,CAAA;AAiCD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC,CAgGhG"}
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/compiler/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAuB,WAAW,EAAE,YAAY,EAAE,UAAU,EAAkB,MAAM,aAAa,CAAA;AA2/CzH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAClD,kGAAkG;IAClG,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAChF;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG;QAAE,MAAM,EAAE,UAAU,EAAE,CAAA;KAAE,CAAA;IACvF,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC,CAAA;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC,CAqGhG"}

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) };
@@ -1851,6 +1855,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 +1981,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 };
@@ -2157,11 +2271,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 +2307,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}}`);
@@ -2540,6 +2652,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 +2776,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,6 +2861,8 @@ 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:
@@ -2799,6 +2931,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 +3047,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 +3127,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 } };
@@ -2973,16 +3166,47 @@ function scanTo(sentinel, { skip: skip2 = [], orEOF = false } = {}) {
   };
 }
 function balanced(open, close, options = {}) {
-  const inner = scanTo(literal(close), options);
+  const self = ref();
+  const skips = options.skip ?? [];
+  const stop = /* @__PURE__ */ new Set([open, close]);
+  let bounded = true;
+  for (const sk of skips) {
+    const cs = firstSetClassChars(sk);
+    if (cs === null) {
+      bounded = false;
+      break;
+    }
+    for (const ch of cs) stop.add(ch);
+  }
+  const cls = [...stop].map(escapeClassChar).join("");
+  const content = bounded ? regex(new RegExp(`[^${cls}]+`)) : regex(new RegExp(`[^${escapeClassChar(open)}${escapeClassChar(close)}]`));
+  const inner = many(choice(self, ...skips, content));
   const combi = transform(
-    sequence(literal(open), inner, 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) {