@beyondwork/docx-react-component 1.0.105 → 1.0.108

package/src/io/ooxml/parse-bookmark-references.ts

@@ -13,6 +13,10 @@
  *   3. A `TOC` field anywhere in the doc — TOC fields produce
  *      hyperlinks to generated `_Toc####` anchors at render time, so
  *      we blanket-retain `_Toc*` whenever a TOC field is present.
+ *   4. A bookmark range that encloses active revision markup. Those
+ *      bookmarks are part of the review round-trip surface; stripping them
+ *      after runtime revision export turns structured re-import into plain
+ *      text.
  *
  * Produces a typed `BookmarkReferenceScan` that the parser consults
  * at every `<w:bookmarkStart>` / `<w:bookmarkEnd>` emission site to
@@ -64,6 +68,11 @@ const TOC_FIELD_RE = /\bTOC\b/;
 const REFLIKE_FIELD_RE =
   /\b(?:HYPERLINK|REF|PAGEREF|NOTEREF)\s+([A-Za-z0-9_:.\-]+)/g;
 const DATA_BINDING_RE = /<(?:\w+:)?dataBinding\b/i;
+const BOOKMARK_START_RE =
+  /<(?:\w+:)?bookmarkStart\b(?=[^>]*\bw:id\s*=\s*"([^"]*)")(?=[^>]*\bw:name\s*=\s*"([^"]*)")[^>]*\/>/gi;
+const BOOKMARK_END_RE =
+  /<(?:\w+:)?bookmarkEnd\b[^>]*\bw:id\s*=\s*"([^"]*)"[^>]*\/>/gi;
+const ACTIVE_REVISION_RE = /<(?:\w+:)?(?:ins|del)\b/i;
 
 /**
  * Always-retain prefix check — bookmarks whose name starts with
@@ -102,6 +111,8 @@ export function scanBookmarkReferences(
     }
   }
 
+  retainRevisionBoundedBookmarks(documentXml, retained);
+
   return {
     retainedNames: retained,
     retainAllTocPattern: retainAllToc,
@@ -109,6 +120,50 @@ export function scanBookmarkReferences(
   };
 }
 
+function retainRevisionBoundedBookmarks(
+  documentXml: string,
+  retained: Set<string>,
+): void {
+  const starts = new Map<
+    string,
+    {
+      name: string;
+      endOffset: number;
+    }
+  >();
+
+  BOOKMARK_START_RE.lastIndex = 0;
+  let startMatch: RegExpExecArray | null;
+  while ((startMatch = BOOKMARK_START_RE.exec(documentXml)) !== null) {
+    const id = startMatch[1];
+    const name = startMatch[2];
+    if (!id || !name) {
+      continue;
+    }
+    starts.set(id, {
+      name,
+      endOffset: startMatch.index + startMatch[0].length,
+    });
+  }
+
+  BOOKMARK_END_RE.lastIndex = 0;
+  let endMatch: RegExpExecArray | null;
+  while ((endMatch = BOOKMARK_END_RE.exec(documentXml)) !== null) {
+    const id = endMatch[1];
+    if (!id) {
+      continue;
+    }
+    const start = starts.get(id);
+    if (!start || start.endOffset > endMatch.index) {
+      continue;
+    }
+    const enclosedXml = documentXml.slice(start.endOffset, endMatch.index);
+    if (ACTIVE_REVISION_RE.test(enclosedXml)) {
+      retained.add(start.name);
+    }
+  }
+}
+
 export function isRetainedBookmarkName(
   name: string,
   scan: BookmarkReferenceScan,

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

@@ -332,13 +332,14 @@ import type {
 } from "../../model/canonical-document.ts";
 import {
   MAIN_STORY_KEY,
+  createCanonicalFieldId,
   createHeaderFooterStoryKey,
   createNoteStoryKey,
 } from "../../model/canonical-layout-inputs.ts";
 import { parseFieldSwitches } from "./parse-field-switches.ts";
 
 const FIELD_FAMILY_PATTERN =
-  /^\s*(REF|PAGEREF|NOTEREF|TOC|PAGE|NUMPAGES|DATE|TIME|AUTHOR|FILENAME|MERGEFIELD|IF|SEQ|INDEX|TC|FORMTEXT|FORMCHECKBOX|FORMDROPDOWN|STYLEREF|SECTIONPAGES)\b/i;
+  /^\s*(REF|PAGEREF|NOTEREF|TOC|PAGE|NUMPAGES|DATE|TIME|AUTHOR|FILENAME|HYPERLINK|MERGEFIELD|IF|SEQ|INDEX|TC|FORMTEXT|FORMCHECKBOX|FORMDROPDOWN|STYLEREF|SECTIONPAGES)\b/i;
 
 const SUPPORTED_FAMILIES = new Set<string>([
   "REF",
@@ -432,20 +433,31 @@ export function buildFieldRegistry(
   walkFieldDocument(root, (node, pIdx) => {
     paragraphIndex = pIdx;
     if (node.type === "field") {
+      const storyKey = MAIN_STORY_KEY;
       const classification = node.fieldFamily
         ? { family: node.fieldFamily, supported: isSupportedFieldFamily(node.fieldFamily), target: node.fieldTarget, switches: node.switches }
         : classifyFieldInstruction(node.instruction);
       const displayText = flattenFieldText(node.children);
       const entry: Mutable<FieldRegistryEntry> = {
         fieldIndex,
+        canonicalFieldId:
+          node.canonicalFieldId ??
+          createCanonicalFieldId({
+            fieldIndex,
+            storyKey,
+            sourceRef: node.sourceRef,
+          }),
         fieldFamily: classification.family,
         supported: classification.supported,
         instruction: node.instruction,
         ...(classification.target ? { fieldTarget: classification.target } : {}),
         displayText,
         paragraphIndex,
-        storyKey: MAIN_STORY_KEY,
+        storyKey,
+        ...(node.sourceRef !== undefined ? { sourceRef: node.sourceRef } : {}),
         refreshStatus: node.refreshStatus ?? (classification.supported ? "stale" : "preserve-only"),
+        ...(node.locked !== undefined ? { locked: node.locked } : {}),
+        ...(node.dirty !== undefined ? { dirty: node.dirty } : {}),
         ...(classification.switches ? { switches: classification.switches } : {}),
       };
       if (classification.supported) {
@@ -469,6 +481,13 @@ export function buildFieldRegistry(
         const displayText = flattenFieldText(node.children);
         const entry: Mutable<FieldRegistryEntry> = {
           fieldIndex,
+          canonicalFieldId:
+            node.canonicalFieldId ??
+            createCanonicalFieldId({
+              fieldIndex,
+              storyKey,
+              sourceRef: node.sourceRef,
+            }),
           fieldFamily: classification.family,
           supported: classification.supported,
           instruction: node.instruction,
@@ -476,7 +495,10 @@ export function buildFieldRegistry(
           displayText,
           paragraphIndex,
           storyKey,
+          ...(node.sourceRef !== undefined ? { sourceRef: node.sourceRef } : {}),
           refreshStatus: node.refreshStatus ?? (classification.supported ? "stale" : "preserve-only"),
+          ...(node.locked !== undefined ? { locked: node.locked } : {}),
+          ...(node.dirty !== undefined ? { dirty: node.dirty } : {}),
           ...(classification.switches ? { switches: classification.switches } : {}),
         };
         if (classification.supported) {

package/src/io/ooxml/parse-headers-footers.ts

@@ -12,6 +12,7 @@ import type {
   TableRowNode,
   TextMark,
   Mutable,
+  CanonicalSourceRef,
 } from "../../model/canonical-document.ts";
 import type { LegacyFormFieldNode } from "../../model/canonical-document.ts";
 import { resolveHighlightColor } from "./highlight-colors.ts";
@@ -58,6 +59,7 @@ import { parseShapeXml, parseVmlXml } from "./parse-shapes.ts";
 
 const TAB_ALIGN_VOCAB = new Set<TabStop["align"]>(["left", "center", "right", "decimal", "num", "bar", "clear"]);
 const TAB_LEADER_VOCAB = new Set<TabStop["leader"]>(["none", "dot", "hyphen", "underscore", "heavy", "middleDot"]);
+let activeHeaderFooterFieldSequenceOrdinal = 0;
 
 // ---- Public types ----
 
@@ -229,6 +231,7 @@ function parseHdrFtrXml(
   opts: ParseHeaderFooterOpts = { relationships: [] },
 ): ParsedHeaderFooterDocument {
   currentSourceXml = xml;
+  activeHeaderFooterFieldSequenceOrdinal = 0;
   let root: XmlElementNode;
   try {
     root = parseXml(xml) as XmlElementNode;
@@ -326,11 +329,12 @@ function parseParagraphElement(
             "complex",
             activeComplexField.children,
             activeComplexField.legacyFormField,
+            activeComplexField.sourceRef,
           ),
         );
         activeComplexField = null;
       }
-      pushFieldNode(children, child, "simple");
+      pushFieldNode(children, child, "simple", opts.sourcePartPath);
     } else if (name === "sdt") {
       // coord-11 §22 — structured-document-tag wrapping run-level content
       // inside a header/footer paragraph. Word commonly uses these to
@@ -355,7 +359,7 @@ function parseParagraphElement(
           } else if (gname === "bookmarkStart" || gname === "bookmarkEnd") {
             children.push(parseBookmarkElement(grandchild));
           } else if (gname === "fldSimple") {
-            pushFieldNode(children, grandchild, "simple");
+            pushFieldNode(children, grandchild, "simple", opts.sourcePartPath);
           }
           // Nested sdt / other elements ignored — deeper nesting is rare
           // enough that opaque round-trip via the block-level sdt parser
@@ -372,6 +376,7 @@ function parseParagraphElement(
         "complex",
         activeComplexField.children,
         activeComplexField.legacyFormField,
+        activeComplexField.sourceRef,
       ),
     );
   }
@@ -391,6 +396,7 @@ interface ActiveComplexField {
   instruction: string;
   children: Array<Extract<InlineNode, { type: "text" | "hard_break" | "tab" }>>;
   mode: "instruction" | "result";
+  sourceRef?: CanonicalSourceRef;
   legacyFormField?: LegacyFormFieldNode;
 }
 
@@ -419,6 +425,7 @@ function appendRunNodes(
           instruction: "",
           children: [],
           mode: "instruction",
+          sourceRef: createFieldSequenceSourceRef(opts.sourcePartPath ?? "/word/document.xml", rElement),
           ...(legacyFormField ? { legacyFormField } : {}),
         };
       } else if (fldType === "separate" && activeComplexField) {
@@ -431,6 +438,7 @@ function appendRunNodes(
               "complex",
               activeComplexField.children,
               activeComplexField.legacyFormField,
+              activeComplexField.sourceRef,
             ),
           );
         }
@@ -443,7 +451,7 @@ function appendRunNodes(
       if (activeComplexField) {
         activeComplexField.instruction += extractTextContent(child);
       } else {
-        pushFieldNode(nodes, child, "complex");
+        pushFieldNode(nodes, child, "complex", opts.sourcePartPath);
       }
       continue;
     }
@@ -522,7 +530,7 @@ function parseRunElement(
     } else if (name === "bookmarkStart" || name === "bookmarkEnd") {
       nodes.push(parseBookmarkElement(child));
     } else if (name === "instrText") {
-      pushFieldNode(nodes, child, "complex");
+      pushFieldNode(nodes, child, "complex", opts.sourcePartPath);
     } else if (name === "drawing") {
       const drawingXml = currentSourceXml.slice(child.start, child.end);
       const drawingResult = parseDrawingInlineNode(drawingXml, opts);
@@ -824,6 +832,7 @@ function pushFieldNode(
   nodes: InlineNode[],
   element: XmlElementNode,
   fieldType: "simple" | "complex",
+  sourcePartPath = "/word/document.xml",
 ): void {
   const instruction = readFieldInstruction(element);
   if (!instruction) {
@@ -832,7 +841,13 @@ function pushFieldNode(
 
   const classification = classifyFieldInstruction(instruction);
 
-  nodes.push(createFieldNode(instruction, fieldType));
+  nodes.push(createFieldNode(
+    instruction,
+    fieldType,
+    [],
+    undefined,
+    createFieldSequenceSourceRef(sourcePartPath, element),
+  ));
 }
 
 function createFieldNode(
@@ -840,6 +855,7 @@ function createFieldNode(
   fieldType: "simple" | "complex",
   children: InlineNode[] = [],
   legacyFormField?: LegacyFormFieldNode,
+  sourceRef?: CanonicalSourceRef,
 ): Extract<InlineNode, { type: "field" }> {
   const classification = classifyFieldInstruction(instruction);
   return {
@@ -850,10 +866,27 @@ function createFieldNode(
     fieldFamily: classification.family,
     ...(classification.target ? { fieldTarget: classification.target } : {}),
     refreshStatus: classification.supported ? "stale" : "preserve-only",
+    ...(sourceRef ? { sourceRef } : {}),
     ...(legacyFormField ? { legacyFormField } : {}),
   };
 }
 
+function createFieldSequenceSourceRef(
+  partPath: string,
+  node: XmlElementNode,
+): CanonicalSourceRef {
+  activeHeaderFooterFieldSequenceOrdinal += 1;
+  return {
+    sourceId: `part:${partPath}#fieldSequence:${activeHeaderFooterFieldSequenceOrdinal}`,
+    partPath,
+    storyKind: /\/footer\d+\.xml$/i.test(partPath) ? "footer" : "header",
+    element: "fieldSequence",
+    ordinal: activeHeaderFooterFieldSequenceOrdinal,
+    startOffset: node.start,
+    endOffset: node.end,
+  };
+}
+
 function readFieldInstruction(element: XmlElementNode): string | undefined {
   const instruction =
     readStringAttr(element, "w:instr") ??

package/src/io/ooxml/parse-main-document.ts

@@ -20,6 +20,7 @@ import type {
   PageSize,
   PageMargins,
   ColumnProperties,
+  CanonicalSourceRef,
   PageNumbering,
   SectionDocumentGrid,
   SectionLineNumbering,
@@ -28,6 +29,7 @@ import type {
   UnknownPropertyChild,
   Mutable,
 } from "../../model/canonical-document.ts";
+import { sha256TextHex } from "../../model/canonical-hash.ts";
 import type { OpcRelationship } from "./part-manifest.ts";
 import { SCOPE_MARKER_BOOKMARK_PREFIX } from "./parse-scope-markers.ts";
 import {
@@ -313,8 +315,10 @@ export interface ParsedParagraphNode {
   styleId?: string;
   numbering?: {
     numberingInstanceId: string;
+    sourceRef?: CanonicalSourceRef;
     level: number;
   };
+  sourceRef?: CanonicalSourceRef;
   alignment?: "left" | "center" | "right" | "both" | "distribute";
   spacing?: ParagraphSpacing;
   contextualSpacing?: boolean;
@@ -438,6 +442,16 @@ export interface ParsedImageNode {
 export interface ParsedHyperlinkNode {
   type: "hyperlink";
   href: string;
+  sourceRef?: CanonicalSourceRef;
+  fieldCarrier?: {
+    sourceRef?: CanonicalSourceRef;
+    fieldFamily?: ReturnType<typeof classifyFieldInstruction>["family"];
+    refreshStatus?: "current" | "stale" | "unresolvable" | "preserve-only";
+    locked?: boolean;
+    dirty?: boolean;
+    instructionHash?: string;
+    resultHash?: string;
+  };
   children: Array<ParsedTextNode | ParsedBreakNode | ParsedColumnBreakNode | ParsedPageBreakNode | ParsedTabNode | ParsedSymbolNode>;
   rawXml: string;
 }
@@ -545,6 +559,7 @@ export interface ParsedFieldInlineNode {
   contentXml?: string;
   children?: Array<ParsedTextNode | ParsedBreakNode | ParsedTabNode>;
   rawXml: string;
+  sourceRef?: CanonicalSourceRef;
   legacyFormField?: import("../../model/canonical-document.ts").LegacyFormFieldNode;
 }
 
@@ -724,6 +739,7 @@ const HYPERLINK_RELATIONSHIP_TYPE =
  * not exist; `parseSdtXml` is only callable externally via `parsePictureSdt`.
  */
 let activeChartPartLookup: ChartPartLookup | undefined;
