docxodus 12.4.0 → 12.5.0

package/README.md

@@ -72,6 +72,13 @@ Two layers, so you can take as much UI as you want:
 import { DocxEditor } from 'docxodus';
 const editor = DocxEditor.open(container, docxBytes, exports);
 
+// Long document? Mount it in windows instead, yielding to the event loop between them, so the
+// tab stays responsive and you can show progress. The result is the same editor and the same DOM.
+const editor = await DocxEditor.openAsync(container, docxBytes, exports, {
+  windowSize: 24,
+  onProgress: (mounted, total) => console.log(`${mounted}/${total} blocks`),
+});
+
 // Or the whole surface: Word's tabbed ribbon (fonts, colour, styles, find & replace, links,
 // pictures, tables, page setup, tracked changes), Word-style comment bubbles beside the page,
 // in-place header/footer editing, a status bar with zoom, and the loading overlay.
@@ -125,6 +132,19 @@ if (!result.success) console.error(result.failure);
 
 Pass `'best_effort'` explicitly only when partial successes should be retained.
 
+A retry after a lost response must not apply the edit twice. Give the batch a transaction id
+and a serializable description of what it does; an identical retry returns the original result
+without executing again, and reusing the id for a different request fails with
+`transaction_conflict`:
+
+```ts
+const result = session.executeBatch(steps, 'atomic', {
+  transactionId: 'plan-42-step-3',
+  request: { replace: firstAnchor, header: 'Confidential' },
+});
+result.transaction; // { schemaVersion: 1, transactionId, requestFingerprint }
+```
+
 `previewBatch` answers "what would this do?" without touching the live session. It runs the
 same steps against a complete isolated clone — each callback is handed the shadow session to
 mutate — and returns the same receipt plus optional predicted HTML:
@@ -144,6 +164,53 @@ the batch would produce, matching what the Python and MCP clients render for the
 `packageHash` is `null` when it could not be computed, so never assert replay equality
 without checking for it.
 
+A preview predicts generated values (new anchor ids, comment ids, revision timestamps), but a
+later `executeBatch` runs afresh and may generate them differently. `retain: true` keeps the
+successful preview's exact result package, and `commitPreview` makes it the live document as
+previewed — one undo step, same ids, same `packageHash`:
+
+```ts
+const preview = session.previewBatch(steps, 'atomic', { html: 'full', retain: true });
+showToReviewer(preview.html, preview.revisionChanges);
+const commit = session.commitPreview(preview.retention!.previewId, {
+  transactionId: 'plan-42-commit', request: { commit: preview.retention!.previewId },
+});
+commit.packageHash === preview.packageHash; // true
+```
+
+The commit refuses with `preview_stale`, editing nothing, if the session's version, package
+content, tracked-changes mode or revision author moved since the preview, and with
+`preview_not_found` once the preview expired, was evicted (8 previews, 64 MiB, 15 minutes per
+session) or was already committed.
+
+### Delivery receipts from captured evidence
+
+A session opened with `captureDeliveryEvidence: true` records the evidence a delivery change
+receipt needs as its edits execute — the exact package before and after every mutation, each
+`executeBatch` step's `tool`/`action`/`args`, transaction ids, and undo/redo lineage — and
+`buildDeliveryReceipt` mints a receipt the portable verifier accepts:
+
+```ts
+const session = openDocxSession(bytes, { captureDeliveryEvidence: true });
+session.executeBatch([
+  { tool: 'docx_edit', action: 'replace_text', args: { anchorId: firstAnchor, markdown: 'Final wording' },
+    mutation: () => session.replaceText(firstAnchor, 'Final wording') },
+], 'atomic', { transactionId: 'plan-42', request: { replace: firstAnchor } });
+
+const bundle = session.buildDeliveryReceipt({ privacyProfile: 'hashAndSummary' });
+const receipt = bundle.artifacts.find(a => a.artifactId === 'change-receipt')!;
+const artifacts = Object.fromEntries(bundle.artifacts
+  .filter(a => a.bytes && a.artifactId !== 'change-receipt')
+  .map(a => [a.artifactId, a.bytes!]));
+await verifyDeliveryReceipt(new TextDecoder().decode(receipt.bytes!), artifacts); // isValid
+```
+
+Deliver the bundle's `final-docx` artifact: it is the bytes the receipt attests. A direct call
+outside `executeBatch` is still captured exactly but recorded as an unlabeled mutation;
+`getDeliveryEvidenceStatus()` counts those and names the first reason a receipt cannot be
+minted (capture off, retention of 256 states / 512 MiB exceeded), in which case the bundle is
+`incomplete` and the receipt artifact carries the reason instead of claiming a history.
+
 ![Markdown projection beside the rendered document](https://raw.githubusercontent.com/JSv4/Docxodus/main/docs/images/projection.png)
 
 Native links and bookmarks use the same stable anchors and exact character spans:
@@ -275,6 +342,29 @@ function DocumentComparer() {
 }
 ```
 
+## Node.js (ES modules)
+
+Import the engine from `docxodus/core` for server-side conversion, comparison, annotations,
+and document sessions. It loads without a bundler or a custom Node loader:
+
+```js
+import { readFile, writeFile } from 'node:fs/promises';
+import { initialize, convertDocxToHtml, compareDocuments } from 'docxodus/core';
+
+await initialize(); // Finds the WASM runtime included in the installed package.
+const original = await readFile('original.docx');
+const revised = await readFile('revised.docx');
+await writeFile('original.html', await convertDocxToHtml(original));
+await writeFile('redline.docx', await compareDocuments(original, revised));
+```
+
+`docxodus/core` exposes the engine functions, types, enums, annotation helpers, and history
+APIs from `docxodus`, excluding `DocxEditor`, `CommentGutter`, `mountRibbon`, and their editor
+types. The existing `docxodus` entry includes those browser editor APIs and requires a browser
+bundler; use `docxodus/core` in plain Node ESM. Both entries share the same engine state.
+Browser helpers retained in `core`, such as pagination, the document viewport, IndexedDB
+storage, and history controls, still require their browser APIs when called.
+
 ## API Reference
 
 ### Package verification
@@ -505,10 +595,21 @@ const redlined = await docxodus.compareDocuments(original, modified, options);
 const revisions = await docxodus.getRevisions(docxFile);
 const metadata = await docxodus.getDocumentMetadata(docxFile);
 
+// The external annotation family runs there too, so a read-only viewer that renders
+// through the worker can annotate without booting a second runtime on the main thread.
+const set = await docxodus.createExternalAnnotationSet(docxFile, 'doc-1');
+const annotated = await docxodus.projectAnnotationsOntoHtml(html, set);
+const validation = await docxodus.validateExternalAnnotations(docxFile, set);
+const exported = await docxodus.exportToOpenContract(docxFile);
+
 // Terminate when done
 docxodus.terminate();
 ```
 
+`projectAnnotationsOntoHtml` parses its input as XML: hand it the converter's output (or
+another well-formed serialization), not a live DOM's `innerHTML`, which leaves `<br>` and
+`<img>` unclosed. `DocxEditor.open()` stays main-thread only — it writes into a live container.
+
 #### First-call warmup
 
 `createWorkerDocxodus()` warms the .NET WASM runtime, but the **comparison code