@beyondwork/docx-react-component 1.0.36 → 1.0.38

package/src/core/selection/mapping.ts

@@ -51,6 +51,12 @@ export interface TransactionMapping {
     affectsComments?: boolean;
     affectsRevisions?: boolean;
     affectsOpaqueFragments?: boolean;
+    /**
+     * Review-tag touches performed during this transaction. Used by the
+     * predicted-text lane's reconciler to classify acks as `adjusted` vs
+     * `structural-divergence` without re-walking the document.
+     */
+    scopeTagTouches?: readonly import("../../api/public-types.ts").ScopeTagTouch[];
     [key: string]: unknown;
   };
 }

package/src/io/docx-session.ts

@@ -67,6 +67,7 @@ import {
   createBrokenRelationshipIssue,
   createMissingPartIssue,
 } from "./opc/corrupt-package.ts";
+import { buildAppPropertiesXml } from "./export/build-app-properties-xml.ts";
 import { createExportSession } from "./export/export-session.ts";
 import { serializeMainDocument } from "./export/serialize-main-document.ts";
 import {
@@ -2909,10 +2910,31 @@ function serializeCanonicalDocumentForExport(document: CanonicalDocumentEnvelope
   });
 }
 
+/**
+ * Read a Node-style environment variable without referencing the Node-only
+ * `process` global in the production build (which excludes @types/node).
+ * Returns `undefined` in browser environments or when the var is unset.
+ */
+function readNodeEnvVar(name: string): string | undefined {
+  const proc = (globalThis as unknown as {
+    process?: { env?: Record<string, string | undefined> };
+  }).process;
+  return proc?.env?.[name];
+}
+
 function canReuseSourceBytesForCurrentDocument(
   state: ImportedDocxState,
   document: CanonicalDocumentEnvelope,
 ): boolean {
+  // The validator-loop CI harness (§1 / §7) needs to exercise the full
+  // serializer pipeline — including A.1 / A.2 / A.3 / A.6 / A.7 / A.8 /
+  // A.9 fixes — so it sets DOCX_VALIDATOR_FORCE_REGEN=1 to disable the
+  // fast-path byte-reuse. Never set this flag in production; it forces a
+  // full XML regeneration on every export and is only used by the CCEP
+  // validator harness to prove our serializer's correctness.
+  if (readNodeEnvVar("DOCX_VALIDATOR_FORCE_REGEN") === "1") {
+    return false;
+  }
   if (requiresHostMetadataNormalization(state.sourcePackage, state.sourceDocumentPartPath)) {
     return false;
   }
@@ -3108,15 +3130,8 @@ function buildCorePropertiesXml(document: CanonicalDocumentEnvelope): string {
   ].join("\n");
 }
 
