parseman 0.39.0 → 0.39.1

package/dist/index.cjs

@@ -57,6 +57,7 @@ __export(index_exports, {
   cstBuildHost: () => cstBuildHost,
   dispatch: () => dispatch,
   duplicationFindingCount: () => duplicationFindingCount,
+  endsWith: () => endsWith,
   expect: () => expect,
   extractCharClasses: () => extractCharClasses,
   field: () => field,
@@ -79,8 +80,10 @@ __export(index_exports, {
   lineBreaksIn: () => lineBreaksIn,
   lineStartWithin: () => lineStartWithin,
   literal: () => literal,
+  makeWhen: () => makeWhen,
   makeWord: () => makeWord,
   many: () => many,
+  matches: () => matches,
   noTrivia: () => noTrivia,
   node: () => node,
   not: () => not,
@@ -97,6 +100,7 @@ __export(index_exports, {
   regex: () => regex,
   relativize: () => relativize,
   relativizeCST: () => relativizeCST,
+  routed: () => routed,
   rules: () => rules,
   run: () => run,
   runWithGrammarCoverage: () => runWithGrammarCoverage,
@@ -106,6 +110,7 @@ __export(index_exports, {
   shiftAbsolute: () => shiftAbsolute,
   siteToString: () => siteToString,
   skip: () => skip,
+  startsWith: () => startsWith,
   token: () => token,
   transform: () => transform,
   trivia: () => trivia,
@@ -171,6 +176,8 @@ function matchesEmpty(p, seen = /* @__PURE__ */ new Set(), resolve) {
       return d.value.length === 0;
     case "keywords":
       return false;
+    case "routed":
+      return false;
     case "regex":
       try {
         const m = new RegExp(d.source).exec("");
@@ -1232,6 +1239,8 @@ function derive(c, seen) {
     case "not":
     case "peek":
       return deriveExpected2(def.parser);
+    case "routed":
+      return ["routed()"];
     case "lazy": {
       const name = c._ruleName;
       if (seen.has(c)) return name ? [name] : [];
@@ -2056,42 +2065,198 @@ function sequence(...parsers) {
 }
 
 // src/combinators/dispatch.ts
-function when(key, parser2) {
+function parserUsesRouted(parser2, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(parser2)) return false;
+  seen.add(parser2);
+  const def = parser2._def;
+  switch (def.tag) {
+    case "routed":
+      return true;
+    case "sequence":
+    case "choice":
+      return def.parsers.some((entry) => parserUsesRouted(entry, seen));
+    case "dispatch":
+      return false;
+    case "sepBy":
+      return parserUsesRouted(def.parser, seen) || parserUsesRouted(def.separator, seen);
+    case "skip":
+      return parserUsesRouted(def.main, seen) || parserUsesRouted(def.skipped, seen);
+    case "grammar":
+      return parserUsesRouted(def.parser, seen) || (def.triviaParser ? parserUsesRouted(def.triviaParser, seen) : false);
+    case "scanTo":
+      return parserUsesRouted(def.sentinel, seen) || def.skip.some((entry) => parserUsesRouted(entry, seen));
+    case "recover":
+      return parserUsesRouted(def.parser, seen) || parserUsesRouted(def.sentinel, seen);
+    case "lazy":
+      try {
+        return parserUsesRouted(def.thunk(), seen);
+      } catch {
+        return false;
+      }
+    case "many":
+    case "oneOrMore":
+    case "optional":
+    case "attempt":
+    case "transform":
+    case "trivia":
+    case "token":
+    case "leaf":
+    case "label":
+    case "field":
+    case "not":
+    case "peek":
+    case "node":
+    case "withCtx":
+    case "expect":
+      return parserUsesRouted(def.parser, seen);
+    default:
+      return false;
+  }
+}
+function branchUsesRouted(branch) {
+  return branch.usesRouted === true || parserUsesRouted(branch.parser);
+}
+function asciiFoldKey(key) {
+  let out = "";
+  for (let i = 0; i < key.length; i++) {
+    const c = key.charCodeAt(i);
+    out += String.fromCharCode(c >= 65 && c <= 90 ? c + 32 : c);
+  }
+  return out;
+}
+function matchesDispatchMatcher(value, matcher) {
+  const candidate = matcher.caseInsensitive ? asciiFoldKey(value) : value;
+  const expected = matcher.caseInsensitive ? asciiFoldKey(matcher.value) : matcher.value;
+  switch (matcher.kind) {
+    case "startsWith":
+      return candidate.startsWith(expected);
+    case "endsWith":
+      return candidate.endsWith(expected);
+    case "matches": {
+      const flags = matcher.caseInsensitive && !matcher.flags?.includes("i") ? `${matcher.flags ?? ""}i` : matcher.flags ?? "";
+      return new RegExp(matcher.value, flags).test(value);
+    }
+  }
+}
+function isStringMatcher(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const kind = value.kind;
+  return kind === "startsWith" || kind === "endsWith" || kind === "matches";
+}
+function fixedMatcher(kind, value) {
+  if (typeof value !== "string") throw new TypeError(`parseman: ${kind}() value must be a string`);
+  if (value.length === 0) throw new RangeError(`parseman: ${kind}() requires a non-empty value`);
+  return { kind, value };
+}
+function startsWith(prefix) {
+  return fixedMatcher("startsWith", prefix);
+}
+function endsWith(suffix) {
+  return fixedMatcher("endsWith", suffix);
+}
+function matches(pattern) {
+  if (!(pattern instanceof RegExp)) throw new TypeError("parseman: matches() requires a RegExp");
+  if (pattern.flags.includes("g") || pattern.flags.includes("y")) {
+    throw new TypeError("parseman: matches() does not accept global or sticky regex flags");
+  }
+  return { kind: "matches", value: pattern.source, flags: pattern.flags };
+}
+function when(key, parser2, opts = {}) {
+  const usesRouted = parserUsesRouted(parser2);
+  if (isStringMatcher(key)) {
+    return { kind: "whenMatcher", matcher: key, parser: parser2, caseInsensitive: opts.caseInsensitive ?? false, usesRouted };
+  }
   const keys = Array.isArray(key) ? [...key] : [key];
   if (keys.length === 0) throw new RangeError("parseman: when() requires at least one key");
   for (const item of keys) {
     if (typeof item !== "string") throw new TypeError("parseman: when() keys must be strings");
   }
-  return { kind: "when", keys, parser: parser2 };
+  return { kind: "when", keys, parser: parser2, caseInsensitive: opts.caseInsensitive ?? false, usesRouted };
+}
+function makeWhen(opts = {}) {
+  return (key, parser2) => when(key, parser2, opts);
 }
 function otherwise(parser2) {
-  return { kind: "otherwise", parser: parser2 };
+  return { kind: "otherwise", parser: parser2, usesRouted: parserUsesRouted(parser2) };
+}
+function routed() {
+  return {
+    _tag: "routed",
+    _meta: { firstSet: { kind: "any" }, canMatchNewline: false, isTrivia: false },
+    _def: { tag: "routed" },
+    parse(_input, pos, ctx) {
+      const item = ctx._routed;
+      if (item === void 0) {
+        return { ok: false, expected: ["routed()"], span: { start: pos, end: pos } };
+      }
+      if (pos !== item.span.start) {
+        return { ok: false, expected: ["routed()"], span: { start: pos, end: pos } };
+      }
+      if (cstCaptureActive(ctx)) {
+        pushCstLeaf(ctx, { _tag: "leaf", value: item.value, span: item.span });
+      }
+      return { ok: true, value: item.value, span: item.span };
+    }
+  };
 }
 function dispatch(selector, ...arms) {
+  if (parserUsesRouted(selector)) {
+    throw new Error("parseman: routed() can only appear inside a dispatch() branch");
+  }
   let fallback;
+  let fallbackUsesRouted = false;
+  const matchers = [];
   const cases = [];
-  const seen = /* @__PURE__ */ new Set();
+  const seen = [];
   for (let i = 0; i < arms.length; i++) {
     const arm = arms[i];
     if (arm.kind === "otherwise") {
       if (fallback !== void 0) throw new Error("parseman: dispatch() accepts at most one otherwise() arm");
       if (i !== arms.length - 1) throw new Error("parseman: otherwise() must be the last dispatch() arm");
       fallback = arm.parser;
+      fallbackUsesRouted = arm.usesRouted === true;
       continue;
     }
-    for (const key of arm.keys) {
-      if (seen.has(key)) throw new Error(`parseman: duplicate dispatch key ${JSON.stringify(key)}`);
-      seen.add(key);
+    if (arm.kind === "whenMatcher") {
+      const matcher = arm.matcher;
+      matchers.push({
+        kind: matcher.kind,
+        value: matcher.value,
+        ...matcher.kind === "matches" ? { flags: matcher.flags } : {},
+        parser: arm.parser,
+        caseInsensitive: arm.caseInsensitive,
+        ...arm.usesRouted === true ? { usesRouted: true } : {}
+      });
+      continue;
     }
-    cases.push({ keys: arm.keys, parser: arm.parser });
+    for (const key of arm.keys) {
+      const folded = asciiFoldKey(key);
+      for (const prior of seen) {
+        const overlaps = arm.caseInsensitive || prior.caseInsensitive ? folded === prior.folded : key === prior.raw;
+        if (overlaps) throw new Error(`parseman: duplicate dispatch key ${JSON.stringify(key)}`);
+      }
+      seen.push({ raw: key, folded, caseInsensitive: arm.caseInsensitive });
+    }
+    cases.push({
+      keys: arm.keys,
+      parser: arm.parser,
+      caseInsensitive: arm.caseInsensitive,
+      ...arm.usesRouted === true ? { usesRouted: true } : {}
+    });
   }
   const meta = {
     firstSet: selector._meta.firstSet,
-    canMatchNewline: selector._meta.canMatchNewline || cases.some((entry) => entry.parser._meta.canMatchNewline) || (fallback?._meta.canMatchNewline ?? false),
+    canMatchNewline: selector._meta.canMatchNewline || cases.some((entry) => entry.parser._meta.canMatchNewline) || matchers.some((entry) => entry.parser._meta.canMatchNewline) || (fallback?._meta.canMatchNewline ?? false),
     isTrivia: false
   };
   const byKey = /* @__PURE__ */ new Map();
-  for (const entry of cases) for (const key of entry.keys) byKey.set(key, entry.parser);
+  const byFoldedKey = /* @__PURE__ */ new Map();
+  for (const entry of cases) {
+    for (const key of entry.keys) {
+      if (entry.caseInsensitive) byFoldedKey.set(asciiFoldKey(key), entry);
+      else byKey.set(key, entry);
+    }
+  }
   return {
     _tag: "dispatch",
     _meta: meta,
@@ -2099,18 +2264,35 @@ function dispatch(selector, ...arms) {
       tag: "dispatch",
       selector,
       cases,
-      ...fallback === void 0 ? {} : { otherwise: fallback }
+      ...matchers.length === 0 ? {} : { matchers },
+      ...fallback === void 0 ? {} : { otherwise: fallback, ...fallbackUsesRouted ? { otherwiseUsesRouted: true } : {} }
     },
     parse(input, pos, ctx) {
+      if (parserUsesRouted(selector)) {
+        throw new Error("parseman: routed() can only appear inside a dispatch() branch");
+      }
+      const selectorMark = saveTriviaMark(ctx);
       const selected = selector.parse(input, pos, ctx);
       if (!selected.ok) return selected;
-      const tail = byKey.get(selected.value) ?? fallback;
-      if (tail === void 0) {
+      const branch = byKey.get(selected.value) ?? (byFoldedKey.size === 0 ? void 0 : byFoldedKey.get(asciiFoldKey(selected.value))) ?? matchers.find((matcher) => matchesDispatchMatcher(selected.value, matcher)) ?? (fallback === void 0 ? void 0 : { keys: [], parser: fallback, caseInsensitive: false, usesRouted: fallbackUsesRouted });
+      if (branch === void 0) {
         const expected = cases.flatMap((entry) => entry.keys.map((key) => JSON.stringify(key)));
         return { ok: false, expected, span: { start: selected.span.end, end: selected.span.end } };
       }
-      const mark = saveTriviaMark(ctx);
-      const result = tail.parse(input, selected.span.end, ctx);
+      const savedRouted = ctx._routed;
+      const usesRouted = branchUsesRouted(branch);
+      let mark = saveTriviaMark(ctx);
+      if (usesRouted) {
+        rollbackTrivia(ctx, selectorMark);
+        mark = saveTriviaMark(ctx);
+        ctx._routed = { value: selected.value, span: selected.span };
+      }
+      let result;
+      try {
+        result = branch.parser.parse(input, usesRouted ? pos : selected.span.end, ctx);
+      } finally {
+        if (usesRouted) ctx._routed = savedRouted;
+      }
       if (!result.ok) {
         rollbackTrivia(ctx, mark);
         return { ...result, committed: true };
@@ -2497,6 +2679,7 @@ function markUnusedValues(root) {
       case "dispatch":
         visit(def.selector, consumed);
         for (const entry of def.cases) visit(entry.parser, consumed);
+        if (def.matchers) for (const entry of def.matchers) visit(entry.parser, consumed);
         if (def.otherwise) visit(def.otherwise, consumed);
         return;
       case "node":
@@ -2775,7 +2958,7 @@ function parserHasOwnFields(p, seen = /* @__PURE__ */ new Set()) {
     case "choice":
       return d.parsers.some((x) => parserHasOwnFields(x, seen));
     case "dispatch":
-      return parserHasOwnFields(d.selector, seen) || d.cases.some((x) => parserHasOwnFields(x.parser, seen)) || (d.otherwise ? parserHasOwnFields(d.otherwise, seen) : false);
+      return parserHasOwnFields(d.selector, seen) || d.cases.some((x) => parserHasOwnFields(x.parser, seen)) || (d.matchers ? d.matchers.some((entry) => parserHasOwnFields(entry.parser, seen)) : false) || (d.otherwise ? parserHasOwnFields(d.otherwise, seen) : false);
     case "sepBy":
       return parserHasOwnFields(d.parser, seen) || parserHasOwnFields(d.separator, seen);
     case "skip":
@@ -2844,7 +3027,7 @@ function parserHasTriviaSite(p, seen = /* @__PURE__ */ new Set()) {
     case "choice":
       return d.parsers.some((x) => parserHasTriviaSite(x, seen));
     case "dispatch":
-      return parserHasTriviaSite(d.selector, seen) || d.cases.some((x) => parserHasTriviaSite(x.parser, seen)) || (d.otherwise ? parserHasTriviaSite(d.otherwise, seen) : false);
+      return parserHasTriviaSite(d.selector, seen) || d.cases.some((x) => parserHasTriviaSite(x.parser, seen)) || (d.matchers ? d.matchers.some((entry) => parserHasTriviaSite(entry.parser, seen)) : false) || (d.otherwise ? parserHasTriviaSite(d.otherwise, seen) : false);
     case "grammar":
       return parserHasTriviaSite(d.parser, seen);
     case "lazy": {
@@ -2871,7 +3054,7 @@ function parserEnablesTriviaCapture(p, seen = /* @__PURE__ */ new Set()) {
     case "choice":
       return d.parsers.some((x) => parserEnablesTriviaCapture(x, seen));
     case "dispatch":
-      return parserEnablesTriviaCapture(d.selector, seen) || d.cases.some((x) => parserEnablesTriviaCapture(x.parser, seen)) || (d.otherwise ? parserEnablesTriviaCapture(d.otherwise, seen) : false);
+      return parserEnablesTriviaCapture(d.selector, seen) || d.cases.some((x) => parserEnablesTriviaCapture(x.parser, seen)) || (d.matchers ? d.matchers.some((entry) => parserEnablesTriviaCapture(entry.parser, seen)) : false) || (d.otherwise ? parserEnablesTriviaCapture(d.otherwise, seen) : false);
     case "sepBy":
       return parserEnablesTriviaCapture(d.parser, seen) || parserEnablesTriviaCapture(d.separator, seen);
     case "skip":
@@ -3273,7 +3456,7 @@ function leaf(root, fn) {
 }
 
 // src/version.ts
-var PARSEMAN_VERSION = "0.39.0";
+var PARSEMAN_VERSION = "0.39.1";
 
 // src/cst/host-mode.ts
 var FUSED_HOST_MODE = /* @__PURE__ */ Symbol.for("parseman.fusedHostMode");
@@ -3533,6 +3716,7 @@ function analyzeGatingRules(ruleMap, opts) {
     if (d.tag === "dispatch") {
       kids.push(d.selector);
       for (const c of d.cases) kids.push(c.parser);
+      if (d.matchers) for (const c of d.matchers) kids.push(c.parser);
       if (d.otherwise !== void 0) kids.push(d.otherwise);
     }
     if (Array.isArray(rec.skip)) kids.push(...rec.skip);
@@ -5056,13 +5240,25 @@ function escapeClassChar(ch2) {
 }
 
 // src/compiler/grammar-coverage-ids.ts
+function idPart(value) {
+  return encodeURIComponent(value);
+}
+function dispatchArmIds(def, path) {
+  const ids = [];
+  for (const entry of def.cases) ids.push(`dispatch:${path}/when:${entry.keys.map(idPart).join("|")}`);
+  for (const entry of def.matchers ?? []) {
+    ids.push(`dispatch:${path}/matcher:${entry.kind}:${idPart(entry.value)}${entry.kind === "matches" && entry.flags ? `:${idPart(entry.flags)}` : ""}`);
+  }
+  if (def.otherwise) ids.push(`dispatch:${path}/otherwise`);
+  return ids;
+}
 function children(def, winners) {
   switch (def.tag) {
     case "sequence":
     case "choice":
       return def.parsers;
     case "dispatch":
-      return [def.selector, ...def.cases.map((entry) => entry.parser), ...def.otherwise ? [def.otherwise] : []];
+      return [def.selector, ...def.cases.map((entry) => entry.parser), ...def.matchers ? def.matchers.map((entry) => entry.parser) : [], ...def.otherwise ? [def.otherwise] : []];
     case "many":
     case "oneOrMore":
     case "optional":
@@ -5105,6 +5301,7 @@ function children(def, winners) {
 function buildGrammarPlan(entry, winners) {
   const definitions = /* @__PURE__ */ new Map();
   const choices = /* @__PURE__ */ new WeakMap();
+  const dispatches = /* @__PURE__ */ new WeakMap();
   const attempts = /* @__PURE__ */ new WeakMap();
   const labels = /* @__PURE__ */ new WeakMap();
   const rules2 = /* @__PURE__ */ new WeakMap();
@@ -5135,6 +5332,11 @@ function buildGrammarPlan(entry, winners) {
       choices.set(parser2, ids);
       ids.forEach((id) => definitions.set(id, { id, kind: "choice-arm" }));
     }
+    if (parser2._def.tag === "dispatch") {
+      const ids = dispatchArmIds(parser2._def, path);
+      dispatches.set(parser2, ids);
+      ids.forEach((id) => definitions.set(id, { id, kind: "dispatch-arm" }));
+    }
     if (parser2._def.tag === "attempt") attempts.set(parser2, `attempt:${path}`);
     if (parser2._def.tag === "label") {
       const id = `label:${path}`;
@@ -5147,7 +5349,7 @@ function buildGrammarPlan(entry, winners) {
   for (const root of roots) {
     visit(root, winnerNames.get(root) ?? root._ruleName ?? "entry");
   }
-  return { definitions: [...definitions.values()].sort((a, b) => a.id.localeCompare(b.id)), choices, attempts, labels, rules: rules2 };
+  return { definitions: [...definitions.values()].sort((a, b) => a.id.localeCompare(b.id)), choices, dispatches, attempts, labels, rules: rules2 };
 }
 
 // src/compiler/scannable-run.ts
@@ -6521,6 +6723,7 @@ function leadingFirstSetRecipe(p, seen = /* @__PURE__ */ new Set()) {
       case "literal":
       case "regex":
       case "keywords":
+      case "routed":
         return { alts: [[seg(p._meta.firstSet, matchesEmpty(p))]] };
       case "choice": {
         const alts = [];
@@ -6871,7 +7074,7 @@ function mayLeavePartialCapture(p, seen = /* @__PURE__ */ new Set()) {
     case "choice":
       return false;
     case "dispatch":
-      return capturesLeaf(d.selector, seen) || d.cases.some((x) => mayLeavePartialCapture(x.parser, seen) || capturesLeaf(x.parser, seen)) || (d.otherwise ? mayLeavePartialCapture(d.otherwise, seen) || capturesLeaf(d.otherwise, seen) : false);
+      return capturesLeaf(d.selector, seen) || d.cases.some((x) => mayLeavePartialCapture(x.parser, seen) || capturesLeaf(x.parser, seen)) || (d.matchers ? d.matchers.some((x) => mayLeavePartialCapture(x.parser, seen) || capturesLeaf(x.parser, seen)) : false) || (d.otherwise ? mayLeavePartialCapture(d.otherwise, seen) || capturesLeaf(d.otherwise, seen) : false);
     case "attempt":
       return false;
     // optional never fails; many/oneOrMore only "fail" with zero captured items.
@@ -6970,6 +7173,7 @@ function capturesLeaf(p, seen = /* @__PURE__ */ new Set()) {
     case "keywords":
     case "node":
     case "token":
+    case "routed":
     case "leaf":
       return true;
     case "not":
@@ -6982,7 +7186,7 @@ function capturesLeaf(p, seen = /* @__PURE__ */ new Set()) {
     case "choice":
       return d.parsers.some((x) => capturesLeaf(x, seen));
     case "dispatch":
-      return capturesLeaf(d.selector, seen) || d.cases.some((x) => capturesLeaf(x.parser, seen)) || (d.otherwise ? capturesLeaf(d.otherwise, seen) : false);
+      return capturesLeaf(d.selector, seen) || d.cases.some((x) => capturesLeaf(x.parser, seen)) || (d.matchers ? d.matchers.some((entry) => capturesLeaf(entry.parser, seen)) : false) || (d.otherwise ? capturesLeaf(d.otherwise, seen) : false);
     case "sepBy":
       return capturesLeaf(d.parser, seen) || capturesLeaf(d.separator, seen);
     case "many":
@@ -7460,6 +7664,7 @@ function mayRecordRecoveryError(p, recovery, seen = /* @__PURE__ */ new Set()) {
       for (const item of d.cases) {
         if (mayRecordRecoveryError(item.parser, recovery, seen)) return true;
       }
+      if (d.matchers?.some((item) => mayRecordRecoveryError(item.parser, recovery, seen))) return true;
       return d.otherwise ? mayRecordRecoveryError(d.otherwise, recovery, seen) : false;
     }
     case "attempt":
@@ -7494,53 +7699,120 @@ function mayRecordRecoveryError(p, recovery, seen = /* @__PURE__ */ new Set()) {
       return false;
   }
 }
-function emitDispatchCombinator(def, ctx, pos) {
+function emitDispatchCombinator(parser2, def, ctx, pos) {
+  if (parserUsesRouted2(def.selector)) {
+    throw new Error("parseman: routed() can only appear inside a dispatch() branch");
+  }
+  const coverageIds = ctx.coverage?.plan.dispatches.get(parser2) ?? [];
+  const branchUsesRouted2 = (entry) => entry.usesRouted === true || parserUsesRouted2(entry.parser);
+  const hasRoutedBranch = def.cases.some(branchUsesRouted2) || (def.matchers ? def.matchers.some(branchUsesRouted2) : false) || (def.otherwise ? def.otherwiseUsesRouted === true || parserUsesRouted2(def.otherwise) : false);
+  const selectorLeafMark = hasRoutedBranch ? v(ctx, "_dsl") : null;
+  const selectorRawMark = hasRoutedBranch ? v(ctx, "_dsr") : null;
+  const selectorTriviaMark = hasRoutedBranch ? v(ctx, "_dst") : null;
+  const selectorLogMark = hasRoutedBranch ? v(ctx, "_dsg") : null;
+  const selectorFieldMark = hasRoutedBranch ? v(ctx, "_dsf") : null;
+  const selectorErrorMark = hasRoutedBranch ? v(ctx, "_dse") : null;
   const selector = emit(def.selector, ctx, pos);
   const outV = v(ctx, "_dval");
   const outE = v(ctx, "_dend");
   const keyV = v(ctx, "_dkey");
   const stmts = [
+    ...selectorLeafMark ? [
+      `${ind(ctx)}const ${selectorLeafMark} = _ctx._cstLeaves?.length ?? 0`,
+      `${ind(ctx)}const ${selectorRawMark} = _ctx._cstRawChildren?.length ?? 0`,
+      `${ind(ctx)}const ${selectorTriviaMark} = _ctx._cstTriviaLog?.length ?? 0`,
+      `${ind(ctx)}const ${selectorLogMark} = _ctx._triviaLog?.length ?? 0`,
+      `${ind(ctx)}const ${selectorFieldMark} = _ctx._fields?.length ?? 0`,
+      `${ind(ctx)}const ${selectorErrorMark} = _ctx._errors?.length ?? 0`
+    ] : [],
     ...selector.stmts,
     `${ind(ctx)}const ${keyV} = ${selector.valueVar}`,
     `${ind(ctx)}let ${outV}, ${outE} = ${selector.endVar}`
   ];
   let wroteBranch = false;
-  const emitSelectedTail = (parser2, keyword, condition) => {
+  const emitSelectedTail = (entry, keyword, condition, coverageId) => {
+    const parser3 = entry.parser;
     const head = keyword === "else" ? `${ind(ctx)}else {` : `${ind(ctx)}${keyword} (${condition}) {`;
     stmts.push(head);
     ctx.indent++;
-    const mayError = mayRecordRecoveryError(parser2, !!ctx.recovery);
+    const usesRouted = branchUsesRouted2(entry);
+    const routedV = usesRouted ? v(ctx, "_drt") : null;
+    const mayError = mayRecordRecoveryError(parser3, !!ctx.recovery);
     const errMark = mayError ? v(ctx, "_derr") : null;
     const logMark = ctx.activeTrivia ? v(ctx, "_dlog") : null;
+    if (routedV) {
+      stmts.push(
+        `${ind(ctx)}const ${routedV} = _ctx._routed; _ctx._routed = { value: ${selector.valueVar}, span: { start: ${pos}, end: ${selector.endVar} } }`,
+        ...selectorLeafMark ? [
+          `${ind(ctx)}if (_ctx._cstLeaves && _ctx._cstLeaves.length !== ${selectorLeafMark}) _ctx._cstLeaves.length = ${selectorLeafMark}; if (_ctx._cstRawChildren && _ctx._cstRawChildren.length !== ${selectorRawMark}) _ctx._cstRawChildren.length = ${selectorRawMark}; if (_ctx._cstTriviaLog && _ctx._cstTriviaLog.length !== ${selectorTriviaMark}) _ctx._cstTriviaLog.length = ${selectorTriviaMark}; if (_ctx._triviaLog && _ctx._triviaLog.length !== ${selectorLogMark}) _ctx._triviaLog.length = ${selectorLogMark}; if (_ctx._fields && _ctx._fields.length !== ${selectorFieldMark}) _ctx._fields.length = ${selectorFieldMark}; if (_ctx._errors && _ctx._errors.length !== ${selectorErrorMark}) _ctx._errors.length = ${selectorErrorMark}`
+        ] : []
+      );
+    }
     if (errMark) stmts.push(`${ind(ctx)}const ${errMark} = _ctx._errors?.length ?? 0`);
     if (logMark) stmts.push(`${ind(ctx)}const ${logMark} = _ctx._triviaLog?.length ?? 0`);
-    const tail = emitTailFallible(parser2, ctx, selector.endVar);
+    const tail = emitTailFallible(parser3, ctx, usesRouted ? pos : selector.endVar);
+    stmts.push(...coverageAttempt(ctx, coverageId, pos));
     const errorRollback = errMark ? `if (_ctx._errors && _ctx._errors.length !== ${errMark}) _ctx._errors.length = ${errMark}; ` : "";
     const logRollback = logMark ? `if (_ctx._triviaLog && _ctx._triviaLog.length !== ${logMark}) _ctx._triviaLog.length = ${logMark}; ` : "";
+    const routedRollback = routedV ? `_ctx._routed = ${routedV}; ` : "";
+    const coverageFailure = coverageId === void 0 ? "" : `_ctx._grammarTrace?.write({ id: ${JSON.stringify(coverageId)}, phase: 'failure', offset: _ctx._fe }); `;
     stmts.push(
       ...tail.stmts,
-      `${ind(ctx)}if (!${tail.okVar}) { ${errorRollback}${logRollback}${committedFailBody(ctx)} }`,
+      `${ind(ctx)}if (!${tail.okVar}) { ${routedRollback}${errorRollback}${logRollback}${coverageFailure}${committedFailBody(ctx)} }`,
+      ...routedV ? [`${ind(ctx)}_ctx._routed = ${routedV}`] : [],
       `${ind(ctx)}${outV} = [${selector.valueVar}, ${tail.valVar}]`,
-      `${ind(ctx)}${outE} = ${tail.endVar}`
+      `${ind(ctx)}${outE} = ${tail.endVar}`,
+      ...coverageHit(ctx, coverageId, pos, tail.endVar)
     );
     ctx.indent--;
     stmts.push(`${ind(ctx)}}`);
   };
+  let coverageIndex = 0;
   for (const entry of def.cases) {
-    const condition = entry.keys.map((key) => `${keyV} === ${JSON.stringify(key)}`).join(" || ");
-    emitSelectedTail(entry.parser, wroteBranch ? "else if" : "if", condition);
+    const condition = entry.keys.map((key) => emitDispatchKeyCondition(keyV, key, entry.caseInsensitive)).join(" || ");
+    emitSelectedTail(entry, wroteBranch ? "else if" : "if", condition, coverageIds[coverageIndex++]);
     wroteBranch = true;
   }
+  const emitMatcherTails = () => {
+    for (const matcher of def.matchers ?? []) {
+      emitSelectedTail(matcher, wroteBranch ? "else if" : "if", emitDispatchMatcherCondition(keyV, matcher), coverageIds[coverageIndex++]);
+      wroteBranch = true;
+    }
+  };
   if (def.otherwise) {
-    if (wroteBranch) emitSelectedTail(def.otherwise, "else");
-    else emitSelectedTail(def.otherwise, "if", "true");
+    emitMatcherTails();
+    const otherwiseEntry = { parser: def.otherwise, usesRouted: def.otherwiseUsesRouted };
+    if (wroteBranch) emitSelectedTail(otherwiseEntry, "else", void 0, coverageIds[coverageIndex++]);
+    else emitSelectedTail(otherwiseEntry, "if", "true", coverageIds[coverageIndex++]);
   } else {
+    emitMatcherTails();
     const expected = JSON.stringify(def.cases.flatMap((entry) => entry.keys.map((key) => JSON.stringify(key))));
     const fail = failArrBody(ctx, expected, selector.endVar);
     stmts.push(wroteBranch ? `${ind(ctx)}else { ${fail} }` : `${ind(ctx)}${fail}`);
   }
   return { stmts, valueVar: outV, endVar: outE };
 }
+function emitDispatchKeyCondition(valueVar, key, caseInsensitive) {
+  if (!caseInsensitive) return `${valueVar} === ${JSON.stringify(key)}`;
+  const parts = [`${valueVar}.length === ${key.length}`];
+  for (let i = 0; i < key.length; i++) {
+    parts.push(foldEq(`${valueVar}.charCodeAt(${i})`, key.charCodeAt(i)));
+  }
+  return parts.join(" && ");
+}
+function emitDispatchMatcherCondition(valueVar, matcher) {
+  if (matcher.kind === "matches") {
+    const flags = matcher.caseInsensitive && !matcher.flags?.includes("i") ? `${matcher.flags ?? ""}i` : matcher.flags ?? "";
+    return `${new RegExp(matcher.value, flags).toString()}.test(${valueVar})`;
+  }
+  const text = matcher.value;
+  const parts = [`${valueVar}.length >= ${text.length}`];
+  const offset = matcher.kind === "endsWith" ? `${valueVar}.length - ${text.length}` : "0";
+  for (let i = 0; i < text.length; i++) {
+    parts.push(matcher.caseInsensitive ? foldEq(`${valueVar}.charCodeAt(${offset}${i === 0 ? "" : ` + ${i}`})`, text.charCodeAt(i)) : `${valueVar}.charCodeAt(${offset}${i === 0 ? "" : ` + ${i}`}) === ${text.charCodeAt(i)}`);
+  }
+  return parts.join(" && ");
+}
 function emitGreedyClassify(def, superIndex, ctx, pos, coverageBase) {
   const superParser = def.parsers[superIndex];
   const regexDef = getCoreRegexDef(superParser);
@@ -8195,6 +8467,18 @@ function emitPeek(def, ctx, pos) {
     endVar: pos
   };
 }
+function emitRouted(ctx, pos) {
+  const item = v(ctx, "_rt");
+  return {
+    stmts: [
+      `${ind(ctx)}const ${item} = _ctx._routed`,
+      ...emitIfFail(ctx, `${item} === undefined || ${item}.span.start !== ${pos}`, failBody(ctx, '"routed()"', pos)),
+      ...emitLeafCapture(ctx, `${item}.value`, `${item}.span.start`, `${item}.span.end`)
+    ],
+    valueVar: `${item}.value`,
+    endVar: `${item}.span.end`
+  };
+}
 function escapeTokenLiteral(value) {
   return value.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
 }
@@ -8660,7 +8944,7 @@ function emitDispatch(p, ctx, pos) {
     case "choice":
       return emitChoice(p, def, ctx, pos);
     case "dispatch":
-      return emitDispatchCombinator(def, ctx, pos);
+      return emitDispatchCombinator(p, def, ctx, pos);
     case "attempt":
       return emitAttempt(p, def, ctx, pos);
     case "many":
@@ -8785,6 +9069,8 @@ function emitDispatch(p, ctx, pos) {
       return emitNot(def, ctx, pos);
     case "peek":
       return emitPeek(def, ctx, pos);
+    case "routed":
+      return emitRouted(ctx, pos);
     case "node":
       return emitNode(def, ctx, pos);
     case "scanTo":
@@ -8882,7 +9168,7 @@ function hasNodeDef(p, seen = /* @__PURE__ */ new Set()) {
     case "choice":
       return d.parsers.some((x) => hasNodeDef(x, seen));
     case "dispatch":
-      return hasNodeDef(d.selector, seen) || d.cases.some((x) => hasNodeDef(x.parser, seen)) || (d.otherwise ? hasNodeDef(d.otherwise, seen) : false);
+      return hasNodeDef(d.selector, seen) || d.cases.some((x) => hasNodeDef(x.parser, seen)) || (d.matchers ? d.matchers.some((entry) => hasNodeDef(entry.parser, seen)) : false) || (d.otherwise ? hasNodeDef(d.otherwise, seen) : false);
     case "sepBy":
       return hasNodeDef(d.parser, seen) || hasNodeDef(d.separator, seen);
     case "scanTo":
@@ -8897,6 +9183,26 @@ function hasNodeDef(p, seen = /* @__PURE__ */ new Set()) {
       return false;
   }
 }
+function parserUsesRouted2(p, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(p)) return false;
+  seen.add(p);
+  const d = p._def;
+  switch (d.tag) {
+    case "routed":
+      return true;
+    case "lazy": {
+      try {
+        return parserUsesRouted2(d.thunk(), seen);
+      } catch {
+        return false;
+      }
+    }
+    case "dispatch":
+      return false;
+    default:
+      return childrenOf2(d).some((child) => parserUsesRouted2(child, seen));
+  }
+}
 function hasDirectBuildDef(p, seen = /* @__PURE__ */ new Set()) {
   if (seen.has(p)) return false;
   seen.add(p);
@@ -8917,7 +9223,7 @@ function childrenOf2(def) {
     case "choice":
       return def.parsers;
     case "dispatch":
-      return [def.selector, ...def.cases.map((entry) => entry.parser), ...def.otherwise ? [def.otherwise] : []];
+      return [def.selector, ...def.cases.map((entry) => entry.parser), ...def.matchers ? def.matchers.map((entry) => entry.parser) : [], ...def.otherwise ? [def.otherwise] : []];
     case "many":
     case "attempt":
     case "optional":
@@ -8954,6 +9260,7 @@ function childrenOf2(def) {
     case "regex":
     case "keywords":
     case "guard":
+    case "routed":
     case "unknown":
       return [];
   }
@@ -9661,7 +9968,7 @@ function childrenOf3(def) {
     case "choice":
       return def.parsers;
     case "dispatch":
-      return [def.selector, ...def.cases.map((entry) => entry.parser), ...def.otherwise ? [def.otherwise] : []];
+      return [def.selector, ...def.cases.map((entry) => entry.parser), ...def.matchers ? def.matchers.map((entry) => entry.parser) : [], ...def.otherwise ? [def.otherwise] : []];
     case "many":
     case "oneOrMore":
     case "optional":
@@ -9690,6 +9997,7 @@ function childrenOf3(def) {
     case "literal":
     case "regex":
     case "keywords":
+    case "routed":
     case "guard":
     case "recover":
     case "unknown":
@@ -9714,6 +10022,16 @@ function repeatOpts(min, max, trailing) {
   if (trailing !== void 0) parts.push(`trailing: ${JSON.stringify(trailing)}`);
   return parts.length === 0 ? "" : `, { ${parts.join(", ")} }`;
 }
+function matcherExpr(entry) {
+  switch (entry.kind) {
+    case "startsWith":
+      return `startsWith(${JSON.stringify(entry.value)})`;
+    case "endsWith":
+      return `endsWith(${JSON.stringify(entry.value)})`;
+    case "matches":
+      return `matches(${new RegExp(entry.value, entry.flags ?? "").toString()})`;
+  }
+}
 function serializeRuleMap(ruleMap, scanSkip) {
   try {
     return new Serializer(ruleMap, scanSkip ?? []).run();
@@ -9813,7 +10131,11 @@ function evalRuleMapIR(ir) {
     "choice",
     "dispatch",
     "when",
+    "startsWith",
+    "endsWith",
+    "matches",
     "otherwise",
+    "routed",
     "attempt",
     "many",
     "oneOrMore",
@@ -9849,7 +10171,11 @@ function evalRuleMapIR(ir) {
     choice,
     dispatch,
     when,
+    startsWith,
+    endsWith,
+    matches,
     otherwise,
+    routed,
     attempt,
     many,
     oneOrMore,
@@ -10037,8 +10363,13 @@ ${outerDecls.map((d) => "  " + d).join("\n")}
       }
       case "dispatch": {
         const arms = def.cases.map(
-          (entry) => `when(${entry.keys.length === 1 ? JSON.stringify(entry.keys[0]) : JSON.stringify(entry.keys)}, ${kid(entry.parser)})`
+          (entry) => `when(${entry.keys.length === 1 ? JSON.stringify(entry.keys[0]) : JSON.stringify(entry.keys)}, ${kid(entry.parser)}${entry.caseInsensitive ? ", { caseInsensitive: true }" : ""})`
         );
+        if (def.matchers) {
+          for (const entry of def.matchers) {
+            arms.push(`when(${matcherExpr(entry)}, ${kid(entry.parser)}${entry.caseInsensitive ? ", { caseInsensitive: true }" : ""})`);
+          }
+        }
         if (def.otherwise) arms.push(`otherwise(${kid(def.otherwise)})`);
         return `dispatch(${kid(def.selector)}${arms.length === 0 ? "" : `, ${arms.join(", ")}`})`;
       }
@@ -10058,6 +10389,8 @@ ${outerDecls.map((d) => "  " + d).join("\n")}
         return `not(${kid(def.parser)})`;
       case "peek":
         return `peek(${kid(def.parser)})`;
+      case "routed":
+        return "routed()";
       case "trivia":
         return `trivia(${kid(def.parser)})`;
       case "token":
@@ -11079,10 +11412,20 @@ function run(entry, input, options = {}) {
 }
 
 // src/coverage.ts
+function dispatchMatcher(entry) {
+  switch (entry.kind) {
+    case "startsWith":
+      return startsWith(entry.value);
+    case "endsWith":
+      return endsWith(entry.value);
+    case "matches":
+      return matches(new RegExp(entry.value, entry.flags));
+  }
+}
 var GRAMMAR_COVERAGE_DEFINITIONS = /* @__PURE__ */ Symbol.for("parseman.grammarCoverageDefinitions");
 function compiledGrammarCoverageDefinitions(grammar) {
   const definitions = grammar[GRAMMAR_COVERAGE_DEFINITIONS];
-  if (!Array.isArray(definitions) || !definitions.every((definition) => typeof definition === "object" && definition !== null && typeof definition.id === "string" && (definition.kind === "rule" || definition.kind === "choice-arm" || definition.kind === "label"))) {
+  if (!Array.isArray(definitions) || !definitions.every((definition) => typeof definition === "object" && definition !== null && typeof definition.id === "string" && (definition.kind === "rule" || definition.kind === "choice-arm" || definition.kind === "dispatch-arm" || definition.kind === "label"))) {
     throw new TypeError("grammar has no coverage definitions; enable grammarCoverage for this macro build");
   }
   return definitions;
@@ -11262,10 +11605,54 @@ function coverageEntry(entry, collector, maps, trace) {
           return unsafeSequence(...def.parsers.map(build));
         }
         case "dispatch": {
-          const arms = def.cases.map((entry2) => when(entry2.keys, build(entry2.parser)));
-          if (def.otherwise) arms.push(otherwise(build(def.otherwise)));
+          const ids = maps.dispatches.get(parser2) ?? [];
+          let armIndex = 0;
+          const dispatchStarts = [];
+          const wrapArm = (arm, id) => {
+            const child = build(arm);
+            return {
+              _tag: child._tag,
+              _meta: child._meta,
+              _def: child._def,
+              parse(input, pos, ctx) {
+                const dispatchStart = dispatchStarts[dispatchStarts.length - 1] ?? pos;
+                if (id) trace?.write({ id, phase: "attempt", offset: dispatchStart });
+                const result = child.parse(input, pos, ctx);
+                if (result.ok) {
+                  if (id) {
+                    collector.hit(id);
+                    trace?.write({ id, phase: "selected", offset: dispatchStart, end: result.span.end });
+                    trace?.write({ id, phase: "success", offset: dispatchStart, end: result.span.end });
+                  }
+                } else if (id) {
+                  trace?.write({ id, phase: "failure", offset: result.span.end });
+                }
+                return result;
+              }
+            };
+          };
+          const arms = def.cases.map(
+            (entry2) => when(entry2.keys, wrapArm(entry2.parser, ids[armIndex++]), entry2.caseInsensitive ? { caseInsensitive: true } : void 0)
+          );
+          if (def.matchers) {
+            for (const entry2 of def.matchers) {
+              arms.push(when(dispatchMatcher(entry2), wrapArm(entry2.parser, ids[armIndex++]), entry2.caseInsensitive ? { caseInsensitive: true } : void 0));
+            }
+          }
+          if (def.otherwise) arms.push(otherwise(wrapArm(def.otherwise, ids[armIndex++])));
           const unsafeDispatch = dispatch;
-          return unsafeDispatch(build(def.selector), ...arms);
+          const base2 = unsafeDispatch(build(def.selector), ...arms);
+          return {
+            ...base2,
+            parse(input, pos, ctx) {
+              dispatchStarts.push(pos);
+              try {
+                return base2.parse(input, pos, ctx);
+              } finally {
+                dispatchStarts.pop();
+              }
+            }
+          };
         }
         case "many":
           return many(build(def.parser));