@beyondwork/docx-react-component 1.0.21 → 1.0.23

package/src/io/docx-session.ts

@@ -403,6 +403,10 @@ export function loadDocxEditorSession(
       normalizedDocument.preservation.opaqueFragments,
       normalizedRevisions.revisions,
     );
+    const subPartOpaqueState = createSubPartOpaqueImportState(
+      normalizedDocument.preservation.opaqueFragments,
+      normalizedDocument.diagnostics.warnings,
+    );
     // ---- Parse sub-parts: headers, footers, footnotes, endnotes, theme ----
     const headerFooterRefs = parseHeaderFooterReferences(sourceDocumentXml);
     const parsedHeaders: HeaderDocument[] = [];
@@ -439,7 +443,13 @@ export function loadDocxEditorSession(
           partPath,
           relationshipId: ref.relationshipId,
           ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-          blocks: parsed.blocks,
+          blocks: normalizeSubPartOpaqueBlocks(
+            parsed.blocks,
+            normalizedDocument.preservation.opaqueFragments,
+            normalizedDocument.diagnostics.warnings,
+            partPath,
+            subPartOpaqueState,
+          ),
         });
         sourceHeaderPaths.push({ partPath, relationshipId: ref.relationshipId });
       } else {
@@ -449,7 +459,13 @@ export function loadDocxEditorSession(
           partPath,
           relationshipId: ref.relationshipId,
           ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-          blocks: parsed.blocks,
+          blocks: normalizeSubPartOpaqueBlocks(
+            parsed.blocks,
+            normalizedDocument.preservation.opaqueFragments,
+            normalizedDocument.diagnostics.warnings,
+            partPath,
+            subPartOpaqueState,
+          ),
         });
         sourceFooterPaths.push({ partPath, relationshipId: ref.relationshipId });
       }
