parseman 0.45.0 → 0.47.0

package/src/table/scan-shapes.ts

@@ -0,0 +1,1578 @@
+/**
+ * SHAPE RECOGNITION AND SOURCE EMISSION FOR SCANNABLE REGEXES.
+ *
+ * Restored from `archive/codegen-fastpaths:src/compiler/scannable-run.ts` and
+ * re-aimed at `emit-assembly.ts`. It is a SOURCE emitter, not a runtime
+ * interpreter: `emitShapeMatch` constant-folds every range and code point into
+ * the text of a per-site `_pf<N>` body via `classCond`/`litCond`/`foldEq`. Built
+ * instead as static runtime bodies the nine shapes would reproduce exactly the
+ * `inRanges` per-character loop this file exists to remove.
+ *
+ * The two trivia-loop emitters (`scanBranch`, `scanBranchLabeled`) are NOT
+ * restored: fusing the trivia path into piece bodies is a separate unit, and
+ * carrying dead emitters here would make this file look like it already did it.
+ *
+ * Structural recognition of "scannable" parser arms — regex shapes that lower to
+ * a tight character-scan loop instead of `regex.exec` / combinator dispatch. Each
+ * shape is derived from the regex STRUCTURE, not from any hardcoded knowledge
+ * that a given regex "is whitespace" or "is a comment":
+ *
+ *   [X]+ / [X]*            → run while the char ∈ X                (chars)
+ *   <lit>[^X]*             → consume <lit>, run until char ∈ X     (until)
+ *   <open>(?:…)*<close>    → consume <open>, run to <close> literal (delimited)
+ *   x?<lit><[X]*>…         → a general linear chain of lit/run     (seq)
+ *
+ * `seq` is the CATEGORY generalization: any chain of literal segments (required
+ * or optional `x?`) and char-class runs (positive/negated, `?`/`*`/`+`). It
+ * subsumes CSS/Less `-?ident`, `--custom`, `@-?keyword`, `[^…]+`, `::?`, etc.
+ * without hardcoding a single byte — lowered only when a greedy one-pass scan
+ * provably equals the engine's backtracking (see `seqIsUnambiguous`).
+ *
+ * A `oneOrMore(choice(a, b, …))` where every arm is one of these compiles to a
+ * single char-dispatch loop with one branch per arm — any count/order, because
+ * the shapes dispatch on their first 1–2 chars and are checked in turn. Trivia
+ * (whitespace + comments) is just the value-discarded instance of this; nothing
+ * here is trivia-specific.
+ */
+
+/**
+ * One segment of a `seq` shape. A `seq` is the general category "a fixed linear
+ * chain of literals and char-class runs" — no alternation, no groups, no
+ * backtracking. It subsumes every CSS/Less token that is "(optional prefix)?
+ * literal* char-run* …" without hardcoding any particular byte:
+ *
+ *   lit   — a run of fixed code points, optionally present (`x?`) or required.
+ *   run   — a char-class run: positive/negated ranges, min 0/1, bounded to one
+ *           char (`[x]`, `[x]?`) or unbounded (`[x]*`, `[x]+`).
+ *   group — a non-capturing sub-pattern `(?:…)` (§8f), quantified the same way
+ *           as `run` (`min`/`unbounded`). `inner` is any already-recognized
+ *           `ScanShape` for the group's body (so a group can itself contain
+ *           `seq`/`chars`/`alt`/… — including a nested alternation via §8e).
+ *           Only used when `groupInnerSafe(inner)` holds (see that function).
+ *
+ * We only lower a `seq` when greedy left-to-right scanning provably equals the
+ * regex engine's backtracking match (see `seqIsUnambiguous`).
+ */
+export type SeqPart =
+  | { part: 'lit'; cps: number[]; optional: boolean }
+  // A char-class run with a general counted quantifier: `min`..`max` occurrences.
+  // `max === Infinity` is unbounded (`+`/`*`/`{n,}`). The four legacy shapes map
+  // as `+`→{1,∞} `*`→{0,∞} `?`→{0,1} bare→{1,1}; `{n,m}` (§8c) fills the rest.
+  // Greedy scanning has "wiggle" a backtracker could exploit iff `max > min`.
+  | { part: 'run'; ranges: Array<[number, number]>; negated: boolean; min: number; max: number }
+  | { part: 'group'; inner: ScanShape; min: 0 | 1; unbounded: boolean }
+
+export type ScanShape =
+  | { kind: 'chars'; ranges: Array<[number, number]>; minOne: boolean }
+  | { kind: 'ident'; head: Array<[number, number]>; tail: Array<[number, number]> }
+  | { kind: 'until'; open: number[]; stop: Array<[number, number]> }
+  | { kind: 'delimited'; open: number[]; close: number[] }
+  // <q>(?:[^<q>\\]|\\.)*<q> — a quote-delimited string with backslash escapes.
+  // `excluded` = the body's negated class (always contains the quote + backslash,
+  // maybe a newline); `escLineTerm` = whether `\\` may be followed by a line
+  // terminator (`\\[\s\S]` → true, `\\.` → false, since `.` excludes them).
+  | { kind: 'string'; quote: number; excluded: Array<[number, number]>; escLineTerm: boolean }
+  // A linear chain of literal/char-run segments (optional prefixes, literal
+  // openers, negated runs, …) — the general CSS/Less token category.
+  | { kind: 'seq'; parts: SeqPart[] }
+  // A pure literal matched case-insensitively (`/i`): the general "ASCII
+  // case-fold literal" category (CSS `url(`, `@media` keywords under `i`, …).
+  | { kind: 'litFold'; open: number[] }
+  // `<inner>(?!class)` / `<inner>(?=class)` — a trailing lookahead boundary
+  // check on an already-lowered shape. Zero-width: `end` is `inner`'s end, never
+  // extended. `classNegated` is the bracket's OWN `[^…]` negation (e.g.
+  // `(?![0-9a-fA-F])` vs `(?=[^0-9])`), independent of `negative` (`!` vs `=`).
+  | { kind: 'lookahead'; inner: ScanShape; ranges: Array<[number, number]>; classNegated: boolean; negative: boolean }
+  // `A|B|C` — top-level alternation (§8e), split outside any `[]`/`()`, each arm
+  // independently lowered. `disjoint` is true iff every pair of arms has
+  // provably non-overlapping first-char sets (`firsts[i]` holds that arm's set,
+  // or `null` if it could start with any char — an unbounded-optional `chars`
+  // arm, or a non-disjoint mix). When `disjoint`, codegen dispatches straight to
+  // the one matching arm; otherwise it tries arms in order and takes the first
+  // that succeeds — the same ordered-choice semantics as regex `|` itself (see
+  // the ordered-vs-longest verification in PERF_IDEAS §8e).
+  | { kind: 'alt'; arms: ScanShape[]; disjoint: boolean; firsts: Array<CharSet | null> }
+
+/** Backslash (`\`) code point — the escape lead char in string shapes. */
+export const BACKSLASH = 92
+
+const META = new Set('()[]{}*+?|^$.'.split(''))
+
+// Regex char-class primitives are shared with the interpreter's first-set
+// analyzer and `regex()`'s scanner — see `../regex/classes.ts`. `SPACE_RANGES`
+// and `parseClassRanges` are re-exported here because codegen's boundary-class
+// lowering imports them from this module.
+import { CLASS_ESCAPES, SPACE_RANGES, literalCodePoints, parseClassOperand, shorthandRanges, readUnicodeEscape, parseClassRanges } from '../regex/classes.ts'
+export { SPACE_RANGES, parseClassRanges }
+
+/** A single class token (`[...]` or `\d`/`\w`) to ranges, or null. Rejects negation. */
+function classToRanges(cls: string): Array<[number, number]> | null {
+  if (cls === '\\d') return shorthandRanges('d')
+  if (cls === '\\w') return shorthandRanges('w')
+  if (cls === '\\s') return shorthandRanges('s')
+  const body = cls.slice(1, -1)
+  if (body.startsWith('^')) return null
+  return parseClassRanges(body)
+}
+
+/** ASCII case-insensitive letter check for `i`-flag literal lowering. */
+// ASCII case-insensitive char compare. For a letter, upper/lower differ only in
+// bit 0x20, and `(c | 32) === <lowercase>` is satisfied by EXACTLY that letter's
+// two cases (nothing else) — one OR + one compare, ~1.75× faster than the
+// two-compare `(c===U || c===L)` form (measured). `(… | 32)` is parenthesized
+// because `===` binds tighter than `|`. Non-letters keep an exact compare.
+// Exported so the case-insensitive `literal()` emitter (codegen) shares the exact
+// same ASCII fold as `/i`-flag regex lowering — no `Intl.Collator` on any path.
+export const foldEq = (cVar: string, cp: number): string => {
+  if (cp >= 65 && cp <= 90) return `(${cVar} | 32) === ${cp + 32}`
+  if (cp >= 97 && cp <= 122) return `(${cVar} | 32) === ${cp}`
+  return `${cVar} === ${cp}`
+}
+
+/**
+ * Recognize a quote-delimited string with backslash escapes:
+ *   <q>(?:[^…]|\\.)*<q>  or  <q>(?:\\.|[^…])*<q>   (`?:` optional)
+ * where the negated body class contains the quote and the backslash, and the
+ * escape body is `.` (no line terminators) or `[\s\S]` (any char). Returns null
+ * for anything else so the caller falls back to `regex.exec`.
+ */
+function parseStringShape(source: string): ScanShape | null {
+  const q = source[0]
+  if (q === undefined || q === '\\' || META.has(q)) return null
+  if (source.length < 3 || source[source.length - 1] !== q) return null
+  const inner = source.slice(1, -1)
+  const CLS = String.raw`\[\^((?:\\.|[^\]])+)\]`
+  const ESC = String.raw`\\\\(\.|\[\\s\\S\]|\[\\S\\s\])`
+  // Two arm orders; `?:` optional. Capture groups differ, so read both out.
+  let body: string | undefined
+  let esc: string | undefined
+  let m = new RegExp(`^\\((?:\\?:)?${CLS}\\|${ESC}\\)\\*$`).exec(inner)
+  if (m) { body = m[1]; esc = m[2] }
+  else {
+    m = new RegExp(`^\\((?:\\?:)?${ESC}\\|${CLS}\\)\\*$`).exec(inner)
+    if (m) { esc = m[1]; body = m[2] }
+  }
+  if (body === undefined || esc === undefined) return null
+  const excluded = parseClassRanges(body)
+  if (!excluded) return null
+  const qcp = q.codePointAt(0)!
+  const inSet = (cp: number) => excluded.some(([lo, hi]) => cp >= lo && cp <= hi)
+  if (!inSet(qcp) || !inSet(BACKSLASH)) return null
+  return { kind: 'string', quote: qcp, excluded, escLineTerm: esc !== '.' }
+}
+
+/**
+ * Parse a regex source into a linear chain of literal / char-run segments, or
+ * null if it uses any construct outside that category (alternation, groups,
+ * `.`, `{n,m}`, lookaround, unknown escapes). This is the STRUCTURAL recognizer
+ * for the `seq` shape — it encodes categories (optional prefix, literal opener,
+ * negated run, …), never any specific byte value.
+ */
+function parseSeqParts(source: string): SeqPart[] | null {
+  const parts: SeqPart[] = []
+  let lit: number[] = []
+  const flush = () => {
+    if (lit.length) { parts.push({ part: 'lit', cps: lit, optional: false }); lit = [] }
+  }
+  // Parse a `{n}` / `{n,}` / `{n,m}` counted quantifier at `source[at]` (`'{'`).
+  // Returns the bounds and the token length, or null when it isn't a well-formed
+  // brace quantifier (then the `{` is left for the caller's metachar decline).
+  const braceQuant = (at: number): { min: number; max: number; len: number } | null => {
+    const close = source.indexOf('}', at)
+    if (close === -1) return null
+    const body = source.slice(at + 1, close)
+    const m = /^(\d+)(,(\d*)?)?$/.exec(body)
+    if (!m) return null
+    const min = Number(m[1])
+    const max = m[2] === undefined ? min : m[3] ? Number(m[3]!) : Infinity
+    // Decline degenerate/empty-capable or invalid bounds — RegExp handles them.
+    if (max < 1 || min > max) return null
+    return { min, max, len: close - at + 1 }
+  }
+  const runFrom = (ranges: Array<[number, number]>, negated: boolean, at: number) => {
+    const q = source[at]
+    if (q === '+') { parts.push({ part: 'run', ranges, negated, min: 1, max: Infinity }); return 1 }
+    if (q === '*') { parts.push({ part: 'run', ranges, negated, min: 0, max: Infinity }); return 1 }
+    if (q === '?') { parts.push({ part: 'run', ranges, negated, min: 0, max: 1 }); return 1 }
+    if (q === '{') {
+      const b = braceQuant(at)
+      if (b) { parts.push({ part: 'run', ranges, negated, min: b.min, max: b.max }); return b.len }
+    }
+    parts.push({ part: 'run', ranges, negated, min: 1, max: 1 })
+    return 0
+  }
+  let i = 0
+  while (i < source.length) {
+    const ch = source[i]!
+    if (ch === '[') {
+      // Read a char class, honoring `\]`.
+      let k = i + 1
+      const neg = source[k] === '^'
+      if (neg) k++
+      let body = ''
+      while (k < source.length && source[k] !== ']') {
+        if (source[k] === '\\') { body += source[k]! + (source[k + 1] ?? ''); k += 2 }
+        else { body += source[k]!; k++ }
+      }
+      if (source[k] !== ']') return null
+      const ranges = parseClassRanges(body)
+      if (!ranges) return null
+      flush()
+      i = k + 1
+      i += runFrom(ranges, neg, i)
+      continue
+    }
+    if (ch === '\\') {
+      const e = source[i + 1]
+      if (e === 'd' || e === 'w' || e === 's') {
+        flush()
+        i += 2
+        i += runFrom(shorthandRanges(e), false, i)
+        continue
+      }
+      // Escaped literal code point (incl. `\uXXXX`, `\t`, `\(`, …).
+      const uni = readUnicodeEscape(source, i)
+      let cp: number
+      if (uni) { cp = uni.cp; i = uni.next }
+      else if (e === undefined) return null
+      else if (e in CLASS_ESCAPES) { cp = CLASS_ESCAPES[e]!; i += 2 }
+      else if ((e >= 'a' && e <= 'z') || (e >= 'A' && e <= 'Z')) return null
+      else { cp = e.codePointAt(0)!; i += 2 }
+      if (source[i] === '?') { flush(); parts.push({ part: 'lit', cps: [cp], optional: true }); i++ }
+      else lit.push(cp)
+      continue
+    }
+    if (ch === '(') {
+      // Only a non-capturing group `(?:…)` is modeled (§8f) — a bare capturing
+      // group, or a lookaround appearing mid-pattern (a TRAILING one is peeled
+      // off separately by `stripTrailingLookahead` before we ever get here), is
+      // declined outright rather than risk misreading it.
+      if (source[i + 1] !== '?' || source[i + 2] !== ':') return null
+      let k = i + 3
+      let depth = 1
+      while (k < source.length && depth > 0) {
+        const c2 = source[k]
+        if (c2 === '\\') { k += 2; continue }
+        if (c2 === '[') {
+          let j = k + 1
+          if (source[j] === '^') j++
+          while (j < source.length && source[j] !== ']') {
+            if (source[j] === '\\') j += 2
+            else j++
+          }
+          if (source[j] !== ']') return null
+          k = j + 1
+          continue
+        }
+        if (c2 === '(') depth++
+        else if (c2 === ')') depth--
+        k++
+      }
+      if (depth !== 0) return null
+      const body = source.slice(i + 3, k - 1)
+      const inner = parseScanShape(body)
+      if (!inner || !groupInnerSafe(inner)) return null
+      const q = source[k]
+      // `{n,m}` on a group is a §8c/§8f combination not modeled — decline.
+      if (q === '{') return null
+      flush()
+      if (q === '+') {
+        if (shapeCanBeEmpty(inner)) return null // would loop forever — decline
+        parts.push({ part: 'group', inner, min: 1, unbounded: true })
+        i = k + 1
+      } else if (q === '*') {
+        if (shapeCanBeEmpty(inner)) return null
+        parts.push({ part: 'group', inner, min: 0, unbounded: true })
+        i = k + 1
+      } else if (q === '?') {
+        parts.push({ part: 'group', inner, min: 0, unbounded: false })
+        i = k + 1
+      } else {
+        parts.push({ part: 'group', inner, min: 1, unbounded: false })
+        i = k
+      }
+      continue
+    }
+    // A bare metachar (`|`, `.`, `{`, stray `*`/`+`/`?`, …) is outside the
+    // linear-chain category — bail to the RegExp fallback.
+    if (META.has(ch)) return null
+    const cp = ch.codePointAt(0)!
+    i += ch.length
+    if (source[i] === '?') { flush(); parts.push({ part: 'lit', cps: [cp], optional: true }); i++ }
+    else lit.push(cp)
+  }
+  flush()
+  return parts.length ? parts : null
+}
+
+/**
+ * Only lower a `seq` when greedy left-to-right scanning matches EXACTLY what the
+ * backtracking regex engine would. The dangerous cases are (a) an optional part
+ * that could also be consumed by what follows, and (b) an unbounded/repeated
+ * part whose accepted class overlaps what follows — both let the engine
+ * backtrack to a different boundary than a one-pass scan. We also require at
+ * least one mandatory segment (so the token can't match zero-width).
+ *
+ * A skippable/repeatable part `p` at index `k` is checked against
+ * `seqFirstAccept(parts.slice(k + 1))` — the accept-set of EVERYTHING that
+ * could start at the very next position, unioned through any further chain of
+ * optionals up to the next mandatory part (the exact same computation
+ * `seqFirstAccept` already does for a seq's OWN leading accept-set). This
+ * subsumes the simpler "check only the immediate neighbor" rule as the
+ * one-part-following case, while also correctly handling a CHAIN of several
+ * consecutive optional parts (e.g. two independent optional groups in a row,
+ * `(?:\.\d+)?(?:[eE][+-]?\d+)?` — JSON/GraphQL's number tail, §8f): each is
+ * safe precisely when disjoint from everything that could follow it, however
+ * many further optionals that spans. An empty tail (`p` is the last part)
+ * naturally resolves to a trivially-disjoint empty set — nothing to check.
+ *
+ * Uniform across `lit`/`run`/`group`: each part's own "first char it could
+ * start with" (`partFirstAccept`) is compared via `firstSetsDisjoint` — the
+ * same subset/disjoint math used everywhere else in this file (§8b's
+ * lookahead guard, §8e's alt-dispatch guard).
+ */
+function seqIsUnambiguous(parts: SeqPart[]): boolean {
+  let hasMandatory = false
+  for (let k = 0; k < parts.length; k++) {
+    const p = parts[k]!
+    const mandatory = p.part === 'lit' ? !p.optional : p.min >= 1
+    if (mandatory) hasMandatory = true
+    // A `group` part has a right-edge exposure (`groupPartExposure`): the chars a
+    // backtracking engine could give back by shrinking the body's own trailing
+    // quantifier, dropping the group (if optional/repeated), or — for a
+    // non-disjoint alt body — switching arms. Ordered-choice greedy scanning
+    // matches the engine only when NONE of those relinquished chars could also
+    // start what follows the group (else the scan and the engine disagree on
+    // where the group ends). Two outcomes:
+    //   - a concrete class → must be disjoint from `seqFirstAccept(rest)`. This
+    //     is the general fix for a group whose body ends in an unbounded run
+    //     (`(?:\d+)\d` must NOT lower), and it lets a mutually-exclusive fixed
+    //     alt (§8i, exposure `null`) lower at ANY position, not just trailing.
+    //   - `'unsupported'` → the exposure can't be bounded (e.g. a non-disjoint
+    //     alt like `(?:a|ab)` that genuinely needs arm-switching). Sound only
+    //     when nothing follows to force reconsideration — the group must be the
+    //     trailing, matched-exactly-once part (§8h); otherwise decline.
+    if (p.part === 'group') {
+      const exposure = groupPartExposure(p)
+      if (exposure === 'unsupported') {
+        const trailingOnce = k === parts.length - 1 && p.min === 1 && !p.unbounded
+        if (!trailingOnce) return false
+      } else if (exposure !== null) {
+        if (!firstSetsDisjoint(exposure, seqFirstAccept(parts.slice(k + 1)))) return false
+      }
+    }
+    // A part needs the disjoint-from-continuation check when a greedy one-pass
+    // scan has freedom a backtracking engine could resolve differently: an
+    // optional `lit`, a `run` with wiggle (`max > min` — covers `?`/`*`/`+` and
+    // bounded `{n,m}` with `m > n`; a fixed `{n}` run has none), or an
+    // optional/repeated `group`. A fixed-length run (`max === min`) consumes an
+    // exact count with no boundary to shift, so it never needs the check.
+    const needsDisjoint =
+      p.part === 'lit' ? p.optional
+      : p.part === 'run' ? p.max > p.min
+      : (p.unbounded || p.min === 0)
+    if (needsDisjoint) {
+      const rest = seqFirstAccept(parts.slice(k + 1))
+      if (!firstSetsDisjoint(partFirstAccept(p), rest)) return false
+    }
+  }
+  return hasMandatory
+}
+
+function rangesOverlap(a: Array<[number, number]>, b: Array<[number, number]>): boolean {
+  return a.some(([lo, hi]) => b.some(([lo2, hi2]) => lo <= hi2 && lo2 <= hi))
+}
+
+/** Is every range in `sub` fully contained in some range of `sup`? */
+function rangesSubset(sub: Array<[number, number]>, sup: Array<[number, number]>): boolean {
+  return sub.every(([lo, hi]) => sup.some(([lo2, hi2]) => lo >= lo2 && hi <= hi2))
+}
+
+type TrailingLookahead = {
+  base: string
+  ranges: Array<[number, number]>
+  classNegated: boolean
+  negative: boolean
+}
+
+type CharSet = { ranges: Array<[number, number]>; negated: boolean }
+
+/** Is char-set `t` fully contained in char-set `u`? Handles all 4 sign combos. */
+function classSubset(t: CharSet, u: CharSet): boolean {
+  if (!t.negated && !u.negated) return rangesSubset(t.ranges, u.ranges)
+  if (!t.negated && u.negated) return !rangesOverlap(t.ranges, u.ranges) // t ⊆ ¬u ⟺ t ∩ u = ∅
+  if (t.negated && !u.negated) return false // ¬t ⊆ u is never true for finite ranges u
+  return rangesSubset(u.ranges, t.ranges) // ¬t ⊆ ¬u ⟺ u ⊆ t
+}
+
+/** Are char-sets `t` and `u` disjoint (no overlap)? Handles all 4 sign combos. */
+function classDisjoint(t: CharSet, u: CharSet): boolean {
+  if (!t.negated && !u.negated) return !rangesOverlap(t.ranges, u.ranges)
+  if (!t.negated && u.negated) return rangesSubset(t.ranges, u.ranges) // t ∩ ¬u = ∅ ⟺ t ⊆ u
+  if (t.negated && !u.negated) return rangesSubset(u.ranges, t.ranges) // symmetric
+  return false // ¬t ∩ ¬u = ∅ would require t ∪ u = every code point — can't prove with finite ranges
+}
+
+/** `classDisjoint`, `'any'`-aware: an empty-capable part's first-set degrades
+ * to `'any'` (see `shapeFirstAccept`), and `'any'` is never disjoint from
+ * anything (it could start with literally any char, including whatever the
+ * other side accepts). */
+function firstSetsDisjoint(a: CharSet | 'any', b: CharSet | 'any'): boolean {
+  if (a === 'any' || b === 'any') return false
+  return classDisjoint(a, b)
+}
+
+/**
+ * A shape's match as a fixed-length list of per-position char-sets, or `null`
+ * if its match length is NOT fixed. Only a `seq` of mandatory `lit`s (each code
+ * point is one fixed position) and mandatory single-char runs (`[x]`, min 1,
+ * bounded) qualifies — anything with an optional part, an unbounded/optional
+ * run, or a nested group has a variable length and returns `null`. Used to
+ * decide when a non-disjoint alternation's arms are mutually exclusive (§8i).
+ */
+function fixedClassSeq(shape: ScanShape): CharSet[] | null {
+  // A case-fold literal is fixed-length: each code point becomes a single-char
+  // class holding BOTH ASCII cases (so mutual-exclusivity is judged on what the
+  // `/i` match actually accepts — `and` vs `or` are disjoint at position 0).
+  if (shape.kind === 'litFold') {
+    return shape.open.map(cp => {
+      const other = cp >= 65 && cp <= 90 ? cp + 32 : cp >= 97 && cp <= 122 ? cp - 32 : cp
+      return other === cp
+        ? { ranges: [[cp, cp]] as Array<[number, number]>, negated: false }
+        : { ranges: [[Math.min(cp, other), Math.min(cp, other)], [Math.max(cp, other), Math.max(cp, other)]] as Array<[number, number]>, negated: false }
+    })
+  }
+  if (shape.kind !== 'seq') return null
+  const out: CharSet[] = []
+  for (const p of shape.parts) {
+    if (p.part === 'lit') {
+      if (p.optional) return null
+      for (const cp of p.cps) out.push({ ranges: [[cp, cp]], negated: false })
+    } else if (p.part === 'run' && p.max === p.min && Number.isFinite(p.max)) {
+      // A fixed-count run `[x]{n}` (incl. the bare `[x]`, n=1) is n fixed
+      // positions of the same class. Variable-length runs return null below.
+      for (let c = 0; c < p.max; c++) out.push({ ranges: p.ranges, negated: p.negated })
+    } else {
+      return null // optional/variable/unbounded run, or a nested group — length not fixed
+    }
+  }
+  return out.length ? out : null
+}
+
+/**
+ * §8i — is a NON-disjoint `alt` shape one whose arms are pairwise MUTUALLY
+ * EXCLUSIVE fixed-length token sets? Every arm must be a `fixedClassSeq`, and no
+ * arm's match may ever be a prefix (proper, or an equal-length overlap) of
+ * another arm's — i.e. for every ordered pair (A, B) with `A.length <= B.length`
+ * there is a position within A where their classes are DISJOINT. That property
+ * guarantees at most one arm matches at any input position, so ordered-choice
+ * commit lands on the SAME arm (and the SAME fixed end) the engine would, with
+ * no arm to switch to under backtracking — sound in ANY position, not just
+ * trailing (unlike the general non-disjoint alt, which needs the trailing-once
+ * gate in `seqIsUnambiguous`). `(?:ab|ac)` and `(?:foo|barn)` qualify;
+ * `(?:a|ab)` (arm `a` is a prefix of `ab`) does NOT.
+ */
+function altFixedMutuallyExclusive(shape: ScanShape): boolean {
+  if (shape.kind !== 'alt' || shape.disjoint) return false
+  const lists: CharSet[][] = []
+  for (const arm of shape.arms) {
+    const f = fixedClassSeq(arm)
+    if (!f) return false
+    lists.push(f)
+  }
+  for (let i = 0; i < lists.length; i++) {
+    for (let j = 0; j < lists.length; j++) {
+      if (i === j) continue
+      const a = lists[i]!
+      const b = lists[j]!
+      if (a.length > b.length) continue // only check the shorter (a) as a prefix of the longer (b)
+      let disjointAt = false
+      for (let p = 0; p < a.length; p++) {
+        if (classDisjoint(a[p]!, b[p]!)) { disjointAt = true; break }
+      }
+      if (!disjointAt) return false // `a` could be a prefix of `b` — not mutually exclusive
+    }
+  }
+  return true
+}
+
+/**
+ * The char-set a backtracking engine could relinquish at a `group` PART's right
+ * edge — its "trailing exposure". Combines two independent backtrack moves: the
+ * group body's OWN trailing wiggle (`trailingBacktrackClass(inner)`, e.g. the
+ * body ends in an unbounded run), and — if the group is optional (`min 0`) or
+ * repeated (`unbounded`) — the "drop the last occurrence" move, which exposes
+ * the body's own first-char set. A required-once group (`min 1`, bounded) has
+ * only the first move. Returns `'unsupported'` if either component can't be
+ * pinned to a concrete set. This is the single computation used everywhere a
+ * group's right boundary matters: `trailingBacktrackClass` (a `seq` ending in a
+ * group) and `seqIsUnambiguous` (a group at ANY position, followed by more).
+ */
+function groupPartExposure(part: Extract<SeqPart, { part: 'group' }>): CharSet | null | 'unsupported' {
+  const innerWiggle = trailingBacktrackClass(part.inner)
+  if (innerWiggle === 'unsupported') return 'unsupported'
+  const requiredOnce = !part.unbounded && part.min === 1
+  if (requiredOnce) return innerWiggle // no "drop it" move possible — only inner's own wiggle matters
+  const dropExposed = shapeFirstAccept(part.inner)
+  if (dropExposed === 'any') return 'unsupported'
+  if (innerWiggle === null) return dropExposed
+  const unioned = unionCharSets([innerWiggle, dropExposed])
+  return unioned === 'any' ? 'unsupported' : unioned
+}
+
+/**
+ * The char-class a backtracking engine could expose by shrinking `shape`'s
+ * OWN trailing quantifier by one position — i.e. the "wiggle room" a trailing
+ * lookahead could interact with. Returns `null` when `shape`'s matched length
+ * is fully fixed once it succeeds (no quantifier to shrink), which makes
+ * wrapping it in a lookahead unconditionally safe. Returns `'unsupported'` for
+ * shape kinds whose backtracking semantics aren't modeled here (declines the
+ * lookahead lowering rather than risking an unproven guard).
+ *
+ * Only the LAST quantifier matters: `seqIsUnambiguous` already proves every
+ * EARLIER part of a `seq` has exactly one valid parse (no alternate length),
+ * so the sole remaining freedom a backtracking engine has — once we attach an
+ * external trailing lookahead — is in whatever quantifier sits at the very end.
+ */
+function trailingBacktrackClass(shape: ScanShape): CharSet | null | 'unsupported' {
+  if (shape.kind === 'chars') return { ranges: shape.ranges, negated: false }
+  if (shape.kind === 'ident') return { ranges: shape.tail, negated: false }
+  if (shape.kind === 'litFold') return null // fixed-length literal — no quantifier at all
+  if (shape.kind === 'seq') {
+    const last = shape.parts[shape.parts.length - 1]!
+    if (last.part === 'lit') {
+      // A REQUIRED literal tail is fixed — no quantifier, no wiggle.
+      //
+      // An OPTIONAL one is the opposite, and reading it as fixed was a defect.
+      // `::?(?![ \t\n\r\f])` on `":: "` matches ONE colon: the engine takes both,
+      // the lookahead rejects the space, it gives the second colon back, and the
+      // lookahead then sees `:` and passes. A greedy scan that resolves `::`
+      // once and never reconsiders reports NO MATCH — which is what this
+      // returned `null` for, so `lookaheadUnambiguous` waved it through and the
+      // shape lowered wrongly. Found by the oracle on jess's css grammar the
+      // first time that grammar emitted at all.
+      //
+      // Declined rather than modelled. The exposed class IS computable — drop
+      // the literal and the char at the new end is `cps[0]` — but a chain of
+      // optional parts (`a?b?`) exposes more than one level, and this analysis
+      // is single-level by construction. Wrong here is a silently wrong parse;
+      // declining costs one regex row.
+      return last.optional ? 'unsupported' : null
+    }
+    if (last.part === 'run') {
+      // Wiggle iff `max > min`: unbounded (`+`/`*`/`{n,}`), optional (`[x]?`),
+      // or bounded `{n,m}` with `m > n` all let a backtracker shrink the trailing
+      // run by ≥1 position. A fixed run (`[x]`, `{n}`, `max === min`) has no
+      // choice — no wiggle, hence no risk.
+      if (last.max > last.min) return { ranges: last.ranges, negated: last.negated }
+      return null
+    }
+    // A trailing `group` (§8f): its trailing exposure combines its body's own
+    // wiggle and (if optional/repeated) the "drop it" move — see
+    // `groupPartExposure`, shared with `seqIsUnambiguous`.
+    return groupPartExposure(last)
+  }
+  if (shape.kind === 'alt') {
+    // Arm-switching hazard (see `groupInnerSafe`) applies here too: a
+    // non-disjoint alt can't be trusted to expose the right wiggle class,
+    // since which arm ultimately "wins" could itself change under backtrack.
+    // A disjoint alt has no such hazard — exactly one arm is ever reachable
+    // from a given starting char, so the union of every arm's OWN wiggle
+    // covers whichever one is actually taken. A non-disjoint alt whose arms are
+    // fixed-length and mutually exclusive (§8i) also has no wiggle — exactly one
+    // arm matches at any position and its length is fixed, so `null`.
+    if (!shape.disjoint) return altFixedMutuallyExclusive(shape) ? null : 'unsupported'
+    const classes = shape.arms.map(trailingBacktrackClass)
+    if (classes.some(c => c === 'unsupported')) return 'unsupported'
+    const concrete = classes.filter((c): c is CharSet => c !== null)
+    if (concrete.length === 0) return null
+    const unioned = unionCharSets(concrete)
+    return unioned === 'any' ? 'unsupported' : unioned
+  }
+  // `until`/`delimited`/`string`/nested `lookahead` — not modeled; decline.
+  return 'unsupported'
+}
+
+/**
+ * Is it safe to lower `inner(?!ranges)` / `inner(?=ranges)` to a one-shot
+ * post-match check (vs. requiring real backtracking)? See PERF_IDEAS §8b.
+ */
+function lookaheadUnambiguous(inner: ScanShape, operand: CharSet, negative: boolean): boolean {
+  const tail = trailingBacktrackClass(inner)
+  if (tail === 'unsupported') return false
+  if (tail === null) return true // inner's length is fixed — no backtracking possible
+  // Negative `(?!op)`: safe iff every char the tail could expose is ALSO
+  // excluded by `op` (so shrinking never turns a failure into a pass).
+  // Positive `(?=op)`: safe iff the tail is disjoint from `op` (so shrinking
+  // could never expose a char that suddenly satisfies `op`).
+  return negative ? classSubset(tail, operand) : classDisjoint(tail, operand)
+}
+
+/**
+ * Strip a trailing `(?!class)` / `(?=class)` boundary assertion, if present.
+ * Only a TRAILING lookahead with a char-class/single-char operand is
+ * recognized — no sub-patterns, no nested groups. Anything else containing an
+ * unescaped `(` is left to the other recognizers, which reject it as a
+ * metachar (`META`) and fall back to `RegExp.exec`, so a false read here can
+ * only fail to lower, never mis-lower.
+ */
+function stripTrailingLookahead(source: string): TrailingLookahead | null {
+  if (!source.endsWith(')')) return null
+  for (const negative of [true, false] as const) {
+    const lead = negative ? '(?!' : '(?='
+    const idx = source.lastIndexOf(lead)
+    if (idx === -1) continue
+    // The operand must be the ENTIRE lookahead body. `parseClassOperand` enforces
+    // that a bracketed body is ONE class token, so a sequence like
+    // `[ \t\n\r\f]*[\$(]` is declined here rather than read as one garbage class.
+    const operand = parseClassOperand(source.slice(idx + lead.length, -1))
+    if (!operand) continue
+    return { base: source.slice(0, idx), ranges: operand.ranges, classNegated: operand.negated, negative }
+  }
+  return null
+}
+
+/**
+ * Strip ONE redundant outer `(?:…)` wrapper, if it spans the ENTIRE source
+ * (nothing before it, nothing — not even a quantifier — after its matching
+ * close). A non-capturing group with no trailing quantifier is semantically
+ * identical to its bare contents, so this is always safe to unwrap; it's what
+ * lets `(?:a|b|c)` (a whole-token alternation written as idiomatic regex
+ * style, e.g. CSS `basicSel`) reach the top-level `|` split below. Bails
+ * (leaves `source` untouched) on anything that isn't a clean whole-string
+ * wrap: unbalanced parens, or a group that closes before the string ends
+ * (which would mean a quantifier or trailing content follows it).
+ */
+function unwrapOuterGroup(source: string): string {
+  while (source.startsWith('(?:')) {
+    let depth = 1
+    let i = 3
+    let ok = true
+    while (i < source.length && depth > 0) {
+      const ch = source[i]
+      if (ch === '\\') { i += 2; continue }
+      if (ch === '[') {
+        let j = i + 1
+        if (source[j] === '^') j++
+        while (j < source.length && source[j] !== ']') {
+          if (source[j] === '\\') j += 2
+          else j++
+        }
+        if (source[j] !== ']') { ok = false; break }
+        i = j + 1
+        continue
+      }
+      if (ch === '(') depth++
+      else if (ch === ')') depth--
+      i++
+    }
+    if (!ok || depth !== 0 || i !== source.length) break
+    source = source.slice(3, -1)
+  }
+  return source
+}
+
+/**
+ * Split a regex source on top-level `|` — i.e. `|` outside any `[]` bracket
+ * class and outside any `(...)` group (parens still count toward depth even
+ * though we don't otherwise understand groups; a `|` nested in one is never a
+ * split point). Returns null if there's no top-level `|` at all, if brackets/
+ * parens are unbalanced, or if any resulting alternative is empty (a
+ * zero-width arm — an unmodeled edge case, decline rather than mis-lower).
+ * One redundant whole-string `(?:…)` wrapper is stripped first (see
+ * `unwrapOuterGroup`) so `(?:a|b)` splits the same as bare `a|b`.
+ */
+function splitTopLevelAlternation(source: string): string[] | null {
+  const body = unwrapOuterGroup(source)
+  const parts: string[] = []
+  let depth = 0
+  let last = 0
+  let i = 0
+  while (i < body.length) {
+    const ch = body[i]
+    if (ch === '\\') { i += 2; continue }
+    if (ch === '[') {
+      let j = i + 1
+      if (body[j] === '^') j++
+      while (j < body.length && body[j] !== ']') {
+        if (body[j] === '\\') j += 2
+        else j++
+      }
+      if (body[j] !== ']') return null
+      i = j + 1
+      continue
+    }
+    if (ch === '(') { depth++; i++; continue }
+    if (ch === ')') { depth--; if (depth < 0) return null; i++; continue }
+    if (ch === '|' && depth === 0) {
+      parts.push(body.slice(last, i))
+      last = i + 1
+      i++
+      continue
+    }
+    i++
+  }
+  if (depth !== 0) return null
+  parts.push(body.slice(last))
+  if (parts.length < 2 || parts.some(p => p.length === 0)) return null
+  return parts
+}
+
+/** Can `shape` match the empty string? Only an unbounded `chars` run with no
+ * `+` (`[x]*`) can — every other shape requires at least one fixed/mandatory
+ * char (`seq` always has ≥1 mandatory part per `seqIsUnambiguous`; `ident`/
+ * `until`/`delimited`/`string`/`litFold` all require a fixed opening char). A
+ * `lookahead`/`alt` defer to what they wrap. */
+function shapeCanBeEmpty(shape: ScanShape): boolean {
+  if (shape.kind === 'chars') return !shape.minOne
+  if (shape.kind === 'lookahead') return shapeCanBeEmpty(shape.inner)
+  if (shape.kind === 'alt') return shape.arms.some(shapeCanBeEmpty)
+  return false
+}
+
+/** Exact union of char-sets when it's computable, else `'any'` (conservative:
+ * forces ordered dispatch rather than guessing at a mixed-polarity union, or
+ * when any input is already `'any'`). A single concrete-set list is returned
+ * as-is (including if negated) — the ambiguity is only in combining ≥2 sets
+ * of differing polarity. */
+function unionCharSets(sets: Array<CharSet | 'any'>): CharSet | 'any' {
+  if (sets.some(s => s === 'any')) return 'any'
+  const concrete = sets as CharSet[]
+  if (concrete.length === 1) return concrete[0]!
+  if (concrete.some(s => s.negated)) return 'any'
+  return { ranges: concrete.flatMap(s => s.ranges), negated: false }
+}
+
+/** A single seq part's own first-char set, ignoring whether it's skippable.
+ * A `group` part delegates to its inner shape's own first-set (§8f) —
+ * possibly `'any'` if the inner shape can match empty or is a non-disjoint
+ * `alt` (see `shapeFirstAccept`). */
+function partFirstAccept(part: SeqPart): CharSet | 'any' {
+  if (part.part === 'lit') return { ranges: [[part.cps[0]!, part.cps[0]!]], negated: false }
+  if (part.part === 'run') return { ranges: part.ranges, negated: part.negated }
+  return shapeFirstAccept(part.inner)
+}
+
+/** The char-set a `seq` can start with: union of each leading skippable part's
+ * own set up to and including the first mandatory part (after which later
+ * parts can no longer be what the very first input char matches). */
+function seqFirstAccept(parts: SeqPart[]): CharSet | 'any' {
+  const sets: Array<CharSet | 'any'> = []
+  for (const p of parts) {
+    const mandatory = p.part === 'lit' ? !p.optional : p.min >= 1
+    sets.push(partFirstAccept(p))
+    if (mandatory) break
+  }
+  return unionCharSets(sets)
+}
+
+/**
+ * Is `inner` safe to use as a group's body (§8f)? `chars`/`ident`/`seq`/
+ * `litFold` are always safe: each is only ever constructed after proving (via
+ * `seqIsUnambiguous` or equivalent) that greedy resolution is the UNIQUE valid
+ * match at a given position — there is no alternate length for a backtracker
+ * to reconsider, so treating the group as an atomic, resolve-once unit is
+ * sound regardless of what follows it. A `lookahead` defers to what it wraps
+ * (zero-width, adds no new choice). An `alt` is safe ONLY when `disjoint`:
+ * a NON-disjoint alt (`(?:a|ab)`) genuinely can need real backtracking into a
+ * DIFFERENT arm if something after the group fails (verified: `/^(?:a|ab)c/`
+ * matches "abc" via the SECOND arm, only because the first arm's match left
+ * "c" unsatisfied) — our ordered-dispatch codegen resolves once and never
+ * reconsiders, so that case must decline. `until`/`delimited`/`string` are
+ * declined outright, same conservative call as `trailingBacktrackClass`.
+ */
+function groupInnerSafe(shape: ScanShape): boolean {
+  if (shape.kind === 'chars' || shape.kind === 'ident' || shape.kind === 'seq' || shape.kind === 'litFold') return true
+  if (shape.kind === 'lookahead') return groupInnerSafe(shape.inner)
+  // A disjoint alt is safe anywhere. A NON-disjoint alt is admitted here too,
+  // but its ordered-choice-commit is only sound in the trailing-once position —
+  // `seqIsUnambiguous` (§8h) enforces that positional constraint; a non-trailing
+  // or optional/repeated non-disjoint-alt group is rejected there.
+  if (shape.kind === 'alt') return true
+  return false
+}
+
+/**
+ * The set of first chars a NON-EMPTY match of `shape` could start with, or
+ * `'any'` if that can't be pinned down to a single char-set (used to decide
+ * whether `alt` arms have disjoint first-sets). A shape that can match empty
+ * degrades to `'any'`: since it could succeed with zero chars regardless of
+ * what follows, it would "accept" any first char by never actually needing one
+ * — treating that as disjoint from anything else would be unsound.
+ */
+function shapeFirstAccept(shape: ScanShape): CharSet | 'any' {
+  if (shapeCanBeEmpty(shape)) return 'any'
+  switch (shape.kind) {
+    case 'chars': return { ranges: shape.ranges, negated: false }
+    case 'ident': return { ranges: shape.head, negated: false }
+    case 'until': return { ranges: [[shape.open[0]!, shape.open[0]!]], negated: false }
+    case 'delimited': return { ranges: [[shape.open[0]!, shape.open[0]!]], negated: false }
+    case 'string': return { ranges: [[shape.quote, shape.quote]], negated: false }
+    case 'litFold': {
+      const cp = shape.open[0]!
+      if (cp >= 65 && cp <= 90) return { ranges: [[cp, cp], [cp + 32, cp + 32]], negated: false }
+      if (cp >= 97 && cp <= 122) return { ranges: [[cp, cp], [cp - 32, cp - 32]], negated: false }
+      return { ranges: [[cp, cp]], negated: false }
+    }
+    case 'seq': return seqFirstAccept(shape.parts)
+    case 'lookahead': return shapeFirstAccept(shape.inner) // zero-width — doesn't change first-char acceptance
+    case 'alt': {
+      // The set of first chars is the union of every arm's own first-set,
+      // independent of whether the arms are mutually disjoint (that flag only
+      // governs dispatch, not what the shape can start with). Any arm whose
+      // first-set is itself `'any'` (stored as `null`) makes the union `'any'`.
+      const sets = shape.firsts.map((f): CharSet | 'any' => (f === null ? 'any' : f))
+      return unionCharSets(sets)
+    }
+  }
+}
+
+/** True iff every pair of `sets` is provably disjoint; `'any'` is disjoint from nothing. */
+function allPairsDisjoint(sets: Array<CharSet | 'any'>): boolean {
+  for (let i = 0; i < sets.length; i++) {
+    const a = sets[i]!
+    if (a === 'any') return false
+    for (let j = i + 1; j < sets.length; j++) {
+      const b = sets[j]!
+      if (b === 'any' || !classDisjoint(a, b)) return false
+    }
+  }
+  return true
+}
+
+/**
+ * Recognize top-level alternation `A|B|C` (§8e): split on `|` outside any
+ * `[]`/`()`, lower each arm independently (an arm may itself be a `seq`,
+ * `chars`, `lookahead`, …, or even nested alternation via one redundant
+ * `(?:…)` wrapper — see `unwrapOuterGroup`). Declines (null) unless EVERY arm
+ * independently lowers — a single unsupported arm (e.g. one with a nested
+ * capturing/non-capturing group, §8f) falls the whole alternation back to
+ * `RegExp.exec` rather than partially lowering.
+ */
+function parseAlternation(source: string): ScanShape | null {
+  const parts = splitTopLevelAlternation(source)
+  if (!parts) return null
+  const arms: ScanShape[] = []
+  for (const p of parts) {
+    const arm = parseScanShape(p)
+    if (!arm) return null
+    arms.push(arm)
+  }
+  const firstSets = arms.map(shapeFirstAccept)
+  const disjoint = allPairsDisjoint(firstSets)
+  return { kind: 'alt', arms, disjoint, firsts: firstSets.map(f => (f === 'any' ? null : f)) }
+}
+
+/**
+ * Recognize one scannable arm from its regex source, or null if it isn't one of
+ * the structural shapes. Top-level alternation (§8e) is tried FIRST — `|` has
+ * the lowest precedence in regex, so splitting on it happens before anything
+ * else, with each arm then recursively re-entering this same function (so an
+ * arm's own trailing lookahead, or its own nested `(?:…)`-wrapped alternation,
+ * is still recognized). Failing that: char-class run, ident, string, then
+ * open-until-terminator, delimited, and finally the general linear `seq` chain.
+ * A trailing `(?!class)`/`(?=class)` is peeled off next (§8b) and re-wraps
+ * whatever shape the remaining base recognizes as.
+ */
+export function parseScanShape(source: string): ScanShape | null {
+  const alt = parseAlternation(source)
+  if (alt) return alt
+  const la = stripTrailingLookahead(source)
+  if (la) {
+    const inner = parseScanShapeCore(la.base)
+    if (!inner) return null
+    const operand: CharSet = { ranges: la.ranges, negated: la.classNegated }
+    if (!lookaheadUnambiguous(inner, operand, la.negative)) return null
+    return { kind: 'lookahead', inner, ranges: la.ranges, classNegated: la.classNegated, negative: la.negative }
+  }
+  return parseScanShapeCore(source)
+}
+
+/**
+ * Split a regex fragment on top-level `|` (outside `[]`/`()`), escape-aware.
+ * Unlike `splitTopLevelAlternation` this allows a SINGLE arm (no `|` at all) and
+ * does not unwrap an outer group — it's used to enumerate the arms of a
+ * `delimited` body, which may legitimately be one bare arm (`[^x]`). Returns
+ * null on unbalanced brackets/parens.
+ */
+function splitDelimArms(body: string): string[] | null {
+  const arms: string[] = []
+  let depth = 0
+  let last = 0
+  let i = 0
+  while (i < body.length) {
+    const ch = body[i]
+    if (ch === '\\') { i += 2; continue }
+    if (ch === '[') {
+      let j = i + 1
+      if (body[j] === '^') j++
+      while (j < body.length && body[j] !== ']') {
+        if (body[j] === '\\') j += 2
+        else j++
+      }
+      if (body[j] !== ']') return null
+      i = j + 1
+      continue
+    }
+    if (ch === '(') { depth++; i++; continue }
+    if (ch === ')') { depth--; if (depth < 0) return null; i++; continue }
+    if (ch === '|' && depth === 0) { arms.push(body.slice(last, i)); last = i + 1 }
+    i++
+  }
+  if (depth !== 0) return null
+  arms.push(body.slice(last))
+  return arms
+}
+
+/**
+ * Prove that the `delimited` lowering — "scan the raw input to the first full
+ * `close` literal, ignoring the body entirely" — is EQUIVALENT to the real regex
+ * `<open>(?:body)*<close>`. That equivalence holds iff `(?:body)*` can never
+ * match a string that contains the `close` literal: then greedy repetition stops
+ * exactly before the first `close`, which is where the scan lands too.
+ *
+ * We only prove this for the two-code-point delimiter-safe idiom (the sole shape that expresses
+ * "any char that doesn't form the close"):
+ *
+ *   n === 1 (`close` is one char l0):   body must be exactly `[^l0]`.
+ *   n === 2 (`close` is `l0 l1`):       body must be exactly `[^l0] | l0(?!l1)`.
+ *
+ * In both the bulk arm `[^l0]` consumes every char except l0, and the guard arm
+ * (n === 2) consumes l0 only when it is NOT followed by l1 — so the body admits
+ * l0 but never the full `l0 l1`, and rejects NOTHING else (a body that excluded
+ * some non-close char would stop early while the raw scan skipped ahead to the
+ * next close, diverging). Anything outside this template — an alternation whose
+ * arms can consume the close (`z(?:a|[0-2]+)*a`), a bulk class narrower/wider
+ * than `[^l0]`, a longer close, extra arms — is declined, falling through to
+ * `RegExp.exec`. Sound-by-construction: we only ever return true for a body we
+ * can prove never contains `close`.
+ */
+function delimitedBodySound(body: string, close: number[]): boolean {
+  const l0 = close[0]!
+  if (close.length > 2) return false
+  const arms = splitDelimArms(body)
+  if (!arms) return false
+  let bulkSeen = false
+  let guardSeen = false
+  for (const arm of arms) {
+    // Bulk arm: a bare negated class `[^l0]` — excluded set is exactly {l0}.
+    const bulk = /^\[\^((?:\\.|[^\]])+)\]$/.exec(arm)
+    if (bulk) {
+      if (bulkSeen) return false
+      const ranges = parseClassRanges(bulk[1]!)
+      if (!ranges || ranges.length !== 1 || ranges[0]![0] !== l0 || ranges[0]![1] !== l0) return false
+      bulkSeen = true
+      continue
+    }
+    // Guard arm (n === 2 only): `l0(?!l1)` — consume l0 unless it starts the close.
+    if (close.length === 2 && arm.endsWith(')')) {
+      const idx = arm.indexOf('(?!')
+      if (idx === -1) return false
+      const prefix = literalCodePoints(arm.slice(0, idx))
+      const op = parseClassOperand(arm.slice(idx + 3, -1))
+      const prefixIsL0 = prefix?.length === 1 && prefix[0] === l0
+      const forbidsL1 = op && !op.negated && op.ranges.length === 1 &&
+        op.ranges[0]![0] === close[1] && op.ranges[0]![1] === close[1]
+      if (!prefixIsL0 || !forbidsL1 || guardSeen) return false
+      guardSeen = true
+      continue
+    }
+    return false
+  }
+  // Require the exact arm set: bulk always; guard iff the close is two chars.
+  return bulkSeen && guardSeen === (close.length === 2)
+}
+
+/**
+ * Structurally recognize `<openLit>(?:<body>)*<closeLit>` — literal opener, a
+ * single non-capturing `*`-repeated group, literal closer — and lower it to a
+ * `delimited` scan ONLY when `delimitedBodySound` proves the body can't contain
+ * the close. Returns null (→ fall through to `seq`/`RegExp.exec`) otherwise.
+ */
+function parseDelimited(source: string): ScanShape | null {
+  // An escape-aware body (a literal `\\` in the source ⇒ string-like) is handled
+  // by `parseStringShape`; here "scan to first close" would wrongly stop at an
+  // escaped delimiter, so decline.
+  if (source.includes('\\\\')) return null
+  // Opener: literal chars up to the first unescaped `(`, which must open `(?:`.
+  let i = 0
+  while (i < source.length && source[i] !== '(') {
+    i += source[i] === '\\' ? 2 : 1
+  }
+  if (source[i] !== '(' || source[i + 1] !== '?' || source[i + 2] !== ':') return null
+  const openFrag = source.slice(0, i)
+  // Balanced scan of the group body to its matching `)`.
+  let k = i + 3
+  let depth = 1
+  while (k < source.length && depth > 0) {
+    const ch = source[k]
+    if (ch === '\\') { k += 2; continue }
+    if (ch === '[') {
+      let j = k + 1
+      if (source[j] === '^') j++
+      while (j < source.length && source[j] !== ']') {
+        if (source[j] === '\\') j += 2
+        else j++
+      }
+      if (source[j] !== ']') return null
+      k = j + 1
+      continue
+    }
+    if (ch === '(') depth++
+    else if (ch === ')') depth--
+    k++
+  }
+  if (depth !== 0) return null
+  const body = source.slice(i + 3, k - 1)
+  if (source[k] !== '*') return null
+  const closeFrag = source.slice(k + 1)
+  const open = literalCodePoints(openFrag)
+  const close = literalCodePoints(closeFrag)
+  if (!open || !close || !delimitedBodySound(body, close)) return null
+  return { kind: 'delimited', open, close }
+}
+
+function parseScanShapeCore(source: string): ScanShape | null {
+  // [X]+ / [X]* — a positive char-class run. A negated `[^X]+`/`[^X]*` is left to
+  // the general `seq` path (which lowers `[^X]+` and declines zero-width `[^X]*`).
+  let m = /^\[((?:\\.|[^\]])+)\]([+*])$/.exec(source)
+  if (m && !m[1]!.startsWith('^')) {
+    const ranges = parseClassRanges(m[1]!)
+    return ranges ? { kind: 'chars', ranges, minOne: m[2] === '+' } : null
+  }
+  // \d+ / \w+ / \s+ / \d* / \w* / \s* — a bare shorthand-class run.
+  m = /^\\([dws])([+*])$/.exec(source)
+  if (m) {
+    return { kind: 'chars', ranges: shorthandRanges(m[1] as 'd' | 'w' | 's'), minOne: m[2] === '+' }
+  }
+  // <head><tail>* — identifier run: one head char, then a run of tail chars.
+  m = /^(\[(?:\\.|[^\]])+\]|\\[dws])(\[(?:\\.|[^\]])+\]|\\[dws])\*$/.exec(source)
+  if (m) {
+    const head = classToRanges(m[1]!)
+    const tail = classToRanges(m[2]!)
+    if (head && tail) return { kind: 'ident', head, tail }
+  }
+  // <q>(?:[^q\\]|\\.)*<q> — a quote-delimited string with escapes.
+  const str = parseStringShape(source)
+  if (str) return str
+  // <lit>[^X]* — consume a literal opener, then run until a terminator char.
+  m = /^(.*?)\[\^((?:\\.|[^\]])+)\]\*$/.exec(source)
+  if (m) {
+    const open = literalCodePoints(m[1]!)
+    const stop = parseClassRanges(m[2]!)
+    if (open && stop) return { kind: 'until', open, stop }
+  }
+  // <open>(?:…)*<close> — delimited token scanned to its first close literal.
+  // Only lowered when the body provably can't contain the close (see
+  // `parseDelimited` / `delimitedBodySound`); any other `X(?:…)*Y` declines here
+  // and falls through to the `seq` path / `RegExp.exec`.
+  const delim = parseDelimited(source)
+  if (delim) return delim
+  // General category: a linear chain of literals + char runs (optional prefixes,
+  // literal openers, negated runs), lowered only when unambiguously greedy.
+  const parts = parseSeqParts(source)
+  if (parts && seqIsUnambiguous(parts)) return { kind: 'seq', parts }
+  return null
+}
+
+/**
+ * Flag-aware wrapper around `parseScanShape`. Lowering to a raw code-point scan
+ * assumes default regex semantics, so any flag that changes matching (`i` case
+ * folding, `u` surrogate handling, `m`/`s` anchor/dot behavior) disables it.
+ * `g`/`y` are stickiness-only and safe.
+ */
+export function scanShapeFromRegex(source: string, flags: string): ScanShape | null {
+  if (/[msu]/.test(flags)) return null
+  if (/i/.test(flags)) return caseFoldShape(source)
+  return parseScanShape(source)
+}
+
+/**
+ * Case-insensitive (`/i`) scannable shapes. Beyond a pure case-fold literal
+ * (`litFold`), this recognizes a top-level alternation of literals (an ordered
+ * `alt` of litFolds — CSS `(?:and|or)`, `(?:media|container|supports)`), each
+ * optionally wrapped in a trailing lookahead boundary (`(?![-\w])`, `(?=\()`).
+ * That last form is the regex spelling of `makeWord` — a keyword plus a word
+ * boundary — the common CSS at-rule/keyword dispatcher. Anything else declines
+ * (→ `RegExp.exec`); a false read here can only fail to lower, never mis-lower.
+ */
+function caseFoldShape(source: string): ScanShape | null {
+  const la = stripTrailingLookahead(source)
+  if (la) {
+    const inner = caseFoldLiteralOrAlt(la.base)
+    if (!inner) return null
+    const operand: CharSet = { ranges: la.ranges, negated: la.classNegated }
+    if (!lookaheadUnambiguous(inner, operand, la.negative)) return null
+    return { kind: 'lookahead', inner, ranges: la.ranges, classNegated: la.classNegated, negative: la.negative }
+  }
+  return caseFoldLiteralOrAlt(source)
+}
+
+/** A case-fold literal, or a top-level `a|b|c` alternation of pure literals. */
+function caseFoldLiteralOrAlt(source: string): ScanShape | null {
+  // `foldEq` only folds ASCII letters (65–90 / 97–122). A non-ASCII code point
+  // with a Unicode case pair (é/É, ä/Ä, …) would be emitted as an exact compare
+  // and silently miss its alternate case — a mis-lower, not just a failed lower.
+  // Decline those so they fall back to `RegExp.exec` (correct Unicode folding),
+  // preserving this file's "a false read can only fail to lower, never mis-lower".
+  const asciiOnly = (cps: number[]): boolean => cps.every(cp => cp <= 127)
+
+  const open = literalCodePoints(source)
+  if (open) return asciiOnly(open) ? { kind: 'litFold', open } : null
+  // `splitTopLevelAlternation` unwraps the outer group itself, so no pre-strip.
+  const arms = splitTopLevelAlternation(source)
+  if (!arms || arms.length < 2) return null
+  const litArms: ScanShape[] = []
+  for (const arm of arms) {
+    const cp = literalCodePoints(arm)
+    if (!cp || !asciiOnly(cp)) return null
+    litArms.push({ kind: 'litFold', open: cp })
+  }
+  // Ordered choice: each litFold arm case-folds on its own, so skipping the
+  // first-char dispatch guard (disjoint:false, firsts:null) is always correct —
+  // it just tries arms in order, exactly like regex `|`.
+  return { kind: 'alt', arms: litArms, disjoint: false, firsts: litArms.map(() => null) }
+}
+
+/**
+ * `PARSEMAN_SCANTO=indexof` swaps the single-stop-char `until` scan loop for
+ * `String.prototype.indexOf`. Defaults OFF so a baseline build is provably
+ * byte-identical to the unmodified compiler, which is what makes the A/B a
+ * toggle rather than two different compilers (docs/design/derived-tokenization.md
+ * §16.3: the gate is a byte-identical parse tree against a toggled baseline).
+ */
+const scanToIndexOfEnabled = (): boolean => process.env.PARSEMAN_SCANTO === 'indexof'
+
+export const classCond = (cVar: string, ranges: Array<[number, number]>): string =>
+  ranges
+    .map(([lo, hi]) => (lo === hi ? `${cVar} === ${lo}` : `(${cVar} >= ${lo} && ${cVar} <= ${hi})`))
+    .join(' || ')
+
+/** Literal-match condition at `base + k` for each code point; uses `firstVar` at offset 0. */
+export const litCond = (base: string, cps: number[], firstVar?: string): string =>
+  cps
+    .map((cp, k) =>
+      k === 0 && firstVar
+        ? `${firstVar} === ${cp}`
+        : `input.charCodeAt(${base}${k ? ` + ${k}` : ''}) === ${cp}`,
+    )
+    .join(' && ')
+
+/** Line-terminator code points `.` does not match (`\n \r \u2028 \u2029`). */
+export const LINE_TERMINATORS = [10, 13, 8232, 8233] as const
+
+/** The body-stop chars that abort a string match (excluded set minus quote/backslash). */
+export function stringHardStop(
+  shape: Extract<ScanShape, { kind: 'string' }>,
+): Array<[number, number]> {
+  return shape.excluded.filter(
+    ([lo, hi]) => !(lo === hi && (lo === shape.quote || lo === BACKSLASH)),
+  )
+}
+
+/** Mints a fresh, unique local variable name (`prefix` + counter). */
+export type Mint = (prefix?: string) => string
+
+/**
+ * The SINGLE source of truth for how a scannable shape matches at `start`. Both
+ * the terminal emitter and the trivia scan loop consume this, so no context can
+ * silently reinterpret an incomplete match (e.g. an unterminated string):
+ *
+ *   - `setup`   statements (indented by `ind`) that compute the match.
+ *   - `ok`      a boolean expr: did a token match at `start`? (zero-width for
+ *               `chars*` counts as a match — terminals allow it.)
+ *   - `end`     the position AFTER the token. **Invariant:** `end === start`
+ *               whenever there is no progress (match failed or matched empty),
+ *               so the trivia loop can gate purely on `end > start`.
+ *
+ * `firstChar`, when supplied, is an expression already equal to
+ * `charCodeAt(start)` (the trivia loop reads it once and shares it).
+ */
+export type ShapeMatch = { setup: string[]; ok: string; end: string }
+
+const codeAt = (start: string, firstChar?: string): string =>
+  firstChar ?? `input.charCodeAt(${start})`
+
+// Dispatch-planning thresholds for a disjoint alt's first-char `switch` — same
+// tuning as codegen's `planDisjointDispatch` (kept local to avoid a scannable-run
+// → codegen import cycle): only worth a jump table when every arm keys off a few
+// DISCRETE points; a wide range (`[a-z]+`) would explode into dozens of cases.
+const ALT_SWITCH_RANGE_LIMIT = 4
+const ALT_SWITCH_MAX_CASES = 48
+const ALT_SWITCH_MIN_CASES = 3
+
+/**
+ * A `switch` jump table for a *disjoint* alt when every arm's first-set is a few
+ * discrete code points (operator/keyword first chars); else `{ kind: 'if' }` to
+ * keep the range-comparison `if/else if` chain. Arms are pairwise-disjoint, so
+ * each code point maps to exactly one arm.
+ */
+function planAltSwitch(firsts: Array<CharSet | null>): { kind: 'switch'; cases: number[][] } | { kind: 'if' } {
+  const cases: number[][] = []
+  let total = 0
+  for (const fs of firsts) {
+    if (!fs || fs.negated) return { kind: 'if' } // any / negated → no discrete keys
+    const pts: number[] = []
+    for (const [lo, hi] of fs.ranges) {
+      if (hi - lo + 1 > ALT_SWITCH_RANGE_LIMIT) return { kind: 'if' }
+      for (let cp = lo; cp <= hi; cp++) pts.push(cp)
+    }
+    total += pts.length
+    if (total > ALT_SWITCH_MAX_CASES) return { kind: 'if' }
+    cases.push(pts)
+  }
+  return total >= ALT_SWITCH_MIN_CASES ? { kind: 'switch', cases } : { kind: 'if' }
+}
+
+export function emitShapeMatch(
+  shape: ScanShape,
+  start: string,
+  mint: Mint,
+  ind: string,
+  firstChar?: string,
+): ShapeMatch {
+  if (shape.kind === 'lookahead') {
+    const inner = emitShapeMatch(shape.inner, start, mint, ind, firstChar)
+    const okV = mint('_ok')
+    const endV = mint('_end')
+    // `charInClass` folds the operand's OWN `[^…]` negation in; `guardFails`
+    // then applies the lookahead's `!`/`=` polarity on top. Zero-width: `end`
+    // is always `inner.end` (on success) or `start` (on failure) — never past
+    // where `inner` itself stopped.
+    const rawIn = classCond(`input.charCodeAt(${inner.end})`, shape.ranges)
+    const charInClass = shape.classNegated ? `!(${rawIn})` : `(${rawIn})`
+    const hasMatchingChar = `${inner.end} < input.length && ${charInClass}`
+    const guardFails = shape.negative ? hasMatchingChar : `!(${hasMatchingChar})`
+    return {
+      setup: [
+        ...inner.setup,
+        `${ind}let ${okV} = ${inner.ok}`,
+        `${ind}let ${endV} = ${inner.end}`,
+        `${ind}if (${okV} && (${guardFails})) { ${okV} = false; ${endV} = ${start} }`,
+      ],
+      ok: okV,
+      end: endV,
+    }
+  }
+
+  if (shape.kind === 'alt') {
+    const okV = mint('_ok')
+    const endV = mint('_end')
+    const lines: string[] = [`${ind}let ${okV} = false`, `${ind}let ${endV} = ${start}`]
+    // Fast path: an alternation of case-fold literals (CSS keyword lists like
+    // `@media|@container|@supports`, `even|odd`) → a `switch` on the first char
+    // that jumps straight to the matching group, tails compared with the bit-OR
+    // fold. Measured ~2.4x over the ordered if-chain / ~1.4x over per-arm bit-OR.
+    // Ordered-choice is preserved: arms are grouped by their FOLDED first code
+    // point and, within a group, emitted in source order (first match wins);
+    // arms in different groups can't both match a given first char.
+    if (shape.arms.length >= 2 && shape.arms.every(a => a.kind === 'litFold' && a.open.length >= 1)) {
+      const groups = new Map<number, number[][]>()
+      for (const a of shape.arms) {
+        const open = (a as Extract<ScanShape, { kind: 'litFold' }>).open
+        const f = open[0]!
+        const lower = f >= 65 && f <= 90 ? f + 32 : f
+        ;(groups.get(lower) ?? groups.set(lower, []).get(lower)!).push(open)
+      }
+      lines.push(`${ind}if (${start} < input.length) switch (${codeAt(start, firstChar)}) {`)
+      for (const [lower, arms] of groups) {
+        const labels = lower >= 97 && lower <= 122 ? `case ${lower}: case ${lower - 32}:` : `case ${lower}:`
+        lines.push(`${ind}  ${labels} {`)
+        for (const open of arms) {
+          const tail = open.slice(1).map((cp, i) => foldEq(`input.charCodeAt(${start} + ${i + 1})`, cp))
+          const cond = tail.length ? ` && ${tail.join(' && ')}` : ''
+          lines.push(`${ind}    if (${start} + ${open.length} <= input.length${cond}) { ${okV} = true; ${endV} = ${start} + ${open.length}; break }`)
+        }
+        lines.push(`${ind}    break`)
+        lines.push(`${ind}  }`)
+      }
+      lines.push(`${ind}}`)
+      return { setup: lines, ok: okV, end: endV }
+    }
+    if (shape.disjoint) {
+      // Mutually exclusive first-sets: dispatch straight to the one matching
+      // arm, no ordering/backtracking concerns (§7b-style disjoint dispatch). A
+      // `switch` jump table when arms key off discrete first chars, else the
+      // range-comparison `if/else if` chain (same plan as codegen's choice()).
+      const plan = planAltSwitch(shape.firsts)
+      if (plan.kind === 'switch') {
+        lines.push(`${ind}if (${start} < input.length) switch (${codeAt(start, firstChar)}) {`)
+        shape.arms.forEach((arm, k) => {
+          const labels = plan.cases[k]!.map(cp => `case ${cp}:`).join(' ')
+          const m = emitShapeMatch(arm, start, mint, `${ind}    `, firstChar)
+          lines.push(`${ind}  ${labels} {`)
+          lines.push(...m.setup)
+          lines.push(`${ind}    ${okV} = ${m.ok}`)
+          lines.push(`${ind}    ${endV} = ${m.ok} ? ${m.end} : ${start}`)
+          lines.push(`${ind}    break`)
+          lines.push(`${ind}  }`)
+        })
+        lines.push(`${ind}}`)
+      } else {
+        const c0 = codeAt(start, firstChar)
+        shape.arms.forEach((arm, k) => {
+          const fs = shape.firsts[k]! // non-null whenever `disjoint` is true
+          const cond = fs.negated ? `!(${classCond(c0, fs.ranges)})` : `(${classCond(c0, fs.ranges)})`
+          const m = emitShapeMatch(arm, start, mint, `${ind}  `, firstChar)
+          lines.push(`${ind}${k === 0 ? 'if' : 'else if'} (${start} < input.length && ${cond}) {`)
+          lines.push(...m.setup)
+          lines.push(`${ind}  ${okV} = ${m.ok}`)
+          lines.push(`${ind}  ${endV} = ${m.ok} ? ${m.end} : ${start}`)
+          lines.push(`${ind}}`)
+        })
+      }
+    } else {
+      // Overlapping first-sets: ordered choice — try each arm in turn and take
+      // the first that succeeds. This is exactly regex `|`'s own semantics:
+      // first alternative to match AT ALL wins on ITS OWN greedy length, never
+      // compared against a later alternative's (possibly longer) match.
+      const lbl = mint('_alt')
+      lines.push(`${ind}${lbl}: {`)
+      for (const arm of shape.arms) {
+        const m = emitShapeMatch(arm, start, mint, `${ind}  `, firstChar)
+        lines.push(...m.setup)
+        lines.push(`${ind}  if (${m.ok}) { ${okV} = true; ${endV} = ${m.end}; break ${lbl} }`)
+      }
+      lines.push(`${ind}}`)
+    }
+    return { setup: lines, ok: okV, end: endV }
+  }
+
+  if (shape.kind === 'chars') {
+    const cur = mint('_e')
+    return {
+      setup: [
+        `${ind}let ${cur} = ${start}`,
+        `${ind}while (${cur} < input.length && (${classCond(`input.charCodeAt(${cur})`, shape.ranges)})) ${cur}++`,
+      ],
+      // `*` always matches (possibly empty); `+` needs at least one char.
+      ok: shape.minOne ? `${cur} > ${start}` : 'true',
+      end: cur,
+    }
+  }
+
+  if (shape.kind === 'ident') {
+    const cur = mint('_e')
+    return {
+      setup: [
+        `${ind}let ${cur} = ${start}`,
+        `${ind}if (${start} < input.length && (${classCond(codeAt(start, firstChar), shape.head)})) {`,
+        `${ind}  ${cur} = ${start} + 1`,
+        `${ind}  while (${cur} < input.length && (${classCond(`input.charCodeAt(${cur})`, shape.tail)})) ${cur}++`,
+        `${ind}}`,
+      ],
+      ok: `${cur} > ${start}`,
+      end: cur,
+    }
+  }
+
+  if (shape.kind === 'seq') {
+    const endV = mint('_e')
+    const okV = mint('_ok')
+    const runCond = (p: Extract<SeqPart, { part: 'run' }>, at: string) => {
+      const c = classCond(`input.charCodeAt(${at})`, p.ranges)
+      return p.negated ? `!(${c})` : `(${c})`
+    }
+    const lines = [`${ind}let ${endV} = ${start}`, `${ind}let ${okV} = false`, `${ind}do {`]
+    let first = true
+    for (const p of shape.parts) {
+      if (p.part === 'lit') {
+        const L = p.cps.length
+        const cond = litCond(endV, p.cps, first ? firstChar : undefined)
+        if (p.optional) {
+          lines.push(`${ind}  if (${endV} + ${L} <= input.length && (${cond})) ${endV} += ${L}`)
+        } else {
+          lines.push(`${ind}  if (!(${endV} + ${L} <= input.length && (${cond}))) break`)
+          lines.push(`${ind}  ${endV} += ${L}`)
+        }
+      } else if (p.part === 'run' && p.max === Infinity) {
+        // Unbounded run (`+`/`*`/`{n,}`): greedy scan, then enforce the minimum.
+        const s = mint('_s')
+        lines.push(`${ind}  const ${s} = ${endV}`)
+        lines.push(`${ind}  while (${endV} < input.length && ${runCond(p, endV)}) ${endV}++`)
+        if (p.min === 1) lines.push(`${ind}  if (${endV} === ${s}) break`)
+        else if (p.min > 1) lines.push(`${ind}  if (${endV} - ${s} < ${p.min}) break`)
+      } else if (p.part === 'run' && p.max === 1) {
+        // Exactly one char: required (min 1) or optional (min 0).
+        if (p.min === 1) {
+          lines.push(`${ind}  if (!(${endV} < input.length && ${runCond(p, endV)})) break`)
+          lines.push(`${ind}  ${endV}++`)
+        } else {
+          lines.push(`${ind}  if (${endV} < input.length && ${runCond(p, endV)}) ${endV}++`)
+        }
+      } else if (p.part === 'run') {
+        // Bounded counted run `[x]{min,max}` (§8c), max ≥ 2: consume up to `max`
+        // occurrences, then require at least `min` (greedy — sound because
+        // `seqIsUnambiguous` proved any wiggle is disjoint from what follows).
+        const s = mint('_s')
+        lines.push(`${ind}  const ${s} = ${endV}`)
+        lines.push(`${ind}  while (${endV} - ${s} < ${p.max} && ${endV} < input.length && ${runCond(p, endV)}) ${endV}++`)
+        if (p.min > 0) lines.push(`${ind}  if (${endV} - ${s} < ${p.min}) break`)
+      } else {
+        // `group` (§8f): the group's own body is just another `ScanShape` —
+        // recurse via `emitShapeMatch`, then splice its setup in as the body
+        // of a required-once check, an optional take, or a repeat loop.
+        const inner = emitShapeMatch(p.inner, endV, mint, `${ind}  `, first ? firstChar : undefined)
+        if (!p.unbounded) {
+          lines.push(...inner.setup)
+          if (p.min === 1) {
+            lines.push(`${ind}  if (!(${inner.ok})) break`)
+            lines.push(`${ind}  ${endV} = ${inner.end}`)
+          } else {
+            lines.push(`${ind}  if (${inner.ok}) ${endV} = ${inner.end}`)
+          }
+        } else {
+          const progV = mint('_prog')
+          lines.push(`${ind}  let ${progV} = false`)
+          lines.push(`${ind}  while (true) {`)
+          lines.push(...inner.setup)
+          lines.push(`${ind}    if (!(${inner.ok})) break`)
+          lines.push(`${ind}    ${endV} = ${inner.end}`)
+          lines.push(`${ind}    ${progV} = true`)
+          lines.push(`${ind}  }`)
+          if (p.min === 1) lines.push(`${ind}  if (!${progV}) break`)
+        }
+      }
+      first = false
+    }
+    lines.push(`${ind}  ${okV} = true`)
+    lines.push(`${ind}} while (false)`)
+    lines.push(`${ind}if (!${okV}) ${endV} = ${start}`)
+    return { setup: lines, ok: okV, end: endV }
+  }
+
+  if (shape.kind === 'litFold') {
+    const openLen = shape.open.length
+    const endV = mint('_end')
+    const checks = shape.open.map((cp, k) => {
+      const cVar = k === 0 && firstChar ? firstChar : `input.charCodeAt(${start} + ${k})`
+      return foldEq(cVar, cp)
+    })
+    return {
+      setup: [
+        `${ind}let ${endV} = ${start}`,
+        `${ind}if (${start} + ${openLen} <= input.length && (${checks.join(' && ')})) ${endV} = ${start} + ${openLen}`,
+      ],
+      ok: `${endV} > ${start}`,
+      end: endV,
+    }
+  }
+
+  if (shape.kind === 'until') {
+    const j = mint('_j')
+    const openLen = shape.open.length
+    const openChk = openLen === 1
+      ? `${codeAt(start, firstChar)} === ${shape.open[0]}`
+      : litCond(start, shape.open, firstChar)
+    // A SINGLE stop code point makes this scan a `memchr`, and V8 implements
+    // `String.prototype.indexOf` with a SIMD one. Measured 4.3x over the char
+    // loop on a 0.97 MiB corpus, 61 of 61 interleaved rounds
+    // (scratchpad/native-primitive-bakeoff/micro-scanto.mjs, regime (a)).
+    // Semantics are identical: the loop stops at the first stop char or at
+    // `input.length`, which is exactly `indexOf`'s hit / not-found pair.
+    // Multi-member stop sets stay on the loop — 3x indexOf + min measured at
+    // parity (0.992), because the min-reduce rescans the tail and discards it.
+    const stopCp =
+      shape.stop.length === 1 && shape.stop[0]![0] === shape.stop[0]![1] ? shape.stop[0]![0] : null
+    const scanLine =
+      stopCp !== null && stopCp <= 0xffff && scanToIndexOfEnabled()
+        ? // No temp is minted: a temp would renumber every later variable in the
+          // function and show up as an artifact-size delta that is counter
+          // renumbering rather than this change (the §9.1.4 / §9.2 effect).
+          `${ind}  ${j} = input.indexOf(${JSON.stringify(String.fromCharCode(stopCp))}, ${j})` +
+          `; if (${j} < 0) ${j} = input.length`
+        : `${ind}  while (${j} < input.length && !(${classCond(`input.charCodeAt(${j})`, shape.stop)})) ${j}++`
+    return {
+      setup: [
+        `${ind}let ${j} = ${start}`,
+        `${ind}if (${start} + ${openLen} <= input.length && (${openChk})) {`,
+        `${ind}  ${j} = ${start} + ${openLen}`,
+        scanLine,
+        `${ind}}`,
+      ],
+      // An open-until-terminator always completes (stop char or EOF), so a matched
+      // open literal is a full match; `end === start` iff the open didn't match.
+      ok: `${j} > ${start}`,
+      end: j,
+    }
+  }
+
+  if (shape.kind === 'string') {
+    const okV = mint('_ok')
+    const endV = mint('_end')
+    const i = mint('_i')
+    const c2 = mint('_c')
+    const hard = stringHardStop(shape)
+    const ltLines = shape.escLineTerm
+      ? []
+      : (() => {
+          const c3 = mint('_c')
+          return [
+            `${ind}      const ${c3} = input.charCodeAt(${i} + 1)`,
+            `${ind}      if (${LINE_TERMINATORS.map(t => `${c3} === ${t}`).join(' || ')}) break`,
+          ]
+        })()
+    return {
+      setup: [
+        `${ind}let ${okV} = false`,
+        `${ind}let ${endV} = ${start}`,
+        `${ind}if (${start} < input.length && (${codeAt(start, firstChar)}) === ${shape.quote}) {`,
+        `${ind}  let ${i} = ${start} + 1`,
+        `${ind}  while (${i} < input.length) {`,
+        `${ind}    const ${c2} = input.charCodeAt(${i})`,
+        `${ind}    if (${c2} === ${shape.quote}) { ${okV} = true; ${endV} = ${i} + 1; break }`,
+        `${ind}    if (${c2} === ${BACKSLASH}) {`,
+        `${ind}      if (${i} + 1 >= input.length) break`,
+        ...ltLines,
+        `${ind}      ${i} += 2`,
+        `${ind}      continue`,
+        `${ind}    }`,
+        ...(hard.length ? [`${ind}    if (${classCond(c2, hard)}) break`] : []),
+        `${ind}    ${i}++`,
+        `${ind}  }`,
+        `${ind}}`,
+      ],
+      ok: okV,
+      end: endV,
+    }
+  }
+
+  // delimited: <open>…<close>, requires the close literal (unclosed ⇒ no match).
+  const j = mint('_j')
+  const endV = mint('_end')
+  const openLen = shape.open.length
+  const closeLen = shape.close.length
+  const openChk = openLen === 1
+    ? `${codeAt(start, firstChar)} === ${shape.open[0]}`
+    : litCond(start, shape.open, firstChar)
+  const closeChk = litCond(j, shape.close)
+  // Scanning to a fixed close literal IS `indexOf`, and V8's is SIMD. The
+  // rewrite is exact: the loop stops at the first close literal at or after `j`,
+  // or runs out of room and leaves the token unterminated (no match). `indexOf`
+  // returns that same first index, or -1 for "never occurs" — mapped to
+  // `input.length`, which makes the `j + closeLen <= input.length` guard fail
+  // exactly where the loop's room check did. When it IS found the close literal
+  // matches by construction, so the guard's re-comparison is dropped.
+  const closeStr = String.fromCharCode(...shape.close)
+  const scanLines = scanToIndexOfEnabled()
+    ? [
+        `${ind}  ${j} = input.indexOf(${JSON.stringify(closeStr)}, ${j}); if (${j} < 0) ${j} = input.length`,
+        `${ind}  if (${j} + ${closeLen} <= input.length) ${endV} = ${j} + ${closeLen}`,
+      ]
+    : [
+        `${ind}  while (${j} + ${closeLen - 1} < input.length && !(${closeChk})) ${j}++`,
+        `${ind}  if (${j} + ${closeLen} <= input.length && (${closeChk})) ${endV} = ${j} + ${closeLen}`,
+      ]
+  return {
+    setup: [
+      `${ind}let ${j} = ${start}`,
+      `${ind}let ${endV} = ${start}`,
+      `${ind}if (${start} + ${openLen} <= input.length && (${openChk})) {`,
+      `${ind}  ${j} = ${start} + ${openLen}`,
+      ...scanLines,
+      `${ind}}`,
+    ],
+    ok: `${endV} > ${start}`,
+    end: endV,
+  }
+}