parseman 0.39.0 → 0.39.1

package/dist/plugin/index.cjs

@@ -94,6 +94,8 @@ function matchesEmpty(p, seen = /* @__PURE__ */ new Set(), resolve2) {
       return d.value.length === 0;
     case "keywords":
       return false;
+    case "routed":
+      return false;
     case "regex":
       try {
         const m = new RegExp(d.source).exec("");
@@ -1186,6 +1188,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] : [];
@@ -2007,42 +2011,195 @@ 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 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,
@@ -2050,18 +2207,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 };
@@ -2411,6 +2585,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":
@@ -2689,7 +2864,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":
@@ -2758,7 +2933,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": {
@@ -2785,7 +2960,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":
@@ -3160,7 +3335,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");
@@ -3420,6 +3595,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);
@@ -4943,13 +5119,25 @@ function escapeClassChar(ch2) {
 }
 
 // src/compiler/grammar-coverage-ids.ts
+function idPart(value) {
+  return encodeURIComponent(value);
+}
+function dispatchArmIds(def, path2) {
+  const ids = [];
+  for (const entry of def.cases) ids.push(`dispatch:${path2}/when:${entry.keys.map(idPart).join("|")}`);
+  for (const entry of def.matchers ?? []) {
+    ids.push(`dispatch:${path2}/matcher:${entry.kind}:${idPart(entry.value)}${entry.kind === "matches" && entry.flags ? `:${idPart(entry.flags)}` : ""}`);
+  }
+  if (def.otherwise) ids.push(`dispatch:${path2}/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":
@@ -4992,6 +5180,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();
@@ -5022,6 +5211,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, path2);
+      dispatches.set(parser2, ids);
+      ids.forEach((id) => definitions.set(id, { id, kind: "dispatch-arm" }));
+    }
     if (parser2._def.tag === "attempt") attempts.set(parser2, `attempt:${path2}`);
     if (parser2._def.tag === "label") {
       const id = `label:${path2}`;
@@ -5034,7 +5228,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
@@ -6408,6 +6602,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 = [];
@@ -6766,7 +6961,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.
@@ -6865,6 +7060,7 @@ function capturesLeaf(p, seen = /* @__PURE__ */ new Set()) {
     case "keywords":
     case "node":
     case "token":
+    case "routed":
     case "leaf":
       return true;
     case "not":
@@ -6877,7 +7073,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":
@@ -7355,6 +7551,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":
@@ -7389,53 +7586,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);
@@ -8090,6 +8354,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, "\\$&");
 }
@@ -8555,7 +8831,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":
@@ -8680,6 +8956,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":
@@ -8777,7 +9055,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":
@@ -8792,6 +9070,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);
@@ -8812,7 +9110,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":
@@ -8849,6 +9147,7 @@ function childrenOf2(def) {
     case "regex":
     case "keywords":
     case "guard":
+    case "routed":
     case "unknown":
       return [];
   }
@@ -9682,7 +9981,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":
@@ -9711,6 +10010,7 @@ function childrenOf3(def) {
     case "literal":
     case "regex":
     case "keywords":
+    case "routed":
     case "guard":
     case "recover":
     case "unknown":
@@ -9735,6 +10035,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();
@@ -9834,7 +10144,11 @@ function evalRuleMapIR(ir) {
     "choice",
     "dispatch",
     "when",
+    "startsWith",
+    "endsWith",
+    "matches",
     "otherwise",
+    "routed",
     "attempt",
     "many",
     "oneOrMore",
@@ -9870,7 +10184,11 @@ function evalRuleMapIR(ir) {
     choice,
     dispatch,
     when,
+    startsWith,
+    endsWith,
+    matches,
     otherwise,
+    routed,
     attempt,
     many,
     oneOrMore,
@@ -10058,8 +10376,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(", ")}`})`;
       }
@@ -10079,6 +10402,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":
@@ -10548,6 +10873,9 @@ function stripTsFromSource(node2, code) {
 function isWordFactory(v2) {
   return !!v2 && typeof v2 === "object" && v2.tag === "wordFactory";
 }
+function isWhenFactory(v2) {
+  return !!v2 && typeof v2 === "object" && v2.tag === "whenFactory";
+}
 function isStaticValueEntry(v2) {
   return !!v2 && typeof v2 === "object" && "value" in v2 && "mfSrcs" in v2;
 }
@@ -10570,6 +10898,23 @@ function wordFactoryFromArgs(args, scope, code, mfs) {
   if (typeof caseInsensitive !== "boolean") return null;
   return { tag: "wordFactory", boundary: "_0-9A-Za-z", caseInsensitive };
 }
+function dispatchWhenOptions(v2) {
+  if (v2 === void 0) return {};
+  if (typeof v2 !== "object" || v2 === null || Array.isArray(v2)) return null;
+  for (const key of Object.keys(v2)) {
+    if (key !== "caseInsensitive") return null;
+  }
+  const caseInsensitive = "caseInsensitive" in v2 ? v2.caseInsensitive : false;
+  if (typeof caseInsensitive !== "boolean") return null;
+  return { caseInsensitive };
+}
+function whenFactoryFromArgs(args, scope, code, mfs) {
+  const [optsArg, extra] = args;
+  if (optsArg?.type === "SpreadElement" || extra !== void 0) return null;
+  const rawOpts = optsArg === void 0 ? void 0 : anyValue(optsArg, scope, code, mfs);
+  const opts = dispatchWhenOptions(rawOpts);
+  return opts === null ? null : { tag: "whenFactory", caseInsensitive: opts.caseInsensitive ?? false };
+}
 var SUPPORTED = {
   literal: (...a) => literal(a[0], a[1]),
   regex: (...a) => regex(a[0], a[1]),
@@ -10585,6 +10930,7 @@ var SUPPORTED = {
   field: (...a) => field(a[0], a[1]),
   noTrivia: (...a) => noTrivia(a[0]),
   token: (...a) => token(a[0]),
+  routed: () => routed(),
   leaf: (...a) => leaf(a[0], a[1]),
   expect: (...a) => expect(a[0], a[1])
 };
@@ -10628,6 +10974,18 @@ function dispatchArmValue(node2, scope, code, mfs) {
   if (node2.type !== "CallExpression") return null;
   const callee = node2.callee;
   if (callee.type !== "Identifier") return null;
+  const factory = scope.get(callee.name);
+  if (isWhenFactory(factory)) {
+    const [keyArg, parserArg, extraArg] = node2.arguments;
+    if (!keyArg || !parserArg || extraArg !== void 0 || keyArg.type === "SpreadElement" || parserArg.type === "SpreadElement") return null;
+    const key = anyValue(keyArg, scope, code, mfs);
+    const parserValue = anyValue(parserArg, scope, code, mfs);
+    if (!isCombinator(parserValue)) return null;
+    const opts = { caseInsensitive: factory.caseInsensitive };
+    if (typeof key === "string") return when(key, parserValue, opts);
+    if (Array.isArray(key) && key.every((item) => typeof item === "string")) return when(key, parserValue, opts);
+    return null;
+  }
   if (callee.name === "otherwise") {
     const [parserArg] = node2.arguments;
     if (!parserArg || parserArg.type === "SpreadElement") return null;
@@ -10636,13 +10994,16 @@ function dispatchArmValue(node2, scope, code, mfs) {
     return otherwise(parserValue);
   }
   if (callee.name === "when") {
-    const [keyArg, parserArg] = node2.arguments;
-    if (!keyArg || !parserArg || keyArg.type === "SpreadElement" || parserArg.type === "SpreadElement") return null;
+    const [keyArg, parserArg, optsArg] = node2.arguments;
+    if (!keyArg || !parserArg || keyArg.type === "SpreadElement" || parserArg.type === "SpreadElement" || optsArg?.type === "SpreadElement") return null;
     const key = anyValue(keyArg, scope, code, mfs);
     const parserValue = anyValue(parserArg, scope, code, mfs);
+    const opts = dispatchWhenOptions(optsArg === void 0 ? void 0 : anyValue(optsArg, scope, code, mfs));
+    if (opts === null) return null;
     if (!isCombinator(parserValue)) return null;
-    if (typeof key === "string") return when(key, parserValue);
-    if (Array.isArray(key) && key.every((item) => typeof item === "string")) return when(key, parserValue);
+    if (typeof key === "string") return when(key, parserValue, opts);
+    if (Array.isArray(key) && key.every((item) => typeof item === "string")) return when(key, parserValue, opts);
+    if (isDispatchMatcher(key)) return when(key, parserValue, opts);
   }
   return null;
 }
@@ -10653,7 +11014,16 @@ function isDispatchArm(v2) {
   if (!v2 || typeof v2 !== "object") return false;
   const rec = v2;
   if (rec.kind === "otherwise") return isCombinator(rec.parser);
-  return rec.kind === "when" && Array.isArray(rec.keys) && rec.keys.every((key) => typeof key === "string") && isCombinator(rec.parser);
+  if (rec.kind === "whenMatcher") {
+    return isDispatchMatcher(rec.matcher) && typeof rec.caseInsensitive === "boolean" && isCombinator(rec.parser);
+  }
+  return rec.kind === "when" && Array.isArray(rec.keys) && rec.keys.every((key) => typeof key === "string") && typeof rec.caseInsensitive === "boolean" && isCombinator(rec.parser);
+}
+function isDispatchMatcher(v2) {
+  if (!v2 || typeof v2 !== "object") return false;
+  const rec = v2;
+  if ((rec.kind === "startsWith" || rec.kind === "endsWith") && typeof rec.value === "string") return true;
+  return rec.kind === "matches" && typeof rec.value === "string" && typeof rec.flags === "string";
 }
 function scopeGet(scope, name, mfs) {
   const entry = scope.get(name);
@@ -11039,9 +11409,27 @@ function anyValue(node2, scope, code, mfs) {
     if (callee.type === "Identifier" && callee.name === "makeWord") {
       return wordFactoryFromArgs(node2.arguments, scope, code, mfs);
     }
+    if (callee.type === "Identifier" && callee.name === "makeWhen") {
+      return whenFactoryFromArgs(node2.arguments, scope, code, mfs);
+    }
+    if (callee.type === "Identifier" && (callee.name === "startsWith" || callee.name === "endsWith")) {
+      if (node2.arguments.length !== 1 || node2.arguments[0]?.type === "SpreadElement") return null;
+      const value = anyValue(node2.arguments[0], scope, code, mfs);
+      if (typeof value !== "string") return null;
+      return callee.name === "startsWith" ? startsWith(value) : endsWith(value);
+    }
+    if (callee.type === "Identifier" && callee.name === "matches") {
+      if (node2.arguments.length !== 1 || node2.arguments[0]?.type === "SpreadElement") return null;
+      const value = anyValue(node2.arguments[0], scope, code, mfs);
+      if (!(value instanceof RegExp)) return null;
+      return matches(value);
+    }
     if (callee.type === "Identifier" && (callee.name === "when" || callee.name === "otherwise")) {
       return dispatchArmValue(node2, scope, code, mfs);
     }
+    if (callee.type === "Identifier" && isWhenFactory(scope.get(callee.name))) {
+      return dispatchArmValue(node2, scope, code, mfs);
+    }
     return exprToCombi(node2, scope, code, mfs);
   }
   return null;
@@ -11052,6 +11440,12 @@ function evaluateWordFactory(node2, scope, code) {
   if (callee.type !== "Identifier" || callee.name !== "makeWord") return null;
   return wordFactoryFromArgs(node2.arguments, scope, code);
 }
+function evaluateWhenFactory(node2, scope, code) {
+  if (node2.type !== "CallExpression") return null;
+  const callee = node2.callee;
+  if (callee.type !== "Identifier" || callee.name !== "makeWhen") return null;
+  return whenFactoryFromArgs(node2.arguments, scope, code);
+}
 function evaluateExpr(node2, scope, code, mapFnSources) {
   return exprToCombi(node2, scope, code, mapFnSources);
 }
@@ -11632,7 +12026,7 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
     for (const match of source.matchAll(/id:\s*"([^"]+)"/g)) ids.add(match[1]);
     return [...ids].sort().map((id2) => ({
       id: id2,
-      kind: id2.startsWith("rule:") ? "rule" : id2.startsWith("label:") ? "label" : "choice-arm"
+      kind: id2.startsWith("rule:") ? "rule" : id2.startsWith("label:") ? "label" : id2.startsWith("dispatch:") ? "dispatch-arm" : "choice-arm"
     }));
   };
   const localComposedCarried = /* @__PURE__ */ new Map();
@@ -12078,6 +12472,14 @@ function transformMacro(code, id, moduleAliases = /* @__PURE__ */ new Set([PARSE
           if (wordFactory) {
             ;
             scope.set(varName, wordFactory);
+            replacements.push({ start: init.start, end: init.end, replacement: "undefined" });
+            continue;
+          }
+          const whenFactory = evaluateWhenFactory(init, scope, code);
+          if (whenFactory) {
+            ;
+            scope.set(varName, whenFactory);
+            replacements.push({ start: init.start, end: init.end, replacement: "undefined" });
             continue;
           }
           const combiArray = evaluateCombinatorArray(init, scope, code);