parseman 0.18.2 → 0.19.0

package/dist/index.cjs

@@ -49,6 +49,7 @@ __export(index_exports, {
   createVisitor: () => createVisitor,
   cstBuildHost: () => cstBuildHost,
   expect: () => expect,
+  field: () => field,
   gapIsSignificant: () => gapIsSignificant,
   gapText: () => gapText,
   guard: () => guard,
@@ -349,7 +350,8 @@ function saveCstMark(ctx) {
   return {
     raw: cstRawLen(ctx),
     tlog: cstTlLen(ctx),
-    leaves: cstLeavesLen(ctx)
+    leaves: cstLeavesLen(ctx),
+    fields: ctx._fields?.length ?? 0
   };
 }
 function rollbackBufList(b, keyMulti, keySingle, len) {
@@ -373,11 +375,13 @@ function rollbackCstCapture(ctx, mark) {
       if (mark.tlog === 0) b.tl = void 0;
       else b.tl.length = mark.tlog;
     }
+    if (ctx._fields) ctx._fields.length = mark.fields;
     return;
   }
   if (ctx._cstRawChildren) ctx._cstRawChildren.length = mark.raw;
   if (ctx._cstTriviaLog) ctx._cstTriviaLog.length = mark.tlog;
   if (ctx._cstLeaves) ctx._cstLeaves.length = mark.leaves;
+  if (ctx._fields) ctx._fields.length = mark.fields;
 }
 function pushCstTriviaEntry(ctx, start, end, kindIndex) {
   const insertIdx = cstRawLen(ctx);
@@ -1117,10 +1121,10 @@ function needsDeferredTriviaCommit(ctx) {
 }
 function saveTriviaMark(ctx) {
   const m = saveCstMark(ctx);
-  return { raw: m.raw, tlog: m.tlog, leaves: m.leaves, log: ctx._triviaLog ? ctx._triviaLog.length : 0 };
+  return { raw: m.raw, tlog: m.tlog, leaves: m.leaves, fields: m.fields, log: ctx._triviaLog ? ctx._triviaLog.length : 0 };
 }
 function rollbackTrivia(ctx, mark) {
-  rollbackCstCapture(ctx, { raw: mark.raw, tlog: mark.tlog, leaves: mark.leaves });
+  rollbackCstCapture(ctx, { raw: mark.raw, tlog: mark.tlog, leaves: mark.leaves, fields: mark.fields });
   if (ctx._triviaLog) ctx._triviaLog.length = mark.log;
 }
 function scanWithLabels(input, cur, ctx) {
@@ -1494,6 +1498,13 @@ function ref() {
     define(p) {
       if (resolved) throw new Error("ref<T>() already defined");
       resolved = p;
+      meta.firstSet = p._meta.firstSet;
+      meta.canMatchNewline = p._meta.canMatchNewline;
+      meta.isTrivia = p._meta.isTrivia;
+      if (p._meta.triviaKindLabels !== void 0) meta.triviaKindLabels = p._meta.triviaKindLabels;
+      else delete meta.triviaKindLabels;
+      if (p._meta.disjoint !== void 0) meta.disjoint = p._meta.disjoint;
+      else delete meta.disjoint;
     }
   };
   return slot;
@@ -1534,6 +1545,9 @@ function markUnusedValues(root) {
       case "transform":
         visit(def.parser, true);
         return;
+      case "field":
+        visit(def.parser, true);
+        return;
       case "skip":
         visit(def.main, consumed);
         visit(def.skipped, false);
@@ -1585,6 +1599,11 @@ function markUnusedValues(root) {
 }
 
 // src/combinators/parser.ts
+function tagRule(r, key) {
+  ;
+  r._ruleName = key;
+  if (r._def.tag === "node" && r._def.type === void 0) r._def.type = key;
+}
 function rules(factory) {
   const cache = {};
   const proxy = new Proxy(cache, {
@@ -1593,7 +1612,7 @@ function rules(factory) {
       const record = target;
       if (!(key in record)) {
         const r = ref();
-        r._ruleName = key;
+        tagRule(r, key);
         record[key] = r;
       }
       return record[key];
@@ -1604,12 +1623,12 @@ function rules(factory) {
     const placeholder = cache[key];
     const parser2 = definitions[key];
     if (placeholder !== void 0 && typeof placeholder.define === "function") {
-      ;
+      tagRule(parser2, key);
       placeholder.define(parser2);
       placeholder._meta.firstSet = parser2._meta.firstSet;
       placeholder._meta.canMatchNewline = parser2._meta.canMatchNewline;
     } else {
-      ;
+      tagRule(parser2, key);
       cache[key] = parser2;
     }
   }
@@ -1666,44 +1685,130 @@ function buildReadsTrivia(def) {
   const src = def.buildSrc ?? def.build.toString();
   const arity = confirmedBuildArity(src);
   if (arity === null) return true;
-  return arity >= 4;
+  return arity >= 5;
 }
 function buildReadsState(def) {
   if (!def.build) return true;
   const src = def.buildSrc ?? def.build.toString();
   const arity = confirmedBuildArity(src);
   if (arity === null) return true;
-  return arity >= 5;
+  return arity >= 6;
+}
+
+// src/compiler/fields.ts
+function buildReadsFields(def) {
+  if (!def.build) return true;
+  const src = def.buildSrc ?? def.build.toString();
+  const arity = confirmedBuildArity(src);
+  if (arity === null) return true;
+  return arity >= 2;
+}
+function parserHasOwnFields(p, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(p)) return false;
+  seen.add(p);
+  const d = p._def;
+  switch (d.tag) {
+    case "field":
+      return true;
+    case "node":
+      return false;
+    case "lazy": {
+      try {
+        return parserHasOwnFields(d.thunk(), seen);
+      } catch {
+        return false;
+      }
+    }
+    case "sequence":
+    case "choice":
+      return d.parsers.some((x) => parserHasOwnFields(x, seen));
+    case "sepBy":
+      return parserHasOwnFields(d.parser, seen) || parserHasOwnFields(d.separator, seen);
+    case "skip":
+      return parserHasOwnFields(d.main, seen) || parserHasOwnFields(d.skipped, seen);
+    case "grammar":
+      return parserHasOwnFields(d.parser, seen) || (d.triviaParser ? parserHasOwnFields(d.triviaParser, seen) : false);
+    case "scanTo":
+      return parserHasOwnFields(d.sentinel, seen) || d.skip.some((x) => parserHasOwnFields(x, seen));
+    case "recover":
+      return parserHasOwnFields(d.parser, seen) || parserHasOwnFields(d.sentinel, seen);
+    case "many":
+    case "oneOrMore":
+    case "optional":
+    case "transform":
+    case "trivia":
+    case "token":
+    case "label":
+    case "expect":
+    case "withCtx":
+    case "not":
+      return parserHasOwnFields(d.parser, seen);
+    default:
+      return false;
+  }
+}
+function buildFieldMap(captures) {
+  if (!captures?.length) return void 0;
+  const out = {};
+  for (const cap of captures) {
+    const entry = { value: cap.value, span: cap.span };
+    const current = out[cap.name];
+    if (current === void 0) out[cap.name] = entry;
+    else if (Array.isArray(current)) current.push(entry);
+    else out[cap.name] = [current, entry];
+  }
+  return out;
 }
 
 // src/combinators/node.ts
-function collapseChild(child) {
+function unwrapChild(child) {
   return child !== null && typeof child === "object" && child._tag === "leaf" ? child.value : child;
 }
-function node(type, combinator, build, opts) {
+function isCstChild(value) {
+  return typeof value === "object" && value !== null && (value._tag === "node" || value._tag === "leaf" || value._tag === "error");
+}
+function missingInferredType() {
+  throw new Error('node(): inferred node type requires a rules() key; pass node("Type", parser) outside rules()');
+}
+function node(typeOrCombinator, combinatorOrBuild, buildOrOpts, maybeOpts) {
+  const hasExplicitType = typeof typeOrCombinator === "string";
+  const type = hasExplicitType ? typeOrCombinator : void 0;
+  const combinator = hasExplicitType ? combinatorOrBuild : typeOrCombinator;
+  const build = hasExplicitType ? buildOrOpts : combinatorOrBuild;
+  const opts = hasExplicitType ? maybeOpts : buildOrOpts;
+  const baseDef = { tag: "node", parser: combinator, ...type === void 0 ? {} : { type }, ...build === void 0 ? {} : { build } };
   const meta = {
     firstSet: combinator._meta.firstSet,
     canMatchNewline: combinator._meta.canMatchNewline,
     isTrivia: false
   };
+  const unwrap = opts?.unwrap === true;
   const collapse = opts?.collapse === true;
-  const def = collapse ? { tag: "node", type, parser: combinator, build, collapse: true } : { tag: "node", type, parser: combinator, build };
+  if (unwrap && collapse) {
+    throw new Error("node() options cannot set both unwrap and collapse");
+  }
+  const def = unwrap || collapse ? { ...baseDef, ...unwrap ? { unwrap: true } : {}, ...collapse ? { collapse: true } : {} } : baseDef;
   const capturesTrivia = build ? buildReadsTrivia(def) : true;
   const clonesState = build ? buildReadsState(def) : true;
+  const capturesFields = parserHasOwnFields(combinator) && (build ? buildReadsFields(def) : true);
   return {
     _tag: "node",
     _meta: meta,
     _def: def,
     parse(input, pos, ctx) {
       const saved = beginCstNodeCapture(ctx);
+      const savedFields = ctx._fields;
+      ctx._fields = capturesFields ? [] : void 0;
       if (!capturesTrivia) ctx.captureTrivia = false;
       const r = combinator.parse(input, pos, ctx);
+      const fields = capturesFields ? buildFieldMap(ctx._fields) : void 0;
+      ctx._fields = savedFields;
       const { children, rawChildren, triviaLog } = endCstNodeCapture(ctx, saved);
       if (!r.ok) return r;
       const st = clonesState && ctx.state !== void 0 ? Object.assign({}, ctx.state) : void 0;
-      const built = collapse && children.length === 1 ? collapseChild(children[0]) : build ? build(children, rawChildren, r.span, triviaLog, st) : ctx.build ? ctx.build(type, children, rawChildren, r.span, triviaLog, st) : { _tag: "node", type, span: { start: r.span.start, end: r.span.end }, state: st ?? null, children };
-      const isNodeLike = typeof built === "object" && built !== null && built._tag === "node";
-      const rawEntry = isNodeLike ? built : { _tag: "leaf", value: typeof built === "string" ? built : "", span: r.span };
+      const nodeType = def.type ?? missingInferredType();
+      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 ? 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 rawEntry = isCstChild(built) ? built : { _tag: "leaf", value: typeof built === "string" ? built : "", span: r.span };
       if (saved.buf !== void 0 || saved.ch !== void 0) {
         pushCstChild(ctx, built, rawEntry);
       }
@@ -1764,6 +1869,19 @@ function label(name, combinator) {
     }
   };
 }
+function field(name, combinator) {
+  return {
+    _tag: combinator._tag,
+    _meta: combinator._meta,
+    _def: { tag: "field", name, parser: combinator },
+    parse(input, pos, ctx) {
+      const result = combinator.parse(input, pos, ctx);
+      if (!result.ok) return result;
+      ctx._fields?.push({ name, value: result.value, span: result.span });
+      return result;
+    }
+  };
+}
 
 // src/compiler/line-index.ts
 function buildLineIndex(input) {
@@ -3246,21 +3364,22 @@ function emitScannableTerminal(shape, c) {
 }
 
 // src/compiler/inline-build.ts
-var MK_BUILD_RE = /^\(\s*(?:\w+\s*,\s*){3}\w+\s*\)\s*=>\s*mk\s*\(\s*(['"])([^'"]+)\1\s*,\s*\w+\s*,\s*\w+\s*,\s*\w+\s*,\s*\w+\s*\)\s*$/;
+var MK_BUILD_RE = /^\(\s*(\w+)\s*,\s*\w+\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*\)\s*=>\s*mk\s*\(\s*(['"])([^'"]+)\5\s*,\s*\1\s*,\s*\3\s*,\s*\2\s*,\s*\4\s*\)\s*$/;
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function looseMkBuildRe(type) {
   return new RegExp(
-    String.raw`^\(\s*(?:\w+\s*,\s*){3}\w+\s*\)\s*=>\s*.+\(\s*(['"])${escapeRegExp(type)}\1\s*,\s*\w+\s*,\s*\w+\s*,\s*\w+\s*,\s*\w+\s*\)\s*$`
+    String.raw`^\(\s*(\w+)\s*,\s*\w+\s*,\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*\)\s*=>\s*.+\(\s*(['"])${escapeRegExp(type)}\5\s*,\s*\1\s*,\s*\3\s*,\s*\2\s*,\s*\4\s*\)\s*$`
   );
 }
 function analyzeMkInlineBuild(def) {
   if (!def.build) return null;
+  if (def.type === void 0) return null;
   const src = (def.buildSrc ?? def.build.toString()).trim();
   const strict = src.match(MK_BUILD_RE);
   if (strict) {
-    const mkType = strict[2];
+    const mkType = strict[6];
     return mkType === def.type ? def.type : null;
   }
   if (looseMkBuildRe(def.type).test(src)) return def.type;
@@ -3587,8 +3706,9 @@ function planDisjointDispatch(parsers) {
   }
   return total >= SWITCH_MIN_CASES ? { kind: "switch", cases } : { kind: "if" };
 }
-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}`;
+function captureRestoreBody(mL, mR, mTl, mLg, mF = null) {
+  const fieldRestore = mF ? `; if (_ctx._fields) _ctx._fields.length = ${mF}` : "";
+  const base = `if (_ctx._cstLeaves) _ctx._cstLeaves.length = ${mL}; if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${mR}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${mTl}${fieldRestore}`;
   return mLg ? `${base}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${mLg}` : base;
 }
 function mayLeavePartialCapture(p, seen = /* @__PURE__ */ new Set()) {
@@ -3636,6 +3756,7 @@ function mayLeavePartialCapture(p, seen = /* @__PURE__ */ new Set()) {
     // Delegating wrappers: defer to the wrapped parser.
     case "transform":
     case "label":
+    case "field":
     case "expect":
     case "withCtx":
     case "grammar":
@@ -3682,6 +3803,7 @@ function capturesLeaf(p, seen = /* @__PURE__ */ new Set()) {
     case "optional":
     case "transform":
     case "label":
+    case "field":
     case "expect":
     case "withCtx":
     case "grammar":
@@ -3719,22 +3841,25 @@ function emitFallible(inner, ctx, pos, swallow = false) {
   ctx.recordFail = savedRecord;
   const ind0 = ind(ctx);
   const needsRollback = ctx.capturing && mayLeavePartialCapture(inner);
+  const needsFieldRollback = needsRollback && parserHasOwnFields(inner);
   const mL = needsRollback ? v(ctx, "_fcl") : null;
   const mR = needsRollback ? v(ctx, "_fcr") : null;
   const mTl = needsRollback ? v(ctx, "_fctl") : null;
+  const mF = needsFieldRollback ? v(ctx, "_fcf") : 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 ${mTl} = _ctx._cstTriviaLog?.length ?? 0`,
+      ...mF ? [`${ind0}const ${mF} = _ctx._fields?.length ?? 0`] : []
     ] : [],
     `${ind0}${lbl}: {`,
     ...r.stmts,
     `${ind0}  ${valV} = ${r.valueVar}; ${endV} = ${r.endVar}; ${okV} = true`,
     `${ind0}}`,
     ...mL ? [
-      `${ind0}if (!${okV}) { ${captureRestoreBody(mL, mR, mTl, null)} }`
+      `${ind0}if (!${okV}) { ${captureRestoreBody(mL, mR, mTl, null, mF)} }`
     ] : []
   ];
   return { stmts, okVar: okV, valVar: valV, endVar: endV };
@@ -3961,6 +4086,7 @@ function failsAtStart(p) {
       return true;
     case "transform":
     case "label":
+    case "field":
       return failsAtStart(d.parser);
     default:
       return false;
@@ -3980,6 +4106,7 @@ function canMatchEmptyAtStart(p) {
       return true;
     case "transform":
     case "label":
+    case "field":
       return canMatchEmptyAtStart(d.parser);
     case "literal":
       return d.value.length === 0;
@@ -4162,11 +4289,13 @@ function emitFirstMatch(def, ctx, pos) {
     const skipCond = gateCond ? `!${resOkV} && ${gateCond}` : `!${resOkV}`;
     const armHasAutoNot = !!(autoNot && autoNot.length > 0);
     const armNeedsRollback = ctx.capturing && (mayLeavePartialCapture(p) || armHasAutoNot && capturesLeaf(p));
+    const armNeedsFieldRollback = armNeedsRollback && parserHasOwnFields(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) : "";
+    const markFields = armNeedsFieldRollback ? v(ctx, "_cmf") : null;
+    const rollback = markLeaves ? captureRestoreBody(markLeaves, markRaw, markTl, markLog, markFields) : "";
     const failSlot = atStart ? staticFx : "_ctx._fx";
     stmts.push(`${ind0}if (${skipCond}) {`);
     if (fsGuard) stmts.push(`${ind(ctx)}if (${fsGuard}) {`);
@@ -4176,7 +4305,8 @@ function emitFirstMatch(def, ctx, pos) {
         `${ind(ctx)}const ${markLeaves} = _ctx._cstLeaves?.length ?? 0`,
         `${ind(ctx)}const ${markRaw} = _ctx._cstRawChildren?.length ?? 0`,
         `${ind(ctx)}const ${markTl} = _ctx._cstTriviaLog?.length ?? 0`,
-        `${ind(ctx)}const ${markLog} = _ctx._triviaLog?.length ?? 0`
+        `${ind(ctx)}const ${markLog} = _ctx._triviaLog?.length ?? 0`,
+        ...markFields ? [`${ind(ctx)}const ${markFields} = _ctx._fields?.length ?? 0`] : []
       );
     }
     const { stmts: armStmts, okVar, valVar, endVar } = emitFallible(p, ctx, pos, atStart);
@@ -4569,6 +4699,9 @@ function emitToken(def, ctx, pos) {
   };
 }
 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()');
+  }
   const structural = def.build === void 0;
   const mkType = structural ? null : analyzeMkInlineBuild(def);
   let buildIdx = null;
@@ -4580,25 +4713,36 @@ function emitNode(def, ctx, pos) {
   const i = ind(ctx);
   const capturesTrivia = mkType !== null || !structural && buildReadsTrivia(def);
   const clonesState = !structural && buildReadsState(def);
+  const hasFields = parserHasOwnFields(def.parser);
+  const capturesFields = hasFields && !structural && buildReadsFields(def);
   const chV = v(ctx, "_ch");
   const rawV = v(ctx, "_raw");
   const capTLv = structural ? v(ctx, "_ctl") : null;
   const capSTv = structural ? v(ctx, "_cst") : null;
+  const capFv = structural && hasFields ? v(ctx, "_cf") : null;
   const tlV = capturesTrivia || structural ? v(ctx, "_tl") : "_EMPTY_TL";
   if (!capturesTrivia) ctx.needsEmptyTl = true;
   const sc = v(ctx, "_sc"), sl = v(ctx, "_sl"), sr = v(ctx, "_sr"), st = v(ctx, "_st"), stl = v(ctx, "_stl");
   if (structural) ctx.needsHostReads = true;
-  const allocStmt = structural ? `${i}const ${capTLv} = _ctx._pmCapTL ??= _hostReads(_ctx.build, 4), ${capSTv} = _ctx._pmCapST ??= (_ctx.build === undefined || _hostReads(_ctx.build, 5))
+  const hostTriviaGate = `_ctx.build !== undefined && (_ctx.build._parsemanCaptureTrivia !== undefined ? _ctx.build._parsemanCaptureTrivia(${JSON.stringify(def.type)}) : (_ctx._pmCapTL ??= _hostReads(_ctx.build, 5)))`;
+  const allocStmt = structural ? `${i}const ${capTLv} = ${hostTriviaGate}, ${capSTv} = _ctx._pmCapST ??= (_ctx.build === undefined || _hostReads(_ctx.build, 6))${capFv ? `, ${capFv} = _ctx.build !== undefined && _hostReads(_ctx.build, 2)` : ""}
 ${i}const ${chV} = [], ${rawV} = [], ${tlV} = ${capTLv} ? [] : _EMPTY_TL` : capturesTrivia ? `${i}const ${chV} = [], ${rawV} = [], ${tlV} = []` : `${i}const ${chV} = [], ${rawV} = []`;
   const innerTl = structural ? `${capTLv} ? ${tlV} : undefined` : capturesTrivia ? tlV : "undefined";
+  const fieldsOn = structural ? capFv ?? "false" : capturesFields ? "true" : "false";
+  const sf = hasFields ? v(ctx, "_sf") : null;
+  const fArr = hasFields ? v(ctx, "_fa") : null;
+  const fObj = hasFields ? v(ctx, "_fields") : "undefined";
   const stmts = [
     allocStmt,
-    `${i}const ${sc} = _ctx._cstChildren, ${sl} = _ctx._cstLeaves, ${sr} = _ctx._cstRawChildren, ${st} = _ctx.captureTrivia, ${stl} = _ctx._cstTriviaLog`,
-    `${i}_ctx._cstChildren = ${chV}; _ctx._cstLeaves = ${chV}; _ctx._cstRawChildren = ${rawV}; _ctx.captureTrivia = true; _ctx._cstTriviaLog = ${innerTl}`
+    `${i}const ${sc} = _ctx._cstChildren, ${sl} = _ctx._cstLeaves, ${sr} = _ctx._cstRawChildren, ${st} = _ctx.captureTrivia, ${stl} = _ctx._cstTriviaLog${sf ? `, ${sf} = _ctx._fields` : ""}`,
+    `${i}_ctx._cstChildren = ${chV}; _ctx._cstLeaves = ${chV}; _ctx._cstRawChildren = ${rawV}; _ctx.captureTrivia = true; _ctx._cstTriviaLog = ${innerTl}${sf ? `; _ctx._fields = ${fieldsOn} ? [] : undefined` : ""}`
   ];
   const { stmts: innerStmts, okVar, endVar } = emitFallible(def.parser, ctx, pos);
   stmts.push(...innerStmts);
-  stmts.push(`${i}_ctx._cstChildren = ${sc}; _ctx._cstLeaves = ${sl}; _ctx._cstRawChildren = ${sr}; _ctx.captureTrivia = ${st}; _ctx._cstTriviaLog = ${stl}`);
+  if (sf && fArr) {
+    stmts.push(`${i}const ${fArr} = _ctx._fields`);
+  }
+  stmts.push(`${i}_ctx._cstChildren = ${sc}; _ctx._cstLeaves = ${sl}; _ctx._cstRawChildren = ${sr}; _ctx.captureTrivia = ${st}; _ctx._cstTriviaLog = ${stl}${sf ? `; _ctx._fields = ${sf}` : ""}`);
   stmts.push(...emitIfFail(ctx, `!${okVar}`, propagateFailBody(ctx)));
   let stV = "undefined";
   if (structural) {
@@ -4608,14 +4752,33 @@ ${i}const ${chV} = [], ${rawV} = [], ${tlV} = ${capTLv} ? [] : _EMPTY_TL` : capt
     stV = v(ctx, "_nst");
     stmts.push(`${i}const ${stV} = _ctx.state !== undefined ? Object.assign({}, _ctx.state) : undefined`);
   }
+  if (sf && fArr) {
+    const fe = v(ctx, "_fe");
+    const cur = v(ctx, "_fc");
+    stmts.push(
+      `${i}let ${fObj} = undefined`,
+      `${i}if (${fArr} && ${fArr}.length) {`,
+      `${i}  ${fObj} = {}`,
+      `${i}  for (const ${fe} of ${fArr}) {`,
+      `${i}    const ${cur} = ${fObj}[${fe}.name], _entry = { value: ${fe}.value, span: ${fe}.span }`,
+      `${i}    if (${cur} === undefined) ${fObj}[${fe}.name] = _entry`,
+      `${i}    else if (Array.isArray(${cur})) ${cur}.push(_entry)`,
+      `${i}    else ${fObj}[${fe}.name] = [${cur}, _entry]`,
+      `${i}  }`,
+      `${i}}`
+    );
+  }
   const ndV = v(ctx, "_nd");
-  const buildExpr = structural ? `{ _tag: 'node', type: ${JSON.stringify(def.type)}, span: { start: ${pos}, end: ${endVar} }, state: ${stV} ?? null, children: ${chV} }` : mkType ? emitInlineMkNodeExpr(mkType, chV, rawV, pos, endVar, tlV) : `${buildRef(ctx)}[${buildIdx}](${chV}, ${rawV}, { start: ${pos}, end: ${endVar} }, ${tlV}, ${stV})`;
-  const ndExpr = ctx.ns || structural ? `_ctx.build !== undefined ? _ctx.build(${JSON.stringify(def.type)}, ${chV}, ${rawV}, { start: ${pos}, end: ${endVar} }, ${tlV}, ${stV}) : (${buildExpr})` : buildExpr;
-  const finalExpr = def.collapse ? `${chV}.length === 1 ? (${chV}[0] !== null && typeof ${chV}[0] === 'object' && ${chV}[0]._tag === 'leaf' ? ${chV}[0].value : ${chV}[0]) : (${ndExpr})` : ndExpr;
+  const buildExpr = structural ? `{ _tag: 'node', type: ${JSON.stringify(def.type)}, span: { start: ${pos}, end: ${endVar} }, state: ${stV} ?? null, children: ${chV} }` : mkType ? emitInlineMkNodeExpr(mkType, chV, rawV, pos, endVar, tlV) : `${buildRef(ctx)}[${buildIdx}](${chV}, ${fObj}, { start: ${pos}, end: ${endVar} }, ${rawV}, ${tlV}, ${stV})`;
+  const ndExpr = ctx.ns || structural ? `_ctx.build !== undefined ? _ctx.build(${JSON.stringify(def.type)}, ${chV}, ${fObj}, { start: ${pos}, end: ${endVar} }, ${rawV}, ${tlV}, ${stV}) : (${buildExpr})` : buildExpr;
+  const hostCollapseExpr = ctx.ns || structural ? `_ctx.build !== undefined && _ctx.build._parsemanCstCollapse !== undefined && ${chV}.length === 1 && ${rawV}.length === 1 && _ctx.build._parsemanCstCollapse(${JSON.stringify(def.type)}, ${chV}[0], ${chV}, ${rawV}) ? ${chV}[0] : (${ndExpr})` : ndExpr;
+  const unwrapExpr = `${chV}.length === 1 ? (${chV}[0] !== null && typeof ${chV}[0] === 'object' && ${chV}[0]._tag === 'leaf' ? ${chV}[0].value : ${chV}[0]) : (${ndExpr})`;
+  const collapseExpr = `${chV}.length === 1 ? ${chV}[0] : (${ndExpr})`;
+  const finalExpr = def.unwrap ? unwrapExpr : def.collapse ? collapseExpr : hostCollapseExpr;
   stmts.push(
     `${i}const ${ndV} = ${finalExpr}`,
     `${i}if (${sc}) ${sc}.push(${ndV})`,
-    `${i}if (${sr}) ${sr}.push((typeof ${ndV} === 'object' && ${ndV} !== null && ${ndV}._tag === 'node') ? ${ndV} : { _tag: 'leaf', value: typeof ${ndV} === 'string' ? ${ndV} : '', span: { start: ${pos}, end: ${endVar} } })`
+    `${i}if (${sr}) ${sr}.push((typeof ${ndV} === 'object' && ${ndV} !== null && (${ndV}._tag === 'node' || ${ndV}._tag === 'leaf' || ${ndV}._tag === 'error')) ? ${ndV} : { _tag: 'leaf', value: typeof ${ndV} === 'string' ? ${ndV} : '', span: { start: ${pos}, end: ${endVar} } })`
   );
   return { stmts, valueVar: ndV, endVar };
 }
@@ -4830,6 +4993,17 @@ function emitDispatch(p, ctx, pos) {
         endVar: inner.endVar
       };
     }
+    case "field": {
+      const inner = emit(def.parser, ctx, pos);
+      return {
+        stmts: [
+          ...inner.stmts,
+          `${ind(ctx)}if (_ctx._fields) _ctx._fields.push({ name: ${JSON.stringify(def.name)}, value: ${inner.valueVar}, span: { start: ${pos}, end: ${inner.endVar} } })`
+        ],
+        valueVar: inner.valueVar,
+        endVar: inner.endVar
+      };
+    }
     case "grammar": {
       const savedTrivia = ctx.activeTrivia;
       const savedKindLabels = ctx.triviaKindLabels;
@@ -4931,6 +5105,7 @@ function hasNodeDef(p, seen = /* @__PURE__ */ new Set()) {
     case "trivia":
     case "token":
     case "label":
+    case "field":
     case "optional":
     case "many":
     case "oneOrMore":
@@ -4967,6 +5142,7 @@ function childrenOf(def) {
     case "trivia":
     case "token":
     case "label":
+    case "field":
     case "grammar":
     case "not":
     case "node":
@@ -5208,6 +5384,11 @@ function assertRuleName(name) {
     );
   }
 }
+function publicRuleWrapperSource(rule, fnSource) {
+  const labels = rule._meta.triviaKindLabels;
+  if (labels === void 0) return fnSource;
+  return `Object.assign(${fnSource}, { _meta: { triviaKindLabels: ${JSON.stringify(labels)} } })`;
+}
 function compileLinkable(ruleMapArg, ns) {
   if (!ns) throw new Error("compileLinkable: ns must be a non-empty namespace");
   for (const [, rule] of ruleMapArg) markUnusedValues(rule);
@@ -5310,7 +5491,7 @@ function compileLinkable(ruleMapArg, ns) {
       ctx.recordFail = savedRec;
       pushNamedFnDecl(ctx, fn, body.stmts, body.valueVar, body.endVar);
     }
-    perEntry.push({ key, r: emitNamedFnCall(ctx, fn, "_pos") });
+    perEntry.push({ key, rule, r: emitNamedFnCall(ctx, fn, "_pos") });
   }
   if (ctx.runtimeParsers.length !== 0) return null;
   const mfSrcs = ctx.mapFns.length > 0 && ctx.mapFnSrcs.every((s) => s !== null) ? ctx.mapFnSrcs : null;
@@ -5333,14 +5514,14 @@ function compileLinkable(ruleMapArg, ns) {
     ...privateFns
   ].filter(Boolean);
   const wrappers = /* @__PURE__ */ new Map();
-  for (const { key, r } of perEntry) {
-    wrappers.set(key, [
+  for (const { key, rule, r } of perEntry) {
+    wrappers.set(key, publicRuleWrapperSource(rule, [
       `function(input, _pos, _ctx) {`,
       `  let pos = _pos`,
       ...r.stmts,
       `  return { ok: true, value: ${r.valueVar}, span: { start: _pos, end: ${r.endVar} } }`,
       `}`
-    ].join("\n"));
+    ].join("\n")));
   }
   const firstSets = /* @__PURE__ */ new Map();
   for (const [key, rule] of ruleMap) {
@@ -5543,6 +5724,7 @@ function evalRuleMapIR(ir) {
     "skip",
     "trivia",
     "label",
+    "field",
     "expect",
     "_tf",
     "_nd",
@@ -5569,6 +5751,7 @@ function evalRuleMapIR(ir) {
     skip,
     trivia,
     label,
+    field,
     expect,
     _tf,
     _nd
@@ -5583,9 +5766,26 @@ function linkable(rulesMap, ns) {
   if (!pieces) throw new Error("linkable(): this grammar cannot be compiled to a linkable artifact (contains a runtime-only parser fallback)");
   return pieces;
 }
-function cstBuildHost(type, children, _rawChildren, span, _triviaLog, state) {
+function normalizeCstCollapse(collapse) {
+  if (collapse === true) return () => true;
+  if (Array.isArray(collapse)) {
+    const types = new Set(collapse);
+    return (type) => types.has(type);
+  }
+  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 cstBuildHost(typeOrOptions, children, _fields, span, rawChildren, triviaLog, state) {
+  if (typeof typeOrOptions === "string") {
+    return buildCstNode(typeOrOptions, children ?? [], _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);
+  if (collapse) host._parsemanCstCollapse = collapse;
+  return host;
+}
 function pick(grammar, names) {
   const p = grammar.ruleFns instanceof Map ? grammar : linkable(grammar);
   const keep = /* @__PURE__ */ new Set();
@@ -5617,8 +5817,9 @@ function fusedBody(pieces) {
     }
   }
   const contributing = new Set(winner.values());
-  const needsEmptyTl = [...contributing].some((p) => p.needsEmptyTl);
-  const needsHostReads = [...contributing].some((p) => p.needsHostReads);
+  const contributingPieces = [...contributing];
+  const needsEmptyTl = contributingPieces.some((p) => p.needsEmptyTl);
+  const needsHostReads = contributingPieces.some((p) => p.needsHostReads);
   const lines = [
     // Shared sentinel protocol (must match NAMED_FN_FAIL / NAMED_FN_END in codegen).
     "const _pfFail = {}",
@@ -5626,7 +5827,7 @@ function fusedBody(pieces) {
     ...needsEmptyTl ? ["const _EMPTY_TL = Object.freeze([])"] : [],
     ...needsHostReads ? [HOST_READS_DECL] : [],
     // Each contributing artifact's namespaced private prelude (regexes, _pf, …).
-    ...[...contributing].flatMap((p) => p.prelude),
+    ...[...new Set(contributingPieces.flatMap((p) => p.prelude))],
     // The winning `_r_<Name>` function for each rule (one per name → no redeclare).
     ...[...winner].map(([k, p]) => p.ruleFns.get(k))
   ];
@@ -5649,7 +5850,7 @@ function fusedBody(pieces) {
     }
   );
   const env = {};
-  for (const p of contributing) {
+  for (const p of contributingPieces) {
     if (p.mfFns.length) env[`${p.ns}mf`] = p.mfFns;
     if (p.buildFns.length) env[`${p.ns}build`] = p.buildFns;
   }
@@ -5669,14 +5870,23 @@ function materializePiece(p) {
   if (!pieces) throw new Error(`compose: carried IR for ns "${p.ns}" could not be re-lowered`);
   return pieces;
 }
-function itemPieces(item) {
+function nextComposeNs(used) {
+  let ns;
+  do {
+    ns = `_lk${_nsCounter++}_`;
+  } while (used.has(ns));
+  used.add(ns);
+  return ns;
+}
+function itemPieces(item, used) {
   const carried = item[COMPOSED_PIECES];
-  if (Array.isArray(carried)) return carried.map(materializePiece);
-  if (item.ruleFns instanceof Map) return [item];
-  return [linkable(item)];
+  const pieces = Array.isArray(carried) ? carried.map(materializePiece) : item.ruleFns instanceof Map ? [item] : [linkable(item, nextComposeNs(used))];
+  for (const p of pieces) used.add(p.ns);
+  return pieces;
 }
 function compose(items) {
-  const pieces = items.flatMap(itemPieces);
+  const used = /* @__PURE__ */ new Set();
+  const pieces = items.flatMap((item) => itemPieces(item, used));
   const map = fuseRules(pieces);
   Object.defineProperty(map, COMPOSED_PIECES, { value: pieces, enumerable: false });
   return map;