@ansonlai/docx-redline-js 0.1.0

package/AGENTS.md

@@ -0,0 +1,176 @@
+# AGENTS.md - AI Agent Quick Reference
+
+> This file helps AI coding agents understand @ansonlai/docx-redline-js quickly.
+> Read this instead of exploring the full source tree.
+
+## What This Package Does
+
+Converts text/markdown edits into valid Office Open XML (OOXML) with Word-native tracked changes. Feed it original OOXML + desired text and it returns OOXML with `w:ins`/`w:del` revision markup.
+
+## Conceptual Model
+
+```
+Input: (paragraph OOXML, original text, modified text, options)
+  |
+  v
+Engine routes to: format-only | surgical | reconstruction | list | table mode
+  |
+  v
+Output: { oxml: string, hasChanges: boolean, warnings?: string[] }
+```
+
+The engine works at paragraph scope. For full-document operations, callers iterate paragraph targets or use the standalone operation runner.
+
+## Entry Point
+
+```js
+import { applyRedlineToOxml, configureXmlProvider } from '@ansonlai/docx-redline-js';
+```
+
+`index.js` is the single package entry point.
+
+## Required Setup (Node.js only)
+
+```js
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+configureXmlProvider({ DOMParser, XMLSerializer });
+```
+
+Browsers have native DOM APIs, so no provider injection is typically needed.
+
+## Key APIs by Use Case
+
+### Apply a text edit with tracked changes
+
+```js
+const result = await applyRedlineToOxml(oxml, originalText, modifiedText, {
+  generateRedlines: true,
+  author: 'Agent Name'
+});
+```
+
+### Apply a text edit without tracked changes
+
+```js
+const result = await applyRedlineToOxml(oxml, originalText, modifiedText, {
+  generateRedlines: false
+});
+```
+
+### Convert OOXML to readable text or markdown
+
+```js
+import { ingestWordOoxmlToPlainText, ingestWordOoxmlToMarkdown } from '@ansonlai/docx-redline-js';
+const plainText = ingestWordOoxmlToPlainText(documentXml);
+const markdown = ingestWordOoxmlToMarkdown(documentXml);
+```
+
+### Add a comment to OOXML
+
+```js
+import { injectCommentsIntoOoxml } from '@ansonlai/docx-redline-js';
+const result = injectCommentsIntoOoxml(paragraphOoxml, [
+  { text: 'Review this clause', targetText: 'force majeure', author: 'Agent' }
+]);
+```
+
+### Apply multiple operations to full document XML
+
+```js
+import { applyOperationToDocumentXml } from '@ansonlai/docx-redline-js/services/standalone-operation-runner.js';
+const result = await applyOperationToDocumentXml(documentXml, operation, options);
+```
+
+### Convert paragraph text into a Word list
+
+```js
+const result = await applyRedlineToOxml(oxml, 'Item text', '1. Item text', {
+  generateRedlines: true
+});
+```
+
+### Reconcile a table
+
+```js
+import { reconcileMarkdownTableOoxml } from '@ansonlai/docx-redline-js';
+const result = await reconcileMarkdownTableOoxml(tableOoxml, originalText, markdownTable);
+```
+
+## Module Map
+
+```
+index.js
+adapters/
+  config.js
+  xml-adapter.js
+  logger.js
+core/
+  types.js
+  paragraph-targeting.js
+  list-targeting.js
+  table-targeting.js
+engine/
+  oxml-engine.js
+  surgical-mode.js
+  reconstruction-mode.js
+  format-application.js
+  formatting-removal.js
+  table-mode.js
+pipeline/
+  pipeline.js
+  ingestion.js
+  ingestion-export.js
+  diff-engine.js
+  markdown-processor.js
+  serialization.js
+  list-generation.js
+services/
+  standalone-operation-runner.js
+  standalone-docx-plumbing.js
+  numbering-helpers.js
+  comment-engine.js
+  table-reconciliation.js
+  package-builder.js
+orchestration/
+  route-plan.js
+  list-markdown.js
+  list-structural-fallback.js
+```
+
+## Common Patterns
+
+### Options shape
+
+```js
+{
+  generateRedlines: true,
+  author: 'Name'
+}
+```
+
+### Typical return shape
+
+```js
+{
+  oxml: string,
+  hasChanges: boolean,
+  warnings?: string[],
+  numberingXml?: string,
+  useNativeApi?: boolean
+}
+```
+
+### OOXML wrapping for Word insertOoxml scenarios
+
+```js
+import { wrapInDocumentFragment } from '@ansonlai/docx-redline-js';
+const wrapped = wrapInDocumentFragment(rawOoxml, { includeNumbering: true, numberingXml });
+```
+
+## Gotchas
+
+1. Call `configureXmlProvider` first in Node.js.
+2. `applyRedlineToOxml` is async.
+3. Paragraph APIs expect paragraph-level OOXML, not full `word/document.xml` in all cases.
+4. List operations may return `numberingXml` that must be merged into package parts.
+5. `useNativeApi: true` means standalone mode cannot fully handle that operation path.

