@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/api/v3/ui/viewport.ts

@@ -34,6 +34,7 @@ import type {
 import type { UiApiContext } from "./_context.ts";
 import { readComposedViewport } from "./_context.ts";
 import { emitUxResponse } from "../_ux-response.ts";
+import { buildPageAnchorElementId } from "../_page-anchor-id.ts";
 
 export const getMetadata: ApiV3FnMetadata = {
   name: "ui.viewport.get",
@@ -159,7 +160,7 @@ export const scrollToPageMetadata: ApiV3FnMetadata = {
   stateClass: "C-local",
   persistsTo: "none",
   rwdReference:
-    "§UI API § ui.viewport.scrollToPage. Resolves pageNumber → scrollY via handle.geometry.getPage(pageIndex); dispatches through controller.dispatchScroll({ kind:'page', value, behavior }); returns the settled {actualPage, scrollY}. 1-based page numbers; clamps to [1, pageCount]. First-class API for visual-fidelity harness + 'Go to page N' UX — replaces DOM-scrape fallback (coord-10 §γ). Parity note: reads the same `handle.geometry.getPage(i).frame.topPx` source as `runtime.viewport.getPageAnchor` (L07 coord-07 §2.9, shipped 2026-04-24 in `src/api/v3/runtime/viewport.ts`), so `actualPage + scrollY` here and `{scrollY, pageRect}` on the runtime side stay consistent by construction. No direct delegation today because `scripts/ci-check-ui-api-layer-purity.mjs` restricts `src/api/v3/ui/**` from importing `src/api/v3/runtime/**`; both surfaces are thin wrappers over the shared geometry facet.",
+    "§UI API § ui.viewport.scrollToPage. Resolves pageNumber → scrollY + elementId via handle.geometry.getPage(pageIndex); dispatches through controller.dispatchScroll({ kind:'page', value, behavior }); returns the settled {actualPage, scrollY, elementId}. 1-based page numbers; clamps to [1, pageCount]. First-class API for visual-fidelity harness + 'Go to page N' UX — replaces DOM-scrape fallback (coord-10 §γ). Parity note: reads the same `handle.geometry.getPage(i).frame.topPx` source as `runtime.viewport.getPageAnchor` (L07 coord-07 §2.9, shipped 2026-04-24 in `src/api/v3/runtime/viewport.ts`), so `actualPage + scrollY + elementId` here and `{scrollY, pageRect, elementId}` on the runtime side stay consistent by construction. No direct delegation today because `scripts/ci-check-ui-api-layer-purity.mjs` restricts `src/api/v3/ui/**` from importing `src/api/v3/runtime/**`; both surfaces are thin wrappers over the shared geometry facet.",
 };
 
 // ----- X5 markup-mode metadata (state-classes cross-cutting Slice X5) -----
@@ -392,10 +393,10 @@ export function createViewportFamily(ctx: UiApiContext) {
      * the document's page count returns the last valid page's scrollY;
      * `actualPage` reflects the clamp so callers can detect it.
      *
-     * Returns `null` when (a) no controller is bound, (b) the controller
-     * has no `dispatchScroll` hook, or (c) geometry cannot resolve any
-     * page (pre-paint / empty doc). Callers that need explicit failure
-     * handling check `result !== null` before trusting the scroll.
+     * Throws when controller wiring is missing. Returns `null` only when
+     * geometry cannot resolve any page (pre-paint / empty doc). Callers
+     * that need explicit failure handling check `result !== null` before
+     * trusting the scroll.
      */
     async scrollToPage(
       pageNumber: number,
@@ -425,11 +426,15 @@ export function createViewportFamily(ctx: UiApiContext) {
       // Try the requested page; if null, scan downward through lower
       // indices to land on the largest resolvable page (the doc's last
       // populated page). If nothing resolves, return null.
-      let resolved: { pageIndex: number; scrollY: number } | null = null;
+      let resolved: { pageIndex: number; scrollY: number; elementId: string } | null = null;
       for (let i = requestedClampedLow - 1; i >= 0; i--) {
         const page = getPage.call(ctx.handle.geometry, i);
         if (page) {
-          resolved = { pageIndex: i, scrollY: page.frame.topPx };
+          resolved = {
+            pageIndex: i,
+            scrollY: page.frame.topPx,
+            elementId: buildPageAnchorElementId(page.pageId, i),
+          };
           break;
         }
       }
@@ -451,11 +456,19 @@ export function createViewportFamily(ctx: UiApiContext) {
         expectedDelta: scrollToPageMetadata.uxIntent.expectedDelta,
         actualDelta: {
           kind: "surface-refresh",
-          payload: { page: actualPage, scrollY: resolved.scrollY },
+          payload: {
+            page: actualPage,
+            scrollY: resolved.scrollY,
+            elementId: resolved.elementId,
+          },
         },
       });
 
-      return { actualPage, scrollY: resolved.scrollY };
+      return {
+        actualPage,
+        scrollY: resolved.scrollY,
+        elementId: resolved.elementId,
+      };
     },
 
     // ----- X5 markup-mode (state-classes cross-cutting Slice X5) -----

package/src/core/commands/image-commands.ts

@@ -139,6 +139,7 @@ function insertImageIntoParagraph(
     (unit) =>
       unit.kind === "opaque_inline" ||
       unit.kind === "opaque_block" ||
+      unit.kind === "structural_block" ||
       unit.kind === "image",
   );
   if (protectedUnit) {

package/src/core/commands/index.ts

@@ -15,7 +15,9 @@ import {
   createNodeAnchor,
   createRangeAnchor,
   DEFAULT_BOUNDARY_ASSOC,
+  MAIN_STORY_TARGET,
   mapAnchor,
+  storyTargetsEqual,
   type BoundaryAssoc,
   type EditorAnchorProjection,
   type MappingStep,
@@ -1925,6 +1927,10 @@ function applyReviewCommand(
       continue;
     }
 
+    if (!storyTargetsEqual(entry.storyTarget, MAIN_STORY_TARGET)) {
+      continue;
+    }
+
     selection = remapSelection(selection, entry.mapping);
     mappingSteps.push(...entry.mapping.steps);
 

package/src/core/schema/text-schema.ts

@@ -8,6 +8,11 @@ import type {
   TextMark,
 } from "../../model/canonical-document.ts";
 
+type PreservedStructuralBlockNode = Exclude<
+  DocumentRootNode["children"][number],
+  ParagraphNode | OpaqueBlockNode
+>;
+
 export interface ParagraphProperties {
   styleId?: string;
   numbering?: ParagraphNode["numbering"];
@@ -33,6 +38,7 @@ export type StoryUnit =
   | ImageUnit
   | OpaqueInlineUnit
   | OpaqueBlockUnit
+  | PreservedStructuralBlockUnit
   | ScopeMarkerUnit
   | ParagraphBreakUnit;
 
@@ -72,6 +78,12 @@ export interface OpaqueBlockUnit {
   nextParagraph?: ParagraphProperties;
 }
 
+export interface PreservedStructuralBlockUnit {
+  kind: "structural_block";
+  block: PreservedStructuralBlockNode;
+  nextParagraph?: ParagraphProperties;
+}
+
 export interface ParagraphBreakUnit {
   kind: "paragraph_break";
   nextParagraph: ParagraphProperties;
@@ -114,14 +126,21 @@ export function parseTextStory(content: unknown): TextStory {
       continue;
     }
 
-    if (block.type !== "opaque_block") {
+    if (block.type === "opaque_block") {
+      units.push({
+        kind: "opaque_block",
+        fragmentId: block.fragmentId,
+        warningId: block.warningId,
+        ...(isParagraphNode(nextBlock)
+          ? { nextParagraph: extractParagraphProperties(nextBlock) }
+          : {}),
+      });
       continue;
     }
 
     units.push({
-      kind: "opaque_block",
-      fragmentId: block.fragmentId,
-      warningId: block.warningId,
+      kind: "structural_block",
+      block,
       ...(isParagraphNode(nextBlock)
         ? { nextParagraph: extractParagraphProperties(nextBlock) }
         : {}),
@@ -186,7 +205,7 @@ export function logicalPositionToUnitIndex(
 }
 
 export function serializeTextStory(story: TextStory): DocumentRootNode {
-  const blocks: Array<ParagraphNode | OpaqueBlockNode> = [];
+  const blocks: DocumentRootNode["children"] = [];
   let currentParagraph: ParagraphNode | undefined = createParagraph(story.firstParagraph);
   let currentHyperlink: HyperlinkNode | undefined;
   let activeTextBuffer:
@@ -301,6 +320,15 @@ export function serializeTextStory(story: TextStory): DocumentRootNode {
       continue;
     }
 
+    if (unit.kind === "structural_block") {
+      flushParagraph();
+      blocks.push(unit.block);
+      currentParagraph = unit.nextParagraph
+        ? createParagraph(unit.nextParagraph)
+        : undefined;
+      continue;
+    }
+
     if (unit.kind === "text") {
       const shouldExtendBuffer =
         activeTextBuffer &&
@@ -384,6 +412,8 @@ export function createPlainText(story: TextStory): string {
           return "\uFFF9";
         case "opaque_block":
           return "\uFFFA";
+        case "structural_block":
+          return "\uFFFA";
         case "scope_marker":
           return "";
       }
@@ -431,6 +461,14 @@ export function cloneStoryUnit(unit: StoryUnit): StoryUnit {
           ? { nextParagraph: cloneParagraphProperties(unit.nextParagraph) }
           : {}),
       };
+    case "structural_block":
+      return {
+        kind: "structural_block",
+        block: structuredClone(unit.block) as PreservedStructuralBlockNode,
+        ...(unit.nextParagraph
+          ? { nextParagraph: cloneParagraphProperties(unit.nextParagraph) }
+          : {}),
+      };
     case "paragraph_break":
       return {
         kind: "paragraph_break",

package/src/core/selection/mapping.ts

@@ -67,12 +67,19 @@ export function createRangeAnchor(
   assoc: BoundaryAssoc = DEFAULT_BOUNDARY_ASSOC,
 ): RangeAnchor {
   const normalized = normalizeRange({ from, to });
-  return {
+  const anchor = {
     kind: "range",
     from: normalized.from,
     to: normalized.to,
     assoc,
   };
+  Object.defineProperty(anchor, "range", {
+    value: normalized,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return anchor as RangeAnchor;
 }
 
 export function createNodeAnchor(at: Position, assoc: Assoc = 1): NodeAnchor {

package/src/core/selection/review-anchors.ts

@@ -95,7 +95,11 @@ export function rangeStaysWithinSingleParagraph(
       continue;
     }
 
-    if (unit.kind === "paragraph_break" || unit.kind === "opaque_block") {
+    if (
+      unit.kind === "paragraph_break" ||
+      unit.kind === "opaque_block" ||
+      unit.kind === "structural_block"
+    ) {
       return false;
     }
   }

package/src/core/state/text-transaction.ts

@@ -914,6 +914,8 @@ function resolveParagraphPropertiesAtPosition(
       current = cloneParagraphProperties(unit.nextParagraph);
     } else if (unit.kind === "opaque_block" && unit.nextParagraph) {
       current = cloneParagraphProperties(unit.nextParagraph);
+    } else if (unit.kind === "structural_block" && unit.nextParagraph) {
+      current = cloneParagraphProperties(unit.nextParagraph);
     }
   }
 
@@ -947,7 +949,11 @@ function normalizeStoryUnits(units: StoryUnit[]): StoryUnit[] {
 
 function ensureEditableRange(units: StoryUnit[]): void {
   const protectedUnit = units.find(
-    (unit) => unit.kind === "opaque_inline" || unit.kind === "opaque_block" || unit.kind === "image",
+    (unit) =>
+      unit.kind === "opaque_inline" ||
+      unit.kind === "opaque_block" ||
+      unit.kind === "structural_block" ||
+      unit.kind === "image",
   );
 
   if (!protectedUnit) {
@@ -971,5 +977,5 @@ function containsParagraphBoundaryChange(
 
   return story.units
     .slice(range.from, range.to)
-    .some((unit) => unit.kind === "paragraph_break");
+    .some((unit) => unit.kind === "paragraph_break" || unit.kind === "structural_block");
 }

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

@@ -40,12 +40,22 @@ export function serializeRevisionsIntoDocumentXml(
   const boundaries = options.boundaries ?? mapRevisionBoundaries(documentXml);
   const replacements: XmlReplacement[] = [];
   const consumedRevisionIds = new Set<string>();
+  const consumedMarkupRevisionIds = new Set<string>();
   const paragraphDecisions = collectParagraphMarkupDecisions(
     preservedMarkup,
     revisionById,
     boundaries,
   );
 
+  replacements.push(
+    ...createMoveRangeMarkerReplacements(
+      preservedMarkup,
+      revisionById,
+      consumedRevisionIds,
+      consumedMarkupRevisionIds,
+    ),
+  );
+
   replacements.push(
     ...createParagraphStructuralReplacements(
       documentXml,
@@ -56,7 +66,10 @@ export function serializeRevisionsIntoDocumentXml(
   );
 
   for (const markup of preservedMarkup) {
-    if (consumedRevisionIds.has(markup.revisionId)) {
+    if (
+      consumedRevisionIds.has(markup.revisionId) ||
+      consumedMarkupRevisionIds.has(markup.revisionId)
+    ) {
       continue;
     }
 
@@ -87,6 +100,141 @@ export function serializeRevisionsIntoDocumentXml(
   return applyReplacements(documentXml, replacements);
 }
 
+function createMoveRangeMarkerReplacements(
+  preservedMarkup: readonly PreservedRevisionMarkup[],
+  revisionById: ReadonlyMap<string, RevisionRecord>,
+  consumedRevisionIds: Set<string>,
+  consumedMarkupRevisionIds: Set<string>,
+): XmlReplacement[] {
+  const replacements: XmlReplacement[] = [];
+  const rangeMarkers = collectMoveRangeMarkers(preservedMarkup);
+
+  for (const marker of rangeMarkers) {
+    const revision = revisionById.get(marker.start.revisionId);
+    if (
+      !revision ||
+      revision.status === "active" ||
+      revision.status === "detached" ||
+      revision.kind !== "move"
+    ) {
+      continue;
+    }
+
+    const direction = revision.metadata.moveData?.direction;
+    if (direction !== marker.direction) {
+      continue;
+    }
+
+    const shouldDropSpan =
+      (revision.status === "accepted" && marker.direction === "from") ||
+      (revision.status === "rejected" && marker.direction === "to");
+
+    if (shouldDropSpan) {
+      replacements.push({
+        start: marker.start.xmlStart,
+        end: marker.end.xmlEnd,
+        replacement: "",
+      });
+    } else {
+      replacements.push(
+        {
+          start: marker.start.xmlStart,
+          end: marker.start.xmlEnd,
+          replacement: "",
+        },
+        {
+          start: marker.end.xmlStart,
+          end: marker.end.xmlEnd,
+          replacement: "",
+        },
+      );
+    }
+
+    consumedRevisionIds.add(marker.start.revisionId);
+    consumedMarkupRevisionIds.add(marker.end.revisionId);
+  }
+
+  return replacements;
+}
+
+function collectMoveRangeMarkers(
+  preservedMarkup: readonly PreservedRevisionMarkup[],
+): Array<{
+  direction: "from" | "to";
+  moveId: string;
+  start: PreservedRevisionMarkup;
+  end: PreservedRevisionMarkup;
+}> {
+  const starts = new Map<string, PreservedRevisionMarkup>();
+  const ends = new Map<string, PreservedRevisionMarkup>();
+
+  for (const markup of preservedMarkup) {
+    const direction = getMoveRangeMarkerDirection(markup.originalRevisionType);
+    if (!direction) {
+      continue;
+    }
+    const moveId = readMoveRangeMarkerId(markup);
+    if (!moveId) {
+      continue;
+    }
+    const key = `${direction}:${moveId}`;
+    if (isMoveRangeStart(markup.originalRevisionType)) {
+      starts.set(key, markup);
+    } else if (isMoveRangeEnd(markup.originalRevisionType)) {
+      ends.set(key, markup);
+    }
+  }
+
+  const markers: Array<{
+    direction: "from" | "to";
+    moveId: string;
+    start: PreservedRevisionMarkup;
+    end: PreservedRevisionMarkup;
+  }> = [];
+
+  for (const [key, start] of starts.entries()) {
+    const end = ends.get(key);
+    if (!end) {
+      continue;
+    }
+    const [direction, moveId] = key.split(":");
+    if ((direction === "from" || direction === "to") && moveId) {
+      markers.push({ direction, moveId, start, end });
+    }
+  }
+
+  return markers;
+}
+
+function isMoveRangeStart(originalRevisionType: string): boolean {
+  return originalRevisionType === "moveFromRangeStart" ||
+    originalRevisionType === "moveToRangeStart";
+}
+
+function isMoveRangeEnd(originalRevisionType: string): boolean {
+  return originalRevisionType === "moveFromRangeEnd" ||
+    originalRevisionType === "moveToRangeEnd";
+}
+
+function getMoveRangeMarkerDirection(
+  originalRevisionType: string,
+): "from" | "to" | undefined {
+  if (originalRevisionType === "moveFromRangeStart" ||
+      originalRevisionType === "moveFromRangeEnd") {
+    return "from";
+  }
+  if (originalRevisionType === "moveToRangeStart" ||
+      originalRevisionType === "moveToRangeEnd") {
+    return "to";
+  }
+  return undefined;
+}
+
+function readMoveRangeMarkerId(markup: PreservedRevisionMarkup): string | undefined {
+  const match = /\b(?:w:)?id=(["'])([^"']+)\1/.exec(markup.rawXml);
+  return match?.[2];
+}
+
 function serializeMarkup(
   markup: PreservedRevisionMarkup,
   revision: RevisionRecord | undefined,

package/src/io/normalize/normalize-text.ts

@@ -245,6 +245,7 @@ function normalizeParagraph(
   const children = normalizeInlineChildren(paragraph.children, state, packagePartName);
   return {
     type: "paragraph",
+    ...(paragraph.sourceRef ? { sourceRef: paragraph.sourceRef } : {}),
     ...(paragraph.styleId ? { styleId: paragraph.styleId } : {}),
     ...(paragraph.numbering ? { numbering: paragraph.numbering } : {}),
     ...(paragraph.alignment ? { alignment: paragraph.alignment } : {}),
@@ -603,6 +604,7 @@ function normalizeInlineChildren(
           ...(classification.target ? { fieldTarget: classification.target } : {}),
           ...(classification.switches ? { switches: classification.switches } : {}),
           refreshStatus: classification.supported ? "stale" : "preserve-only",
+          ...(node.sourceRef ? { sourceRef: node.sourceRef } : {}),
           ...(node.legacyFormField ? { legacyFormField: node.legacyFormField } : {}),
         });
         state.cursor += renderedLength > 0 ? renderedLength : 1;
@@ -720,6 +722,8 @@ function registerComplexPreviewMedia(
 function normalizeHyperlink(node: ParsedHyperlinkNode): {
   type: "hyperlink";
   href: string;
+  sourceRef?: ParsedHyperlinkNode["sourceRef"];
+  fieldCarrier?: ParsedHyperlinkNode["fieldCarrier"];
   children: Array<
     | TextNode
     | { type: "hard_break" }
@@ -789,6 +793,8 @@ function normalizeHyperlink(node: ParsedHyperlinkNode): {
   return {
     type: "hyperlink",
     href: node.href,
+    ...(node.sourceRef ? { sourceRef: node.sourceRef } : {}),
+    ...(node.fieldCarrier ? { fieldCarrier: node.fieldCarrier } : {}),
     children,
   };
 }

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) {