@ansonlai/docx-redline-js 0.7.1 → 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) |
 
@@ -21,82 +21,71 @@ specific advanced operation, API, or recovery topic you need.
 
 ## Ordinary document edits
 
-For a literal mechanical edit with known old and new text, try one fail-closed
-apply call. When global matching is too broad, use a longer, fairly unique
-nearby phrase plus a directional range:
-
-```bash
-docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-```
-
-Generic or repeated anchors widen the unioned scope and may return
-`AMBIGUOUS_TARGET`, costing a recovery turn. On success, treat
-`results[i].change.context.anchorMatchCount > 1` as a signal to confirm the
-returned location and excerpts.
-
-For semantic drafting, inspect once and apply once. With a structured wrapper,
-use revision-bound handles. For shell-only work, use serializer-backed stdin:
+Use one focused extraction and one apply call. With a structured wrapper, use
+its revision-bound target handles. For shell-only work, use serializer-backed
+stdin and the explicit agent profile:
 
 ```bash
 docx-redline extract contract.docx --search "termination" --around 3
 node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
 ```
 
-A single deleted paragraph found in rejected view can be restored verbatim with
-`apply --restore --target-id ID`; add one `--find`/`--replace` pair for a small
-exact correction. This shortcut does not infer ranges or companion paragraphs.
-
-For every ordinary text operation, `modified` is the complete desired
-accepted-view content. Copy inspected `exactText` verbatim and include
-`paragraphId` or `fingerprint`. Independent strong targets are bound against the
-batch-start document, so do not manually sort around structural edits.
-Consolidate incompatible writes to the same source; use captures for intentional
-created-content dependencies.
-
-Require `completion: true`, `written: true`, a non-null output path, and no
-per-operation errors. Localized edits also require
-`results[i].change.committed: true`, `finalDisposition: "applied"`, and
-`verification.acceptedViewMatchesCompiledText: true`. Follow
+Retain inspected `exactText` for drafting and target with its compact
+`paragraphId` plus `fingerprint`. Use complete `modified` text for a broad
+semantic revision; for a small literal change, use `replacements` so the apply
+payload need not repeat the whole paragraph. Independent strong targets bind to the batch start, so do
+not manually sort around structural edits. Consolidate incompatible writes to
+one source; use captures only for intentional created-content dependencies.
+
+If the user requests restoration, search `--view rejected` directly. Otherwise
+follow `selection.hint` if extraction identifies an alternate revision view.
+Restore only the inspected strong target; do not infer adjacent content.
+
+Require `completion: true` and a non-null output path. Follow
 `error.recovery.action` and `retryPlan`; never retry unchanged failed arguments.
-Follow `selection.hint` for restorable text. Do not accept/reject another
-reviewer's work or remove comments without explicit user authorization. The
-source is never overwritten unless `--in-place` is explicit.
+Do not accept/reject another reviewer's work or remove comments without explicit
+user authorization. The source is never overwritten unless `--in-place` is
+explicit.
 
 The agent profile preserves progressive execution and the ordinary revision
 policy. Add `--atomic` or `--existing-revisions slice-cross-author` only when
 that policy is intended, and confirm the resolved `effectiveOptions`.
 