+let activeFieldSequenceOrdinal = 0;
 
 /**
  * Phase 1 telemetry — optional bus installed by the runtime before a load.
@@ -838,6 +854,7 @@ export function parseMainDocumentXml(
   activeCosmeticStripContext = stripContext;
   const bus = activeParseTelemetryBus;
   const started = bus?.isEnabled("parse") ? performanceNow() : 0;
+  activeFieldSequenceOrdinal = 0;
   try {
     const result = parseMainDocumentXmlInner(xml, relationships, mediaParts, sourcePartPath);
     if (Object.keys(stripContext.counts).length > 0) {
@@ -850,6 +867,7 @@ export function parseMainDocumentXml(
   } finally {
     activeChartPartLookup = undefined;
     activeCosmeticStripContext = null;
+    activeFieldSequenceOrdinal = 0;
   }
 }
 
@@ -1266,7 +1284,7 @@ function parseBodyChild(
     switch (localName(child.name)) {
       case "pPr":
         styleId = readParagraphStyleId(child);
-        numbering = readParagraphNumbering(child);
+        numbering = readParagraphNumbering(child, sourcePartPath);
         alignment = readParagraphAlignment(child);
         spacing = readParagraphSpacing(child);
         contextualSpacing = readOptionalOnOffParagraphProperty(child, "contextualSpacing");
@@ -1307,7 +1325,7 @@ function parseBodyChild(
         flushActiveComplexField(children, () => {
           activeComplexField = null;
         }, activeComplexField);
-        const hyperlink = parseHyperlink(child, sourceXml, relationshipMap);
+        const hyperlink = parseHyperlink(child, sourceXml, relationshipMap, {}, sourcePartPath);
         children.push(hyperlink);
         break;
       }
@@ -1400,6 +1418,7 @@ function parseBodyChild(
           instruction: fieldInstr,
           contentXml: fieldContentXml,
           rawXml: sourceXml.slice(child.start, child.end),
+          sourceRef: createFieldSequenceSourceRef(sourcePartPath, child),
         } as ParsedFieldInlineNode);
         break;
       }
@@ -1481,6 +1500,7 @@ function parseBodyChild(
 
   return {
     type: "paragraph",
+    sourceRef: createElementSourceRef(sourcePartPath, "p", node),
     styleId,
     ...(numbering ? { numbering } : {}),
     ...(alignment ? { alignment } : {}),
@@ -1514,6 +1534,7 @@ function appendParagraphRunNodes(
     instruction: string;
     children: Array<ParsedTextNode | ParsedBreakNode | ParsedTabNode>;
     mode: "instruction" | "result";
+    sourceRef?: CanonicalSourceRef;
     legacyFormField?: import("../../model/canonical-document.ts").LegacyFormFieldNode;
   } | null,
   sourceXml: string,
@@ -1524,6 +1545,7 @@ function appendParagraphRunNodes(
   instruction: string;
   children: Array<ParsedTextNode | ParsedBreakNode | ParsedTabNode>;
   mode: "instruction" | "result";
+  sourceRef?: CanonicalSourceRef;
   legacyFormField?: import("../../model/canonical-document.ts").LegacyFormFieldNode;
 } | null {
   const hasFieldMarkers = node.children.some(
@@ -1565,6 +1587,7 @@ function appendParagraphRunNodes(
           instruction: "",
           children: [],
           mode: "instruction",
+          sourceRef: createFieldSequenceSourceRef(sourcePartPath, node),
           ...(legacyFormField ? { legacyFormField } : {}),
         };
       } else if (fldType === "separate" && activeComplexField) {
@@ -1591,6 +1614,7 @@ function appendParagraphRunNodes(
           instruction,
           children: [],
           rawXml: sourceXml.slice(node.start, node.end),
+          sourceRef: createFieldSequenceSourceRef(sourcePartPath, node),
         });
       }
       continue;
@@ -1607,6 +1631,7 @@ function flushActiveComplexField(
     instruction: string;
     children: Array<ParsedTextNode | ParsedBreakNode | ParsedTabNode>;
     mode: "instruction" | "result";
+    sourceRef?: CanonicalSourceRef;
     legacyFormField?: import("../../model/canonical-document.ts").LegacyFormFieldNode;
   } | null,
 ): void {
@@ -1620,6 +1645,7 @@ function flushActiveComplexField(
     instruction: activeComplexField.instruction,
     children: activeComplexField.children,
     rawXml: "",
+    ...(activeComplexField.sourceRef ? { sourceRef: activeComplexField.sourceRef } : {}),
     ...(activeComplexField.legacyFormField ? { legacyFormField: activeComplexField.legacyFormField } : {}),
   });
   reset();
@@ -2547,6 +2573,7 @@ function readParagraphStyleId(node: XmlElementNode): string | undefined {
 
 function readParagraphNumbering(
   node: XmlElementNode,
+  sourcePartPath: string,
 ): ParsedParagraphNode["numbering"] | undefined {
   const numberingProperties = node.children.find(
     (child): child is XmlElementNode =>
@@ -2572,10 +2599,50 @@ function readParagraphNumbering(
 
   return {
     numberingInstanceId: toCanonicalNumberingInstanceId(rawInstanceId),
+    sourceRef: createElementSourceRef(sourcePartPath, "numPr", numberingProperties),
     level: Number.parseInt(rawLevel, 10),
   };
 }
 
+function createElementSourceRef(
+  partPath: string,
+  element: string,
+  node: XmlElementNode,
+): CanonicalSourceRef {
+  return {
+    sourceId: `part:${partPath}#${element}:${node.start}`,
+    partPath,
+    storyKind: storyKindFromPartPath(partPath),
+    element,
+    startOffset: node.start,
+    endOffset: node.end,
+  };
+}
+
+function createFieldSequenceSourceRef(
+  partPath: string,
+  node: XmlElementNode,
+): CanonicalSourceRef {
+  activeFieldSequenceOrdinal += 1;
+  return {
+    sourceId: `part:${partPath}#fieldSequence:${activeFieldSequenceOrdinal}`,
+    partPath,
+    storyKind: storyKindFromPartPath(partPath),
+    element: "fieldSequence",
+    ordinal: activeFieldSequenceOrdinal,
+    startOffset: node.start,
+    endOffset: node.end,
+  };
+}
+
+function storyKindFromPartPath(partPath: string): string {
+  if (/\/header\d+\.xml$/i.test(partPath)) return "header";
+  if (/\/footer\d+\.xml$/i.test(partPath)) return "footer";
+  if (/\/footnotes\.xml$/i.test(partPath)) return "footnote";
+  if (/\/endnotes\.xml$/i.test(partPath)) return "endnote";
+  return "main";
+}
+
 function parseRun(
   node: XmlElementNode,
   sourceXml: string,
@@ -2916,10 +2983,16 @@ function parseRevisionContainer(
         break;
       }
       case "hyperlink": {
-        const hyperlink = parseHyperlink(child, sourceXml, relationshipMap, {
-          allowDeletedText: allowsDeletedText,
-          preserveUnsupportedReviewMarkup: true,
-        });
+        const hyperlink = parseHyperlink(
+          child,
+          sourceXml,
+          relationshipMap,
+          {
+            allowDeletedText: allowsDeletedText,
+            preserveUnsupportedReviewMarkup: true,
+          },
+          "/word/document.xml",
+        );
         if (hyperlink.type === "opaque_inline") {
           return [
             {
@@ -3020,6 +3093,7 @@ function parseHyperlink(
     allowDeletedText?: boolean;
     preserveUnsupportedReviewMarkup?: boolean;
   } = {},
+  sourcePartPath = "/word/document.xml",
 ): ParsedHyperlinkNode | ParsedOpaqueInlineNode {
   const relationshipId = node.attributes["r:id"] ?? node.attributes.id;
   const anchor = node.attributes["w:anchor"] ?? node.attributes.anchor;
@@ -3058,6 +3132,10 @@ function parseHyperlink(
   // escape the hyperlink scope.
   type FieldBracketMode = "outside" | "instruction" | "result";
   let bracketMode: FieldBracketMode = "outside";
+  let fieldSourceRef: CanonicalSourceRef | undefined;
+  let fieldInstruction = "";
+  let fieldLocked: boolean | undefined;
+  let fieldDirty: boolean | undefined;
 
   for (const child of node.children) {
     if (child.type !== "element") {
@@ -3081,9 +3159,29 @@ function parseHyperlink(
     if (fldChar) {
       const fldType =
         fldChar.attributes["w:fldCharType"] ?? fldChar.attributes.fldCharType;
-      if (fldType === "begin") bracketMode = "instruction";
-      else if (fldType === "separate") bracketMode = "result";
-      else if (fldType === "end") bracketMode = "outside";
+      if (fldType === "begin") {
+        bracketMode = "instruction";
+        fieldSourceRef = createFieldSequenceSourceRef(sourcePartPath, child);
+        fieldInstruction = "";
+        fieldLocked = readOnOffFieldFlag(fldChar, "fldLock");
+        fieldDirty = readOnOffFieldFlag(fldChar, "dirty");
+      } else if (fldType === "separate") {
+        bracketMode = "result";
+      } else if (fldType === "end") {
+        bracketMode = "outside";
+      }
+      continue;
+    }
+
+    const instrText = child.children.find(
+      (c): c is XmlElementNode =>
+        c.type === "element" && localName(c.name) === "instrText",
+    );
+    if (instrText && bracketMode === "instruction") {
+      fieldInstruction += instrText.children
+        .filter((entry): entry is XmlTextNode => entry.type === "text")
+        .map((entry) => entry.text)
+        .join("");
       continue;
     }
 
@@ -3107,14 +3205,60 @@ function parseHyperlink(
     children.push(...run.nodes);
   }
 
+  const fieldClassification = fieldInstruction.trim().length > 0
+    ? classifyFieldInstruction(fieldInstruction)
+    : undefined;
   return {
     type: "hyperlink",
     href,
+    sourceRef: createElementSourceRef(sourcePartPath, "hyperlink", node),
+    ...(fieldSourceRef
+      ? {
+          fieldCarrier: {
+            sourceRef: fieldSourceRef,
+            ...(fieldClassification ? { fieldFamily: fieldClassification.family } : {}),
+            refreshStatus: fieldClassification?.supported
+              ? "stale"
+              : "preserve-only",
+            ...(fieldInstruction ? { instructionHash: sha256TextHex(fieldInstruction) } : {}),
+            ...(children.length > 0 ? { resultHash: sha256TextHex(hyperlinkFieldResultText(children)) } : {}),
+            ...(fieldLocked !== undefined ? { locked: fieldLocked } : {}),
+            ...(fieldDirty !== undefined ? { dirty: fieldDirty } : {}),
+          },
+        }
+      : {}),
     children,
     rawXml: sourceXml.slice(node.start, node.end),
   };
 }
 
+function hyperlinkFieldResultText(children: readonly ParsedInlineNode[]): string {
+  return children
+    .map((child) => {
+      switch (child.type) {
+        case "text":
+          return child.text;
+        case "tab":
+          return "\t";
+        case "hard_break":
+          return "\n";
+        case "symbol":
+          return child.char;
+        default:
+          return "";
+      }
+    })
+    .join("");
+}
+
+function readOnOffFieldFlag(node: XmlElementNode, name: string): boolean | undefined {
+  const raw = node.attributes[`w:${name}`] ?? node.attributes[name];
+  if (raw === undefined) return undefined;
+  const normalized = raw.toLowerCase();
+  if (normalized === "0" || normalized === "false" || normalized === "off") return false;
+  return true;
+}
+
 function parseRunContentOnly(
   node: XmlElementNode,
   _sourceXml: string,

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

@@ -1,4 +1,5 @@
 import type {
+  CanonicalSourceRef,
   NumberingCatalog,
   NumberingLevelDefinition,
   NumberingLevelParagraphGeometry,
@@ -93,6 +94,9 @@ export function parseNumberingXml(xml: string, context?: ParseNumberingContext):
         const numStyleLink = numStyleLinkEl ? readStringAttr(numStyleLinkEl, "w:val") : undefined;
         abstractDefinitions[abstractNumberingId] = {
           abstractNumberingId,
+          ...(context?.partPath !== undefined
+            ? { sourceRef: createNumberingSourceRef(context.partPath, "abstractNum", rawId) }
+            : {}),
           levels: readLevels(child),
           ...(nsid ? { nsid } : {}),
           ...(multiLevelType ? { multiLevelType } : {}),
@@ -114,6 +118,9 @@ export function parseNumberingXml(xml: string, context?: ParseNumberingContext):
         const numberingInstanceId = toCanonicalNumberingInstanceId(rawId);
         instances[numberingInstanceId] = {
           numberingInstanceId,
+          ...(context?.partPath !== undefined
+            ? { sourceRef: createNumberingSourceRef(context.partPath, "num", rawId) }
+            : {}),
           abstractNumberingId: toCanonicalAbstractNumberingId(rawAbstractId),
           overrides: readOverrides(child),
         };
@@ -129,6 +136,19 @@ export function parseNumberingXml(xml: string, context?: ParseNumberingContext):
   };
 }
 
+function createNumberingSourceRef(
+  partPath: string,
+  element: "abstractNum" | "num",
+  rawId: string,
+): CanonicalSourceRef {
+  return {
+    sourceId: `part:${partPath}#${element}:${rawId}`,
+    partPath,
+    storyKind: "numbering",
+    element,
+  };
+}
+
 /**
  * Read a `<w:numPicBullet>` element into a catalog entry. Extracts the
  * inner `wp:extent` when present (drawingML path); the raw XML is