package/ARCHITECTURE.md

@@ -0,0 +1,121 @@
+# Reconciliation Core Architecture
+
+This document describes the standalone, host-agnostic OOXML reconciliation package and how to work inside it safely.
+
+## Scope
+
+This repository contains only the publishable package surface:
+
+- `adapters/`
+- `core/`
+- `engine/`
+- `pipeline/`
+- `services/`
+- `orchestration/`
+- `index.js`
+- `standalone.js`
+
+No Word add-in entrypoints or host-specific integration layers are part of this package.
+
+## Goals
+
+- Preserve Word-compatible redlines by editing OOXML directly.
+- Keep core logic host-independent (no Office.js globals, no Word API calls).
+- Reuse the same engine in browser, Node.js, and other JavaScript runtimes.
+
+## Folder Layout
+
+```text
+.
+├── adapters/
+│   ├── config.js
+│   ├── logger.js
+│   └── xml-adapter.js
+├── core/
+├── engine/
+│   └── formatting-removal.js
+├── orchestration/
+├── pipeline/
+├── services/
+│   ├── numbering-helpers.js
+│   ├── standalone-docx-plumbing.js
+│   └── standalone-operation-runner.js
+├── index.js
+└── standalone.js
+```
+
+## Entry Points
+
+- `index.js`: primary package entrypoint.
+- `standalone.js`: compatibility alias that re-exports from `index.js` (deprecated for new imports).
+
+## Module Responsibilities
+
+- `adapters/config.js`
+  - Runtime configuration for defaults (`setDefaultAuthor`, `getDefaultAuthor`, `setPlatform`, `getPlatform`).
+- `adapters/xml-adapter.js`
+  - XML parser/serializer injection for browser or Node.js runtimes.
+- `adapters/logger.js`
+  - Runtime logger injection and shared logging methods.
+- `core/*`
+  - Shared types, OOXML identity helpers, target resolution, list/table targeting heuristics, and XML query helpers.
+- `engine/oxml-engine.js`
+  - Main reconciliation router and mode selection.
+- `engine/formatting-removal.js`
+  - Shared formatting removal and highlight helpers.
+- `pipeline/*`
+  - Ingestion, markdown preprocessing, diffing, patching, and serialization stages.
+- `services/numbering-helpers.js`
+  - Dynamic numbering ID allocation, numbering payload remapping, and schema-order-safe numbering merges.
+- `services/standalone-docx-plumbing.js`
+  - Package-level extraction/wiring/validation for `word/document.xml`, `word/numbering.xml`, and `word/comments.xml`.
+- `services/standalone-operation-runner.js`
+  - Host-agnostic operation bridge for `redline`, `highlight`, and `comment` workflows.
+- `orchestration/*`
+  - Route planning and list fallback orchestration utilities.
+
+## End-to-End Flow
+
+1. Caller imports from `index.js` (or legacy `standalone.js` alias).
+2. Caller configures XML provider/logger/defaults when needed via `adapters/*`.
+3. Caller invokes reconciliation APIs (`applyRedlineToOxml`, operation runner, ingestion/export helpers).
+4. `engine/oxml-engine.js` routes to format, table, list, surgical, or reconstruction flows.
+5. Pipeline/services return OOXML and optional package artifacts (`numberingXml`, comments payloads).
+6. Caller writes resulting XML back to package/document boundaries.
+
+## Public Surfaces
+
+- Primary: `index.js`
+- Compatibility alias: `standalone.js` (deprecated)
+
+Keep exports centralized through `index.js`; maintain `standalone.js` only for backward compatibility.
+
+## Build Output
+
+`npm run build` generates CDN-ready ESM bundles under `dist/`:
+
+- `dist/docx-redline-js.esm.js`
+- `dist/docx-redline-js.esm.js.map`
+- `dist/docx-redline-js.esm.min.js`
+- `dist/docx-redline-js.esm.min.js.map`
+
+The bundle inlines `diff-match-patch` and keeps `@xmldom/xmldom` external.
+
+## Testing
+
+- `npm test`
+  - Runs the package test runner (`scripts/run-tests.mjs`) against all `tests/*.mjs` except setup helpers.
+- `npm run test:isolation`
+  - Runs boundary checks for Word API markers and dependency-graph isolation.
+
+Use these checks before publishing or tagging.
+
+## Fast Orientation For Contributors
+
+Use this sequence to understand or modify behavior without reading everything:
+
+1. Start at `index.js` to locate the exported API.
+2. Follow exports into `engine/oxml-engine.js` or relevant `services/*` module.
+3. For targeting bugs, inspect `core/paragraph-targeting.js`, `core/list-targeting.js`, and `core/table-targeting.js`.
+4. For package wiring issues, inspect `services/standalone-docx-plumbing.js`.
+5. For numbering/list issues, inspect `services/numbering-helpers.js` and orchestration list-fallback modules.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anson Lai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# @ansonlai/docx-redline-js
+
+Host-independent OOXML reconciliation engine for `.docx` manipulation with track changes (redlines).
+
+Converts AI-generated or programmatic text/markdown edits into valid Office Open XML (OOXML) with `w:ins`/`w:del` revision markup that Microsoft Word renders as native tracked changes.
+
+## Features
+
+- Text reconciliation with word-level diffing and native-looking redlines
+- Formatting updates (bold, italic, underline, strikethrough) via surgical `w:rPrChange`
+- Lists: generate and edit real Word lists (`w:numPr`) from markdown
+- Tables: virtual-grid diffing for cell-level edits with merge safety
+- Comments: inject OOXML comments anchored to text ranges
+- Highlights: apply highlight colors to runs
+- Markdown and OOXML conversion in both directions
+- Package plumbing helpers for numbering.xml, comments.xml, content types, and relationships
+- Zero host dependencies: works in Node.js, browsers, Deno, and similar JS runtimes with DOM parsing support
+
+## Install
+
+### npm / Node.js
+
+```bash
+npm install @ansonlai/docx-redline-js
+```
+
+### CDN (browser `<script type="module">`)
+
+```html
+<script type="module">
+  import { applyRedlineToOxml } from 'https://esm.sh/@ansonlai/docx-redline-js';
+</script>
+```
+
+Or use the pre-bundled file (no import map needed, `diff-match-patch` is inlined):
+
+```html
+<script type="module">
+  import { applyRedlineToOxml } from 'https://cdn.jsdelivr.net/npm/@ansonlai/docx-redline-js/dist/docx-redline-js.esm.min.js';
+</script>
+```
+
+### Local git clone
+
+```bash
+git clone https://github.com/YOUR_ORG/docx-redline-js.git
+```
+
+```js
+import { applyRedlineToOxml } from './docx-redline-js/index.js';
+```
+
+## Quick Start
+
+### Node.js
+
+```js
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import {
+  configureXmlProvider,
+  setDefaultAuthor,
+  applyRedlineToOxml
+} from '@ansonlai/docx-redline-js';
+
+configureXmlProvider({ DOMParser, XMLSerializer });
+setDefaultAuthor('My App');
+
+const result = await applyRedlineToOxml(
+  paragraphOoxml,
+  'Original sentence.',
+  'Updated sentence.',
+  { generateRedlines: true, author: 'Editor' }
+);
+
+console.log(result.hasChanges);
+console.log(result.oxml);
+```
+
+### Browser
+
+```js
+import {
+  setDefaultAuthor,
+  applyRedlineToOxml
+} from '@ansonlai/docx-redline-js';
+
+setDefaultAuthor('Browser Editor');
+
+const result = await applyRedlineToOxml(oxml, original, modified, {
+  generateRedlines: true
+});
+```
+
+## API Reference
+
+### Configuration (call once at startup)
+
+| Function | Purpose |
+|----------|---------|
+| `configureXmlProvider({ DOMParser, XMLSerializer })` | Inject XML parser. Required in Node.js; browsers usually provide native support. |
+| `configureLogger({ log, warn, error })` | Replace default console logger. |
+| `setDefaultAuthor(name)` | Set fallback track-change author (default: `'Author'`). |
+| `setPlatform(label)` | Set platform label for diagnostics (default: `'Unknown'`). |
+
+### Engine (primary reconciliation APIs)
+
+| Function | Purpose |
+|----------|---------|
+| `applyRedlineToOxml(oxml, original, modified, options)` | Core engine entry point for text/markdown reconciliation with optional redlines. |
+| `applyRedlineToOxmlWithListFallback(oxml, original, modified, options)` | Core engine with automatic single-line list structural fallback. |
+| `reconcileMarkdownTableOoxml(oxml, original, markdownTable, options)` | Table-specific reconciliation helper. |
+
+### Pipeline (lower-level access)
+
+| Function | Purpose |
+|----------|---------|
+| `ReconciliationPipeline` | Direct pipeline access (ingest, diff, patch, serialize). |
+| `ingestWordOoxmlToPlainText(oxml)` | Extract plain text from OOXML. |
+| `ingestWordOoxmlToMarkdown(oxml)` | Convert OOXML to markdown. |
+| `ingestOoxml(oxml)` | Flatten OOXML into an internal run model with offsets. |
+| `preprocessMarkdown(text)` | Normalize markdown and extract format hints. |
+
+### Services
+
+| Function | Purpose |
+|----------|---------|
+| `injectCommentsIntoOoxml(oxml, comments, options)` | Add comments anchored to text ranges. |
+| `generateTableOoxml(headers, rows, options)` | Generate a `w:tbl` from tabular data. |
+| `createDynamicNumberingIdState(numberingXml)` | Allocate numbering IDs without collisions. |
+| `ensureNumberingArtifactsInZip(zip, numberingXml)` | Merge numbering artifacts into a `.docx` package. |
+| `ensureCommentsArtifactsInZip(zip, commentsXml)` | Merge comments artifacts into a `.docx` package. |
+| `validateDocxPackage(zip)` | Validate `.docx` structural consistency. |
+
+### Deep Imports
+
+For advanced usage, import specific submodules:
+
+```js
+import { applyOperationToDocumentXml } from '@ansonlai/docx-redline-js/services/standalone-operation-runner.js';
+import { getParagraphText } from '@ansonlai/docx-redline-js/core/paragraph-targeting.js';
+```
+
+## Working With `.docx` Files
+
+This package operates on OOXML strings (XML parts inside `.docx` zip archives), not raw `.docx` binaries.
+
+Typical flow:
+
+1. Extract the `.docx` zip (for example with JSZip, fflate, or similar)
+2. Read `word/document.xml`
+3. Apply reconciliation APIs to XML strings
+4. Merge numbering/comments artifacts when needed
+5. Write the archive back to a `.docx` file
+
+```js
+import JSZip from 'jszip';
+import {
+  configureXmlProvider,
+  applyRedlineToOxml,
+  ensureNumberingArtifactsInZip,
+  validateDocxPackage
+} from '@ansonlai/docx-redline-js';
+
+const zip = await JSZip.loadAsync(docxBuffer);
+const documentXml = await zip.file('word/document.xml').async('string');
+
+// Apply edits with applyRedlineToOxml(...)
+// Merge artifacts with ensureNumberingArtifactsInZip(...) as needed
+
+const output = await zip.generateAsync({ type: 'nodebuffer' });
+```
+
+## Architecture
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for module layout, data flow, and contributor guidance.
+
+See [AGENTS.md](./AGENTS.md) for a concise reference for AI coding agents.

