parseman 0.55.4 → 0.57.0

package/src/combinators/lines.ts

@@ -0,0 +1,244 @@
+import type { Combinator, ParseContext, ParseResult, ParserMeta } from '../types.ts'
+import { any, matchesEmpty } from './first-set.ts'
+import { createDetachedParseContext } from '../parse-context.ts'
+import { recordLineRangeFromContext } from '../line-index.ts'
+import { failAt } from './probe.ts'
+
+/**
+ * One line of a run that `lines()` hands its body.
+ *
+ * The body parses the run's lines with their prefixes removed and joined by
+ * `\n`. Each entry says where a line's content sits in that text (`offset`) and
+ * in the run's own input (`source`), where its column count starts, and whether
+ * it joined the run through `lazy`.
+ */
+export type RunLine = {
+  /** Where the line's content starts in the body's input. */
+  readonly offset: number
+  /** Where the same content starts in the run's input. */
+  readonly source: number
+  /** Where the line ends in the run's input, before its newline. */
+  readonly end: number
+  /**
+   * The column at `source`: tab stops every four columns, counted from the
+   * start of the outermost input's line, through every enclosing run.
+   */
+  readonly column: number
+  /**
+   * Columns of the character at `source` that a prefix already took. A
+   * `columns(n)` prefix that ends inside a tab leaves the tab in the content and
+   * records the columns it took here, so the content keeps the tab's remainder.
+   */
+  readonly split: number
+  /** The line joined through `lazy`, with nothing removed. */
+  readonly lazy: boolean
+}
+
+/** The lines of the run whose body is parsing, and the run enclosing it. */
+export type LineView = {
+  readonly lines: readonly RunLine[]
+  readonly parent: LineView | undefined
+}
+
+export type LinesOptions = {
+  /** The prefix of the run's first line, when it differs from the others' (a list item's marker). */
+  first?: Combinator<unknown>
+  /**
+   * A line the prefix does not match continues the run, whole, when `lazy`
+   * matches at its start: Markdown's lazy continuation lines. Only the match
+   * counts; what `lazy` consumes is not removed.
+   */
+  lazy?: Combinator<unknown>
+}
+
+type LinesContext = ParseContext
+
+/** The index of the run line holding `offset` of the body's input, by binary search. */
+function lineIndexAt(view: LineView, offset: number): number {
+  const lines = view.lines
+  let lo = 0, hi = lines.length - 1
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1
+    if (lines[mid]!.offset <= offset) lo = mid
+    else hi = mid - 1
+  }
+  return lo
+}
+const lineAt = (view: LineView, offset: number): RunLine | undefined => view.lines[lineIndexAt(view, offset)]
+
+/** Map an offset in a run body's input to the offset in the run's own input. */
+export function sourceOffset(view: LineView, offset: number): number {
+  const line = lineAt(view, offset)
+  return line === undefined ? offset : line.source + (offset - line.offset)
+}
+
+/**
+ * The column at `pos` and the columns of the character there already taken,
+ * counting from the line start of the current input, or, inside a run's body,
+ * from that run's line, whose column and split the enclosing runs supply.
+ */
+function columnAt(input: string, pos: number, ctx: LinesContext): { column: number; split: number } {
+  const view = ctx.lineView
+  let start: number, column: number, split: number
+  const line = view === undefined ? undefined : lineAt(view, pos)
+  if (line !== undefined && pos >= line.offset) { start = line.offset; column = line.column; split = line.split }
+  else { start = input.lastIndexOf('\n', pos - 1) + 1; column = 0; split = 0 }
+  for (let i = start; i < pos; i++) {
+    if (input.charCodeAt(i) === 0x09) {
+      // A tab reaches the next stop; one the prefix split has fewer columns left.
+      const width = 4 - (column - (i === start ? split : 0)) % 4 - (i === start ? split : 0)
+      column += width
+    } else column++
+    split = 0
+  }
+  return { column, split: pos === start ? split : 0 }
+}
+
+/**
+ * `n` columns of indentation: spaces and tabs, a tab reaching the next stop of
+ * four columns. When the `n`th column falls inside a tab, the match stops before
+ * that tab, and a `lines()` prefix ending there leaves the tab's remaining
+ * columns in the content (`RunLine.split`). Fails when the indentation is
+ * narrower than `n`.
+ */
+export function columns(n: number): Combinator<string> {
+  if (!Number.isInteger(n) || n < 0) throw new TypeError(`columns(n) needs a non-negative integer, got ${n}`)
+  const expected = [`columns(${n})`]
+  const meta: ParserMeta = {
+    firstSet: n === 0 ? any() : { kind: 'ranges', ranges: [{ lo: 0x09, hi: 0x09 }, { lo: 0x20, hi: 0x20 }] },
+    canMatchNewline: false,
+    isTrivia: false,
+  }
+  return {
+    _tag: 'columns',
+    _meta: meta,
+    _def: { tag: 'columns', n },
+    parse(input: string, pos: number, ctx: ParseContext): ParseResult<string> {
+      const c = ctx as LinesContext
+      let { column, split } = columnAt(input, pos, c)
+      const goal = column + n
+      let at = pos
+      while (column < goal) {
+        const code = input.charCodeAt(at)
+        if (code === 0x20) { column++; split = 0; at++; continue }
+        if (code !== 0x09) return { ok: false, expected, span: { start: at, end: at } }
+        const width = 4 - (column - split) % 4 - split
+        if (column + width > goal) {
+          // The goal falls inside this tab: stop before it, and say how much of it is taken.
+          c._columnsSplit = { at, split: split + (goal - column) }
+          return { ok: true, value: input.slice(pos, at), span: { start: pos, end: at } }
+        }
+        column += width; split = 0; at++
+      }
+      return { ok: true, value: input.slice(pos, at), span: { start: pos, end: at } }
+    },
+  }
+}
+
+/**
+ * Parse `body` over a run of lines with a prefix removed from each.
+ *
+ * The run starts at `pos`, where `first` (default `prefix`) must match. Each
+ * following line joins while `prefix` matches at its start, or, failing that,
+ * while `lazy` does; the run ends at the first line that joins neither way or
+ * at the end of the input. A prefix never reaches past its own line.
+ *
+ * `body` parses the lines' contents joined by `\n`, starting at 0. While it
+ * runs, `ctx.lineView` describes the lines (`RunLine`), so nested `columns()`
+ * and `lines()` count tab stops from the right column. The result spans from
+ * `pos` to where the body stopped, mapped back to this input: a body that
+ * consumes a whole line ends at the next line's start, so lines it leaves, and
+ * the rest of a line where it stops partway, are the enclosing grammar's. Spans inside the body's value and its CST are offsets in the
+ * body's input; `sourceOffset(view, offset)` maps them back. Recovered errors
+ * the body records are mapped back to this input, line tracking records the
+ * run's lines in this input, and a completion probe at a cursor inside a
+ * line's content sees what the body expects there.
+ *
+ * The run is read before the body runs, so a body that leaves most of its run
+ * makes a repeated run reread the lines it left: a body reads its run to the end.
+ */
+export function lines<T>(prefix: Combinator<unknown>, body: Combinator<T>, options: LinesOptions = {}): Combinator<T> {
+  const { first, lazy } = options
+  const opening = first ?? prefix
+  const meta: ParserMeta = {
+    // An opening that matches empty starts a run at any character.
+    firstSet: matchesEmpty(opening) ? any() : opening._meta.firstSet,
+    canMatchNewline: true,
+    isTrivia: false,
+  }
+  return {
+    _tag: 'lines',
+    _meta: meta,
+    _def: { tag: 'lines', prefix, body: body as Combinator<unknown>, ...(first === undefined ? {} : { first }), ...(lazy === undefined ? {} : { lazy }) },
+    parse(input: string, pos: number, ctx: ParseContext): ParseResult<T> {
+      const c = ctx as LinesContext
+      // Prefixes and lazy checks are probes: they run detached, so they leave
+      // no leaves, trivia or errors in the parse that encloses the run.
+      const probe = createDetachedParseContext(false, ctx.state) as LinesContext
+      probe.lineView = c.lineView
+      const run: RunLine[] = []
+      const parts: string[] = []
+      let offset = 0
+      for (let start = pos; start < input.length || start === pos;) {
+        let end = input.indexOf('\n', start)
+        if (end < 0) end = input.length
+        probe._columnsSplit = undefined
+        const head = (run.length === 0 ? opening : prefix).parse(input, start, probe)
+        let content: number
+        let joined: 'prefix' | 'lazy' | undefined
+        if (head.ok && head.span.end <= end) { content = head.span.end; joined = 'prefix' }
+        else if (run.length === 0) {
+          // A prefix is a probe: its failure is the run's, never a commitment.
+          return { ok: false, expected: head.ok ? ['line prefix'] : head.expected, span: { start, end: start } }
+        } else if (lazy !== undefined && lazy.parse(input, start, probe).ok) { content = start; joined = 'lazy' }
+        else break
+        const mark = probe._columnsSplit as { at: number; split: number } | undefined
+        const here = columnAt(input, content, c)
+        const split = joined === 'prefix' && mark !== undefined && mark.at === content ? mark.split : here.split
+        run.push({ offset, source: content, end, column: here.column + (split - here.split), split, lazy: joined === 'lazy' })
+        const text = input.slice(content, end)
+        const newline = end < input.length
+        parts.push(newline ? `${text}\n` : text)
+        offset += text.length + (newline ? 1 : 0)
+        start = end + 1
+        if (!newline) break
+      }
+      const view: LineView = { lines: run, parent: c.lineView }
+      // The body parses another string: what records positions in this input
+      // (the line index, the completion probe) stays out of its way. A probe
+      // whose cursor lies in a line's content gets its own, at the body's offset.
+      const saved = c.lineView, starts = c._lineStarts, lineIndex = c._lineIndex, scanned = c._lineScannedTo, probing = c._probe
+      const errors = c._errors?.length ?? 0
+      let cursor = -1
+      if (probing !== undefined) for (const line of run) {
+        if (probing.offset >= line.source && probing.offset <= line.end) { cursor = line.offset + probing.offset - line.source; break }
+      }
+      const inner: ParseContext['_probe'] = cursor < 0 ? undefined : { offset: cursor, best: null }
+      c.lineView = view; c._lineStarts = undefined; c._lineIndex = undefined; c._lineScannedTo = undefined; c._probe = inner
+      let result: ParseResult<T>
+      try { result = body.parse(parts.join(''), 0, ctx) }
+      finally { c.lineView = saved; c._lineStarts = starts; c._lineIndex = lineIndex; c._lineScannedTo = scanned; c._probe = probing }
+      // The body's deepest failure at the cursor counts where it is in this input.
+      if (inner?.best) failAt(c, inner.best.expected, sourceOffset(view, inner.best.span.start))
+      // Errors the body recovered from move to where they are in this input.
+      if (c._errors !== undefined) for (let i = errors; i < c._errors.length; i++) {
+        const error = c._errors[i] as { span: { start: number; end: number } }
+        error.span = { start: sourceOffset(view, error.span.start), end: sourceOffset(view, error.span.end) }
+      }
+      if (!result.ok) {
+        const at = sourceOffset(view, result.span.start)
+        return { ...result, span: { start: at, end: at } }
+      }
+      // The body's end maps to the end of its line: a body that consumed a
+      // whole line, newline included, ends at the next line's start.
+      const stop = result.span.end
+      const index = lineIndexAt(view, stop)
+      const line = run[index]!
+      const end = stop === line.offset && index > 0 ? run[index - 1]!.end + 1
+        : stop - line.offset > line.end - line.source ? line.end + 1
+        : line.source + (stop - line.offset)
+      recordLineRangeFromContext(c, input, pos, end)
+      return { ok: true, value: result.value, span: { start: pos, end } }
+    },
+  }
+}