@@ -481,12 +497,28 @@ export function loadDocxEditorSession(
       footnoteCollection = parseFootnotesXml(
         decodeUtf8(sourcePackage.parts.get(footnotesPartPath)?.bytes ?? new Uint8Array()),
       );
+      normalizeFootnoteCollectionOpaqueBlocks(
+        footnoteCollection,
+        "footnote",
+        normalizedDocument.preservation.opaqueFragments,
+        normalizedDocument.diagnostics.warnings,
+        footnotesPartPath,
+        subPartOpaqueState,
+      );
     }
     if (endnotesPartPath) {
       footnoteCollection = parseEndnotesXml(
         decodeUtf8(sourcePackage.parts.get(endnotesPartPath)?.bytes ?? new Uint8Array()),
         footnoteCollection,
       );
+      normalizeFootnoteCollectionOpaqueBlocks(
+        footnoteCollection,
+        "endnote",
+        normalizedDocument.preservation.opaqueFragments,
+        normalizedDocument.diagnostics.warnings,
+        endnotesPartPath,
+        subPartOpaqueState,
+      );
     }
 
     const themeRelationship = documentPart.relationships.find(
@@ -753,6 +785,14 @@ function exportDocxEditorSession(
   const actionableRevisions = currentRevisions.filter(
     (revision) => getRevisionActionability(revision) === "actionable",
   );
+  const secondaryStoryActionableRevisions = actionableRevisions.filter(
+    (revision) => revision.metadata.storyTarget?.kind && revision.metadata.storyTarget.kind !== "main",
+  );
+  if (secondaryStoryActionableRevisions.length > 0) {
+    throw new Error(
+      `DOCX export is blocked because ${secondaryStoryActionableRevisions.length} secondary-story tracked changes cannot yet be serialized safely.`,
+    );
+  }
   const commentThreads = Object.values(
     createCommentStoreFromRuntimeComments(currentDocument.review.comments).threads,
   );
@@ -1096,6 +1136,143 @@ function createImportedCanonicalDocument(input: {
   };
 }
 
+type SubPartOpaqueImportState = {
+  nextFragmentIndex: number;
+  nextWarningIndex: number;
+  nextDiagnosticIndex: number;
+  cursor: number;
+};
+
+function createSubPartOpaqueImportState(
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
+): SubPartOpaqueImportState {
+  const maxByPrefix = (values: Iterable<string>, prefix: string): number => {
+    let max = 0;
+    for (const value of values) {
+      const match = new RegExp(`^${prefix}(\\d+)$`).exec(value);
+      if (!match) {
+        continue;
+      }
+      const parsed = Number.parseInt(match[1] ?? "0", 10);
+      if (Number.isFinite(parsed) && parsed > max) {
+        max = parsed;
+      }
+    }
+    return max;
+  };
+
+  const maxCursor = Object.values(opaqueFragments).reduce(
+    (currentMax, fragment) => Math.max(currentMax, fragment.lastKnownRange?.to ?? 0),
+    0,
+  );
+
+  return {
+    nextFragmentIndex:
+      maxByPrefix(Object.keys(opaqueFragments), "fragment:import-") + 1,
+    nextWarningIndex:
+      maxByPrefix(
+        [
+          ...Object.values(opaqueFragments).map((fragment) => fragment.warningId),
+          ...warnings.map((warning) => warning.warningId),
+        ],
+        "warning:import-",
+      ) + 1,
+    nextDiagnosticIndex:
+      maxByPrefix(warnings.map((warning) => warning.diagnosticId), "diagnostic:import-") + 1,
+    cursor: maxCursor,
+  };
+}
+
+function normalizeSubPartOpaqueBlocks(
+  blocks: BlockNode[],
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
+  packagePartName: string,
+  state: SubPartOpaqueImportState,
+): BlockNode[] {
+  return blocks.map((block) => {
+    if (block.type !== "opaque_block" || typeof block.rawXml !== "string") {
+      return block;
+    }
+    return recordImportedOpaqueBlock(
+      block.rawXml,
+      opaqueFragments,
+      warnings,
+      packagePartName,
+      state,
+    );
+  });
+}
+
+function normalizeFootnoteCollectionOpaqueBlocks(
+  collection: FootnoteCollection | undefined,
+  kind: "footnote" | "endnote",
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
+  packagePartName: string,
+  state: SubPartOpaqueImportState,
+): void {
+  if (!collection) {
+    return;
+  }
+  const notes = kind === "footnote" ? collection.footnotes : collection.endnotes;
+  for (const definition of Object.values(notes)) {
+    definition.blocks = normalizeSubPartOpaqueBlocks(
+      definition.blocks,
+      opaqueFragments,
+      warnings,
+      packagePartName,
+      state,
+    );
+  }
+}
+
+function recordImportedOpaqueBlock(
+  rawXml: string,
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
+  packagePartName: string,
+  state: SubPartOpaqueImportState,
+): BlockNode {
+  const fragmentId = `fragment:import-${state.nextFragmentIndex}`;
+  state.nextFragmentIndex += 1;
+  const warningId = `warning:import-${state.nextWarningIndex}`;
+  state.nextWarningIndex += 1;
+  const diagnosticId = `diagnostic:import-${state.nextDiagnosticIndex}`;
+  state.nextDiagnosticIndex += 1;
+
+  const rangeStart = state.cursor;
+  const rangeEnd = state.cursor + 1;
+  state.cursor = rangeEnd;
+
+  opaqueFragments[fragmentId] = {
+    fragmentId,
+    payloadKind: "xml-subtree",
+    payloadReference: rawXml,
+    featureClass: "preserve-only",
+    lastKnownRange: {
+      from: rangeStart,
+      to: rangeEnd,
+    },
+    warningId,
+    packagePartName,
+  };
+  warnings.push({
+    diagnosticId,
+    warningId,
+    source: "import",
+    message: "Unsupported sub-part OOXML was preserved as an opaque placeholder.",
+  });
+
+  return {
+    type: "opaque_block",
+    fragmentId,
+    warningId,
+    rawXml,
+  };
+}
+
 // Canonical model styleId validation pattern — styleIds that don't match
 // are excluded from the catalog to avoid snapshot validation failures.
 const VALID_STYLE_ID = /^[A-Za-z_][A-Za-z0-9._-]{0,127}$/;
@@ -1785,6 +1962,7 @@ function toRuntimeRevisionRecords(
         warningIds: [...revision.warningIds],
         metadata: {
           source: revision.metadata.source,
+          storyTarget: revision.metadata.storyTarget,
           preserveOnlyReason: revision.metadata.preserveOnlyReason,
           importedRevisionForm: revision.metadata.importedRevisionForm,
           originalRevisionType: revision.metadata.originalRevisionType,
@@ -1808,6 +1986,7 @@ function toReviewRevisionRecords(
     warningIds: [...(revision.warningIds ?? [])],
     metadata: {
       source: revision.metadata?.source ?? "runtime",
+      storyTarget: revision.metadata?.storyTarget,
       preserveOnlyReason: revision.metadata?.preserveOnlyReason,
       importedRevisionForm: revision.metadata?.importedRevisionForm,
       originalRevisionType: revision.metadata?.originalRevisionType,

package/src/io/export/serialize-main-document.ts

@@ -218,7 +218,7 @@ function serializeTableNode(
       : "";
   const rowsXml = table.rows
     .map((row) => {
-      const rowPropertiesXml = row.propertiesXml ?? "";
+      const rowPropertiesXml = row.propertiesXml ?? buildTableRowPropertiesXml(row);
       const cellsXml = row.cells
         .map((cell) => serializeTableCellNode(cell, state))
         .join("");
@@ -280,6 +280,26 @@ function buildCellPropertiesXml(cell: TableCellNode): string {
   return children.length > 0 ? `<w:tcPr>${children.join("")}</w:tcPr>` : "";
 }
 
+function buildTableRowPropertiesXml(row: TableNode["rows"][number]): string {
+  const children: string[] = [];
+  if (row.gridBefore !== undefined) {
+    children.push(`<w:gridBefore w:val="${row.gridBefore}"/>`);
+  }
+  if (row.widthBefore) {
+    children.push(`<w:wBefore w:w="${row.widthBefore.value}" w:type="${row.widthBefore.type}"/>`);
+  }
+  if (row.gridAfter !== undefined) {
+    children.push(`<w:gridAfter w:val="${row.gridAfter}"/>`);
+  }
+  if (row.widthAfter) {
+    children.push(`<w:wAfter w:w="${row.widthAfter.value}" w:type="${row.widthAfter.type}"/>`);
+  }
+  if (children.length === 0) {
+    return "";
+  }
+  return `<w:trPr>${children.join("")}</w:trPr>`;
+}
+
 function serializeSdtNode(
   block: SdtNode,
   state: SerializationState,

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

@@ -211,6 +211,10 @@ function normalizeTableRow(
   return {
     type: "table_row",
     ...(row.propertiesXml ? { propertiesXml: row.propertiesXml } : {}),
+    ...(row.gridBefore !== undefined ? { gridBefore: row.gridBefore } : {}),
+    ...(row.widthBefore ? { widthBefore: row.widthBefore } : {}),
+    ...(row.gridAfter !== undefined ? { gridAfter: row.gridAfter } : {}),
+    ...(row.widthAfter ? { widthAfter: row.widthAfter } : {}),
     cells,
   };
 }

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

@@ -7,6 +7,7 @@ import type {
   ParagraphIndentation,
   TabStop,
   TableLook,
+  TableWidth,
   SectionProperties,
   PageSize,
   PageMargins,
@@ -309,6 +310,10 @@ export interface ParsedTableRowNode {
   type: "table_row";
   propertiesXml?: string;
   cells: ParsedTableCellNode[];
+  gridBefore?: number;
+  widthBefore?: TableWidth;
+  gridAfter?: number;
+  widthAfter?: TableWidth;
   rawXml: string;
 }
 
@@ -843,6 +848,10 @@ function parseTableRowElement(
   sourcePartPath: string,
 ): ParsedTableRowNode {
   let propertiesXml: string | undefined;
+  let gridBefore: number | undefined;
+  let widthBefore: TableWidth | undefined;
+  let gridAfter: number | undefined;
+  let widthAfter: TableWidth | undefined;
   const cells: ParsedTableCellNode[] = [];
 
   for (const child of node.children) {
@@ -851,6 +860,10 @@ function parseTableRowElement(
     switch (localName(child.name)) {
       case "trPr":
         propertiesXml = sourceXml.slice(child.start, child.end);
+        gridBefore = readTableRowGridPosition(child, "gridBefore");
+        widthBefore = readTableRowWidth(child, "wBefore");
+        gridAfter = readTableRowGridPosition(child, "gridAfter");
+        widthAfter = readTableRowWidth(child, "wAfter");
         break;
       case "tc":
         cells.push(parseTableCellElement(child, sourceXml, relationshipMap, relationships, mediaParts, sourcePartPath));
@@ -861,6 +874,10 @@ function parseTableRowElement(
   return {
     type: "table_row",
     ...(propertiesXml ? { propertiesXml } : {}),
+    ...(gridBefore !== undefined ? { gridBefore } : {}),
+    ...(widthBefore ? { widthBefore } : {}),
+    ...(gridAfter !== undefined ? { gridAfter } : {}),
+    ...(widthAfter ? { widthAfter } : {}),
     cells,
     rawXml: sourceXml.slice(node.start, node.end),
   };
@@ -1185,14 +1202,13 @@ function tableRequiresOpaquePreservation(rawXml: string): boolean {
   // 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|gridAfter|gridBefore|tblCellSpacing)\b/.test(rawXml)) {
+  if (/<w:(ins|del|rPrChange|pPrChange|tblPrChange|trPrChange|tcPrChange|sectPrChange|cellIns|cellDel|cellMerge|smartTag|tblCellSpacing)\b/.test(rawXml)) {
     return true;
   }
 
-  const fldSimpleInstructions = [...rawXml.matchAll(/\bw:instr="([^"]*)"/g)].map((match) => match[1] ?? "");
-  const complexInstructions = [...rawXml.matchAll(/<(?:\w+:)?instrText\b[^>]*>([\s\S]*?)<\/(?:\w+:)?instrText>/gu)]
-    .map((match) => decodeXmlEntities(match[1] ?? ""));
-  for (const instruction of [...fldSimpleInstructions, ...complexInstructions]) {
+  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;
@@ -1213,6 +1229,69 @@ function isSafeMainStoryTableFieldFamily(family: string): boolean {
   );
 }
 
+function extractComplexFieldInstructions(rawXml: string): string[] {
+  const tokenPattern =
+    /<(?:\w+:)?fldChar\b[^>]*?(?:\w+:)?fldCharType="(begin|separate|end)"[^>]*?(?:\/>|>[\s\S]*?<\/(?:\w+:)?fldChar>)|<(?:\w+:)?instrText\b[^>]*>([\s\S]*?)<\/(?:\w+:)?instrText>/gu;
+  const instructions: string[] = [];
+  let activeInstruction = "";
+  let capturingInstruction = false;
+
+  for (const match of rawXml.matchAll(tokenPattern)) {
+    const fldCharType = match[1];
+    const instrText = match[2];
+    if (fldCharType === "begin") {
+      activeInstruction = "";
+      capturingInstruction = true;
+      continue;
+    }
+    if (fldCharType === "separate" || fldCharType === "end") {
+      if (capturingInstruction && activeInstruction.trim().length > 0) {
+        instructions.push(activeInstruction);
+      }
+      activeInstruction = "";
+      capturingInstruction = false;
+      continue;
+    }
+    if (capturingInstruction && instrText !== undefined) {
+      activeInstruction += decodeXmlEntities(instrText);
+    }
+  }
+
+  return instructions;
+}
+
+function readTableRowGridPosition(
+  node: XmlElementNode,
+  local: "gridBefore" | "gridAfter",
+): number | undefined {
+  const positionNode = node.children.find(
+    (child): child is XmlElementNode => child.type === "element" && localName(child.name) === local,
+  );
+  if (!positionNode) return undefined;
+  const raw = positionNode.attributes["w:val"] ?? positionNode.attributes.val;
+  const value = Number.parseInt(raw ?? "", 10);
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function readTableRowWidth(
+  node: XmlElementNode,
+  local: "wBefore" | "wAfter",
+): TableWidth | undefined {
+  const widthNode = node.children.find(
+    (child): child is XmlElementNode => child.type === "element" && localName(child.name) === local,
+  );
+  if (!widthNode) return undefined;
+  const rawValue = widthNode.attributes["w:w"] ?? widthNode.attributes.w;
+  const value = Number.parseInt(rawValue ?? "", 10);
+  if (!Number.isFinite(value)) {
+    return undefined;
+  }
+  const rawType = (widthNode.attributes["w:type"] ?? widthNode.attributes.type ?? "dxa").toLowerCase();
+  const type: TableWidth["type"] =
+    rawType === "auto" ? "auto" : rawType === "pct" ? "pct" : rawType === "nil" ? "nil" : "dxa";
+  return { value, type };
+}
+
 function readCellGridSpan(node: XmlElementNode): number | undefined {
   const gridSpanNode = node.children.find(
     (child): child is XmlElementNode => child.type === "element" && localName(child.name) === "gridSpan",
@@ -1801,9 +1880,11 @@ function parseRevisionContainer(
           },
         ];
       case "permStart":
-        return [parsePermStartNode(node, sourceXml)];
+        result.push(parsePermStartNode(child, sourceXml));
+        break;
       case "permEnd":
-        return [parsePermEndNode(node, sourceXml)];
+        result.push(parsePermEndNode(child, sourceXml));
+        break;
       default:
         return [
           {

package/src/model/canonical-document.ts

@@ -417,6 +417,10 @@ export interface TableRowNode {
   type: "table_row";
   propertiesXml?: string;
   cells: TableCellNode[];
+  gridBefore?: number;
+  widthBefore?: TableWidth;
+  gridAfter?: number;
+  widthAfter?: TableWidth;
   height?: number;
   heightRule?: "auto" | "atLeast" | "exact";
   isHeader?: boolean;
@@ -943,6 +947,23 @@ export interface RevisionMoveData {
   direction: "from" | "to";
 }
 
+export type RevisionStoryTargetRecord =
+  | { kind: "main" }
+  | {
+      kind: "header";
+      relationshipId: string;
+      variant: "default" | "first" | "even";
+      sectionIndex?: number;
+    }
+  | {
+      kind: "footer";
+      relationshipId: string;
+      variant: "default" | "first" | "even";
+      sectionIndex?: number;
+    }
+  | { kind: "footnote"; noteId: string }
+  | { kind: "endnote"; noteId: string };
+
 export interface RevisionRecord {
   changeId: string;
   kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
@@ -956,6 +977,7 @@ export interface RevisionRecord {
 
 export interface RevisionMetadataRecord {
   source?: "runtime" | "import";
+  storyTarget?: RevisionStoryTargetRecord;
   preserveOnlyReason?: string;
   importedRevisionForm?:
     | "run-insertion"

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

@@ -81,6 +81,7 @@ export function createRevisionRecord(
     warningIds: [...(params.warningIds ?? [])],
     metadata: {
       source: params.metadata?.source ?? "runtime",
+      storyTarget: params.metadata?.storyTarget,
       preserveOnlyReason:
         params.metadata?.preserveOnlyReason ??
         (getRevisionActionability(params.kind) === "preserve-only"

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

@@ -9,6 +9,7 @@ import {
   type EditorAnchorProjection,
   type TransactionMapping,
 } from "../../core/selection/mapping.ts";
+import type { RevisionStoryTargetRecord } from "../../model/canonical-document.ts";
 
 export type RevisionAnchor = EditorAnchorProjection;
 
@@ -33,6 +34,7 @@ export interface MoveData {
 
 export interface RevisionMetadataEnvelope {
   source: "runtime" | "import";
+  storyTarget?: RevisionStoryTargetRecord;
   preserveOnlyReason?: string;
   importedRevisionForm?:
     | "run-insertion"