package/adapters/config.js

@@ -0,0 +1,43 @@
+/**
+ * Configurable runtime defaults for the reconciliation core.
+ * Callers can set these during bootstrap.
+ */
+
+let _defaultAuthor = 'Author';
+let _platform = 'Unknown';
+
+/**
+ * Set the default track-change author for revision metadata.
+ *
+ * @param {string} author
+ */
+export function setDefaultAuthor(author) {
+    _defaultAuthor = typeof author === 'string' && author.trim() ? author.trim() : 'Author';
+}
+
+/**
+ * Get the current default track-change author.
+ *
+ * @returns {string}
+ */
+export function getDefaultAuthor() {
+    return _defaultAuthor;
+}
+
+/**
+ * Set the platform identifier (e.g. 'Win32', 'Mac', 'OfficeOnline').
+ *
+ * @param {string} platform
+ */
+export function setPlatform(platform) {
+    _platform = typeof platform === 'string' && platform.trim() ? platform.trim() : 'Unknown';
+}
+
+/**
+ * Get the current platform identifier.
+ *
+ * @returns {string}
+ */
+export function getPlatform() {
+    return _platform;
+}

package/adapters/logger.js

@@ -0,0 +1,89 @@
+/**
+ * Logger adapter for reconciliation modules.
+ */
+
+let _logger = console;
+
+const LEVELS = Object.freeze({
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3
+});
+
+const DEFAULT_LOG_LEVEL = (() => {
+    const isProd = typeof process !== 'undefined' && process?.env?.NODE_ENV === 'production';
+    return isProd ? 'warn' : 'info';
+})();
+
+let _logLevel = DEFAULT_LOG_LEVEL;
+
+function normalizeLogLevel(level) {
+    const normalized = String(level || '').toLowerCase();
+    return Object.prototype.hasOwnProperty.call(LEVELS, normalized) ? normalized : _logLevel;
+}
+
+function isEnabled(level) {
+    return LEVELS[_logLevel] >= LEVELS[level];
+}
+
+/**
+ * Configures logger implementation.
+ *
+ * @param {{log?: Function, warn?: Function, error?: Function}} logger - Logger object
+ * @param {{ level?: 'silent'|'error'|'warn'|'info' }} [options={}] - Logger options
+ */
+export function configureLogger(logger, options = {}) {
+    _logger = logger || console;
+    if (options.level) {
+        _logLevel = normalizeLogLevel(options.level);
+    }
+}
+
+/**
+ * Sets the minimum log level for reconciliation logs.
+ *
+ * @param {'silent'|'error'|'warn'|'info'} level - Desired log level
+ */
+export function setLogLevel(level) {
+    _logLevel = normalizeLogLevel(level);
+}
+
+/**
+ * Gets current logger level.
+ *
+ * @returns {'silent'|'error'|'warn'|'info'}
+ */
+export function getLogLevel() {
+    return _logLevel;
+}
+
+/**
+ * Log passthrough.
+ *
+ * @param {...any} args - Log args
+ */
+export function log(...args) {
+    if (!isEnabled('info')) return;
+    (_logger.log || (() => { }))(...args);
+}
+
+/**
+ * Warn passthrough.
+ *
+ * @param {...any} args - Warn args
+ */
+export function warn(...args) {
+    if (!isEnabled('warn')) return;
+    (_logger.warn || (() => { }))(...args);
+}
+
+/**
+ * Error passthrough.
+ *
+ * @param {...any} args - Error args
+ */
+export function error(...args) {
+    if (!isEnabled('error')) return;
+    (_logger.error || (() => { }))(...args);
+}

