parseman 0.53.0 → 0.54.0

package/src/table/assemble.ts

@@ -66,6 +66,7 @@
 import type { Combinator, FieldMap, FirstSet, ParseContext, ParseResult, ParserDef } from '../types.ts'
 import { balanced, scanTo } from '../combinators/scanTo.ts'
 import { buildFieldMap } from '../compiler/fields.ts'
+import { FIELD_LEADING_TRIVIA, FIELD_TRAILING_TRIVIA, LEAD, triviaFieldCapture } from '../combinators/field-trivia.ts'
 import { asciiFoldKey } from '../combinators/dispatch.ts'
 import { projectChild, unwrapChild } from '../combinators/node.ts'
 import { cstOutputHost } from '../compiler/build-arity.ts'
@@ -129,7 +130,7 @@ import { computeSiteLabels, reachableSites } from './site-labels.ts'
 import { refuseUnclassifiedRootScope } from '../cst/root-trivia-scope.ts'
 import { captureError, firstSetSentinel, matchesAt, orSentinel, recoverScan } from '../recovery/scan.ts'
 import {
-  leadingLiteralFamily, leadingScalarSequence, leadingScalarTerminal, makeScalarRecognizer, scalarTerminalNodeChild,
+  largeChoiceLiteralPretest, leadingScalarSequence, leadingScalarTerminal, makeScalarRecognizer, scalarTerminalNodeChild,
   scalarTerminalNotChild, type ScalarRecognizer,
 } from './scalar-terminal.ts'
 
