@ansonlai/docx-redline-js 0.1.6 → 0.2.1

package/engine/run-builders.js

@@ -5,7 +5,7 @@
  * and `w:pPrChange` elements used by surgical and reconstruction modes.
  */
 
-import { RPR_SCHEMA_ORDER } from './rpr-helpers.js';
+import { extractFormatFromRPr, RPR_SCHEMA_ORDER } from './rpr-helpers.js';
 import { createRevisionMetadata } from '../core/types.js';
 import { getFirstElementByTag } from '../core/xml-query.js';
 import { createWordElement } from '../core/word-xml.js';
@@ -140,8 +140,8 @@ export function createTextRun(xmlDoc, text, rPr, isDelete) {
  * @param {boolean} [generateRedlines] - Whether to create rPrChange
  * @returns {Element[]}
  */
-export function createFormattedRuns(xmlDoc, text, baseRPr, formatHints, baseOffset, author, generateRedlines) {
-    if (!text) return [];
+export function createFormattedRuns(xmlDoc, text, baseRPr, formatHints, baseOffset, author, generateRedlines) {
+    if (!text) return [];
 
     const breaks = new Set([0, text.length]);
     for (const hint of formatHints) {
@@ -167,13 +167,17 @@ export function createFormattedRuns(xmlDoc, text, baseRPr, formatHints, baseOffs
             h.start <= segmentBaseOffset && h.end >= segmentEndOffset
         );
 
-        const combinedFormat = {};
-        applicableHints.forEach(h => {
-            if (h.format) Object.assign(combinedFormat, h.format);
-        });
-
-        const formattedRPr = injectFormattingToRPr(xmlDoc, baseRPr, combinedFormat, author, generateRedlines);
-        runs.push(createTextRunWithRPrElement(xmlDoc, segment, formattedRPr, false));
+        const combinedFormat = { ...extractFormatFromRPr(baseRPr) };
+        applicableHints.forEach(h => {
+            if (h.format) Object.assign(combinedFormat, h.format);
+        });
+
+        // During a text edit, missing Markdown is not an instruction to clear
+        // the source run's formatting. Only synchronize explicitly hinted spans.
+        const formattedRPr = applicableHints.length > 0
+            ? injectFormattingToRPr(xmlDoc, baseRPr, combinedFormat, author, generateRedlines)
+            : baseRPr?.cloneNode(true) || null;
+        runs.push(createTextRunWithRPrElement(xmlDoc, segment, formattedRPr, false));
     }
 
     return runs;

package/engine/surgical-diff-application.js

@@ -1,5 +1,4 @@
 import { getApplicableFormatHints } from '../pipeline/markdown-processor.js';
-import { isWordElement } from '../core/word-xml.js';
 import {
     createTrackChange,
     createTextRun,
@@ -20,30 +19,17 @@ import {
     findLastSpanEndingBeforeOrAt,
     forEachOverlappingSpan
 } from './surgical-spans.js';
+import { extractFormatFromRPr } from './rpr-helpers.js';
 
 export function reconcileFormattingForTextSpan(xmlDoc, span, start, end, applicableHints, author, generateRedlines) {
-    const desiredFormat = {};
-    if (applicableHints.length > 0) {
-        applicableHints.forEach(h => Object.assign(desiredFormat, h.format));
-    }
+    // Plain modified text carries no negative formatting instruction. Preserve
+    // unchanged source formatting unless Markdown explicitly targets this span.
+    if (applicableHints.length === 0) return false;
 
     const rPr = span.rPr;
-    const hasElement = (localName) => {
-        if (!rPr) return false;
-        for (let node = rPr.firstChild; node; node = node.nextSibling) {
-            if (isWordElement(node, localName)) {
-                return true;
-            }
-        }
-        return false;
-    };
-
-    const existingFormat = {
-        bold: hasElement('b'),
-        italic: hasElement('i'),
-        underline: hasElement('u'),
-        strikethrough: hasElement('strike')
-    };
+    const existingFormat = extractFormatFromRPr(rPr);
+    const desiredFormat = { ...existingFormat };
+    applicableHints.forEach(h => Object.assign(desiredFormat, h.format));
 
     const formatsToCheck = ['bold', 'italic', 'underline', 'strikethrough'];
     const changesNeeded = formatsToCheck.some(f => !!desiredFormat[f] !== existingFormat[f]);

package/index.d.ts

@@ -126,6 +126,30 @@ export function rejectTrackedChangesInOoxml(oxml: string, options?: RevisionFilt
 export function deleteCommentsByAuthorInOoxml(oxml: string, options?: RevisionFilterOptions): DeleteCommentsResult;
 export function containsTrackedChanges(xmlDoc: Document | Element): boolean;
 
+export type RedlineValidationSeverity = 'error' | 'warning';
+
+export interface RedlineValidationIssue {
+  code:
+    | 'PARSE_ERROR'
+    | 'NESTED_REVISION'
+    | 'DEL_CONTAINS_T'
+    | 'MISSING_REVISION_METADATA'
+    | 'DUPLICATE_REVISION_ID'
+    | 'MISSING_SPACE_PRESERVE'
+    | 'EMPTY_TEXT_ELEMENT'
+    | 'EMPTY_REVISION_WRAPPER'
+    | string;
+  severity: RedlineValidationSeverity;
+  message: string;
+}
+
+export interface RedlineValidationResult {
+  valid: boolean;
+  issues: RedlineValidationIssue[];
+}
+
+export function validateRedlineOoxml(oxml: string): RedlineValidationResult;
+
 export function applyHighlightToOoxml(oxml: string, targetText: string, color: string, options?: Record<string, unknown>): string;
 export function generateTableOoxml(headersOrData: unknown, rowsOrOptions?: unknown, options?: Record<string, unknown>): string;
 export function extractReplacementNodesFromOoxml(oxml: string): unknown;

package/index.js

@@ -1,13 +1,13 @@
-/**
- * Standalone reconciliation entrypoint (no Word JS API dependencies).
- */
-
+/**
+ * Standalone reconciliation entrypoint (no Word JS API dependencies).
+ */
+
 // Adapters
 export { configureXmlProvider } from './adapters/xml-adapter.js';
 export { configureLogger } from './adapters/logger.js';
 export { setDefaultAuthor, getDefaultAuthor, setPlatform, getPlatform } from './adapters/config.js';
-
-// Engine
+
+// Engine
 import {
     applyRedlineToOxml as applyRedlineToOxmlEngine,
     sanitizeAiResponse,
@@ -27,14 +27,15 @@ import {
 } from './orchestration/list-structural-fallback.js';
 import { withOoxmlSourceType } from './core/word-xml.js';
 export { containsTrackedChanges } from './core/word-xml.js';
-
-/**
- * Standalone-safe redline wrapper.
- *
- * In non-Word runtimes, the engine can return `{ useNativeApi: true, hasChanges: true }`
- * without an OOXML payload for some format-only operations. Standalone callers cannot
- * complete that native fallback path, so normalize to a no-op with warnings.
- */
+export { validateRedlineOoxml } from './core/redline-validation.js';
+
+/**
+ * Standalone-safe redline wrapper.
+ *
+ * In non-Word runtimes, the engine can return `{ useNativeApi: true, hasChanges: true }`
+ * without an OOXML payload for some format-only operations. Standalone callers cannot
+ * complete that native fallback path, so normalize to a no-op with warnings.
+ */
 export async function applyRedlineToOxml(oxml, originalText, modifiedText, options = {}) {
     const result = await applyRedlineToOxmlEngine(oxml, originalText, modifiedText, options);
     if (result?.useNativeApi && typeof result?.oxml !== 'string') {
@@ -99,9 +100,9 @@ export async function reconcileMarkdownTableOoxml(oxml, originalText, markdownTa
     };
 }
 
-export { resolveParagraphRangeByRefs } from './core/paragraph-targeting.js';
-export { inferTableReplacementParagraphBlock, isLikelyStructuredTableSourceParagraph } from './core/table-targeting.js';
-
+export { resolveParagraphRangeByRefs } from './core/paragraph-targeting.js';
+export { inferTableReplacementParagraphBlock, isLikelyStructuredTableSourceParagraph } from './core/table-targeting.js';
+
 /**
  * Applies redline reconciliation, then forces single-line structural list
  * conversion when the redline is a no-op on marker-prefixed list text.
@@ -234,8 +235,8 @@ export { ingestOoxml } from './pipeline/ingestion.js';
 export { ingestWordOoxmlToPlainText, ingestWordOoxmlToMarkdown } from './pipeline/ingestion-export.js';
 export { preprocessMarkdown } from './pipeline/markdown-processor.js';
 export { serializeToOoxml, wrapInDocumentFragment } from './pipeline/serialization.js';
-
-// Comment engine
+
+// Comment engine
 export {
     injectCommentsIntoOoxml,
     injectCommentsIntoPackage,
@@ -247,15 +248,15 @@ export {
     rejectTrackedChangesInOoxml,
     deleteCommentsByAuthorInOoxml
 } from './services/revision-comment-management.js';
-
+
 // Formatting removal utilities
 export {
     removeFormattingFromRPr,
     applyFormattingRemovalToOoxml,
     applyHighlightToOoxml
 } from './engine/formatting-removal.js';
-
-// Table/list tools
+
+// Table/list tools
 export { generateTableOoxml } from './services/table-reconciliation.js';
 export { NumberingService } from './services/numbering-service.js';
 export {
@@ -282,20 +283,20 @@ export {
     enforceListBindingOnParagraphNodes,
     stripSingleLineListMarkerPrefix
 } from './orchestration/list-structural-fallback.js';
-
-// Core types/constants
-export { DiffOp, RunKind, ContainerKind, ContentType, NS_W, escapeXml } from './core/types.js';
-export { extractParagraphIdFromOoxml } from './core/ooxml-identifiers.js';
+
+// Core types/constants
+export { DiffOp, RunKind, ContainerKind, ContentType, NS_W, escapeXml } from './core/types.js';
+export { extractParagraphIdFromOoxml } from './core/ooxml-identifiers.js';
 export {
     WORD_MAIN_NS,
     getParagraphText,
     getDocumentParagraphNodes,
     normalizeWhitespaceForTargeting,
-    isMarkdownTableText,
-    parseParagraphReference,
-    stripLeadingParagraphMarker,
-    splitLeadingParagraphMarker,
-    findContainingWordElement,
+    isMarkdownTableText,
+    parseParagraphReference,
+    stripLeadingParagraphMarker,
+    splitLeadingParagraphMarker,
+    findContainingWordElement,
     findParagraphByReference,
     findParagraphByStrictText,
     findParagraphByBestTextMatch,
@@ -303,7 +304,7 @@ export {
     buildTargetReferenceSnapshot,
     resolveTargetParagraphWithSnapshot
 } from './core/paragraph-targeting.js';
-export { synthesizeTableMarkdownFromMultilineCellEdit } from './core/table-targeting.js';
+export { synthesizeTableMarkdownFromMultilineCellEdit } from './core/table-targeting.js';
 export {
     getParagraphListInfo,
     collectContiguousListParagraphBlock,
@@ -311,5 +312,5 @@ export {
     planListInsertionOnlyEdit,
     stripRedundantLeadingListMarkers
 } from './core/list-targeting.js';
-
-
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",
@@ -51,13 +51,14 @@
     }
   },
   "devDependencies": {
-    "esbuild": "^0.24.0",
-    "@xmldom/xmldom": "^0.9.0"
+    "@xmldom/xmldom": "^0.9.0",
+    "esbuild": "^0.28.1"
   },
   "scripts": {
     "build": "node scripts/build.mjs",
     "check:types": "node scripts/check-types.mjs",
     "smoke:word": "powershell -File scripts/word-com-smoke.ps1",
+    "smoke:word:diff": "powershell -File scripts/word-com-differential.ps1",
     "test": "node scripts/run-tests.mjs",
     "test:isolation": "node tests/no_word_api_index_check.mjs && node tests/core_dependency_graph_check.mjs",
     "prepublishOnly": "npm run test:isolation && npm run build"
@@ -78,6 +79,6 @@
     "url": "https://github.com/AnsonLai/docx-redline-js.git"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   }
 }

package/scripts/build.mjs

@@ -1,14 +1,19 @@
 import { build } from 'esbuild';
 import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
 
-const pkg = JSON.parse(readFileSync('./package.json', 'utf8'));
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const entryPoint = resolve(repoRoot, 'index.js');
+const distDir = resolve(repoRoot, 'dist');
+const pkg = JSON.parse(readFileSync(resolve(repoRoot, 'package.json'), 'utf8'));
 
 // ESM bundle with diff-match-patch inlined (for CDN/browser <script type="module">)
 await build({
-  entryPoints: ['./index.js'],
+  entryPoints: [entryPoint],
   bundle: true,
   format: 'esm',
-  outfile: 'dist/docx-redline-js.esm.js',
+  outfile: resolve(distDir, 'docx-redline-js.esm.js'),
   platform: 'neutral',         // no Node builtins assumed
   target: 'es2020',
   minify: false,                // keep readable for debugging
@@ -21,10 +26,10 @@ await build({
 
 // Minified version for production CDN use
 await build({
-  entryPoints: ['./index.js'],
+  entryPoints: [entryPoint],
   bundle: true,
   format: 'esm',
-  outfile: 'dist/docx-redline-js.esm.min.js',
+  outfile: resolve(distDir, 'docx-redline-js.esm.min.js'),
   platform: 'neutral',
   target: 'es2020',
   minify: true,

package/scripts/check-types.mjs

@@ -8,7 +8,8 @@ const requiredSnippets = [
   'export function applyRedlineToOxml',
   'export function acceptTrackedChangesInOoxml',
   'export function rejectTrackedChangesInOoxml',
-  'export function deleteCommentsByAuthorInOoxml'
+  'export function deleteCommentsByAuthorInOoxml',
+  'export function validateRedlineOoxml'
 ];
 
 for (const snippet of requiredSnippets) {

package/scripts/export-validation-fixtures.mjs

@@ -2,7 +2,10 @@ import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
 import { configureXmlProvider } from '../adapters/xml-adapter.js';
+import { validateRedlineOoxml } from '../core/redline-validation.js';
+import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
 import { applyOperationToDocumentXml } from '../services/standalone-operation-runner.js';
+import { buildMinimalDocx } from './lib/minimal-zip.mjs';
 
 const { DOMParser, XMLSerializer } = await import('@xmldom/xmldom');
 configureXmlProvider({ DOMParser, XMLSerializer });
@@ -14,7 +17,7 @@ mkdirSync(outputDir, { recursive: true });
 const baseDocument = text => `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <w:document xmlns:w="${NS_W}">
   <w:body>
-    <w:p><w:r><w:t>${text}</w:t></w:r></w:p>
+    <w:p><w:r><w:t xml:space="preserve">${text}</w:t></w:r></w:p>
     <w:sectPr/>
   </w:body>
 </w:document>`;
@@ -22,47 +25,101 @@ const baseDocument = text => `<?xml version="1.0" encoding="UTF-8" standalone="y
 const cases = [
   {
     name: 'simple-redline',
-    documentXml: baseDocument('The old sentence.'),
-    operation: { type: 'redline', target: 'The old sentence.', modified: 'The new sentence.' }
+    original: 'The old sentence.',
+    modified: 'The new sentence.'
   },
   {
     name: 'paragraph-insert',
-    documentXml: baseDocument('one'),
-    operation: { type: 'redline', target: 'one', modified: 'one\ntwo' }
+    original: 'one',
+    modified: 'one\ntwo'
   },
   {
     name: 'format-only',
-    documentXml: baseDocument('Make word bold'),
-    operation: { type: 'redline', target: 'Make word bold', modified: 'Make **word** bold' }
+    original: 'Make word bold',
+    modified: 'Make **word** bold'
+  },
+  {
+    name: 'whitespace-heavy',
+    original: 'Alpha beta gamma delta.',
+    modified: 'Alpha  beta REPLACED delta.'
+  },
+  {
+    name: 'unicode-replace',
+    original: 'Term 条款 applies to café.',
+    modified: 'Term 合同 applies to café 🚀.'
   }
 ];
 
+let failures = 0;
+
 for (const testCase of cases) {
   const result = await applyOperationToDocumentXml(
-    testCase.documentXml,
-    testCase.operation,
+    baseDocument(testCase.original),
+    { type: 'redline', target: testCase.original, modified: testCase.modified },
     'Validation',
     null,
     { generateRedlines: true }
   );
+
+  if (!result?.hasChanges || result?.status === 'error') {
+    console.error(`FAIL ${testCase.name}: redline did not apply (status=${result?.status}, error=${result?.error?.message})`);
+    failures++;
+    continue;
+  }
+
+  const validation = validateRedlineOoxml(result.documentXml);
+  const validationErrors = validation.issues.filter(issue => issue.severity === 'error');
+  if (validationErrors.length > 0) {
+    console.error(`FAIL ${testCase.name}: validateRedlineOoxml reported ${validationErrors.map(issue => issue.code).join(', ')}`);
+    failures++;
+    continue;
+  }
+
   writeFileSync(join(outputDir, `${testCase.name}.document.xml`), result.documentXml, 'utf8');
   if (result.numberingXml) {
     writeFileSync(join(outputDir, `${testCase.name}.numbering.xml`), result.numberingXml, 'utf8');
   }
+
+  const docx = buildMinimalDocx(result.documentXml, { numberingXml: result.numberingXml || null });
+  writeFileSync(join(outputDir, `${testCase.name}.docx`), docx);
+
+  // Expected text is derived from edit *intent*, not from this library's
+  // accept/reject transforms, so external consumers (Word COM, LibreOffice)
+  // act as independent oracles.
+  const expected = {
+    name: testCase.name,
+    expectedAcceptedText: preprocessMarkdown(testCase.modified).cleanText,
+    expectedRejectedText: testCase.original
+  };
+  writeFileSync(join(outputDir, `${testCase.name}.expected.json`), `${JSON.stringify(expected, null, 2)}\n`, 'utf8');
+
+  console.log(`wrote ${testCase.name}: .document.xml, .docx, .expected.json`);
 }
 
 writeFileSync(join(outputDir, 'README.md'), `# Validation Fixtures
 
-This folder contains generated OOXML parts for release-time validation.
+Generated by \`node scripts/export-validation-fixtures.mjs\`.
+
+Each case produces:
 
-The script writes document XML rather than complete .docx packages because this
-package intentionally does not add a zip dependency.
+- \`<name>.document.xml\` — the generated \`word/document.xml\` payload (for
+  XSD validation and manual inspection).
+- \`<name>.docx\` — a minimal package assembled by release tooling only (the
+  published library still has no zip dependency).
+- \`<name>.expected.json\` — the accept-all / reject-all plain-text outcomes
+  derived from edit intent, used by external-consumer differential checks.
 
-To manually inspect these fixtures:
+Validation entry points:
 
-1. Copy a generated *.document.xml file into a minimal .docx package as word/document.xml.
-2. Include any matching *.numbering.xml as word/numbering.xml.
-3. Open with Word, LibreOffice, or another OOXML consumer.
+- Word (differential accept/reject): \`npm run smoke:word:diff\`
+- LibreOffice parse check: \`soffice --headless --convert-to pdf *.docx\`
+- Schema check: \`xmllint --noout --schema wml.xsd *.document.xml\`
+  (transitional schemas from ECMA-376 Part 4; see docs/VALIDATION.md)
 `, 'utf8');
 
+if (failures > 0) {
+  console.error(`\n${failures} fixture case(s) failed.`);
+  process.exit(1);
+}
+
 console.log(`Wrote validation fixtures to ${outputDir}`);

package/scripts/lib/minimal-zip.mjs

@@ -0,0 +1,155 @@
+/**
+ * Minimal zip writer for assembling validation .docx fixtures.
+ *
+ * Script-only helper (not part of the published API surface) so the package
+ * keeps its no-zip-dependency guarantee while release tooling can still emit
+ * real .docx files for Word/LibreOffice validation. Uses deflate via
+ * node:zlib and a fixed timestamp for deterministic output.
+ */
+
+import { deflateRawSync } from 'zlib';
+
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++) {
+            c = c & 1 ? 0xEDB88320 ^ (c >>> 1) : c >>> 1;
+        }
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+
+function crc32(buffer) {
+    let crc = 0xFFFFFFFF;
+    for (let i = 0; i < buffer.length; i++) {
+        crc = CRC_TABLE[(crc ^ buffer[i]) & 0xFF] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xFFFFFFFF) >>> 0;
+}
+
+// Fixed DOS date/time (2026-01-01 00:00:00) keeps fixture bytes deterministic.
+const DOS_TIME = 0;
+const DOS_DATE = ((2026 - 1980) << 9) | (1 << 5) | 1;
+
+/**
+ * Builds a zip archive.
+ *
+ * @param {Array<{ name: string, data: Buffer|string }>} entries - Entry names
+ *   must use forward slashes (OPC requirement for .docx parts).
+ * @returns {Buffer}
+ */
+export function buildZip(entries) {
+    const localParts = [];
+    const centralParts = [];
+    let offset = 0;
+
+    for (const entry of entries) {
+        const nameBytes = Buffer.from(entry.name, 'utf8');
+        const data = Buffer.isBuffer(entry.data) ? entry.data : Buffer.from(entry.data, 'utf8');
+        const crc = crc32(data);
+
+        const deflated = deflateRawSync(data, { level: 9 });
+        const useDeflate = deflated.length < data.length;
+        const method = useDeflate ? 8 : 0;
+        const payload = useDeflate ? deflated : data;
+
+        const localHeader = Buffer.alloc(30);
+        localHeader.writeUInt32LE(0x04034B50, 0);
+        localHeader.writeUInt16LE(20, 4);            // version needed
+        localHeader.writeUInt16LE(0, 6);             // flags
+        localHeader.writeUInt16LE(method, 8);
+        localHeader.writeUInt16LE(DOS_TIME, 10);
+        localHeader.writeUInt16LE(DOS_DATE, 12);
+        localHeader.writeUInt32LE(crc, 14);
+        localHeader.writeUInt32LE(payload.length, 18);
+        localHeader.writeUInt32LE(data.length, 22);
+        localHeader.writeUInt16LE(nameBytes.length, 26);
+        localHeader.writeUInt16LE(0, 28);            // extra length
+
+        localParts.push(localHeader, nameBytes, payload);
+
+        const centralHeader = Buffer.alloc(46);
+        centralHeader.writeUInt32LE(0x02014B50, 0);
+        centralHeader.writeUInt16LE(20, 4);          // version made by
+        centralHeader.writeUInt16LE(20, 6);          // version needed
+        centralHeader.writeUInt16LE(0, 8);           // flags
+        centralHeader.writeUInt16LE(method, 10);
+        centralHeader.writeUInt16LE(DOS_TIME, 12);
+        centralHeader.writeUInt16LE(DOS_DATE, 14);
+        centralHeader.writeUInt32LE(crc, 16);
+        centralHeader.writeUInt32LE(payload.length, 20);
+        centralHeader.writeUInt32LE(data.length, 24);
+        centralHeader.writeUInt16LE(nameBytes.length, 28);
+        centralHeader.writeUInt16LE(0, 30);          // extra length
+        centralHeader.writeUInt16LE(0, 32);          // comment length
+        centralHeader.writeUInt16LE(0, 34);          // disk number
+        centralHeader.writeUInt16LE(0, 36);          // internal attrs
+        centralHeader.writeUInt32LE(0, 38);          // external attrs
+        centralHeader.writeUInt32LE(offset, 42);
+
+        centralParts.push(centralHeader, nameBytes);
+        offset += localHeader.length + nameBytes.length + payload.length;
+    }
+
+    const centralDirectory = Buffer.concat(centralParts);
+
+    const endRecord = Buffer.alloc(22);
+    endRecord.writeUInt32LE(0x06054B50, 0);
+    endRecord.writeUInt16LE(0, 4);                   // disk number
+    endRecord.writeUInt16LE(0, 6);                   // central dir start disk
+    endRecord.writeUInt16LE(entries.length, 8);
+    endRecord.writeUInt16LE(entries.length, 10);
+    endRecord.writeUInt32LE(centralDirectory.length, 12);
+    endRecord.writeUInt32LE(offset, 16);
+    endRecord.writeUInt16LE(0, 20);                  // comment length
+
+    return Buffer.concat([...localParts, centralDirectory, endRecord]);
+}
+
+const CONTENT_TYPES_BASE = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+%OVERRIDES%</Types>`;
+
+const ROOT_RELS = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
+</Relationships>`;
+
+/**
+ * Assembles a minimal .docx package around a word/document.xml payload.
+ *
+ * @param {string} documentXml - Complete word/document.xml content
+ * @param {{ numberingXml?: string|null }} [parts] - Optional extra parts
+ * @returns {Buffer} - .docx bytes
+ */
+export function buildMinimalDocx(documentXml, parts = {}) {
+    const overrides = [];
+    const documentRels = [];
+    const entries = [];
+
+    if (parts.numberingXml) {
+        overrides.push('  <Override PartName="/word/numbering.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml"/>\n');
+        documentRels.push('  <Relationship Id="rIdNum1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering" Target="numbering.xml"/>');
+    }
+
+    entries.push({ name: '[Content_Types].xml', data: CONTENT_TYPES_BASE.replace('%OVERRIDES%', overrides.join('')) });
+    entries.push({ name: '_rels/.rels', data: ROOT_RELS });
+    entries.push({
+        name: 'word/_rels/document.xml.rels',
+        data: `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+${documentRels.join('\n')}
+</Relationships>`
+    });
+    entries.push({ name: 'word/document.xml', data: documentXml });
+    if (parts.numberingXml) {
+        entries.push({ name: 'word/numbering.xml', data: parts.numberingXml });
+    }
+
+    return buildZip(entries);
+}

package/scripts/validate-fixtures-xsd.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Validates generated validation fixtures against the ECMA-376 transitional
+# wordprocessingml XSD using xmllint. Used by the nightly validation workflow
+# and runnable locally on any machine with curl, unzip, and xmllint.
+#
+# Usage: scripts/validate-fixtures-xsd.sh [fixtures-dir]
+set -euo pipefail
+
+FIXTURES_DIR="${1:-tmp/validation-docx}"
+CACHE_DIR="${OOXML_SCHEMA_DIR:-.cache/ooxml-schemas}"
+ECMA_ZIP_URL="https://ecma-international.org/wp-content/uploads/ECMA-376-4_5th_edition_december_2016.zip"
+XML_XSD_URL="https://www.w3.org/2001/xml.xsd"
+
+command -v xmllint >/dev/null || { echo "xmllint not found (install libxml2-utils)"; exit 1; }
+
+shopt -s nullglob
+fixtures=("$FIXTURES_DIR"/*.document.xml)
+if [ ${#fixtures[@]} -eq 0 ]; then
+  echo "No *.document.xml fixtures in $FIXTURES_DIR — run: node scripts/export-validation-fixtures.mjs"
+  exit 1
+fi
+
+if [ ! -f "$CACHE_DIR/wml.xsd" ]; then
+  echo "Downloading ECMA-376 Part 4 transitional schemas..."
+  mkdir -p "$CACHE_DIR"
+  curl -sSL --retry 3 -o "$CACHE_DIR/ecma376-4.zip" "$ECMA_ZIP_URL"
+  unzip -o -q "$CACHE_DIR/ecma376-4.zip" "OfficeOpenXML-XMLSchema-Transitional.zip" -d "$CACHE_DIR"
+  unzip -o -q "$CACHE_DIR/OfficeOpenXML-XMLSchema-Transitional.zip" -d "$CACHE_DIR"
+  curl -sSL --retry 3 -o "$CACHE_DIR/xml.xsd" "$XML_XSD_URL"
+  # ECMA's published XSDs import the xml namespace without a schemaLocation;
+  # point them at the local copy so xmllint can compile offline.
+  sed -i.bak 's|<xsd:import namespace="http://www.w3.org/XML/1998/namespace"/>|<xsd:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="xml.xsd"/>|' "$CACHE_DIR"/*.xsd
+  rm -f "$CACHE_DIR"/*.xsd.bak "$CACHE_DIR/ecma376-4.zip"
+fi
+
+xmllint --noout --schema "$CACHE_DIR/wml.xsd" "${fixtures[@]}"
+echo "XSD validation passed for ${#fixtures[@]} fixture(s)."