@beyondwork/docx-react-component 1.0.73 → 1.0.75

package/src/io/ooxml/table-opaque-preservation.ts

@@ -0,0 +1,171 @@
+/**
+ * Unified table-opaque-preservation predicate — shared across
+ * `parse-main-document.ts`, `parse-headers-footers.ts`, and
+ * `parse-footnotes.ts` so the three parsers agree on which tables can
+ * be promoted to the typed `TableNode` shape and which must fall back
+ * to `opaque_block` for lossless rawXml round-trip.
+ *
+ * ## History
+ *
+ * Before this module existed, each of the three parsers maintained its
+ * own divergent allowlist. That divergence drove the coord-01 §11
+ * finding (2026-04-24): legacy form fields (`FORMTEXT`,
+ * `FORMCHECKBOX`, `FORMDROPDOWN`) classify as `UNKNOWN` under
+ * `FIELD_FAMILY_PATTERN` (which targets data-field families), so both
+ * the main-story and secondary-story table predicates rejected them
+ * even though the body-direct paragraph parser path (via
+ * `parseFFDataFromFldChar`) handles them correctly. The result was
+ * 58 cell paragraphs lost on APS Short Form because 2 body-direct
+ * tables flattened to opaque_block; 5 additional footer tables on
+ * the same doc also flatten (those carry `DOCPROPERTY` — a real data
+ * field, distinct from the legacy form-field case).
+ *
+ * ## Contract
+ *
+ * A `<w:tbl>` is "safe to parse as structured" iff NONE of the
+ * following are true:
+ *
+ * 1. **Revision markup.** `<w:ins>`, `<w:del>`, `<w:moveFrom>`,
+ *    `<w:moveTo>`, `<w:rPrChange>`, `<w:pPrChange>`,
+ *    `<w:tblPrChange>`, `<w:trPrChange>`, `<w:tcPrChange>`,
+ *    `<w:sectPrChange>`, `<w:cellIns>`, `<w:cellDel>`,
+ *    `<w:cellMerge>`, `<w:smartTag>`.
+ *    Rationale: tracked-change-aware table editing isn't implemented;
+ *    flattening preserves fidelity until it is.
+ *
+ * 2. **Field instruction outside the safe set.** Scan every
+ *    `w:instr` simple-field attribute + every `<w:instrText>` inside
+ *    a complex field (`<w:fldChar>begin</w:fldChar>...end`) and
+ *    classify via `classifyFieldInstruction`. If the classified
+ *    family isn't in `SAFE_TABLE_FIELD_FAMILIES` AND the instruction
+ *    isn't a legacy form field (`isLegacyFormFieldInstruction`), the
+ *    table flattens. The legacy-form-field short-circuit is the
+ *    coord-01 §11 fix — those tokens are fully supported by the cell
+ *    paragraph parser but classify as `UNKNOWN`.
+ *
+ * Extending this contract is a cross-layer architectural decision:
+ * widening `SAFE_TABLE_FIELD_FAMILIES` lets more tables parse as
+ * structured but commits the edit-command layer (L06/L08) to handle
+ * each field family's cell-level edit semantics. Keep this list
+ * aligned with the field families supported by the runtime
+ * formatting + scope-command pipeline.
+ */
+
+import { classifyFieldInstruction } from "./parse-fields.ts";
+
+/**
+ * Field families safe enough to leave a `<w:tbl>` in structured
+ * canonical form. Widening this set commits L06 / L08 to cell-level
+ * edit semantics for that family — don't expand opportunistically.
+ */
+export const SAFE_TABLE_FIELD_FAMILIES: ReadonlySet<string> = new Set([
+  "REF",
+  "PAGEREF",
+  "NOTEREF",
+  "TOC",
+  "PAGE",
+  "NUMPAGES",
+]);
+
+/**
+ * Revision + structural markup that forces table flattening.
+ */
+const RISKY_TABLE_MARKUP_RE =
+  /<w:(ins|del|moveFrom|moveTo|rPrChange|pPrChange|tblPrChange|trPrChange|tcPrChange|sectPrChange|cellIns|cellDel|cellMerge|smartTag)\b/;
+
+const SIMPLE_FIELD_INSTR_RE = /\bw:instr="([^"]*)"/g;
+
+const COMPLEX_FIELD_TOKEN_RE =
+  /<(?:\w+:)?fldChar\b[^>]*?(?:\w+:)?fldCharType="(begin|separate|end)"[^>]*?(?:\/>|>[\s\S]*?<\/(?:\w+:)?fldChar>)|<(?:\w+:)?instrText\b[^>]*>([\s\S]*?)<\/(?:\w+:)?instrText>/gu;
+
+/**
+ * Decode the minimal set of XML entities that can appear inside an
+ * `instrText` payload. `classifyFieldInstruction` consumes the raw
+ * instruction text, so we normalize `&amp;` / `&quot;` / `&lt;` /
+ * `&gt;` / `&apos;` before handing it off. Matches the pre-existing
+ * behavior in `parse-main-document.ts::extractComplexFieldInstructions`.
+ */
+function decodeXmlEntities(text: string): string {
+  return text
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+/**
+ * Extract every complex-field instruction (`<w:fldChar
+ * fldCharType="begin">...<w:instrText>...</w:instrText>...</w:fldChar
+ * fldCharType="end">`) as a single concatenated instruction string.
+ * Mirrors `parse-main-document.ts::extractComplexFieldInstructions`.
+ */
+export function extractComplexFieldInstructionsFromRaw(rawXml: string): string[] {
+  const instructions: string[] = [];
+  let active = "";
+  let capturing = false;
+  for (const match of rawXml.matchAll(COMPLEX_FIELD_TOKEN_RE)) {
+    const [, fldCharType, instrText] = match;
+    if (fldCharType === "begin") {
+      active = "";
+      capturing = true;
+      continue;
+    }
+    if (fldCharType === "separate" || fldCharType === "end") {
+      if (capturing && active.trim().length > 0) instructions.push(active);
+      active = "";
+      capturing = false;
+      continue;
+    }
+    if (capturing && instrText !== undefined) active += decodeXmlEntities(instrText);
+  }
+  return instructions;
+}
+
+/**
+ * Legacy form fields (ECMA-376 §17.16.21) — `FORMTEXT`, `FORMCHECKBOX`,
+ * `FORMDROPDOWN`. These are fully supported by the body-direct
+ * paragraph parser via `parseFFDataFromFldChar` but classify as
+ * `UNKNOWN` under `FIELD_FAMILY_PATTERN` (which targets data-field
+ * families like REF / TOC / MERGEFIELD). Short-circuiting them lets
+ * form-field cells stay in structured canonical tables instead of
+ * flattening the entire table to `opaque_block`. Coord-01 §11, 2026-04-24.
+ */
+export function isLegacyFormFieldInstruction(instruction: string): boolean {
+  return /^\s*(FORMTEXT|FORMCHECKBOX|FORMDROPDOWN)\b/i.test(instruction);
+}
+
+/**
+ * Decides whether a single field instruction (either `w:instr`
+ * attribute value or concatenated `instrText` run) is safe for
+ * structured-table parsing. Used by the shared predicate below;
+ * exposed for direct callers (the debug diagnostics script runs
+ * this to classify source instructions alongside the canonical).
+ */
+export function isSafeTableFieldInstruction(instruction: string): boolean {
+  if (isLegacyFormFieldInstruction(instruction)) return true;
+  const family = classifyFieldInstruction(instruction).family;
+  return SAFE_TABLE_FIELD_FAMILIES.has(family);
+}
+
+/**
+ * Shared `<w:tbl>` opaque-preservation predicate. Returns `true`
+ * when the table must fall back to `opaque_block` for lossless
+ * round-trip, `false` when `parseTable` / `parseSimpleTableElement`
+ * can promote it to a structured `TableNode`.
+ *
+ * Callers (`parse-main-document.ts`, `parse-headers-footers.ts`,
+ * `parse-footnotes.ts`) pass the raw XML of the `<w:tbl>` element.
+ */
+export function tableRequiresOpaquePreservation(rawXml: string): boolean {
+  if (RISKY_TABLE_MARKUP_RE.test(rawXml)) return true;
+
+  const simpleInstructions = [...rawXml.matchAll(SIMPLE_FIELD_INSTR_RE)].map(
+    (match) => match[1] ?? "",
+  );
+  const complexInstructions = extractComplexFieldInstructionsFromRaw(rawXml);
+  for (const instruction of [...simpleInstructions, ...complexInstructions]) {
+    if (!isSafeTableFieldInstruction(instruction)) return true;
+  }
+  return false;
+}

package/src/model/anchor.ts

@@ -25,9 +25,17 @@ export interface BoundaryAssoc {
   end: Assoc;
 }
 
+/**
+ * Range anchor — flat shape `{ kind: "range", from, to, assoc }` after the
+ * 2026-04-23 flat-wins collapse. Prior to the collapse this carried a nested
+ * `{ range: DocRange, assoc }` shape. See `canonical-document.ts` CanonicalAnchor
+ * for the matching canonical shape + `repairCanonicalDocumentEnvelope` for the
+ * persisted-snapshot legacy-to-flat migration.
+ */
 export interface RangeAnchor {
   kind: "range";
-  range: DocRange;
+  from: Position;
+  to: Position;
   assoc: BoundaryAssoc;
 }
 

package/src/model/canonical-document.ts

@@ -2013,7 +2013,8 @@ export interface BoundaryAssoc {
 export type CanonicalAnchor =
   | {
       kind: "range";
-      range: DocRange;
+      from: number;
+      to: number;
       assoc: BoundaryAssoc;
     }
   | {
@@ -2329,7 +2330,7 @@ export function repairCanonicalDocumentEnvelope(
     review:
       record.review === undefined
         ? base.review
-        : (record.review as CanonicalDocument["review"]),
+        : (migrateLegacyReviewAnchors(record.review) as CanonicalDocument["review"]),
     preservation:
       record.preservation === undefined
         ? base.preservation
@@ -2355,6 +2356,67 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
+/**
+ * Schema-compat shim for the 2026-04-23 flat-wins anchor collapse. Legacy
+ * persisted snapshots carry range anchors as `{kind: "range", range: {from, to},
+ * assoc}`. Rewrite those to the flat shape `{kind: "range", from, to, assoc}`
+ * on rehydration so old snapshots continue to load.
+ */
+export function migrateLegacyReviewAnchors(review: unknown): unknown {
+  if (!isPlainRecord(review)) {
+    return review;
+  }
+  const migrated: Record<string, unknown> = { ...review };
+  if (isPlainRecord(review.comments)) {
+    migrated.comments = Object.fromEntries(
+      Object.entries(review.comments).map(([id, record]) => [
+        id,
+        migrateReviewRecordAnchor(record),
+      ]),
+    );
+  }
+  if (isPlainRecord(review.revisions)) {
+    migrated.revisions = Object.fromEntries(
+      Object.entries(review.revisions).map(([id, record]) => [
+        id,
+        migrateReviewRecordAnchor(record),
+      ]),
+    );
+  }
+  return migrated;
+}
+
+function migrateReviewRecordAnchor(record: unknown): unknown {
+  if (!isPlainRecord(record)) {
+    return record;
+  }
+  const anchor = record.anchor;
+  if (!isPlainRecord(anchor) || anchor.kind !== "range") {
+    return record;
+  }
+  if (typeof anchor.from === "number" && typeof anchor.to === "number") {
+    return record;
+  }
+  const nested = anchor.range;
+  if (
+    isPlainRecord(nested) &&
+    typeof nested.from === "number" &&
+    typeof nested.to === "number"
+  ) {
+    const { range: _range, ...rest } = anchor;
+    void _range;
+    return {
+      ...record,
+      anchor: {
+        ...rest,
+        from: nested.from,
+        to: nested.to,
+      },
+    };
+  }
+  return record;
+}
+
 export function serializeCanonicalDocument(document: CanonicalDocument): string {
   assertCanonicalDocument(document);
   return stableStringify(document);
@@ -3507,7 +3569,18 @@ function validateAnchor(
   }
 
   if (kind === "range") {
-    validateRange(record.range, `${path}.range`, issues);
+    if (typeof record.from !== "number") {
+      issues.push({
+        path: `${path}.from`,
+        message: "range anchor from must be a number.",
+      });
+    }
+    if (typeof record.to !== "number") {
+      issues.push({
+        path: `${path}.to`,
+        message: "range anchor to must be a number.",
+      });
+    }
     validateBoundaryAssoc(record.assoc, `${path}.assoc`, issues);
   } else if (kind === "node") {
     if (typeof record.at !== "number") {

package/src/preservation/store.ts

@@ -170,6 +170,15 @@ export function describeStructuredWrapperBlock(
       };
     }
     if (block.properties.sdtType === "docPartObj") {
+      // coord-02 §11 P0 — a Template content control that wraps a
+      // drawing_frame (CCEP header logos, cover hero photos) must stay
+      // recursable so surface-projection emits the inner image segment.
+      // Collapsing to opaque_block here silently drops every image
+      // inside a docPartObj SDT. Only collapse when the content is
+      // genuinely wrapper-heavy with no user-visible media.
+      if (sdtContainsDrawingFrame(block)) {
+        return null;
+      }
       return {
         featureKey: "content-controls",
         label: "Template content control",
@@ -220,6 +229,21 @@ function createDetail(fragment: OpaqueFragmentRecord): string {
     : "Preserved whole-unit to keep unsupported OOXML intact.";
 }
 
+function sdtContainsDrawingFrame(block: Extract<BlockNode, { type: "sdt" }>): boolean {
+  const visit = (node: unknown): boolean => {
+    if (!node || typeof node !== "object") return false;
+    const n = node as { type?: string; children?: readonly unknown[] };
+    if (n.type === "drawing_frame") return true;
+    if (Array.isArray(n.children)) {
+      for (const child of n.children) {
+        if (visit(child)) return true;
+      }
+    }
+    return false;
+  };
+  return block.children.some(visit);
+}
+
 function isTocContentControl(block: Extract<BlockNode, { type: "sdt" }>): boolean {
   const searchText = [
     block.properties.alias,

package/src/review/store/comment-anchors.ts

@@ -47,7 +47,7 @@ export function summarizeCommentAnchor(anchor: CommentAnchor): CommentAnchorSumm
     return {
       anchor,
       state: "active",
-      range: normalizeRange(anchor.range),
+      range: normalizeRange({ from: anchor.from, to: anchor.to }),
     };
   }
 

package/src/review/store/comment-remapping.ts

@@ -98,7 +98,7 @@ function normalizeCommentAnchor(
 
   if (
     mappedAnchor.kind === "range" &&
-    !rangeStaysWithinCommentableStory(nextContent, mappedAnchor.range)
+    !rangeStaysWithinCommentableStory(nextContent, { from: mappedAnchor.from, to: mappedAnchor.to })
   ) {
     return detachReviewAnchor(previousRange, "invalidatedByStructureChange");
   }

package/src/review/store/revision-actions.ts

@@ -153,8 +153,8 @@ export function applyRevisionAction(
 
   const story = parseTextStory(options.document.content);
   const range = normalizeRange(
-    revision.anchor.range.from,
-    revision.anchor.range.to,
+    revision.anchor.from,
+    revision.anchor.to,
   );
 
   if (range.to > story.size) {
@@ -811,8 +811,8 @@ function resolveParagraphMarkDeletionRange(
 
   const paragraphs = mapParagraphRanges(story);
   const anchorPosition = normalizeRange(
-    revision.anchor.range.from,
-    revision.anchor.range.to,
+    revision.anchor.from,
+    revision.anchor.to,
   ).from;
   const paragraph = paragraphs.find(
     (candidate) =>

package/src/review/store/revision-types.ts

@@ -77,7 +77,7 @@ export function summarizeRevisionAnchor(anchor: RevisionAnchor): RevisionAnchorS
     return {
       anchor,
       state: "active",
-      range: normalizeRange(anchor.range),
+      range: normalizeRange({ from: anchor.from, to: anchor.to }),
     };
   }
 

package/src/review/store/scope-tag-diff.ts

@@ -96,7 +96,7 @@ export function collectScopeTagTouches(
 
 function anchorRange(anchor: CanonicalAnchor): { from: number; to: number } {
   if (anchor.kind === "range") {
-    return { from: anchor.range.from, to: anchor.range.to };
+    return { from: anchor.from, to: anchor.to };
   }
   if (anchor.kind === "node") {
     return { from: anchor.at, to: anchor.at };

package/src/runtime/collab/map-local-selection-on-remote-replay.ts

@@ -88,10 +88,10 @@ export function mapLocalSelectionOnRemoteReplay(
 
   if (active.kind === "range") {
     const directionForward = selection.anchor <= selection.head;
-    const isCollapsed = active.range.from === active.range.to;
+    const isCollapsed = active.from === active.to;
 
     if (isCollapsed) {
-      const collapsedAt = mapPosition(active.range.from, 1, mapping).position;
+      const collapsedAt = mapPosition(active.from, 1, mapping).position;
       return {
         anchor: collapsedAt,
         head: collapsedAt,
@@ -107,7 +107,7 @@ export function mapLocalSelectionOnRemoteReplay(
     const mapped = mapAnchor(active, mapping);
 
     if (mapped.kind === "range") {
-      const { from, to } = mapped.range;
+      const { from, to } = mapped;
       return {
         anchor: directionForward ? from : to,
         head: directionForward ? to : from,
@@ -122,7 +122,7 @@ export function mapLocalSelectionOnRemoteReplay(
     // positions that land inside a deleted span to `step.from +
     // insertSize`, which is the correct logical "where the selection
     // used to start" position.
-    const collapsedAt = mapPosition(active.range.from, 1, mapping).position;
+    const collapsedAt = mapPosition(active.from, 1, mapping).position;
     return {
       anchor: collapsedAt,
       head: collapsedAt,
@@ -147,9 +147,9 @@ export function mapLocalSelectionOnRemoteReplay(
     }
     if (mapped.kind === "range") {
       return {
-        anchor: mapped.range.from,
-        head: mapped.range.to,
-        isCollapsed: mapped.range.from === mapped.range.to,
+        anchor: mapped.from,
+        head: mapped.to,
+        isCollapsed: mapped.from === mapped.to,
         activeRange: mapped,
       };
     }