@beyondwork/docx-react-component 1.0.18 → 1.0.19

package/src/validation/compatibility-engine.ts

@@ -104,23 +104,13 @@ function collectContentFeatures(
     lists: false,
     hyperlinks: false,
     images: false,
+    tables: false,
+    sections: false,
+    contentControls: false,
   };
 
   for (let index = 0; index < content.children.length; index += 1) {
-    const block = content.children[index];
-    if (block.type !== "paragraph") {
-      continue;
-    }
-
-    flags.paragraphs = true;
-    if (block.styleId?.toLowerCase().startsWith("heading")) {
-      flags.headings = true;
-    }
-    if (block.numbering) {
-      flags.lists = true;
-    }
-
-    measureParagraph(block, flags);
+    measureBlock(content.children[index], flags);
   }
 
   const entries: CompatibilityFeatureEntry[] = [];
@@ -145,16 +135,94 @@ function collectContentFeatures(
   if (flags.images) {
     entries.push(supportedEntry("inline-images", "Inline image placements stay attached to preserved media parts."));
   }
+  if (flags.tables) {
+    entries.push(
+      supportedEntry(
+        "tables",
+        "Structured tables keep cell topology and common visual properties through runtime editing and export.",
+      ),
+    );
+  }
+  if (flags.sections) {
+    entries.push(
+      supportedEntry(
+        "sections",
+        "Section boundaries and page-layout properties remain structured and export-safe.",
+      ),
+    );
+  }
+  if (flags.contentControls) {
+    entries.push(
+      supportedEntry(
+        "content-controls",
+        "Common content controls render through structured SDT state and round-trip without flattening to opaque placeholders.",
+      ),
+    );
+  }
   return entries;
 }
 
