@beyondwork/docx-react-component 1.0.1 → 1.0.3

package/src/io/export/serialize-comments.ts

@@ -0,0 +1,876 @@
+import type { CommentEntry, CommentThread } from "../../review/store/comment-store.ts";
+import type { RevisionParagraphBoundary } from "../ooxml/revision-boundaries.ts";
+import type { ImportedCommentDefinition } from "../ooxml/parse-comments.ts";
+
+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;
+
+interface ParagraphBoundaryMap {
+  paragraphIndex: number;
+  start: number;
+  end: number;
+  boundaries: Map<number, number>;
+}
+
+interface SerializableCommentEntry {
+  thread: CommentThread;
+  entry: CommentEntry;
+  exportCommentId: string;
+  paraId: string;
+  durableId?: string;
+  isRoot: boolean;
+}
+
+export interface SerializedCommentsResult {
+  commentsXml: string;
+  serializedCommentIds: string[];
+  commentsExtendedXml?: string;
+  commentsIdsXml?: string;
+  peopleXml?: string;
+}
+
+export interface SerializeMergedCommentsXmlOptions {
+  preservedDefinitions?: readonly ImportedCommentDefinition[];
+  sourceRootTag?: string;
+  sourceExtendedRootTag?: string;
+  sourceIdsRootTag?: string;
+  sourcePeopleRootTag?: string;
+  peopleAuthors?: readonly string[];
+  exportCommentIds?: ReadonlyMap<string, string>;
+}
+
+export interface SerializeCommentAnchorsOptions {
+  exportCommentIds?: ReadonlyMap<string, string>;
+}
+
+export interface SerializedCommentDocumentResult {
+  documentXml: string;
+  serializedCommentIds: string[];
+  skippedCommentIds: string[];
+}
+
+const DEFAULT_COMMENTS_ROOT_TAG =
+  `<w:comments xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" mc:Ignorable="w14">`;
+const DEFAULT_COMMENTS_EXTENDED_ROOT_TAG =
+  `<w15:commentsEx xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml">`;
+const DEFAULT_COMMENTS_IDS_ROOT_TAG =
+  `<w16cid:commentsIds xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid">`;
+const DEFAULT_PEOPLE_ROOT_TAG =
+  `<w15:people xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml">`;
+
+export function serializeCommentsXml(
+  threads: readonly CommentThread[],
+  options: {
+    exportCommentIds?: ReadonlyMap<string, string>;
+  } = {},
+): SerializedCommentsResult {
+  return serializeMergedCommentsXml(threads, {
+    exportCommentIds: options.exportCommentIds,
+  });
+}
+
+export function serializeMergedCommentsXml(
+  threads: readonly CommentThread[],
+  options: SerializeMergedCommentsXmlOptions = {},
+): SerializedCommentsResult {
+  const serializableThreads = threads.filter((thread) => thread.entries.length > 0);
+  const preservedDefinitions = (options.preservedDefinitions ?? [])
+    .slice()
+    .sort((left, right) => left.order - right.order);
+  const runtimeThreadById = new Map(
+    serializableThreads.map((thread) => [thread.commentId, thread]),
+  );
+  const exportCommentIds =
+    options.exportCommentIds ??
+    createCommentExportIdMap(serializableThreads, preservedDefinitions);
+  const serializableEntries = createSerializableEntries(
+    serializableThreads,
+    preservedDefinitions,
+    exportCommentIds,
+  );
+  const serializedEntryByOoxmlId = new Map(
+    serializableEntries.map((entry) => [entry.exportCommentId, entry]),
+  );
+  const emittedThreadIds = new Set<string>();
+  const mergedComments: string[] = [];
+
+  for (const definition of preservedDefinitions) {
+    const ownedThread = runtimeThreadById.get(definition.commentId);
+    if (ownedThread) {
+      if (emittedThreadIds.has(ownedThread.commentId)) {
+        continue;
+      }
+      mergedComments.push(
+        ...serializeThreadEntries(
+          serializableEntries.filter((entry) => entry.thread.commentId === ownedThread.commentId),
+        ),
+      );
+      emittedThreadIds.add(ownedThread.commentId);
+      continue;
+    }
+
+    if (serializedEntryByOoxmlId.has(definition.commentId)) {
+      continue;
+    }
+
+    mergedComments.push(definition.rawXml);
+  }
+
+  for (const thread of serializableThreads) {
+    if (emittedThreadIds.has(thread.commentId)) {
+      continue;
+    }
+
+    mergedComments.push(
+      ...serializeThreadEntries(
+        serializableEntries.filter((entry) => entry.thread.commentId === thread.commentId),
+      ),
+    );
+    emittedThreadIds.add(thread.commentId);
+  }
+
+  const mergedExtendedEntries = [
+    ...serializePreservedCommentExtensions(
+      preservedDefinitions.filter((definition) => !serializedEntryByOoxmlId.has(definition.commentId)),
+    ),
+    ...serializableEntries
+      .map((entry) => serializeCommentExtension(entry))
+      .filter((xml): xml is string => Boolean(xml)),
+  ];
+  const mergedDurableIds = [
+    ...serializePreservedCommentIds(
+      preservedDefinitions.filter((definition) => !serializedEntryByOoxmlId.has(definition.commentId)),
+    ),
+    ...serializableEntries
+      .map((entry) => serializeCommentDurableId(entry))
+      .filter((xml): xml is string => Boolean(xml)),
+  ];
+  const peopleAuthors = new Set([
+    ...(options.peopleAuthors ?? []),
+    ...preservedDefinitions
+      .map((definition) => definition.authorId)
+      .filter((authorId): authorId is string => typeof authorId === "string" && authorId.length > 0),
+    ...serializableEntries
+      .map((entry) => entry.entry.authorId)
+      .filter((authorId): authorId is string => typeof authorId === "string" && authorId.length > 0),
+  ]);
+
+  return {
+    commentsXml: [
+      `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
+      normalizeCommentsRootTag(options.sourceRootTag ?? DEFAULT_COMMENTS_ROOT_TAG),
+      ...mergedComments,
+      `</w:comments>`,
+    ].join("\n"),
+    serializedCommentIds: serializableThreads.map((thread) => thread.commentId),
+    commentsExtendedXml:
+      mergedExtendedEntries.length > 0
+        ? [
+            `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
+            options.sourceExtendedRootTag ?? DEFAULT_COMMENTS_EXTENDED_ROOT_TAG,
+            ...mergedExtendedEntries,
+            `</w15:commentsEx>`,
+          ].join("\n")
+        : undefined,
+    commentsIdsXml:
+      mergedDurableIds.length > 0
+        ? [
+            `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
+            options.sourceIdsRootTag ?? DEFAULT_COMMENTS_IDS_ROOT_TAG,
+            ...mergedDurableIds,
+            `</w16cid:commentsIds>`,
+          ].join("\n")
+        : undefined,
+    peopleXml:
+      peopleAuthors.size > 0
+        ? [
+            `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
+            options.sourcePeopleRootTag ?? DEFAULT_PEOPLE_ROOT_TAG,
+            ...[...peopleAuthors]
+              .sort((left, right) => left.localeCompare(right))
+              .map(
+                (authorId) =>
+                  `<w15:person w15:author="${escapeAttribute(authorId)}" />`,
+              ),
+            `</w15:people>`,
+          ].join("\n")
+        : undefined,
+  };
+}
+
+function normalizeCommentsRootTag(rootTag: string): string {
+  let normalized = rootTag;
+  if (!/\bxmlns:w14=/u.test(normalized)) {
+    normalized = normalized.replace(
+      />$/u,
+      ` xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml">`,
+    );
+  }
+  if (!/\bxmlns:mc=/u.test(normalized)) {
+    normalized = normalized.replace(
+      />$/u,
+      ` xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006">`,
+    );
+  }
+  if (!/\bmc:Ignorable=/u.test(normalized)) {
+    normalized = normalized.replace(/>$/u, ` mc:Ignorable="w14">`);
+  } else if (!/\bmc:Ignorable="[^"]*\bw14\b/u.test(normalized)) {
+    normalized = normalized.replace(
+      /\bmc:Ignorable="([^"]*)"/u,
+      (_match, value: string) =>
+        `mc:Ignorable="${`${value} w14`.trim().replace(/\s+/gu, " ")}"`,
+    );
+  }
+  return normalized;
+}
+
+export function serializeCommentAnchorsIntoDocumentXml(
+  documentXml: string,
+  threads: readonly CommentThread[],
+  paragraphs: readonly Pick<
+    RevisionParagraphBoundary,
+    "paragraphIndex" | "start" | "end" | "boundaries"
+  >[] = mapParagraphBoundaries(documentXml),
+  options: SerializeCommentAnchorsOptions = {},
+): SerializedCommentDocumentResult {
+  const insertions = new Map<number, string[]>();
+  const serializedCommentIds: string[] = [];
+  const skippedCommentIds: string[] = [];
+  const exportCommentIds =
+    options.exportCommentIds ?? createCommentExportIdMap(threads);
+
+  for (const thread of threads) {
+    if (thread.anchor.kind !== "range") {
+      skippedCommentIds.push(thread.commentId);
+      continue;
+    }
+
+    const paragraph = paragraphs.find(
+      (candidate) =>
+        thread.anchor.range.from >= candidate.start &&
+        thread.anchor.range.to <= candidate.end,
+    );
+
+    if (!paragraph) {
+      skippedCommentIds.push(thread.commentId);
+      continue;
+    }
+
+    const startIndex = paragraph.boundaries.get(thread.anchor.range.from);
+    const endIndex = paragraph.boundaries.get(thread.anchor.range.to);
+
+    if (startIndex === undefined || endIndex === undefined) {
+      skippedCommentIds.push(thread.commentId);
+      continue;
+    }
+
+    const exportCommentId = exportCommentIds.get(thread.commentId) ?? thread.commentId;
+    pushInsertion(
+      insertions,
+      startIndex,
+      `<w:commentRangeStart w:id="${escapeAttribute(exportCommentId)}"/>`,
+    );
+    pushInsertion(
+      insertions,
+      endIndex,
+      `<w:commentRangeEnd w:id="${escapeAttribute(exportCommentId)}"/>`,
+    );
+    pushInsertion(
+      insertions,
+      endIndex,
+      `<w:r><w:commentReference w:id="${escapeAttribute(exportCommentId)}"/></w:r>`,
+    );
+    serializedCommentIds.push(thread.commentId);
+  }
+
+  const sortedInsertions = [...insertions.entries()].sort((left, right) => left[0] - right[0]);
+  let cursor = 0;
+  let output = "";
+
+  for (const [index, snippets] of sortedInsertions) {
+    output += documentXml.slice(cursor, index);
+    output += snippets.join("");
+    cursor = index;
+  }
+
+  output += documentXml.slice(cursor);
+
+  return {
+    documentXml: output,
+    serializedCommentIds,
+    skippedCommentIds,
+  };
+}
+
+export function createCommentExportIdMap(
+  threads: readonly CommentThread[],
+  preservedDefinitions: readonly ImportedCommentDefinition[] = [],
+): ReadonlyMap<string, string> {
+  const exportIds = new Map<string, string>();
+  const reservedNumericIds = new Set<number>();
+
+  for (const definition of preservedDefinitions) {
+    const numericId = parseOoxmlNumericId(definition.commentId);
+    if (numericId !== undefined) {
+      reservedNumericIds.add(numericId);
+    }
+  }
+
+  for (const thread of threads) {
+    const rootEntry = getRootEntry(thread);
+    const preferredValue =
+      thread.metadata?.rootOoxmlCommentId ??
+      rootEntry?.metadata?.ooxmlCommentId ??
+      thread.commentId;
+    const numericId = parseOoxmlNumericId(preferredValue);
+    if (numericId !== undefined && !reservedNumericIds.has(numericId)) {
+      exportIds.set(thread.commentId, String(numericId));
+      reservedNumericIds.add(numericId);
+    }
+  }
+
+  let nextGeneratedId =
+    reservedNumericIds.size > 0 ? Math.max(...reservedNumericIds) + 1 : 1;
+
+  for (const thread of threads) {
+    if (exportIds.has(thread.commentId)) {
+      continue;
+    }
+
+    while (reservedNumericIds.has(nextGeneratedId)) {
+      nextGeneratedId += 1;
+    }
+
+    exportIds.set(thread.commentId, String(nextGeneratedId));
+    reservedNumericIds.add(nextGeneratedId);
+    nextGeneratedId += 1;
+  }
+
+  return exportIds;
+}
+
+function createSerializableEntries(
+  threads: readonly CommentThread[],
+  preservedDefinitions: readonly ImportedCommentDefinition[],
+  exportCommentIds: ReadonlyMap<string, string>,
+): SerializableCommentEntry[] {
+  const entries: SerializableCommentEntry[] = [];
+  const reservedNumericIds = new Set<number>();
+
+  for (const definition of preservedDefinitions) {
+    const numericId = parseOoxmlNumericId(definition.commentId);
+    if (numericId !== undefined) {
+      reservedNumericIds.add(numericId);
+    }
+  }
+
+  for (const thread of threads) {
+    const rootEntry = getRootEntry(thread);
+    if (!rootEntry) {
+      continue;
+    }
+
+    const rootExportCommentId = exportCommentIds.get(thread.commentId) ?? thread.commentId;
+    const rootNumericId = parseOoxmlNumericId(rootExportCommentId);
+    if (rootNumericId !== undefined) {
+      reservedNumericIds.add(rootNumericId);
+    }
+
+    const rootParaId =
+      rootEntry.metadata?.paraId ??
+      thread.metadata?.rootParaId ??
+      generateParaId(thread.commentId, 0);
+    const rootDurableId =
+      rootEntry.metadata?.durableId ??
+      createDurableId(rootEntry, rootExportCommentId, 0);
+
+    entries.push({
+      thread,
+      entry: rootEntry,
+      exportCommentId: rootExportCommentId,
+      paraId: rootParaId,
+      durableId: rootDurableId,
+      isRoot: true,
+    });
+
+    for (let index = 1; index < thread.entries.length; index += 1) {
+      const entry = thread.entries[index];
+      if (!entry) {
+        continue;
+      }
+
+      const preferredCommentId = entry.metadata?.ooxmlCommentId;
+      let exportCommentId: string | undefined;
+      const preferredNumericId = preferredCommentId
+        ? parseOoxmlNumericId(preferredCommentId)
+        : undefined;
+      if (
+        preferredNumericId !== undefined &&
+        !reservedNumericIds.has(preferredNumericId)
+      ) {
+        exportCommentId = String(preferredNumericId);
+        reservedNumericIds.add(preferredNumericId);
+      } else {
+        let nextGeneratedId =
+          reservedNumericIds.size > 0 ? Math.max(...reservedNumericIds) + 1 : 1;
+        while (reservedNumericIds.has(nextGeneratedId)) {
+          nextGeneratedId += 1;
+        }
+        exportCommentId = String(nextGeneratedId);
+        reservedNumericIds.add(nextGeneratedId);
+      }
+
+      entries.push({
+        thread,
+        entry,
+        exportCommentId,
+        paraId: entry.metadata?.paraId ?? generateParaId(thread.commentId, index),
+        durableId:
+          entry.metadata?.durableId ??
+          createDurableId(entry, exportCommentId, index),
+        isRoot: false,
+      });
+    }
+  }
+
+  return entries;
+}
+
+function serializeThreadEntries(entries: readonly SerializableCommentEntry[]): string[] {
+  return entries.map((entry) => serializeCommentEntry(entry));
+}
+
+function serializeCommentEntry(entry: SerializableCommentEntry): string {
+  const author = escapeAttribute(entry.entry.authorId);
+  const createdAt = escapeAttribute(entry.entry.createdAt);
+  const initials = entry.entry.metadata?.initials;
+  const paragraphXml = serializeCommentParagraphs(entry.entry.body, entry.paraId);
+
+  return `<w:comment w:id="${escapeAttribute(entry.exportCommentId)}"${initials ? ` w:initials="${escapeAttribute(initials)}"` : ""} w:author="${author}" w:date="${createdAt}">${paragraphXml}</w:comment>`;
+}
+
+function serializeCommentParagraphs(body: string, paraId: string): string {
+  const paragraphs = body.length > 0 ? body.split("\n") : [""];
+  const textId = deriveTextIdFromParaId(paraId);
+  return paragraphs
+    .map((paragraph, index) => {
+      const attributes =
+        index === 0
+          ? ` w14:paraId="${escapeAttribute(paraId)}" w14:textId="${escapeAttribute(textId)}"`
+          : "";
+      return `<w:p${attributes}><w:r>${serializeText(paragraph)}</w:r></w:p>`;
+    })
+    .join("");
+}
+
+function serializePreservedCommentExtensions(
+  definitions: readonly ImportedCommentDefinition[],
+): string[] {
+  return definitions
+    .map((definition) =>
+      definition.paraId
+        ? serializePreservedCommentExtension(definition)
+        : undefined,
+    )
+    .filter((xml): xml is string => Boolean(xml));
+}
+
+function serializePreservedCommentExtension(
+  definition: ImportedCommentDefinition,
+): string {
+  const doneValue = definition.isDone ? "true" : "false";
+  return `<w15:commentEx w15:paraId="${escapeAttribute(definition.paraId!)}"${definition.parentParaId ? ` w15:paraIdParent="${escapeAttribute(definition.parentParaId)}"` : ""} w15:done="${doneValue}" />`;
+}
+
+function serializeCommentExtension(
+  entry: SerializableCommentEntry,
+): string | undefined {
+  return `<w15:commentEx w15:paraId="${escapeAttribute(entry.paraId)}"${entry.isRoot ? "" : ` w15:paraIdParent="${escapeAttribute(findRootParaId(entry.thread, entry.paraId))}"`} w15:done="${entry.isRoot && entry.thread.status === "resolved" ? "true" : "false"}" />`;
+}
+
+function serializePreservedCommentIds(
+  definitions: readonly ImportedCommentDefinition[],
+): string[] {
+  return definitions
+    .map((definition) =>
+      definition.paraId && definition.durableId
+        ? `<w16cid:commentId w16cid:paraId="${escapeAttribute(definition.paraId)}" w16cid:durableId="${escapeAttribute(definition.durableId)}" />`
+        : undefined,
+    )
+    .filter((xml): xml is string => Boolean(xml));
+}
+
+function serializeCommentDurableId(
+  entry: SerializableCommentEntry,
+): string | undefined {
+  if (!entry.durableId) {
+    return undefined;
+  }
+
+  return `<w16cid:commentId w16cid:paraId="${escapeAttribute(entry.paraId)}" w16cid:durableId="${escapeAttribute(entry.durableId)}" />`;
+}
+
+function getRootEntry(thread: CommentThread): CommentEntry | undefined {
+  return thread.entries[0];
+}
+
+function findRootParaId(thread: CommentThread, fallback: string): string {
+  return (
+    thread.entries[0]?.metadata?.paraId ??
+    thread.metadata?.rootParaId ??
+    fallback
+  );
+}
+
+function generateParaId(seed: string, index: number): string {
+  const normalized = `${seed}:${index}`;
+  let hash = 0;
+
+  for (let cursor = 0; cursor < normalized.length; cursor += 1) {
+    hash = (hash * 31 + normalized.charCodeAt(cursor)) >>> 0;
+  }
+
+  return hash.toString(16).toUpperCase().padStart(8, "0").slice(-8);
+}
+
+function createDurableId(
+  entry: CommentEntry,
+  exportCommentId: string,
+  index: number,
+): string {
+  const seed = `${entry.entryId}:${exportCommentId}:${index}`;
+  let hash = 0n;
+
+  for (let cursor = 0; cursor < seed.length; cursor += 1) {
+    hash = (hash * 131n + BigInt(seed.charCodeAt(cursor))) & 0xffffffffffffffffn;
+  }
+
+  return hash.toString(16).toUpperCase().padStart(16, "0").slice(-16);
+}
+
+function deriveTextIdFromParaId(paraId: string): string {
+  return paraId.slice(-8).padStart(8, "0");
+}
+
+function parseOoxmlNumericId(value: string): number | undefined {
+  if (!/^-?\d+$/u.test(value)) {
+    return undefined;
+  }
+
+  const numericId = Number.parseInt(value, 10);
+  return Number.isFinite(numericId) ? numericId : undefined;
+}
+
+function mapParagraphBoundaries(documentXml: string): ParagraphBoundaryMap[] {
+  const root = parseXml(documentXml);
+  const documentElement = findChildElement(root, "document");
+  const bodyElement = findChildElement(documentElement, "body");
+  const paragraphs: ParagraphBoundaryMap[] = [];
+  let globalCursor = 0;
+  let paragraphIndex = -1;
+  let previousWasParagraph = false;
+
+  for (const child of bodyElement.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    if (localName(child.name) !== "p") {
+      globalCursor += 1;
+      previousWasParagraph = false;
+      continue;
+    }
+
+    if (previousWasParagraph) {
+      globalCursor += 1;
+    }
+    paragraphIndex += 1;
+    const boundaries = new Map<number, number>();
+    boundaries.set(globalCursor, child.start + openingTagLength(documentXml, child.start));
+
+    walkParagraphForBoundaries(
+      child,
+      documentXml,
+      boundaries,
+      () => globalCursor,
+      (next) => {
+        globalCursor = next;
+      },
+    );
+
+    if (!boundaries.has(globalCursor)) {
+      boundaries.set(globalCursor, child.end - 4);
+    }
+    paragraphs.push({
+      paragraphIndex,
+      start: Math.min(...boundaries.keys()),
+      end: Math.max(...boundaries.keys()),
+      boundaries,
+    });
+    previousWasParagraph = true;
+  }
+
+  return paragraphs;
+}
+
+function walkParagraphForBoundaries(
+  paragraph: XmlElementNode,
+  sourceXml: string,
+  boundaries: Map<number, number>,
+  getCursor: () => number,
+  setCursor: (next: number) => void,
+): void {
+  for (const child of paragraph.children) {
+    walkInlineNodeForBoundaries(child, sourceXml, boundaries, getCursor, setCursor);
+  }
+}
+
+function walkInlineNodeForBoundaries(
+  node: XmlNode,
+  sourceXml: string,
+  boundaries: Map<number, number>,
+  getCursor: () => number,
+  setCursor: (next: number) => void,
+): void {
+  if (node.type !== "element") {
+    return;
+  }
+
+  switch (localName(node.name)) {
+    case "r": {
+      if (!boundaries.has(getCursor())) {
+        boundaries.set(getCursor(), node.start);
+      }
+
+      for (const child of node.children) {
+        walkInlineNodeForBoundaries(child, sourceXml, boundaries, getCursor, setCursor);
+      }
+
+      boundaries.set(getCursor(), node.end);
+      return;
+    }
+    case "t": {
+      const text = node.children
+        .filter((child): child is XmlTextNode => child.type === "text")
+        .map((child) => child.text)
+        .join("");
+      setCursor(getCursor() + Array.from(text).length);
+      return;
+    }
+    case "tab":
+    case "br": {
+      const startCursor = getCursor();
+      boundaries.set(startCursor, node.start);
+      const nextCursor = startCursor + 1;
+      boundaries.set(nextCursor, node.end);
+      setCursor(nextCursor);
+      return;
+    }
+    default:
+      for (const child of node.children) {
+        walkInlineNodeForBoundaries(child, sourceXml, boundaries, getCursor, setCursor);
+      }
+  }
+}
+
+function pushInsertion(
+  insertions: Map<number, string[]>,
+  index: number,
+  xml: string,
+): void {
+  const bucket = insertions.get(index);
+  if (bucket) {
+    bucket.push(xml);
+    return;
+  }
+
+  insertions.set(index, [xml]);
+}
+
+function serializeText(text: string): string {
+  const preserve = requiresPreservedSpace(text) ? ` xml:space="preserve"` : "";
+  return `<w:t${preserve}>${escapeXml(text)}</w:t>`;
+}
+
+function requiresPreservedSpace(text: string): boolean {
+  return /^\s/u.test(text) || /\s$/u.test(text) || /\s{2,}/u.test(text);
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function escapeAttribute(value: string): string {
+  return escapeXml(value).replace(/"/g, "&quot;");
+}
+
+function openingTagLength(xml: string, start: number): number {
+  const end = xml.indexOf(">", start);
+  if (end < 0) {
+    throw new Error("Malformed XML: missing tag close.");
+  }
+
+  return end - start + 1;
+}
+
+function parseXml(xml: string): XmlElementNode {
+  const root: XmlElementNode = {
+    type: "element",
+    name: "#document",
+    attributes: {},
+    children: [],
+    start: 0,
+    end: xml.length,
+  };
+  const stack: XmlElementNode[] = [root];
+  const tokenPattern =
+    /<!--[\s\S]*?-->|<\?[\s\S]*?\?>|<!DOCTYPE[\s\S]*?>|<!\[CDATA\[[\s\S]*?\]\]>|<[^>]+>|[^<]+/gu;
+
+  for (const match of xml.matchAll(tokenPattern)) {
+    const token = match[0] ?? "";
+    const start = match.index ?? 0;
+    const end = start + token.length;
+
+    if (token.startsWith("<?") || token.startsWith("<!DOCTYPE") || token.startsWith("<!--")) {
+      continue;
+    }
+
+    if (token.startsWith("<![CDATA[")) {
+      const text = token.slice(9, -3);
+      stack[stack.length - 1]?.children.push({
+        type: "text",
+        text,
+        start,
+        end,
+      });
+      continue;
+    }
+
+    if (token.startsWith("</")) {
+      const node = stack.pop();
+      if (!node) {
+        throw new Error("Malformed XML: unexpected closing tag.");
+      }
+      node.end = end;
+      continue;
+    }
+
+    if (token.startsWith("<")) {
+      const selfClosing = /\/>$/.test(token);
+      const tagBody = token.slice(1, token.length - (selfClosing ? 2 : 1)).trim();
+      const { name, attributes } = parseTag(tagBody);
+      const node: XmlElementNode = {
+        type: "element",
+        name,
+        attributes,
+        children: [],
+        start,
+        end,
+      };
+      stack[stack.length - 1]?.children.push(node);
+      if (!selfClosing) {
+        stack.push(node);
+      }
+      continue;
+    }
+
+    const text = decodeXmlText(token);
+    if (text.length > 0) {
+      stack[stack.length - 1]?.children.push({
+        type: "text",
+        text,
+        start,
+        end,
+      });
+    }
+  }
+
+  if (stack.length !== 1) {
+    throw new Error("Malformed XML: unclosed tag.");
+  }
+
+  return root;
+}
+
+function parseTag(tagBody: string): { name: string; attributes: Record<string, string> } {
+  const whitespaceIndex = tagBody.search(/\s/u);
+  const name = whitespaceIndex === -1 ? tagBody : tagBody.slice(0, whitespaceIndex);
+  const rawAttributes = whitespaceIndex === -1 ? "" : tagBody.slice(whitespaceIndex + 1);
+  const attributes: Record<string, string> = {};
+  const pattern = /([A-Za-z_][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
+
+  for (const match of rawAttributes.matchAll(pattern)) {
+    const key = match[1];
+    const value = match[3] ?? match[4] ?? "";
+    if (key) {
+      attributes[key] = decodeXmlText(value);
+    }
+  }
+
+  return { name, attributes };
+}
+
+function findChildElement(node: XmlElementNode, name: string): XmlElementNode {
+  const match = node.children.find(
+    (child): child is XmlElementNode =>
+      child.type === "element" && localName(child.name) === name,
+  );
+
+  if (!match) {
+    throw new Error(`Expected XML element ${name}.`);
+  }
+
+  return match;
+}
+
+function localName(name: string): string {
+  const index = name.indexOf(":");
+  return index === -1 ? name : name.slice(index + 1);
+}
+
+function decodeXmlText(text: string): string {
+  return text.replace(
+    /&(?:#x([0-9A-Fa-f]+)|#([0-9]+)|([A-Za-z]+));/gu,
+    (_, hex, dec, named) => {
+      if (hex) {
+        return String.fromCodePoint(Number.parseInt(hex, 16));
+      }
+      if (dec) {
+        return String.fromCodePoint(Number.parseInt(dec, 10));
+      }
+
+      switch (named) {
+        case "amp":
+          return "&";
+        case "lt":
+          return "<";
+        case "gt":
+          return ">";
+        case "quot":
+          return "\"";
+        case "apos":
+          return "'";
+        default:
+          return `&${named};`;
+      }
+    },
+  );
+}