@@ -146,6 +147,7 @@ const EMIT_ENABLED = (globalThis as { process?: { env?: Record<string, string |
 
 /** Failure sentinel — SHARED with the other two engines, see `cell.ts`. */
 import { FAIL, newEndCell } from './cell.ts'
+import { fieldSpec, leadingTriviaFieldAt } from './field-spec.ts'
 
 const EMPTY_TL: readonly number[] = Object.freeze([])
 /** `finishCstBuf`'s two empty sentinels, held here so the node piece can inline it. */
@@ -1053,6 +1055,15 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
     return cur
   }
 
+  /**
+   * A `field(…, { leadingTrivia: true })` term. The pre-scan cursor reaches the
+   * field AFTER `step`'s scan, right before the field runs, so a field inside the
+   * trivia grammar cannot take it first. One closure per call; only such terms pay.
+   */
+  function leadingFieldTerm(step: typeof nextTerm, child: Piece, input: string, cur: number, ctx: ParseContext): number {
+    return step((i, p, c) => { LEAD.at = cur; return child(i, p, c) }, input, cur, ctx)
+  }
+
   function committed(c: ParseContext): boolean {
     return c._fc === true
   }
@@ -1793,12 +1804,27 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
       }
 
       case OP_FIELD: {
-        const name = k[code[ip + 1]!] as string
+        const { name, bits } = fieldSpec(k[code[ip + 1]!])
         const child = link(code[ip + 2]!)
+        if (bits === 0) {
+          return (input, pos, ctx) => {
+            const v = child(input, pos, ctx)
+            if (v === FAIL) return FAIL
+            ctx._fields?.push({ name, value: v, span: { start: pos, end: EC.e } })
+            return v
+          }
+        }
+        const leading = (bits & FIELD_LEADING_TRIVIA) !== 0
+        const trailing = (bits & FIELD_TRAILING_TRIVIA) !== 0
         return (input, pos, ctx) => {
+          const leadFrom = leading ? LEAD.at : -1
+          LEAD.at = -1
           const v = child(input, pos, ctx)
           if (v === FAIL) return FAIL
-          ctx._fields?.push({ name, value: v, span: { start: pos, end: EC.e } })
+          const end = EC.e
+          const trailEnd = trailing && ctx.trivia !== undefined ? consumeTrivia(input, end, ctx) : end
+          ctx._fields?.push(triviaFieldCapture(name, v, input, pos, end, leadFrom, trailEnd))
+          EC.e = trailEnd
           return v
         }
       }
@@ -2322,6 +2348,12 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
             const kidIp = code[base + i]!
             if (code[kidIp] !== OP_ADJ) {
               const kid = link(kidIp)
+              if (leadingTriviaFieldAt(code, k, kidIp)) {
+                return (input, cur, ctx, inherited) => {
+                  ctx._sync = sync ?? inherited
+                  return leadingFieldTerm(step, kid, input, cur, ctx)
+                }
+              }
               return (input, cur, ctx, inherited) => {
                 ctx._sync = sync ?? inherited
                 return step(kid, input, cur, ctx)
@@ -2389,14 +2421,22 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
           }
         }
 
+        // A `field(…, { leadingTrivia: true })` term is a boundary fact too: the
+        // runner hands it the cursor from BEFORE the scan (`LEAD`, cell.ts).
         let hasAdj = false
-        for (let i = 1; i < n; i++) if (code[code[base + i]!] === OP_ADJ) { hasAdj = true; break }
+        for (let i = 1; i < n; i++) {
+          const kidIp = code[base + i]!
+          if (code[kidIp] === OP_ADJ || leadingTriviaFieldAt(code, k, kidIp)) { hasAdj = true; break }
+        }
         if (hasAdj) {
           const first = link(code[base]!)
           const runnerAt = (i: number): TermRunner => {
             const kidIp = code[base + i]!
             if (code[kidIp] !== OP_ADJ) {
               const kid = link(kidIp)
+              if (leadingTriviaFieldAt(code, k, kidIp)) {
+                return (input, cur, ctx) => leadingFieldTerm(step, kid, input, cur, ctx)
+              }
               return (input, cur, ctx) => step(kid, input, cur, ctx)
             }
             const negated = code[kidIp + 1] === 1
@@ -2791,7 +2831,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         if (n === 2 || n === 3) {
           const a0 = link(code[base]!), a1 = link(code[base + 1]!)
           const a2 = n === 3 ? link(code[base + 2]!) : undefined
-          const predecide = !hostCst && !REC && !cfg.probe && !cfg.coverage && !cfg.trackLines
+          const predecide = !REC && !cfg.probe && !cfg.coverage && !cfg.trackLines
           const p0ip = predecide ? leadingScalarTerminal(code, code[base]!, 2, true, true) : -1
           const p1ip = predecide ? leadingScalarTerminal(code, code[base + 1]!, 2, true, true) : -1
           const p2ip = predecide && n === 3 ? leadingScalarTerminal(code, code[base + 2]!, 2, true, true) : -1
@@ -2958,6 +2998,56 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
             )
           }
           const masked = bindMasked(0, EMPTY_EXPECTED_PREFIX)
+          // LITERAL PRETESTS. First-char dispatch cannot tell `@{…}` or `@@x` from
+          // `@x`, so every arm sharing the char is entered, and under a CST host
+          // each entered node opens a capture frame before failing on the second
+          // char. An arm that must begin with a literal of two or more chars (or
+          // one of a family of them) is tested on the literal first and, on a
+          // miss, skipped exactly as a char-excluded arm is: its static expected
+          // set is the one reported. The test is pure, so a miss leaves no
+          // capture, trivia or field to roll back.
+          const pBit: number[] = []
+          const pRec: ScalarRecognizer[] = []
+          if (!REC && !cfg.probe && !cfg.coverage && !cfg.trackLines) {
+            for (let i = 0; i < n; i++) {
+              for (const terminal of largeChoiceLiteralPretest(code, k, code[base + i]!) ?? []) {
+                pBit.push(1 << i)
+                pRec.push(scalarFor(terminal)!)
+              }
+            }
+          }
+          const pn = pBit.length
+          if (pn !== 0) {
+            return (input, pos, ctx) => {
+              const c = lead(input, pos)
+              const need = markCst(ctx)
+              const mRaw = MRAW
+              const mTl = MTL
+              const mLv = MLV
+              const mFl = need ? ctx._fields?.length ?? 0 : 0
+              const mEr = need ? ctx._errors?.length ?? 0 : 0
+              const mLog = need ? ctx._triviaLog?.length ?? 0 : 0
+              const mRoot = need ? ctx._rootTriviaLog?.length ?? 0 : 0
+              if (c < 128) {
+                const bits = mask[c < 0 ? 128 : c]!
+                let tested = 0
+                let hit = 0
+                for (let i = 0; i < pn; i++) {
+                  const b = pBit[i]!
+                  if ((bits & b) === 0 || (hit & b) !== 0) continue
+                  tested |= b
+                  if (pRec[i]!(input, pos) >= 0) hit |= b
+                }
+                return masked(
+                  input, pos, ctx, bits & (~tested | hit),
+                  need, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot, undefined, 0, pos,
+                )
+              }
+              return general(
+                input, pos, ctx, c, need, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot, undefined, 0, pos,
+              )
+            }
+          }
           return (input, pos, ctx) => {
             const c = lead(input, pos)
             const need = markCst(ctx)
@@ -3100,6 +3190,8 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         const max = code[ip + 3]!
         const sepIp = code[ip + 4]!
         const sep = sepIp >= 0 ? link(sepIp) : undefined
+        // A `field(…, { leadingTrivia: true })` separator reads the pre-scan cursor.
+        const sepLeads = sepIp >= 0 && leadingTriviaFieldAt(code, k, sepIp)
         const flags = code[ip + 5]!
         const keepSeparators = (flags & 2) !== 0
         const trailingAllowed = (flags & 1) !== 0
@@ -3183,6 +3275,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
                 let sp = cur
                 if (hasTrivia) sp = skipTrivia(input, sp, ctx)
                 ctx._fc = false
+                if (sepLeads) LEAD.at = cur
                 const sv = sep(input, sp, ctx)
                 if (sv === FAIL) {
                   if (needMark) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)
@@ -3283,6 +3376,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
               let sp = cur
               if (hasTrivia) sp = skipTrivia(input, sp, ctx)
               ctx._fc = false
+              if (sepLeads) LEAD.at = cur
               const sv = sep(input, sp, ctx)
               if (sv === FAIL) {
                 if (needMark) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)
@@ -3706,20 +3800,9 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
               if (child >= 0) scalarFor(child)
               continue
             }
-            if (child >= 0) {
-              const spec = k[code[child + 1]!]
-              if (code[child] === OP_LIT && typeof spec === 'string' && spec.length >= 2) {
-                scalarFor(child)
-                continue
-              }
-            }
-            const family = leadingLiteralFamily(code, k, armIp)
-            if (family !== undefined && family.length >= 2 && family.every(terminal => {
-              const value = k[code[terminal + 1]!]
-              return typeof value === 'string' && value.length >= 2
-            })) {
-              for (const terminal of family) scalarFor(terminal)
-            }
+            const literals = largeChoiceLiteralPretest(code, k, armIp)
+            if (literals !== undefined) for (const terminal of literals) scalarFor(terminal)
+            if (literals !== undefined && literals.length === 1 && literals[0] === child) continue
             const sequence = leadingScalarSequence(code, armIp)
             if (sequence !== undefined && (sequence.trivia < 0
               || triviaScan[sequence.trivia] != null)) {
@@ -3767,6 +3850,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         REC ? prog.cc.map((_, i) => sentinelFor(i)) : EMPTY_SENTS,
         matchesAt, recoverScan, orSentinel, captureError,
         scalarRecognizers, commitTriviaScan, scanTriviaCompact, t.lex, adjacencyHolds, t.lexPrograms,
+        LEAD, triviaFieldCapture,
       )
       emitReached = new Set(pre.reached)
     }
@@ -3848,6 +3932,7 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
         REC ? prog.cc.map((_, i) => sentinelFor(i)) : EMPTY_SENTS,
         matchesAt, recoverScan, orSentinel, captureError,
         scalarRecognizers, commitTriviaScan, scanTriviaCompact, t.lex, adjacencyHolds, t.lexPrograms,
+        LEAD, triviaFieldCapture,
       )
       emitReached = em.reached
     } catch (e) {
@@ -4067,6 +4152,13 @@ export class AssemblyCache {
   }
 }
 