+function measureBlock(
+  block: BlockNode,
+  flags: {
+    paragraphs: boolean;
+    runs: boolean;
+    whitespace: boolean;
+    headings: boolean;
+    lists: boolean;
+    hyperlinks: boolean;
+    images: boolean;
+    tables: boolean;
+    sections: boolean;
+    contentControls: boolean;
+  },
+): number {
+  switch (block.type) {
+    case "paragraph":
+      flags.paragraphs = true;
+      if (block.styleId?.toLowerCase().startsWith("heading")) {
+        flags.headings = true;
+      }
+      if (block.numbering) {
+        flags.lists = true;
+      }
+      return measureParagraph(block, flags);
+    case "table":
+      flags.tables = true;
+      return block.rows.reduce(
+        (size, row) =>
+          size +
+          row.cells.reduce(
+            (cellSize, cell) =>
+              cellSize + cell.children.reduce((childSize, child) => childSize + measureBlock(child, flags), 0),
+            0,
+          ),
+        0,
+      );
+    case "sdt":
+      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);
+    case "section_break":
+      flags.sections = true;
+      return 1;
+    default:
+      return 0;
+  }
+}
+
 function measureParagraph(
   paragraph: ParagraphNode,
   flags: {
+    paragraphs: boolean;
     runs: boolean;
     whitespace: boolean;
     hyperlinks: boolean;
     images: boolean;
+    tables: boolean;
+    sections: boolean;
+    contentControls: boolean;
   },
 ): number {
   let size = 0;
@@ -170,10 +238,14 @@ function measureParagraph(
 function measureInlineNode(
   node: InlineNode,
   flags: {
+    paragraphs: boolean;
     runs: boolean;
     whitespace: boolean;
     hyperlinks: boolean;
     images: boolean;
+    tables: boolean;
+    sections: boolean;
+    contentControls: boolean;
   },
 ): number {
   switch (node.type) {
@@ -310,12 +382,12 @@ function collectSubPartFeatures(
     Object.keys(subParts.footnoteCollection?.footnotes ?? {}).length +
     Object.keys(subParts.footnoteCollection?.endnotes ?? {}).length;
 
-  if (hasHeaderFooterContent) {
+  if (hasHeaderFooterContent && !entries.some((entry) => entry.featureKey === "headers-footers-lossy")) {
     entries.push({
       featureEntryId: "feature:subparts:headers-footers",
       featureKey: "headers-footers",
-      featureClass: "preserve-only",
-      message: "Headers and footers are preserved through structured sub-part ownership.",
+      featureClass: "supported-roundtrip",
+      message: "Headers and footers resolve as structured secondary stories with export-safe ownership.",
       details: {
         headerCount: subParts.headers?.length ?? 0,
         footerCount: subParts.footers?.length ?? 0,
@@ -323,12 +395,12 @@ function collectSubPartFeatures(
     });
   }
 
-  if (noteCount > 0) {
+  if (noteCount > 0 && !entries.some((entry) => entry.featureKey === "notes-lossy")) {
     entries.push({
       featureEntryId: "feature:subparts:notes",
       featureKey: "notes",
-      featureClass: "preserve-only",
-      message: "Footnotes and endnotes are preserved through structured sub-part ownership.",
+      featureClass: "supported-roundtrip",
+      message: "Footnotes and endnotes resolve as structured secondary stories with export-safe ownership.",
       details: {
         footnoteCount: Object.keys(subParts.footnoteCollection?.footnotes ?? {}).length,
         endnoteCount: Object.keys(subParts.footnoteCollection?.endnotes ?? {}).length,

package/src/validation/diagnostics.ts

@@ -48,6 +48,7 @@ export const EDITOR_ERROR_SOURCES = [
   "runtime",
   "validation",
   "datastore",
+  "host",
   "export",
 ] as const;
 

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

@@ -0,0 +1,487 @@
+import type {
+  CompatibilityReport,
+  DocumentNavigationSnapshot,
+  RuntimeRenderSnapshot,
+} from "../api/public-types.ts";
+import { parseCommentsFromOoxml } from "../io/ooxml/parse-comments.ts";
+import { readOpcPackage } from "../io/opc/package-reader.ts";
+
+export interface ClosureValidationContext {
+  renderSnapshot: Pick<
+    RuntimeRenderSnapshot,
+    | "isReady"
+    | "fatalError"
+    | "comments"
+    | "trackedChanges"
+    | "surface"
+    | "pageLayout"
+  >;
+  navigation?: Pick<DocumentNavigationSnapshot, "pages">;
+  compatibility: Pick<CompatibilityReport, "errors" | "featureEntries">;
+  surface: RuntimeRenderSnapshot["surface"];
+}
+
+export type ClosureValidationCheck =
+  | { type: "mustLoad" }
+  | { type: "compatibilityFeature"; featureKey: string; featureClass: string }
+  | { type: "minTrackedChanges"; count: number }
+  | { type: "maxTrackedChanges"; count: number }
+  | { type: "minCommentThreads"; count: number }
+  | { type: "lockedFragmentCountAtLeast"; count: number }
+  | { type: "surfaceBlockKind"; kind: string; count?: number }
+  | { type: "opaqueBlockLabelPrefix"; value: string }
+  | { type: "opaqueInlineLabelPrefix"; value: string }
+  | {
+      type: "secondaryStoryMatch";
+      kind: "header" | "footer" | "footnote" | "endnote";
+      relationshipId?: string;
+      variant?: "default" | "first" | "even";
+      noteId?: string;
+      minBlockCount?: number;
+    }
+  | {
+      type: "pageLayoutMatch";
+      sectionIndex?: number;
+      orientation?: "portrait" | "landscape";
+      columns?: number;
+      differentFirstPage?: boolean;
+      differentOddEvenPages?: boolean;
+      headerVariantCountAtLeast?: number;
+      footerVariantCountAtLeast?: number;
+    }
+  | {
+      type: "commentThreadMatch";
+      commentId?: string;
+      status?: "open" | "resolved" | "detached";
+      entryCount?: number;
+      anchorKind?: "range" | "node" | "detached";
+      bodyIncludes?: string[];
+      entryBodies?: string[];
+      entryAuthorIds?: string[];
+      authorId?: string;
+    };
+
+export interface ClosureValidationResult {
+  type: string;
+  passed: boolean;
+  reason: string;
+}
+
+export interface DocxCommentProof {
+  partPresence: {
+    commentsXml: boolean;
+    commentsExtendedXml: boolean;
+    commentsIdsXml: boolean;
+    peopleXml: boolean;
+  };
+  serializedCommentIds: string[];
+  peopleAuthors: string[];
+  threads: Array<{
+    commentId: string;
+    rootCommentId?: string;
+    status: "open" | "resolved" | "detached";
+    entryCount: number;
+    bodies: string[];
+    authorIds: string[];
+    anchorKind: "range" | "node" | "detached";
+  }>;
+}
+
+export function evaluateClosureCheck(
+  check: ClosureValidationCheck,
+  context: ClosureValidationContext,
+): ClosureValidationResult {
+  switch (check.type) {
+    case "mustLoad":
+      return {
+        type: check.type,
+        passed:
+          context.renderSnapshot.isReady &&
+          context.renderSnapshot.fatalError === undefined &&
+          context.compatibility.errors.length === 0,
+        reason: "exported artifact did not reload into a healthy runtime",
+      };
+    case "compatibilityFeature": {
+      const passed = context.compatibility.featureEntries.some(
+        (entry) =>
+          entry.featureKey === check.featureKey &&
+          entry.featureClass === check.featureClass,
+      );
+      return {
+        type: check.type,
+        passed,
+        reason: `missing compatibility feature ${check.featureKey}:${check.featureClass}`,
+      };
+    }
+    case "minTrackedChanges":
+      return {
+        type: check.type,
+        passed: context.renderSnapshot.trackedChanges.totalCount >= check.count,
+        reason: `expected at least ${check.count} tracked changes`,
+      };
+    case "maxTrackedChanges":
+      return {
+        type: check.type,
+        passed: context.renderSnapshot.trackedChanges.totalCount <= check.count,
+        reason: `expected at most ${check.count} tracked changes`,
+      };
+    case "minCommentThreads":
+      return {
+        type: check.type,
+        passed: context.renderSnapshot.comments.totalCount >= check.count,
+        reason: `expected at least ${check.count} comment threads`,
+      };
+    case "lockedFragmentCountAtLeast":
+      return {
+        type: check.type,
+        passed: (context.surface?.lockedFragmentIds.length ?? 0) >= check.count,
+        reason: `expected at least ${check.count} locked fragments`,
+      };
+    case "surfaceBlockKind":
+      return {
+        type: check.type,
+        passed:
+          (context.surface?.blocks.filter((block) => block.kind === check.kind).length ?? 0) >=
+          (check.count ?? 1),
+        reason: `expected at least ${check.count ?? 1} surface blocks of kind ${check.kind}`,
+      };
+    case "opaqueBlockLabelPrefix":
+      return {
+        type: check.type,
+        passed:
+          context.surface?.blocks.some(
+            (block) =>
+              block.kind === "opaque_block" &&
+              typeof block.label === "string" &&
+              block.label.startsWith(check.value),
+          ) ?? false,
+        reason: `expected an opaque block label starting with ${check.value}`,
+      };
+    case "opaqueInlineLabelPrefix":
+      return {
+        type: check.type,
+        passed: hasOpaqueInlineLabelPrefix(context.surface, check.value),
+        reason: `expected an opaque inline label starting with ${check.value}`,
+      };
+    case "secondaryStoryMatch": {
+      const passed =
+        context.surface?.secondaryStories.some((story) => {
+          if (story.target.kind !== check.kind) {
+            return false;
+          }
+          if (
+            "relationshipId" in story.target &&
+            check.relationshipId &&
+            story.target.relationshipId !== check.relationshipId
+          ) {
+            return false;
+          }
+          if ("variant" in story.target && check.variant && story.target.variant !== check.variant) {
+            return false;
+          }
+          if ("noteId" in story.target && check.noteId && story.target.noteId !== check.noteId) {
+            return false;
+          }
+          if ((check.minBlockCount ?? 0) > story.blocks.length) {
+            return false;
+          }
+          return true;
+        }) ?? false;
+      return {
+        type: check.type,
+        passed,
+        reason: `expected secondary story ${describeSecondaryStoryMatch(check)}`,
+      };
+    }
+    case "pageLayoutMatch": {
+      const layouts = getLayoutsForCheck(context, check);
+      const headerVariantCount = countUniqueStoryVariants(layouts, "headerVariants");
+      const footerVariantCount = countUniqueStoryVariants(layouts, "footerVariants");
+      const passed = Boolean(
+        layouts.length > 0 &&
+          layouts.some(
+            (layout) =>
+              (check.orientation === undefined || layout.orientation === check.orientation) &&
+              (check.columns === undefined || layout.columns === check.columns) &&
+              (check.differentFirstPage === undefined ||
+                layout.differentFirstPage === check.differentFirstPage) &&
+              (check.differentOddEvenPages === undefined ||
+                layout.differentOddEvenPages === check.differentOddEvenPages),
+          ) &&
+          (check.headerVariantCountAtLeast === undefined ||
+            headerVariantCount >= check.headerVariantCountAtLeast) &&
+          (check.footerVariantCountAtLeast === undefined ||
+            footerVariantCount >= check.footerVariantCountAtLeast)
+      );
+      return {
+        type: check.type,
+        passed,
+        reason: `expected page layout ${describePageLayoutMatch(check)}`,
+      };
+    }
+    case "commentThreadMatch": {
+      const passed = context.renderSnapshot.comments.threads.some((thread) =>
+        matchesCommentThread(thread, check),
+      );
+      return {
+        type: check.type,
+        passed,
+        reason: `expected a comment thread matching ${describeCommentThreadMatch(check)}`,
+      };
+    }
+    default:
+      return {
+        type: (check as { type: string }).type,
+        passed: false,
+        reason: `unknown closure validation check type ${(check as { type: string }).type}`,
+      };
+  }
+}
+
+export function extractDocxCommentProof(bytes: Uint8Array): DocxCommentProof {
+  const packageFile = readOpcPackage(bytes);
+  const documentXml = decodePartText(packageFile.parts.get("/word/document.xml")?.bytes);
+  const commentsXml = decodePartText(packageFile.parts.get("/word/comments.xml")?.bytes);
+  const commentsExtendedXml = decodePartText(
+    packageFile.parts.get("/word/commentsExtended.xml")?.bytes,
+  );
+  const commentsIdsXml = decodePartText(packageFile.parts.get("/word/commentsIds.xml")?.bytes);
+  const peopleXml = decodePartText(packageFile.parts.get("/word/people.xml")?.bytes);
+  const parsedComments =
+    documentXml && commentsXml
+      ? parseCommentsFromOoxml(documentXml, {
+          commentsXml,
+          commentsExtendedXml,
+          commentsIdsXml,
+          peopleXml,
+        })
+      : {
+          threads: [],
+          definitions: [],
+          peopleAuthors: [],
+        };
+
+  return {
+    partPresence: {
+      commentsXml: commentsXml.length > 0,
+      commentsExtendedXml: commentsExtendedXml.length > 0,
+      commentsIdsXml: commentsIdsXml.length > 0,
+      peopleXml: peopleXml.length > 0,
+    },
+    serializedCommentIds: parsedComments.definitions.map((definition) => definition.commentId),
+    peopleAuthors: [...parsedComments.peopleAuthors],
+    threads: parsedComments.threads.map((thread) => ({
+      commentId: thread.commentId,
+      rootCommentId: thread.metadata?.rootOoxmlCommentId,
+      status: thread.status,
+      entryCount: thread.entries.length,
+      bodies: thread.entries.map((entry) => entry.body),
+      authorIds: [...new Set(thread.entries.map((entry) => entry.authorId))],
+      anchorKind: thread.anchor.kind,
+    })),
+  };
+}
+
+function hasOpaqueInlineLabelPrefix(
+  surface: RuntimeRenderSnapshot["surface"],
+  prefix: string,
+): boolean {
+  if (!surface) {
+    return false;
+  }
+
+  for (const block of surface.blocks) {
+    if (block.kind !== "paragraph") {
+      continue;
+    }
+
+    if (
+      block.segments.some(
+        (segment) =>
+          segment.kind === "opaque_inline" &&
+          typeof segment.label === "string" &&
+          segment.label.startsWith(prefix),
+      )
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function matchesCommentThread(
+  thread: RuntimeRenderSnapshot["comments"]["threads"][number],
+  check: Extract<ClosureValidationCheck, { type: "commentThreadMatch" }>,
+): boolean {
+  if (check.commentId && thread.commentId !== check.commentId) {
+    return false;
+  }
+  if (check.status && thread.status !== check.status) {
+    return false;
+  }
+  if (typeof check.entryCount === "number" && thread.entries.length !== check.entryCount) {
+    return false;
+  }
+  if (check.anchorKind && thread.anchor.kind !== check.anchorKind) {
+    return false;
+  }
+  if (check.authorId && thread.createdBy !== check.authorId) {
+    return false;
+  }
+  if (check.bodyIncludes?.length) {
+    const bodies = thread.entries.map((entry) => entry.body);
+    for (const expectedBody of check.bodyIncludes) {
+      if (!bodies.some((body) => body.includes(expectedBody))) {
+        return false;
+      }
+    }
+  }
+  if (check.entryBodies?.length) {
+    if (thread.entries.length < check.entryBodies.length) {
+      return false;
+    }
+    for (let index = 0; index < check.entryBodies.length; index += 1) {
+      const expectedBody = check.entryBodies[index];
+      const actualBody = thread.entries[index]?.body;
+      if (typeof expectedBody !== "string" || actualBody !== expectedBody) {
+        return false;
+      }
+    }
+  }
+  if (check.entryAuthorIds?.length) {
+    if (thread.entries.length < check.entryAuthorIds.length) {
+      return false;
+    }
+    for (let index = 0; index < check.entryAuthorIds.length; index += 1) {
+      const expectedAuthorId = check.entryAuthorIds[index];
+      const actualAuthorId = thread.entries[index]?.authorId;
+      if (typeof expectedAuthorId !== "string" || actualAuthorId !== expectedAuthorId) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+function getLayoutsForCheck(
+  context: ClosureValidationContext,
+  check: Extract<ClosureValidationCheck, { type: "pageLayoutMatch" }>,
+) {
+  const navigationLayouts =
+    context.navigation?.pages
+      .filter((page) => check.sectionIndex === undefined || page.sectionIndex === check.sectionIndex)
+      .map((page) => page.layout) ?? [];
+  if (navigationLayouts.length > 0) {
+    return navigationLayouts;
+  }
+  const activeLayout = context.renderSnapshot.pageLayout;
+  if (
+    activeLayout &&
+    (check.sectionIndex === undefined || activeLayout.sectionIndex === check.sectionIndex)
+  ) {
+    return [activeLayout];
+  }
+  return [];
+}
+
+function countUniqueStoryVariants(
+  layouts: Array<{
+    headerVariants: Array<{ variant: string; relationshipId: string }>;
+    footerVariants: Array<{ variant: string; relationshipId: string }>;
+  }>,
+  key: "headerVariants" | "footerVariants",
+) {
+  const variants = new Set<string>();
+  for (const layout of layouts) {
+    for (const variant of layout[key]) {
+      variants.add(`${variant.variant}:${variant.relationshipId}`);
+    }
+  }
+  return variants.size;
+}
+
+function describeCommentThreadMatch(
+  check: Extract<ClosureValidationCheck, { type: "commentThreadMatch" }>,
+): string {
+  const parts: string[] = [];
+  if (check.commentId) {
+    parts.push(`commentId=${check.commentId}`);
+  }
+  if (check.status) {
+    parts.push(`status=${check.status}`);
+  }
+  if (typeof check.entryCount === "number") {
+    parts.push(`entryCount=${check.entryCount}`);
+  }
+  if (check.anchorKind) {
+    parts.push(`anchorKind=${check.anchorKind}`);
+  }
+  if (check.authorId) {
+    parts.push(`authorId=${check.authorId}`);
+  }
+  if (check.bodyIncludes?.length) {
+    parts.push(`bodyIncludes=${check.bodyIncludes.join(" | ")}`);
+  }
+  if (check.entryBodies?.length) {
+    parts.push(`entryBodies=${check.entryBodies.join(" | ")}`);
+  }
+  if (check.entryAuthorIds?.length) {
+    parts.push(`entryAuthorIds=${check.entryAuthorIds.join(" | ")}`);
+  }
+  return parts.length > 0 ? parts.join(", ") : "any thread";
+}
+
+function describeSecondaryStoryMatch(
+  check: Extract<ClosureValidationCheck, { type: "secondaryStoryMatch" }>,
+): string {
+  const parts = [`kind=${check.kind}`];
+  if (check.relationshipId) {
+    parts.push(`relationshipId=${check.relationshipId}`);
+  }
+  if (check.variant) {
+    parts.push(`variant=${check.variant}`);
+  }
+  if (check.noteId) {
+    parts.push(`noteId=${check.noteId}`);
+  }
+  if (typeof check.minBlockCount === "number") {
+    parts.push(`minBlockCount=${check.minBlockCount}`);
+  }
+  return parts.join(", ");
+}
+
+function describePageLayoutMatch(
+  check: Extract<ClosureValidationCheck, { type: "pageLayoutMatch" }>,
+): string {
+  const parts: string[] = [];
+  if (typeof check.sectionIndex === "number") {
+    parts.push(`sectionIndex=${check.sectionIndex}`);
+  }
+  if (check.orientation) {
+    parts.push(`orientation=${check.orientation}`);
+  }
+  if (typeof check.columns === "number") {
+    parts.push(`columns=${check.columns}`);
+  }
+  if (typeof check.differentFirstPage === "boolean") {
+    parts.push(`differentFirstPage=${check.differentFirstPage}`);
+  }
+  if (typeof check.differentOddEvenPages === "boolean") {
+    parts.push(`differentOddEvenPages=${check.differentOddEvenPages}`);
+  }
+  if (typeof check.headerVariantCountAtLeast === "number") {
+    parts.push(`headerVariantCountAtLeast=${check.headerVariantCountAtLeast}`);
+  }
+  if (typeof check.footerVariantCountAtLeast === "number") {
+    parts.push(`footerVariantCountAtLeast=${check.footerVariantCountAtLeast}`);
+  }
+  return parts.length > 0 ? parts.join(", ") : "present";
+}
+
+function decodePartText(bytes: Uint8Array | undefined): string {
+  if (!bytes) {
+    return "";
+  }
+  return new TextDecoder("utf-8").decode(bytes);
+}