@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/session/export/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Barrel for the Layer-01 export helpers.
+ *
+ * Slice 4 ships these as pure, P6-clean pieces of the export pipeline.
+ * Slice 5 will wire them together into a single export entry point on
+ * `DocxSession.export()`; until then the legacy
+ * `exportDocxEditorSession` in `src/io/docx-session.ts` continues to
+ * orchestrate while consuming these helpers one-by-one.
+ */
+
+export {
+  ExportBlockedError,
+  formatBlockedExportMessage,
+  type ExportBlockedCode,
+  type ExportBlockedDetails,
+} from "./export-diagnostics.ts";
+
+export {
+  assertExportNotBlockedByCompatibility,
+  assertNoBlockingPreservedComments,
+  assertNoBlockingSkippedComments,
+  assertNoSkippedRevisions,
+} from "./export-validation.ts";
+
+export {
+  groupFooterRevisionsByPartPath,
+  groupHeaderRevisionsByPartPath,
+  groupNoteRevisionsByNoteId,
+} from "./serialize-dispatch.ts";
+
+export {
+  reattachPreservedParts,
+  reattachPreservedPackageParts,
+} from "./preservation-reattach.ts";

package/src/session/export/preservation-reattach.ts

@@ -0,0 +1,30 @@
+/**
+ * Session-layer facade for preserved-part reattachment.
+ *
+ * Slice 4c of refactor/01 package-session. The actual reattach body
+ * lives under `src/io/export/reattach-preserved-parts.ts` (already in
+ * the `src/io/export/**` home that stays put per the target
+ * architecture). This module exposes it under the session-layer
+ * naming convention so consumers importing from
+ * `src/session/export/**` see one coherent entry surface.
+ *
+ * P6 clean — transits only `src/io/**`, which is allowed.
+ *
+ * What "reattach" means (architecture §P2 — preserve-first):
+ *   Every package part that was present on input but not owned by
+ *   the runtime export pipeline is copied back verbatim into the
+ *   output package, along with its relationships. This is the
+ *   round-trip byte-identity guarantee for parts the runtime does
+ *   not understand (opaque-fragment store-backed parts, unknown
+ *   OOXML, vendor extensions).
+ */
+
+export {
+  reattachPreservedParts,
+  /**
+   * Expose the reattach entry point under a more session-shaped name
+   * for import sites that prefer it. The legacy name stays live for
+   * existing in-tree callers.
+   */
+  reattachPreservedParts as reattachPreservedPackageParts,
+} from "../../io/export/reattach-preserved-parts.ts";

package/src/session/export/serialize-dispatch.ts

