@ansonlai/docx-redline-js 0.7.2 → 0.8.0

package/AGENTS.md

@@ -11,8 +11,8 @@ or an installed plugin bundle to infer public behavior.
 | Edit or review a complete `.docx` | [Agent Fast Start](docs/AGENT_FAST_START.md) and the `docx-redline` CLI |
 | Build or update an agent skill/tool wrapper | [Skill Authoring Contract](docs/SKILL_AUTHORING.md), then [README wrapper example](README.md#example-agent-session-wrapper-development-only) |
 | Change paragraph/range reconciliation | `index.js` → `engine/oxml-engine.js` → selected `engine/*-mode.js` |
-| Change complete-document operations | `services/standalone-operation-runner.js` → `services/document-operation-*.js` |
-| Change DOCX ZIP or CLI behavior | `node/index.js`, `node/docx-document.js`, `node/cli.js` |
+| Change complete-document operations | `document/docx-document.js` → `services/standalone-operation-runner.js` → `services/document-operation-*.js` |
+| Change DOCX ZIP or CLI behavior | `document/zip-archive.js`, `node/index.js`, `node/docx-document.js`, `node/cli.js` |
 | Choose or add tests | Closest `tests/*.mjs`, then [Testing Guide](docs/TESTING.md) |
 | Understand ownership/dependencies | [Architecture](ARCHITECTURE.md) |
 
@@ -59,11 +59,13 @@ examples live in the
 
 ## Thin wrappers
 
-Wrap the CLI for shell hosts or `openDocx` from
-`@ansonlai/docx-redline-js/node` for byte-oriented Node hosts. A wrapper should
-inspect, translate narrow ergonomic inputs into canonical operations, call the
-facade once, and return its structured result. Do not reproduce ZIP handling,
-targeting, revision allocation, comments, numbering, validation, or rollback.
+Wrap the CLI for shell hosts or `openDocx` from `@ansonlai/docx-redline-js`
+(or `@ansonlai/docx-redline-js/bundle` for zero-dependency sandboxes, or
+`@ansonlai/docx-redline-js/node` for backward-compatible Node hosts) for
+byte-oriented hosts. A wrapper should inspect, translate narrow ergonomic inputs
+into canonical operations, call the facade once, and return its structured result.
+Do not reproduce ZIP handling, targeting, revision allocation, comments, numbering,
+validation, or rollback.
 
 The stateful wrapper in `examples/agent-session-wrapper.mjs` is a testable
 development demonstration only. It is excluded from package files and exports.
@@ -74,13 +76,16 @@ not belong in an ordinary editing prompt merely because the CLI supports them.
 ## Code map
 
 ```text
-index.js       host-independent public API
-core/          OOXML primitives, text views, targeting, validation
+index.js       host-independent public API & universal document facade
+adapters/      DOM/XML parser provider with automatic pure-JS fallback
+core/          OOXML primitives, text views, targeting, SHA-256, validation
+document/      universal Uint8Array DOCX facade & fflate ZIP container
 pipeline/      ingestion, diffing, Markdown, lists, serialization
 engine/        reconciliation modes and run-level mutation
 orchestration/ route planning and structural conversion
 services/      document operations, comments, receipts, artifacts
-node/          Node-only ZIP and whole-DOCX facade/CLI
+node/          Node CLI and backward-compatibility re-exports
+dist/          universal ESM and zero-dependency sandbox bundles
 tests/*.mjs    directly runnable suites
 ```
 

package/ARCHITECTURE.md

@@ -8,11 +8,12 @@ This repository contains only the publishable package surface:
 
 - `adapters/`
 - `core/`
+- `document/` (universal complete-DOCX facade & ZIP archive layer)
 - `engine/`
 - `pipeline/`
 - `services/`
 - `orchestration/`
-- `node/` (separate Node-only package facade)
+- `node/` (Node CLI & backward-compatibility facade)
 - `index.js`
 - `index.d.ts`
 - `dist/`
@@ -22,8 +23,9 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 ## 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.
+- Keep core logic and document-level operations host-independent (no Office.js globals, no Word API calls, no runtime Node built-ins like `node:zlib` or `node:crypto`).
+- Standardize complete-document packages on `Uint8Array` binary payloads, pure-JS SHA-256 revision tokens, and `fflate` ZIP container manipulation.
+- Reuse the same engine across Node.js, browsers, Cloudflare Workers, Deno, Bun, and sandboxed runtimes (e.g. n8n Code nodes).
 - Keep generated OOXML schema-safe through shared Word element creation and
   centralized revision metadata helpers.
 
@@ -37,7 +39,12 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 │   └── xml-adapter.js
 ├── core/
 │   ├── paragraph-text.js
+│   ├── sha256.js
 │   └── word-xml.js
+├── document/
+│   ├── docx-document.js
+│   ├── docx-document.d.ts
+│   └── zip-archive.js
 ├── engine/
 │   ├── oxml-engine.js
 │   ├── surgical-mode.js
@@ -63,16 +70,22 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 │   ├── cli.js
 │   ├── zip-archive.js
 │   └── index.js
+├── dist/
+│   ├── docx-redline-js.esm.js
+│   ├── docx-redline.bundle.js
+│   └── docx-redline.bundle.cjs
 ├── index.js
 └── index.d.ts
 ```
 
 ## Entry Points
 
-- `index.js`: primary host-independent exports for OOXML reconciliation.
+- `index.js`: primary host-independent exports for OOXML reconciliation and universal complete-document operations (`openDocx`, `DocxDocument`, `computePackageRevisionToken`).
+- `document/docx-document.js`: universal `Uint8Array`-based document facade and package-level operation runner.
+- `dist/docx-redline.bundle.js` / `dist/docx-redline.bundle.cjs`: zero-dependency standalone sandbox bundles, exported via `@ansonlai/docx-redline-js/bundle`.
 - `services/standalone-operation-runner.js`: stable complete-document XML
   operations, exported as `@ansonlai/docx-redline-js/standalone-runner`.
-- `node/index.js`: Node-only complete-DOCX buffer facade, exported as
+- `node/index.js`: Node-compatible complete-DOCX facade re-exports, exported as
   `@ansonlai/docx-redline-js/node`.
 - `bin/docx-redline.js`: CLI launcher; command implementation lives in
   `node/cli.js` and shared operation behavior lives in `services/`.
@@ -181,11 +194,18 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 - `services/document-inspection.js`
   - Read-only paragraphs/comments inventory with target identity, headings,
     revision authors, table context, and advisory visible numbering.
-- `node/docx-document.js`
-  - Transactional whole-DOCX editing, artifact wiring, validation, and rollback.
-    OOXML and package issues are classified as baseline/generated multisets, so
-    unchanged source defects remain diagnostics while new defects block writes.
-    This surface is excluded from the browser/root dependency graph.
+- `document/docx-document.js`
+  - Universal transactional whole-DOCX editing, artifact wiring, validation, and rollback.
+    Standardized on `Uint8Array` binary payloads and pure-JS SHA-256 revision tokens.
+    Exposes `openDocx`, `DocxDocument`, and `computePackageRevisionToken` directly across all runtimes.
+- `document/zip-archive.js`
+  - Universal, pure-JS ZIP archive reader and writer based on `fflate`. Operates on
+    `Uint8Array` byte arrays with zero Node built-ins (`node:zlib`, `Buffer`).
+- `core/sha256.js`
+  - Pure-JS synchronous implementation of FIPS 180-4 SHA-256 with zero dependencies,
+    enabling deterministic revision tokens in sandboxed runtimes without `node:crypto`.
+- `node/docx-document.js` and `node/zip-archive.js`
+  - Node-compatible re-exports maintaining `Buffer` compatibility for `@ansonlai/docx-redline-js/node`.
 - `node/cli.js` and `bin/docx-redline.js`
   - Cross-platform, JSON-only agent command boundary. Read commands never
     mutate; write commands require attribution, use package transactions, and

package/CHANGELOG.md

@@ -1,18 +1,73 @@
 # Changelog
 
-## Unreleased
+## 0.8.0
+
+### Universal Document Facade & Zero-Node Architecture
+
+- **Universal `DocxDocument` & `openDocx`:** Implemented complete-DOCX lifecycle operations
+  (`openDocx`, `doc.inspect()`, `doc.applyOperations()`, `doc.resolveRevisions()`, `doc.deleteComments()`,
+  `doc.toUint8Array()`, `doc.getRevisionToken()`) on standard `Uint8Array` in `document/docx-document.js`,
+  re-exported directly from `index.js`. Enables complete-document redline workflows in any JavaScript
+  runtime without Node.js dependencies.
+- **Pure-JS ZIP container (`fflate`):** Replaced `node:zlib` with lightweight, zero-dependency `fflate`
+  in `document/zip-archive.js`, providing cross-runtime raw DEFLATE / INFLATE compression and decompression
+  with full OOXML archive compatibility.
+- **Pure-JS FIPS 180-4 SHA-256:** Created zero-dependency, synchronous SHA-256 implementation in
+  `core/sha256.js`, removing `node:crypto` from package revision token calculations while retaining
+  exact deterministic hash parity with standard NIST vectors.
+- **Transparent XML DOM fallback:** Added `resolveDomParserConstructor()` and
+  `resolveXmlSerializerConstructor()` in `adapters/xml-adapter.js`, automatically utilizing native
+  `globalThis.DOMParser`/`globalThis.XMLSerializer` when present and falling back transparently to
+  `@xmldom/xmldom` in headless, server, edge, and sandbox environments without requiring manual provider setup.
+- **Zero-dependency sandbox bundles:** Configured `scripts/build.mjs` with `esbuild` (`platform: 'neutral'`)
+  to produce single-file, zero-dependency standalone bundles in both ESM (`dist/docx-redline.bundle.js`)
+  and CommonJS (`dist/docx-redline.bundle.cjs`), exported as `@ansonlai/docx-redline-js/bundle` for direct
+  use in workflow engines (e.g., n8n Code nodes), Cloudflare Workers, AWS Lambda, Deno, and QuickJS sandboxes.
+- **Strict runtime boundary enforcement:** Removed `node:zlib` and `node:crypto` from allowed external
+  imports in `tests/no_word_api_index_check.mjs`. Automated sandbox isolation tests
+  (`tests/sandbox_bundle_isolation_tests.mjs`) verify zero Node built-in imports and full document
+  reconciliation in restricted VM contexts without `process`, `Buffer`, or `require`.
+- **Backward compatibility:** Preserved full API and `Buffer` compatibility for `@ansonlai/docx-redline-js/node`
+  consumers and `doc.toBuffer()`.
+
+## 0.7.2
+
+### Agent Surface Simplification
+
+- **Extraction-first golden path:** Re-established the single deterministic two-turn
+  "extract-then-apply" sequence as the default agent workflow across `AGENTS.md`,
+  `docs/AGENT_FAST_START.md`, and `docs/SKILL_AUTHORING.md`. Eliminates the
+  upfront "choice tax" and model deliberation overhead.
+- **Localized replacements after inspection:** Decoupled localized patching from
+  speculation. Agents inspect the target paragraph first, then supply compact
+  `replacements` instructions, achieving 60.6%–90.8% payload reductions without
+  speculative ambiguity risk.
+- **Computed success gate:** Consolidated standard success verification onto
+  `completion: true` and non-null `outputPath`, removing multi-field verification
+  checklists from primary prompts while retaining full `change` audit evidence.
+- **Advanced features relocated:** Speculative 1-turn apply, directional context
+  windows (`--context-range`), and anchor diagnostics are relocated to
+  `docs/AGENT_KNOWLEDGE_BASE.md` and CLI help as opt-in harness policies.
+- **Observed-state restoration:** Restructured restoration as a clean request-
+  or hint-driven branch (`--view rejected` or `selection.hint`) rather than an
+  upfront classification decision.
+- **Empirical surface evaluation:** Added synthetic replay benchmark
+  (`npm run benchmark:agent-surface`) and validation report documenting 100%
+  first-attempt task correctness and payload savings across three workflow policies.
+
+## 0.7.1
+
+### Reliability and Discovery Refinements
 
 - Localized replacement matching now tries exact case-sensitive text first,
   then a narrow ASCII-space/non-breaking-space equivalent match. Ambiguous
   equivalent matches still fail closed, and unchanged boundary NBSPs are
   retained to avoid incidental whitespace redlines.
-
 - Added a narrow single-paragraph restore shortcut. A restore with a strong
   rejected-view target may omit `modified` for verbatim restoration or provide
   exact `replacements`; the CLI exposes the same path through `apply --restore
   --target-id ID`. Ranges, captures, weak targets, and inferred companion
   content remain excluded.
-
 - Fixed rejected-view restore receipts so `resolvedTarget` text, fingerprint,
   revision view, and match diagnostics describe the view actually used to
   resolve the target.

package/adapters/xml-adapter.js

@@ -1,64 +1,92 @@
-/**
- * XML adapter for parser/serializer portability.
- *
- * Default behavior uses browser-provided DOMParser/XMLSerializer.
- * Consumers can override these constructors for non-browser runtimes.
+/**
+ * XML adapter for parser/serializer portability.
+ *
+ * Transparently uses browser-provided DOMParser/XMLSerializer when available in
+ * standard web runtimes, automatically falling back to pure-JS @xmldom/xmldom in
+ * Node.js and sandbox environments. Consumers can also explicitly override these
+ * constructors via configureXmlProvider.
  */
 
+import { DOMParser as XmlDomParser, XMLSerializer as XmlDomSerializer } from '@xmldom/xmldom';
 import { warn as logWarning, error as logError } from './logger.js';
 
-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}
- */
+let _DOMParser = null;
+let _XMLSerializer = null;
+
+/**
+ * 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 ('DOMParser' in options) _DOMParser = options.DOMParser;
+    if ('XMLSerializer' in options) _XMLSerializer = options.XMLSerializer;
+}
+
+/**
+ * Resolves the active DOMParser constructor.
+ *
+ * Priority order:
+ * 1. Explicitly configured constructor (via configureXmlProvider)
+ * 2. Host environment native DOMParser (globalThis.DOMParser)
+ * 3. Pure-JS @xmldom/xmldom fallback
+ *
+ * @returns {typeof DOMParser}
+ */
+export function resolveDomParserConstructor() {
+    return _DOMParser || globalThis.DOMParser || XmlDomParser;
+}
+
+/**
+ * Resolves the active XMLSerializer constructor.
+ *
+ * Priority order:
+ * 1. Explicitly configured constructor (via configureXmlProvider)
+ * 2. Host environment native XMLSerializer (globalThis.XMLSerializer)
+ * 3. Pure-JS @xmldom/xmldom fallback
+ *
+ * @returns {typeof XMLSerializer}
+ */
+export function resolveXmlSerializerConstructor() {
+    return _XMLSerializer || globalThis.XMLSerializer || XmlDomSerializer;
+}
+
+/**
+ * Creates a parser instance.
+ *
+ * @param {Object} [options={}] - Parser options (e.g. { onError } for xmldom)
+ * @returns {DOMParser}
+ */
 export function createParser(options = {}) {
-    if (!_DOMParser && globalThis.DOMParser) {
-        _DOMParser = globalThis.DOMParser;
-    }
-    if (!_DOMParser) {
-        throw new Error('DOMParser is not configured. Call configureXmlProvider({ DOMParser, XMLSerializer }) first.');
-    }
-    return new _DOMParser(options);
-}
-
-/**
- * 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}
- */
+    const ParserCtor = resolveDomParserConstructor();
+    if (!ParserCtor) {
+        throw new Error('DOMParser is not configured and no fallback XML parser is available.');
+    }
+    return new ParserCtor(options);
+}
+
+/**
+ * Creates a serializer instance.
+ *
+ * @returns {XMLSerializer}
+ */
+export function createSerializer() {
+    const SerializerCtor = resolveXmlSerializerConstructor();
+    if (!SerializerCtor) {
+        throw new Error('XMLSerializer is not configured and no fallback XML serializer is available.');
+    }
+    return new SerializerCtor();
+}
+
+/**
+ * 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 result = parseOoxmlSafe(xmlString, contentType);
     if (result.error) {

package/core/sha256.js

@@ -0,0 +1,120 @@
+/**
+ * Pure-JS synchronous SHA-256 (FIPS 180-4) implementation.
+ *
+ * Self-contained, deterministic, and free from Node.js or browser crypto built-ins.
+ * Accepts string, Uint8Array, Buffer, or ArrayBuffer and returns a 64-character hex string.
+ */
+
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2
+]);
+
+const textEncoder = new TextEncoder();
+
+/**
+ * Computes the SHA-256 digest of binary or text data.
+ *
+ * @param {Uint8Array|ArrayBuffer|ArrayBufferView|string} input - Input data to hash
+ * @returns {string} 64-character lowercase hex string
+ */
+export function sha256(input) {
+    let bytes;
+    if (typeof input === 'string') {
+        bytes = textEncoder.encode(input);
+    } else if (input instanceof Uint8Array) {
+        bytes = input;
+    } else if (input instanceof ArrayBuffer) {
+        bytes = new Uint8Array(input);
+    } else if (ArrayBuffer.isView(input)) {
+        bytes = new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+    } else {
+        throw new TypeError('sha256 input must be a string, Uint8Array, Buffer, or ArrayBuffer.');
+    }
+
+    const byteLen = bytes.length;
+    const bitLen = byteLen * 8;
+
+    // Pad length: input + 1 (0x80) + zeros + 8 bytes (64-bit length) to multiple of 64 bytes
+    const paddedLen = Math.ceil((byteLen + 9) / 64) * 64;
+    const padded = new Uint8Array(paddedLen);
+    padded.set(bytes, 0);
+    padded[byteLen] = 0x80;
+
+    const dataView = new DataView(padded.buffer, padded.byteOffset, padded.byteLength);
+    // Write 64-bit big-endian length in bits
+    const highBits = Math.floor(bitLen / 0x100000000);
+    const lowBits = (bitLen >>> 0);
+    dataView.setUint32(paddedLen - 8, highBits, false);
+    dataView.setUint32(paddedLen - 4, lowBits, false);
+
+    // Initial hash values
+    let h0 = 0x6a09e667;
+    let h1 = 0xbb67ae85;
+    let h2 = 0x3c6ef372;
+    let h3 = 0xa54ff53a;
+    let h4 = 0x510e527f;
+    let h5 = 0x9b05688c;
+    let h6 = 0x1f83d9ab;
+    let h7 = 0x5be0cd19;
+
+    const W = new Uint32Array(64);
+
+    for (let offset = 0; offset < paddedLen; offset += 64) {
+        for (let t = 0; t < 16; t++) {
+            W[t] = dataView.getUint32(offset + t * 4, false);
+        }
+        for (let t = 16; t < 64; t++) {
+            const w15 = W[t - 15];
+            const s0 = ((w15 >>> 7) | (w15 << 25)) ^ ((w15 >>> 18) | (w15 << 14)) ^ (w15 >>> 3);
+            const w2 = W[t - 2];
+            const s1 = ((w2 >>> 17) | (w2 << 15)) ^ ((w2 >>> 19) | (w2 << 13)) ^ (w2 >>> 10);
+            W[t] = (W[t - 16] + s0 + W[t - 7] + s1) | 0;
+        }
+
+        let a = h0;
+        let b = h1;
+        let c = h2;
+        let d = h3;
+        let e = h4;
+        let f = h5;
+        let g = h6;
+        let h = h7;
+
+        for (let t = 0; t < 64; t++) {
+            const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const ch = (e & f) ^ (~e & g);
+            const temp1 = (h + S1 + ch + K[t] + W[t]) | 0;
+            const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const temp2 = (S0 + maj) | 0;
+
+            h = g;
+            g = f;
+            f = e;
+            e = (d + temp1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (temp1 + temp2) | 0;
+        }
+
+        h0 = (h0 + a) | 0;
+        h1 = (h1 + b) | 0;
+        h2 = (h2 + c) | 0;
+        h3 = (h3 + d) | 0;
+        h4 = (h4 + e) | 0;
+        h5 = (h5 + f) | 0;
+        h6 = (h6 + g) | 0;
+        h7 = (h7 + h) | 0;
+    }
+
+    const hex = n => (n >>> 0).toString(16).padStart(8, '0');
+    return hex(h0) + hex(h1) + hex(h2) + hex(h3) + hex(h4) + hex(h5) + hex(h6) + hex(h7);
+}