@beyondwork/docx-react-component 1.0.73 → 1.0.75

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

@@ -33,9 +33,92 @@
  */
 
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
-import type { ScopeBundle } from "../../public-types.ts";
+import type {
+  ScopeBundle,
+  ScopeCardModel,
+  ScopeRailSnapshot,
+  SemanticScope,
+  SemanticScopeKind,
+} from "../../public-types.ts";
 import type { UiApiContext } from "./_context.ts";
 
+export interface UiScopeListFilter {
+  readonly kind?: SemanticScopeKind;
+  readonly limit?: number;
+}
+
+export interface UiScopeRailOptions {
+  /**
+   * Narrow the snapshot to a single page index. Omit (default) to
+   * span every page the runtime's page graph knows about.
+   */
+  readonly pageIndex?: number;
+}
+
+export const cardMetadata: ApiV3FnMetadata = {
+  name: "ui.scope.card",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/scope-card-rail.test.ts",
+    commit: "refactor-10-ki-008-ui-scope-card-rail",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "scope",
+    auditCategory: "ui-scope-card-read",
+  },
+  // Same classification as other `ui.scope.*` reads — canonical scope
+  // projection (not class-C local preference). KI-008 close.
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§UI API § ui.scope.card. Wraps handle.compileScopeCardById(scopeId) which projects runtime.workflow.getAllScopeCardModels() filtered to the matching scope. Returns plain-value ScopeCardModel — no React handlers, no DOM refs. Hosts wire event handlers in their own chrome tree.",
+};
+
+export const railMetadata: ApiV3FnMetadata = {
+  name: "ui.scope.rail",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/scope-card-rail.test.ts",
+    commit: "refactor-10-ki-008-ui-scope-card-rail",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "ui-scope-rail-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§UI API § ui.scope.rail. Wraps handle.compileScopeRailSnapshot({pageIndex?}) which projects runtime.workflow.getRailSegments(pageIndex) / getAllRailSegments() into a ScopeRailSnapshot envelope. Plain-value data; no React handlers.",
+};
+
+export const listMetadata: ApiV3FnMetadata = {
+  name: "ui.scope.list",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/scope-list.test.ts",
+    commit: "refactor-10-ki-008-ui-scope-list",
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "ui-scope-list",
+  },
+  // Same classification as `ui.scope.getBundle` — reads canonical
+  // scope state (not class-C local preference). KI-008 closure.
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§UI API § ui.scope.list. Wraps handle.compileScopeList(filter?) to enumerate compiled SemanticScope records through the L10 seam without importing src/runtime/scopes/**. Filter matches ai.listScopes({kind?, limit?}) for identity-set symmetry.",
+};
+
 export const getBundleMetadata: ApiV3FnMetadata = {
   name: "ui.scope.getBundle",
   status: "live-with-adapter",
@@ -67,5 +150,34 @@ export function createScopeFamily(ctx: UiApiContext) {
       const nowUtc = new Date().toISOString();
       return compile.call(ctx.handle, scopeId, nowUtc);
     },
+    list(filter?: UiScopeListFilter): readonly SemanticScope[] {
+      // KI-008 — enumeration through the handle's batch primitive
+      // (L10 purity blocks importing src/runtime/scopes/**). Returns
+      // a fresh array so callers that sort / splice don't leak into
+      // internal compiler state.
+      const enumerate = ctx.handle.compileScopeList;
+      if (typeof enumerate !== "function") return Object.freeze([]);
+      return enumerate.call(ctx.handle, filter);
+    },
+    card(scopeId: string): ScopeCardModel | null {
+      // KI-008 close — single-scope presentation projection. Returns
+      // a plain-value ScopeCardModel (posture, label, issue, suggestion
+      // groups, review actions, agent-pending flag). Host chrome wires
+      // event handlers around it.
+      const compile = ctx.handle.compileScopeCardById;
+      if (typeof compile !== "function") return null;
+      return compile.call(ctx.handle, scopeId);
+    },
+    rail(options?: UiScopeRailOptions): ScopeRailSnapshot {
+      // KI-008 close — rail snapshot. When `options.pageIndex` is
+      // supplied, narrows to that page; otherwise spans every page
+      // in the runtime's page graph. Envelope shape is stable either
+      // way; callers check `snapshot.pageIndex` to detect narrowing.
+      const compile = ctx.handle.compileScopeRailSnapshot;
+      if (typeof compile !== "function") {
+        return { segments: Object.freeze([]) };
+      }
+      return compile.call(ctx.handle, options);
+    },
   };
 }

package/src/compare/diff-engine.ts

@@ -410,8 +410,7 @@ function createParagraphRevisionRecords(
       changeId: revision.changeId,
       kind: revision.kind,
       anchor: {
-        kind: "range",
-        range: { from: position, to: position },
+        kind: "range", from: position, to: position,
         assoc: { start: -1, end: 1 },
       },
       authorId,

package/src/core/commands/index.ts

@@ -1525,9 +1525,9 @@ export function remapSelection(
 
   if (activeRange.kind === "range") {
     return {
-      anchor: activeRange.range.from,
-      head: activeRange.range.to,
-      isCollapsed: activeRange.range.from === activeRange.range.to,
+      anchor: activeRange.from,
+      head: activeRange.to,
+      isCollapsed: activeRange.from === activeRange.to,
       activeRange,
     };
   }
@@ -1664,8 +1664,8 @@ function normalizeSelection(selection: SelectionSnapshot): SelectionSnapshot {
   );
 
   if (activeRange.kind === "range") {
-    const rangeFrom = activeRange.range.from;
-    const rangeTo = activeRange.range.to;
+    const rangeFrom = activeRange.from;
+    const rangeTo = activeRange.to;
     const collapsed = rangeFrom === rangeTo;
     const anchorWithinRange = selection.anchor >= rangeFrom && selection.anchor <= rangeTo;
     const headWithinRange = selection.head >= rangeFrom && selection.head <= rangeTo;
@@ -2256,7 +2256,8 @@ function createAuthoredRevision(
     kind,
     anchor: {
       kind: "range",
-      range: { from, to },
+      from,
+      to,
       assoc: { start: 1, end: -1 },
     },
     authorId,
@@ -2396,8 +2397,7 @@ function applySuggestingInsert(
       const updatedRevision: CanonicalRevisionRecord = {
         ...existingInsertion,
         anchor: {
-          kind: "range",
-          range: { from: existingInsertion.anchor.range.from, to: insertedTo },
+          kind: "range", from: existingInsertion.anchor.from, to: insertedTo,
           assoc: { start: 1, end: -1 },
         },
       };
@@ -2635,19 +2635,18 @@ function applySuggestingDelete(
   if (existingDeletion) {
     // Extend the existing deletion revision to cover the new range
     const extendedFrom = Math.min(
-      existingDeletion.anchor.kind === "range" ? existingDeletion.anchor.range.from : deleteFrom,
+      existingDeletion.anchor.kind === "range" ? existingDeletion.anchor.from : deleteFrom,
       deleteFrom,
     );
     const extendedTo = Math.max(
-      existingDeletion.anchor.kind === "range" ? existingDeletion.anchor.range.to : deleteTo,
+      existingDeletion.anchor.kind === "range" ? existingDeletion.anchor.to : deleteTo,
       deleteTo,
     );
 
     const updatedRevision: CanonicalRevisionRecord = {
       ...existingDeletion,
       anchor: {
-        kind: "range",
-        range: { from: extendedFrom, to: extendedTo },
+        kind: "range", from: extendedFrom, to: extendedTo,
         assoc: { start: 1, end: -1 },
       },
     };
@@ -2933,7 +2932,7 @@ function findAdjacentInsertionRevision(
       revision.status === "open" &&
       revision.metadata?.source === "runtime" &&
       revision.anchor.kind === "range" &&
-      revision.anchor.range.to === cursorPos &&
+      revision.anchor.to === cursorPos &&
       revision.authorId === authorId
     ) {
       return revision;
@@ -2954,8 +2953,8 @@ function findOverlappingAuthoredDeletion(
       revision.metadata?.source === "runtime" &&
       revision.anchor.kind === "range"
     ) {
-      const revFrom = revision.anchor.range.from;
-      const revTo = revision.anchor.range.to;
+      const revFrom = revision.anchor.from;
+      const revTo = revision.anchor.to;
       // Adjacent or overlapping: the deletion is directly next to or overlapping the range
       if (
         (from >= revFrom && from <= revTo) ||

package/src/core/selection/anchor-conversion.ts

@@ -79,8 +79,8 @@ export function toPublicAnchorProjection(
     case "range":
       return {
         kind: "range",
-        from: anchor.range.from,
-        to: anchor.range.to,
+        from: anchor.from,
+        to: anchor.to,
         assoc: anchor.assoc,
       };
     case "node":

package/src/core/selection/mapping.ts

@@ -66,9 +66,11 @@ export function createRangeAnchor(
   to = from,
   assoc: BoundaryAssoc = DEFAULT_BOUNDARY_ASSOC,
 ): RangeAnchor {
+  const normalized = normalizeRange({ from, to });
   return {
     kind: "range",
-    range: normalizeRange({ from, to }),
+    from: normalized.from,
+    to: normalized.to,
     assoc,
   };
 }
@@ -89,7 +91,7 @@ export function createEmptyMapping(): TransactionMapping {
 
 export function getEffectiveRange(anchor: EditorAnchorProjection): DocRange {
   if (anchor.kind === "range") {
-    return anchor.range;
+    return { from: anchor.from, to: anchor.to };
   }
   if (anchor.kind === "node") {
     return { from: anchor.at, to: anchor.at };
@@ -140,13 +142,13 @@ export function mapAnchor(
     return createNodeAnchor(mapped.position, anchor.assoc);
   }
 
-  const from = mapPosition(anchor.range.from, anchor.assoc.start, mapping);
-  const to = mapPosition(anchor.range.to, anchor.assoc.end, mapping);
+  const from = mapPosition(anchor.from, anchor.assoc.start, mapping);
+  const to = mapPosition(anchor.to, anchor.assoc.end, mapping);
   const mappedRange = normalizeRange({ from: from.position, to: to.position });
 
   if (from.deleted && to.deleted && mappedRange.from === mappedRange.to) {
     return createDetachedAnchor(
-      anchor.range,
+      { from: anchor.from, to: anchor.to },
       mapping.metadata?.invalidatesStructures
         ? "invalidatedByStructureChange"
         : "deleted",
@@ -187,8 +189,8 @@ export function areAnchorsEqual(
 
   if (left.kind === "range" && right.kind === "range") {
     return (
-      left.range.from === right.range.from &&
-      left.range.to === right.range.to &&
+      left.from === right.from &&
+      left.to === right.to &&
       left.assoc.start === right.assoc.start &&
       left.assoc.end === right.assoc.end
     );
@@ -213,7 +215,7 @@ export function anchorUnaffectedByMapping(
 ): boolean {
   if (anchor.kind === "detached") return true;
   if (mapping.steps.length === 0) return true;
-  const end = anchor.kind === "range" ? anchor.range.to : anchor.at;
+  const end = anchor.kind === "range" ? anchor.to : anchor.at;
   return mapping.steps.every((s) => s.from > end);
 }
 

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

@@ -40,7 +40,7 @@ export function mapReviewAnchor(
 
 export function getAnchorRange(anchor: ReviewAnchor): DocRange {
   if (anchor.kind === "range") {
-    return normalizeRange(anchor.range);
+    return normalizeRange({ from: anchor.from, to: anchor.to });
   }
 
   if (anchor.kind === "node") {
@@ -136,7 +136,7 @@ export function commentAnchorRejectionReason(
     return "invalid_comment_anchor";
   }
 
-  const normalized = normalizeRange(anchor.range);
+  const normalized = normalizeRange({ from: anchor.from, to: anchor.to });
   if (normalized.from === normalized.to) {
     return "invalid_comment_anchor";
   }
@@ -164,7 +164,7 @@ export function snapCommentAnchorAwayFromTable(
 ): ReviewAnchor | null {
   if (anchor.kind !== "range") return null;
 
-  const normalized = normalizeRange(anchor.range);
+  const normalized = normalizeRange({ from: anchor.from, to: anchor.to });
   if (normalized.from === normalized.to) return null;
 
   // If the anchor is already flagged invalid for other reasons (crosses an

package/src/io/export/export-session.ts

@@ -119,6 +119,7 @@ export class ExportSession {
       this.packageRelationships,
       this.ownedPaths,
     );
+    ensurePicNamespaceOnStoryParts(this.workingParts);
     const parts = pruneReservedManifestParts(this.workingParts);
     const manifest = buildManifest(parts, this.packageRelationships, this.sourcePackage.manifest.contentTypes);
     return {
@@ -140,6 +141,58 @@ export function createExportSession(
   return new ExportSession(sourcePackage, ownedOutputPaths);
 }
 
+/**
+ * LibreOffice strict-parser safety net. Word tolerates `pic:` prefix
+ * usage (from `<pic:pic>` / `<pic:spPr>` inside drawings) without
+ * declaring `xmlns:pic` at the part root, because it inherits scope
+ * from `<wp:inline xmlns:pic=…>` wrappers or from `mc:AlternateContent`
+ * fallbacks. LibreOffice refuses the file ("Namespace prefix pic on
+ * spPr is not defined"). Our own serializers already inject
+ * `xmlns:pic` on freshly serialized parts — but parts that pass
+ * through unmodified from the source package keep the original
+ * declaration (which may be missing it). This sweep runs at toPackage
+ * time over the main story + every header / footer part, and injects
+ * `xmlns:pic` on the root element when the part uses the `pic:` prefix
+ * but doesn't declare it. Byte-stable for parts already correct.
+ *
+ * See commit a3e05a8e (serializer-side fix) + this (pass-through fix).
+ */
+const PIC_NAMESPACE_URI = "http://schemas.openxmlformats.org/drawingml/2006/picture";
+const PIC_NAMESPACE_DECL = ` xmlns:pic="${PIC_NAMESPACE_URI}"`;
+
+function ensurePicNamespaceOnStoryParts(
+  parts: Map<string, OpcPackagePart>,
+): void {
+  for (const [path, part] of parts.entries()) {
+    if (!isPicSensitiveStoryPath(path)) continue;
+    const patched = ensurePicNamespaceOnRoot(part.bytes);
+    if (patched !== part.bytes) {
+      parts.set(path, { ...part, bytes: patched, crc32: 0 });
+    }
+  }
+}
+
+function isPicSensitiveStoryPath(path: string): boolean {
+  // Normalize for leading slash variation.
+  const normalized = path.startsWith("/") ? path.slice(1) : path;
+  if (normalized === "word/document.xml") return true;
+  if (/^word\/(?:header|footer|footnotes|endnotes)[^/]*\.xml$/.test(normalized)) return true;
+  return false;
+}
+
+function ensurePicNamespaceOnRoot(bytes: Uint8Array): Uint8Array {
+  const xml = new TextDecoder().decode(bytes);
+  // Match the first element (skipping the XML prolog + whitespace).
+  const rootMatch = xml.match(/^([\s\S]*?)<([A-Za-z][\w.:-]*)([^>]*)>/);
+  if (!rootMatch) return bytes;
+  const [fullMatch, prefix, tagName, rootAttrs] = rootMatch;
+  if (rootAttrs.includes("xmlns:pic=")) return bytes; // already declared
+  if (!/\bpic:[A-Za-z]/.test(xml)) return bytes; // doesn't use pic: prefix
+  const patchedRoot = `<${tagName}${rootAttrs}${PIC_NAMESPACE_DECL}>`;
+  const patched = `${prefix}${patchedRoot}${xml.slice(fullMatch.length)}`;
+  return new TextEncoder().encode(patched);
+}
+
 function clonePartsForExport(
   parts: Map<string, OpcPackagePart>,
   ownedPaths: ReadonlySet<string>,

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

@@ -269,16 +269,16 @@ export function serializeCommentAnchorsIntoDocumentXml(
       continue;
     }
 
-    const startParagraph = findParagraphForEndpoint(paragraphs, anchor.range.from, "start");
-    const endParagraph = findParagraphForEndpoint(paragraphs, anchor.range.to, "end");
+    const startParagraph = findParagraphForEndpoint(paragraphs, anchor.from, "start");
+    const endParagraph = findParagraphForEndpoint(paragraphs, anchor.to, "end");
 
     if (!startParagraph || !endParagraph) {
       skippedCommentIds.push(thread.commentId);
       continue;
     }
 
-    const startIndex = startParagraph.boundaries.get(anchor.range.from);
-    const endIndex = endParagraph.boundaries.get(anchor.range.to);
+    const startIndex = startParagraph.boundaries.get(anchor.from);
+    const endIndex = endParagraph.boundaries.get(anchor.to);
 
     if (startIndex === undefined || endIndex === undefined) {
       skippedCommentIds.push(thread.commentId);

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

@@ -135,8 +135,8 @@ function createParagraphPropertyChangeReplacement(
   }
   const paragraphBoundary = findParagraphBoundaryForRange(
     boundaries,
-    revision.anchor.range.from,
-    revision.anchor.range.to,
+    revision.anchor.from,
+    revision.anchor.to,
   );
   if (!paragraphBoundary) {
     return undefined;
@@ -168,14 +168,14 @@ function createRunPropertyChangeReplacement(
   }
   const paragraphBoundary = findParagraphBoundaryForRange(
     boundaries,
-    revision.anchor.range.from,
-    revision.anchor.range.to,
+    revision.anchor.from,
+    revision.anchor.to,
   );
   if (!paragraphBoundary) {
     return undefined;
   }
-  const startIndex = paragraphBoundary.boundaries.get(revision.anchor.range.from);
-  const endIndex = paragraphBoundary.boundaries.get(revision.anchor.range.to);
+  const startIndex = paragraphBoundary.boundaries.get(revision.anchor.from);
+  const endIndex = paragraphBoundary.boundaries.get(revision.anchor.to);
   if (startIndex === undefined || endIndex === undefined || endIndex < startIndex) {
     return undefined;
   }
@@ -245,13 +245,13 @@ function createRangeRevisionReplacement(
   if (anchor.kind !== "range") {
     return undefined;
   }
-  const paragraphBoundary = findParagraphBoundaryForRange(boundaries, anchor.range.from, anchor.range.to);
+  const paragraphBoundary = findParagraphBoundaryForRange(boundaries, anchor.from, anchor.to);
   if (!paragraphBoundary) {
     return undefined;
   }
 
-  const startIndex = paragraphBoundary.boundaries.get(anchor.range.from);
-  const endIndex = paragraphBoundary.boundaries.get(anchor.range.to);
+  const startIndex = paragraphBoundary.boundaries.get(anchor.from);
+  const endIndex = paragraphBoundary.boundaries.get(anchor.to);
   if (startIndex === undefined || endIndex === undefined || endIndex < startIndex) {
     return undefined;
   }
@@ -340,7 +340,7 @@ function findParagraphBoundaryForAnchor(
   boundaries: readonly RevisionParagraphBoundary[],
   revision: RevisionRecord,
 ): RevisionParagraphBoundary | undefined {
-  const anchor = revision.anchor.kind === "range" ? revision.anchor.range.from : undefined;
+  const anchor = revision.anchor.kind === "range" ? revision.anchor.from : undefined;
   if (anchor === undefined) {
     return undefined;
   }

package/src/io/export/split-review-boundaries.ts

@@ -35,8 +35,8 @@ function collectSplitPositions(
       continue;
     }
 
-    positions.add(thread.anchor.range.from);
-    positions.add(thread.anchor.range.to);
+    positions.add(thread.anchor.from);
+    positions.add(thread.anchor.to);
   }
 
   for (const revision of revisions) {
@@ -51,8 +51,8 @@ function collectSplitPositions(
       continue;
     }
 
-    positions.add(revision.anchor.range.from);
-    positions.add(revision.anchor.range.to);
+    positions.add(revision.anchor.from);
+    positions.add(revision.anchor.to);
   }
 
   return positions;

package/src/io/export/split-story-blocks-for-runtime-revisions.ts

@@ -200,8 +200,8 @@ function collectSplitPoints(
 ): number[] {
   const points = new Set<number>();
   for (const revision of revisions) {
-    const from = revision.anchor.range.from;
-    const to = revision.anchor.range.to;
+    const from = revision.anchor.from;
+    const to = revision.anchor.to;
     if (from > start && from < end) {
       points.add(from);
     }

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

@@ -652,9 +652,9 @@ function extractNodeText(node: XmlNode): string {
 
 function compareThreadsByAnchor(left: CommentThread, right: CommentThread): number {
   const leftStart =
-    left.anchor.kind === "range" ? left.anchor.range.from : Number.MAX_SAFE_INTEGER;
+    left.anchor.kind === "range" ? left.anchor.from : Number.MAX_SAFE_INTEGER;
   const rightStart =
-    right.anchor.kind === "range" ? right.anchor.range.from : Number.MAX_SAFE_INTEGER;
+    right.anchor.kind === "range" ? right.anchor.from : Number.MAX_SAFE_INTEGER;
 
   if (leftStart !== rightStart) {
     return leftStart - rightStart;

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

@@ -17,6 +17,7 @@ import { resolveHighlightColor } from "./highlight-colors.ts";
 import type { ParseDrawingOpts } from "./parse-drawing.ts";
 import { parseFFDataFromFldChar } from "./parse-ffdata.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
+import { isSafeTableFieldInstruction } from "./table-opaque-preservation.ts";
 import { parseXmlWithOffsets as parseXml } from "./xml-parser.ts";
 import { localName, readStringAttr } from "./xml-attr-helpers.ts";
 import {
@@ -1018,8 +1019,12 @@ function containsRiskyElement(element: XmlElementNode): boolean {
       const instruction =
         readStringAttr(child, "w:instr") ??
         extractTextContent(child);
-      const classification = classifyFieldInstruction(instruction);
-      if (!isSafeSecondaryStoryFieldFamily(classification.family)) {
+      // Coord-01 §11 unification (2026-04-24): the field-safety check
+      // is delegated to the shared `isSafeTableFieldInstruction` helper
+      // so body-direct + secondary-story tables apply the same
+      // allowlist. Legacy form fields (FORMTEXT/FORMCHECKBOX/
+      // FORMDROPDOWN) now pass here just like in main-story tables.
+      if (!isSafeTableFieldInstruction(instruction)) {
         return true;
       }
       continue;
@@ -1041,17 +1046,6 @@ function containsRiskyElement(element: XmlElementNode): boolean {
   return false;
 }
 
-function isSafeSecondaryStoryFieldFamily(family: string): boolean {
-  return (
-    family === "REF" ||
-    family === "PAGEREF" ||
-    family === "NOTEREF" ||
-    family === "TOC" ||
-    family === "PAGE" ||
-    family === "NUMPAGES"
-  );
-}
-
 function parseSimpleTableElement(
   tblElement: XmlElementNode,
   sourceXml: string,

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

@@ -41,6 +41,7 @@ import { parseShapeXml, parseVmlXml } from "./parse-shapes.ts";
 import { parseObject } from "./parse-object.ts";
 import { parseDrawingFrame } from "./parse-drawing.ts";
 import { readFrameProperties } from "./parse-paragraph-formatting.ts";
+import { tableRequiresOpaquePreservation } from "./table-opaque-preservation.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
 import { parseFFDataFromFldChar } from "./parse-ffdata.ts";
 import { resolveHighlightColor } from "./highlight-colors.ts";
@@ -2020,37 +2021,12 @@ function readCellCnfStyle(node: XmlElementNode): string | undefined {
  * Tables matching this check stay opaque until the respective features
  * are implemented in the table editing path.
  */
-function tableRequiresOpaquePreservation(rawXml: string): boolean {
-  // Safe table-local content now includes hyperlinks, bookmarks, comments,
-  // nested tables, floating images, VML preview atoms, and bounded field
-  // families already owned by the current field slice. Risky table-local
-  // semantics still fail closed to preserve-only.
-  if (/<w:(ins|del|rPrChange|pPrChange|tblPrChange|trPrChange|tcPrChange|sectPrChange|cellIns|cellDel|cellMerge|smartTag)\b/.test(rawXml)) {
-    return true;
-  }
-
-  const simpleInstructions = [...rawXml.matchAll(/\bw:instr="([^"]*)"/g)].map((match) => match[1] ?? "");
-  const complexInstructions = extractComplexFieldInstructions(rawXml);
-  for (const instruction of [...simpleInstructions, ...complexInstructions]) {
-    const classification = classifyFieldInstruction(instruction);
-    if (!isSafeMainStoryTableFieldFamily(classification.family)) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-function isSafeMainStoryTableFieldFamily(family: string): boolean {
-  return (
-    family === "REF" ||
-    family === "PAGEREF" ||
-    family === "NOTEREF" ||
-    family === "TOC" ||
-    family === "PAGE" ||
-    family === "NUMPAGES"
-  );
-}
+// `tableRequiresOpaquePreservation` now lives in
+// `src/io/ooxml/table-opaque-preservation.ts` as a shared helper used by
+// `parse-main-document.ts`, `parse-headers-footers.ts`, and
+// `parse-footnotes.ts`. Unified 2026-04-24 per coord-01 §11 to stop the
+// three parsers from drifting out of alignment. The top-of-file import
+// `tableRequiresOpaquePreservation` points at that module.
 
 function extractComplexFieldInstructions(rawXml: string): string[] {
   const tokenPattern =