package/adapters/xml-adapter.js

@@ -0,0 +1,74 @@
+/**
+ * XML adapter for parser/serializer portability.
+ *
+ * Default behavior uses browser-provided DOMParser/XMLSerializer.
+ * Consumers can override these constructors for non-browser runtimes.
+ */
+
+let _DOMParser = globalThis.DOMParser;
+let _XMLSerializer = globalThis.XMLSerializer;
+
+/**
+ * Configures XML provider constructors.
+ *
+ * @param {Object} [options={}] - Provider overrides
+ * @param {typeof DOMParser} [options.DOMParser] - DOMParser constructor
+ * @param {typeof XMLSerializer} [options.XMLSerializer] - XMLSerializer constructor
+ */
+export function configureXmlProvider(options = {}) {
+    if (options.DOMParser) _DOMParser = options.DOMParser;
+    if (options.XMLSerializer) _XMLSerializer = options.XMLSerializer;
+}
+
+/**
+ * Creates a parser instance.
+ *
+ * @returns {DOMParser}
+ */
+export function createParser() {
+    if (!_DOMParser && globalThis.DOMParser) {
+        _DOMParser = globalThis.DOMParser;
+    }
+    if (!_DOMParser) {
+        throw new Error('DOMParser is not configured. Call configureXmlProvider({ DOMParser, XMLSerializer }) first.');
+    }
+    return new _DOMParser();
+}
+
+/**
+ * Creates a serializer instance.
+ *
+ * @returns {XMLSerializer}
+ */
+export function createSerializer() {
+    if (!_XMLSerializer && globalThis.XMLSerializer) {
+        _XMLSerializer = globalThis.XMLSerializer;
+    }
+    if (!_XMLSerializer) {
+        throw new Error('XMLSerializer is not configured. Call configureXmlProvider({ DOMParser, XMLSerializer }) first.');
+    }
+    return new _XMLSerializer();
+}
+
+/**
+ * Parses XML text into a DOM document.
+ *
+ * @param {string} xmlString - XML string
+ * @param {string} [contentType='text/xml'] - MIME type
+ * @returns {Document}
+ */
+export function parseXml(xmlString, contentType = 'text/xml') {
+    const parser = createParser();
+    return parser.parseFromString(xmlString, contentType);
+}
+
+/**
+ * Serializes a node to XML text.
+ *
+ * @param {Node} node - Node to serialize
+ * @returns {string}
+ */
+export function serializeXml(node) {
+    const serializer = createSerializer();
+    return serializer.serializeToString(node);
+}