parseman 0.27.1 → 0.28.0

package/dist/index.js

@@ -59,6 +59,7 @@ function matchesEmpty(p, seen = /* @__PURE__ */ new Set()) {
     case "label":
     case "trivia":
     case "token":
+    case "leaf":
     case "expect":
     case "withCtx":
     case "node":
@@ -122,6 +123,7 @@ function firstSetOf(p, seen = /* @__PURE__ */ new Set()) {
     case "label":
     case "trivia":
     case "token":
+    case "leaf":
     case "node":
     case "grammar":
     case "expect":
@@ -190,10 +192,10 @@ function beginCstNodeCapture(ctx) {
 }
 function finishCstBuf(buf) {
   if (!buf) return { children: EMPTY, rawChildren: EMPTY, triviaLog: EMPTY_TL };
-  const children = buf.ch ?? (buf.single !== void 0 ? [buf.single] : EMPTY);
+  const children2 = buf.ch ?? (buf.single !== void 0 ? [buf.single] : EMPTY);
   const rawChildren = buf.raw ?? (buf.rawSingle !== void 0 ? [buf.rawSingle] : EMPTY);
   const triviaLog = buf.tl ?? EMPTY_TL;
-  return { children, rawChildren, triviaLog };
+  return { children: children2, rawChildren, triviaLog };
 }
 function endCstNodeCapture(ctx, saved) {
   const materialized = finishCstBuf(ctx._cstBuf);
@@ -205,8 +207,8 @@ function endCstNodeCapture(ctx, saved) {
   ctx.captureTrivia = saved.cap;
   return materialized;
 }
-function pushCstLeaf(ctx, leaf) {
-  pushCstChild(ctx, leaf, leaf);
+function pushCstLeaf(ctx, leaf2) {
+  pushCstChild(ctx, leaf2, leaf2);
 }
 function pushCstChild(ctx, built, rawEntry) {
   const b = ctx._cstBuf;
@@ -940,10 +942,13 @@ function deriveExpected(c) {
       return def.parsers.flatMap(deriveExpected);
     case "sequence":
       return def.parsers.length > 0 ? deriveExpected(def.parsers[0]) : [];
+    case "attempt":
+      return deriveExpected(def.parser);
     case "node":
     case "grammar":
     case "trivia":
     case "token":
+    case "leaf":
     case "optional":
     case "many":
     case "oneOrMore":
@@ -1721,6 +1726,24 @@ function sequence(...parsers) {
   };
 }
 
+// src/combinators/attempt.ts
+function attempt(parser2) {
+  return {
+    _tag: "attempt",
+    _meta: parser2._meta,
+    _def: { tag: "attempt", parser: parser2 },
+    parse(input, pos, ctx) {
+      const mark = saveCstMark(ctx);
+      const log = ctx._triviaLog?.length;
+      const result = parser2.parse(input, pos, ctx);
+      if (result.ok) return result;
+      rollbackCstCapture(ctx, mark);
+      if (log !== void 0 && ctx._triviaLog) ctx._triviaLog.length = log;
+      return { ok: false, expected: result.expected, span: { start: pos, end: pos } };
+    }
+  };
+}
+
 // src/combinators/repeat.ts
 function repItem(combinator, input, cur, ctx) {
   const mark = saveTriviaMark(ctx);
@@ -2030,10 +2053,14 @@ function markUnusedValues(root) {
       case "label":
       case "trivia":
       case "token":
+      case "attempt":
       case "withCtx":
       case "expect":
         visit(def.parser, consumed);
         return;
+      case "leaf":
+        visit(def.parser, true);
+        return;
       case "lazy":
         return;
       default:
@@ -2156,6 +2183,20 @@ function confirmedBuildArity(src) {
   if (/\barguments\b/.test(s)) return null;
   return parts.length;
 }
+function buildReadsChildren(def) {
+  if (!def.build) return true;
+  const src = def.buildSrc ?? def.build.toString();
+  const arity = confirmedBuildArity(src);
+  if (arity === null) return true;
+  return arity >= 1;
+}
+function buildReadsRaw(def) {
+  if (!def.build) return true;
+  const src = def.buildSrc ?? def.build.toString();
+  const arity = confirmedBuildArity(src);
+  if (arity === null) return true;
+  return arity >= 4;
+}
 function buildReadsTrivia(def) {
   if (!def.build) return true;
   const src = def.buildSrc ?? def.build.toString();
@@ -2211,9 +2252,11 @@ function parserHasOwnFields(p, seen = /* @__PURE__ */ new Set()) {
     case "many":
     case "oneOrMore":
     case "optional":
+    case "attempt":
     case "transform":
     case "trivia":
     case "token":
+    case "leaf":
     case "label":
     case "expect":
     case "withCtx":
@@ -2246,9 +2289,11 @@ function parserHasTriviaSite(p, seen = /* @__PURE__ */ new Set()) {
     case "keywords":
     case "guard":
     case "token":
+    case "leaf":
       return false;
     // Transparent single-child wrappers: recurse.
     case "optional":
+    case "attempt":
     case "transform":
     case "trivia":
     case "label":
@@ -2295,6 +2340,7 @@ function parserEnablesTriviaCapture(p, seen = /* @__PURE__ */ new Set()) {
     case "many":
     case "oneOrMore":
     case "optional":
+    case "attempt":
     case "transform":
     case "trivia":
     case "token":
@@ -2304,6 +2350,10 @@ function parserEnablesTriviaCapture(p, seen = /* @__PURE__ */ new Set()) {
     case "withCtx":
     case "not":
       return parserEnablesTriviaCapture(d.parser, seen);
+    // leaf() clears the inner CST/trivia collector and publishes only its own
+    // terminal result. An inner parser() capture cannot reach this node.
+    case "leaf":
+      return false;
     case "lazy": {
       try {
         return parserEnablesTriviaCapture(d.thunk(), seen);
@@ -2382,12 +2432,12 @@ function node(typeOrCombinator, combinatorOrBuild, buildOrOpts, maybeOpts) {
       const fields = capturesFields ? buildFieldMap(ctx._fields) : void 0;
       ctx._fields = savedFields;
       ctx._triviaCaptureMask = savedMask;
-      const { children, rawChildren, triviaLog } = endCstNodeCapture(ctx, saved);
+      const { children: children2, rawChildren, triviaLog } = endCstNodeCapture(ctx, saved);
       if (!r.ok) return r;
       const st = clonesState && ctx.state !== void 0 ? Object.assign({}, ctx.state) : void 0;
       const nodeType = def.type ?? missingInferredType();
       const cstOutput = ctx.build?._parsemanCstOutput === true;
-      const built = unwrap && children.length === 1 ? unwrapChild(children[0]) : collapse && children.length === 1 ? children[0] : !build && ctx.build?._parsemanCstCollapse && children.length === 1 && rawChildren.length === 1 && ctx.build._parsemanCstCollapse(nodeType, children[0], children, rawChildren) ? children[0] : build ? cstOutput && ctx.build ? ctx.build(nodeType, children, fields, r.span, rawChildren, triviaLog, st) : build(children, fields, r.span, rawChildren, triviaLog, st) : ctx.build ? ctx.build(nodeType, children, fields, r.span, rawChildren, triviaLog, st) : { _tag: "node", type: nodeType, span: { start: r.span.start, end: r.span.end }, state: st ?? null, children };
+      const built = unwrap && children2.length === 1 ? unwrapChild(children2[0]) : collapse && children2.length === 1 ? children2[0] : !build && ctx.build?._parsemanCstCollapse && children2.length === 1 && rawChildren.length === 1 && ctx.build._parsemanCstCollapse(nodeType, children2[0], children2, rawChildren) ? children2[0] : build ? cstOutput && ctx.build ? ctx.build(nodeType, children2, fields, r.span, rawChildren, triviaLog, st) : build(children2, fields, r.span, rawChildren, triviaLog, st) : ctx.build ? ctx.build(nodeType, children2, fields, r.span, rawChildren, triviaLog, st) : { _tag: "node", type: nodeType, span: { start: r.span.start, end: r.span.end }, state: st ?? null, children: children2 };
       const rawEntry = isCstChild(built) ? built : { _tag: "leaf", value: typeof built === "string" ? built : typeof built === "object" && built !== null ? input.slice(r.span.start, r.span.end) : "", span: r.span };
       if (saved.buf !== void 0 || saved.ch !== void 0) {
         pushCstChild(ctx, built, rawEntry);
@@ -2618,6 +2668,141 @@ function token(root) {
     }
   };
 }
+function leaf(root, fn) {
+  const meta = {
+    firstSet: root._meta.firstSet,
+    canMatchNewline: root._meta.canMatchNewline,
+    isTrivia: false
+  };
+  return {
+    _tag: "leaf",
+    _meta: meta,
+    _def: { tag: "leaf", parser: root, fn },
+    parse(input, pos, ctx) {
+      const savedBuf = ctx._cstBuf;
+      const savedChildren = ctx._cstChildren;
+      const savedLeaves = ctx._cstLeaves;
+      const savedRaw = ctx._cstRawChildren;
+      const savedTriviaLog = ctx._cstTriviaLog;
+      const savedOuterTriviaLog = ctx._triviaLog;
+      const wasCapturing = cstCaptureActive(ctx);
+      ctx._cstBuf = void 0;
+      ctx._cstChildren = void 0;
+      ctx._cstLeaves = void 0;
+      ctx._cstRawChildren = void 0;
+      ctx._cstTriviaLog = void 0;
+      delete ctx._triviaLog;
+      let result;
+      try {
+        result = root.parse(input, pos, ctx);
+      } finally {
+        ctx._cstBuf = savedBuf;
+        ctx._cstChildren = savedChildren;
+        ctx._cstLeaves = savedLeaves;
+        ctx._cstRawChildren = savedRaw;
+        ctx._cstTriviaLog = savedTriviaLog;
+        if (savedOuterTriviaLog === void 0) delete ctx._triviaLog;
+        else ctx._triviaLog = savedOuterTriviaLog;
+      }
+      if (!result.ok) return result;
+      const value = fn(result.value, result.span);
+      if (wasCapturing) pushCstLeaf(ctx, { _tag: "leaf", value, span: result.span });
+      return { ok: true, value, span: result.span };
+    }
+  };
+}
+
+// src/compiler/grammar-coverage-ids.ts
+function children(def, winners) {
+  switch (def.tag) {
+    case "sequence":
+    case "choice":
+      return def.parsers;
+    case "many":
+    case "oneOrMore":
+    case "optional":
+    case "attempt":
+    case "transform":
+    case "trivia":
+    case "token":
+    case "leaf":
+    case "label":
+    case "field":
+    case "grammar":
+    case "not":
+    case "node":
+    case "guard":
+    case "withCtx":
+    case "recover":
+    case "expect":
+      return "parser" in def ? [def.parser] : [];
+    case "sepBy":
+      return [def.parser, def.separator];
+    case "skip":
+      return [def.main, def.skipped];
+    case "scanTo":
+      return [def.sentinel, ...def.skip];
+    case "lazy": {
+      let resolved;
+      try {
+        resolved = def.thunk();
+      } catch {
+        return [];
+      }
+      const name = resolved._ruleName;
+      return name && winners?.[name] ? [winners[name]] : [resolved];
+    }
+    default:
+      return [];
+  }
+}
+function buildGrammarPlan(entry, winners) {
+  const definitions = /* @__PURE__ */ new Map();
+  const choices = /* @__PURE__ */ new WeakMap();
+  const attempts = /* @__PURE__ */ new WeakMap();
+  const labels = /* @__PURE__ */ new WeakMap();
+  const rules2 = /* @__PURE__ */ new WeakMap();
+  const winnerNames = /* @__PURE__ */ new Map();
+  if (winners) {
+    for (const [name, winner] of Object.entries(winners)) {
+      winnerNames.set(winner, name);
+      if (winner._def.tag === "lazy") {
+        try {
+          winnerNames.set(winner._def.thunk(), name);
+        } catch {
+        }
+      }
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (parser2, path) => {
+    if (seen.has(parser2)) return;
+    seen.add(parser2);
+    const rule = winnerNames.get(parser2) ?? parser2._ruleName;
+    if (rule && (winnerNames.has(parser2) || parser2._def.tag !== "lazy")) {
+      const id = `rule:${rule}`;
+      definitions.set(id, { id, kind: "rule" });
+      rules2.set(parser2, id);
+    }
+    if (parser2._def.tag === "choice") {
+      const ids = parser2._def.parsers.map((_, index) => `choice:${path}/arm:${index}`);
+      choices.set(parser2, ids);
+      ids.forEach((id) => definitions.set(id, { id, kind: "choice-arm" }));
+    }
+    if (parser2._def.tag === "attempt") attempts.set(parser2, `attempt:${path}`);
+    if (parser2._def.tag === "label") {
+      const id = `label:${path}`;
+      labels.set(parser2, [id]);
+      definitions.set(id, { id, kind: "label" });
+    }
+    children(parser2._def, winners).forEach((child, index) => visit(child, `${path}/${parser2._def.tag}:${index}`));
+  };
+  const roots = Array.isArray(entry) ? entry : [entry];
+  for (const root of roots) {
+    visit(root, winnerNames.get(root) ?? root._ruleName ?? "entry");
+  }
+  return { definitions: [...definitions.values()].sort((a, b) => a.id.localeCompare(b.id)), choices, attempts, labels, rules: rules2 };
+}
 
 // src/compiler/scannable-run.ts
 var BACKSLASH = 92;
@@ -4002,21 +4187,23 @@ function probeUpdate(ctx, expectedArr, posExpr, constant = true) {
 }
 function failBody(ctx, expected, posExpr) {
   const probe = probeUpdate(ctx, `[${expected}]`, posExpr);
+  const trace = ctx.activeCoverageRuleId === void 0 ? "" : `_ctx._grammarTrace?.write({ id: ${JSON.stringify(ctx.activeCoverageRuleId)}, phase: 'failure', offset: ${posExpr} }); `;
   if (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} }`;
+    if (!ctx.recordFail) return probe ? `{ ${probe}${trace}break ${ctx.failLabel} }` : trace ? `{ ${trace}break ${ctx.failLabel} }` : `break ${ctx.failLabel}`;
+    return `{ ${probe}_ctx._fe = ${posExpr}; _ctx._fx = ${hoistExpected(ctx, `[${expected}]`)}; ${trace}break ${ctx.failLabel} }`;
   }
-  return probe + failReturn(expected, posExpr);
+  return probe + trace + failReturn(expected, posExpr);
 }
 function failArrBody(ctx, expectedArr, posExpr, constant = true) {
   const probe = probeUpdate(ctx, expectedArr, posExpr, constant);
+  const trace = ctx.activeCoverageRuleId === void 0 ? "" : `_ctx._grammarTrace?.write({ id: ${JSON.stringify(ctx.activeCoverageRuleId)}, phase: 'failure', offset: ${posExpr} }); `;
   if (ctx.failLabel) {
-    if (!ctx.recordFail) return probe ? `{ ${probe}break ${ctx.failLabel} }` : `break ${ctx.failLabel}`;
+    if (!ctx.recordFail) return probe ? `{ ${probe}${trace}break ${ctx.failLabel} }` : trace ? `{ ${trace}break ${ctx.failLabel} }` : `break ${ctx.failLabel}`;
     const fx = constant ? hoistExpected(ctx, expectedArr) : expectedArr;
-    return `{ ${probe}_ctx._fe = ${posExpr}; _ctx._fx = ${fx}; break ${ctx.failLabel} }`;
+    return `{ ${probe}_ctx._fe = ${posExpr}; _ctx._fx = ${fx}; ${trace}break ${ctx.failLabel} }`;
   }
-  if (!constant) return `${probe}return { ok: false, expected: [...${expectedArr}], span: { start: ${posExpr}, end: ${posExpr} } }`;
-  return probe + failReturnArr(expectedArr, posExpr);
+  if (!constant) return `${probe}${trace}return { ok: false, expected: [...${expectedArr}], span: { start: ${posExpr}, end: ${posExpr} } }`;
+  return probe + trace + failReturnArr(expectedArr, posExpr);
 }
 function resultFromRecorded(feExpr = "_ctx._fe", fxExpr = "_ctx._fx") {
   return `return { ok: false, expected: [...${fxExpr}], span: { start: ${feExpr}, end: ${feExpr} } }`;
@@ -4051,7 +4238,7 @@ var NAMED_FN_END = "_pfEnd";
 function namedFnPrelude() {
   return [`const ${NAMED_FN_FAIL} = {}`, `let ${NAMED_FN_END}`];
 }
-function pushNamedFnDecl(ctx, fnName, bodyStmts, valueVar, endVar) {
+function pushNamedFnDecl(ctx, fnName, bodyStmts, valueVar, endVar, failureRuleId) {
   ctx.namedFnDecls.push([
     `function ${fnName}(input, _pos, _ctx) {`,
     `  _pfail: {`,
@@ -4059,6 +4246,7 @@ function pushNamedFnDecl(ctx, fnName, bodyStmts, valueVar, endVar) {
     `    ${NAMED_FN_END} = ${endVar}`,
     `    return ${valueVar}`,
     `  }`,
+    ...failureRuleId === void 0 ? [] : [`  _ctx._grammarTrace?.write({ id: ${JSON.stringify(failureRuleId)}, phase: 'failure', offset: _ctx._fe ?? _pos })`],
     `  return ${NAMED_FN_FAIL}`,
     `}`
   ].join("\n"));
@@ -4220,6 +4408,7 @@ function mayLeavePartialCapture(p, seen = /* @__PURE__ */ new Set()) {
     case "not":
     case "trivia":
     case "token":
+    case "leaf":
     case "scanTo":
     case "unknown":
       return false;
@@ -4231,6 +4420,8 @@ function mayLeavePartialCapture(p, seen = /* @__PURE__ */ new Set()) {
     // nothing committed remains.
     case "choice":
       return false;
+    case "attempt":
+      return false;
     // optional never fails; many/oneOrMore only "fail" with zero captured items.
     case "optional":
     case "many":
@@ -4283,6 +4474,7 @@ function capturesLeaf(p, seen = /* @__PURE__ */ new Set()) {
     case "keywords":
     case "node":
     case "token":
+    case "leaf":
       return true;
     case "not":
     case "guard":
@@ -4297,6 +4489,7 @@ function capturesLeaf(p, seen = /* @__PURE__ */ new Set()) {
     case "many":
     case "oneOrMore":
     case "optional":
+    case "attempt":
     case "transform":
     case "label":
     case "field":
@@ -4638,35 +4831,55 @@ function needsFirstSetGuard(p) {
   const fs = p._meta.firstSet;
   return fs.kind !== "any" && !canMatchEmptyAtStart(p);
 }
-function emitDisjointArm(p, ctx, pos, valV, endV) {
-  if (failsAtStart(p)) {
+function coverageHit(ctx, id, offset = "_pos", end) {
+  return id === void 0 ? [] : [
+    `${ind(ctx)}_ctx._grammarCoverage?.(${JSON.stringify(id)})`,
+    `${ind(ctx)}_ctx._grammarTrace?.write({ id: ${JSON.stringify(id)}, phase: 'selected', offset: ${offset}${end === void 0 ? "" : `, end: ${end}`} })`,
+    `${ind(ctx)}_ctx._grammarTrace?.write({ id: ${JSON.stringify(id)}, phase: 'success', offset: ${offset}${end === void 0 ? "" : `, end: ${end}`} })`
+  ];
+}
+function coverageAttempt(ctx, id, offset) {
+  return id === void 0 ? [] : [`${ind(ctx)}_ctx._grammarTrace?.write({ id: ${JSON.stringify(id)}, phase: 'attempt', offset: ${offset} })`];
+}
+function coverageFailureBacktrack(ctx, id, failureOffset, startOffset) {
+  return id === void 0 ? [] : [
+    `${ind(ctx)}_ctx._grammarTrace?.write({ id: ${JSON.stringify(id)}, phase: 'failure', offset: ${failureOffset} })`,
+    `${ind(ctx)}_ctx._grammarTrace?.write({ id: ${JSON.stringify(id)}, phase: 'backtrack', offset: ${startOffset} })`
+  ];
+}
+function emitDisjointArm(p, ctx, pos, valV, endV, coverageId) {
+  if (failsAtStart(p) && coverageId === void 0) {
     const r = emit(p, ctx, pos);
-    return [...r.stmts, `${ind(ctx)}${valV} = ${r.valueVar}`, `${ind(ctx)}${endV} = ${r.endVar}`];
+    return [...coverageAttempt(ctx, coverageId, pos), ...r.stmts, `${ind(ctx)}${valV} = ${r.valueVar}`, `${ind(ctx)}${endV} = ${r.endVar}`, ...coverageHit(ctx, coverageId, pos, r.endVar)];
   }
   const { stmts, okVar, valVar, endVar } = emitFallible(p, ctx, pos);
   return [
+    ...coverageAttempt(ctx, coverageId, pos),
     ...stmts,
-    ...emitIfFail(ctx, `!${okVar}`, failArrBody(ctx, "_ctx._fx", pos, false)),
+    ...emitIfFail(ctx, `!${okVar}`, `${coverageFailureBacktrack(ctx, coverageId, "_ctx._fe", pos).join("; ")}; ${failArrBody(ctx, "_ctx._fx", pos, false)}`),
     `${ind(ctx)}${valV} = ${valVar}`,
-    `${ind(ctx)}${endV} = ${endVar}`
+    `${ind(ctx)}${endV} = ${endVar}`,
+    ...coverageHit(ctx, coverageId, pos, endVar)
   ];
 }
-function emitDisjointArmGated(def, i, ctx, pos, valV, endV) {
+function emitDisjointArmGated(def, i, ctx, pos, valV, endV, coverageId) {
   const p = def.parsers[i];
   const gate = def.gates[i];
-  if (!gate) return emitDisjointArm(p, ctx, pos, valV, endV);
+  if (!gate) return emitDisjointArm(p, ctx, pos, valV, endV, coverageId);
   const gateIdx = ctx.mapFns.length;
   ctx.mapFns.push(gate);
   ctx.mapFnSrcs.push(def.gateSrcs?.[i] ?? null);
   const gateCond = `${mfRef(ctx)}[${gateIdx}](_ctx.state)`;
   const stmts = [`${ind(ctx)}if (${gateCond}) {`];
   ctx.indent++;
-  stmts.push(...emitDisjointArm(p, ctx, pos, valV, endV));
+  stmts.push(...emitDisjointArm(p, ctx, pos, valV, endV, coverageId));
   ctx.indent--;
   stmts.push(`${ind(ctx)}} else { ${failArrBody(ctx, deriveExpectedArr([p]), pos)} }`);
   return stmts;
 }
-function emitChoice(def, ctx, pos) {
+function emitChoice(parser2, def, ctx, pos) {
+  const coverageIds = ctx.coverage?.plan.choices.get(parser2);
+  const coverageBase = coverageIds?.[0]?.slice(0, -1);
   const allExpected = deriveExpectedArr(def.parsers);
   if (def.disjoint) {
     const codeV = v(ctx, "_code");
@@ -4685,7 +4898,7 @@ function emitChoice(def, ctx, pos) {
         stmts.push(`${ind(ctx)}{`);
         ctx.indent++;
         stmts.push(
-          ...emitDisjointArmGated(def, i, ctx, pos, valV, endV),
+          ...emitDisjointArmGated(def, i, ctx, pos, valV, endV, coverageIds?.[i]),
           `${ind(ctx)}break`
         );
         ctx.indent--;
@@ -4704,16 +4917,16 @@ function emitChoice(def, ctx, pos) {
       first = false;
       stmts.push(`${ind(ctx)}${kw} (${cond}) {`);
       ctx.indent++;
-      stmts.push(...emitDisjointArmGated(def, i, ctx, pos, valV, endV));
+      stmts.push(...emitDisjointArmGated(def, i, ctx, pos, valV, endV, coverageIds?.[i]));
       ctx.indent--;
       stmts.push(`${ind(ctx)}}`);
     }
     stmts.push(...emitElseFail(ctx, failArrBody(ctx, allExpected, pos)));
     return { stmts, valueVar: valV, endVar: endV };
   }
-  return emitNonDisjoint(def, def.strategy, allExpected, ctx, pos);
+  return emitNonDisjoint(def, def.strategy, allExpected, ctx, pos, coverageBase);
 }
-function emitGreedyClassify(def, superIndex, ctx, pos) {
+function emitGreedyClassify(def, superIndex, ctx, pos, coverageBase) {
   const superParser = def.parsers[superIndex];
   const regexDef = getCoreRegexDef(superParser);
   const cleanFlags = "y" + regexDef.flags.replace(/[gy]/g, "");
@@ -4729,10 +4942,12 @@ function emitGreedyClassify(def, superIndex, ctx, pos) {
   const endV = v(ctx, "_ge");
   const valV = v(ctx, "_gcv");
   const regexExpected = JSON.stringify(deriveExpected(superParser));
+  const superCoverageId = coverageBase === void 0 ? void 0 : `${coverageBase}${superIndex}`;
   const stmts = [
+    ...coverageAttempt(ctx, superCoverageId, pos),
     `${ind(ctx)}${reVar}.lastIndex = ${pos}`,
     `${ind(ctx)}const ${matchV} = ${reVar}.exec(input)`,
-    ...emitIfFail(ctx, `${matchV} === null`, failArrBody(ctx, regexExpected, pos)),
+    ...emitIfFail(ctx, `${matchV} === null`, `${coverageFailureBacktrack(ctx, superCoverageId, pos, pos).join("; ")}; ${failArrBody(ctx, regexExpected, pos)}`),
     `${ind(ctx)}const ${wordV} = ${matchV}[0]`,
     `${ind(ctx)}const ${endV} = ${pos} + ${wordV}.length`,
     `${ind(ctx)}let ${valV}`
@@ -4748,8 +4963,9 @@ function emitGreedyClassify(def, superIndex, ctx, pos) {
     stmts.push(`${ind(ctx)}${kw} (${wordV} === ${JSON.stringify(litVal)}) {`);
     ctx.indent++;
     const tR = emitTransformChain(p, JSON.stringify(litVal), endV, pos, ctx);
+    stmts.push(...coverageFailureBacktrack(ctx, superCoverageId, pos, pos));
     stmts.push(...emitLeafCapture(ctx, JSON.stringify(litVal), pos, endV));
-    stmts.push(...tR.stmts, `${ind(ctx)}${valV} = ${tR.valueVar}`);
+    stmts.push(...tR.stmts, `${ind(ctx)}${valV} = ${tR.valueVar}`, ...coverageHit(ctx, coverageBase === void 0 ? void 0 : `${coverageBase}${i}`, pos, endV));
     ctx.indent--;
     stmts.push(`${ind(ctx)}}`);
   }
@@ -4757,12 +4973,12 @@ function emitGreedyClassify(def, superIndex, ctx, pos) {
   const regexKw = first ? "if" : "else";
   stmts.push(`${ind(ctx)}${regexKw} {`);
   ctx.indent++;
-  stmts.push(...emitLeafCapture(ctx, wordV, pos, endV), ...rR.stmts, `${ind(ctx)}${valV} = ${rR.valueVar}`);
+  stmts.push(...emitLeafCapture(ctx, wordV, pos, endV), ...rR.stmts, `${ind(ctx)}${valV} = ${rR.valueVar}`, ...coverageHit(ctx, coverageBase === void 0 ? void 0 : `${coverageBase}${superIndex}`, pos, endV));
   ctx.indent--;
   stmts.push(`${ind(ctx)}}`);
   return { stmts, valueVar: valV, endVar: endV };
 }
-function emitLiteralsLongestFirst(def, sortedIndices, allExpected, ctx, pos) {
+function emitLiteralsLongestFirst(def, sortedIndices, allExpected, ctx, pos, coverageBase) {
   const valV = v(ctx, "_llv");
   const endV = v(ctx, "_lle");
   const stmts = [`${ind(ctx)}let ${valV}, ${endV} = ${pos}`];
@@ -4779,10 +4995,12 @@ function emitLiteralsLongestFirst(def, sortedIndices, allExpected, ctx, pos) {
     ctx.indent++;
     const tR = emitTransformChain(p, JSON.stringify(litVal), litEnd, pos, ctx);
     stmts.push(
+      ...coverageAttempt(ctx, coverageBase === void 0 ? void 0 : `${coverageBase}${idx}`, pos),
       ...emitLeafCapture(ctx, JSON.stringify(litVal), pos, litEnd),
       ...tR.stmts,
       `${ind(ctx)}${valV} = ${tR.valueVar}`,
-      `${ind(ctx)}${endV} = ${litEnd}`
+      `${ind(ctx)}${endV} = ${litEnd}`,
+      ...coverageHit(ctx, coverageBase === void 0 ? void 0 : `${coverageBase}${idx}`, pos, litEnd)
     );
     ctx.indent--;
     stmts.push(`${ind(ctx)}}`);
@@ -4790,16 +5008,18 @@ function emitLiteralsLongestFirst(def, sortedIndices, allExpected, ctx, pos) {
   stmts.push(...emitElseFail(ctx, failArrBody(ctx, allExpected, pos)));
   return { stmts, valueVar: valV, endVar: endV };
 }
-function emitFirstMatch(def, ctx, pos) {
+function emitFirstMatch(def, ctx, pos, coverageBase) {
   const resValV = v(ctx, "_crv");
   const resEndV = v(ctx, "_cre");
   const resOkV = v(ctx, "_crok");
   const codeV = v(ctx, "_chcode");
   const slots = def.parsers.map(() => v(ctx, "_cfx"));
+  const autoRejectedV = coverageBase === void 0 ? void 0 : v(ctx, "_carej");
   const ind0 = ind(ctx);
   const stmts = [
     `${ind0}let ${resValV}, ${resEndV} = ${pos}, ${resOkV} = false`,
     `${ind0}let ${slots.join(", ")}`,
+    ...autoRejectedV === void 0 ? [] : [`${ind0}const ${autoRejectedV} = []`],
     `${ind0}const ${codeV} = ${pos} < input.length ? (input.codePointAt(${pos}) ?? -1) : -1`
   ];
   for (let i = 0; i < def.parsers.length; i++) {
@@ -4835,6 +5055,7 @@ function emitFirstMatch(def, ctx, pos) {
     stmts.push(`${ind0}if (${skipCond}) {`);
     if (fsGuard) stmts.push(`${ind(ctx)}if (${fsGuard}) {`);
     ctx.indent += fsGuard ? 2 : 1;
+    if (coverageBase !== void 0) stmts.push(`${ind(ctx)}_ctx._grammarTrace?.write({ id: ${JSON.stringify(`${coverageBase}${i}`)}, phase: 'attempt', offset: ${pos} })`);
     if (markLeaves) {
       stmts.push(
         `${ind(ctx)}const ${markLeaves} = _ctx._cstLeaves?.length ?? 0`,
@@ -4857,13 +5078,21 @@ function emitFirstMatch(def, ctx, pos) {
       stmts.push(`${ind(ctx)}    ${resValV} = ${valVar}`);
       stmts.push(`${ind(ctx)}    ${resEndV} = ${endVar}`);
       stmts.push(`${ind(ctx)}    ${resOkV} = true`);
+      if (autoRejectedV !== void 0) {
+        stmts.push(`${ind(ctx)}    for (const _rejectedId of ${autoRejectedV}) { _ctx._grammarTrace?.write({ id: _rejectedId, phase: 'failure', offset: ${pos} }); _ctx._grammarTrace?.write({ id: _rejectedId, phase: 'backtrack', offset: ${pos} }) }`);
+      }
+      stmts.push(...coverageHit(ctx, coverageBase === void 0 ? void 0 : `${coverageBase}${i}`, pos, endVar));
       stmts.push(`${ind(ctx)}  }`);
+      if (autoRejectedV !== void 0) {
+        stmts.push(`${ind(ctx)}  else { ${autoRejectedV}.push(${JSON.stringify(`${coverageBase}${i}`)}) }`);
+      }
       stmts.push(`${ind(ctx)}}`);
-      stmts.push(`${ind(ctx)}else { ${slots[i]} = ${failSlot} }`);
+      stmts.push(`${ind(ctx)}else { ${slots[i]} = ${failSlot}; ${coverageBase === void 0 ? "" : `_ctx._grammarTrace?.write({ id: ${JSON.stringify(`${coverageBase}${i}`)}, phase: 'failure', offset: ${atStart ? pos : "_ctx._fe"} }); _ctx._grammarTrace?.write({ id: ${JSON.stringify(`${coverageBase}${i}`)}, phase: 'backtrack', offset: ${pos} });`} }`);
       if (rollback) stmts.push(`${ind(ctx)}if (!${resOkV}) { ${rollback} }`);
     } else {
-      stmts.push(`${ind(ctx)}if (${okVar}) { ${resValV} = ${valVar}; ${resEndV} = ${endVar}; ${resOkV} = true }`);
-      stmts.push(`${ind(ctx)}else { ${slots[i]} = ${failSlot}${rollback ? `; ${rollback}` : ""} }`);
+      const rejectedFlush = autoRejectedV === void 0 ? "" : `; for (const _rejectedId of ${autoRejectedV}) { _ctx._grammarTrace?.write({ id: _rejectedId, phase: 'failure', offset: ${pos} }); _ctx._grammarTrace?.write({ id: _rejectedId, phase: 'backtrack', offset: ${pos} }) }`;
+      stmts.push(`${ind(ctx)}if (${okVar}) { ${resValV} = ${valVar}; ${resEndV} = ${endVar}; ${resOkV} = true${coverageBase === void 0 ? "" : `${rejectedFlush}; _ctx._grammarCoverage?.(${JSON.stringify(`${coverageBase}${i}`)}); _ctx._grammarTrace?.write({ id: ${JSON.stringify(`${coverageBase}${i}`)}, phase: 'selected', offset: ${pos}, end: ${endVar} }); _ctx._grammarTrace?.write({ id: ${JSON.stringify(`${coverageBase}${i}`)}, phase: 'success', offset: ${pos}, end: ${endVar} })`} }`);
+      stmts.push(`${ind(ctx)}else { ${slots[i]} = ${failSlot}${rollback ? `; ${rollback}` : ""}${coverageBase === void 0 ? "" : `; _ctx._grammarTrace?.write({ id: ${JSON.stringify(`${coverageBase}${i}`)}, phase: 'failure', offset: ${atStart ? pos : "_ctx._fe"} }); _ctx._grammarTrace?.write({ id: ${JSON.stringify(`${coverageBase}${i}`)}, phase: 'backtrack', offset: ${pos} })`} }`);
     }
     ctx.indent -= fsGuard ? 2 : 1;
     if (fsGuard) stmts.push(`${ind(ctx)}} else { ${slots[i]} = ${staticFx} }`);
@@ -4873,12 +5102,12 @@ function emitFirstMatch(def, ctx, pos) {
   stmts.push(...emitIfFail(ctx, `!${resOkV}`, failArrBody(ctx, concatExpr, pos, false)));
   return { stmts, valueVar: resValV, endVar: resEndV };
 }
-function emitNonDisjoint(def, strategy, allExpected, ctx, pos) {
+function emitNonDisjoint(def, strategy, allExpected, ctx, pos, coverageBase) {
   if (strategy.tag === "greedyClassify")
-    return emitGreedyClassify(def, strategy.superIndex, ctx, pos);
+    return emitGreedyClassify(def, strategy.superIndex, ctx, pos, coverageBase);
   if (strategy.tag === "literalsLongestFirst")
-    return emitLiteralsLongestFirst(def, strategy.sortedIndices, allExpected, ctx, pos);
-  return emitFirstMatch(def, ctx, pos);
+    return emitLiteralsLongestFirst(def, strategy.sortedIndices, allExpected, ctx, pos, coverageBase);
+  return emitFirstMatch(def, ctx, pos, coverageBase);
 }
 function pushMapFn(ctx, fn, src) {
   if (src !== null && ctx.mapFns.length === ctx.mapFnSrcs.length) {
@@ -4996,6 +5225,27 @@ function emitOptional(def, ctx, pos) {
   ];
   return { stmts, valueVar: valV, endVar: endV };
 }
+function emitAttempt(p, def, ctx, pos) {
+  const inner = emitFallible(def.parser, ctx, pos);
+  const leaves = v(ctx, "_atl");
+  const raw = v(ctx, "_atr");
+  const trivia2 = v(ctx, "_att");
+  const log = v(ctx, "_atg");
+  const fields = v(ctx, "_atf");
+  const errors = v(ctx, "_ate");
+  const rollback = `if (_ctx._cstLeaves) _ctx._cstLeaves.length = ${leaves}; if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${raw}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${trivia2}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${log}; if (_ctx._fields) _ctx._fields.length = ${fields}; if (_ctx._errors) _ctx._errors.length = ${errors}`;
+  const traceId = ctx.coverage?.plan.attempts.get(p);
+  const traceRollback = traceId === void 0 ? "" : ` _ctx._grammarTrace?.write({ id: ${JSON.stringify(traceId)}, phase: 'rollback', offset: ${pos} });`;
+  return {
+    stmts: [
+      `${ind(ctx)}const ${leaves} = _ctx._cstLeaves?.length ?? 0, ${raw} = _ctx._cstRawChildren?.length ?? 0, ${trivia2} = _ctx._cstTriviaLog?.length ?? 0, ${log} = _ctx._triviaLog?.length ?? 0, ${fields} = _ctx._fields?.length ?? 0, ${errors} = _ctx._errors?.length ?? 0`,
+      ...inner.stmts,
+      ...emitIfFail(ctx, `!${inner.okVar}`, `{ ${rollback};${traceRollback} _ctx._fe = ${pos}; ${propagateFailBody(ctx)} }`)
+    ],
+    valueVar: inner.valVar,
+    endVar: inner.endVar
+  };
+}
 function emitSepBy(_p, def, ctx, pos) {
   const arrV = v(ctx, "_arr");
   const curV = v(ctx, "_cur");
@@ -5286,6 +5536,36 @@ function emitToken(def, ctx, pos) {
     endVar: inner.endVar
   };
 }
+function emitLeaf(def, ctx, pos) {
+  const inner = emitFallible(def.parser, ctx, pos);
+  const i = ind(ctx);
+  const sc = v(ctx, "_leafCh");
+  const sl = v(ctx, "_leafLv");
+  const sr = v(ctx, "_leafRaw");
+  const stl = v(ctx, "_leafTl");
+  const sol = v(ctx, "_leafLog");
+  const sb = v(ctx, "_leafBuf");
+  const rawV = v(ctx, "_leafRawValue");
+  const valV = v(ctx, "_leaf");
+  const fnIdx = pushMapFn(ctx, def.fn, def.fnSrc ?? null);
+  return {
+    stmts: [
+      `${i}const ${sc} = _ctx._cstChildren, ${sl} = _ctx._cstLeaves, ${sr} = _ctx._cstRawChildren, ${stl} = _ctx._cstTriviaLog, ${sol} = _ctx._triviaLog, ${sb} = _ctx._cstBuf`,
+      `${i}_ctx._cstChildren = undefined; _ctx._cstLeaves = undefined; _ctx._cstRawChildren = undefined; _ctx._cstTriviaLog = undefined; _ctx._triviaLog = undefined; _ctx._cstBuf = undefined`,
+      `${i}try {`,
+      ...reindentStmts(inner.stmts, ctx.indent + 1).map((stmt) => stmt.replace(/^(\s*)(?:const|let)\s+/, "$1var ")),
+      `${i}} finally {`,
+      `${i}  _ctx._cstChildren = ${sc}; _ctx._cstLeaves = ${sl}; _ctx._cstRawChildren = ${sr}; _ctx._cstTriviaLog = ${stl}; _ctx._triviaLog = ${sol}; _ctx._cstBuf = ${sb}`,
+      `${i}}`,
+      ...emitIfFail(ctx, `!${inner.okVar}`, propagateFailBody(ctx)),
+      `${i}const ${rawV} = ${inner.valVar}`,
+      `${i}const ${valV} = ${mfRef(ctx)}[${fnIdx}](${rawV}, { start: ${pos}, end: ${inner.endVar} })`,
+      ...emitLeafCapture(ctx, valV, pos, inner.endVar)
+    ],
+    valueVar: valV,
+    endVar: inner.endVar
+  };
+}
 function emitNode(def, ctx, pos) {
   if (def.type === void 0) {
     throw new Error('node(): inferred node type requires a rules() key; pass node("Type", parser) outside rules()');
@@ -5301,6 +5581,8 @@ function emitNode(def, ctx, pos) {
   const i = ind(ctx);
   const capturesTrivia = mkType !== null || def.captureTrivia === true || def.trailingTrivia === true || !structural && buildReadsTrivia(def);
   const clonesState = !structural && buildReadsState(def);
+  const capturesChildren = !structural && (mkType !== null || def.unwrap || def.collapse || buildReadsChildren(def));
+  const capturesRaw = !structural && (mkType !== null || buildReadsRaw(def));
   const hasFields = parserHasOwnFields(def.parser);
   const capturesFields = hasFields && !structural && buildReadsFields(def);
   const innerEnablesTriviaCapture = parserEnablesTriviaCapture(def.parser);
@@ -5319,9 +5601,13 @@ function emitNode(def, ctx, pos) {
   const profHoist = `${i}const ${pmV} = _ctx._pmProfile, ${recV} = ${pmV}?.phase === 'recognizer', ${capV} = ${pmV}?.phase === 'capture'`;
   const profileRecognizer = recV;
   const profileCapture = capV;
+  const directCstV = !structural && (!capturesChildren || !capturesRaw) ? v(ctx, "_dcst") : null;
+  const directCstGate = directCstV === null ? "false" : `${profileCapture} || _ctx.build?._parsemanCstOutput === true`;
   const structuralCapturesTrivia = structural && (def.captureTrivia === true || def.trailingTrivia === true);
   const allocStmt = structural ? `${i}const ${capTLv} = !(${profileRecognizer}) && (${profileCapture} || ${structuralCapturesTrivia ? "true" : hostTriviaGate}), ${capSTv} = !(${profileRecognizer} || ${profileCapture}) && (_ctx._pmCapST ??= (_ctx.build === undefined || _hostReads(_ctx.build, 6)))${capFv ? `, ${capFv} = !(${profileRecognizer}) && (${profileCapture} || (_ctx.build !== undefined && _hostReads(_ctx.build, 2)))` : ""}
-${i}const ${chV} = ${profileRecognizer} ? undefined : [], ${rawV} = ${profileRecognizer} ? undefined : [], ${tlV} = ${profileRecognizer} ? undefined : ${innerEnablesTriviaCapture ? "[]" : `${capTLv} ? [] : _EMPTY_TL`}` : capturesTrivia ? `${i}const ${capTLv} = !(${profileRecognizer}), ${chV} = ${profileRecognizer} ? undefined : [], ${rawV} = ${profileRecognizer} ? undefined : [], ${tlV} = ${profileRecognizer} ? undefined : []` : `${i}const ${chV} = ${profileRecognizer} ? undefined : [], ${rawV} = ${profileRecognizer} ? undefined : []`;
+${i}const ${chV} = ${profileRecognizer} ? undefined : [], ${rawV} = ${profileRecognizer} ? undefined : [], ${tlV} = ${profileRecognizer} ? undefined : ${innerEnablesTriviaCapture ? "[]" : `${capTLv} ? [] : _EMPTY_TL`}` : capturesTrivia ? `${directCstV ? `${i}const ${directCstV} = ${directCstGate}
+` : ""}${i}const ${capTLv} = !(${profileRecognizer}), ${chV} = ${profileRecognizer} ? undefined : ${capturesChildren ? "[]" : `${directCstV} ? [] : undefined`}, ${rawV} = ${profileRecognizer} ? undefined : ${capturesRaw ? "[]" : `${directCstV} ? [] : undefined`}, ${tlV} = ${profileRecognizer} ? undefined : []` : `${directCstV ? `${i}const ${directCstV} = ${directCstGate}
+` : ""}${i}const ${chV} = ${profileRecognizer} ? undefined : ${capturesChildren ? "[]" : `${directCstV} ? [] : undefined`}, ${rawV} = ${profileRecognizer} ? undefined : ${capturesRaw ? "[]" : `${directCstV} ? [] : undefined`}`;
   const innerTl = structural || capturesTrivia ? structural && !innerEnablesTriviaCapture ? `${capTLv} ? ${tlV} : undefined` : tlV : "undefined";
   const fieldsOn = structural ? capFv ?? "false" : `${profileRecognizer} ? false : ${capturesFields ? "true" : "false"}`;
   const sf = hasFields ? v(ctx, "_sf") : null;
@@ -5438,14 +5724,23 @@ function emitLazy(p, def, ctx, pos) {
     const savedIndent = ctx.indent;
     const savedFailLabel = ctx.failLabel;
     const savedRecord = ctx.recordFail;
+    const failureRuleId = p === ctx.coverage?.entry ? void 0 : ctx.coverage?.plan.rules.get(p) ?? ctx.coverage?.plan.rules.get(resolved);
+    const savedActiveRule = ctx.activeCoverageRuleId;
+    const savedSuppressFailure = ctx.suppressCoverageFailure;
     ctx.indent = 1;
     ctx.failLabel = "_pfail";
     ctx.recordFail = true;
+    if (failureRuleId !== void 0) {
+      ctx.activeCoverageRuleId = void 0;
+      ctx.suppressCoverageFailure = true;
+    }
     const r = emit(resolved, ctx, "_pos");
     ctx.indent = savedIndent;
     ctx.failLabel = savedFailLabel;
     ctx.recordFail = savedRecord;
-    pushNamedFnDecl(ctx, fnName2, r.stmts, r.valueVar, r.endVar);
+    ctx.activeCoverageRuleId = savedActiveRule;
+    ctx.suppressCoverageFailure = savedSuppressFailure;
+    pushNamedFnDecl(ctx, fnName2, r.stmts, r.valueVar, r.endVar, failureRuleId);
   }
   const fnName = ctx.namedParsers.get(p);
   return emitNamedFnCall(ctx, fnName, pos);
@@ -5496,6 +5791,30 @@ function emitExpect(def, ctx, pos) {
   return { stmts, valueVar: valVar, endVar };
 }
 function emit(p, ctx, pos) {
+  const dispatch = (emissionPos = pos) => {
+    const savedRule = ctx.activeCoverageRuleId;
+    const rule = ctx.coverage?.plan.rules.get(p);
+    if (rule && p !== ctx.coverage?.entry && !ctx.suppressCoverageFailure) ctx.activeCoverageRuleId = rule;
+    const result = emitDispatch(p, ctx, emissionPos);
+    ctx.activeCoverageRuleId = savedRule;
+    return result;
+  };
+  const instrument = (r) => {
+    const ruleId = ctx.coverage?.plan.rules.get(p);
+    const labelIds = ctx.coverage?.plan.labels.get(p);
+    if (!ruleId && !labelIds) return r;
+    return {
+      ...r,
+      stmts: [
+        ...ruleId ? [`${ind(ctx)}_ctx._grammarCoverage?.(${JSON.stringify(ruleId)})`] : [],
+        ...ruleId ? [`${ind(ctx)}_ctx._grammarTrace?.write({ id: ${JSON.stringify(ruleId)}, phase: 'enter', offset: ${pos} })`] : [],
+        ...r.stmts,
+        ...ruleId ? [`${ind(ctx)}_ctx._grammarTrace?.write({ id: ${JSON.stringify(ruleId)}, phase: 'success', offset: ${pos}, end: ${r.endVar} })`] : [],
+        ...labelIds?.flatMap((id) => [`${ind(ctx)}_ctx._grammarCoverage?.(${JSON.stringify(id)})`]) ?? [],
+        ...labelIds?.flatMap((id) => [`${ind(ctx)}_ctx._grammarTrace?.write({ id: ${JSON.stringify(id)}, phase: 'success', offset: ${pos}, end: ${r.endVar} })`]) ?? []
+      ]
+    };
+  };
   const usage = ctx.lazyUsage;
   if (usage && !ctx.noHoist && !ctx.capAsTrivia && !ctx.ruleNames?.has(p) && isHoistableTag(p._def.tag) && (usage.counts.get(p) ?? 0) > 1 && // Only hoist subtrees big enough that de-duplicating them beats the call
   // overhead. A tiny shared wrapper (e.g. `optional(literal(';'))`) inlines
@@ -5512,14 +5831,14 @@ function emit(p, ctx, pos) {
     ctx.indent = 1;
     ctx.failLabel = "_pfail";
     ctx.recordFail = true;
-    const r = emitDispatch(p, ctx, "_pos");
+    const r = dispatch("_pos");
     ctx.indent = savedIndent;
     ctx.failLabel = savedFailLabel;
     ctx.recordFail = savedRecord;
     pushNamedFnDecl(ctx, fnName, r.stmts, r.valueVar, r.endVar);
-    return emitNamedFnCall(ctx, fnName, pos);
+    return instrument(emitNamedFnCall(ctx, fnName, pos));
   }
-  return emitDispatch(p, ctx, pos);
+  return instrument(dispatch());
 }
 function emitDispatch(p, ctx, pos) {
   const def = p._def;
@@ -5533,7 +5852,9 @@ function emitDispatch(p, ctx, pos) {
     case "sequence":
       return emitSeq(def, ctx, pos);
     case "choice":
-      return emitChoice(def, ctx, pos);
+      return emitChoice(p, def, ctx, pos);
+    case "attempt":
+      return emitAttempt(p, def, ctx, pos);
     case "many":
     case "oneOrMore":
       return emitMany(def, ctx, pos);
@@ -5602,6 +5923,8 @@ function emitDispatch(p, ctx, pos) {
       return emit(def.parser, ctx, pos);
     case "token":
       return emitToken(def, ctx, pos);
+    case "leaf":
+      return emitLeaf(def, ctx, pos);
     case "label": {
       const inner = emitFallible(def.parser, ctx, pos);
       return {
@@ -5733,6 +6056,7 @@ function hasNodeDef(p, seen = /* @__PURE__ */ new Set()) {
     case "grammar":
     case "trivia":
     case "token":
+    case "leaf":
     case "label":
     case "field":
     case "optional":
@@ -5760,16 +6084,32 @@ function hasNodeDef(p, seen = /* @__PURE__ */ new Set()) {
       return false;
   }
 }
+function hasDirectBuildDef(p, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(p)) return false;
+  seen.add(p);
+  const d = p._def;
+  if (d.tag === "node" && d.build !== void 0) return true;
+  if (d.tag === "lazy") {
+    try {
+      return hasDirectBuildDef(d.thunk(), seen);
+    } catch {
+      return false;
+    }
+  }
+  return childrenOf(d).some((child) => hasDirectBuildDef(child, seen));
+}
 function childrenOf(def) {
   switch (def.tag) {
     case "sequence":
     case "choice":
       return def.parsers;
     case "many":
+    case "attempt":
     case "optional":
     case "transform":
     case "trivia":
     case "token":
+    case "leaf":
     case "label":
     case "field":
     case "grammar":
@@ -5944,10 +6284,25 @@ function compile(combinator, mapFnSources, opts) {
     namedFnDecls: [],
     capturing: hasNodeDef(combinator),
     recovery: opts?.recovery ?? false,
+    ...opts?.coverage ? { coverage: { plan: buildGrammarPlan(combinator), entry: combinator } } : {},
     lazyUsage: analyzeLazyUsage(combinator),
     ...grammarTrivia ? { activeTrivia: grammarTrivia, triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {}
   };
   const r = emit(combinator, ctx, "_pos");
+  const coverageRootRuleId = ctx.coverage?.plan.rules.get(combinator);
+  const resultBody = coverageRootRuleId === void 0 ? [
+    `  let pos = _pos`,
+    ...r.stmts,
+    `  return { ok: true, value: ${r.valueVar}, span: { start: _pos, end: ${r.endVar} } }`
+  ] : [
+    `  const _coverageResult = (() => {`,
+    `    let pos = _pos`,
+    ...r.stmts,
+    `    return { ok: true, value: ${r.valueVar}, span: { start: _pos, end: ${r.endVar} } }`,
+    `  })()`,
+    `  if (!_coverageResult.ok) _ctx._grammarTrace?.write({ id: ${JSON.stringify(coverageRootRuleId)}, phase: 'failure', offset: _coverageResult.span.start })`,
+    `  return _coverageResult`
+  ];
   const namedPrelude = ctx.namedFnDecls.length > 0 ? [...namedFnPrelude(), ""] : [];
   const emptyTlDecls = ctx.needsEmptyTl ? ["const _EMPTY_TL = Object.freeze([])"] : [];
   const hostReadsDecls = ctx.needsHostReads ? [HOST_READS_DECL] : [];
@@ -5960,9 +6315,7 @@ function compile(combinator, mapFnSources, opts) {
     ...namedPrelude,
     ctx.namedFnDecls.join("\n\n"),
     `function _parse(input, _pos, _rp, _mf, _build, _ctx) {`,
-    `  let pos = _pos`,
-    ...r.stmts,
-    `  return { ok: true, value: ${r.valueVar}, span: { start: _pos, end: ${r.endVar} } }`,
+    ...resultBody,
     `}`
   ].join("\n");
   const fn = new Function("input", "_pos", "_rp", "_mf", "_build", "_ctx", [
@@ -5972,9 +6325,15 @@ function compile(combinator, mapFnSources, opts) {
     ...ctx.expectedDecls,
     ...namedPrelude,
     ...ctx.namedFnDecls.flatMap((decl, i) => i > 0 ? ["", decl] : [decl]),
-    `let pos = _pos`,
-    ...r.stmts,
-    `return { ok: true, value: ${r.valueVar}, span: { start: _pos, end: ${r.endVar} } }`
+    ...coverageRootRuleId === void 0 ? [`let pos = _pos`, ...r.stmts, `return { ok: true, value: ${r.valueVar}, span: { start: _pos, end: ${r.endVar} } }`] : [
+      `const _coverageResult = (() => {`,
+      `  let pos = _pos`,
+      ...r.stmts,
+      `  return { ok: true, value: ${r.valueVar}, span: { start: _pos, end: ${r.endVar} } }`,
+      `})()`,
+      `if (!_coverageResult.ok) _ctx._grammarTrace?.write({ id: ${JSON.stringify(coverageRootRuleId)}, phase: 'failure', offset: _coverageResult.span.start })`,
+      `return _coverageResult`
+    ]
   ].join("\n"));
   const defaultCtx = {
     trackLines: false,
@@ -5986,10 +6345,11 @@ function compile(combinator, mapFnSources, opts) {
   const buildSources = ctx.buildFns.length === 0 ? void 0 : ctx.buildSrcs;
   const mfCovered = ctx.mapFns.length === 0 || effectiveSources !== void 0 && effectiveSources.length === ctx.mapFns.length;
   const canInline = ctx.runtimeParsers.length === 0 && mfCovered && buildCovered;
-  const inlineExpression = canInline ? buildInlineExpression(ctx, r, effectiveSources, buildSources) : null;
+  const inlineExpression = canInline ? buildInlineExpression(ctx, r, effectiveSources, buildSources, coverageRootRuleId) : null;
   return {
     source,
     inlineExpression,
+    ...ctx.coverage === void 0 ? {} : { coverageDefinitions: ctx.coverage.plan.definitions },
     parse(input, pos = 0) {
       return fn(input, pos, ctx.runtimeParsers, ctx.mapFns, ctx.buildFns, defaultCtx);
     },
@@ -6052,8 +6412,13 @@ function compileLinkable(ruleMapArg, ns, opts) {
     triviaCaptureNames: /* @__PURE__ */ new Map(),
     triviaFnNames: /* @__PURE__ */ new Map(),
     namedFnDecls: [],
-    capturing: ruleMap.some(([, rule]) => hasNodeDef(rule)),
+    // A recognition-only fragment normally has no node collector of its own.
+    // Leaf composition can re-lower it beneath a local semantic node, though;
+    // in that case its terminals must feed the caller's collector rather than
+    // merely returning their scalar parse values.
+    capturing: opts?.captureTerminals === true || ruleMap.some(([, rule]) => hasNodeDef(rule)),
     recovery: opts?.recovery ?? false,
+    ...opts?.coverage ? { coverage: { plan: opts.coverage } } : {},
     lazyUsage: analyzeLazyUsageMulti(ruleMap.map(([, rule]) => rule)),
     ns,
     deferFirstSetRefs: true,
@@ -6127,7 +6492,14 @@ function compileLinkable(ruleMapArg, ns, opts) {
       ctx.indent = savedIndent;
       ctx.failLabel = savedFail;
       ctx.recordFail = savedRec;
-      pushNamedFnDecl(ctx, fn, body.stmts, body.valueVar, body.endVar);
+      const ruleId = ctx.coverage?.plan.rules.get(rule);
+      const stmts = ruleId === void 0 ? body.stmts : [
+        `${ind(ctx)}_ctx._grammarCoverage?.(${JSON.stringify(ruleId)})`,
+        `${ind(ctx)}_ctx._grammarTrace?.write({ id: ${JSON.stringify(ruleId)}, phase: 'enter', offset: _pos })`,
+        ...body.stmts,
+        `${ind(ctx)}_ctx._grammarTrace?.write({ id: ${JSON.stringify(ruleId)}, phase: 'success', offset: _pos, end: ${body.endVar} })`
+      ];
+      pushNamedFnDecl(ctx, fn, stmts, body.valueVar, body.endVar);
     }
     perEntry.push({ key, rule, r: emitNamedFnCall(ctx, fn, "_pos") });
   }
@@ -6184,15 +6556,46 @@ function compileLinkable(ruleMapArg, ns, opts) {
     deps: ruleDependencies(ruleMap),
     needsEmptyTl: !!ctx.needsEmptyTl,
     needsHostReads: !!ctx.needsHostReads,
+    hasDirectBuilders: ruleMap.some(([, rule]) => hasDirectBuildDef(rule)),
+    isRecognitionOnly: !hasSemanticReduction(ruleMap.map(([, rule]) => rule)),
     mfFns: mfSrcs ? [] : ctx.mapFns,
     buildFns: buildSrcs ? [] : ctx.buildFns
   };
 }
-function buildInlineExpression(ctx, r, mapFnSources, buildSources) {
-  const bodyLines = [
+function hasSemanticReduction(roots) {
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (parser2) => {
+    if (seen.has(parser2)) return false;
+    seen.add(parser2);
+    const def = parser2._def;
+    if (def.tag === "transform" && !def.recognitionOnly) return true;
+    if (def.tag === "choice" && def.gates.some(Boolean)) return true;
+    if (def.tag === "guard" || def.tag === "withCtx") return true;
+    if (def.tag === "node" && def.build !== void 0) return true;
+    if (def.tag === "lazy") {
+      try {
+        return visit(def.thunk());
+      } catch {
+        return true;
+      }
+    }
+    return childrenOf(def).some(visit);
+  };
+  return roots.some(visit);
+}
+function buildInlineExpression(ctx, r, mapFnSources, buildSources, coverageRootRuleId) {
+  const bodyLines = coverageRootRuleId === void 0 ? [
     `  let pos = _pos`,
     ...r.stmts,
     `  return { ok: true, value: ${r.valueVar}, span: { start: _pos, end: ${r.endVar} } }`
+  ] : [
+    `  const _coverageResult = (() => {`,
+    `    let pos = _pos`,
+    ...r.stmts,
+    `    return { ok: true, value: ${r.valueVar}, span: { start: _pos, end: ${r.endVar} } }`,
+    `  })()`,
+    `  if (!_coverageResult.ok) _ctx._grammarTrace?.write({ id: ${JSON.stringify(coverageRootRuleId)}, phase: 'failure', offset: _coverageResult.span.start })`,
+    `  return _coverageResult`
   ];
   const innerFn = [
     `function(input, _pos, _ctx) {`,
@@ -6247,8 +6650,8 @@ function scanTo(sentinel, { skip: skip2 = [], orEOF = false } = {}) {
       };
       const emit2 = (end) => {
         if (end > pos && cstCaptureActive(ctx)) {
-          const leaf = { _tag: "leaf", value: input.slice(pos, end), span: { start: pos, end } };
-          pushCstLeaf(ctx, leaf);
+          const leaf2 = { _tag: "leaf", value: input.slice(pos, end), span: { start: pos, end } };
+          pushCstLeaf(ctx, leaf2);
         }
       };
       while (cur < input.length) {
@@ -6302,6 +6705,7 @@ function balanced(open, close, options = {}) {
   );
   if (combi._def.tag === "transform") {
     combi._def.fnSrc = '([o, parts, c]) => o + parts.map(p => typeof p === "string" ? p : Array.isArray(p) ? p.join("") : "").join("") + (typeof c === "string" ? c : "")';
+    combi._def.recognitionOnly = true;
   }
   self.define(combi);
   return combi;
@@ -6347,9 +6751,11 @@ function childrenOf2(def) {
     case "many":
     case "oneOrMore":
     case "optional":
+    case "attempt":
     case "transform":
     case "trivia":
     case "token":
+    case "leaf":
     case "label":
     case "field":
     case "not":
@@ -6398,7 +6804,7 @@ function serializeRuleMap(ruleMap) {
   }
 }
 function evalRuleMapIR(ir) {
-  const _tf = (child, src) => {
+  const _tf = (child, src, recognitionOnly = false) => {
     let fn2;
     try {
       fn2 = (0, eval)(`(${src})`);
@@ -6409,8 +6815,22 @@ function evalRuleMapIR(ir) {
     }
     const t = transform(child, fn2);
     t._def.fnSrc = src;
+    if (recognitionOnly) t._def.recognitionOnly = true;
     return t;
   };
+  const _lf = (child, src) => {
+    let fn2;
+    try {
+      fn2 = (0, eval)(`(${src})`);
+    } catch {
+      fn2 = () => {
+        throw new Error("IR leaf fn not materialized");
+      };
+    }
+    const l = leaf(child, fn2);
+    l._def.fnSrc = src;
+    return l;
+  };
   const _nd = (type, child, src, opts, staticError) => {
     if (staticError !== void 0 && staticError.length > 0) {
       throw new Error(`IR direct node builder for ${type} must be macro-static and self-contained; unsupported binding(s): ${staticError.join(", ")}`);
@@ -6469,6 +6889,7 @@ function evalRuleMapIR(ir) {
     "keywords",
     "sequence",
     "choice",
+    "attempt",
     "many",
     "oneOrMore",
     "optional",
@@ -6478,6 +6899,7 @@ function evalRuleMapIR(ir) {
     "parser",
     "scanTo",
     "token",
+    "leaf",
     "transform",
     "skip",
     "trivia",
@@ -6485,6 +6907,7 @@ function evalRuleMapIR(ir) {
     "field",
     "expect",
     "_tf",
+    "_lf",
     "_nd",
     "_gch",
     "_wc",
@@ -6498,6 +6921,7 @@ function evalRuleMapIR(ir) {
     keywords,
     sequence,
     choice,
+    attempt,
     many,
     oneOrMore,
     optional,
@@ -6507,6 +6931,7 @@ function evalRuleMapIR(ir) {
     parser,
     scanTo,
     token,
+    leaf,
     transform,
     skip,
     trivia,
@@ -6514,6 +6939,7 @@ function evalRuleMapIR(ir) {
     field,
     expect,
     _tf,
+    _lf,
     _nd,
     _gch,
     _wc
@@ -6645,6 +7071,8 @@ ${body}
         return `oneOrMore(${kid(def.parser)})`;
       case "optional":
         return `optional(${kid(def.parser)})`;
+      case "attempt":
+        return `attempt(${kid(def.parser)})`;
       case "sepBy":
         return `sepBy(${kid(def.parser)}, ${kid(def.separator)})`;
       case "not":
@@ -6653,6 +7081,10 @@ ${body}
         return `trivia(${kid(def.parser)})`;
       case "token":
         return `token(${kid(def.parser)})`;
+      case "leaf": {
+        if (def.fnSrc === void 0) throw new Unserializable("leaf without fnSrc");
+        return `_lf(${kid(def.parser)}, ${JSON.stringify(def.fnSrc)})`;
+      }
       case "label":
         return `label(${JSON.stringify(def.label)}, ${kid(def.parser)})`;
       case "field":
@@ -6665,7 +7097,7 @@ ${body}
         return `scanTo(${kid(def.sentinel)}, { skip: [${def.skip.map(kid).join(", ")}], orEOF: ${def.orEOF} })`;
       case "transform": {
         if (def.fnSrc === void 0) throw new Unserializable("transform without fnSrc");
-        return `_tf(${kid(def.parser)}, ${JSON.stringify(def.fnSrc)})`;
+        return `_tf(${kid(def.parser)}, ${JSON.stringify(def.fnSrc)}${def.recognitionOnly ? ", true" : ""})`;
       }
       case "node": {
         if (def.build !== void 0 && def.buildSrc === void 0) throw new Unserializable("node build without buildSrc");
@@ -6717,15 +7149,15 @@ function normalizeCstCollapse(collapse) {
   }
   return typeof collapse === "function" ? collapse : void 0;
 }
-function buildCstNode(type, children, _fields, span, _rawChildren, _triviaLog, state) {
-  return { _tag: "node", type, span: { start: span.start, end: span.end }, state: state ?? null, children: [...children] };
+function buildCstNode(type, children2, _fields, span, _rawChildren, _triviaLog, state) {
+  return { _tag: "node", type, span: { start: span.start, end: span.end }, state: state ?? null, children: [...children2] };
 }
-function cstBuildHost(typeOrOptions, children, _fields, span, rawChildren, triviaLog, state) {
+function cstBuildHost(typeOrOptions, children2, _fields, span, rawChildren, triviaLog, state) {
   if (typeof typeOrOptions === "string") {
-    return buildCstNode(typeOrOptions, children ?? [], _fields, span ?? { start: 0, end: 0 }, rawChildren, triviaLog, state);
+    return buildCstNode(typeOrOptions, children2 ?? [], _fields, span ?? { start: 0, end: 0 }, rawChildren, triviaLog, state);
   }
   const collapse = normalizeCstCollapse(typeOrOptions?.collapse);
-  const host = (type, children2, fields, span2, rawChildren2, triviaLog2, state2) => buildCstNode(type, children2, fields, span2, rawChildren2, triviaLog2, state2);
+  const host = (type, children3, fields, span2, rawChildren2, triviaLog2, state2) => buildCstNode(type, children3, fields, span2, rawChildren2, triviaLog2, state2);
   host._parsemanCstOutput = true;
   if (collapse) host._parsemanCstCollapse = collapse;
   return host;
@@ -6784,13 +7216,39 @@ function fuseRules(pieces) {
   return new Function("_env", body)(env);
 }
 var COMPOSED_PIECES = /* @__PURE__ */ Symbol.for("parseman.composedPieces");
+var LEAF_COMPOSED = /* @__PURE__ */ Symbol.for("parseman.leafComposed");
 var COMPOSED_TRIVIA = /* @__PURE__ */ Symbol.for("parseman.composedTrivia");
+var COMPOSED_COVERAGE_RULES = /* @__PURE__ */ Symbol.for("parseman.composedCoverageRules");
 function isIRPiece(p) {
   return !!p && typeof p === "object" && typeof p.ir === "string" && typeof p.ns === "string" && !("ruleFns" in p);
 }
-function materializePiece(p, trivia2) {
+function coverageRulesOf(carried) {
+  const winners = {};
+  for (const piece of carried) {
+    if (!isIRPiece(piece)) return void 0;
+    const map = evalRuleMapIR(piece.ir);
+    for (const [name, rule] of map) {
+      if (rule._def.tag === "lazy") {
+        try {
+          rule._def.thunk();
+        } catch {
+          continue;
+        }
+      }
+      winners[name] = rule;
+    }
+  }
+  return winners;
+}
+function composedCoverageRules(grammar) {
+  return grammar[COMPOSED_COVERAGE_RULES];
+}
+function materializePiece(p, trivia2, captureTerminals = false) {
   if (!isIRPiece(p)) return p;
-  const pieces = compileLinkable(evalRuleMapIR(p.ir), p.ns, trivia2 ? { trivia: trivia2 } : void 0);
+  const pieces = compileLinkable(evalRuleMapIR(p.ir), p.ns, {
+    ...trivia2 ? { trivia: trivia2 } : {},
+    ...captureTerminals ? { captureTerminals: true } : {}
+  });
   if (!pieces) throw new Error(`compose: carried IR for ns "${p.ns}" could not be re-lowered`);
   return pieces;
 }
@@ -6841,6 +7299,9 @@ function composingTriviaOf(items) {
   return void 0;
 }
 function compose(items) {
+  if (items.some((item) => item[LEAF_COMPOSED] === true)) {
+    throw new Error("compose: a composeLeaf() result is terminal and cannot be composed again");
+  }
   const used = /* @__PURE__ */ new Set();
   const trivia2 = composingTriviaOf(items);
   const carried = items.flatMap((item) => itemCarried(item, used, trivia2));
@@ -6848,8 +7309,13 @@ function compose(items) {
   const map = fuseRules(pieces);
   Object.defineProperty(map, COMPOSED_PIECES, { value: carried, enumerable: false });
   if (trivia2) Object.defineProperty(map, COMPOSED_TRIVIA, { value: trivia2, enumerable: false });
+  const coverageRules = coverageRulesOf(carried);
+  if (coverageRules) Object.defineProperty(map, COMPOSED_COVERAGE_RULES, { value: coverageRules, enumerable: false });
   return map;
 }
+function composeLeaf(_items) {
+  throw new Error("composeLeaf(): requires Parseman macro lowering; runtime composition is forbidden");
+}
 
 // src/combinators/guard.ts
 function guard(predicate) {
@@ -7013,7 +7479,9 @@ function producesRepetition(def, depth = 0) {
     // Transparent wrappers — look through to the inner parser.
     case "node":
     case "transform":
+    case "attempt":
     case "token":
+    case "leaf":
     case "label":
     case "field":
     case "expect":
@@ -7065,8 +7533,8 @@ function replaceAtPath(rebuild, root, path, newNode) {
   newChildren[idx] = rest.length === 0 ? newNode : replaceAtPath(rebuild, root.children[idx], rest, newNode);
   return rebuild(root, newChildren);
 }
-function defaultRebuild(node2, children) {
-  return { ...node2, children };
+function defaultRebuild(node2, children2) {
+  return { ...node2, children: children2 };
 }
 function shiftRelStart(child, delta) {
   const c = child;
@@ -7406,7 +7874,8 @@ function runOnce(entry, input, options, phase, profileState) {
     state: options.state,
     ...grammarTrivia !== void 0 ? { trivia: grammarTrivia, ...grammarTrivia._meta.triviaKindLabels ? { triviaKindLabels: grammarTrivia._meta.triviaKindLabels } : {} } : {},
     ...options.triviaCaptureMask !== void 0 ? { _triviaCaptureMask: options.triviaCaptureMask } : {},
-    ...options.tolerant ? { _tolerant: true, _rec: REC } : {}
+    ...options.tolerant ? { _tolerant: true, _rec: REC } : {},
+    ...options.instrumentation === void 0 ? {} : options.instrumentation
   };
   const r = invoke(entry, input, 0, ctx);
   let unconsumedFrom = null;
@@ -7461,6 +7930,265 @@ function run(entry, input, options = {}) {
   };
 }
 
+// src/coverage.ts
+var GRAMMAR_COVERAGE_DEFINITIONS = /* @__PURE__ */ Symbol.for("parseman.grammarCoverageDefinitions");
+function compiledGrammarCoverageDefinitions(grammar) {
+  const definitions = grammar[GRAMMAR_COVERAGE_DEFINITIONS];
+  if (!Array.isArray(definitions) || !definitions.every((definition) => typeof definition === "object" && definition !== null && typeof definition.id === "string" && (definition.kind === "rule" || definition.kind === "choice-arm" || definition.kind === "label"))) {
+    throw new TypeError("grammar has no coverage definitions; enable grammarCoverage for this macro build");
+  }
+  return definitions;
+}
+function createGrammarInstrumentationContext(options = {}) {
+  return {
+    trackLines: options.trackLines ?? false,
+    ...options.state === void 0 ? {} : { state: options.state },
+    ...options.collector === void 0 ? {} : { _grammarCoverage: (id) => options.collector.hit(id) },
+    ...options.trace === void 0 ? {} : { _grammarTrace: options.trace }
+  };
+}
+function createGrammarTraceSink(options) {
+  if (!Number.isInteger(options.capacity) || options.capacity < 0) throw new TypeError("trace capacity must be a finite non-negative integer");
+  const events = [];
+  let detached = false;
+  let truncated = false;
+  let dropped = 0;
+  return {
+    write(event) {
+      if (detached || events.length >= options.capacity) {
+        detached = true;
+        truncated = true;
+        dropped++;
+        return;
+      }
+      events.push(Object.freeze({ ...event }));
+      try {
+        if (options.write?.(event) === false) {
+          detached = true;
+          truncated = true;
+        }
+      } catch {
+        detached = true;
+        truncated = true;
+      }
+    },
+    snapshot() {
+      return Object.freeze({ events: Object.freeze([...events]), truncated, dropped });
+    }
+  };
+}
+function createGrammarCoverageCollector(definitions) {
+  const ordered = [...definitions].sort((a, b) => a.id.localeCompare(b.id));
+  const known = new Set(ordered.map((definition) => definition.id));
+  const hits = /* @__PURE__ */ new Set();
+  return {
+    hit(id) {
+      if (known.has(id)) hits.add(id);
+    },
+    snapshot() {
+      const hitList = [...hits].sort();
+      const unhit = ordered.map((definition) => definition.id).filter((id) => !hits.has(id));
+      return { definitions: ordered, hits: hitList, unhit, ratio: ordered.length === 0 ? 1 : hitList.length / ordered.length };
+    },
+    reset() {
+      hits.clear();
+    }
+  };
+}
+function grammarCoverageDefinitions(entry, winners) {
+  return buildGrammarPlan(entry, winners).definitions;
+}
+function composedGrammarCoverageDefinitions(grammar, startRule) {
+  const winners = composedCoverageRules(grammar);
+  if (!winners) throw new TypeError("semantic coverage needs re-lowerable composed IR; this composition contains an opaque artifact");
+  const entry = winners[startRule];
+  if (!entry) throw new TypeError(`semantic coverage start rule ${JSON.stringify(startRule)} is not a final winner`);
+  return grammarCoverageDefinitions(entry, winners);
+}
+function coverageEntry(entry, collector, maps, trace) {
+  const cache = /* @__PURE__ */ new WeakMap();
+  const build = (parser2) => {
+    const existing = cache.get(parser2);
+    if (existing) return existing;
+    const rule = maps.rules.get(parser2);
+    const wrap = (parse2) => {
+      const wrapped = {
+        _tag: parser2._tag,
+        _meta: parser2._meta,
+        _def: parser2._def,
+        parse(input, pos, ctx) {
+          if (rule) {
+            collector.hit(rule);
+            trace?.write({ id: rule, phase: "enter", offset: pos });
+          }
+          const result = parse2(input, pos, ctx);
+          if (rule) trace?.write(result.ok ? { id: rule, phase: "success", offset: pos, end: result.span.end } : { id: rule, phase: "failure", offset: result.span.end });
+          return result;
+        }
+      };
+      cache.set(parser2, wrapped);
+      return wrapped;
+    };
+    const def = parser2._def;
+    if (def.tag === "lazy") {
+      return wrap((input, pos, ctx) => build(def.thunk()).parse(input, pos, ctx));
+    }
+    if (def.tag === "label") {
+      const base2 = label(def.label, build(def.parser));
+      return wrap((input, pos, ctx) => {
+        const result = base2.parse(input, pos, ctx);
+        if (result.ok) for (const id of maps.labels.get(parser2) ?? []) {
+          collector.hit(id);
+          trace?.write({ id, phase: "success", offset: pos, end: result.span.end });
+        }
+        return result;
+      });
+    }
+    if (def.tag === "choice") {
+      const ids = maps.choices.get(parser2) ?? [];
+      const invocations = [];
+      const arms = def.parsers.map((arm, index) => {
+        const child = build(arm);
+        return {
+          _tag: child._tag,
+          _meta: child._meta,
+          _def: child._def,
+          parse(input, pos, ctx) {
+            const id = ids[index];
+            if (id) trace?.write({ id, phase: "attempt", offset: pos });
+            const result = child.parse(input, pos, ctx);
+            if (result.ok) {
+              if (def.strategy.tag !== "greedyClassify") collector.hit(ids[index]);
+              const invocation = invocations[invocations.length - 1];
+              if (invocation) {
+                invocation.lastSuccessfulArm = index;
+                invocation.successfulArms.push(index);
+              }
+            } else if (id) {
+              trace?.write({ id, phase: "failure", offset: result.span.end });
+              trace?.write({ id, phase: "backtrack", offset: pos });
+            }
+            return result;
+          }
+        };
+      });
+      const args = arms.map((arm, index) => def.gates[index] ? { combinator: arm, gate: def.gates[index] } : arm);
+      const unsafeChoice = choice;
+      const baseChoice = unsafeChoice(...args);
+      return wrap((input, pos, ctx) => {
+        const invocation = { lastSuccessfulArm: void 0, successfulArms: [] };
+        invocations.push(invocation);
+        const result = baseChoice.parse(input, pos, ctx);
+        const strategy = def.strategy;
+        if (result.ok && strategy.tag === "greedyClassify") {
+          const text = input.slice(pos, result.span.end);
+          const classified = def.parsers.findIndex((arm, index) => index !== strategy.superIndex && getCoreLiteralValue(arm) === text);
+          if (classified !== -1) invocation.lastSuccessfulArm = classified;
+          else invocation.lastSuccessfulArm = strategy.superIndex;
+        }
+        if (result.ok && invocation.lastSuccessfulArm !== void 0) {
+          const id = ids[invocation.lastSuccessfulArm];
+          for (const rejected of invocation.successfulArms) {
+            if (rejected !== invocation.lastSuccessfulArm) {
+              const rejectedId = ids[rejected];
+              if (rejectedId) {
+                trace?.write({ id: rejectedId, phase: "failure", offset: pos });
+                trace?.write({ id: rejectedId, phase: "backtrack", offset: pos });
+              }
+            }
+          }
+          if (id) {
+            collector.hit(id);
+            trace?.write({ id, phase: "selected", offset: pos, end: result.span.end });
+            trace?.write({ id, phase: "success", offset: pos, end: result.span.end });
+          }
+        }
+        invocations.pop();
+        return result;
+      });
+    }
+    const base = (() => {
+      switch (def.tag) {
+        case "sequence": {
+          const unsafeSequence = sequence;
+          return unsafeSequence(...def.parsers.map(build));
+        }
+        case "many":
+          return many(build(def.parser));
+        case "oneOrMore":
+          return oneOrMore(build(def.parser));
+        case "optional":
+          return optional(build(def.parser));
+        case "attempt": {
+          const base2 = attempt(build(def.parser));
+          const id = maps.attempts.get(parser2);
+          return id === void 0 ? base2 : {
+            ...base2,
+            parse(input, pos, ctx) {
+              const result = base2.parse(input, pos, ctx);
+              if (!result.ok) trace?.write({ id, phase: "rollback", offset: pos });
+              return result;
+            }
+          };
+        }
+        case "sepBy":
+          return sepBy(build(def.parser), build(def.separator));
+        case "transform":
+          return transform(build(def.parser), def.fn);
+        case "skip":
+          return skip(build(def.main), build(def.skipped));
+        case "trivia":
+          return trivia(build(def.parser));
+        case "token":
+          return token(build(def.parser));
+        case "leaf":
+          return leaf(build(def.parser), def.fn);
+        case "field":
+          return field(def.name, build(def.parser));
+        case "grammar":
+          return parser({
+            ...def.triviaParser === void 0 ? def.clearTrivia ? { trivia: null } : {} : { trivia: build(def.triviaParser) },
+            ...def.captureTrivia ? { captureTrivia: true } : {},
+            ...def.trackLines ? { trackLines: true } : {}
+          }, build(def.parser));
+        case "not":
+          return not(build(def.parser));
+        case "node": {
+          const opts = { ...def.unwrap ? { unwrap: true } : {}, ...def.collapse ? { collapse: true } : {}, ...def.captureTrivia ? { captureTrivia: true } : {}, ...def.trailingTrivia ? { trailingTrivia: true } : {} };
+          return def.type === void 0 ? node(build(def.parser), def.build, opts) : node(def.type, build(def.parser), def.build, opts);
+        }
+        case "guard":
+          return guard(def.predicate);
+        case "withCtx":
+          return withCtx(def.extra, build(def.parser));
+        case "expect":
+          return expect(build(def.parser), def.label);
+        case "scanTo":
+          return scanTo(build(def.sentinel), { skip: def.skip.map(build), orEOF: def.orEOF });
+        case "literal":
+        case "regex":
+        case "keywords":
+          return parser2;
+        case "recover":
+        case "unknown":
+          throw new TypeError(`runWithGrammarCoverage does not yet support ${def.tag}`);
+        default:
+          return parser2;
+      }
+    })();
+    return wrap((input, pos, ctx) => base.parse(input, pos, ctx));
+  };
+  return build(entry);
+}
+function runWithGrammarCoverage(entry, input, options = {}) {
+  if (typeof entry === "function") throw new TypeError("runWithGrammarCoverage currently requires an interpreter combinator entry");
+  const plan = buildGrammarPlan(entry);
+  const definitions = plan.definitions;
+  const collector = options.collector ?? createGrammarCoverageCollector(definitions);
+  const { collector: _collector, trace, ...runOptions } = options;
+  return { result: run(coverageEntry(entry, collector, plan, trace), input, runOptions), coverage: collector.snapshot() };
+}
+
 // src/cst/trivia-index.ts
 function merge(map, key, run2) {
   if (run2.length === 0) return;
@@ -7531,9 +8259,9 @@ function buildTriviaIndex(root, input = "", opts) {
 function walk(root, visitor, ctx = void 0) {
   const go = (node2, parent) => {
     const descend = visitor.enter ? visitor.enter(node2, parent, ctx) : void 0;
-    const children = node2.children;
-    if (descend !== false && Array.isArray(children)) {
-      for (const child of children) go(child, node2);
+    const children2 = node2.children;
+    if (descend !== false && Array.isArray(children2)) {
+      for (const child of children2) go(child, node2);
     }
     visitor.leave?.(node2, parent, ctx);
   };
@@ -7549,9 +8277,9 @@ function createVisitor(handlers) {
     },
     visitChildren(node2) {
       const out = [];
-      const children = node2.children;
-      if (Array.isArray(children)) {
-        for (const child of children) {
+      const children2 = node2.children;
+      if (Array.isArray(children2)) {
+        for (const child of children2) {
           const r = api.visit(child);
           if (r !== void 0) out.push(r);
         }
@@ -7792,6 +8520,7 @@ function buildOffsetIndex(root, input = "") {
 // src/index.ts
 registerRegexAnalyzer(firstSetFromRegex);
 export {
+  GRAMMAR_COVERAGE_DEFINITIONS,
   OffsetIndex,
   absoluteSpanAt,
   absoluteSpanCST,
@@ -7799,6 +8528,7 @@ export {
   absolutizeCST,
   annotateSpan,
   applyEdit,
+  attempt,
   balanced,
   blankLinesIn,
   buildLineIndex,
@@ -7808,20 +8538,28 @@ export {
   collectLeafSlots,
   commentsIn,
   compile,
+  compiledGrammarCoverageDefinitions,
   completionsAt,
   compose,
+  composeLeaf,
+  composedGrammarCoverageDefinitions,
+  createGrammarCoverageCollector,
+  createGrammarInstrumentationContext,
+  createGrammarTraceSink,
   createVisitor,
   cstBuildHost,
   expect,
   field,
   gapIsSignificant,
   gapText,
+  grammarCoverageDefinitions,
   guard,
   indentMixed,
   indentWidth,
   isParseError,
   keywords,
   label,
+  leaf,
   lineBreaksIn,
   lineStartWithin,
   literal,
@@ -7842,6 +8580,7 @@ export {
   relativizeCST,
   rules,
   run,
+  runWithGrammarCoverage,
   scanTo,
   sepBy,
   sequence,