-function buildAppPropertiesXml(): string {
-  return [
-    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
-    `<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties" xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes">`,
-    `  <Application>React OOXML Office</Application>`,
-    `  <AppVersion>1.0</AppVersion>`,
-    `</Properties>`,
-  ].join("\n");
-}
+// buildAppPropertiesXml moved to src/io/export/build-app-properties-xml.ts
+// per close-render-fidelity §2 A.5. Re-import as `buildAppPropertiesXmlFn`.
 
 function xmlNode(tagName: string, value: string | undefined): string | undefined {
   if (typeof value !== "string" || value.length === 0) {

package/src/io/export/build-app-properties-xml.ts

@@ -0,0 +1,88 @@
+/**
+ * build-app-properties-xml — synthesises `/docProps/app.xml` for the export.
+ *
+ * Mirrors `buildCorePropertiesXml` (in `docx-session.ts`) but targets the
+ * `extended-properties` namespace. Emitted once per export when the source
+ * package does not already carry a valid app.xml part with the correct
+ * content type.
+ *
+ * Required by:
+ *   docs/plans/close-render-fidelity.md §2 A.5
+ *
+ * Schema shape (ECMA-376 Part 1, Office Extended properties):
+ *   <Properties xmlns="…/extended-properties" xmlns:vt="…/docPropsVTypes">
+ *     <Application>@beyondwork/docx-react-component/<pkg.version></Application>
+ *     <AppVersion>1.0</AppVersion>
+ *     <Pages>0</Pages>
+ *     <Words>0</Words>
+ *     <Characters>0</Characters>
+ *     <Lines>0</Lines>
+ *     <Paragraphs>0</Paragraphs>
+ *   </Properties>
+ *
+ * Zero counts are acceptable per the ECMA schema — Word-authoritative counts
+ * are recomputed at open time by the hosting application. A future §4 pass
+ * can replace these with canonical-derived counts without changing the XML
+ * shape.
+ */
+
+import { PACKAGE_VERSION } from "../../api/package-version.ts";
+
+export const APP_PROPERTIES_NAMESPACE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties";
+export const APP_PROPERTIES_VT_NAMESPACE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes";
+
+export interface AppPropertiesStats {
+  /** Rendered page count; zero is a valid placeholder. */
+  pages?: number;
+  /** Word count. */
+  words?: number;
+  /** Character count. */
+  characters?: number;
+  /** Line count. */
+  lines?: number;
+  /** Paragraph count. */
+  paragraphs?: number;
+  /** App-version string override; defaults to the package version. */
+  appVersion?: string;
+  /** Application identifier override; defaults to package.json name@version. */
+  application?: string;
+}
+
+export function buildAppPropertiesXml(
+  stats: AppPropertiesStats = {},
+): string {
+  const application = stats.application ?? defaultApplicationLabel();
+  const appVersion = stats.appVersion ?? PACKAGE_VERSION;
+  const pages = stats.pages ?? 0;
+  const words = stats.words ?? 0;
+  const characters = stats.characters ?? 0;
+  const lines = stats.lines ?? 0;
+  const paragraphs = stats.paragraphs ?? 0;
+
+  return [
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
+    `<Properties xmlns="${APP_PROPERTIES_NAMESPACE}" xmlns:vt="${APP_PROPERTIES_VT_NAMESPACE}">`,
+    `  <Application>${escapeXml(application)}</Application>`,
+    `  <AppVersion>${escapeXml(appVersion)}</AppVersion>`,
+    `  <Pages>${Math.max(0, Math.round(pages))}</Pages>`,
+    `  <Words>${Math.max(0, Math.round(words))}</Words>`,
+    `  <Characters>${Math.max(0, Math.round(characters))}</Characters>`,
+    `  <Lines>${Math.max(0, Math.round(lines))}</Lines>`,
+    `  <Paragraphs>${Math.max(0, Math.round(paragraphs))}</Paragraphs>`,
+    `</Properties>`,
+  ].join("\n");
+}
+
+function defaultApplicationLabel(): string {
+  return `@beyondwork/docx-react-component/${PACKAGE_VERSION}`;
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;")
+    .replace(/"/gu, "&quot;");
+}

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

@@ -64,8 +64,13 @@ export interface SerializedCommentDocumentResult {
   skippedCommentIds: string[];
 }
 
+// A.8: emit root attributes in deterministic order (xmlns:* alphabetised,
+// then mc:Ignorable, then other attrs). The sort above happens to produce
+// the same token order `mc < w < w14` + `mc:Ignorable` — keep the literal
+// in sync with renderDeterministicRootAttributes so regenerated docs and
+// comments.xml samples match byte-for-byte when snapshots compare them.
 const DEFAULT_COMMENTS_ROOT_TAG =
-  `<w:comments xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" mc:Ignorable="w14">`;
+  `<w:comments xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" mc:Ignorable="w14">`;
 const DEFAULT_COMMENTS_EXTENDED_ROOT_TAG =
   `<w15:commentsEx xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml">`;
 const DEFAULT_COMMENTS_IDS_ROOT_TAG =

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

@@ -16,6 +16,7 @@ import {
   serializeTablePropertiesXml,
   serializeTableRowPropertiesXml,
 } from "./table-properties-xml.ts";
+import { twip } from "./twip.ts";
 
 export const WORD_FOOTNOTES_CONTENT_TYPE =
   "application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml";
@@ -142,7 +143,7 @@ function serializeTable(table: TableNode): string {
   if (table.gridColumns.length > 0) {
     xml += "<w:tblGrid>";
     for (const width of table.gridColumns) {
-      xml += `<w:gridCol w:w="${width}"/>`;
+      xml += `<w:gridCol w:w="${twip(width)}"/>`;
     }
     xml += "</w:tblGrid>";
   }
@@ -194,9 +195,9 @@ function buildParagraphPropertiesXml(paragraph: ParagraphNode): string {
   }
   if (paragraph.spacing) {
     const attrs: string[] = [];
-    if (paragraph.spacing.before !== undefined) attrs.push(`w:before="${paragraph.spacing.before}"`);
-    if (paragraph.spacing.after !== undefined) attrs.push(`w:after="${paragraph.spacing.after}"`);
-    if (paragraph.spacing.line !== undefined) attrs.push(`w:line="${paragraph.spacing.line}"`);
+    if (paragraph.spacing.before !== undefined) attrs.push(`w:before="${twip(paragraph.spacing.before)}"`);
+    if (paragraph.spacing.after !== undefined) attrs.push(`w:after="${twip(paragraph.spacing.after)}"`);
+    if (paragraph.spacing.line !== undefined) attrs.push(`w:line="${twip(paragraph.spacing.line)}"`);
     if (paragraph.spacing.lineRule) attrs.push(`w:lineRule="${escapeAttribute(paragraph.spacing.lineRule)}"`);
     if (attrs.length > 0) {
       parts.push(`<w:spacing ${attrs.join(" ")}/>`);
@@ -204,10 +205,10 @@ function buildParagraphPropertiesXml(paragraph: ParagraphNode): string {
   }
   if (paragraph.indentation) {
     const attrs: string[] = [];
-    if (paragraph.indentation.left !== undefined) attrs.push(`w:left="${paragraph.indentation.left}"`);
-    if (paragraph.indentation.right !== undefined) attrs.push(`w:right="${paragraph.indentation.right}"`);
-    if (paragraph.indentation.firstLine !== undefined) attrs.push(`w:firstLine="${paragraph.indentation.firstLine}"`);
-    if (paragraph.indentation.hanging !== undefined) attrs.push(`w:hanging="${paragraph.indentation.hanging}"`);
+    if (paragraph.indentation.left !== undefined) attrs.push(`w:left="${twip(paragraph.indentation.left)}"`);
+    if (paragraph.indentation.right !== undefined) attrs.push(`w:right="${twip(paragraph.indentation.right)}"`);
+    if (paragraph.indentation.firstLine !== undefined) attrs.push(`w:firstLine="${twip(paragraph.indentation.firstLine)}"`);
+    if (paragraph.indentation.hanging !== undefined) attrs.push(`w:hanging="${twip(paragraph.indentation.hanging)}"`);
     if (attrs.length > 0) {
       parts.push(`<w:ind ${attrs.join(" ")}/>`);
     }
@@ -330,7 +331,7 @@ function buildRunPropertiesXml(marks: TextMark[] | undefined): string {
         );
         break;
       case "fontSize":
-        parts.push(`<w:sz w:val="${mark.val}"/>`);
+        parts.push(`<w:sz w:val="${twip(mark.val)}"/>`);
         break;
       case "textColor":
         parts.push(`<w:color w:val="${escapeAttribute(mark.color)}"/>`);

package/src/io/export/serialize-headers-footers.ts

@@ -16,6 +16,7 @@ import {
   serializeTablePropertiesXml,
   serializeTableRowPropertiesXml,
 } from "./table-properties-xml.ts";
+import { twip } from "./twip.ts";
 
 export const WORD_HEADER_CONTENT_TYPE =
   "application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml";
@@ -132,7 +133,7 @@ function serializeTable(table: TableNode): string {
   if (table.gridColumns.length > 0) {
     xml += "<w:tblGrid>";
     for (const width of table.gridColumns) {
-      xml += `<w:gridCol w:w="${width}"/>`;
+      xml += `<w:gridCol w:w="${twip(width)}"/>`;
     }
     xml += "</w:tblGrid>";
   }
@@ -182,19 +183,19 @@ function buildParagraphPropertiesXml(paragraph: ParagraphNode): string {
   if (paragraph.spacing) {
     const s = paragraph.spacing;
     const attrs: string[] = [];
-    if (s.before !== undefined) attrs.push(`w:before="${s.before}"`);
-    if (s.after !== undefined) attrs.push(`w:after="${s.after}"`);
-    if (s.line !== undefined) attrs.push(`w:line="${s.line}"`);
+    if (s.before !== undefined) attrs.push(`w:before="${twip(s.before)}"`);
+    if (s.after !== undefined) attrs.push(`w:after="${twip(s.after)}"`);
+    if (s.line !== undefined) attrs.push(`w:line="${twip(s.line)}"`);
     if (s.lineRule) attrs.push(`w:lineRule="${escapeAttribute(s.lineRule)}"`);
     if (attrs.length > 0) parts.push(`<w:spacing ${attrs.join(" ")}/>`);
   }
   if (paragraph.indentation) {
     const ind = paragraph.indentation;
     const attrs: string[] = [];
-    if (ind.left !== undefined) attrs.push(`w:left="${ind.left}"`);
-    if (ind.right !== undefined) attrs.push(`w:right="${ind.right}"`);
-    if (ind.firstLine !== undefined) attrs.push(`w:firstLine="${ind.firstLine}"`);
-    if (ind.hanging !== undefined) attrs.push(`w:hanging="${ind.hanging}"`);
+    if (ind.left !== undefined) attrs.push(`w:left="${twip(ind.left)}"`);
+    if (ind.right !== undefined) attrs.push(`w:right="${twip(ind.right)}"`);
+    if (ind.firstLine !== undefined) attrs.push(`w:firstLine="${twip(ind.firstLine)}"`);
+    if (ind.hanging !== undefined) attrs.push(`w:hanging="${twip(ind.hanging)}"`);
     if (attrs.length > 0) parts.push(`<w:ind ${attrs.join(" ")}/>`);
   }
   if (paragraph.alignment) {
@@ -203,7 +204,7 @@ function buildParagraphPropertiesXml(paragraph: ParagraphNode): string {
   if (paragraph.tabStops && paragraph.tabStops.length > 0) {
     const tabsXml = paragraph.tabStops.map((tab) => {
       const leaderAttr = tab.leader ? ` w:leader="${escapeAttribute(tab.leader)}"` : "";
-      return `<w:tab w:val="${tab.align}" w:pos="${tab.position}"${leaderAttr}/>`;
+      return `<w:tab w:val="${tab.align}" w:pos="${twip(tab.position)}"${leaderAttr}/>`;
     }).join("");
     parts.push(`<w:tabs>${tabsXml}</w:tabs>`);
   }
@@ -303,7 +304,7 @@ function buildRunPropertiesXml(marks: TextMark[] | undefined): string {
         parts.push(`<w:rFonts w:ascii="${escapeAttribute(mark.val)}" w:hAnsi="${escapeAttribute(mark.val)}"/>`);
         break;
       case "fontSize":
-        parts.push(`<w:sz w:val="${mark.val}"/>`);
+        parts.push(`<w:sz w:val="${twip(mark.val)}"/>`);
         break;
       case "textColor":
         parts.push(`<w:color w:val="${escapeAttribute(mark.color)}"/>`);