@beyondwork/docx-react-component 1.0.29 → 1.0.30

package/src/io/ooxml/parse-fields.ts

@@ -0,0 +1,834 @@
+/**
+ * parse-fields.ts
+ *
+ * Standalone parsers for OOXML field codes (w:fldSimple, complex fldChar sequences)
+ * and bookmarks (w:bookmarkStart / w:bookmarkEnd).
+ *
+ * These types mirror the canonical FieldNode / BookmarkStartNode / BookmarkEndNode
+ * shapes from canonical-document.ts, but carry raw XML for preservation and are
+ * pre-normalization (no fragmentId / warningId yet).
+ *
+ * Usage: call parseFieldsFromParagraphXml() or parseBookmarksFromXml() for
+ * independent field/bookmark extraction.  The functions are designed to be
+ * imported by parse-main-document.ts when full pipeline integration is ready.
+ */
+
+// ─── Parsed types ────────────────────────────────────────────────────────────
+
+export interface ParsedSimpleFieldNode {
+  type: "field";
+  fieldType: "simple";
+  instruction: string;
+  /** Raw XML of the content runs inside <w:fldSimple>. */
+  contentXml: string;
+  rawXml: string;
+}
+
+export interface ParsedComplexFieldNode {
+  type: "field";
+  fieldType: "complex";
+  instruction: string;
+  /** Raw XML of the content runs between the "separate" and "end" fldChar. */
+  contentXml: string;
+  /** Start index in the source document XML. */
+  start: number;
+  /** End index (exclusive) in the source document XML. */
+  end: number;
+}
+
+export type ParsedFieldNode = ParsedSimpleFieldNode | ParsedComplexFieldNode;
+
+export interface ParsedBookmarkStartNode {
+  type: "bookmark_start";
+  bookmarkId: string;
+  name: string;
+  rawXml: string;
+}
+
+export interface ParsedBookmarkEndNode {
+  type: "bookmark_end";
+  bookmarkId: string;
+  rawXml: string;
+}
+
+export type ParsedBookmarkNode = ParsedBookmarkStartNode | ParsedBookmarkEndNode;
+
+// ─── Internal XML types ───────────────────────────────────────────────────────
+
+interface XmlElementNode {
+  type: "element";
+  name: string;
+  attributes: Record<string, string>;
+  children: XmlNode[];
+  start: number;
+  end: number;
+}
+
+interface XmlTextNode {
+  type: "text";
+  text: string;
+  start: number;
+  end: number;
+}
+
+type XmlNode = XmlElementNode | XmlTextNode;
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Parse all simple fields and bookmarks from the XML of a single paragraph
+ * element.  Complex fields that span paragraphs are not fully resolved here;
+ * use extractComplexFieldsFromBodyXml for body-level extraction.
+ *
+ * @param paragraphXml  Raw XML string of a <w:p> element.
+ */
+export function parseFieldsFromParagraphXml(paragraphXml: string): {
+  simpleFields: ParsedSimpleFieldNode[];
+  bookmarks: ParsedBookmarkNode[];
+} {
+  const root = parseXml(paragraphXml);
+  const pEl = findFirstChild(root, "p");
+  const target = pEl ?? root;
+
+  const simpleFields: ParsedSimpleFieldNode[] = [];
+  const bookmarks: ParsedBookmarkNode[] = [];
+
+  for (const child of target.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+
+    if (name === "fldSimple") {
+      const field = parseFldSimple(child, paragraphXml);
+      if (field) simpleFields.push(field);
+    } else if (name === "bookmarkStart") {
+      const bk = parseBookmarkStart(child, paragraphXml);
+      if (bk) bookmarks.push(bk);
+    } else if (name === "bookmarkEnd") {
+      const bk = parseBookmarkEnd(child, paragraphXml);
+      if (bk) bookmarks.push(bk);
+    }
+  }
+
+  return { simpleFields, bookmarks };
+}
+
+/**
+ * Extract complex field sequences from a body element XML string.
+ * A complex field is a begin / instrText* / separate / content / end sequence
+ * spread across multiple <w:r> siblings.
+ *
+ * @param bodyXml  Raw XML string of a <w:body> element (or full document).
+ */
+export function extractComplexFieldsFromBodyXml(bodyXml: string): ParsedComplexFieldNode[] {
+  const root = parseXml(bodyXml);
+  const results: ParsedComplexFieldNode[] = [];
+
+  // Walk all <w:p> children of the body
+  const bodyEl = findFirstChild(root, "body") ?? findFirstChild(root, "document");
+  const scanTarget = bodyEl ?? root;
+
+  for (const block of scanTarget.children) {
+    if (block.type !== "element") continue;
+    if (localName(block.name) !== "p") continue;
+    extractComplexFieldsFromParagraph(block, bodyXml, results);
+  }
+
+  return results;
+}
+
+/**
+ * Parse all bookmark start/end nodes from a full document or body XML.
+ */
+export function extractBookmarksFromBodyXml(bodyXml: string): ParsedBookmarkNode[] {
+  const root = parseXml(bodyXml);
+  const results: ParsedBookmarkNode[] = [];
+  collectBookmarks(root, bodyXml, results);
+  return results;
+}
+
+// ─── Element-level parsers (exported for unit testing) ────────────────────────
+
+export function parseFldSimple(
+  element: { attributes: Record<string, string>; children: XmlNode[]; start: number; end: number },
+  sourceXml: string,
+): ParsedSimpleFieldNode | undefined {
+  const instruction = (element.attributes["w:instr"] ?? element.attributes.instr ?? "").trim();
+  const contentXml = element.children
+    .filter((c): c is XmlElementNode => c.type === "element")
+    .map((c) => sourceXml.slice(c.start, c.end))
+    .join("");
+  return {
+    type: "field",
+    fieldType: "simple",
+    instruction,
+    contentXml,
+    rawXml: sourceXml.slice(element.start, element.end),
+  };
+}
+
+export function parseBookmarkStart(
+  element: { attributes: Record<string, string>; start: number; end: number },
+  sourceXml: string,
+): ParsedBookmarkStartNode | undefined {
+  const bookmarkId = element.attributes["w:id"] ?? element.attributes.id ?? "";
+  const name = element.attributes["w:name"] ?? element.attributes.name ?? "";
+  if (!bookmarkId) return undefined;
+  return {
+    type: "bookmark_start",
+    bookmarkId,
+    name,
+    rawXml: sourceXml.slice(element.start, element.end),
+  };
+}
+
+export function parseBookmarkEnd(
+  element: { attributes: Record<string, string>; start: number; end: number },
+  sourceXml: string,
+): ParsedBookmarkEndNode | undefined {
+  const bookmarkId = element.attributes["w:id"] ?? element.attributes.id ?? "";
+  if (!bookmarkId) return undefined;
+  return {
+    type: "bookmark_end",
+    bookmarkId,
+    rawXml: sourceXml.slice(element.start, element.end),
+  };
+}
+
+// ─── Field family classification ─────────────────────────────────────────────
+
+import type {
+  CanonicalDocument,
+  DocumentNode,
+  FieldFamily,
+  FieldNode,
+  FieldRegistry,
+  FieldRegistryEntry,
+  FieldRefreshStatus,
+  InlineNode,
+  ParagraphNode,
+  SubPartsCatalog,
+  SupportedFieldFamily,
+  TocEntry,
+  TocStructure,
+} from "../../model/canonical-document.ts";
+
+const FIELD_FAMILY_PATTERN =
+  /^\s*(REF|PAGEREF|NOTEREF|TOC|PAGE|NUMPAGES|DATE|TIME|AUTHOR|FILENAME|MERGEFIELD|IF|SEQ|INDEX|TC|STYLEREF)\b/i;
+
+const SUPPORTED_FAMILIES = new Set<string>(["REF", "PAGEREF", "NOTEREF", "TOC"]);
+
+/**
+ * Classify a field instruction into its field family.
+ * Returns the family enum value and whether it is in the supported slice.
+ */
+export function classifyFieldInstruction(instruction: string): {
+  family: FieldFamily;
+  supported: boolean;
+  target?: string;
+} {
+  const trimmed = instruction.trim();
+  const match = FIELD_FAMILY_PATTERN.exec(trimmed);
+  if (!match) {
+    return { family: "UNKNOWN", supported: false };
+  }
+
+  const family = match[1].toUpperCase() as FieldFamily;
+  const supported = SUPPORTED_FAMILIES.has(family);
+
+  let target: string | undefined;
+  if (family === "REF" || family === "PAGEREF" || family === "NOTEREF") {
+    const targetMatch = /^\s*(?:REF|PAGEREF|NOTEREF)\s+(?:"([^"]+)"|(\S+))/i.exec(trimmed);
+    target = (targetMatch?.[1] ?? targetMatch?.[2])?.trim();
+  }
+
+  return { family, supported, target };
+}
+
+/**
+ * Returns true if the given field family is in the supported refresh slice.
+ */
+export function isSupportedFieldFamily(family: FieldFamily): family is SupportedFieldFamily {
+  return SUPPORTED_FAMILIES.has(family);
+}
+
+// ─── Field registry builder ─────────────────────────────────────────────────
+
+/**
+ * Build a field registry from a canonical document, cataloging every field
+ * instance with its classification, dependency metadata, and refresh status.
+ *
+ * The registry partitions fields into `supported` (REF, PAGEREF, NOTEREF, TOC)
+ * and `preserveOnly` (all others) slices.
+ */
+export function buildFieldRegistry(
+  document: Pick<CanonicalDocument, "content" | "styles"> & {
+    subParts?: SubPartsCatalog;
+  },
+): FieldRegistry {
+  const root = document.content;
+  const supported: FieldRegistryEntry[] = [];
+  const preserveOnly: FieldRegistryEntry[] = [];
+  let fieldIndex = 0;
+  let paragraphIndex = -1;
+  let tocInstruction: string | undefined;
+
+  walkFieldDocument(root, (node, pIdx) => {
+    paragraphIndex = pIdx;
+    if (node.type === "field") {
+      const classification = node.fieldFamily
+        ? { family: node.fieldFamily, supported: isSupportedFieldFamily(node.fieldFamily), target: node.fieldTarget }
+        : classifyFieldInstruction(node.instruction);
+      const displayText = flattenFieldText(node.children);
+      const entry: FieldRegistryEntry = {
+        fieldIndex,
+        fieldFamily: classification.family,
+        supported: classification.supported,
+        instruction: node.instruction,
+        ...(classification.target ? { fieldTarget: classification.target } : {}),
+        displayText,
+        paragraphIndex,
+        refreshStatus: node.refreshStatus ?? (classification.supported ? "stale" : "preserve-only"),
+      };
+      if (classification.supported) {
+        supported.push(entry);
+        if (classification.family === "TOC" && !tocInstruction) {
+          tocInstruction = node.instruction;
+        }
+      } else {
+        preserveOnly.push(entry);
+      }
+      fieldIndex += 1;
+    }
+  });
+  if (document.subParts) {
+    walkSubPartFields(document.subParts, (node, pIdx) => {
+      paragraphIndex = pIdx;
+      if (node.type === "field") {
+        const classification = node.fieldFamily
+          ? { family: node.fieldFamily, supported: isSupportedFieldFamily(node.fieldFamily), target: node.fieldTarget }
+          : classifyFieldInstruction(node.instruction);
+        const displayText = flattenFieldText(node.children);
+        const entry: FieldRegistryEntry = {
+          fieldIndex,
+          fieldFamily: classification.family,
+          supported: classification.supported,
+          instruction: node.instruction,
+          ...(classification.target ? { fieldTarget: classification.target } : {}),
+          displayText,
+          paragraphIndex,
+          refreshStatus: node.refreshStatus ?? (classification.supported ? "stale" : "preserve-only"),
+        };
+        if (classification.supported) {
+          supported.push(entry);
+        } else {
+          preserveOnly.push(entry);
+        }
+        fieldIndex += 1;
+      }
+    });
+  }
+
+  const tocStructure = tocInstruction
+    ? buildTocStructure(document, tocInstruction)
+    : undefined;
+
+  return {
+    supported,
+    preserveOnly,
+    ...(tocStructure ? { tocStructure } : {}),
+  };
+}
+
+/**
+ * Parse the heading level range from a TOC field instruction.
+ * The \\o switch specifies the outline level range (e.g. \\o "1-3").
+ * Defaults to 1-9 if no \\o switch is present.
+ */
+export function parseTocLevelRange(instruction: string): { from: number; to: number } {
+  const match = /\\o\s+"(\d+)-(\d+)"/.exec(instruction);
+  if (match) {
+    return { from: Number.parseInt(match[1], 10), to: Number.parseInt(match[2], 10) };
+  }
+  return { from: 1, to: 9 };
+}
+
+/**
+ * Build a TocStructure from the document's heading paragraphs and the
+ * TOC field instruction.  This produces a deterministic, package-backed
+ * TOC model that the runtime can use for refresh without DOM recomputation.
+ */
+export function buildTocStructure(
+  document: Pick<CanonicalDocument, "content" | "styles">,
+  instruction: string,
+): TocStructure {
+  const levelRange = parseTocLevelRange(instruction);
+  const entries: TocEntry[] = [];
+  let paragraphIndex = -1;
+
+  walkFieldDocument(document.content, (node, pIdx) => {
+    paragraphIndex = pIdx;
+    if (node.type !== "paragraph") return;
+    const paragraph = node as ParagraphNode;
+
+    // Determine heading level from outlineLevel or style
+    let level: number | undefined = paragraph.outlineLevel;
+    if (level === undefined && paragraph.styleId) {
+      const style = document.styles.paragraphs[paragraph.styleId];
+      if (style?.outlineLevel !== undefined) {
+        level = style.outlineLevel;
+      }
+    }
+
+    if (level === undefined) return;
+    // TOC outline levels are 0-based internally, 1-based in TOC notation
+    const tocLevel = level + 1;
+    if (tocLevel < levelRange.from || tocLevel > levelRange.to) return;
+
+    const text = flattenParagraphInlineText(paragraph.children);
+    if (text.trim().length === 0) return;
+
+    // Find bookmark anchoring this heading
+    let bookmarkName: string | undefined;
+    for (const child of paragraph.children) {
+      if (child.type === "bookmark_start" && child.name) {
+        bookmarkName = child.name;
+        break;
+      }
+    }
+
+    entries.push({
+      text: text.trim(),
+      level: tocLevel,
+      paragraphIndex,
+      ...(paragraph.styleId ? { styleId: paragraph.styleId } : {}),
+      ...(bookmarkName ? { bookmarkName } : {}),
+    });
+  });
+
+  return {
+    instruction,
+    levelRange,
+    entries,
+    status: "stale",
+  };
+}
+
+/**
+ * Deterministic refresh helper for REF fields.
+ * Given a bookmark name map and the document content, resolves the display
+ * text for a REF field by extracting text from the bookmarked paragraph.
+ *
+ * Returns the resolved text, or undefined if the bookmark is not found.
+ */
+export function resolveRefFieldText(
+  document: Pick<CanonicalDocument, "content">,
+  bookmarkNameMap: Map<string, { bookmarkId: string; paragraphIndex: number }>,
+  fieldTarget: string,
+): { text: string; refreshStatus: "current" | "unresolvable" } | undefined {
+  const bookmark = bookmarkNameMap.get(fieldTarget);
+  if (!bookmark) {
+    return { text: "", refreshStatus: "unresolvable" };
+  }
+
+  // Find the paragraph at bookmarkIndex and extract its text content
+  let paragraphIndex = -1;
+  let resolvedText: string | undefined;
+
+  walkFieldDocument(document.content, (node, pIdx) => {
+    if (node.type !== "paragraph") return;
+    paragraphIndex = pIdx;
+    if (paragraphIndex === bookmark.paragraphIndex) {
+      resolvedText = flattenBookmarkContent(node as ParagraphNode, bookmark.bookmarkId);
+    }
+  });
+
+  if (resolvedText !== undefined) {
+    return { text: resolvedText, refreshStatus: "current" };
+  }
+  return { text: "", refreshStatus: "unresolvable" };
+}
+
+/**
+ * Deterministic refresh helper that updates all supported field entries
+ * in a registry with their current resolved status.
+ *
+ * This does NOT mutate the document nodes — it returns a new registry
+ * with updated refresh statuses.  A3 owns the runtime wiring that
+ * applies these to the live document.
+ */
+export function refreshFieldRegistry(
+  registry: FieldRegistry,
+  bookmarkNameMap: Map<string, { bookmarkId: string; paragraphIndex: number }>,
+): FieldRegistry {
+  const refreshed: FieldRegistryEntry[] = registry.supported.map((entry) => {
+    if (entry.fieldFamily === "TOC") {
+      // TOC refresh is handled through tocStructure, not individual entries
+      return { ...entry, refreshStatus: registry.tocStructure ? "current" : "stale" as FieldRefreshStatus };
+    }
+    if (!entry.fieldTarget) {
+      return { ...entry, refreshStatus: "unresolvable" as FieldRefreshStatus };
+    }
+    const bookmark = bookmarkNameMap.get(entry.fieldTarget);
+    if (!bookmark) {
+      return { ...entry, refreshStatus: "unresolvable" as FieldRefreshStatus };
+    }
+    return { ...entry, refreshStatus: "current" as FieldRefreshStatus };
+  });
+
+  return {
+    supported: refreshed,
+    preserveOnly: registry.preserveOnly,
+    ...(registry.tocStructure ? { tocStructure: registry.tocStructure } : {}),
+  };
+}
+
+// ─── Field registry internal helpers ────────────────────────────────────────
+
+function walkFieldDocument(
+  node: DocumentNode,
+  visit: (node: DocumentNode, paragraphIndex: number) => void,
+  paragraphIndex = -1,
+): number {
+  if (node.type === "paragraph") {
+    paragraphIndex += 1;
+  }
+  visit(node, paragraphIndex);
+
+  if ("children" in node && Array.isArray(node.children)) {
+    for (const child of node.children) {
+      paragraphIndex = walkFieldDocument(child as DocumentNode, visit, paragraphIndex);
+    }
+  }
+  if (node.type === "table") {
+    for (const row of node.rows) {
+      paragraphIndex = walkFieldDocument(row, visit, paragraphIndex);
+    }
+  } else if (node.type === "table_row") {
+    for (const cell of node.cells) {
+      paragraphIndex = walkFieldDocument(cell, visit, paragraphIndex);
+    }
+  }
+  return paragraphIndex;
+}
+
+function walkSubPartFields(
+  subParts: SubPartsCatalog,
+  visit: (node: DocumentNode, paragraphIndex: number) => void,
+): void {
+  for (const header of subParts.headers) {
+    for (const block of header.blocks) {
+      walkFieldDocument(block, visit);
+    }
+  }
+  for (const footer of subParts.footers) {
+    for (const block of footer.blocks) {
+      walkFieldDocument(block, visit);
+    }
+  }
+  if (subParts.footnoteCollection) {
+    for (const note of Object.values(subParts.footnoteCollection.footnotes)) {
+      for (const block of note.blocks) {
+        walkFieldDocument(block, visit);
+      }
+    }
+    for (const note of Object.values(subParts.footnoteCollection.endnotes)) {
+      for (const block of note.blocks) {
+        walkFieldDocument(block, visit);
+      }
+    }
+  }
+}
+
+function flattenFieldText(children: InlineNode[]): string {
+  return children
+    .map((child) => {
+      if (child.type === "text") return child.text;
+      if (child.type === "tab") return "\t";
+      if (child.type === "hard_break" || child.type === "column_break") return "\n";
+      return "";
+    })
+    .join("");
+}
+
+function flattenParagraphInlineText(children: InlineNode[]): string {
+  return children
+    .map((child) => {
+      if (child.type === "text") return child.text;
+      if (child.type === "tab") return "\t";
+      if (child.type === "hard_break" || child.type === "column_break") return "\n";
+      if (child.type === "hyperlink") return flattenFieldText(child.children);
+      if (child.type === "field") return flattenFieldText(child.children);
+      return "";
+    })
+    .join("");
+}
+
+function flattenBookmarkContent(
+  paragraph: ParagraphNode,
+  bookmarkId: string,
+): string {
+  let inside = false;
+  const parts: string[] = [];
+  for (const child of paragraph.children) {
+    if (child.type === "bookmark_start" && child.bookmarkId === bookmarkId) {
+      inside = true;
+      continue;
+    }
+    if (child.type === "bookmark_end" && child.bookmarkId === bookmarkId) {
+      break;
+    }
+    if (inside) {
+      if (child.type === "text") parts.push(child.text);
+      else if (child.type === "tab") parts.push("\t");
+      else if (child.type === "hard_break") parts.push("\n");
+    }
+  }
+  // If no bookmark boundaries found in this paragraph, return full paragraph text
+  if (!inside) {
+    return flattenParagraphInlineText(paragraph.children);
+  }
+  return parts.join("");
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+function extractComplexFieldsFromParagraph(
+  paragraph: XmlElementNode,
+  sourceXml: string,
+  results: ParsedComplexFieldNode[],
+): void {
+  type FieldState = "idle" | "in-instr" | "in-content";
+  let state: FieldState = "idle";
+  let instrParts: string[] = [];
+  let contentStart = -1;
+  let contentEnd = -1;
+  let fieldStart = -1;
+
+  for (const child of paragraph.children) {
+    if (child.type !== "element" || localName(child.name) !== "r") continue;
+
+    const fldChar = findFirstChildEl(child, "fldChar");
+    const instrText = findFirstChildEl(child, "instrText");
+
+    if (fldChar) {
+      const charType = (
+        fldChar.attributes["w:fldCharType"] ??
+        fldChar.attributes.fldCharType ??
+        ""
+      ).toLowerCase();
+
+      if (charType === "begin") {
+        state = "in-instr";
+        instrParts = [];
+        fieldStart = child.start;
+        contentStart = -1;
+        contentEnd = -1;
+      } else if (charType === "separate" && state === "in-instr") {
+        state = "in-content";
+        contentStart = child.end;
+      } else if (charType === "end") {
+        if (state === "in-content" || state === "in-instr") {
+          if (state === "in-content") {
+            contentEnd = child.start;
+          }
+          const instruction = instrParts.join("").trim();
+          const contentXml =
+            contentStart >= 0 && contentEnd >= contentStart
+              ? sourceXml.slice(contentStart, contentEnd)
+              : "";
+          results.push({
+            type: "field",
+            fieldType: "complex",
+            instruction,
+            contentXml,
+            start: fieldStart,
+            end: child.end,
+          });
+        }
+        state = "idle";
+        instrParts = [];
+      }
+    } else if (instrText && state === "in-instr") {
+      const text = instrText.children
+        .filter((c): c is XmlTextNode => c.type === "text")
+        .map((c) => c.text)
+        .join("");
+      instrParts.push(text);
+    }
+  }
+}
+
+function collectBookmarks(
+  node: XmlElementNode,
+  sourceXml: string,
+  results: ParsedBookmarkNode[],
+): void {
+  for (const child of node.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+    if (name === "bookmarkStart") {
+      const bk = parseBookmarkStart(child, sourceXml);
+      if (bk) results.push(bk);
+    } else if (name === "bookmarkEnd") {
+      const bk = parseBookmarkEnd(child, sourceXml);
+      if (bk) results.push(bk);
+    } else {
+      collectBookmarks(child, sourceXml, results);
+    }
+  }
+}
+
+function findFirstChild(node: XmlElementNode, childLocalName: string): XmlElementNode | undefined {
+  return node.children.find(
+    (c): c is XmlElementNode => c.type === "element" && localName(c.name) === childLocalName,
+  );
+}
+
+function findFirstChildEl(node: XmlElementNode, childLocalName: string): XmlElementNode | undefined {
+  return node.children.find(
+    (c): c is XmlElementNode => c.type === "element" && localName(c.name) === childLocalName,
+  );
+}
+
+function localName(name: string): string {
+  const sep = name.indexOf(":");
+  return sep >= 0 ? name.slice(sep + 1) : name;
+}
+
+// ─── Minimal XML parser (same pattern as parse-tables.ts) ────────────────────
+
+function parseXml(xml: string): XmlElementNode {
+  const root: XmlElementNode = {
+    type: "element",
+    name: "__root__",
+    attributes: {},
+    children: [],
+    start: 0,
+    end: xml.length,
+  };
+  const stack: XmlElementNode[] = [root];
+  let cursor = 0;
+
+  while (cursor < xml.length) {
+    if (xml.startsWith("<!--", cursor)) {
+      const end = xml.indexOf("-->", cursor);
+      cursor = end >= 0 ? end + 3 : xml.length;
+      continue;
+    }
+    if (xml.startsWith("<?", cursor)) {
+      const end = xml.indexOf("?>", cursor);
+      cursor = end >= 0 ? end + 2 : xml.length;
+      continue;
+    }
+    if (xml.startsWith("<![CDATA[", cursor)) {
+      const end = xml.indexOf("]]>", cursor);
+      const textEnd = end >= 0 ? end : xml.length;
+      stack[stack.length - 1]?.children.push({
+        type: "text",
+        text: xml.slice(cursor + 9, textEnd),
+        start: cursor,
+        end: end >= 0 ? end + 3 : xml.length,
+      });
+      cursor = end >= 0 ? end + 3 : xml.length;
+      continue;
+    }
+    if (xml[cursor] !== "<") {
+      const nextTag = xml.indexOf("<", cursor);
+      const end = nextTag >= 0 ? nextTag : xml.length;
+      const text = decodeXmlEntities(xml.slice(cursor, end));
+      if (text.length > 0) {
+        stack[stack.length - 1]?.children.push({ type: "text", text, start: cursor, end });
+      }
+      cursor = end;
+      continue;
+    }
+    if (xml[cursor + 1] === "/") {
+      const end = xml.indexOf(">", cursor);
+      if (end < 0) throw new Error("Malformed XML: missing >.");
+      const name = xml.slice(cursor + 2, end).trim();
+      const current = stack.pop();
+      if (!current || localName(current.name) !== localName(name)) {
+        throw new Error(`Malformed XML: unexpected closing tag </${name}>.`);
+      }
+      current.end = end + 1;
+      cursor = end + 1;
+      continue;
+    }
+    const tagEnd = findTagEnd(xml, cursor);
+    const tagBody = xml.slice(cursor + 1, tagEnd);
+    const selfClosing = /\/\s*$/.test(tagBody);
+    const { name, attributes } = parseTag(tagBody.replace(/\/\s*$/, "").trim());
+    const element: XmlElementNode = {
+      type: "element",
+      name,
+      attributes,
+      children: [],
+      start: cursor,
+      end: tagEnd + 1,
+    };
+    stack[stack.length - 1]?.children.push(element);
+    if (!selfClosing) stack.push(element);
+    cursor = tagEnd + 1;
+  }
+
+  if (stack.length !== 1) throw new Error("Malformed XML: unclosed element.");
+  return root;
+}
+
+function parseTag(tagBody: string): { name: string; attributes: Record<string, string> } {
+  let cursor = 0;
+  while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) cursor += 1;
+  const nameStart = cursor;
+  while (cursor < tagBody.length && !/\s/.test(tagBody[cursor] ?? "")) cursor += 1;
+  const name = tagBody.slice(nameStart, cursor);
+  const attributes: Record<string, string> = {};
+
+  while (cursor < tagBody.length) {
+    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) cursor += 1;
+    if (cursor >= tagBody.length) break;
+    const keyStart = cursor;
+    while (cursor < tagBody.length && !/[\s=]/.test(tagBody[cursor] ?? "")) cursor += 1;
+    const key = tagBody.slice(keyStart, cursor);
+    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) cursor += 1;
+    if (tagBody[cursor] !== "=") { attributes[key] = ""; continue; }
+    cursor += 1;
+    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) cursor += 1;
+    const quote = tagBody[cursor];
+    if (quote !== `"` && quote !== `'`) throw new Error(`Malformed XML attribute ${key}.`);
+    cursor += 1;
+    const valueStart = cursor;
+    while (cursor < tagBody.length && tagBody[cursor] !== quote) cursor += 1;
+    attributes[key] = decodeXmlEntities(tagBody.slice(valueStart, cursor));
+    cursor += 1;
+  }
+  return { name, attributes };
+}
+
+function findTagEnd(xml: string, start: number): number {
+  let cursor = start + 1;
+  let quote: string | null = null;
+  while (cursor < xml.length) {
+    const c = xml[cursor];
+    if (quote) { if (c === quote) quote = null; cursor += 1; continue; }
+    if (c === `"` || c === `'`) { quote = c; cursor += 1; continue; }
+    if (c === ">") return cursor;
+    cursor += 1;
+  }
+  throw new Error("Malformed XML: missing >.");
+}
+
+function decodeXmlEntities(value: string): string {
+  return value.replace(/&(#x[0-9a-fA-F]+|#\d+|amp|lt|gt|quot|apos);/g, (match, entity) => {
+    switch (entity) {
+      case "amp": return "&";
+      case "lt": return "<";
+      case "gt": return ">";
+      case "quot": return `"`;
+      case "apos": return `'`;
+      default:
+        if (entity.startsWith("#x")) return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
+        if (entity.startsWith("#")) return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
+        return match;
+    }
+  });
+}