@beyondwork/docx-react-component 1.0.36 → 1.0.37

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

@@ -3,6 +3,7 @@ import {
   isSyntheticDocxNullAbstractDefinition,
   isSyntheticDocxNullNumberingInstance,
 } from "../ooxml/numbering-sentinels.ts";
+import { twip } from "./twip.ts";
 
 export const WORD_NUMBERING_CONTENT_TYPE =
   "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml";
@@ -48,14 +49,18 @@ export function serializeParagraphNumberingProperties(
     return "";
   }
 
-  return `<w:numPr><w:ilvl w:val="${numbering.level}"/><w:numId w:val="${escapeAttribute(
-    stripCanonicalPrefix(numbering.numberingInstanceId, "num:"),
+  return `<w:numPr><w:ilvl w:val="${clampIlvl(numbering.level)}"/><w:numId w:val="${escapeAttribute(
+    clampNonNegativeIdString(
+      stripCanonicalPrefix(numbering.numberingInstanceId, "num:"),
+    ),
   )}"/></w:numPr>`;
 }
 
 function serializeAbstractDefinition(definition: NumberingCatalog["abstractDefinitions"][string]): string {
   const abstractNumId = escapeAttribute(
-    stripCanonicalPrefix(definition.abstractNumberingId, "abstract-num:"),
+    clampNonNegativeIdString(
+      stripCanonicalPrefix(definition.abstractNumberingId, "abstract-num:"),
+    ),
   );
   const levels = [...definition.levels]
     .sort((left, right) => left.level - right.level)
@@ -69,7 +74,10 @@ function serializeLevel(
   level: NumberingCatalog["abstractDefinitions"][string]["levels"][number],
   serializedLevel = level.level,
 ): string {
-  const start = level.startAt !== undefined ? `<w:start w:val="${level.startAt}"/>` : "";
+  const start =
+    level.startAt !== undefined
+      ? `<w:start w:val="${clampStart(level.startAt)}"/>`
+      : "";
   const paragraphStyle = level.paragraphStyleId
     ? `<w:pStyle w:val="${escapeAttribute(level.paragraphStyleId)}"/>`
     : "";
@@ -80,7 +88,7 @@ function serializeLevel(
     : "";
   const paragraphProperties = serializeLevelParagraphGeometry(level.paragraphGeometry);
 
-  return `<w:lvl w:ilvl="${serializedLevel}">${start}<w:numFmt w:val="${escapeAttribute(
+  return `<w:lvl w:ilvl="${clampIlvl(serializedLevel)}">${start}<w:numFmt w:val="${escapeAttribute(
     level.format,
   )}"/><w:lvlText w:val="${escapeAttribute(level.text)}"/>${paragraphStyle}${isLegal}${suffix}${justification}${paragraphProperties}</w:lvl>`;
 }
@@ -93,7 +101,10 @@ function serializeLevelOverride(
     return "";
   }
 
-  const start = level.startAt !== undefined ? `<w:start w:val="${level.startAt}"/>` : "";
+  const start =
+    level.startAt !== undefined
+      ? `<w:start w:val="${clampStart(level.startAt)}"/>`
+      : "";
   const format = level.format ? `<w:numFmt w:val="${escapeAttribute(level.format)}"/>` : "";
   const text = level.text !== undefined
     ? `<w:lvlText w:val="${escapeAttribute(level.text)}"/>`
