@beyondwork/docx-react-component 1.0.47 → 1.0.49

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

@@ -153,6 +153,7 @@ export function parseStylesXml(xml: string): ParseStylesResult {
       switch (styleType) {
         case "paragraph": {
           const nextStyle = readLinkedStyleId(child, "next");
+          const linkedStyleId = readLinkedStyleId(child, "link");
           const outlineLevel = readParagraphStyleOutlineLevel(child);
           const numbering = readParagraphStyleNumbering(child);
           const pPrNode = findChildElementOptional(child, "pPr");
@@ -170,10 +171,12 @@ export function parseStylesXml(xml: string): ParseStylesResult {
             ...(numbering ? { numbering } : {}),
             ...(paragraphProperties ? { paragraphProperties } : {}),
             ...(runProperties ? { runProperties } : {}),
+            ...(linkedStyleId ? { linkedStyleId } : {}),
           };
           break;
         }
         case "character": {
+          const linkedStyleId = readLinkedStyleId(child, "link");
           const rPrNode = findChildElementOptional(child, "rPr");
           const runProperties = readRunProperties(rPrNode);
           characters[styleId] = {
@@ -183,6 +186,7 @@ export function parseStylesXml(xml: string): ParseStylesResult {
             isDefault,
             ...(basedOn ? { basedOn } : {}),
             ...(runProperties ? { runProperties } : {}),
+            ...(linkedStyleId ? { linkedStyleId } : {}),
           };
           break;
         }
@@ -209,6 +213,8 @@ export function parseStylesXml(xml: string): ParseStylesResult {
     }
   }
 
+  resolveStyleLinkReciprocals(paragraphs, characters, diagnostics);
+
   const hasLatent = Object.keys(latentStyles).length > 0;
   diagnostics.push(
     `parsed ${Object.keys(paragraphs).length} paragraph, ` +
@@ -250,6 +256,65 @@ function readLinkedStyleId(
   return el.attributes["w:val"] ?? el.attributes.val ?? undefined;
 }
 
+/**
+ * Second-pass resolver for `<w:link>` on paragraph ↔ character style pairs.
+ *
+ * Mirrors LibreOffice's StyleSheetTable.cxx around line 1533 ("Update the
+ * styles that were created before their linked styles"): after every style
+ * is ingested, walk the two catalogs and synthesize the reciprocal
+ * `linkedStyleId` on a partner whose source XML declared no `<w:link>` of
+ * its own. This makes the canonical catalog symmetric regardless of source
+ * declaration order.
+ *
+ * Conflict handling is conservative: if a style already declares its own
+ * linkedStyleId pointing at a different target, the existing value is left
+ * intact and a diagnostic is emitted so a future debugger can trace the
+ * conflicting source-side assertions.
+ *
+ * Dangling references (a `<w:link>` that points at a styleId not in either
+ * catalog) are preserved verbatim and logged as a diagnostic — matching
+ * LibreOffice's "keep the XML, warn the author" stance.
+ */
+function resolveStyleLinkReciprocals(
+  paragraphs: Record<string, ParagraphStyleDefinition>,
+  characters: Record<string, CharacterStyleDefinition>,
+  diagnostics: string[],
+): void {
+  const walkers: Array<{
+    catalog:
+      | Record<string, ParagraphStyleDefinition>
+      | Record<string, CharacterStyleDefinition>;
+    partnerCatalog:
+      | Record<string, ParagraphStyleDefinition>
+      | Record<string, CharacterStyleDefinition>;
+    label: string;
+  }> = [
+    { catalog: paragraphs, partnerCatalog: characters, label: "paragraph" },
+    { catalog: characters, partnerCatalog: paragraphs, label: "character" },
+  ];
+
+  for (const { catalog, partnerCatalog, label } of walkers) {
+    for (const style of Object.values(catalog)) {
+      const target = style.linkedStyleId;
+      if (!target) continue;
+      const partner = partnerCatalog[target];
+      if (!partner) {
+        diagnostics.push(
+          `style ${label} "${style.styleId}" declares <w:link w:val="${target}"/> but no matching ${label === "paragraph" ? "character" : "paragraph"} style was found; link preserved as dangling`,
+        );
+        continue;
+      }
+      if (partner.linkedStyleId === undefined) {
+        partner.linkedStyleId = style.styleId;
+      } else if (partner.linkedStyleId !== style.styleId) {
+        diagnostics.push(
+          `style ${label} "${style.styleId}" links to "${target}" but partner already links to "${partner.linkedStyleId}"; partner link retained`,
+        );
+      }
+    }
+  }
+}
+
 function readParagraphStyleOutlineLevel(
   styleNode: XmlElementNode,
 ): number | undefined {

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

@@ -4,22 +4,8 @@ import type {
   ThemeFontScheme,
   ResolvedTheme,
 } from "../../model/canonical-document.ts";
-
-// ---- XML node types (inline, no external dep) ----
-
-interface XmlElementNode {
-  type: "element";
-  name: string;
-  attributes: Record<string, string>;
-  children: XmlNode[];
-}
-
-interface XmlTextNode {
-  type: "text";
-  text: string;
-}
-
-type XmlNode = XmlElementNode | XmlTextNode;
+import type { XmlElementNode } from "./xml-element.ts";
+import { parseXml } from "./xml-parser.ts";
 
 // ---- Well-known DrawingML color slot names ----
 
@@ -233,114 +219,3 @@ function localName(name: string): string {
   return idx >= 0 ? name.slice(idx + 1) : name;
 }
 
-// ---- Minimal XML parser ----
-
-function parseXml(xml: string): XmlElementNode {
-  const root: XmlElementNode = {
-    type: "element",
-    name: "__root__",
-    attributes: {},
-    children: [],
-  };
-  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),
-      });
-      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.trim().length > 0 || (text.length > 0 && stack.length > 1)) {
-        stack[stack.length - 1]?.children.push({ type: "text", text });
-      }
-      cursor = end;
-      continue;
-    }
-
-    if (xml[cursor + 1] === "/") {
-      const end = xml.indexOf(">", cursor);
-      if (end < 0) break;
-      stack.pop();
-      cursor = end + 1;
-      continue;
-    }
-
-    const tagEnd = xml.indexOf(">", cursor);
-    if (tagEnd < 0) break;
-
-    const tagContent = xml.slice(cursor + 1, tagEnd);
-    const selfClosing = tagContent.endsWith("/");
-    const normalized = selfClosing ? tagContent.slice(0, -1).trimEnd() : tagContent;
-
-    const spaceIndex = normalized.search(/\s/);
-    const tagName = spaceIndex >= 0 ? normalized.slice(0, spaceIndex) : normalized;
-    const attrString = spaceIndex >= 0 ? normalized.slice(spaceIndex + 1) : "";
-    const attributes = parseAttributes(attrString);
-
-    const element: XmlElementNode = {
-      type: "element",
-      name: tagName,
-      attributes,
-      children: [],
-    };
-
-    stack[stack.length - 1]?.children.push(element);
-
-    if (!selfClosing) {
-      stack.push(element);
-    }
-
-    cursor = tagEnd + 1;
-  }
-
-  return root;
-}
-
-function parseAttributes(attrString: string): Record<string, string> {
-  const attrs: Record<string, string> = {};
-  const pattern = /([A-Za-z_:][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
-  for (const match of attrString.matchAll(pattern)) {
-    const name = match[1];
-    const value = match[3] ?? match[4] ?? "";
-    if (name) {
-      attrs[name] = decodeXmlEntities(value);
-    }
-  }
-  return attrs;
-}
-
-function decodeXmlEntities(text: string): string {
-  return text
-    .replace(/&amp;/g, "&")
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&apos;/g, "'")
-    .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number.parseInt(dec, 10)))
-    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) =>
-      String.fromCodePoint(Number.parseInt(hex, 16)),
-    );
-}

