parseman 0.53.0 → 0.55.0

package/src/cst/trivia-charscan.ts

@@ -226,74 +226,35 @@ function plainRegexSource(p: Combinator<unknown>): string | null {
   return d.tag === 'regex' && d.flags === '' ? d.source : null
 }
 
-let visitSpec0: LabeledTriviaSpec | undefined
-let visitSpec1: LabeledTriviaSpec | undefined
-let visitSpec2: LabeledTriviaSpec | undefined
-let visitSpec3: LabeledTriviaSpec | undefined
-let visitValue0: CssTriviaVisitor | null | undefined
-let visitValue1: CssTriviaVisitor | null | undefined
-let visitValue2: CssTriviaVisitor | null | undefined
-let visitValue3: CssTriviaVisitor | null | undefined
+/** The fields of a spec the char-level lowerings below are computed from. */
+type TriviaArmsSpec = Pick<LabeledTriviaSpec, 'arms' | 'minRepeats'>
 
-/** A direct classified scanner for the four canonical CSS/Less trivia tuples. */
-export function commonLabeledTriviaVisitor(spec: LabeledTriviaSpec): CssTriviaVisitor | null {
-  if (spec === visitSpec0) return visitValue0!
-  if (spec === visitSpec1) return visitValue1!
-  if (spec === visitSpec2) return visitValue2!
-  if (spec === visitSpec3) return visitValue3!
-  const sources = spec.minRepeats <= 1 ? spec.arms.map(arm => plainRegexSource(arm.parser)) : []
-  const visitor = commonCssTriviaVisitor(sources)
-  visitSpec3 = visitSpec2
-  visitValue3 = visitValue2
-  visitSpec2 = visitSpec1
-  visitValue2 = visitValue1
-  visitSpec1 = visitSpec0
-  visitValue1 = visitValue0
-  visitSpec0 = spec
-  visitValue0 = visitor
-  return visitor
+/**
+ * A direct classified scanner for the four canonical CSS/Less trivia tuples.
+ * Computed once per spec, by `analyzeLabeledTrivia`, and read off it as
+ * `spec.visitor`: a scan never asks again.
+ */
+export function commonLabeledTriviaVisitor(spec: TriviaArmsSpec): CssTriviaVisitor | null {
+  return commonCssTriviaVisitor(spec.minRepeats <= 1 ? spec.arms.map(arm => plainRegexSource(arm.parser)) : [])
 }
 
-let armSpec0: LabeledTriviaSpec | undefined
-let armSpec1: LabeledTriviaSpec | undefined
-let armSpec2: LabeledTriviaSpec | undefined
-let armSpec3: LabeledTriviaSpec | undefined
-let armValue0: readonly TriviaArmMatcher[] | null | undefined
-let armValue1: readonly TriviaArmMatcher[] | null | undefined
-let armValue2: readonly TriviaArmMatcher[] | null | undefined
-let armValue3: readonly TriviaArmMatcher[] | null | undefined
-
 /**
  * The character-level matchers for a spec's arms — index-parallel to `spec.arms`,
  * so a matcher's index IS its kind index — or `null` when any arm has no lowering.
+ * Computed once per spec, as `spec.charArms`.
  *
  * `spec.minRepeats > 1` is excluded: the loops below report only an END, and a run
  * that fails a minimum of two must report NOTHING. `classifiedTrivia()` never
  * produces one, and the combinator path still handles it if a host writes one.
  */
-export function charArmsFor(spec: LabeledTriviaSpec): readonly TriviaArmMatcher[] | null {
-  if (spec === armSpec0) return armValue0!
-  if (spec === armSpec1) return armValue1!
-  if (spec === armSpec2) return armValue2!
-  if (spec === armSpec3) return armValue3!
-  let arms: TriviaArmMatcher[] | null = []
-  if (spec.minRepeats > 1) {
-    arms = null
-  } else {
-    for (const arm of spec.arms) {
-      const c = classifyParser(arm.parser)
-      if (!c) { arms = null; break }
-      arms.push(c)
-    }
+export function charArmsFor(spec: TriviaArmsSpec): readonly TriviaArmMatcher[] | null {
+  if (spec.minRepeats > 1) return null
+  const arms: TriviaArmMatcher[] = []
+  for (const arm of spec.arms) {
+    const c = classifyParser(arm.parser)
+    if (!c) return null
+    arms.push(c)
   }
-  armSpec3 = armSpec2
-  armValue3 = armValue2
-  armSpec2 = armSpec1
-  armValue2 = armValue1
-  armSpec1 = armSpec0
-  armValue1 = armValue0
-  armSpec0 = spec
-  armValue0 = arms
   return arms
 }
 

package/src/cst/trivia-kinds.ts

@@ -2,7 +2,10 @@ import type { Combinator, ParseContext } from '../types.ts'
 import { pushCstTriviaEntry, pushTriviaLogEntry } from './capture-buffer.ts'
 import { startsFirstSet } from '../combinators/first-set.ts'
 import { createDetachedParseContext } from '../parse-context.ts'
-import { charArmsFor, charTriviaEnd, charTriviaKindMask, charTriviaVisit, commonLabeledTriviaVisitor } from './trivia-charscan.ts'
+import {
+  charArmsFor, charTriviaEnd, charTriviaKindMask, charTriviaVisit, commonLabeledTriviaVisitor, type TriviaArmMatcher,
+} from './trivia-charscan.ts'
+import type { CssTriviaVisitor } from './trivia-css-scanner.ts'
 
 export type TriviaChunk = { start: number; end: number; kindIndex: number }
 
@@ -10,6 +13,13 @@ export type LabeledTriviaSpec = {
   readonly labels: readonly string[]
   readonly arms: ReadonlyArray<{ label: string; kindIndex: number; parser: Combinator<unknown> }>
   readonly minRepeats: number
+  /**
+   * The spec's char-level scanners, built with it. A scan reads them here: the
+   * four-slot memo they used to sit behind thrashed on a grammar with more trivia
+   * tables than slots, and rebuilt one on every miss.
+   */
+  readonly visitor: CssTriviaVisitor | null
+  readonly charArms: readonly TriviaArmMatcher[] | null
 }
 
 /** See `trivia-skip.ts`: bounded scalar memoisation avoids a WeakMap in the
@@ -93,12 +103,18 @@ export function analyzeLabeledTrivia(trivia: Combinator<unknown>): LabeledTrivia
     arms.push({ label: peeled.label, kindIndex: 0, parser: peeled.parser })
   }
 
-  const spec = {
+  return cacheLabeledTrivia(trivia, labeledTriviaSpec(arms, minRepeats))
+}
+
+/** A spec, with the char-level scanners every scan of it reads. */
+export function labeledTriviaSpec(arms: LabeledTriviaSpec['arms'], minRepeats: number): LabeledTriviaSpec {
+  return {
     labels: arms.map(a => a.label),
     arms,
     minRepeats,
+    visitor: commonLabeledTriviaVisitor({ arms, minRepeats }),
+    charArms: charArmsFor({ arms, minRepeats }),
   }
-  return cacheLabeledTrivia(trivia, spec)
 }
 
 /** Label table on a `trivia()` combinator, if all arms are labeled. */
@@ -169,9 +185,9 @@ export function scanLabeledTriviaEnd(
   spec: LabeledTriviaSpec,
   state?: unknown,
 ): number {
-  // `charArmsFor` only lowers `minRepeats <= 1`, where "no chunk matched" and
+  // `charArms` only lowers `minRepeats <= 1`, where "no chunk matched" and
   // "the minimum was not met" are the same position — so an end IS the answer.
-  const chars = charArmsFor(spec)
+  const chars = spec.charArms
   if (chars !== null) return charTriviaEnd(input, cur, chars)
 
   let pos = cur
@@ -205,9 +221,9 @@ export function visitLabeledTrivia(
   visit: (start: number, end: number, kindIndex: number) => void,
 ): number | undefined {
   if (spec.minRepeats > 1) return undefined
-  const common = commonLabeledTriviaVisitor(spec)
+  const common = spec.visitor
   if (common !== null) return common(input, cur, visit)
-  const chars = charArmsFor(spec)
+  const chars = spec.charArms
   if (chars !== null) return charTriviaVisit(input, cur, chars, visit)
 
   let pos = cur
@@ -331,7 +347,7 @@ export function triviaKindMaskAt(
   spec: LabeledTriviaSpec,
   state?: unknown,
 ): number {
-  const chars = charArmsFor(spec)
+  const chars = spec.charArms
   if (chars !== null) return charTriviaKindMask(input, pos, chars)
 
   let cur = pos

package/src/index.ts

@@ -30,6 +30,7 @@ export { node } from './combinators/node.ts'
 export type { BuildNode, NodeCombinator, NodeOptions, NodeProjectOptions } from './combinators/node.ts'
 // lazy() is intentionally NOT exported.
 export { transform, trivia, classifiedTrivia, label, field } from './combinators/map.ts'
+export type { FieldOptions } from './combinators/map.ts'
 export { parse, parser, noTrivia } from './combinators/grammar.ts'
 export type { ParseOptions, ParserOptions, ParsemanParser } from './combinators/grammar.ts'
 export { token, leaf, sourceLeaf } from './combinators/token.ts'

package/src/plugin/evaluator.ts

@@ -96,6 +96,9 @@ function stripTsFromSource(node: Node, code: string): string {
 class UnevaluatedExtra {}
 const UNEVALUATED_EXTRA: unknown = new UnevaluatedExtra()
 
+/** The stand-in for a derive-form `withCtx(s => next, …)`; see the `withCtx` case. */
+const DERIVE_STAND_IN = (state: unknown): unknown => state
+
 // ---------------------------------------------------------------------------
 // Reducer resolution
 //
@@ -314,7 +317,7 @@ const SUPPORTED: Record<string, (...args: unknown[]) => Combinator<unknown>> = {
       a[0] as Readonly<Record<string, Combinator<unknown>>>,
     ),
   label:     (...a) => parseman.label(a[0] as string, a[1] as Combinator<unknown>),
-  field:     (...a) => parseman.field(a[0] as string, a[1] as Combinator<unknown>),
+  field:     (...a) => parseman.field(a[0] as string, a[1] as Combinator<unknown>, a[2] as parseman.FieldOptions | undefined),
   noTrivia:  (...a) => parseman.noTrivia(a[0] as Combinator<unknown>),
   token:     (...a) => parseman.token(a[0] as Combinator<unknown>),
   // `routed(fallback)` — the fallback must be forwarded. A zero-arg entry here read
@@ -1028,10 +1031,17 @@ function exprToCombi(node: Expression, scope: XScope, code?: string, mfs?: strin
       // survives only when it cannot be evaluated, and then it is `emittableConst`
       // that decides — a plain `{}` extras object is indistinguishable from an
       // author's `{}`, so an unevaluable one must NOT masquerade as empty state.
-      const evaluated = anyValue(extraArg as Expression, scope, code, [])
+      //
+      // A function literal is the DERIVE form, `withCtx(s => next, inner)`. Its
+      // value is never needed here — the encoder prints `extraSrc` into the
+      // artifact — but the def must hold a FUNCTION so the encoder lowers the
+      // derive form at all; the stand-in is that function, like `gate`'s.
+      const extraType = (unwrapStaticExpr(extraArg as Expression) as { type: string }).type
+      const derives = extraType === 'ArrowFunctionExpression' || extraType === 'FunctionExpression'
+      const evaluated = derives ? null : anyValue(extraArg as Expression, scope, code, [])
       const usable = typeof evaluated === 'object' && evaluated !== null && !Array.isArray(evaluated)
         && Object.getPrototypeOf(evaluated) === Object.prototype
-      const combi = parseman.withCtx(usable ? evaluated : UNEVALUATED_EXTRA, inner)
+      const combi = parseman.withCtx(derives ? DERIVE_STAND_IN : usable ? evaluated : UNEVALUATED_EXTRA, inner)
       if (combi._def.tag !== 'withCtx') return null
       combi._def.extraSrc = extraSrc
       return combi

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
         }
       }
@@ -1835,8 +1861,18 @@ export function assemble(t: ResolvedTable, prog: TableProgram, cfg: RunCfg): Ass
 
       case OP_WITHCTX: {
         // `extra` and the child are both bound HERE; the piece only swaps a field.
-        const extra = k[code[ip + 1]!]
+        const ki = code[ip + 1]!
         const child = link(code[ip + 2]!)
+        if (ki < 0) {
+          const derive = fns[~ki] as (s: unknown) => unknown
+          return (input, pos, ctx) => {
+            const saved = ctx.state
+            ctx.state = derive(saved)
+            try { return child(input, pos, ctx) }
+            finally { ctx.state = saved }
+          }
+        }
+        const extra = k[ki]
         return (input, pos, ctx) => {
           const saved = ctx.state
           ctx.state = extra
@@ -2322,6 +2358,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 +2431,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 +2841,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 +3008,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 +3200,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 +3285,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 +3386,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 +3810,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 +3860,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 +3942,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 +4162,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 +4178,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 +4215,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 +4238,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