@beyondwork/docx-react-component 1.0.105 → 1.0.108

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

@@ -24,6 +24,7 @@ import type { SelectionSnapshot } from "../../public-types.ts";
 import type {
   SelectionRangeInput,
   ScrollTarget,
+  UiObjectDragStartInput,
   ViewportState,
 } from "./_types.ts";
 import type { UiApiContext } from "./_context.ts";
@@ -105,6 +106,31 @@ export const scrollToMetadata: ApiV3FnMetadata = {
   rwdReference: "§UI API § ui.surface.scrollTo. Adapter delegates to UiController.dispatchScroll. Slice 3 adds geometry-backed target resolution for block/scope/comment/revision kinds prior to dispatch.",
 };
 
+export const beginObjectDragMetadata: ApiV3FnMetadata = {
+  name: "ui.surface.beginObjectDrag",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/object-drag.test.ts",
+    commit: "refactor-10-object-drag-lifecycle",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "object drag lifecycle starts for a mounted object handle",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "selection",
+    auditCategory: "ui-surface-object-drag",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  rwdReference:
+    "§UI API § object handles. Adapter delegates mounted object drag to UiController.beginObjectDrag; commit routes through host-owned runtime mutation and layout invalidation paths.",
+};
+
 export function createSurfaceFamily(ctx: UiApiContext) {
   return {
     getSelection(): SelectionSnapshot | null {
@@ -166,5 +192,35 @@ export function createSurfaceFamily(ctx: UiApiContext) {
         actualDelta: { kind: "surface-refresh", payload: { kind: target.kind, value: target.kind === "scope" || target.kind === "comment" || target.kind === "revision" || target.kind === "block" ? target.value : undefined } },
       });
     },
+    beginObjectDrag(input: UiObjectDragStartInput) {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.surface.beginObjectDrag: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.beginObjectDrag) {
+        throw new Error(
+          `ui.surface.beginObjectDrag: controller of kind "${controller.kind}" did not provide a beginObjectDrag hook`,
+        );
+      }
+      const session = controller.beginObjectDrag(input);
+      emitUxResponse(ctx.handle, {
+        apiFn: beginObjectDragMetadata.name,
+        intent: beginObjectDragMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: beginObjectDragMetadata.uxIntent.expectedDelta,
+        actualDelta: {
+          kind: "surface-refresh",
+          payload: {
+            objectId: input.objectId,
+            handle: input.handle,
+            sessionId: session.id,
+          },
+        },
+      });
+      return session;
+    },
   };
 }

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

@@ -24,6 +24,7 @@
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import type {
   ViewportState,
+  PageResidencySnapshot,
   UiListener,
   UiUnsubscribe,
   WorkflowMarkupMode,
@@ -33,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",
@@ -86,6 +88,52 @@ export const subscribeMetadata: ApiV3FnMetadata = {
   rwdReference: "§UI API § ui.viewport.subscribe. Adapter delegates to UiController.subscribeViewport; throws when the active binding has no hook. Subscribe call emits one `ux.response.ui.viewport.subscribe` acknowledgement; per-tick ViewportState deliveries flow through the listener (rAF-coalesced, U7).",
 };
 
+export const getPageResidencyMetadata: ApiV3FnMetadata = {
+  name: "ui.viewport.getPageResidency",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/viewport-residency.test.ts",
+    commit: "refactor-10-pe2-residency",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription: "Mock PageResidencySnapshot with residency='evicted' and status='unavailable' when no mounted controller exposes L10 residency policy.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-viewport-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§PE2 § Virtual Page Windowing. Reads L10 page residency policy (realized/cold/evicted) without probing L05 geometry or realizing L11 DOM.",
+};
+
+export const subscribePageResidencyMetadata: ApiV3FnMetadata = {
+  name: "ui.viewport.subscribePageResidency",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/viewport-residency.test.ts",
+    commit: "refactor-10-pe2-residency",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "page-residency subscriber attached; future realized/cold/evicted changes propagate through the listener",
+  },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-viewport-subscribe" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  subscriptionShape: {
+    eventType: "ui.viewport.page_residency_changed",
+    payloadType: "PageResidencySnapshot",
+    coalescing: "raf",
+  },
+  rwdReference: "§PE2 § Virtual Page Windowing. Adapter delegates to UiController.subscribePageResidency; emissions are plain snapshots and do not dispatch PM transactions or force geometry rehydration.",
+};
+
 // ----- scrollToPage (coord-10 §γ — visual-fidelity / Go-to-page UX) -----
 
 export const scrollToPageMetadata: ApiV3FnMetadata = {
@@ -112,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) -----
@@ -245,6 +293,23 @@ export function createViewportFamily(ctx: UiApiContext) {
     notifyMarkupModeSubscribers();
   });
 
+  function normalizePageIndex(pageIndex: number): number {
+    if (!Number.isFinite(pageIndex)) return 0;
+    return Math.max(0, Math.floor(pageIndex));
+  }
+
+  function unavailableResidency(pageIndex: number): PageResidencySnapshot {
+    return Object.freeze({
+      __mock: true,
+      pageIndex: normalizePageIndex(pageIndex),
+      residency: "evicted",
+      status: "unavailable",
+      revision: 0,
+      source: "unavailable",
+      reason: "page-residency policy is not wired on the active controller",
+    } as const);
+  }
+
   return {
     // Slice 11 — composes scroll/dpr/zoom from `handle.geometry` with
     // width/height from the bound controller (see
@@ -279,6 +344,39 @@ export function createViewportFamily(ctx: UiApiContext) {
       });
       return unsubscribe;
     },
+    getPageResidency(pageIndex: number): PageResidencySnapshot {
+      const normalized = normalizePageIndex(pageIndex);
+      const resolver = ctx.binding?.controller.getPageResidency;
+      if (!resolver) return unavailableResidency(normalized);
+      return resolver(normalized);
+    },
+    subscribePageResidency(
+      pageIndex: number,
+      listener: UiListener<PageResidencySnapshot>,
+    ): UiUnsubscribe {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.viewport.subscribePageResidency: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.subscribePageResidency) {
+        throw new Error(
+          `ui.viewport.subscribePageResidency: controller of kind "${controller.kind}" did not provide a subscribePageResidency hook`,
+        );
+      }
+      const normalized = normalizePageIndex(pageIndex);
+      const unsubscribe = controller.subscribePageResidency(normalized, listener);
+      emitUxResponse(ctx.handle, {
+        apiFn: subscribePageResidencyMetadata.name,
+        intent: subscribePageResidencyMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: subscribePageResidencyMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { subscribed: "ui.viewport.pageResidency", pageIndex: normalized } },
+      });
+      return unsubscribe;
+    },
 
     // ----- scrollToPage (coord-10 §γ) -----
 
@@ -295,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,
@@ -328,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;
         }
       }
@@ -354,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,
   };
 }