@beyondwork/docx-react-component 1.0.40 → 1.0.42

package/src/index.ts

@@ -8,7 +8,114 @@ export {
   EDITOR_SESSION_STATE_VERSION,
 } from "./api/session-state.ts";
 // R2 — issue metadata id for scope-card-overlay P1.
-export { ISSUE_METADATA_ID } from "./api/public-types.ts";
+// K1-light — review-action metadata id for scope-card-overlay P2.
+export { ISSUE_METADATA_ID, REVIEW_ACTION_METADATA_ID } from "./api/public-types.ts";
+// P17 — metadata persistence error class.
+export { MetadataResolverMissingError } from "./api/public-types.ts";
+
+// Collab substrate (P1 – P8f + P14). See docs/plans/collab-master-plan.md
+// for the shipped-slice table. Surfaces are stable for host integration;
+// the chrome preset + markdown renderer land in P9 / P10.
+export { createCollabSession } from "./runtime/collab-session.ts";
+export { createCollabSessionBridge } from "./runtime/collab-session-bridge.ts";
+export { createCollabSessionFacet } from "./runtime/collab-session-facet.ts";
+export { createTamperGate } from "./runtime/tamper-gate.ts";
+export { resignPayload } from "./runtime/resign-payload.ts";
+export {
+  setLocalIdentity,
+  clearLocalIdentity,
+  getPresenceSnapshot,
+  getCollabPosture,
+} from "./runtime/awareness-identity.ts";
+export { runtimeSendToExternal } from "./runtime/external-send-runtime.ts";
+export { sendToExternal } from "./io/export/external-send.ts";
+export { maybeRestoreFromExternalCustody } from "./io/import/external-reimport.ts";
+export {
+  signWorkflowPayloadXml,
+  verifyWorkflowPayloadXml,
+  createHmacSigner,
+  createHmacVerifier,
+} from "./io/ooxml/payload-signature.ts";
+export type {
+  // Collab types
+  CollabSession,
+  CollabSessionOptions,
+  CollabSessionEventOrIntegrity,
+  AttachPayloadArgs,
+  SendToExternalCallArgs,
+} from "./runtime/collab-session.ts";
+export type {
+  CollabSessionBridge,
+  CollabSessionEvent,
+  CreateCollabSessionBridgeOptions,
+} from "./runtime/collab-session-bridge.ts";
+export type {
+  CollabSessionFacet,
+  DispatchContext,
+  DispatchResult,
+} from "./runtime/collab-session-facet.ts";
+export type {
+  TamperGate,
+  TamperGateEvent,
+  MetadataIntegrity,
+  TamperGateArgs,
+  AttachArgs as TamperGateAttachArgs,
+  GuardResult as TamperGateGuardResult,
+} from "./runtime/tamper-gate.ts";
+export type {
+  RuntimeSendToExternalArgs,
+  RuntimeSendToExternalResult,
+} from "./runtime/external-send-runtime.ts";
+export type {
+  CommentNegotiationAction,
+  CommentNegotiationEntry,
+  CommentNegotiationSnapshot,
+  CommentNegotiationState,
+  CommentNegotiationActionType,
+  NegotiationHistoryRow,
+  NegotiationVote,
+  NegotiationCounterProposal,
+  NegotiationBlockReason,
+  NegotiationRole,
+  CollabBlockReason,
+} from "./api/comment-negotiation-types.ts";
+export type {
+  CommentPresentation,
+  CommentPresentationAction,
+  CommentPresentationSnapshot,
+  CommentPresentationReply,
+  CommentBody,
+  CommentAttachment,
+  CommentAudience,
+  CommentLabel,
+  CommentMention,
+  CommentReaction,
+} from "./api/comment-presentation-types.ts";
+export type {
+  Participant,
+  ParticipantRoster,
+  ParticipantRole,
+  AuthorKind,
+} from "./api/participants-types.ts";
+export type {
+  AwarenessIdentity,
+  AwarenessPeer,
+  CollabPosture,
+  PresenceSnapshot,
+  TransportStatus,
+} from "./api/awareness-identity-types.ts";
+export type {
+  ExternalCustody,
+  ExternalCustodyResolver,
+  ExternalCustodyArchivePayload,
+  ExternalCustodyRestoredContent,
+} from "./api/external-custody-types.ts";
+export type {
+  PayloadSignature,
+  PayloadSigner,
+  PayloadVerifier,
+  SignatureAlgorithm,
+} from "./io/ooxml/payload-signature.ts";
 export type {
   LoadRequest,
   LoadSourcePolicy,
@@ -113,6 +220,11 @@ export type {
   IssueMetadataValue,
   ScopeIssueAction,
   ScopeCardModel,
+  // R3 — suggestion groups (scope-card-overlay P2)
+  SuggestionGroup,
+  // K1-light — review-action audit trail (scope-card-overlay P2)
+  ReviewActionKind,
+  ReviewActionMetadataValue,
   WorkflowBlockedCommandReason,
   WorkflowScopeSnapshot,
   InteractionGuardSnapshot,
@@ -150,4 +262,9 @@ export type {
   RuntimeContextAnalyticsUnavailableField,
   RuntimeContextAnalyticsProvenance,
   RuntimeContextAnalyticsSnapshot,
+  // P17 — metadata persistence types (schema 1.1)
+  MetadataPersistenceMode,
+  ScopeMetadataPersistence,
+  ScopeMetadataResolver,
+  ScopeMetadataStorageRef,
 } from "./api/public-types.ts";

package/src/io/export/escape-xml-attribute.ts

@@ -0,0 +1,26 @@
+/**
+ * Escape a string for safe use inside a double-quoted XML attribute value.
+ *
+ * Handles the minimum set XML 1.0 §2.3 requires to survive an attribute
+ * parser: `&` (otherwise any `&foo;` sequence becomes an entity reference),
+ * `<` (not permitted in any attribute value), and `"` (the delimiter
+ * itself).  Escaping `>` is not strictly required but matches the pattern
+ * already shipped by every serializer in this directory — keep doing it
+ * so the output remains byte-identical to the previous per-file copies.
+ *
+ * Rationale: before this helper existed, eight files under `src/io/export/`
+ * carried private copies of the same 3-or-4-line function
+ * (`serialize-{comments,footnotes,headers-footers,numbering,main-document,
+ * runtime-revisions,tables}.ts` + `table-properties-xml.ts`).  Two of them
+ * had a subtle variant (`escapeXml(value).replace('"', '&quot;')`) that
+ * composed with a local `escapeXml` copy; the end state was equivalent for
+ * every observed input, and this single implementation keeps that
+ * behaviour while removing seven copies.
+ */
+export function escapeXmlAttribute(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;")
+    .replace(/"/gu, "&quot;");
+}

package/src/io/export/external-send.ts

@@ -0,0 +1,188 @@
+import type {
+  CommentNegotiationSnapshot,
+} from "../../api/comment-negotiation-types.ts";
+import type {
+  CommentPresentationSnapshot,
+} from "../../api/comment-presentation-types.ts";
+import type {
+  ExternalCustody,
+  ExternalCustodyResolver,
+} from "../../api/external-custody-types.ts";
+import type { ParticipantRoster } from "../../api/participants-types.ts";
+
+export interface SendToExternalArgs {
+  /** Snapshot taken from the runtime before the call. */
+  presentation: CommentPresentationSnapshot;
+  negotiation: CommentNegotiationSnapshot;
+  participants: ParticipantRoster;
+
+  /** Current runtime role — author-only action. */
+  role: "author" | "reviewer" | "observer";
+  /** Blocks send if the runtime flagged the payload as tampered. */
+  metadataIntegrity: "unsigned" | "verified" | "tampered";
+
+  /** Origin document identity, used to populate the custody receipt. */
+  originDocumentId: string;
+  originPayloadId: string;
+  /** sha256:{hex} of canonicalized word/document.xml at send time. */
+  originContentHash: string;
+
+  /** Host-provided archive+restore contract. */
+  resolver: ExternalCustodyResolver;
+  recipient: string;
+  sentBy: string;
+  archiveRef: string;
+
+  /** Optional uuid + clock overrides for deterministic tests. */
+  custodyId?: string;
+  now?: string;
+}
+
+export interface SendToExternalResult {
+  custody: ExternalCustody;
+  kept: {
+    presentation: CommentPresentationSnapshot;
+    negotiation: CommentNegotiationSnapshot;
+    participants: ParticipantRoster;
+  };
+  stripped: {
+    commentIds: string[];
+    participantIds: string[];
+  };
+}
+
+export type SendToExternalBlock =
+  | { ok: false; reason: "collab_role_restricted" }
+  | { ok: false; reason: "metadata_tampered" }
+  | { ok: true; result: SendToExternalResult };
+
+/**
+ * Pure pipeline: classify comments by audience, split the snapshots
+ * into kept vs. archived, hand archived content to the resolver, and
+ * return the kept snapshots + custody receipt for the caller to
+ * serialize into the supplier-bound docx.
+ *
+ * The caller is responsible for: serializing the kept snapshots back
+ * into `bw:extensions`, rewriting `word/comments.xml` (and the three
+ * companion parts + `word/document.xml` anchor runs) to drop the
+ * stripped `commentIds`, appending the custody receipt, and re-signing
+ * via the central `resignPayload()` hook.
+ */
+export async function sendToExternal(
+  args: SendToExternalArgs,
+): Promise<SendToExternalBlock> {
+  if (args.role !== "author") {
+    return { ok: false, reason: "collab_role_restricted" };
+  }
+  if (args.metadataIntegrity === "tampered") {
+    return { ok: false, reason: "metadata_tampered" };
+  }
+
+  const strippedPresentation = args.presentation.entries.filter(
+    (e) => e.audience === "internal",
+  );
+  const keptPresentation = args.presentation.entries.filter(
+    (e) => e.audience !== "internal",
+  );
+  const strippedCommentIds = strippedPresentation.map((e) => e.commentId);
+  const strippedCommentIdSet = new Set(strippedCommentIds);
+
+  const strippedNegotiation = args.negotiation.entries.filter((e) =>
+    strippedCommentIdSet.has(e.commentId),
+  );
+  const keptNegotiation = args.negotiation.entries.filter(
+    (e) => !strippedCommentIdSet.has(e.commentId),
+  );
+
+  const referencedUserIds = collectReferencedUserIds(
+    keptPresentation,
+    keptNegotiation,
+  );
+  const strippedParticipants = args.participants.entries.filter(
+    (p) => !referencedUserIds.has(p.userId),
+  );
+  const keptParticipants = args.participants.entries.filter((p) =>
+    referencedUserIds.has(p.userId),
+  );
+  const strippedParticipantIds = strippedParticipants.map((p) => p.userId);
+
+  const custody: ExternalCustody = {
+    schemaVersion: 1,
+    custodyId: args.custodyId ?? newCustodyId(),
+    originDocumentId: args.originDocumentId,
+    originPayloadId: args.originPayloadId,
+    originContentHash: args.originContentHash,
+    sentAt: args.now ?? new Date().toISOString(),
+    sentBy: args.sentBy,
+    recipient: args.recipient,
+    archiveRef: args.archiveRef,
+    strippedCommentIds,
+    strippedParticipantIds,
+  };
+
+  await args.resolver.archive({
+    custodyId: custody.custodyId,
+    strippedPresentation,
+    strippedNegotiation,
+    strippedParticipants,
+    originContentHash: args.originContentHash,
+  });
+
+  return {
+    ok: true,
+    result: {
+      custody,
+      kept: {
+        presentation: { schemaVersion: 1, entries: keptPresentation },
+        negotiation: { schemaVersion: 1, entries: keptNegotiation },
+        participants: { schemaVersion: 1, entries: keptParticipants },
+      },
+      stripped: {
+        commentIds: strippedCommentIds,
+        participantIds: strippedParticipantIds,
+      },
+    },
+  };
+}
+
+function collectReferencedUserIds(
+  presentation: CommentPresentationSnapshot["entries"],
+  negotiation: CommentNegotiationSnapshot["entries"],
+): Set<string> {
+  const ids = new Set<string>();
+  for (const entry of presentation) {
+    for (const m of entry.mentions) ids.add(m.userId);
+    for (const r of entry.reactions) ids.add(r.authorId);
+  }
+  for (const entry of negotiation) {
+    for (const v of entry.votes) ids.add(v.authorId);
+    for (const a of entry.requiredApprovers) ids.add(a);
+    for (const p of entry.counterProposals) ids.add(p.authorId);
+    for (const h of entry.history) ids.add(h.actorId);
+    if (entry.lockedBy) ids.add(entry.lockedBy);
+  }
+  return ids;
+}
+
+function newCustodyId(): string {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  // Cryptographic fallback.  custodyId is used as a lookup key against the
+  // host archive that holds stripped internal comments — a predictable id
+  // would let an attacker enumerate or guess other sessions' archives.
+  // WebCrypto's getRandomValues is in Node 18+ and every modern browser;
+  // throw if unavailable rather than fall back to Math.random().
+  if (typeof globalThis.crypto?.getRandomValues !== "function") {
+    throw new Error(
+      "newCustodyId: WebCrypto (crypto.getRandomValues) is required — refusing " +
+        "to fall back to Math.random() for a security-sensitive identifier.",
+    );
+  }
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

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

@@ -1,6 +1,7 @@
 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";
+import { escapeXmlAttribute } from "./escape-xml-attribute.ts";
 
 interface XmlElementNode {
   type: "element";
@@ -210,7 +211,7 @@ export function serializeMergedCommentsXml(
               .sort((left, right) => left.localeCompare(right))
               .map(
                 (authorId) =>
-                  `<w15:person w15:author="${escapeAttribute(authorId)}" />`,
+                  `<w15:person w15:author="${escapeXmlAttribute(authorId)}" />`,
               ),
             `</w15:people>`,
           ].join("\n")
@@ -289,17 +290,17 @@ export function serializeCommentAnchorsIntoDocumentXml(
     pushInsertion(
       insertions,
       startIndex,
-      `<w:commentRangeStart w:id="${escapeAttribute(exportCommentId)}"/>`,
+      `<w:commentRangeStart w:id="${escapeXmlAttribute(exportCommentId)}"/>`,
     );
     pushInsertion(
       insertions,
       endIndex,
-      `<w:commentRangeEnd w:id="${escapeAttribute(exportCommentId)}"/>`,
+      `<w:commentRangeEnd w:id="${escapeXmlAttribute(exportCommentId)}"/>`,
     );
     pushInsertion(
       insertions,
       endIndex,
-      `<w:r><w:commentReference w:id="${escapeAttribute(exportCommentId)}"/></w:r>`,
+      `<w:r><w:commentReference w:id="${escapeXmlAttribute(exportCommentId)}"/></w:r>`,
     );
     serializedCommentIds.push(thread.commentId);
   }
@@ -462,12 +463,12 @@ function serializeThreadEntries(entries: readonly SerializableCommentEntry[]): s
 }
 
 function serializeCommentEntry(entry: SerializableCommentEntry): string {
-  const author = escapeAttribute(entry.entry.authorId);
-  const createdAt = escapeAttribute(entry.entry.createdAt);
+  const author = escapeXmlAttribute(entry.entry.authorId);
+  const createdAt = escapeXmlAttribute(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>`;
+  return `<w:comment w:id="${escapeXmlAttribute(entry.exportCommentId)}"${initials ? ` w:initials="${escapeXmlAttribute(initials)}"` : ""} w:author="${author}" w:date="${createdAt}">${paragraphXml}</w:comment>`;
 }
 
 function serializeCommentParagraphs(body: string, paraId: string): string {
@@ -477,7 +478,7 @@ function serializeCommentParagraphs(body: string, paraId: string): string {
     .map((paragraph, index) => {
       const attributes =
         index === 0
-          ? ` w14:paraId="${escapeAttribute(paraId)}" w14:textId="${escapeAttribute(textId)}"`
+          ? ` w14:paraId="${escapeXmlAttribute(paraId)}" w14:textId="${escapeXmlAttribute(textId)}"`
           : "";
       return `<w:p${attributes}><w:r>${serializeText(paragraph)}</w:r></w:p>`;
     })
@@ -500,13 +501,13 @@ 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}" />`;
+  return `<w15:commentEx w15:paraId="${escapeXmlAttribute(definition.paraId!)}"${definition.parentParaId ? ` w15:paraIdParent="${escapeXmlAttribute(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"}" />`;
+  return `<w15:commentEx w15:paraId="${escapeXmlAttribute(entry.paraId)}"${entry.isRoot ? "" : ` w15:paraIdParent="${escapeXmlAttribute(findRootParaId(entry.thread, entry.paraId))}"`} w15:done="${entry.isRoot && entry.thread.status === "resolved" ? "true" : "false"}" />`;
 }
 
 function serializePreservedCommentIds(
@@ -515,7 +516,7 @@ function serializePreservedCommentIds(
   return definitions
     .map((definition) =>
       definition.paraId && definition.durableId
-        ? `<w16cid:commentId w16cid:paraId="${escapeAttribute(definition.paraId)}" w16cid:durableId="${escapeAttribute(definition.durableId)}" />`
+        ? `<w16cid:commentId w16cid:paraId="${escapeXmlAttribute(definition.paraId)}" w16cid:durableId="${escapeXmlAttribute(definition.durableId)}" />`
         : undefined,
     )
     .filter((xml): xml is string => Boolean(xml));
@@ -528,7 +529,7 @@ function serializeCommentDurableId(
     return undefined;
   }
 
-  return `<w16cid:commentId w16cid:paraId="${escapeAttribute(entry.paraId)}" w16cid:durableId="${escapeAttribute(entry.durableId)}" />`;
+  return `<w16cid:commentId w16cid:paraId="${escapeXmlAttribute(entry.paraId)}" w16cid:durableId="${escapeXmlAttribute(entry.durableId)}" />`;
 }
 
 function getRootEntry(thread: CommentThread): CommentEntry | undefined {
@@ -794,10 +795,6 @@ function escapeXml(value: string): string {
     .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) {

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

@@ -17,6 +17,7 @@ import {
   serializeTableRowPropertiesXml,
 } from "./table-properties-xml.ts";
 import { twip } from "./twip.ts";
+import { escapeXmlAttribute } from "./escape-xml-attribute.ts";
 
 export const WORD_FOOTNOTES_CONTENT_TYPE =
   "application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml";
@@ -104,7 +105,7 @@ function serializeNoteDefinition(
     .join("");
 
   const body = blocks || `<w:p><w:r><w:t></w:t></w:r></w:p>`;
-  const noteXml = `<${tag} w:id="${escapeAttribute(definition.noteId)}">${body}</${tag}>`;
+  const noteXml = `<${tag} w:id="${escapeXmlAttribute(definition.noteId)}">${body}</${tag}>`;
   if (revisions.length === 0) {
     return noteXml;
   }
@@ -188,17 +189,17 @@ function buildParagraphPropertiesXml(paragraph: ParagraphNode): string {
   const parts: string[] = [];
 
   if (paragraph.styleId) {
-    parts.push(`<w:pStyle w:val="${escapeAttribute(paragraph.styleId)}"/>`);
+    parts.push(`<w:pStyle w:val="${escapeXmlAttribute(paragraph.styleId)}"/>`);
   }
   if (paragraph.alignment) {
-    parts.push(`<w:jc w:val="${escapeAttribute(paragraph.alignment)}"/>`);
+    parts.push(`<w:jc w:val="${escapeXmlAttribute(paragraph.alignment)}"/>`);
   }
   if (paragraph.spacing) {
     const attrs: string[] = [];
     if (paragraph.spacing.before !== undefined) attrs.push(`w:before="${twip(paragraph.spacing.before)}"`);
     if (paragraph.spacing.after !== undefined) attrs.push(`w:after="${twip(paragraph.spacing.after)}"`);
     if (paragraph.spacing.line !== undefined) attrs.push(`w:line="${twip(paragraph.spacing.line)}"`);
-    if (paragraph.spacing.lineRule) attrs.push(`w:lineRule="${escapeAttribute(paragraph.spacing.lineRule)}"`);
+    if (paragraph.spacing.lineRule) attrs.push(`w:lineRule="${escapeXmlAttribute(paragraph.spacing.lineRule)}"`);
     if (attrs.length > 0) {
       parts.push(`<w:spacing ${attrs.join(" ")}/>`);
     }
@@ -233,8 +234,8 @@ function serializeInlineNode(node: InlineNode): string {
     case "footnote_ref": {
       const refElement =
         node.noteKind === "footnote"
-          ? `<w:footnoteReference w:id="${escapeAttribute(node.noteId)}"/>`
-          : `<w:endnoteReference w:id="${escapeAttribute(node.noteId)}"/>`;
+          ? `<w:footnoteReference w:id="${escapeXmlAttribute(node.noteId)}"/>`
+          : `<w:endnoteReference w:id="${escapeXmlAttribute(node.noteId)}"/>`;
       const styleVal =
         node.noteKind === "footnote"
           ? "FootnoteReference"
@@ -242,9 +243,9 @@ function serializeInlineNode(node: InlineNode): string {
       return `<w:r><w:rPr><w:rStyle w:val="${styleVal}"/></w:rPr>${refElement}</w:r>`;
     }
     case "bookmark_start":
-      return `<w:bookmarkStart w:id="${escapeAttribute(node.bookmarkId)}" w:name="${escapeAttribute(node.name)}"/>`;
+      return `<w:bookmarkStart w:id="${escapeXmlAttribute(node.bookmarkId)}" w:name="${escapeXmlAttribute(node.name)}"/>`;
     case "bookmark_end":
-      return `<w:bookmarkEnd w:id="${escapeAttribute(node.bookmarkId)}"/>`;
+      return `<w:bookmarkEnd w:id="${escapeXmlAttribute(node.bookmarkId)}"/>`;
     case "field":
       if (node.children && node.children.length > 0) {
         const childrenXml = node.children.map((child) => serializeInlineNode(child)).join("");
@@ -257,10 +258,10 @@ function serializeInlineNode(node: InlineNode): string {
             `<w:r><w:fldChar w:fldCharType="end"/></w:r>`
           );
         }
-        return `<w:fldSimple w:instr="${escapeAttribute(node.instruction)}">${childrenXml}</w:fldSimple>`;
+        return `<w:fldSimple w:instr="${escapeXmlAttribute(node.instruction)}">${childrenXml}</w:fldSimple>`;
       }
       if (node.fieldType === "simple") {
-        return `<w:fldSimple w:instr="${escapeAttribute(node.instruction)}"/>`;
+        return `<w:fldSimple w:instr="${escapeXmlAttribute(node.instruction)}"/>`;
       }
       return (
         `<w:r><w:fldChar w:fldCharType="begin"/></w:r>` +
@@ -282,10 +283,10 @@ function serializeInlineNode(node: InlineNode): string {
             `<w:r><w:fldChar w:fldCharType="end"/></w:r>`
           );
         }
-        return `<w:fldSimple w:instr="${escapeAttribute(node.instruction)}">${childrenXml}</w:fldSimple>`;
+        return `<w:fldSimple w:instr="${escapeXmlAttribute(node.instruction)}">${childrenXml}</w:fldSimple>`;
       }
       if (node.fieldType === "simple") {
-        return `<w:fldSimple w:instr="${escapeAttribute(node.instruction)}"/>`;
+        return `<w:fldSimple w:instr="${escapeXmlAttribute(node.instruction)}"/>`;
       }
       return (
         `<w:r><w:fldChar w:fldCharType="begin"/></w:r>` +
@@ -327,14 +328,14 @@ function buildRunPropertiesXml(marks: TextMark[] | undefined): string {
         break;
       case "fontFamily":
         parts.push(
-          `<w:rFonts w:ascii="${escapeAttribute(mark.val)}" w:hAnsi="${escapeAttribute(mark.val)}"/>`,
+          `<w:rFonts w:ascii="${escapeXmlAttribute(mark.val)}" w:hAnsi="${escapeXmlAttribute(mark.val)}"/>`,
         );
         break;
       case "fontSize":
         parts.push(`<w:sz w:val="${twip(mark.val)}"/>`);
         break;
       case "textColor":
-        parts.push(`<w:color w:val="${escapeAttribute(mark.color)}"/>`);
+        parts.push(`<w:color w:val="${escapeXmlAttribute(mark.color)}"/>`);
         break;
       case "smallCaps":
         parts.push("<w:smallCaps/>");
@@ -371,23 +372,15 @@ function escapeXml(text: string): string {
     .replace(/>/g, "&gt;");
 }
 
-function escapeAttribute(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}
-
 function serializeHyperlinkNode(node: Extract<InlineNode, { type: "hyperlink" }>): string {
   const childrenXml = node.children.map((child) => serializeInlineNode(child)).join("");
   if (node.href.startsWith("#")) {
-    return `<w:hyperlink w:anchor="${escapeAttribute(node.href.slice(1))}">${childrenXml}</w:hyperlink>`;
+    return `<w:hyperlink w:anchor="${escapeXmlAttribute(node.href.slice(1))}">${childrenXml}</w:hyperlink>`;
   }
   if (!/^rId[A-Za-z0-9._-]+$/u.test(node.href)) {
     throw new Error("Cannot safely serialize URL-backed note hyperlinks without relationship context.");
   }
-  return `<w:hyperlink r:id="${escapeAttribute(node.href)}">${childrenXml}</w:hyperlink>`;
+  return `<w:hyperlink r:id="${escapeXmlAttribute(node.href)}">${childrenXml}</w:hyperlink>`;
 }
 
 function buildTableCellPropertiesXml(cell: TableCellNode): string {