@@ -101,12 +112,17 @@ function serializeLevelOverride(
   const paragraphStyle = level.paragraphStyleId
     ? `<w:pStyle w:val="${escapeAttribute(level.paragraphStyleId)}"/>`
     : "";
+  // ST_OnOff element (A.3):
+  // - true  → <w:isLgl/>.
+  // - false → <w:isLgl w:val="false"/> (explicit override of a parent
+  //            abstract level that declared legal numbering on).
+  // - undefined → omit.
   const isLegal =
-    level.isLegalNumbering === undefined
-      ? ""
-      : level.isLegalNumbering
-        ? "<w:isLgl/>"
-        : `<w:isLgl w:val="0"/>`;
+    level.isLegalNumbering === true
+      ? "<w:isLgl/>"
+      : level.isLegalNumbering === false
+        ? `<w:isLgl w:val="false"/>`
+        : "";
   const suffix = level.suffix ? `<w:suff w:val="${escapeAttribute(level.suffix)}"/>` : "";
   const justification = level.paragraphGeometry?.justification
     ? `<w:lvlJc w:val="${escapeAttribute(level.paragraphGeometry.justification)}"/>`
@@ -114,13 +130,19 @@ function serializeLevelOverride(
   const paragraphProperties = serializeLevelParagraphGeometry(level.paragraphGeometry);
   const body = `${start}${format}${text}${paragraphStyle}${isLegal}${suffix}${justification}${paragraphProperties}`;
 
-  return body.length > 0 ? `<w:lvl w:ilvl="${serializedLevel}">${body}</w:lvl>` : "";
+  return body.length > 0
+    ? `<w:lvl w:ilvl="${clampIlvl(serializedLevel)}">${body}</w:lvl>`
+    : "";
 }
 
 function serializeInstance(instance: NumberingCatalog["instances"][string]): string {
-  const numId = escapeAttribute(stripCanonicalPrefix(instance.numberingInstanceId, "num:"));
+  const numId = escapeAttribute(
+    clampNonNegativeIdString(stripCanonicalPrefix(instance.numberingInstanceId, "num:")),
+  );
   const abstractNumId = escapeAttribute(
-    stripCanonicalPrefix(instance.abstractNumberingId, "abstract-num:"),
+    clampNonNegativeIdString(
+      stripCanonicalPrefix(instance.abstractNumberingId, "abstract-num:"),
+    ),
   );
   const overrides = [...instance.overrides]
     .sort((left, right) => left.level - right.level)
@@ -132,11 +154,13 @@ function serializeInstance(instance: NumberingCatalog["instances"][string]): str
 
 function serializeOverride(override: NumberingCatalog["instances"][string]["overrides"][number]): string {
   const startOverride =
-    override.startAt !== undefined ? `<w:startOverride w:val="${override.startAt}"/>` : "";
+    override.startAt !== undefined
+      ? `<w:startOverride w:val="${clampStart(override.startAt)}"/>`
+      : "";
   const levelDefinition = override.levelDefinition
     ? serializeLevelOverride(override.levelDefinition, override.level)
     : "";
-  return `<w:lvlOverride w:ilvl="${override.level}">${startOverride}${levelDefinition}</w:lvlOverride>`;
+  return `<w:lvlOverride w:ilvl="${clampIlvl(override.level)}">${startOverride}${levelDefinition}</w:lvlOverride>`;
 }
 
 function serializeLevelParagraphGeometry(
@@ -150,13 +174,13 @@ function serializeLevelParagraphGeometry(
   if (paragraphGeometry.spacing) {
     const attrs: string[] = [];
     if (paragraphGeometry.spacing.before !== undefined) {
-      attrs.push(`w:before="${paragraphGeometry.spacing.before}"`);
+      attrs.push(`w:before="${twip(paragraphGeometry.spacing.before)}"`);
     }
     if (paragraphGeometry.spacing.after !== undefined) {
-      attrs.push(`w:after="${paragraphGeometry.spacing.after}"`);
+      attrs.push(`w:after="${twip(paragraphGeometry.spacing.after)}"`);
     }
     if (paragraphGeometry.spacing.line !== undefined) {
-      attrs.push(`w:line="${paragraphGeometry.spacing.line}"`);
+      attrs.push(`w:line="${twip(paragraphGeometry.spacing.line)}"`);
     }
     if (paragraphGeometry.spacing.lineRule !== undefined) {
       attrs.push(`w:lineRule="${paragraphGeometry.spacing.lineRule}"`);
@@ -169,16 +193,16 @@ function serializeLevelParagraphGeometry(
   if (paragraphGeometry.indentation) {
     const attrs: string[] = [];
     if (paragraphGeometry.indentation.left !== undefined) {
-      attrs.push(`w:left="${paragraphGeometry.indentation.left}"`);
+      attrs.push(`w:left="${twip(paragraphGeometry.indentation.left)}"`);
     }
     if (paragraphGeometry.indentation.right !== undefined) {
-      attrs.push(`w:right="${paragraphGeometry.indentation.right}"`);
+      attrs.push(`w:right="${twip(paragraphGeometry.indentation.right)}"`);
     }
     if (paragraphGeometry.indentation.firstLine !== undefined) {
-      attrs.push(`w:firstLine="${paragraphGeometry.indentation.firstLine}"`);
+      attrs.push(`w:firstLine="${twip(paragraphGeometry.indentation.firstLine)}"`);
     }
     if (paragraphGeometry.indentation.hanging !== undefined) {
-      attrs.push(`w:hanging="${paragraphGeometry.indentation.hanging}"`);
+      attrs.push(`w:hanging="${twip(paragraphGeometry.indentation.hanging)}"`);
     }
     if (attrs.length > 0) {
       children.push(`<w:ind ${attrs.join(" ")}/>`);
@@ -189,7 +213,7 @@ function serializeLevelParagraphGeometry(
     const tabsXml = paragraphGeometry.tabStops.map((tab) => {
       const leader = tab.leader === "middleDot" ? "middledot" : tab.leader;
       const leaderAttr = leader ? ` w:leader="${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("");
     children.push(`<w:tabs>${tabsXml}</w:tabs>`);
   }
@@ -197,6 +221,73 @@ function serializeLevelParagraphGeometry(
   return children.length > 0 ? `<w:pPr>${children.join("")}</w:pPr>` : "";
 }
 
+/**
+ * ST_DecimalNumberOrPercent / ST_DecimalNumber based ilvl/numId/abstractNumId
+ * attributes are integer-typed. Ilvl is bounded 0-8 by the schema.
+ * Negative ids violate MinInclusive ≥ 0 and make the validator fail.
+ * These clampers normalise at the authoring edge (A.6 MinInclusive clamp).
+ */
+function clampIlvl(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) return 0;
+  const rounded = Math.round(value);
+  if (rounded < 0) {
+    warnClamp("w:ilvl", rounded, 0);
+    return 0;
+  }
+  if (rounded > 8) {
+    warnClamp("w:ilvl", rounded, 8);
+    return 8;
+  }
+  return rounded;
+}
+
+function clampStart(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) return 1;
+  const rounded = Math.round(value);
+  // w:start MinInclusive per the schema is 0 (0 is legal for Word-created
+  // lists that begin with a 0-based custom format). Negative values fail.
+  if (rounded < 0) {
+    warnClamp("w:start", rounded, 0);
+    return 0;
+  }
+  return rounded;
+}
+
+/**
+ * Clamp a stringified id attribute (w:numId / w:abstractNumId) to the
+ * schema's MinInclusive=0. Accepts the canonical id string (produced by
+ * `stripCanonicalPrefix`) and returns a string safe to embed as a value.
+ * If the string is non-numeric or positive it passes through unchanged.
+ */
+function clampNonNegativeIdString(value: string): string {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) return value;
+  if (parsed < 0) {
+    warnClamp("w:numId/w:abstractNumId", parsed, 0);
+    return "0";
+  }
+  return value;
+}
+
+let warnedClamps = 0;
+const WARNED_CLAMPS_MAX = 20;
+function warnClamp(attr: string, from: number, to: number): void {
+  if (warnedClamps >= WARNED_CLAMPS_MAX) return;
+  warnedClamps += 1;
+  // Only warn outside of production builds. The test runner shows these
+  // via console.warn automatically; in production this is a silent no-op
+  // so the Buffer cost is zero. Read NODE_ENV through globalThis so the
+  // production tsconfig (which excludes @types/node) type-checks cleanly.
+  const proc = (globalThis as unknown as {
+    process?: { env?: Record<string, string | undefined> };
+  }).process;
+  if (proc?.env?.NODE_ENV !== "production") {
+    console.warn(
+      `[numbering] clamped ${attr} ${from} -> ${to} at MinInclusive (A.6 guard)`,
+    );
+  }
+}
+
 function compareSerializedIds(left: string, right: string): number {
   return stripKnownPrefix(left).localeCompare(stripKnownPrefix(right), "en", { numeric: true });
 }

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

@@ -10,13 +10,14 @@ import type {
   ParsedTableRow,
   ParsedTableWidth,
 } from "../ooxml/parse-tables.ts";
+import { twip } from "./twip.ts";
 
 export function serializeTable(table: ParsedTable): string {
   const propertiesXml = table.propertiesXml ?? buildTablePropertiesXml(table);
   const gridXml =
     table.gridColumns.length > 0
       ? `<w:tblGrid>${table.gridColumns
-          .map((width) => `<w:gridCol w:w="${width}"/>`)
+          .map((width) => `<w:gridCol w:w="${twip(width)}"/>`)
           .join("")}</w:tblGrid>`
       : "";
   const rowsXml = table.rows.map(serializeRow).join("");
@@ -65,7 +66,7 @@ function buildRowPropertiesXml(row: ParsedTableRow): string {
   const children: string[] = [];
   if (row.height !== undefined) {
     const hRuleAttr = row.heightRule ? ` w:hRule="${row.heightRule}"` : "";
-    children.push(`<w:trHeight w:val="${row.height}"${hRuleAttr}/>`);
+    children.push(`<w:trHeight w:val="${twip(row.height)}"${hRuleAttr}/>`);
   }
   if (row.isHeader) {
     children.push(`<w:tblHeader/>`);
@@ -83,7 +84,7 @@ function ensureCellProperties(cell: ParsedTableCell): string {
     children.push(serializeWidth("tcW", cell.width));
   }
   if (cell.gridSpan && cell.gridSpan > 1) {
-    children.push(`<w:gridSpan w:val="${cell.gridSpan}"/>`);
+    children.push(`<w:gridSpan w:val="${twip(cell.gridSpan)}"/>`);
   }
   if (cell.verticalMerge) {
     children.push(
@@ -107,14 +108,14 @@ function ensureCellProperties(cell: ParsedTableCell): string {
 }
 
 function serializeWidth(element: string, width: ParsedTableWidth): string {
-  return `<w:${element} w:w="${width.value}" w:type="${width.type}"/>`;
+  return `<w:${element} w:w="${twip(width.value)}" w:type="${width.type}"/>`;
 }
 
 function serializeBorderSpec(element: string, spec: ParsedBorderSpec): string {
   const attrs: string[] = [];
   if (spec.value) attrs.push(`w:val="${spec.value}"`);
-  if (spec.size !== undefined) attrs.push(`w:sz="${spec.size}"`);
-  if (spec.space !== undefined) attrs.push(`w:space="${spec.space}"`);
+  if (spec.size !== undefined) attrs.push(`w:sz="${twip(spec.size)}"`);
+  if (spec.space !== undefined) attrs.push(`w:space="${twip(spec.space)}"`);
   if (spec.color) attrs.push(`w:color="${spec.color}"`);
   const attrsStr = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
   return `<w:${element}${attrsStr}/>`;
@@ -149,7 +150,8 @@ function serializeTableLook(tblLook: ParsedTableLook): string {
   ] as const) {
     const value = tblLook[key];
     if (value !== undefined) {
-      attrs.push(`${attr}="${value ? "1" : "0"}"`);
+      // ST_OnOff (A.3): emit "true"/"false", never "1"/"0".
+      attrs.push(`${attr}="${value ? "true" : "false"}"`);
     }
   }
   return attrs.length > 0 ? `<w:tblLook ${attrs.join(" ")}/>` : "";
@@ -166,9 +168,9 @@ function serializeCellShading(shading: ParsedCellShading): string {
 
 function serializeTableCellMargins(margins: ParsedCellMargins): string {
   const parts: string[] = [];
-  if (margins.top !== undefined) parts.push(`<w:top w:w="${margins.top}" w:type="dxa"/>`);
-  if (margins.left !== undefined) parts.push(`<w:left w:w="${margins.left}" w:type="dxa"/>`);
-  if (margins.bottom !== undefined) parts.push(`<w:bottom w:w="${margins.bottom}" w:type="dxa"/>`);
-  if (margins.right !== undefined) parts.push(`<w:right w:w="${margins.right}" w:type="dxa"/>`);
+  if (margins.top !== undefined) parts.push(`<w:top w:w="${twip(margins.top)}" w:type="dxa"/>`);
+  if (margins.left !== undefined) parts.push(`<w:left w:w="${twip(margins.left)}" w:type="dxa"/>`);
+  if (margins.bottom !== undefined) parts.push(`<w:bottom w:w="${twip(margins.bottom)}" w:type="dxa"/>`);
+  if (margins.right !== undefined) parts.push(`<w:right w:w="${twip(margins.right)}" w:type="dxa"/>`);
   return parts.join("");
 }

package/src/io/export/table-properties-xml.ts

@@ -1,3 +1,5 @@
+import { twip } from "./twip.ts";
+
 interface TableWidthLike {
   value: number;
   type: string;
@@ -196,23 +198,35 @@ function buildTablePropertiesInnerXml(table: TablePropertiesLike): string {
 function buildTableRowPropertiesInnerXml(row: TableRowPropertiesLike): string {
   const children: string[] = [];
   if (row.gridBefore !== undefined) {
-    children.push(`<w:gridBefore w:val="${row.gridBefore}"/>`);
+    children.push(`<w:gridBefore w:val="${twip(row.gridBefore)}"/>`);
   }
   if (row.widthBefore) {
-    children.push(`<w:wBefore w:w="${row.widthBefore.value}" w:type="${row.widthBefore.type}"/>`);
+    children.push(
+      `<w:wBefore w:w="${twip(row.widthBefore.value)}" w:type="${row.widthBefore.type}"/>`,
+    );
   }
   if (row.gridAfter !== undefined) {
-    children.push(`<w:gridAfter w:val="${row.gridAfter}"/>`);
+    children.push(`<w:gridAfter w:val="${twip(row.gridAfter)}"/>`);
   }
   if (row.widthAfter) {
-    children.push(`<w:wAfter w:w="${row.widthAfter.value}" w:type="${row.widthAfter.type}"/>`);
+    children.push(
+      `<w:wAfter w:w="${twip(row.widthAfter.value)}" w:type="${row.widthAfter.type}"/>`,
+    );
   }
   if (row.height !== undefined) {
     const hRuleAttr = row.heightRule ? ` w:hRule="${escapeAttribute(row.heightRule)}"` : "";
-    children.push(`<w:trHeight w:val="${row.height}"${hRuleAttr}/>`);
+    children.push(`<w:trHeight w:val="${twip(row.height)}"${hRuleAttr}/>`);
   }
-  if (row.isHeader !== undefined) {
-    children.push(row.isHeader ? `<w:tblHeader/>` : `<w:tblHeader w:val="0"/>`);
+  // ST_OnOff element (A.3):
+  // - true  → <w:tblHeader/> (element-only form = implicit true).
+  // - false → <w:tblHeader w:val="false"/> (explicit override — canonical
+  //            carries an explicit false because the source distinguished it
+  //            from "missing" at import time; never emit "0"/"1" per A.3).
+  // - undefined → omit (no element).
+  if (row.isHeader === true) {
+    children.push(`<w:tblHeader/>`);
+  } else if (row.isHeader === false) {
+    children.push(`<w:tblHeader w:val="false"/>`);
   }
   return children.join("");
 }
@@ -223,7 +237,7 @@ function buildTableCellPropertiesInnerXml(cell: TableCellPropertiesLike): string
     children.push(serializeWidth("tcW", cell.width));
   }
   if (cell.gridSpan && cell.gridSpan > 1) {
-    children.push(`<w:gridSpan w:val="${cell.gridSpan}"/>`);
+    children.push(`<w:gridSpan w:val="${twip(cell.gridSpan)}"/>`);
   }
   if (cell.verticalMerge) {
     children.push(
@@ -251,7 +265,9 @@ function buildTableCellPropertiesInnerXml(cell: TableCellPropertiesLike): string
 }
 
 function serializeWidth(elementName: "tblW" | "tcW", width: TableWidthLike): string {
-  return `<w:${elementName} w:w="${width.value}" w:type="${escapeAttribute(width.type)}"/>`;
+  // OOXML allows w:w to be percentage (pct) or twentieths-of-a-percent too, but
+  // both are integer-typed in the schema. Always round at the authoring edge.
+  return `<w:${elementName} w:w="${twip(width.value)}" w:type="${escapeAttribute(width.type)}"/>`;
 }
 
 function serializeBorders(borders: TableBordersLike): string {
@@ -265,18 +281,18 @@ function serializeBorders(borders: TableBordersLike): string {
 function serializeBorderSpec(elementName: string, border: BorderSpecLike): string {
   const attrs: string[] = [];
   if (border.value) attrs.push(`w:val="${escapeAttribute(border.value)}"`);
-  if (border.size !== undefined) attrs.push(`w:sz="${border.size}"`);
-  if (border.space !== undefined) attrs.push(`w:space="${border.space}"`);
+  if (border.size !== undefined) attrs.push(`w:sz="${twip(border.size)}"`);
+  if (border.space !== undefined) attrs.push(`w:space="${twip(border.space)}"`);
   if (border.color) attrs.push(`w:color="${escapeAttribute(border.color)}"`);
   return attrs.length > 0 ? `<w:${elementName} ${attrs.join(" ")}/>` : "";
 }
 
 function serializeTableCellMargins(margins: TableCellMarginsLike): string {
   const parts: string[] = [];
-  if (margins.top !== undefined) parts.push(`<w:top w:w="${margins.top}" w:type="dxa"/>`);
-  if (margins.left !== undefined) parts.push(`<w:left w:w="${margins.left}" w:type="dxa"/>`);
-  if (margins.bottom !== undefined) parts.push(`<w:bottom w:w="${margins.bottom}" w:type="dxa"/>`);
-  if (margins.right !== undefined) parts.push(`<w:right w:w="${margins.right}" w:type="dxa"/>`);
+  if (margins.top !== undefined) parts.push(`<w:top w:w="${twip(margins.top)}" w:type="dxa"/>`);
+  if (margins.left !== undefined) parts.push(`<w:left w:w="${twip(margins.left)}" w:type="dxa"/>`);
+  if (margins.bottom !== undefined) parts.push(`<w:bottom w:w="${twip(margins.bottom)}" w:type="dxa"/>`);
+  if (margins.right !== undefined) parts.push(`<w:right w:w="${twip(margins.right)}" w:type="dxa"/>`);
   return parts.join("");
 }
 
@@ -295,7 +311,10 @@ function serializeTableLook(tblLook: TableLookLike): string {
   ] as const) {
     const value = tblLook[key];
     if (value !== undefined) {
-      attrs.push(`${attr}="${value ? "1" : "0"}"`);
+      // tblLook individual attributes are ST_OnOff per ECMA-376 2nd Ed.
+      // Emit the string form ("true"/"false"); the "1"/"0" form is rejected
+      // by DocumentFormat.OpenXml's enumeration validator.
+      attrs.push(`${attr}="${value ? "true" : "false"}"`);
     }
   }
   return attrs.length > 0 ? `<w:tblLook ${attrs.join(" ")}/>` : "";

package/src/io/export/twip.ts

@@ -0,0 +1,66 @@
+/**
+ * Integer-twip guard for OOXML numeric attributes.
+ *
+ * OOXML twip-based attributes (w:ind.left, w:pgSz.w, w:tblW.w, w:tcW.w,
+ * w:gridCol.w, w:trHeight.val, border w:sz, tab-stop w:pos, etc.) are
+ * schema-typed as ST_TwipsMeasure / ST_SignedTwipsMeasure / ST_MeasurementOrPercent
+ * or plain xsd:int variants. The OpenXML SDK validates these as Int32. Emitting
+ * a fractional value like "566.9999999999999" triggers the SDK
+ * "invalid 'Int32' value" finding, even when the numeric result is only off
+ * by float-rounding noise.
+ *
+ * These helpers normalise every numeric attribute write through `Math.round`
+ * and reject non-finite inputs at the authoring boundary so the serializer
+ * cannot accidentally emit NaN, Infinity, or fractional values.
+ *
+ * Callers should route through:
+ *   twip(value)         — optional numeric: undefined passes through; returns integer.
+ *   requireTwip(value)  — mandatory numeric: throws on non-finite input.
+ *
+ * Source:
+ *   docs/plans/close-render-fidelity.md §2 A.2
+ */
+
+/**
+ * Normalise a numeric twip attribute to an integer. Returns undefined when
+ * the input is undefined, preserving existing "omit attribute" semantics.
+ * Throws when the numeric input is NaN or non-finite — this indicates a
+ * bug in whichever authoring path produced the value and must never reach
+ * the serialized XML buffer.
+ */
+export function twip(value: number | undefined | null): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Number.isFinite(value)) {
+    throw new RangeError(
+      `twip(): expected finite number, received ${String(value)}`,
+    );
+  }
+  return Math.round(value);
+}
+
+/**
+ * Normalise a mandatory numeric twip attribute to an integer. Throws when
+ * the input is not a finite number.
+ */
+export function requireTwip(value: number): number {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(
+      `requireTwip(): expected finite number, received ${String(value)}`,
+    );
+  }
+  return Math.round(value);
+}
+
+/**
+ * Parse a numeric attribute from an OOXML document. Accepts whatever the
+ * raw string carries — Word sometimes emits floats from scaling math — and
+ * returns either an integer or `undefined` when the input is missing /
+ * unparseable. This symmetric helper is used on the parser side so the
+ * canonical model never holds a fractional twip.
+ */
+export function parseTwipAttribute(raw: string | undefined): number | undefined {
+  if (raw === undefined || raw === null || raw === "") return undefined;
+  const parsed = Number.parseFloat(raw);
+  if (!Number.isFinite(parsed)) return undefined;
+  return Math.round(parsed);
+}

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

@@ -182,6 +182,11 @@ function normalizeParagraph(
     ...(paragraph.bidi ? { bidi: paragraph.bidi } : {}),
     ...(paragraph.borders ? { borders: paragraph.borders } : {}),
     ...(paragraph.shading ? { shading: paragraph.shading } : {}),
+    // A.7: preserve w14:paraId / w14:textId across import → export so
+    // downstream tools that diff documents by paragraph id stay stable.
+    ...(paragraph.wordExtensionIds
+      ? { wordExtensionIds: paragraph.wordExtensionIds }
+      : {}),
     children,
   };
 }

package/src/io/ooxml/parse-footnotes.ts

@@ -546,7 +546,8 @@ function parseRunProperties(rElement: XmlElementNode): TextMark[] {
       }
       case "color": {
         const colorVal = child.attributes["w:val"] ?? child.attributes.val;
-        if (colorVal && colorVal !== "auto") marks.push({ type: "textColor", color: colorVal });
+        // A.9: preserve "auto" verbatim for round-trip.
+        if (colorVal) marks.push({ type: "textColor", color: colorVal });
         break;
       }
       case "smallCaps":

package/src/io/ooxml/parse-headers-footers.ts

@@ -689,7 +689,8 @@ function parseRunProperties(rElement: XmlElementNode): TextMark[] {
       }
       case "color": {
         const colorVal = child.attributes["w:val"] ?? child.attributes.val;
-        if (colorVal && colorVal !== "auto") {
+        // A.9: preserve "auto" verbatim for round-trip.
+        if (colorVal) {
           marks.push({ type: "textColor", color: colorVal });
         }
         break;

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

@@ -92,6 +92,11 @@ export interface ParsedParagraphNode {
   bidi?: boolean;
   suppressLineNumbers?: boolean;
   cnfStyle?: string;
+  /** A.7: preserved w14 extension ids (paraId/textId). */
+  wordExtensionIds?: {
+    paraId?: string;
+    textId?: string;
+  };
   sectionProperties?: SectionProperties;
   sectionPropertiesXml?: string;
   children: ParsedInlineNode[];
@@ -493,6 +498,17 @@ function parseBodyChild(
   let sectionProperties: SectionProperties | undefined;
   let sectionPropertiesXml: string | undefined;
   let paragraphSupported = true;
+  // A.7: capture w14:paraId / w14:textId from the <w:p> element attributes
+  // so round-trip export can re-emit them unchanged.
+  const paraId = node.attributes["w14:paraId"] ?? node.attributes.paraId;
+  const textId = node.attributes["w14:textId"] ?? node.attributes.textId;
+  const wordExtensionIds: ParsedParagraphNode["wordExtensionIds"] | undefined =
+    paraId || textId
+      ? {
+          ...(paraId ? { paraId: paraId.toUpperCase() } : {}),
+          ...(textId ? { textId: textId.toUpperCase() } : {}),
+        }
+      : undefined;
   const children: ParsedInlineNode[] = [];
   let activeComplexField: {
     instruction: string;
@@ -709,6 +725,7 @@ function parseBodyChild(
     ...(bidi ? { bidi } : {}),
     ...(suppressLineNumbers ? { suppressLineNumbers } : {}),
     ...(cnfStyle ? { cnfStyle } : {}),
+    ...(wordExtensionIds ? { wordExtensionIds } : {}),
     ...(sectionProperties ? { sectionProperties } : {}),
     ...(sectionPropertiesXml ? { sectionPropertiesXml } : {}),
     children,
@@ -2242,7 +2259,10 @@ function readRunMarks(node: XmlElementNode, sourceXml: string): MarksParseResult
   );
   if (colorNode) {
     const colorVal = colorNode.attributes["w:val"] ?? colorNode.attributes.val;
-    if (colorVal && colorVal !== "auto") {
+    // A.9: preserve the literal "auto" marker so the serializer can round-trip
+    // it back. The canonical colour string is free-form; downstream paint
+    // paths treat "auto" as "inherit from theme/style".
+    if (colorVal) {
       marks.push({ type: "textColor", color: colorVal });
     }
   }

package/src/legal/bookmarks.ts

@@ -254,6 +254,84 @@ export function resolveBookmarkFieldDependencies(
   return deps;
 }
 
+/**
+ * A.4 — detect duplicate bookmark ids in the canonical document.
+ *
+ * Walks the document in order and records every bookmarkStart. The first
+ * occurrence of each id keeps its original value; later occurrences are
+ * scheduled for re-keying to a fresh monotonically-increasing id above
+ * `max(existing numeric ids)` so newly-allocated ids never collide with
+ * any surviving original.
+ *
+ * Returns a plan the caller can use to mutate both bookmark nodes and
+ * every reference to them (PAGEREF / REF field instructions, hyperlink
+ * w:anchor, TOC entries). Each assignment is keyed by the start node's
+ * ordinal position so callers can walk the document a second time and
+ * apply the new id deterministically.
+ */
+export interface BookmarkRekeyAssignment {
+  /** Ordinal position of the bookmark_start within the pre-order walk. */
+  ordinal: number;
+  /** Original bookmark id as emitted by the source. */
+  oldId: string;
+  /** New id when a re-key was scheduled; undefined when the id is kept. */
+  newId?: string;
+}
+
+export interface BookmarkRekeyPlan {
+  assignments: readonly BookmarkRekeyAssignment[];
+  /** All ids that had ≥2 occurrences in the source. */
+  duplicatedIds: readonly string[];
+  /** New max id allocated by the plan (advisory for allocators). */
+  nextId: number;
+}
+
+export function detectDuplicateBookmarkIds(
+  document: Pick<CanonicalDocument, "content"> | DocumentNode,
+): BookmarkRekeyPlan {
+  const root = "content" in document ? document.content : document;
+  const seenStarts = new Set<string>();
+  const duplicatedIds = new Set<string>();
+  let maxNumericId = 0;
+
+  const bookmarkStarts: Array<BookmarkStartNode> = [];
+
+  walkDocument(root, (node) => {
+    if (node.type === "bookmark_start") {
+      bookmarkStarts.push(node);
+      const parsed = Number.parseInt(node.bookmarkId, 10);
+      if (Number.isFinite(parsed)) {
+        maxNumericId = Math.max(maxNumericId, parsed);
+      }
+    }
+  });
+
+  const assignments: BookmarkRekeyAssignment[] = [];
+  let nextId = maxNumericId + 1;
+  for (let ordinal = 0; ordinal < bookmarkStarts.length; ordinal += 1) {
+    const start = bookmarkStarts[ordinal]!;
+    if (!seenStarts.has(start.bookmarkId)) {
+      seenStarts.add(start.bookmarkId);
+      assignments.push({ ordinal, oldId: start.bookmarkId });
+      continue;
+    }
+    duplicatedIds.add(start.bookmarkId);
+    const fresh = String(nextId);
+    nextId += 1;
+    assignments.push({
+      ordinal,
+      oldId: start.bookmarkId,
+      newId: fresh,
+    });
+  }
+
+  return {
+    assignments,
+    duplicatedIds: [...duplicatedIds].sort(),
+    nextId,
+  };
+}
+
 function walkDocument(node: DocumentNode, visit: (node: DocumentNode) => void): void {
   visit(node);