@beyondwork/docx-react-component 1.0.28 → 1.0.30

package/src/validation/compatibility-engine.ts

@@ -14,6 +14,7 @@ import type {
 } from "../model/canonical-document.ts";
 import {
   describeOpaqueFragment,
+  describeStructuredWrapperBlock,
   listOpaqueFragments,
   listPreservedPackageParts,
 } from "../preservation/store.ts";
@@ -40,6 +41,8 @@ export function buildCompatibilityReport(
   }
   const featureEntries: CompatibilityFeatureEntry[] = [
     ...contentFeatures,
+    ...collectStructuredWrapperFeatures(content),
+    ...collectReviewFeatures(input.document),
     ...collectPreservationFeatures(input.document),
   ];
   const warnings = dedupeWarnings([
@@ -69,6 +72,110 @@ function hasSupportedRuntimeComments(
   return Object.values(comments).some((comment) => comment.anchor.kind !== "detached");
 }
 
+function collectReviewFeatures(
+  document: CanonicalDocumentEnvelope,
+): CompatibilityFeatureEntry[] {
+  const entries: CompatibilityFeatureEntry[] = [];
+  const comments = Object.values(document.review.comments ?? {});
+  const revisions = Object.values(document.review.revisions ?? {});
+
+  const multiParagraphComment = comments.find(
+    (comment) => comment.metadata?.detachedReason === "multi-paragraph" && comment.anchor.kind === "detached",
+  );
+  if (multiParagraphComment?.anchor.kind === "detached") {
+    entries.push({
+      featureEntryId: "feature:comments-multi-paragraph-ranges",
+      featureKey: "comments-multi-paragraph-ranges",
+      featureClass: "preserve-only",
+      message:
+        "Cross-paragraph comment anchors remain visible but detached to preserve package truth and export safety.",
+      affectedAnchor: createRangeAnchor(
+        multiParagraphComment.anchor.lastKnownRange.from,
+        multiParagraphComment.anchor.lastKnownRange.to,
+      ),
+      details: {
+        commentId: multiParagraphComment.commentId,
+        detachedReason: multiParagraphComment.metadata?.detachedReason,
+        actionabilityNote: multiParagraphComment.metadata?.actionabilityNote,
+      },
+    });
+  }
+
+  const moveRevision = revisions.find((revision) => revision.kind === "move");
+  if (moveRevision) {
+    entries.push({
+      featureEntryId: "feature:tracked-moves",
+      featureKey: "tracked-moves",
+      featureClass: "preserve-only",
+      message:
+        "Tracked move revisions are preserved for round-trip and review visibility but remain non-actionable in the current runtime.",
+      affectedAnchor: toRevisionAffectedAnchor(moveRevision),
+      details: {
+        revisionId: moveRevision.changeId,
+        moveDirection: moveRevision.metadata?.moveData?.direction,
+        linkedRevisionId: moveRevision.metadata?.moveData?.linkedRevisionId,
+      },
+    });
+  }
+
+  const formattingRevisions = revisions.filter(
+    (revision) =>
+      revision.kind === "formatting" ||
+      (revision.kind === "property-change" && revision.metadata?.propertyChangeData?.xmlTag === "rPrChange"),
+  );
+  if (formattingRevisions.length > 0) {
+    const featureClass = formattingRevisions.some(
+      (revision) => typeof revision.metadata?.preserveOnlyReason === "string" && revision.metadata.preserveOnlyReason.length > 0,
+    )
+      ? "preserve-only"
+      : "supported-roundtrip";
+    entries.push({
+      featureEntryId: "feature:formatting-revisions",
+      featureKey: "formatting-revisions",
+      featureClass,
+      message:
+        featureClass === "preserve-only"
+          ? "Formatting revisions remain visible for review, but at least one formatting-change slice is still preserve-only."
+          : "Formatting-change revisions remain structured and round-trip through the runtime review model.",
+      affectedAnchor: toRevisionAffectedAnchor(formattingRevisions[0]!),
+      details: {
+        revisionCount: formattingRevisions.length,
+      },
+    });
+  }
+
+  const structuralRevisions = revisions.filter(
+    (revision) =>
+      revision.kind === "property-change" &&
+      revision.metadata?.propertyChangeData?.xmlTag !== "rPrChange",
+  );
+  if (structuralRevisions.length > 0) {
+    const featureClass = structuralRevisions.some(
+      (revision) => typeof revision.metadata?.preserveOnlyReason === "string" && revision.metadata.preserveOnlyReason.length > 0,
+    )
+      ? "preserve-only"
+      : "supported-roundtrip";
+    entries.push({
+      featureEntryId: "feature:structural-revisions",
+      featureKey: "structural-revisions",
+      featureClass,
+      message:
+        featureClass === "preserve-only"
+          ? "Structural property revisions are preserved for round-trip, but at least one slice remains non-actionable."
+          : "Structured paragraph, table, or section property revisions remain mapped in the runtime review model.",
+      affectedAnchor: toRevisionAffectedAnchor(structuralRevisions[0]!),
+      details: {
+        revisionCount: structuralRevisions.length,
+        revisionKinds: structuralRevisions.map(
+          (revision) => revision.metadata?.propertyChangeData?.xmlTag ?? revision.kind,
+        ),
+      },
+    });
+  }
+
+  return entries;
+}
+
 function normalizeDocumentRoot(content: unknown): DocumentRootNode {
   if (content && typeof content === "object" && (content as { type?: string }).type === "doc") {
     return content as DocumentRootNode;
@@ -105,6 +212,7 @@ function collectContentFeatures(
     hyperlinks: false,
     images: false,
     tables: false,
+    mergedCells: false,
     sections: false,
     contentControls: false,
   };
@@ -139,7 +247,15 @@ function collectContentFeatures(
     entries.push(
       supportedEntry(
         "tables",
-        "Structured tables keep cell topology and common visual properties through runtime editing and export.",
+        "Structured tables keep bounded topology and common visual properties through runtime editing and export.",
+      ),
+    );
+  }
+  if (flags.mergedCells) {
+    entries.push(
+      supportedEntry(
+        "merged-cells",
+        "Merged-cell topology survives through the supported table runtime and export path.",
       ),
     );
   }
@@ -173,6 +289,7 @@ function measureBlock(
     hyperlinks: boolean;
     images: boolean;
     tables: boolean;
+    mergedCells: boolean;
     sections: boolean;
     contentControls: boolean;
   },
@@ -189,6 +306,13 @@ function measureBlock(
       return measureParagraph(block, flags);
     case "table":
       flags.tables = true;
+      if (
+        block.rows.some((row) =>
+          row.cells.some((cell) => (cell.gridSpan ?? 1) > 1 || cell.verticalMerge != null),
+        )
+      ) {
+        flags.mergedCells = true;
+      }
       return block.rows.reduce(
         (size, row) =>
           size +
@@ -200,10 +324,15 @@ function measureBlock(
         0,
       );
     case "sdt":
+      if (describeStructuredWrapperBlock(block)?.featureKey === "content-controls") {
+        return 1;
+      }
       flags.contentControls = true;
       return block.children.reduce((size, child) => size + measureBlock(child, flags), 0);
     case "custom_xml":
-      return block.children.reduce((size, child) => size + measureBlock(child, flags), 0);
+      return 1;
+    case "alt_chunk":
+      return 1;
     case "section_break":
       flags.sections = true;
       return 1;
@@ -212,6 +341,54 @@ function measureBlock(
   }
 }
 
+function collectStructuredWrapperFeatures(
+  content: DocumentRootNode,
+): CompatibilityFeatureEntry[] {
+  const entries: CompatibilityFeatureEntry[] = [];
+  let structuredWrapperIndex = 0;
+
+  function visitBlock(block: BlockNode): void {
+    const descriptor = describeStructuredWrapperBlock(block);
+    if (descriptor) {
+      entries.push({
+        featureEntryId: `feature:structured-wrapper:${structuredWrapperIndex}`,
+        featureKey: descriptor.featureKey,
+        featureClass: "preserve-only",
+        message: descriptor.label,
+        details: {
+          detail: descriptor.detail,
+          surface: "structured-wrapper",
+        },
+      });
+      structuredWrapperIndex += 1;
+      return;
+    }
+
+    if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          for (const child of cell.children) {
+            visitBlock(child);
+          }
+        }
+      }
+      return;
+    }
+
+    if (block.type === "sdt") {
+      for (const child of block.children) {
+        visitBlock(child);
+      }
+    }
+  }
+
+  for (const block of content.children) {
+    visitBlock(block);
+  }
+
+  return entries;
+}
+
 function measureParagraph(
   paragraph: ParagraphNode,
   flags: {
@@ -381,6 +558,16 @@ function collectSubPartFeatures(
   const noteCount =
     Object.keys(subParts.footnoteCollection?.footnotes ?? {}).length +
     Object.keys(subParts.footnoteCollection?.endnotes ?? {}).length;
+  const headerFooterBookmarkCount =
+    [...(subParts.headers ?? []), ...(subParts.footers ?? [])].reduce(
+      (count, subPart) => count + countBookmarksInBlocks(subPart.blocks),
+      0,
+    );
+  const noteBookmarkCount =
+    [
+      ...Object.values(subParts.footnoteCollection?.footnotes ?? {}),
+      ...Object.values(subParts.footnoteCollection?.endnotes ?? {}),
+    ].reduce((count, note) => count + countBookmarksInBlocks(note.blocks), 0);
 
   if (hasHeaderFooterContent && !entries.some((entry) => entry.featureKey === "headers-footers-lossy")) {
     entries.push({
@@ -391,6 +578,7 @@ function collectSubPartFeatures(
       details: {
         headerCount: subParts.headers?.length ?? 0,
         footerCount: subParts.footers?.length ?? 0,
+        bookmarkCount: headerFooterBookmarkCount,
       },
     });
   }
@@ -404,6 +592,7 @@ function collectSubPartFeatures(
       details: {
         footnoteCount: Object.keys(subParts.footnoteCollection?.footnotes ?? {}).length,
         endnoteCount: Object.keys(subParts.footnoteCollection?.endnotes ?? {}).length,
+        bookmarkCount: noteBookmarkCount,
       },
     });
   }
@@ -472,6 +661,45 @@ function collectLossySubPartFeatures(
   return entries;
 }
 
+function countBookmarksInBlocks(blocks: readonly BlockNode[]): number {
+  return blocks.reduce((count, block) => count + countBookmarksInBlock(block), 0);
+}
+
+function countBookmarksInBlock(block: BlockNode): number {
+  switch (block.type) {
+    case "paragraph":
+      return (block.children ?? []).reduce((count, child) => count + countBookmarksInInlineNode(child), 0);
+    case "table":
+      return block.rows.reduce(
+        (count, row) =>
+          count +
+          row.cells.reduce(
+            (cellCount, cell) =>
+              cellCount + cell.children.reduce((childCount, child) => childCount + countBookmarksInBlock(child), 0),
+            0,
+          ),
+        0,
+      );
+    case "sdt":
+    case "custom_xml":
+      return block.children.reduce((count, child) => count + countBookmarksInBlock(child), 0);
+    default:
+      return 0;
+  }
+}
+
+function countBookmarksInInlineNode(node: InlineNode): number {
+  switch (node.type) {
+    case "bookmark_start":
+      return 1;
+    case "hyperlink":
+    case "field":
+      return (node.children ?? []).reduce((count, child) => count + countBookmarksInInlineNode(child), 0);
+    default:
+      return 0;
+  }
+}
+
 function collectLossyBlocks(
   blocks: readonly BlockNode[],
   surface: string,
@@ -613,6 +841,22 @@ function supportedEntry(
   };
 }
 
+function toRevisionAffectedAnchor(
+  revision: CanonicalDocumentEnvelope["review"]["revisions"][string],
+) {
+  switch (revision.anchor.kind) {
+    case "range":
+      return createRangeAnchor(revision.anchor.range.from, revision.anchor.range.to);
+    case "node":
+      return createRangeAnchor(revision.anchor.at, revision.anchor.at + 1);
+    case "detached":
+      return createRangeAnchor(
+        revision.anchor.lastKnownRange.from,
+        revision.anchor.lastKnownRange.to,
+      );
+  }
+}
+
 function dedupeWarnings(warnings: EditorWarning[]): EditorWarning[] {
   const byId = new Map<string, EditorWarning>();
 

package/src/validation/docx-comment-proof.ts

@@ -26,18 +26,31 @@ export interface ClosureValidationContext {
   harnessShowcase?: HarnessShowcaseValidationContext;
 }
 
+export const HARNESS_SHOWCASE_AREAS = [
+  "workflow-overlay",
+  "blocked-commands",
+  "preserve-only",
+  "search-candidates",
+  "right-rail",
+  "multi-scope",
+  "public-api",
+  "sidebar-integration",
+  "policy-yaml",
+  "harness-lifecycle",
+  "export-continuity",
+  "main-story-text",
+  "paragraph-structure",
+  "secondary-story-text",
+  "formatting-property-list",
+  "table-field-slices",
+  "fail-closed-boundaries",
+  "media-section-fail-closed",
+  "continuity-proof",
+  "harness-suggestion-telemetry",
+] as const;
+
 export type HarnessShowcaseArea =
-  | "workflow-overlay"
-  | "blocked-commands"
-  | "preserve-only"
-  | "search-candidates"
-  | "right-rail"
-  | "multi-scope"
-  | "public-api"
-  | "sidebar-integration"
-  | "policy-yaml"
-  | "harness-lifecycle"
-  | "export-continuity";
+  (typeof HARNESS_SHOWCASE_AREAS)[number];
 
 export interface HarnessShowcaseAreaProof {
   demonstrated: boolean;