@@ -0,0 +1,165 @@
+/**
+ * Export-side serializer dispatch helpers.
+ *
+ * Slice 4b of refactor/01 package-session. Extracted from the inline
+ * sub-part serialization loops inside `exportDocxEditorSession`
+ * (`src/io/docx-session.ts:2360–2482`).
+ *
+ * Each helper takes pre-filtered inputs (the actionable revision list
+ * from the review layer, the canonical sub-part record) and returns a
+ * deterministic grouping by part path or note id. This lets the legacy
+ * file call these instead of the inline loops + keeps the session
+ * layer free of review-store reads (P6 clean).
+ *
+ * The helpers are explicitly generic over the revision record shape
+ * so they can be consumed by the legacy file without importing review
+ * types into `src/session/**`. Callers pass a `getStoryTarget`
+ * accessor that projects the revision's story target.
+ */
+
+import type { EditorStoryTarget } from "../../api/public-types.ts";
+import type { SubPartsCatalog } from "../../model/canonical-document.ts";
+
+type HeaderPart = SubPartsCatalog["headers"][number];
+type FooterPart = SubPartsCatalog["footers"][number];
+
+/**
+ * Structural identity for `EditorStoryTarget` — matches the shape that
+ * `src/core/selection/mapping.ts` exports, inlined here to keep the
+ * session layer P6 clean. Behavior is identical: `main` matches `main`
+ * regardless of other fields; `header` / `footer` match on
+ * `relationshipId` + `variant` + (`sectionIndex` when both sides
+ * define it); notes match on `noteId`; everything else is !=.
+ */
+function storyTargetEquals(
+  left: EditorStoryTarget | undefined,
+  right: EditorStoryTarget | undefined,
+): boolean {
+  if (left === right) return true;
+  if (!left || !right) return left === right;
+  if (left.kind !== right.kind) return false;
+  if (left.kind === "main") return true;
+  if (left.kind === "header" && right.kind === "header") {
+    return (
+      left.relationshipId === right.relationshipId &&
+      left.variant === right.variant &&
+      (left.sectionIndex === undefined || right.sectionIndex === undefined
+        ? true
+        : left.sectionIndex === right.sectionIndex)
+    );
+  }
+  if (left.kind === "footer" && right.kind === "footer") {
+    return (
+      left.relationshipId === right.relationshipId &&
+      left.variant === right.variant &&
+      (left.sectionIndex === undefined || right.sectionIndex === undefined
+        ? true
+        : left.sectionIndex === right.sectionIndex)
+    );
+  }
+  if (left.kind === "footnote" && right.kind === "footnote") {
+    return left.noteId === right.noteId;
+  }
+  if (left.kind === "endnote" && right.kind === "endnote") {
+    return left.noteId === right.noteId;
+  }
+  return false;
+}
+
+/**
+ * Group the actionable revisions by header part path.
+ *
+ * Each entry stores the canonical header record AND the revisions
+ * that target it. When multiple header records share a part path
+ * (unusual but possible), the entry is seeded with the first record
+ * seen; if a later record carries matching revisions, the entry's
+ * `header` reference is overwritten so the serializer uses the record
+ * that owns those revisions.
+ */
+export function groupHeaderRevisionsByPartPath<R>(
+  headers: readonly HeaderPart[],
+  actionableRevisions: readonly R[],
+  getStoryTarget: (revision: R) => EditorStoryTarget | undefined,
+): Map<string, { header: HeaderPart; revisions: R[] }> {
+  const result = new Map<string, { header: HeaderPart; revisions: R[] }>();
+  for (const header of headers) {
+    const entry = result.get(header.partPath) ?? { header, revisions: [] };
+    const matching = actionableRevisions.filter((revision) =>
+      storyTargetEquals(
+        getStoryTarget(revision) ?? { kind: "main" },
+        {
+          kind: "header",
+          relationshipId: header.relationshipId,
+          variant: header.variant,
+          ...(header.sectionIndex !== undefined
+            ? { sectionIndex: header.sectionIndex }
+            : {}),
+        },
+      ),
+    );
+    entry.revisions.push(...matching);
+    if (matching.length > 0) {
+      entry.header = header;
+    }
+    result.set(header.partPath, entry);
+  }
+  return result;
+}
+
+/**
+ * Symmetric with `groupHeaderRevisionsByPartPath`.
+ */
+export function groupFooterRevisionsByPartPath<R>(
+  footers: readonly FooterPart[],
+  actionableRevisions: readonly R[],
+  getStoryTarget: (revision: R) => EditorStoryTarget | undefined,
+): Map<string, { footer: FooterPart; revisions: R[] }> {
+  const result = new Map<string, { footer: FooterPart; revisions: R[] }>();
+  for (const footer of footers) {
+    const entry = result.get(footer.partPath) ?? { footer, revisions: [] };
+    const matching = actionableRevisions.filter((revision) =>
+      storyTargetEquals(
+        getStoryTarget(revision) ?? { kind: "main" },
+        {
+          kind: "footer",
+          relationshipId: footer.relationshipId,
+          variant: footer.variant,
+          ...(footer.sectionIndex !== undefined
+            ? { sectionIndex: footer.sectionIndex }
+            : {}),
+        },
+      ),
+    );
+    entry.revisions.push(...matching);
+    if (matching.length > 0) {
+      entry.footer = footer;
+    }
+    result.set(footer.partPath, entry);
+  }
+  return result;
+}
+
+/**
+ * Group actionable revisions by `storyTarget.noteId` for the given
+ * note kind (`footnote` or `endnote`). The return value is a
+ * `Record<noteId, R[]>` suitable for passing directly into
+ * `serializeFootnotesXml` / `serializeEndnotesXml`.
+ *
+ * Revisions whose story target is not a note of the given kind are
+ * excluded.
+ */
+export function groupNoteRevisionsByNoteId<R>(
+  actionableRevisions: readonly R[],
+  kind: "footnote" | "endnote",
+  getStoryTarget: (revision: R) => EditorStoryTarget | undefined,
+): Record<string, R[]> {
+  const result: Record<string, R[]> = {};
+  for (const revision of actionableRevisions) {
+    const target = getStoryTarget(revision);
+    if (!target || target.kind !== kind) continue;
+    const noteId = target.noteId;
+    if (!(noteId in result)) result[noteId] = [];
+    result[noteId]!.push(revision);
+  }
+  return result;
+}

