@metaobjectsdev/render 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/render",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Logic-less, deterministic text render engine (Mustache) for MetaObjects templates — provider-resolved partials, format-driven escaping, zero core dependency.",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,7 +12,12 @@
       "default": "./dist/index.js"
     }
   },
-  "files": ["dist", "src", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsc -p .",
     "typecheck": "tsc -p tsconfig.typecheck.json"
@@ -21,23 +26,29 @@
   "author": "Doug Mealing <doug@dougmealing.com>",
   "homepage": "https://metaobjects.dev",
   "bugs": {
-  "url": "https://github.com/metaobjectsdev/metaobjects/issues"
-},
-"repository": {
-  "type": "git",
-  "url": "https://github.com/metaobjectsdev/metaobjects.git",
-  "directory": "server/typescript/packages/render"
-},
-"keywords": ["metaobjects", "render", "mustache", "prompt", "template"],
-"publishConfig": {
-"access": "public"
-},
-"dependencies": {
-  "mustache": "^4.2.0"
-},
-"devDependencies": {
-  "@types/mustache": "^4.2.5",
-  "bun-types": "latest",
-  "typescript": "^5.6.0"
-}
+    "url": "https://github.com/metaobjectsdev/metaobjects/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/metaobjectsdev/metaobjects.git",
+    "directory": "server/typescript/packages/render"
+  },
+  "keywords": [
+    "metaobjects",
+    "render",
+    "mustache",
+    "prompt",
+    "template"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "mustache": "^4.2.0"
+  },
+  "devDependencies": {
+    "@types/mustache": "^4.2.5",
+    "bun-types": "latest",
+    "typescript": "^5.6.0"
+  }
 }

package/src/extract/coerce.ts