package/src/io/ooxml/property-grab-bag.ts

@@ -0,0 +1,211 @@
+/**
+ * Property-level grab-bag primitive for Lane 3 O2.
+ *
+ * LibreOffice captures unmodelled children / attributes on every OOXML
+ * property container (`<w:pPr>`, `<w:rPr>`, `<w:tcPr>`, `<w:trPr>`,
+ * `<w:tblPr>`, `<w:sectPr>`) via per-container "grab bags" keyed by
+ * element name — see `PropertyMap.hxx:82` and
+ * `libreoffice-analysis.md` §2 for the mechanism. On export, every grab
+ * bag re-emits verbatim inside its container so the round-trip pipeline
+ * does not silently drop extension-namespace properties (`w15:collapsed`,
+ * `w16cex:...`, etc.) or attributes Word adds after we parsed its schema.
+ *
+ * This module is a small, framework-free adapter: per-container parsers
+ * supply a descriptor listing modelled child names (and later, modelled
+ * attributes on modelled children); the helper returns everything else as
+ * raw XML in insertion order. The matching emitter is a one-liner that
+ * just joins `rawXml` strings.
+ *
+ * Scope (O2 Slice 1): per-container child diff only — the unknown-attribute
+ * diff on modelled children is a follow-up slice. Today the descriptor's
+ * `modelledChildAttributes` is declared but ignored; the helper emits a
+ * whole-child entry only when the element's localName is NOT in
+ * `modelledChildNames`.
+ */
+
+/**
+ * Input node shape accepted by `capturePropertyGrabBag`. Intentionally
+ * minimal so every caller can adapt their own scanner output — per-file
+ * parsers in `src/io/ooxml/` each carry a slightly different node shape.
+ */
+export interface GrabBagSourceChild {
+  /**
+   * Local element name (no namespace prefix). E.g. `"kinsoku"` for
+   * `<w:kinsoku>`, `"collapsed"` for `<w15:collapsed>`.
+   */
+  localName: string;
+  /**
+   * The source XML for the entire child element, including its opening
+   * tag, all attributes, any children, and its closing tag (or the
+   * self-closing form). Preserved verbatim for re-emission.
+   */
+  rawXml: string;
+}
+
+/**
+ * Interop helper for callers that only carry the parsed `XmlElementNode`
+ * shape used by `src/io/ooxml/xml-element.ts`. Reconstructs a best-effort
+ * `rawXml` string from the parsed tree so parsers that don't track source
+ * offsets can still feed the grab-bag helper.
+ *
+ * The reconstruction preserves element/attribute semantic content and
+ * attribute insertion order (since `Record<string, string>` iteration in
+ * V8 is insertion-ordered for string keys) but does NOT guarantee
+ * byte-identical source preservation: whitespace between elements and
+ * attribute quoting style are normalized. For the Slice 1 scope this is
+ * the correct trade-off — unmodelled children's semantic content
+ * survives, which closes the silent-drop gap.
+ */
+export function buildGrabBagSourceChildFromParsed(node: {
+  name: string;
+  attributes: Record<string, string>;
+  children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
+}): GrabBagSourceChild {
+  return {
+    localName: localNameOf(node.name),
+    rawXml: serializeElementToString(node),
+  };
+}
+
+function localNameOf(qualified: string): string {
+  const colon = qualified.indexOf(":");
+  return colon < 0 ? qualified : qualified.slice(colon + 1);
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;")
+    .replace(/"/gu, "&quot;");
+}
+
+function escapeText(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;");
+}
+
+function serializeElementToString(node: {
+  name: string;
+  attributes: Record<string, string>;
+  children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
+}): string {
+  const attrs = Object.entries(node.attributes)
+    .map(([name, value]) => ` ${name}="${escapeAttr(value)}"`)
+    .join("");
+  if (node.children.length === 0) {
+    return `<${node.name}${attrs}/>`;
+  }
+  const body = node.children
+    .map((child) => {
+      if (child.type === "text") return escapeText(child.text);
+      return serializeElementToString(
+        child as {
+          name: string;
+          attributes: Record<string, string>;
+          children: Array<{ type: "element"; name: string; attributes: Record<string, string>; children: unknown[] } | { type: "text"; text: string }>;
+        },
+      );
+    })
+    .join("");
+  return `<${node.name}${attrs}>${body}</${node.name}>`;
+}
+
+/**
+ * Descriptor a per-container parser supplies to the helper to declare
+ * which child element names it dispatches into its modelled fields.
+ * Children not listed here become grab-bag entries.
+ */
+export interface PropertyGrabBagDescriptor {
+  /**
+   * Set of local names the container parser handles natively. Children
+   * whose `localName` matches one of these are NOT captured.
+   */
+  modelledChildNames: ReadonlySet<string>;
+  /**
+   * Reserved for the follow-up slice: per-modelled-child the set of
+   * attributes the parser consumes. The Slice 1 helper ignores this
+   * field; Slice 2 will use it to emit attribute-level grab entries on
+   * modelled children.
+   *
+   * Note: table containers (tblPr/trPr/tcPr — O2 Slice 3) currently use
+   * a parallel raw-XML mechanism in `src/io/export/table-properties-xml.ts`
+   * (`mergePropertiesXml`) that stores the full container XML as a string
+   * on `TableNode.propertiesXml`/`TableRowNode.propertiesXml`/
+   * `TableCellNode.propertiesXml`. That path cannot participate in the
+   * attribute-level grab-bag slice until it is retrofit to emit
+   * `UnknownPropertyChild[]` through this descriptor. Tracked as a Lane 3
+   * Tier-2 backlog entry — see `docs/plans/lane-3-layout-engine-ooxml-fidelity.md`.
+   */
+  modelledChildAttributes: ReadonlyMap<string, ReadonlySet<string>>;
+}
+
+/**
+ * Single grab-bag entry: an unmodelled top-level child captured verbatim
+ * so the serializer can re-emit it inside its container without any
+ * round-trip loss.
+ */
+export interface UnknownPropertyChild {
+  /**
+   * Qualified element name as it appeared in the source (e.g.
+   * `"w:kinsoku"`, `"w15:collapsed"`). Used for diagnostics and for the
+   * future attribute-level diff so the emitter can re-open the matching
+   * element when needed.
+   */
+  elementName: string;
+  /**
+   * Verbatim XML for the child element.
+   */
+  rawXml: string;
+}
+
+/**
+ * Walk the container's direct children. Return every child whose
+ * `localName` is NOT in `descriptor.modelledChildNames` as a grab-bag
+ * entry in source order. Returns `undefined` when no unmodelled children
+ * were found — callers should prefer `undefined` over an empty array so
+ * the canonical model stays sparse.
+ *
+ * The helper does NOT inspect attributes or grandchildren. That
+ * refinement is reserved for the follow-up slice.
+ */
+export function capturePropertyGrabBag(
+  children: readonly GrabBagSourceChild[],
+  descriptor: PropertyGrabBagDescriptor,
+): UnknownPropertyChild[] | undefined {
+  const bag: UnknownPropertyChild[] = [];
+  for (const child of children) {
+    if (descriptor.modelledChildNames.has(child.localName)) continue;
+    bag.push({
+      elementName: extractQualifiedNameFromRawXml(child.rawXml) ?? child.localName,
+      rawXml: child.rawXml,
+    });
+  }
+  return bag.length > 0 ? bag : undefined;
+}
+
+/**
+ * Emit a grab-bag list back into a property container. Just concatenates
+ * each entry's `rawXml` in insertion order — the source bytes survive
+ * verbatim including attribute order, whitespace inside the element, and
+ * namespace prefixes.
+ */
+export function emitPropertyGrabBag(
+  entries: readonly UnknownPropertyChild[] | undefined,
+): string {
+  if (!entries || entries.length === 0) return "";
+  return entries.map((entry) => entry.rawXml).join("");
+}
+
+/**
+ * Best-effort extraction of the qualified element name from an opening
+ * tag — e.g. `<w15:collapsed w:val="1"/>` → `"w15:collapsed"`. Falls back
+ * to the caller-supplied `localName` when the raw XML doesn't look like
+ * a valid element.
+ */
+function extractQualifiedNameFromRawXml(rawXml: string): string | undefined {
+  const match = rawXml.match(/^<([^\s/>]+)/u);
+  return match?.[1];
+}

package/src/io/ooxml/xml-attr-helpers.ts

@@ -10,7 +10,7 @@
  * parse-styles.ts, parse-numbering.ts.
  */
 
-import type { XmlElementNode } from "./xml-element.ts";
+import type { XmlElementNode, XmlNode } from "./xml-element.ts";
 
 export function localName(name: string): string {
   const sep = name.indexOf(":");
@@ -26,6 +26,27 @@ export function findChildOptional(
   );
 }
 
+/**
+ * Depth-first search for the first descendant element with the given local name
+ * (namespace prefix ignored). Returns undefined if no descendant matches.
+ *
+ * Useful when the exact parent chain isn't known — e.g. descending into
+ * `<w:drawing>` to find a `<c:chart>` regardless of which DrawingML wrapper
+ * stands between them.
+ */
+export function findFirstDescendant(
+  node: XmlElementNode,
+  local: string,
+): XmlElementNode | undefined {
+  for (const child of node.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) === local) return child;
+    const nested = findFirstDescendant(child, local);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
 /** ST_OnOff: missing child → undefined; present bare or w:val="1|true|on" → true; w:val="0|false|off" → false. */
 export function readOnOff(node: XmlElementNode | undefined): boolean | undefined {
   if (!node) return undefined;
@@ -46,6 +67,43 @@ export function readIntVal(node: XmlElementNode | undefined): number | undefined
   return Number.isFinite(v) ? v : undefined;
 }
 
+/** Read the child's `val` attribute as a float. Returns undefined if missing or not a finite number. */
+export function readFloatVal(node: XmlElementNode | undefined): number | undefined {
+  if (!node) return undefined;
+  const raw = node.attributes["w:val"] ?? node.attributes.val;
+  if (raw === undefined) return undefined;
+  const v = Number.parseFloat(raw);
+  return Number.isFinite(v) ? v : undefined;
+}
+
+/**
+ * Return the concatenated text content of the first child element with the
+ * given local name. Returns undefined if the child is missing. Returns an
+ * empty string if the child exists but has no text.
+ */
+export function readStringChild(
+  node: XmlElementNode | undefined,
+  local: string,
+): string | undefined {
+  if (!node) return undefined;
+  const child = findChildOptional(node, local);
+  if (!child) return undefined;
+  return textContent(child);
+}
+
+/** Concatenate all descendant text nodes of an element into a single string. */
+export function textContent(node: XmlElementNode): string {
+  let out = "";
+  const walk = (children: XmlNode[]): void => {
+    for (const c of children) {
+      if (c.type === "text") out += c.text;
+      else walk(c.children);
+    }
+  };
+  walk(node.children);
+  return out;
+}
+
 /** Read an arbitrary attribute from a node as an int, with namespace fallback. */
 export function readIntAttr(node: XmlElementNode, attr: string): number | undefined {
   const raw = node.attributes[attr] ?? node.attributes[attr.replace(/^w:/, "")];

package/src/io/ooxml/xml-parser.ts

@@ -0,0 +1,142 @@
+/**
+ * Minimal XML parser shared across OOXML parsers.
+ *
+ * Handles the subset of XML that Office documents actually emit:
+ * elements, attributes, text, comments (stripped), processing instructions
+ * (stripped), and CDATA sections. Namespace prefixes are preserved verbatim
+ * on element and attribute names — strip with `localName()` from
+ * `xml-attr-helpers.ts` when lookups must be prefix-agnostic.
+ *
+ * Not a full XML conformance parser: does not validate element nesting,
+ * does not track source offsets on produced nodes, does not report errors on
+ * malformed input beyond best-effort early termination. Sufficient for every
+ * OOXML part we import.
+ *
+ * Originally inlined in `parse-theme.ts`; extracted here so the chart parsers
+ * and any future OOXML import path can share the same implementation.
+ */
+import type { XmlElementNode } from "./xml-element.ts";
+
+const ROOT_TAG = "__root__";
+
+/**
+ * Parse an XML string into a virtual root element. The root is a synthetic
+ * wrapper element whose `children` contain the top-level nodes from the
+ * source. Callers typically do `parseXml(xml).children.find(...)` or look up
+ * a specific top-level element via `findChildOptional`.
+ */
+export function parseXml(xml: string): XmlElementNode {
+  const root: XmlElementNode = {
+    type: "element",
+    name: ROOT_TAG,
+    attributes: {},
+    children: [],
+  };
+  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),
+      });
+      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.trim().length > 0 || (text.length > 0 && stack.length > 1)) {
+        stack[stack.length - 1]?.children.push({ type: "text", text });
+      }
+      cursor = end;
+      continue;
+    }
+
+    if (xml[cursor + 1] === "/") {
+      const end = xml.indexOf(">", cursor);
+      if (end < 0) break;
+      stack.pop();
+      cursor = end + 1;
+      continue;
+    }
+
+    const tagEnd = xml.indexOf(">", cursor);
+    if (tagEnd < 0) break;
+
+    const tagContent = xml.slice(cursor + 1, tagEnd);
+    const selfClosing = tagContent.endsWith("/");
+    const normalized = selfClosing
+      ? tagContent.slice(0, -1).trimEnd()
+      : tagContent;
+
+    const spaceIndex = normalized.search(/\s/);
+    const tagName =
+      spaceIndex >= 0 ? normalized.slice(0, spaceIndex) : normalized;
+    const attrString = spaceIndex >= 0 ? normalized.slice(spaceIndex + 1) : "";
+    const attributes = parseAttributes(attrString);
+
+    const element: XmlElementNode = {
+      type: "element",
+      name: tagName,
+      attributes,
+      children: [],
+    };
+
+    stack[stack.length - 1]?.children.push(element);
+
+    if (!selfClosing) {
+      stack.push(element);
+    }
+
+    cursor = tagEnd + 1;
+  }
+
+  return root;
+}
+
+/** Decode the standard XML entity references plus numeric character references. */
+export function decodeXmlEntities(text: string): string {
+  return text
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, dec) =>
+      String.fromCodePoint(Number.parseInt(dec, 10)),
+    )
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) =>
+      String.fromCodePoint(Number.parseInt(hex, 16)),
+    );
+}
+
+function parseAttributes(attrString: string): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  const pattern = /([A-Za-z_:][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
+  for (const match of attrString.matchAll(pattern)) {
+    const name = match[1];
+    const value = match[3] ?? match[4] ?? "";
+    if (name) {
+      attrs[name] = decodeXmlEntities(value);
+    }
+  }
+  return attrs;
+}