package/src/session/export/stateful-export-pipeline.ts

@@ -0,0 +1,432 @@
+/**
+ * Stateful-export-pipeline helpers extracted from `src/io/docx-session.ts`
+ * (slice 5e-6f.1). These functions run on the export side only — they
+ * decide whether source bytes can be reused, ensure host-owned metadata
+ * parts (core/app properties + workflow payload) are present, build the
+ * core-properties XML, and weave `w:permStart` / `w:permEnd` protection
+ * anchors into the serialized document XML.
+ *
+ * Export-only by contract: every caller lives inside
+ * `exportDocxEditorSession`. Protection-extraction helpers
+ * (`extractDocumentProtection` / `buildProtectionSnapshot` / …) are
+ * load-path-shared and stay in docx-session.ts until slice 5e-7 rewires
+ * `DocxSession.open` directly.
+ *
+ * P6-clean: imports reach into src/io/ooxml, src/io/export,
+ * src/api/public-types, and src/model/canonical-document. Nothing from
+ * src/runtime, src/review, src/core, or src/ui-tailwind.
+ */
+
+import type { EditorSessionState, ProtectionSnapshot } from "../../api/public-types.ts";
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
+import { buildAppPropertiesXml } from "../../io/export/build-app-properties-xml.ts";
+import { ExportSession } from "../../io/export/export-session.ts";
+import { mapParagraphBoundaries } from "../../io/export/serialize-comments.ts";
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import {
+  CONTENT_TYPES_PATH,
+  PACKAGE_RELATIONSHIPS_PATH,
+  getRelationshipsPartPath,
+  resolveRelationshipTarget,
+} from "../../io/ooxml/part-manifest.ts";
+import {
+  buildWorkflowPayloadParts,
+  WORKFLOW_PAYLOAD_CONTENT_TYPE,
+  WORKFLOW_PAYLOAD_CUSTOM_PROPS_CONTENT_TYPE,
+  WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
+  WORKFLOW_PAYLOAD_CUSTOM_PROPS_RELATIONSHIP_TYPE,
+  WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE,
+  type EditorStatePayload,
+} from "../../io/ooxml/workflow-payload.ts";
+
+type CanonicalDocumentEnvelope = CanonicalDocument;
+
+/**
+ * Minimal shape of the session-import state object that the export pipeline
+ * consumes. The full ImportedDocxState interface lives in docx-session.ts;
+ * these are the subset of fields this module actually reads.
+ */
+export interface ExportPipelineState {
+  sourcePackage: OpcPackage;
+  sourceDocumentPartPath: string;
+  sourceCommentsPartPath?: string;
+  sourceCommentsExtendedPartPath?: string;
+  sourceCommentsIdsPartPath?: string;
+  sourcePeoplePartPath?: string;
+}
+
+// Core + app properties OPC addresses. Moved here from docx-session.ts
+// alongside the helpers that consume them; the legacy file re-imports.
+export const APP_PROPERTIES_PART_PATH = "/docProps/app.xml";
+export const CORE_PROPERTIES_PART_PATH = "/docProps/core.xml";
+export const APP_PROPERTIES_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.extended-properties+xml";
+export const CORE_PROPERTIES_CONTENT_TYPE =
+  "application/vnd.openxmlformats-package.core-properties+xml";
+export const APP_PROPERTIES_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties";
+export const CORE_PROPERTIES_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties";
+
+/**
+ * Read a Node-style environment variable without referencing the Node-only
+ * `process` global in the production build (which excludes @types/node).
+ * Returns `undefined` in browser environments or when the var is unset.
+ */
+export function readNodeEnvVar(name: string): string | undefined {
+  const proc = (globalThis as unknown as {
+    process?: { env?: Record<string, string | undefined> };
+  }).process;
+  return proc?.env?.[name];
+}
+
+export function canReuseSourceBytesForCurrentDocument(
+  state: ExportPipelineState,
+  document: CanonicalDocumentEnvelope,
+): boolean {
+  // The validator-loop CI harness (§1 / §7) needs to exercise the full
+  // serializer pipeline — including A.1 / A.2 / A.3 / A.6 / A.7 / A.8 /
+  // A.9 fixes — so it sets DOCX_VALIDATOR_FORCE_REGEN=1 to disable the
+  // fast-path byte-reuse. Never set this flag in production; it forces a
+  // full XML regeneration on every export and is only used by the CCEP
+  // validator harness to prove our serializer's correctness.
+  if (readNodeEnvVar("DOCX_VALIDATOR_FORCE_REGEN") === "1") {
+    return false;
+  }
+  if (requiresHostMetadataNormalization(state.sourcePackage, state.sourceDocumentPartPath)) {
+    return false;
+  }
+
+  const commentThreads = Object.values(document.review.comments);
+  const hasLiveComments = commentThreads.some((thread) => thread.anchor.kind !== "detached");
+  const hasRuntimeAuthoredActiveRevisions = Object.values(document.review.revisions).some((revision) =>
+    revision.status === "open" && revision.metadata?.source === "runtime"
+  );
+  if (hasRuntimeAuthoredActiveRevisions) {
+    return false;
+  }
+  if (!hasLiveComments) {
+    return true;
+  }
+
+  return Boolean(
+    state.sourceCommentsPartPath &&
+      state.sourceCommentsExtendedPartPath &&
+      state.sourceCommentsIdsPartPath &&
+      state.sourcePeoplePartPath,
+  );
+}
+
+export function requiresHostMetadataNormalization(
+  sourcePackage: OpcPackage,
+  sourceDocumentPartPath: string,
+): boolean {
+  return (
+    isSuspiciouslySkeletalWordPackage(sourcePackage, sourceDocumentPartPath) &&
+    !hasHostSafeMetadataPackageStructure(sourcePackage)
+  );
+}
+
+export function ensureHostMetadataParts(
+  exportSession: ExportSession,
+  sourcePackage: OpcPackage,
+  document: CanonicalDocumentEnvelope,
+): void {
+  const corePropertiesPart = sourcePackage.parts.get(CORE_PROPERTIES_PART_PATH);
+  if (!corePropertiesPart || corePropertiesPart.contentType !== CORE_PROPERTIES_CONTENT_TYPE) {
+    exportSession.replaceOwnedPart({
+      path: CORE_PROPERTIES_PART_PATH,
+      bytes: corePropertiesPart?.bytes ?? new TextEncoder().encode(buildCorePropertiesXml(document)),
+      contentType: CORE_PROPERTIES_CONTENT_TYPE,
+      compression: corePropertiesPart?.compression,
+    });
+  }
+
+  const appPropertiesPart = sourcePackage.parts.get(APP_PROPERTIES_PART_PATH);
+  if (!appPropertiesPart || appPropertiesPart.contentType !== APP_PROPERTIES_CONTENT_TYPE) {
+    exportSession.replaceOwnedPart({
+      path: APP_PROPERTIES_PART_PATH,
+      bytes: appPropertiesPart?.bytes ?? new TextEncoder().encode(buildAppPropertiesXml()),
+      contentType: APP_PROPERTIES_CONTENT_TYPE,
+      compression: appPropertiesPart?.compression,
+    });
+  }
+
+  exportSession.ensurePackageRelationship({
+    type: CORE_PROPERTIES_RELATIONSHIP_TYPE,
+    target: CORE_PROPERTIES_PART_PATH,
+    preferredId: "rIdDocPropsCore",
+  });
+  exportSession.ensurePackageRelationship({
+    type: APP_PROPERTIES_RELATIONSHIP_TYPE,
+    target: APP_PROPERTIES_PART_PATH,
+    preferredId: "rIdDocPropsApp",
+  });
+}
+
+export function ensureWorkflowPayloadParts(
+  exportSession: ExportSession,
+  sessionState: EditorSessionState,
+  document: CanonicalDocumentEnvelope,
+  sourcePackage: OpcPackage,
+  resolvedPartPaths: {
+    payloadPartPath: string;
+    itemPropsPartPath: string;
+  },
+  editorState?: EditorStatePayload,
+): void {
+  const payloadParts = buildWorkflowPayloadParts({
+    sourcePackage,
+    workflowMetadata: sessionState.workflowMetadata,
+    workflowOverlay: sessionState.workflowOverlay,
+    visibilityPolicies: sessionState.visibilityPolicies,
+    markupModePolicy: sessionState.markupModePolicy ?? null,
+    editorState,
+    documentId: sessionState.documentId,
+    createdAt: document.createdAt,
+    updatedAt: document.updatedAt,
+    producerVersion: sessionState.editorBuild,
+  });
+  if (!payloadParts) {
+    return;
+  }
+  if (
+    payloadParts.payloadPartPath !== resolvedPartPaths.payloadPartPath ||
+    payloadParts.itemPropsPartPath !== resolvedPartPaths.itemPropsPartPath
+  ) {
+    throw new Error(
+      "Workflow payload export resolved inconsistent customXml paths; export session ownership no longer matches payload serialization.",
+    );
+  }
+
+  const payloadPart = sourcePackage.parts.get(payloadParts.payloadPartPath);
+  const itemPropsPart = sourcePackage.parts.get(payloadParts.itemPropsPartPath);
+  const customPropsPart = sourcePackage.parts.get(WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH);
+
+  exportSession.replaceOwnedPart({
+    path: payloadParts.payloadPartPath,
+    bytes: new TextEncoder().encode(payloadParts.payloadPartXml),
+    contentType: payloadPart?.contentType ?? WORKFLOW_PAYLOAD_CONTENT_TYPE,
+    relationships: payloadParts.payloadRelationships,
+    compression: payloadPart?.compression,
+  });
+  exportSession.replaceOwnedPart({
+    path: payloadParts.itemPropsPartPath,
+    bytes: new TextEncoder().encode(payloadParts.itemPropsXml),
+    contentType: itemPropsPart?.contentType ?? WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE,
+    compression: itemPropsPart?.compression,
+  });
+  exportSession.replaceOwnedPart({
+    path: WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
+    bytes: new TextEncoder().encode(payloadParts.customPropertiesXml),
+    contentType: customPropsPart?.contentType ?? WORKFLOW_PAYLOAD_CUSTOM_PROPS_CONTENT_TYPE,
+    compression: customPropsPart?.compression,
+  });
+
+  exportSession.ensurePackageRelationship({
+    type: WORKFLOW_PAYLOAD_CUSTOM_PROPS_RELATIONSHIP_TYPE,
+    target: WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
+    preferredId: "rIdBwWorkflowCustomProps",
+  });
+}
+
+export function hasHostSafeMetadataPackageStructure(sourcePackage: OpcPackage): boolean {
+  const corePropertiesPart = sourcePackage.parts.get(CORE_PROPERTIES_PART_PATH);
+  const appPropertiesPart = sourcePackage.parts.get(APP_PROPERTIES_PART_PATH);
+  return (
+    corePropertiesPart?.contentType === CORE_PROPERTIES_CONTENT_TYPE &&
+    appPropertiesPart?.contentType === APP_PROPERTIES_CONTENT_TYPE &&
+    hasPackageRelationshipTarget(
+      sourcePackage,
+      CORE_PROPERTIES_RELATIONSHIP_TYPE,
+      CORE_PROPERTIES_PART_PATH,
+    ) &&
+    hasPackageRelationshipTarget(
+      sourcePackage,
+      APP_PROPERTIES_RELATIONSHIP_TYPE,
+      APP_PROPERTIES_PART_PATH,
+    )
+  );
+}
+
+export function hasPackageRelationshipTarget(
+  sourcePackage: OpcPackage,
+  relationshipType: string,
+  targetPartPath: string,
+): boolean {
+  return sourcePackage.manifest.packageRelationships.some(
+    (relationship) =>
+      relationship.type === relationshipType &&
+      relationship.targetMode === "internal" &&
+      resolveRelationshipTarget(null, relationship) === targetPartPath,
+  );
+}
+
+export function isSuspiciouslySkeletalWordPackage(
+  sourcePackage: OpcPackage,
+  sourceDocumentPartPath: string,
+): boolean {
+  const allowedPaths = new Set<string>([
+    CONTENT_TYPES_PATH,
+    PACKAGE_RELATIONSHIPS_PATH,
+    sourceDocumentPartPath,
+  ]);
+  const relationshipsPartPath = getRelationshipsPartPath(sourceDocumentPartPath);
+  if (relationshipsPartPath) {
+    allowedPaths.add(relationshipsPartPath);
+  }
+
+  return [...sourcePackage.parts.keys()].every((partPath) => allowedPaths.has(partPath));
+}
+
+export function buildCorePropertiesXml(document: CanonicalDocumentEnvelope): string {
+  const { metadata } = document;
+  const keywords =
+    Array.isArray(metadata.keywords) && metadata.keywords.length > 0
+      ? metadata.keywords.join(", ")
+      : undefined;
+  const propertyLines = [
+    xmlNode("dc:title", metadata.title),
+    xmlNode("dc:subject", metadata.subject),
+    xmlNode("dc:description", metadata.description),
+    xmlNode("dc:language", metadata.language),
+    xmlNode("cp:keywords", keywords),
+    xmlNode("cp:category", metadata.category),
+    xmlNode('dcterms:created xsi:type="dcterms:W3CDTF"', document.createdAt),
+    xmlNode('dcterms:modified xsi:type="dcterms:W3CDTF"', document.updatedAt),
+  ].filter((line): line is string => Boolean(line));
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>',
+    '<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">',
+    ...propertyLines.map((line) => `  ${line}`),
+    "</cp:coreProperties>",
+  ].join("\n");
+}
+
+export function xmlNode(tagName: string, value: string | undefined): string | undefined {
+  if (typeof value !== "string" || value.length === 0) {
+    return undefined;
+  }
+
+  return `<${tagName}>${escapeXml(value)}</${tagName.split(" ", 1)[0]}>`;
+}
+
+export function serializeProtectionRangesIntoDocumentXml(
+  documentXml: string,
+  protection: ProtectionSnapshot,
+  paragraphs = mapParagraphBoundaries(documentXml),
+): string {
+  if (protection.ranges.length === 0) {
+    return documentXml;
+  }
+
+  const insertions = new Map<number, string[]>();
+
+  for (const range of protection.ranges) {
+    if (typeof range.start !== "number" || typeof range.end !== "number") {
+      continue;
+    }
+    const rangeStart = range.start;
+    const rangeEnd = range.end;
+
+    const startParagraph = paragraphs.find(
+      (candidate) => rangeStart >= candidate.start && rangeStart <= candidate.end,
+    );
+    const endParagraph = paragraphs.find(
+      (candidate) => rangeEnd >= candidate.start && rangeEnd <= candidate.end,
+    );
+    if (!startParagraph || !endParagraph) {
+      continue;
+    }
+
+    const startIndex =
+      startParagraph.boundaries.get(rangeStart) ??
+      findNearestBoundaryIndex(startParagraph.boundaries, rangeStart, "backward");
+    const endIndex =
+      endParagraph.boundaries.get(rangeEnd) ??
+      findNearestBoundaryIndex(endParagraph.boundaries, rangeEnd, "forward");
+    if (startIndex === undefined || endIndex === undefined) {
+      continue;
+    }
+
+    const permStartXml = [
+      `<w:permStart`,
+      ` w:id="${escapeXmlAttribute(range.rangeId)}"`,
+      range.editorGroup ? ` w:edGrp="${escapeXmlAttribute(range.editorGroup)}"` : "",
+      range.editor ? ` w:ed="${escapeXmlAttribute(range.editor)}"` : "",
+      `/>`,
+    ].join("");
+    const permEndXml = `<w:permEnd w:id="${escapeXmlAttribute(range.rangeId)}"/>`;
+
+    pushProtectionInsertion(insertions, startIndex, permStartXml);
+    pushProtectionInsertion(insertions, endIndex, permEndXml);
+  }
+
+  if (insertions.size === 0) {
+    return documentXml;
+  }
+
+  const parts: string[] = [];
+  let cursor = 0;
+  for (const [index, snippets] of [...insertions.entries()].sort(([left], [right]) => left - right)) {
+    parts.push(documentXml.slice(cursor, index));
+    parts.push(...snippets);
+    cursor = index;
+  }
+  parts.push(documentXml.slice(cursor));
+  return parts.join("");
+}
+
+function pushProtectionInsertion(
+  insertions: Map<number, string[]>,
+  index: number,
+  xml: string,
+): void {
+  const existing = insertions.get(index);
+  if (existing) {
+    existing.push(xml);
+    return;
+  }
+  insertions.set(index, [xml]);
+}
+
+function findNearestBoundaryIndex(
+  boundaries: Map<number, number>,
+  position: number,
+  direction: "backward" | "forward",
+): number | undefined {
+  const ordered = [...boundaries.entries()].sort(([left], [right]) => left - right);
+  if (direction === "backward") {
+    for (let index = ordered.length - 1; index >= 0; index -= 1) {
+      const [boundaryPos, boundaryIndex] = ordered[index]!;
+      if (boundaryPos <= position) {
+        return boundaryIndex;
+      }
+    }
+    return undefined;
+  }
+  for (const [boundaryPos, boundaryIndex] of ordered) {
+    if (boundaryPos >= position) {
+      return boundaryIndex;
+    }
+  }
+  return undefined;
+}
+
+export function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/\"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+export function escapeXmlAttribute(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}