+/**
+ * One rule of the map. A lowered terminal is emitted as this call, not as
+ * `tableRules(…)["Entry"]`: `@__PURE__` covers a call and not a property read
+ * after it, so a bundler had to keep the whole table of every terminal nothing
+ * referenced. With the lookup inside the call the statement is droppable.
+ */
+export function tableRules(source: TableProgram | CompactProgram, entry: string): TableRule
 /**
  * The ASSEMBLED rule map — the same artifact contract as `tableRules`, run
  * through linked closures instead of the bytecode interpreter.
@@ -4076,11 +4168,19 @@ export class AssemblyCache {
  * assembly built for it. Everything past that point is pieces, and no piece body
  * reads an option — `scripts/check-invariants.mjs` INV-6 asserts it. `forCtx`
  * carries the argument for why that read is irreducible rather than merely cheap.
+ *
+ * Declared last, so `ReturnType<typeof tableRules>` stays the map.
  */
 export function tableRules(
   source: TableProgram | CompactProgram,
-  artifactMetadata: Readonly<Record<symbol, unknown>> = {},
-): Record<string, TableRule> {
+  artifactMetadata?: Readonly<Record<symbol, unknown>>,
+): Record<string, TableRule>
+export function tableRules(
+  source: TableProgram | CompactProgram,
+  metadataOrEntry: Readonly<Record<symbol, unknown>> | string = {},
+): Record<string, TableRule> | TableRule {
+  const entry = typeof metadataOrEntry === 'string' ? metadataOrEntry : undefined
+  const artifactMetadata = typeof metadataOrEntry === 'string' ? {} : metadataOrEntry
   const prog = expandCompact(source)
   const resolved = resolveTable(prog)
   const cache = new AssemblyCache(prog, resolved)
@@ -4105,7 +4205,7 @@ export function tableRules(
    * `runRule`, after the outer read.
    */
   let selected: Assembly | undefined
-  return stampRuleMap(prog, {
+  const map = stampRuleMap(prog, {
     runRule: (ri, input, pos, ctx) => {
       const a = selected ?? cache.forCtx(ctx)
       selected = undefined
@@ -4128,4 +4228,8 @@ export function tableRules(
       return a.scanSkip[skipOf?.[ri] ?? -1]
     },
   }, artifactMetadata, resolved)
+  if (entry === undefined) return map
+  // Own properties only: the map inherits `toString`, `constructor` and the rest.
+  if (!Object.hasOwn(map, entry)) throw new Error(`tableRules: the program has no rule ${JSON.stringify(entry)}`)
+  return map[entry]!
 }

package/src/table/emit-assembly.ts

@@ -63,10 +63,12 @@ import {
   computeSiteLabels, reachableSites, type SiteLabel,
 } from './site-labels.ts'
 import {
-  leadingLiteralFamily, leadingScalarSequence, leadingScalarTerminal,
+  largeChoiceLiteralPretest, leadingScalarSequence, leadingScalarTerminal,
   scalarTerminalNodeChild, scalarTerminalNotChild, type LeadingScalarSequence,
 } from './scalar-terminal.ts'
 import { childSlots } from './child-slots.ts'
+import { fieldSpec, leadingTriviaFieldAt } from './field-spec.ts'
+import { FIELD_LEADING_TRIVIA, FIELD_TRAILING_TRIVIA } from '../combinators/field-trivia.ts'
 
 /** What the compiled factory hands back — the emitted twin of `Assembly`. */
 export type EmittedPiece = (input: string, pos: number, ctx: ParseContext) => unknown
@@ -122,6 +124,9 @@ export const EMITTED_PARAMS = [
   'adjacencyHolds',
   // Appended for selected composite lexical programs; old factories ignore it.
   'LEXPROG',
+  // Appended for trivia-attributing fields (`field(…, { leadingTrivia })`);
+  // old factories ignore them.
+  'LEAD', 'triviaFieldCapture',
 ] as const
 
 /**
@@ -607,20 +612,12 @@ export function emitAssemblySource(
           if (child >= 0) scalarSpecs.add(code[child + 1]!)
           continue
         }
-        if (child >= 0) {
-          const spec = k[code[child + 1]!]
-          if (code[child] === OP_LIT && typeof spec === 'string' && spec.length >= 2) {
-            largeChoiceScalarSpecs.add(code[child + 1]!)
-            continue
-          }
-        }
-        const family = leadingLiteralFamily(code, k, armIp)
-        if (family !== undefined && family.length >= 2 && family.every(terminal => {
-          const value = k[code[terminal + 1]!]
-          return typeof value === 'string' && value.length >= 2
-        })) {
-          largeChoiceLiteralFamilies.set(armIp, family)
+        const literals = largeChoiceLiteralPretest(code, k, armIp)
+        if (literals !== undefined && literals.length === 1 && literals[0] === child) {
+          largeChoiceScalarSpecs.add(code[child + 1]!)
+          continue
         }
+        if (literals !== undefined) largeChoiceLiteralFamilies.set(armIp, literals)
         const sequence = leadingScalarSequence(code, armIp)
         // A labelled trivia scanner is still recognition authority here. This
         // pretest is pure: on a miss the ordinary arm's trivia log would have
@@ -1307,17 +1304,34 @@ return v
       }
 
       case OP_FIELD: {
-        const name = q(k[code[ip + 1]!] as string)
+        const spec = fieldSpec(k[code[ip + 1]!])
+        const name = q(spec.name)
         const child = link(code[ip + 2]!)
         // `ctx._fields?.push(…)` — conditional on a field-reading node being
         // open, exactly as `map.ts` has it, so a field outside one costs a load
         // and a branch. The ARRAY is what `OP_NODE` hands to `buildFieldMap`.
-        return `${head}
+        if (spec.bits === 0) {
+          return `${head}
 const v=${child}(input,pos,ctx)
 if(v===FAIL)return FAIL
 const f=ctx._fields
 if(f!==undefined)f.push({name:${name},value:v,span:{start:pos,end:EC.e}})
 return v
+}`
+        }
+        const leading = (spec.bits & FIELD_LEADING_TRIVIA) !== 0
+        const trailing = (spec.bits & FIELD_TRAILING_TRIVIA) !== 0
+        return `${head}
+const lf=${leading ? 'LEAD.at' : '-1'}
+LEAD.at=-1
+const v=${child}(input,pos,ctx)
+if(v===FAIL)return FAIL
+const e=EC.e
+const te=${trailing ? 'ctx.trivia!==undefined?consumeTrivia(input,e,ctx):e' : 'e'}
+const f=ctx._fields
+if(f!==undefined)f.push(triviaFieldCapture(${name},v,input,pos,e,lf,te))
+EC.e=te
+return v
 }`
       }
 
@@ -1687,7 +1701,13 @@ return v
               `if(!adjacencyHolds(input,cur,ctx,${negated ? 'true' : 'false'},${kinds})){ctx._fe=cur;ctx._fx=${expected};return FAIL}`,
               `${vn}=null`,
             )
-          } else parts.push(emitTerm(kids[i]!, vn, tmp(), L, skipFor(L)))
+          } else {
+            // A leading-trivia field reads the cursor from before the term's scan.
+            // The callee expression hands it over AFTER the scan statement, right
+            // before the call, so a field inside the trivia grammar cannot take it.
+            const callee = leadingTriviaFieldAt(code, k, childIp) ? `(LEAD.at=cur,${kids[i]!})` : kids[i]!
+            parts.push(emitTerm(callee, vn, tmp(), L, skipFor(L)))
+          }
           names.push(vn)
         }
         parts.push('EC.e=cur')
@@ -2232,7 +2252,7 @@ ${sep !== undefined ? `if(count>0){
 const lb=cstLeavesLen(ctx)
 let sp=cur
 ${hasTrivia === 'false' ? '' : hasTrivia === 'true' ? `sp=${skip}(input,sp,ctx)\n` : `if(hasTrivia)sp=${skip}(input,sp,ctx)\n`}ctx._fc=false
-const sv=${sep}(input,sp,ctx)
+${sepIp >= 0 && leadingTriviaFieldAt(code, k, sepIp) ? 'LEAD.at=cur\n' : ''}const sv=${sep}(input,sp,ctx)
 if(sv===FAIL){
 ${rb}
 if(ctx._fc===true)return FAIL

package/src/table/emit.ts

@@ -352,12 +352,16 @@ export type ExpressionEmitOptions = EmitOptions & {
    *
    * `null` is what a `rules()` call site needs: its initialiser evaluates to the
    * `{ name: fn, … }` object, exactly what `tableRules(…)` already returns, so
-   * the map form is the expression WITHOUT the trailing index — not a second
+   * the map form is the expression WITHOUT the entry argument — not a second
    * emitter. `compileRuleMap`'s replacement has the same shape and the same
    * splice point, which is what makes the two lowerings interchangeable there.
    */
   readonly entry?: string | null
-  /** Static metadata object passed to `tableRules` as its second argument. */
+  /**
+   * Static metadata object passed to `tableRules` as its second argument. Only
+   * the rule-map form (`entry: null`) takes it; with an entry, that argument is
+   * the entry's name.
+   */
   readonly metadataSource?: string
 }
 
@@ -379,11 +383,18 @@ export function emitTableExpression(prog: TableProgram, opts: ExpressionEmitOpti
   const entry = opts.entry === undefined ? 'grammar' : opts.entry
   const ref = opts.runtimeRef ?? 'tableRules'
   const fns = opts.fnSources ?? prog.fns.map(() => '() => {}')
-  const close = `}${opts.metadataSource === undefined ? '' : `,${opts.metadataSource}`})`
+  // The entry is an ARGUMENT, never a trailing `[entry]`: `@__PURE__` covers the
+  // call and not a property read after it, so `tableRules({…})["Entry"]` left an
+  // unreferenced terminal's whole table in every bundle.
+  const meta = opts.metadataSource
+  if (entry !== null && meta !== undefined) {
+    throw new Error('emitTableExpression: metadataSource is for the rule-map form (entry: null); a single entry carries none')
+  }
+  const tail = entry !== null ? `,${jsString(entry)}` : meta === undefined ? '' : `,${meta}`
   return [
     `/* @__PURE__ */ ${ref}({`,
     ...programFields(prog, fns, opts),
-    entry === null ? close : `${close}[${jsString(entry)}]`,
+    `}${tail})`,
   ].join('\n')
 }
 

package/src/table/encode.ts

@@ -7,6 +7,7 @@ import { deriveExpected } from '../combinators/expect.ts'
 import { assertionFailureExpected, directTerminalFailureExpected } from '../combinators/expected.ts'
 import { buildReadsRaw, buildReadsState, buildReadsTrivia } from '../compiler/build-arity.ts'
 import { buildReadsFields, parserHasOwnFields } from '../compiler/fields.ts'
+import { FIELD_LEADING_TRIVIA, FIELD_TRAILING_TRIVIA } from '../combinators/field-trivia.ts'
 import { asciiFoldKey, branchUsesRouted, parserUsesRouted } from '../combinators/dispatch.ts'
 import {
   OP_CHOICE, OP_EMPTY, OP_GATE, OP_LEAF, OP_SOURCE_LEAF, OP_LIT, OP_NODE, OP_NOT, OP_OPT,
@@ -555,6 +556,17 @@ class Encoder {
     return i
   }
 
+  private fieldSpecIndex = new Map<string, number>()
+  private fieldSpecSlot(name: string, bits: number): number {
+    const key = JSON.stringify([name, bits])
+    const hit = this.fieldSpecIndex.get(key)
+    if (hit !== undefined) return hit
+    const i = this.k.length
+    this.k.push([name, bits])
+    this.fieldSpecIndex.set(key, i)
+    return i
+  }
+
   /**
    * A `notAdjacent({ kinds })` filter, pooled by its CONTENTS.
    *
@@ -1518,8 +1530,12 @@ class Encoder {
         for (let i = 0; i < arms.length; i++) this.code[head + 6 + i] = arms[i]!
         return head
       }
-      case 'field':
-        return this.emit(OP_FIELD, this.constant(d.name), this.node(d.parser).ip)
+      case 'field': {
+        // A trivia-attributing field carries `[name, bits]` in the name slot
+        // (`FIELD_LEADING_TRIVIA`/`FIELD_TRAILING_TRIVIA`); a plain one the name.
+        const bits = (d.leadingTrivia === true ? FIELD_LEADING_TRIVIA : 0) | (d.trailingTrivia === true ? FIELD_TRAILING_TRIVIA : 0)
+        return this.emit(OP_FIELD, bits === 0 ? this.constant(d.name) : this.fieldSpecSlot(d.name, bits), this.node(d.parser).ip)
+      }
       case 'lazy': {
         // A named reference is not a hop: it resolves to the target's row.
         // Emitting a trampoline here cost one dispatch per reference for nothing.

package/src/table/exec.ts

@@ -72,6 +72,8 @@ import { scalarTerminalNotChild } from './scalar-terminal.ts'
  * a successful match to the other engine.
  */
 import { FAIL, newEndCell, type EndCell } from './cell.ts'
+import { fieldSpec, leadingTriviaFieldAt } from './field-spec.ts'
+import { FIELD_LEADING_TRIVIA, FIELD_TRAILING_TRIVIA, LEAD, triviaFieldCapture } from '../combinators/field-trivia.ts'
 
 /**
  * DIAGNOSTIC ROW COUNTER — off unless `PM_TABLE_COUNT=1` at process start.
@@ -645,11 +647,21 @@ function makeDriver(
       }
 
       case OP_FIELD: {
+        const spec = fieldSpec(k[code[ip + 1]!])
+        const leadFrom = LEAD.at
+        if (spec.bits !== 0) LEAD.at = -1
         const v = exec(code[ip + 2]!, input, pos, ctx)
         if (v === FAIL) return FAIL
         // Conditional on a live sink, exactly as src/combinators/map.ts has it:
         // a `field()` outside any field-reading node costs nothing.
-        ctx._fields?.push({ name: k[code[ip + 1]!] as string, value: v, span: { start: pos, end: EC.e } })
+        if (spec.bits === 0) {
+          ctx._fields?.push({ name: spec.name, value: v, span: { start: pos, end: EC.e } })
+          return v
+        }
+        const end = EC.e
+        const trailEnd = (spec.bits & FIELD_TRAILING_TRIVIA) !== 0 && ctx.trivia !== undefined ? consumeTrivia(input, end, ctx) : end
+        ctx._fields?.push(triviaFieldCapture(spec.name, v, input, pos, end, (spec.bits & FIELD_LEADING_TRIVIA) !== 0 ? leadFrom : -1, trailEnd))
+        EC.e = trailEnd
         return v
       }
 
@@ -885,6 +897,7 @@ function makeDriver(
             const scanTl = need ? cstTlLen(ctx) : 0
             const scanLog = need ? ctx._triviaLog?.length ?? 0 : 0
             const scanRoot = need ? ctx._rootTriviaLog?.length ?? 0 : 0
+            if (leadingTriviaFieldAt(code, k, child)) LEAD.at = cur
             const v = exec(child, input, scanEnd, ctx)
             if (v === FAIL) { if (REC) ctx._sync = inheritedSync; return FAIL }
             if (EC.e > scanEnd) cur = EC.e
@@ -1256,6 +1269,7 @@ function makeDriver(
             let sp = cur
             if (hasTrivia) sp = skipTrivia(input, sp, ctx)
             ctx._fc = false
+            if (leadingTriviaFieldAt(code, k, sep)) LEAD.at = cur
             const sv = exec(sep, input, sp, ctx)
             if (sv === FAIL) {
               if (needMark) rollbackTriviaAt(ctx, mRaw, mTl, mLv, mFl, mEr, mLog, mRoot)

package/src/table/field-spec.ts

@@ -0,0 +1,17 @@
+import { OP_FIELD } from './ops.ts'
+import { FIELD_LEADING_TRIVIA } from '../combinators/field-trivia.ts'
+
+/**
+ * An `OP_FIELD` name slot: the name, or `[name, bits]` for a field that
+ * attributes trivia (`FIELD_LEADING_TRIVIA` / `FIELD_TRAILING_TRIVIA`). A
+ * program printed before those options existed carries only names, and reads
+ * as bits 0.
+ */
+export function fieldSpec(slot: unknown): { readonly name: string; readonly bits: number } {
+  return Array.isArray(slot) ? { name: slot[0] as string, bits: slot[1] as number } : { name: slot as string, bits: 0 }
+}
+
+/** Is the instruction at `ip` a `field(…, { leadingTrivia: true })`? */
+export function leadingTriviaFieldAt(code: ArrayLike<number>, k: readonly unknown[], ip: number): boolean {
+  return code[ip] === OP_FIELD && (fieldSpec(k[code[ip + 1]!]).bits & FIELD_LEADING_TRIVIA) !== 0
+}

package/src/table/scalar-terminal.ts

@@ -261,3 +261,28 @@ export function leadingLiteralFamily(
 
   return walk(ip, 0)
 }
+
+/**
+ * The literal terminals an arm of a LARGE ordered choice (more than three arms)
+ * may be pretested on before it is entered, or `undefined` when it has none.
+ *
+ * A pretest runs again when the arm then matches, so a large choice only takes
+ * literals of two or more characters: one `startsWith` is the price of skipping an
+ * arm that first-char dispatch could not exclude (`@{` and `@@` beside `@name`).
+ * A one-character literal is exactly what the dispatch mask already decided.
+ * The emitted and the closure engines both select through this function.
+ */
+export function largeChoiceLiteralPretest(
+  code: ArrayLike<number>, constants: readonly unknown[], armIp: number,
+): readonly number[] | undefined {
+  const child = leadingScalarTerminal(code, armIp, 2, true, true)
+  if (child >= 0) {
+    const spec = constants[code[child + 1]!]
+    if (code[child] === OP_LIT && typeof spec === 'string' && spec.length >= 2) return [child]
+  }
+  const family = leadingLiteralFamily(code, constants, armIp)
+  return family !== undefined && family.length >= 2 && family.every(terminal => {
+    const value = constants[code[terminal + 1]!]
+    return typeof value === 'string' && value.length >= 2
+  }) ? family : undefined
+}

package/src/types.ts

@@ -83,7 +83,7 @@ export type ParserDef =
   | { tag: 'routed';    fallback?: Combinator<unknown> }
   | { tag: 'leaf';      parser: Combinator<unknown>; fn: (v: unknown, span: { start: number; end: number }) => unknown; fnSrc?: string; cstValue?: 'source' }
   | { tag: 'label';     label: string; parser: Combinator<unknown> }
-  | { tag: 'field';     name: string; parser: Combinator<unknown> }
+  | { tag: 'field';     name: string; parser: Combinator<unknown>; leadingTrivia?: true; trailingTrivia?: true }
   | { tag: 'grammar';   parser: Combinator<unknown>; triviaParser: Combinator<unknown> | undefined; clearTrivia?: boolean; captureTrivia?: boolean; rootCapture?: 'opaque'; trackLines: boolean; constructionTrackLines?: 'on' | 'off' | 'inherit'; constructionCaptureTriviaKinds?: readonly string[] }
   | { tag: 'lazy';     thunk: () => Combinator<unknown> }
   | { tag: 'not';      parser: Combinator<unknown> }
@@ -203,6 +203,16 @@ export type BuildHost = ((
 export type FieldCapture<T = unknown> = {
   value: T
   span: Span
+  /**
+   * `field(…, { leadingTrivia: true })` only: the source text of the trivia the
+   * enclosing sequence or separated list skipped right before this field, or `''`.
+   */
+  leading?: string
+  /**
+   * `field(…, { trailingTrivia: true })` only: the source text of the trivia the
+   * field consumed after its match, or `''`.
+   */
+  trailing?: string
 }
 
 export type FieldMap = Record<string, FieldCapture | FieldCapture[]>
@@ -382,7 +392,7 @@ export type ParseContext = {
    */
   _cstTriviaLog?: number[] | undefined
   /** Framework-internal: active node() field captures, enabled only when needed. */
-  _fields?: Array<{ name: string; value: unknown; span: Span }> | undefined
+  _fields?: Array<{ name: string; value: unknown; span: Span; leading?: string; trailing?: string }> | undefined
   /** Framework-internal: lazy capture buffer for active node() parse. */
   _cstBuf?: CstCaptureBuf | undefined
   /** Framework-internal: value/span already consumed by an enclosing dispatch(). */

package/src/version.ts

@@ -13,4 +13,4 @@
  * Kept in sync with `package.json` by `test/unit/version-sync.test.ts`, which fails
  * the build if this constant drifts from the published version.
  */
-export const PARSEMAN_VERSION = '0.53.0'
+export const PARSEMAN_VERSION = '0.54.0'