-Advanced restore, rejected-view insertion, list, table, formatting, comments,
-revision policies, and failure examples live in the
+Speculative apply, directional search ranges, advanced restore, rejected-view
+insertion, list, table, formatting, comments, revision policies, and failure
+examples live in the
 [knowledge base](docs/AGENT_KNOWLEDGE_BASE.md#agent-document-workflow-cli) and
 [operation schema](docs/schemas/document-operations.schema.json).
 
 ## 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.
 Production harnesses own their transport and negotiate the minimum CLI
-`contractVersion`/capabilities they use. The 0.7.0 localized fast path requires
-contract 8 and its localized replacement, speculative apply, and change-summary
-capabilities; the narrow restore shortcut additionally requires
-`restore-shortcuts-v1`.
+`contractVersion` and capabilities they actually use. Optional capabilities do
+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,13 +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/README.md

@@ -16,18 +16,16 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 - Highlights: apply highlight colors to runs
 - Markdown and OOXML conversion in both directions
 - Status/error result fields for parse, targeting, and existing-revision failures
-- Localized exact replacements and fail-closed one-turn CLI edits with verified before/after evidence
+- Localized exact replacements against inspected targets, plus optional fail-closed speculative CLI edits
 - 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
 
 ## What's New in 0.7.0
 
-Version 0.7.0 adds a contract-8 fast path for exact mechanical edits. Agents can
-send a small `find`/`replace` request instead of reproducing a complete legal
-paragraph, and may omit a strong target when the source literal resolves to one
-accepted-view paragraph. A longer, fairly unique nearby phrase can narrow the
-attempt with a signed directional window. Generic or repeated anchors widen the
-unioned scope and may cause a safe ambiguity failure and another tool turn.
+Version 0.7.0 adds contract-8 localized edits. Agents can send a small
+`find`/`replace` request against an inspected target instead of reproducing a
+complete paragraph. An optional speculative form may omit the strong target
+when the source literal resolves uniquely; advanced scoping is described below.
 
 Speculative edits fail without writing when the anchor, paragraph, or source
 span is missing or ambiguous. Successful localized results include a committed
@@ -249,18 +247,10 @@ latency. Checked comparative results are in the
 ### Agent CLI
 
 ```bash
-# One-turn exact mechanical edit; fails closed unless one paragraph matches
-docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-
-# Directional context using a longer phrase with a higher chance of uniqueness
-docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-
-# Semantic drafting still starts with focused context
+# Default agent workflow: inspect once, then apply once
 docx-redline extract contract.docx --search "termination" --around 3
-docx-redline preflight contract.docx --operations operations.json --author "Editor"
-docx-redline apply contract.docx --operations operations.json --author "Editor" --output reviewed.docx
-docx-redline validate reviewed.docx
-```
+node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
+```
 
 ```bash
 # Inline one-liner edit (no operations file needed)
@@ -275,9 +265,9 @@ docx-redline apply contract.docx --target "Another author's clause" --modified "
 # High-assurance atomic batch with nonzero exit on any incomplete result
 docx-redline apply contract.docx --operations operations.json --atomic --require-complete --output reviewed.docx
 
-# Agent shell path: JSON is emitted by a serializer, not interpolated by the shell
-node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
-```
+# Optional read-only audit before a deliberately staged batch
+docx-redline preflight contract.docx --operations operations.json --author "Editor"
+```
 
 All commands emit JSON on stdout. `apply` defaults:
 - **Author**: Defaults to `'AI Redliner'` (or `DOCX_REDLINE_AUTHOR` environment variable).
@@ -290,7 +280,8 @@ All commands emit JSON on stdout. `apply` defaults:
 - **Compact stdout**: `--compact` emits one-line mutation JSON. It changes serialization only, not operation semantics.
 - **Tracked changes**: Defaults to `generateRedlines: true`. Pass `--no-redlines` when clean direct text edits are desired.
 - **Inline edits**: Use `--target <text>` with `--modified <text>` or `--comment <text>` for quick one-liners without creating a JSON file.
-- **Localized edits**: Use `--find`/`--replace` with a known strong target, or omit the target for fail-closed global resolution. Add a longer, fairly unique `--search` phrase with `--context-range 1:3` for directional scope; `--around 3` is symmetric. Generic or repeated anchors can widen the unioned scope until multiple paragraphs contain `find`, producing a safe `AMBIGUOUS_TARGET` failure and an extra recovery turn. On success, `results[i].change.context.anchorMatchCount > 1` signals a non-unique anchor; confirm the returned location and bounded before/after evidence.
+- **Localized edits**: After extraction, use `replacements` with the inspected `paragraphId` plus `fingerprint` to avoid restating a long paragraph. Retain `exactText` locally for drafting. Targetless `--find`/`--replace` is an optional speculative path described below.
+- **Invisible spaces**: Localized matching is case-sensitive and tries exact text first. If no exact span exists, ordinary spaces may match DOCX non-breaking spaces; ambiguous equivalent matches still fail closed, and `change.replacements[i].matchMode` reports `space_equivalent` when used.
 - **Compact mutation results**: `apply`, `accept`, `reject`, and `delete-comments` omit full OOXML/package payloads and inspection text from stdout. CLI operation results omit duplicate nested receipt bodies; the ordered top-level `receipts` array is authoritative. Successful exact target-match diagnostics are omitted and equivalent-whitespace matches retain only mode/count. Node and standalone-runner results remain unchanged. Use `validate` when full issue arrays are needed.
 
 Inspection commands default to 20 direct matches and a 48 KiB soft response
@@ -312,10 +303,31 @@ user-facing Word locations; use `humanReference`, `provision`, or
 `agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
 `compact-cli-json-v1`, `localized-replacements-v1`,
 `speculative-search-apply-v1`, `localized-change-summary-v1`, and
-`restore-shortcuts-v1` capabilities.
+`restore-shortcuts-v1`, plus `localized-space-equivalence-v1` capabilities.
 Wrappers should negotiate only the
 capabilities they use. Run `docx-redline <command> --help` for that command's
 machine-readable options, behavior, exit codes, canonical GitHub documentation links, and compact examples.
+
+#### Optional speculative CLI path
+
+Harnesses with a measured confidence policy may attempt a targetless localized
+edit. This is not the default agent workflow:
+
+```bash
+# Globally unique literal
+docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+
+# Optional directional scope using a longer, fairly unique nearby phrase
+docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+Generic or repeated anchors can widen the unioned scope until multiple
+paragraphs contain `find`, causing a safe `AMBIGUOUS_TARGET` failure and a
+recovery turn. `--around 3` is symmetric. On success,
+`change.context.anchorMatchCount > 1` signals a repeated anchor; confirm the
+returned location and bounded evidence. Matching remains case-sensitive and
+exact-first, with a narrow ordinary-space/NBSP fallback that still refuses
+ambiguity.
 
 See the [compact agent fast start](./docs/AGENT_FAST_START.md), the
 [skill/harness authoring contract](./docs/SKILL_AUTHORING.md), and the

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) {