@@ -49,9 +49,9 @@ export function coerceValue(
       return coerceEnum(raw, spec, opts, fieldPath, report, ci);
     case FieldKind.INT:
     case FieldKind.LONG:
-      return coerceInt(raw, spec, fieldPath, report);
+      return coerceInt(raw, spec, fieldPath, report, ci);
     case FieldKind.DOUBLE:
-      return coerceDouble(raw, spec, fieldPath, report);
+      return coerceDouble(raw, spec, fieldPath, report, ci);
     case FieldKind.BOOLEAN:
       return coerceBool(raw, ci);
     default:
@@ -171,16 +171,16 @@ function lookupAliasIn(raw: string, aliases: Readonly<Record<string, string>>, m
   return null;
 }
 
-function coerceInt(raw: string, spec: FieldSpec, path: string, report: ExtractionReport): unknown | typeof MALFORMED {
+function coerceInt(raw: string, spec: FieldSpec, path: string, report: ExtractionReport, lenient: boolean): unknown | typeof MALFORMED {
   const n = parseFiniteNumber(raw);
   if (n === null) return MALFORMED;
-  return clamp(Math.trunc(n), spec, path, report);
+  return clamp(Math.trunc(n), spec, path, report, lenient);
 }
 
-function coerceDouble(raw: string, spec: FieldSpec, path: string, report: ExtractionReport): unknown | typeof MALFORMED {
+function coerceDouble(raw: string, spec: FieldSpec, path: string, report: ExtractionReport, lenient: boolean): unknown | typeof MALFORMED {
   const n = parseFiniteNumber(raw);
   if (n === null) return MALFORMED;
-  return clamp(n, spec, path, report);
+  return clamp(n, spec, path, report, lenient);
 }
 
 /** Parse a trimmed numeric string; null if empty, non-numeric, or non-finite (NaN/±Infinity). */
@@ -194,11 +194,20 @@ function parseFiniteNumber(raw: string): number | null {
   return Number.isFinite(n) ? n : null;
 }
 
-function clamp(n: number, spec: FieldSpec, path: string, report: ExtractionReport): number {
+/**
+ * Apply the field's min/max range (sourced from its numeric validator). Under LENIENT tolerance an
+ * out-of-range value is CLAMPED to the bound (recorded as a "clamp" coercion); under STRICT tolerance
+ * it is MALFORMED (the validator's "value out of range" contract). Cross-port: ports must match the
+ * lenient-clamp / strict-reject split.
+ */
+function clamp(n: number, spec: FieldSpec, path: string, report: ExtractionReport, lenient: boolean): number | typeof MALFORMED {
   let c = n;
   if (spec.min != null && c < spec.min) c = spec.min;
   if (spec.max != null && c > spec.max) c = spec.max;
-  if (c !== n) report.addCoercion({ fieldPath: path, from: stringify(n), to: stringify(c), kind: "clamp" });
+  if (c !== n) {
+    if (!lenient) return MALFORMED; // STRICT: out-of-range is invalid, not silently clamped
+    report.addCoercion({ fieldPath: path, from: stringify(n), to: stringify(c), kind: "clamp" });
+  }
   return c;
 }
 

package/src/extract/extract.ts

@@ -11,8 +11,8 @@ import type { FieldSpec, ExtractOptions, ExtractionOutcome, ExtractSchema } from
 import { ExtractionReport } from "./types.js";
 import { strip } from "./strip.js";
 import { locateJson, locateXml } from "./locate.js";
-import { readJson, TRUNCATED } from "./json-forgiving-reader.js";
-import { readXml } from "./xml-forgiving-reader.js";
+import { readJson, TRUNCATED, NULL_LITERAL } from "./json-forgiving-reader.js";
+import { readXml, readXmlRootless, TEXT_KEY } from "./xml-forgiving-reader.js";
 import { coerceValue, scalarCoerce, MALFORMED } from "./coerce.js";
 
 /** The forgiving entry point: extract dirty `text` against `schema`. Never throws. */
@@ -28,16 +28,20 @@ export function extract(
   const stripped = strip(text);
   const ci = o.tolerance !== Tolerance.STRICT;
 
-  const span =
-    schema.format === Format.JSON ? locateJson(stripped) : locateXml(stripped, schema.rootName, ci);
-
+  // XML rootless (opts.rootless): the payload's fields ARE the top-level elements — there is no
+  // enclosing root to locate — so parse the whole stripped text's top-level elements directly.
+  // Otherwise locate the <rootName> span as before. JSON is unaffected. Mirrors Java Extract.
+  let span: string | null;
   let raw: Record<string, unknown>;
-  if (span == null) {
-    raw = {};
-  } else if (schema.format === Format.JSON) {
-    raw = readJson(span);
+  if (schema.format === Format.JSON) {
+    span = locateJson(stripped);
+    raw = span == null ? {} : readJson(span);
+  } else if (o.rootless) {
+    span = stripped.length === 0 ? null : stripped;
+    raw = span == null ? {} : readXmlRootless(stripped, ci);
   } else {
-    raw = readXml(span, ci);
+    span = locateXml(stripped, schema.rootName, ci);
+    raw = span == null ? {} : readXml(span, ci);
   }
 
   if (isEmptyRecord(raw) && (stripped.length === 0 || span == null)) {
@@ -59,7 +63,9 @@ function extractFields(
 ): void {
   for (const f of fields) {
     const path = prefix.length === 0 ? f.name : `${prefix}.${f.name}`;
-    const present = lookup(raw, f.name, ci);
+    // A @xmlText field reads the element's text body (carried under the #text sentinel when the
+    // element also has attributes), not a same-named child element.
+    const present = f.textContent === true ? raw[TEXT_KEY] : lookup(raw, f.name, ci);
     if (present === undefined) {
       // FR-011 / Phase B: an absent field with a declared @default fills the value → DEFAULTED
       // (which satisfies a @required field). Generalized to all field kinds: an enum default is
@@ -84,6 +90,13 @@ function extractFields(
       report.set(path, FieldExtraction.MALFORMED);
       continue;
     }
+    if (present === NULL_LITERAL) {
+      // The JSON null literal is the caller's explicit "no value": leave the field null
+      // (do NOT apply @default — an explicit null is a value, not an omission), matching a
+      // standard JSON bind. Without this the bare `null` token leaks as the string "null".
+      report.set(path, f.required ? FieldExtraction.LOST_REQUIRED : FieldExtraction.LOST_OPTIONAL);
+      continue;
+    }
     if (f.array) {
       // An array field: a single non-list value is treated as a one-element array
       // (e.g. a single repeated-XML tag). Each element is coerced/recursed independently.
@@ -151,6 +164,11 @@ function extractValue(
   o: ExtractOptions,
   ci: boolean,
 ): unknown | typeof MALFORMED {
+  if (present === NULL_LITERAL) {
+    // A JSON null array element (e.g. [1, null, 3]) carries no value → drop it as malformed
+    // rather than letting the sentinel stringify.
+    return MALFORMED;
+  }
   if (f.kind === FieldKind.OBJECT) {
     if (f.nested != null && isPlainObject(present)) {
       const nestedData: Record<string, unknown> = {};
@@ -159,6 +177,12 @@ function extractValue(
     }
     return MALFORMED; // object expected but scalar/non-map present
   }
+  // A text element that also carried XML attributes is represented by readXml as a record with
+  // the body under TEXT_KEY. A scalar field reads that text (attributes ignored for scalars —
+  // preserving pre-attribute-support behaviour).
+  if (isPlainObject(present) && Object.prototype.hasOwnProperty.call(present, TEXT_KEY)) {
+    present = (present as Record<string, unknown>)[TEXT_KEY];
+  }
   const rawStr = typeof present === "string" ? present : stringifyScalar(present);
   return coerceValue(rawStr, f, o, path, report);
 }

package/src/extract/json-forgiving-reader.ts

@@ -4,6 +4,14 @@
 /** Sentinel: a key appeared in the text but its value was empty/cut-off (present-but-garbled). */
 export const TRUNCATED: unique symbol = Symbol("extract.json.TRUNCATED");
 
+/**
+ * Sentinel: the JSON `null` literal. Distinct from a JS `null` return (which this reader uses
+ * internally for "no token / garbled") and from the 4-char string "null". The extract phase maps
+ * this to an actual null field value (JSON null → null), instead of letting the bare `null` literal
+ * leak through as the text "null".
+ */
+export const NULL_LITERAL: unique symbol = Symbol("extract.json.NULL_LITERAL");
+
 /** A character is JSON-insignificant whitespace. Mirrors Java Character.isWhitespace closely enough for the corpus. */
 function isWhitespace(c: string): boolean {
   return c === " " || c === "\t" || c === "\n" || c === "\r" || c === "\f" || c === "\v" || /\s/.test(c);
@@ -132,11 +140,13 @@ class Reader {
     return sb; // unterminated string → return what we have
   }
 
-  private readBareScalar(): string | null {
+  private readBareScalar(): string | null | typeof NULL_LITERAL {
     const start = this.i;
     while (this.i < this.s.length && ",}]".indexOf(this.s.charAt(this.i)) < 0) this.i++;
     const result = this.s.substring(start, this.i).trim();
-    return result.length === 0 ? null : result; // null = no token read (zero-width)
+    if (result.length === 0) return null; // no token read (zero-width)
+    if (result === "null") return NULL_LITERAL; // JSON null literal → explicit null, NOT the string "null"
+    return result;
   }
 
   private ws(): void {

package/src/extract/types.ts

@@ -85,6 +85,13 @@ export interface FieldSpec {
   readonly defaultValue: string | null;
   /** FR-011: resolved enum normalization mode (from `@normalize`; default `"strip"`). */
   readonly normalize: NormalizeMode;
+  /**
+   * `@xmlText`: this field receives its element's TEXT CONTENT (analogous to JAXB `@XmlValue` /
+   * Jackson `@JacksonXmlText` / .NET `[XmlText]`). The extract engine reads it from the
+   * `#text` sentinel the lenient XML reader carries when an element has both attributes and a
+   * text body, instead of a same-named child. Absent/false for normal fields and for JSON.
+   */
+  readonly textContent?: boolean;
 }
 
 /**
@@ -115,6 +122,14 @@ export function scalar(
   };
 }
 
+/**
+ * A field that receives its element's TEXT CONTENT — the `@xmlText` marker (see
+ * {@link FieldSpec.textContent}). A scalar with the `textContent` flag set; coerced to `kind`.
+ */
+export function textContentField(name: string, kind: FieldKind, required: boolean): FieldSpec {
+  return { ...scalar(name, kind, required), textContent: true };
+}
+
 export function enumField(
   name: string,
   required: boolean,
@@ -231,16 +246,23 @@ export type OnField = (fieldPath: string, rawValue: string, spec: FieldSpec) =>
 /**
  * Bounded runtime override surface. aliases/normalizers are MERGED with the
  * schema's, runtime winning on key conflict. onField is the single hook.
+ *
+ * `rootless` (XML only): when `true`, the input has NO enclosing root element — the payload's
+ * fields ARE the top-level elements (a flat sequence like `<a>..</a><b>..</b>`). The engine
+ * parses those top-level elements directly instead of locating a `<rootName>` span, so the caller
+ * need not synthesize a wrapper. No effect for JSON. Default `false` (a single root element is
+ * expected, as before). Mirrors Java ExtractOptions.rootless.
  */
 export interface ExtractOptions {
   readonly tolerance: Tolerance;
   readonly aliases: Readonly<Record<string, string>>;
   readonly normalizers: Readonly<Record<string, (raw: string) => unknown | null>>;
   readonly onField: OnField | null;
+  readonly rootless: boolean;
 }
 
 export function defaults(): ExtractOptions {
-  return { tolerance: Tolerance.NORMAL, aliases: {}, normalizers: {}, onField: null };
+  return { tolerance: Tolerance.NORMAL, aliases: {}, normalizers: {}, onField: null, rootless: false };
 }
 
 /** Normalize a partial / undefined options bag into a complete ExtractOptions. */
@@ -251,6 +273,7 @@ export function normalizeOptions(opts?: Partial<ExtractOptions> | null): Extract
     aliases: opts.aliases == null ? {} : { ...opts.aliases },
     normalizers: opts.normalizers == null ? {} : { ...opts.normalizers },
     onField: opts.onField ?? null,
+    rootless: opts.rootless ?? false,
   };
 }
 

package/src/extract/xml-forgiving-reader.ts

@@ -1,5 +1,21 @@
 // Stage-4 tolerant XML reader for the bounded corpus malformation set. Never throws.
-// Mirrors Java XmlForgivingReader. Must not index-out-of-range on a leading close tag.
+// Mirrors Java XmlForgivingReader: maps an element's child elements, text, AND attributes
+// into the field map, and handles self-closing tags (<x a="1"/>). Must not index-out-of-range
+// on a leading close tag.
+//
+// Representation:
+//   - text-only element, no attributes        → its trimmed text (string) — unchanged
+//   - self-closing / attributes-only element   → a record of attribute name→value ("" when none)
+//   - element with child elements (± attrs)     → a record merging attributes + child entries
+//                                                  (a child element wins a name collision)
+//   - element with text AND attributes          → a record of the attributes plus the body text
+//                                                  under TEXT_KEY (a scalar consumer unwraps it)
+//   - repeated sibling tags                     → an array (unchanged)
+
+/** Reserved key holding an element's own text content when the element is represented as a
+ *  record (because it also carries attributes). '#' is not a legal XML name char, so it never
+ *  collides with a real attribute or child-element name. */
+export const TEXT_KEY = "#text";
 
 function quote(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -12,7 +28,11 @@ function matchFrom(source: string, flags: string, text: string, from: number): R
   return g.exec(text);
 }
 
-const OPEN_TAG_SRC = "<([A-Za-z_][A-Za-z0-9_]*)(\\s[^>]*)?>";
+// tag name + everything up to the closing '>' (attributes and/or a trailing '/' for a
+// self-closing tag). Non-greedy so the first '>' closes the open tag.
+const OPEN_TAG_SRC = "<([A-Za-z_][A-Za-z0-9_]*)([^>]*?)>";
+// one attribute: name = "double" | 'single' | bareword.
+const ATTR_SRC = "([A-Za-z_:][A-Za-z0-9_:.\\-]*)\\s*=\\s*(?:\"([^\"]*)\"|'([^']*)'|([^\\s/>]+))";
 
 export function readXml(span: string | null | undefined, caseInsensitive: boolean): Record<string, unknown> {
   const out: Record<string, unknown> = {};
@@ -25,6 +45,21 @@ export function readXml(span: string | null | undefined, caseInsensitive: boolea
   return out;
 }
 
+/**
+ * Rootless read: parse the WHOLE text's top-level elements directly, with no enclosing root
+ * element to strip (a flat sequence like `<a>..</a><b>..</b>`). Used for `ExtractOptions.rootless`
+ * responses. Leading/trailing non-element text is ignored. Never throws. Mirrors Java readRootless.
+ */
+export function readXmlRootless(
+  text: string | null | undefined,
+  caseInsensitive: boolean,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (text == null || text.trim().length === 0) return out;
+  parseChildren(text, caseInsensitive, out);
+  return out;
+}
+
 function parseChildren(inner: string, ci: boolean, out: Record<string, unknown>): void {
   const flags = ci ? "i" : "";
   let pos = 0;
@@ -33,8 +68,19 @@ function parseChildren(inner: string, ci: boolean, out: Record<string, unknown>)
     if (m == null) break;
     const tag = m[1] ?? "";
     const key = ci ? tag.toLowerCase() : tag;
-    const contentStart = m.index + m[0].length;
 
+    let rawAttrs = (m[2] ?? "").trim();
+    const selfClosing = rawAttrs.endsWith("/");
+    if (selfClosing) rawAttrs = rawAttrs.slice(0, -1).trim();
+    const attrs = parseAttrs(rawAttrs, ci);
+
+    if (selfClosing) {
+      accumulate(out, key, Object.keys(attrs).length === 0 ? "" : attrs);
+      pos = m.index + m[0].length;
+      continue;
+    }
+
+    const contentStart = m.index + m[0].length;
     const closeRe = `</${quote(tag)}\\s*>`;
     const close = matchFrom(closeRe, flags, inner, contentStart);
 
@@ -44,11 +90,25 @@ function parseChildren(inner: string, ci: boolean, out: Record<string, unknown>)
       contentEnd = close.index;
       next = close.index + close[0].length;
     } else {
-      // unclosed tag: extract text up to the next sibling open tag
+      // unclosed tag: extract content up to the next sibling open tag.
       const sib = matchFrom(OPEN_TAG_SRC, flags, inner, contentStart);
       if (sib != null) {
-        contentEnd = sib.index;
-        next = contentEnd;
+        // When the unclosed element's content begins IMMEDIATELY with a child open tag
+        // (no leading text), that child was almost certainly meant to be NESTED, not a
+        // sibling — a common LLM malformation is dropping the parent's close tag while
+        // still emitting a real child element (e.g. <check ...><payoff>text). Absorb the
+        // remainder of this span as the unclosed element's content so the child nests
+        // under it. When there IS leading text before the first child tag (e.g. <t>hi<c>..),
+        // keep the sibling split — the leading text is the unclosed element's body and the
+        // following tag is its sibling. Mirrors Java XmlForgivingReader.
+        const noLeadingText = inner.substring(contentStart, sib.index).trim().length === 0;
+        if (noLeadingText) {
+          contentEnd = inner.length;
+          next = inner.length;
+        } else {
+          contentEnd = sib.index;
+          next = contentEnd;
+        }
       } else {
         contentEnd = inner.length;
         next = inner.length;
@@ -56,16 +116,43 @@ function parseChildren(inner: string, ci: boolean, out: Record<string, unknown>)
     }
 
     const content = inner.substring(contentStart, contentEnd);
-    const value: unknown = content.includes("<") ? nestedOrText(content, ci) : content.trim();
-    accumulate(out, key, value);
+    accumulate(out, key, combine(attrs, content, ci));
     pos = next;
   }
 }
 
-function nestedOrText(content: string, ci: boolean): unknown {
-  const nested: Record<string, unknown> = {};
-  parseChildren(content, ci, nested);
-  return Object.keys(nested).length === 0 ? content.trim() : nested;
+/** Combine an element's attributes with its body (nested children or plain text). */
+function combine(attrs: Record<string, unknown>, content: string, ci: boolean): unknown {
+  if (content.includes("<")) {
+    const nested: Record<string, unknown> = {};
+    parseChildren(content, ci, nested);
+    if (Object.keys(nested).length > 0) {
+      // attributes first; a child element wins a name collision
+      return { ...attrs, ...nested };
+    }
+  }
+  return textValue(attrs, content);
+}
+
+function textValue(attrs: Record<string, unknown>, content: string): unknown {
+  const text = content.trim();
+  if (Object.keys(attrs).length === 0) return text;
+  return { ...attrs, [TEXT_KEY]: text };
+}
+
+function parseAttrs(rawAttrs: string, ci: boolean): Record<string, unknown> {
+  const attrs: Record<string, unknown> = {};
+  if (rawAttrs.length === 0) return attrs;
+  const re = new RegExp(ATTR_SRC, "g");
+  let a: RegExpExecArray | null;
+  while ((a = re.exec(rawAttrs)) != null) {
+    const rawName = a[1];
+    if (rawName === undefined) continue; // group 1 is mandatory in a match; guards strict TS
+    const name = ci ? rawName.toLowerCase() : rawName;
+    const val = a[2] ?? a[3] ?? a[4] ?? "";
+    if (!Object.prototype.hasOwnProperty.call(attrs, name)) attrs[name] = val;
+  }
+  return attrs;
 }
 
 function accumulate(out: Record<string, unknown>, key: string, value: unknown): void {

package/src/index.ts

@@ -3,11 +3,14 @@ export { type Provider, InMemoryProvider } from "./provider.js";
 export { ESCAPERS, type RenderFormat } from "./escapers.js";
 export {
   verify,
+  resolveTemplateVariable,
+  parseTemplate,
   ERR_VAR_NOT_ON_PAYLOAD,
   ERR_PARTIAL_UNRESOLVED,
   ERR_REQUIRED_SLOT_UNUSED,
   ERR_OUTPUT_TAG_MISSING,
   type PayloadField,
+  type ResolveStack,
   type VerifyError,
   type VerifyOptions,
 } from "./verify.js";
@@ -21,6 +24,7 @@ export {
   Tolerance,
   ExtractionReport,
   scalar,
+  textContentField,
   enumField,
   enumArray,
   range,

package/src/verify.ts

@@ -54,20 +54,34 @@ const MAX_DEPTH = 32;
 
 // A Mustache parse token: [type, value, start, end, subTokens?, ...].
 type Token = readonly unknown[];
-// The context stack — innermost context last, mirroring Mustache lookup order.
-type Stack = readonly PayloadField[][];
+/**
+ * The context stack — innermost context last, mirroring Mustache lookup order.
+ * Generic over the field node so consumers (e.g. the docs annotator) can resolve
+ * an ENRICHED field tree (carrying owner/type metadata) through the EXACT same
+ * walk verify uses, guaranteeing the two surfaces agree.
+ */
+export type ResolveStack<F extends PayloadField = PayloadField> = readonly F[][];
 
-function find(fields: PayloadField[], name: string): PayloadField | undefined {
+function find<F extends PayloadField>(fields: F[], name: string): F | undefined {
   return fields.find((f) => f.name === name);
 }
 
-// Resolve a (possibly dotted) variable path the way Mustache does: the FIRST
-// segment is looked up through the context stack (innermost → outermost); each
-// remaining segment is a direct descent into the resolved field's `fields`.
-// Returns the resolved field, or undefined if any segment is missing.
-function resolve(stack: Stack, path: string): PayloadField | undefined {
+/**
+ * Resolve a (possibly dotted) variable path the way Mustache does: the FIRST
+ * segment is looked up through the context stack (innermost → outermost); each
+ * remaining segment is a direct descent into the resolved field's `fields`.
+ * Returns the resolved field, or undefined if any segment is missing.
+ *
+ * EXPORTED so the docs annotator can share this ONE resolution (annotator ⇆
+ * verify must agree). Generic over the node type: an enriched tree resolves the
+ * same way, since only `name`/`fields` drive the walk.
+ */
+export function resolveTemplateVariable<F extends PayloadField>(
+  stack: ResolveStack<F>,
+  path: string,
+): F | undefined {
   const segs = path.split(".");
-  let current: PayloadField | undefined;
+  let current: F | undefined;
   for (let i = stack.length - 1; i >= 0; i--) {
     const hit = find(stack[i]!, segs[0]!);
     if (hit) {
@@ -76,15 +90,27 @@ function resolve(stack: Stack, path: string): PayloadField | undefined {
     }
   }
   for (let i = 1; current && i < segs.length; i++) {
-    current = current.fields ? find(current.fields, segs[i]!) : undefined;
+    current = current.fields ? (find(current.fields, segs[i]!) as F | undefined) : undefined;
   }
   return current;
 }
 
+// Internal alias preserving the original call sites unchanged.
+const resolve = resolveTemplateVariable;
+
 function parse(text: string): Token[] {
   return Mustache.parse(text) as unknown as Token[];
 }
 
+/**
+ * Parse a template into Mustache tokens (`[type, value, start, end, subTokens?]`),
+ * the SAME parse verify walks. Exported so the docs annotator tokenizes through
+ * one parser (no divergent re-tokenization). Returns a readonly token list.
+ */
+export function parseTemplate(text: string): readonly (readonly unknown[])[] {
+  return parse(text);
+}
+
 // An opening tag is `<tag` immediately followed by `>` or XML whitespace, so
 // attributes are allowed (`<answer foo="1">`) but a longer name is not over-matched
 // (`<answers>` does not satisfy `answer`).
@@ -124,7 +150,7 @@ export function verify(
   // (no second resolution pass).
   const staticTexts: string[] = [templateText];
 
-  function walk(tokens: Token[], stack: Stack, seen: readonly string[]): void {
+  function walk(tokens: Token[], stack: ResolveStack, seen: readonly string[]): void {
     const atRoot = stack.length === 1 && stack[0] === root;
     for (const tok of tokens) {
       const type = tok[0] as string;