package/src/combinators/node.ts

@@ -83,7 +83,7 @@ export type NodeOptions<Tags extends readonly string[] = readonly never[]> = {
    * cannot read.
    *
    * Arity gates five capture tiers (`>= 1` children, `>= 2` fields, `>= 4` rawChildren,
-   * `>= 5` triviaLog, `>= 6` a clone of `_ctx.state`), and parseman normally derives it
+   * `>= 5` triviaLog, `>= 6` `_ctx.state`), and parseman normally derives it
    * from the reducer's declaration — including across module boundaries. A few shapes
    * are genuinely undecidable: a rest parameter (`...args`), a body that reads
    * `arguments`, a reassigned or dynamically constructed reducer. Those fail OPEN, which
@@ -208,7 +208,7 @@ export function node<N>(
     : baseDef
   // Arity-gated elision — decided once, identically to the compiler (build-arity.ts).
   // When the build never reads the trivia (4th) arg, disable per-node CST-trivia
-  // capture for the inner scope; when it never reads state (5th), skip the state clone.
+  // capture for the inner scope; when it never reads state (6th), it is handed none.
   // A STRUCTURAL node (no own build) defers to `ctx.build` / a default CST, which
   // may read either, so capture both.
   // These are the DIRECT builder's own needs, and they are not the whole story. A node
@@ -228,7 +228,7 @@ export function node<N>(
   // or without a node log. Forcing capture for it handed a three-argument reducer
   // a log it never reads, at the price of the full capture frame on every match.
   const capturesTrivia = captureTrivia || (build ? buildReadsTrivia(def) : project === undefined)
-  const clonesState = build ? buildReadsState(def) : project === undefined
+  const readsState = build ? buildReadsState(def) : project === undefined
   const hasOwnFields = parserHasOwnFields(combinator)
   const capturesFields = hasOwnFields && (build ? buildReadsFields(def) : project === undefined)
   // First-set fail-fast (mirrors emitNode's codegen guard): a node whose body can't
@@ -298,17 +298,10 @@ export function node<N>(
       if (!r.ok) return r
 
       // unwrap/collapse: a single captured child IS the value — skip build.
-      const st = clonesState && ctx.state !== undefined ? Object.assign({}, ctx.state as Record<string, unknown>) : undefined
+      const st = readsState ? ctx.state : undefined
       const nodeType = def.type ?? missingInferredType()
       const cstOutput = cstOutputHost(ctx.build)
       const span = ctx.trackLines ? annotateSpanFromLineContext(r.span, ctx) : r.span
-      // A direct builder that never declared `state` still owes the host its snapshot.
-      // The clone happens AFTER the body, so unlike trivia it needs no gate up front —
-      // build it here, on a branch the eval-AST path never takes. Matches what
-      // `hostMode: 'cst'` does in the compiled engine.
-      const hostState = clonesState
-        ? st
-        : ctx.state !== undefined ? Object.assign({}, ctx.state as Record<string, unknown>) : undefined
       const built: unknown = unwrap && children.length === 1
         ? unwrapChild(children[0])
         : collapse && children.length === 1
@@ -326,14 +319,14 @@ export function node<N>(
           ? children[0]
         : project !== undefined
           ? cstOutput && ctx.build
-            ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, hostState, tags)
+            ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, ctx.state, tags)
             : projectChild(children, project, nodeType)
         : build
           // A direct builder normally owns its result. The positioned-CST host is
           // the one exception: it must never receive an arbitrary AST object as a
           // child of a CST node, so build this grammar node through that host.
           ? cstOutput && ctx.build
-            ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, hostState, tags)
+            ? ctx.build(nodeType, children, fields, span, rawChildren, triviaLog, ctx.state, tags)
             : build(children, fields, span, rawChildren, triviaLog, st)
           // Structural node: a `ctx.build` host if present, else a default CST.
           : ctx.build

package/src/combinators/trivia-skip.ts

@@ -188,15 +188,17 @@ function parseTriviaNoCapture(
  * `peek(sequence(literal('a'), literal('zzz')))` over `"ab"` offered `"zzz"` as
  * the ONLY completion, though no input can ever reach it there.
  */
-export type LookaheadMark = TriviaRollbackMark & { probeBest: ParseFail | null }
+export type LookaheadMark = TriviaRollbackMark & { probeBest: ParseFail | null; split: ParseContext['_columnsSplit'] }
 
 export function saveLookaheadMark(ctx: ParseContext): LookaheadMark {
-  return { ...saveTriviaMark(ctx), probeBest: ctx._probe ? ctx._probe.best : null }
+  return { ...saveTriviaMark(ctx), probeBest: ctx._probe ? ctx._probe.best : null, split: ctx._columnsSplit }
 }
 
 export function rollbackLookahead(ctx: ParseContext, mark: LookaheadMark): void {
   rollbackTrivia(ctx, mark)
   if (ctx._probe) ctx._probe.best = mark.probeBest
+  // A lookahead takes no columns of a tab: `lines()` reads `columns()`'s split mark.
+  ctx._columnsSplit = mark.split
 }
 
 function scanWithLabels(input: string, cur: number, ctx: ParseContext): CompactTriviaScan {
@@ -568,11 +570,54 @@ function regexTriviaScanner(parser: Combinator<unknown>): FastTriviaScanner | nu
   // and every trivia gap in every dialect went through the labelled char scanner.
   const d = parser._def.tag === 'label' ? parser._def.parser._def : parser._def
   if (d.tag !== 'regex' || d.flags) return null
-  const source = d.source
+  return sourceScanner(d.source)
+}
+
+function sourceScanner(source: string): FastTriviaScanner | null {
   return classRunSource(source)
     ?? altStarSource(source)
     ?? prefixRunSource(source)
     ?? delimitedSource(source)
+    ?? sharedPrefixAltSource(source)
+}
+
+/**
+ * `<literal>(?:<alt>|<alt>…)`: a literal every alternative shares, as in jess's
+ * one comment arm `\/(?:\*(?:[^*]|\*(?!\/))*\*\/|\/[^\n\r]*)` for both `/*…*\/`
+ * and `//…`. Each `<literal><alt>` is lowered on its own, and the scanner takes
+ * the first that matches, as the regex does. Without it that arm had no
+ * scanner, so neither did the trivia it sits in.
+ */
+function sharedPrefixAltSource(source: string): FastTriviaScanner | null {
+  const m = /^((?:\\.|[^\\[\]()*+?|^$.{}])+)\(\?:(.*)\)$/.exec(source)
+  if (!m) return null
+  const alts: string[] = []
+  const body = m[2]!
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i]
+    if (c === '\\') { i++; continue }
+    if (c === '[') { while (i < body.length && body[i] !== ']') i += body[i] === '\\' ? 2 : 1; continue }
+    if (c === '(') depth++
+    else if (c === ')' && --depth < 0) return null
+    else if (c === '|' && depth === 0) { alts.push(body.slice(start, i)); start = i + 1 }
+  }
+  if (depth !== 0 || alts.length === 0) return null
+  alts.push(body.slice(start))
+  const scanners: FastTriviaScanner[] = []
+  for (const alt of alts) {
+    const scanner = sourceScanner(m[1]! + alt)
+    if (scanner === null) return null
+    scanners.push(scanner)
+  }
+  return (input, cur) => {
+    for (const scanner of scanners) {
+      const end = scanner(input, cur)
+      if (end > cur) return end
+    }
+    return cur
+  }
 }
 
 /**

package/src/compiler/build-arity.ts

@@ -338,7 +338,7 @@ export function confirmedArityForDef(def: NodeDef): number | null {
     where: `node("${def.type ?? '<inferred>'}")`,
     subject,
     fellBackTo: `could not confirm its declared arity — ${unconfirmableReason(def, src)} — `
-      + 'so this node captures children, fields and raw children, logs trivia, and clones `_ctx.state` on every match',
+      + 'so this node captures children, fields and raw children, logs trivia, and hands it `_ctx.state` on every match',
     otherwise: 'only the tiers the reducer actually declares would be captured '
       + '(arity >= 1 children, >= 2 fields, >= 4 raw, >= 5 trivia, >= 6 state). '
       + 'Declare it with `node(..., { buildArity: n })` if it cannot be derived',
@@ -371,9 +371,9 @@ export function buildReadsTrivia(def: NodeDef): boolean {
   return arity >= 5
 }
 
-/** Build reads the 6th (state) arg? Unknown/unparseable → true (keep state clone). */
+/** Build reads the 6th (state) arg? Unknown/unparseable → true (hand it the state). */
 export function buildReadsState(def: NodeDef): boolean {
-  if (!def.build) return true // structural node: host may read state — keep clone
+  if (!def.build) return true // structural node: host may read state
   const arity = confirmedArityForDef(def)
   if (arity === null) return true
   return arity >= 6

package/src/compiler/fields.ts

@@ -30,6 +30,7 @@ export function parserHasOwnFields(p: Combinator<unknown>, seen: Set<Combinator<
       || (d.recoverAt !== undefined && parserHasOwnFields(d.recoverAt, seen))
       || (d.stopAt !== undefined && parserHasOwnFields(d.stopAt, seen))
     case 'recover': return parserHasOwnFields(d.parser, seen) || parserHasOwnFields(d.sentinel, seen)
+    case 'lines': return parserHasOwnFields(d.body, seen)
     case 'routed': return d.fallback ? parserHasOwnFields(d.fallback, seen) : false
     case 'many':
     case 'oneOrMore':
@@ -98,6 +99,7 @@ function hasTriviaSite(p: Combinator<unknown>, seen: Set<Combinator<unknown>>, t
     case 'sepBy':
     case 'scanTo':
     case 'recover':
+    case 'lines':
       return true
     // Nested node manages its own trivia frame; none logs into THIS frame. The
     // root log has no frames, so it must look inside.
@@ -159,6 +161,7 @@ export function parserEnablesTriviaCapture(p: Combinator<unknown>, seen: Set<Com
       || (d.recoverAt !== undefined && parserEnablesTriviaCapture(d.recoverAt, seen))
       || (d.stopAt !== undefined && parserEnablesTriviaCapture(d.stopAt, seen))
     case 'recover': return parserEnablesTriviaCapture(d.parser, seen) || parserEnablesTriviaCapture(d.sentinel, seen)
+    case 'lines': return parserEnablesTriviaCapture(d.body, seen)
     case 'routed': return d.fallback ? parserEnablesTriviaCapture(d.fallback, seen) : false
     case 'many':
     case 'oneOrMore':

package/src/compiler/grammar-coverage-ids.ts

@@ -39,6 +39,7 @@ function children(def: ParserDef, winners?: Record<string, Combinator<unknown>>)
       ...(def.recoverAt === undefined ? [] : [def.recoverAt]),
       ...(def.stopAt === undefined ? [] : [def.stopAt]),
     ]
+    case 'lines': return [def.prefix, def.body, ...(def.first === undefined ? [] : [def.first]), ...(def.lazy === undefined ? [] : [def.lazy])]
     case 'lazy': {
       let resolved: Combinator<unknown>
       try { resolved = def.thunk() } catch (e) {

package/src/compiler/ir-serialize.ts

@@ -72,6 +72,8 @@ function childrenOf(def: ParserDef): Comb[] {
       ...(def.stopAt === undefined ? [] : [def.stopAt]),
     ]
     case 'routed':    return def.fallback ? [def.fallback] : []
+    case 'lines':     return [def.prefix, def.body, ...(def.first === undefined ? [] : [def.first]), ...(def.lazy === undefined ? [] : [def.lazy])]
+    case 'columns':
     case 'lazy':
     case 'literal':
     case 'regex':
@@ -488,6 +490,14 @@ class Serializer {
       case 'expect':    return `expect(${kid(def.parser)}${def.label !== undefined ? `, ${JSON.stringify(def.label)}` : ''})`
       case 'scanTo':
         return `scanTo(${kid(def.sentinel)}, { skip: [${def.skip.map(kid).join(', ')}]${def.raw ? ', raw: true' : ''}, orEOF: ${def.orEOF}${def.recoverAt === undefined ? '' : `, recoverAt: ${kid(def.recoverAt)}`}${def.stopAt === undefined ? '' : `, stopAt: ${kid(def.stopAt)}`} })`
+      case 'lines': {
+        const options = [
+          ...(def.first === undefined ? [] : [`first: ${kid(def.first)}`]),
+          ...(def.lazy === undefined ? [] : [`lazy: ${kid(def.lazy)}`]),
+        ]
+        return `lines(${kid(def.prefix)}, ${kid(def.body)}${options.length === 0 ? '' : `, { ${options.join(', ')} }`})`
+      }
+      case 'columns':   return `columns(${def.n})`
       case 'transform': {
         if (def.fnSrc === undefined) throw new Unserializable('transform without fnSrc')
         // `_tf` sets `_def.fnSrc` so re-lowering INLINES the callback (a plain

package/src/compiler/token-alphabet.ts

@@ -1698,6 +1698,8 @@ function normalizeLexicalBody(
     case 'adjacency': return done({ refusal: 'adjacency depends on parser state' })
     case 'recover': return done({ refusal: 'recover is effectful' })
     case 'scanTo': return done({ refusal: 'scanTo is not a lexical run' })
+    case 'lines': return done({ refusal: 'lines removes prefixes from its input' })
+    case 'columns': return done({ refusal: 'columns counts tab stops' })
     case 'sepBy': return done({ refusal: 'separated repetition is not a lexical run' })
     case 'dispatch': return done({ refusal: 'nested dispatch has semantic outcomes' })
     case 'routed': return done({ refusal: 'routed depends on an outer dispatch' })
@@ -2026,7 +2028,7 @@ function decisionLead(
       return finish({ gap: 'repeated or nullable leading language needs a range-partition proof' })
     case 'peek': return finish({ gap: 'positive lookahead needs an exact effect-free compatible view' })
     case 'not': return finish({ gap: 'negative lookahead needs a decidable complement' })
-    case 'withCtx': case 'guard': case 'adjacency': case 'recover': case 'scanTo': case 'routed': case 'unknown':
+    case 'withCtx': case 'guard': case 'adjacency': case 'recover': case 'scanTo': case 'routed': case 'unknown': case 'lines': case 'columns':
       return finish({ gap: `leading ${def.tag} language is not represented` })
     case 'literal': case 'keywords': case 'regex':
       throw new Error('parseman: decision lead terminal escaped its direct case')

package/src/coverage.ts

@@ -1,3 +1,4 @@
+import { lines } from './combinators/lines.ts'
 import { run, type RunOptions, type RunResult, type Runnable } from './functional/run.ts'
 import { GRAMMAR_COVERAGE_DEFINITIONS } from './grammar-metadata.ts'
 export { GRAMMAR_COVERAGE_DEFINITIONS } from './grammar-metadata.ts'
@@ -365,6 +366,11 @@ function coverageEntry(entry: Combinator<unknown>, collector: GrammarCoverageCol
           ...(def.recoverAt === undefined ? {} : { recoverAt: build(def.recoverAt) }),
           ...(def.stopAt === undefined ? {} : { stopAt: build(def.stopAt) }),
         })
+        case 'lines': return lines(build(def.prefix), build(def.body), {
+          ...(def.first === undefined ? {} : { first: build(def.first) }),
+          ...(def.lazy === undefined ? {} : { lazy: build(def.lazy) }),
+        })
+        case 'columns': return parser
         // Zero-width assertion with no coverage-bearing child; reuse it verbatim so
         // the rebuilt sequence still recognises the boundary marker.
         case 'adjacency': return parser

package/src/cst/reflection.ts

@@ -66,6 +66,9 @@ function childrenOf(def: ParserDef): readonly Combinator<unknown>[] {
       ]
     case 'routed':
       return def.fallback ? [def.fallback] : []
+    case 'lines':
+      return [def.prefix, def.body, ...(def.first === undefined ? [] : [def.first]), ...(def.lazy === undefined ? [] : [def.lazy])]
+    case 'columns':
     case 'literal':
     case 'regex':
     case 'keywords':

package/src/cst/trivia-kinds.ts

@@ -1,4 +1,4 @@
-import type { Combinator, ParseContext } from '../types.ts'
+import type { CharRange, 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'
@@ -20,6 +20,14 @@ export type LabeledTriviaSpec = {
    */
   readonly visitor: CssTriviaVisitor | null
   readonly charArms: readonly TriviaArmMatcher[] | null
+  /**
+   * `table/trivia-gap.ts`'s root-selection fast path, for the selection it was
+   * last primed with: the selected arms' first characters, and the unlabelled
+   * scanner that answers a run free of them (`null`: no fast path).
+   */
+  rootKinds: Readonly<Record<string, number>> | undefined
+  rootLeaders: readonly CharRange[]
+  rootScan: ((input: string, cur: number) => number) | null
 }
 
 /** See `trivia-skip.ts`: bounded scalar memoisation avoids a WeakMap in the
@@ -114,6 +122,9 @@ export function labeledTriviaSpec(arms: LabeledTriviaSpec['arms'], minRepeats: n
     minRepeats,
     visitor: commonLabeledTriviaVisitor({ arms, minRepeats }),
     charArms: charArmsFor({ arms, minRepeats }),
+    rootKinds: undefined,
+    rootLeaders: [],
+    rootScan: null,
   }
 }
 

package/src/index.ts

@@ -152,6 +152,8 @@ export { isParseError } from './combinators/expect.ts'
 export { expect } from './combinators/expect.ts'
 export { completionsAt } from './combinators/completions.ts'
 export { scanTo, balanced } from './combinators/scanTo.ts'
+export { lines, columns, sourceOffset } from './combinators/lines.ts'
+export type { LinesOptions, LineView, RunLine } from './combinators/lines.ts'
 export type { ScanToOptions } from './combinators/scanTo.ts'
 
 export type { CSTNode, CSTLeaf, CSTError, CSTTrivia, CSTChild, CSTRawChild, NodeLike } from './cst/types.ts'

package/src/parse-context.ts

@@ -48,6 +48,8 @@ export function createParseContext(): ParseContext {
     _triviaCaptureMask: undefined,
     trackLines: false,
     state: undefined,
+    lineView: undefined,
+    _columnsSplit: undefined,
     build: undefined,
     _errors: undefined,
     _tolerant: undefined,
@@ -66,6 +68,7 @@ export function createParseContext(): ParseContext {
     _rootTriviaKindIndex: undefined,
     _rootTriviaStrictScopes: undefined,
     _rootTriviaCapture: undefined,
+    _gap: undefined,
     _cstTriviaLog: undefined,
     _fields: undefined,
     _cstBuf: undefined,

package/src/plugin/entry-supercompiler.ts

@@ -11,7 +11,7 @@ import { parseSync } from 'oxc-parser'
 import { OP_ATTEMPT, OP_NODE, OP_NODE_TRACK, OP_REPV, OP_SCAN } from '../table/ops.ts'
 import { emitAssemblySource, type EmitResult } from '../table/emit-assembly.ts'
 import { defaultAssemblyCfgs } from '../table/emit.ts'
-import { resolveTable, type TableProgram } from '../table/program.ts'
+import { assemblyExtraIps, resolveTable, type TableProgram } from '../table/program.ts'
 
 type Ast = { type: string; start?: number; end?: number; [key: string]: unknown }
 
@@ -229,20 +229,19 @@ export function supercompileEntryAssembly(
  * then finds the precompiled assembly through the table object's AST shape and
  * replaces only that factory body. Any mismatch returns the canonical source.
  */
-export function supercompileRuleMapReplacement(prog: TableProgram, replacement: string): string {
+export function supercompileRuleMapReplacement(
+  prog: TableProgram,
+  replacement: string,
+  select?: ReadonlySet<number>,
+): string {
   const cfg = defaultAssemblyCfgs(prog)[0]
   if (cfg === undefined) return replacement
-  const extraIps: number[] = []
-  for (const scan of prog.scans ?? []) {
-    for (const ref of scan.skip) extraIps.push(ref[0])
-    if (scan.sentinel !== undefined) extraIps.push(scan.sentinel[0])
-  }
-  for (const set of prog.scanSkip ?? []) for (const ref of set) extraIps.push(ref[0])
+  const extraIps = assemblyExtraIps(prog)
 
   let canonical: EmitResult
   let candidate: EntrySupercompileResult
   try {
-    canonical = emitAssemblySource(resolveTable(prog), prog, cfg, extraIps, true)
+    canonical = emitAssemblySource(resolveTable(prog), prog, cfg, extraIps, true, select)
     candidate = supercompileEmittedAssembly(prog, cfg, extraIps, canonical)
   } catch {
     return replacement

package/src/plugin/evaluator.ts

@@ -320,6 +320,10 @@ const SUPPORTED: Record<string, (...args: unknown[]) => 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>),
+  // `lines(prefix, body, { first, lazy })`: its options are combinators, which the
+  // generic argument evaluation already resolves; a missing option stays absent.
+  lines:     (...a) => parseman.lines(a[0] as Combinator<unknown>, a[1] as Combinator<unknown>, a[2] as parseman.LinesOptions | undefined),
+  columns:   (...a) => parseman.columns(a[0] as number),
   // `routed(fallback)` — the fallback must be forwarded. A zero-arg entry here read
   // as "routed takes no arguments" and SILENTLY built a bare `routed()`, so a
   // production written to work both inside and outside a dispatch branch lost its