docxodus 9.9.0 → 11.0.0

package/README.md

@@ -23,6 +23,13 @@ linked as one operation instead of reported as an unrelated delete and insert.*
 `getRevisions()` gives you the same changes as structured data — typed, with move pairing and stable
 `kind:scope:unid` anchors — so you can drive a review UI without parsing OOXML.
 
+For audit and verification workflows, `docxDiffGetSemanticChanges(left, right)` returns the stable
+`docxodus.semantic-changes` v1 object. It distinguishes content, formatting, structure, table,
+story/review, relationship/media, and opaque-package families, with typed before/after values and
+deterministic ids. An open session exposes the same opening-to-current comparison through
+`session.getSemanticChanges()`; it requires the default `captureInitialProjection: true` setting.
+See the [semantic diff contract](../docs/architecture/semantic_diff.md).
+
 ## Render a document faithfully
 
 `convertDocxToHtml()` keeps what naive converters drop: justification, style inheritance, legal
@@ -33,6 +40,23 @@ numbering, tables, images, comments, headers and footers, and real footnotes wit
 Paginated mode flows content into real page boxes with per-page numbers and page-anchored footnotes —
 a print-accurate preview in the browser.
 
+Supply an exact layout token to materialize portable page citations from that layout:
+
+```ts
+const result = paginateHtml(html, viewer, {
+  layoutToken: { documentVersion: session.getVersion(), rendererFingerprint: 'chromium-layout-v1' },
+});
+session.registerPageMap(result.pageMap!, 'chromium-layout-v1');
+const citation = session.getPageCitation(anchorId, {
+  documentVersion: session.getVersion(),
+  rendererFingerprint: 'chromium-layout-v1',
+});
+navigateToPageCitation(viewer, citation);
+```
+
+Continuous renderers return explicit unavailability; Docxodus never estimates a citation page.
+See the [PageMap contract](../docs/architecture/page_map.md).
+
 ## Edit it in place
 
 `DocxEditor` is a framework-agnostic block editor over the live document. Edits go through a
@@ -66,7 +90,7 @@ runtime location auto-detected — no build step, no configuration:
 ```html
 <div id="doc" style="height: 100dvh"></div>
 <script type="module">
-  import { createRibbonEditor } from 'https://cdn.jsdelivr.net/npm/docxodus@9.2.0/dist/embed.bundle.js';
+  import { createRibbonEditor } from 'https://cdn.jsdelivr.net/npm/docxodus@10.0.0/dist/embed.bundle.js';
   const ribbon = await createRibbonEditor('#doc', './contract.docx'); // or bytes / Blob / File
   // ...later: const editedBytes = ribbon.save();
 </script>
@@ -82,8 +106,80 @@ Bundler users get the same API from `docxodus/embed`; classic-script pages can l
 `convertWmlToMarkdown()` renders the document as markdown where **every block carries a stable id**,
 so an agent can point at a clause and edit it — and `openDocxSession()` writes back to that same id.
 
+Multi-step plans are atomic by default. Each callback may call any synchronous
+session mutation; success is one version/undo unit, while a failure or throw
+restores the complete package and history checkpoint:
+
+```ts
+const result = session.executeBatch([
+  { tool: 'docx_edit', action: 'replace_text',
+    mutation: () => session.replaceText(firstAnchor, 'Replacement text') },
+  { tool: 'docx_create', action: 'set_header_text',
+    mutation: () => session.setHeaderText(firstAnchor, 'default', 'Confidential') },
+]);
+
+if (!result.success) console.error(result.failure);
+```
+
+Pass `'best_effort'` explicitly only when partial successes should be retained.
+
+`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:
+
+```ts
+const preview = session.previewBatch([
+  { tool: 'docx_edit', action: 'replace_text',
+    mutation: shadow => shadow.replaceText(firstAnchor, 'Proposed replacement') },
+], 'atomic', { html: 'full' });
+
+console.log(preview.html, preview.revisionChanges.added, preview.warnings);
+```
+
+The live document's bytes, version and undo/redo history are unchanged either way. Preview
+HTML shows tracked changes, comments, annotations, notes and headers/footers — the document
+the batch would produce, matching what the Python and MCP clients render for the same batch.
+`packageHash` is `null` when it could not be computed, so never assert replay equality
+without checking for it.
+
 ![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:
+
+```ts
+const session = openDocxSession(docxBytes, { persistAnchorIds: true });
+const paragraph = Object.keys(session.project().anchorIndex)
+  .find(id => id.startsWith('p:body:'))!;
+session.addBookmark('Definitions', {
+  startAnchorId: paragraph, startOffset: 0,
+  endAnchorId: paragraph, endOffset: 11,
+});
+session.addHyperlink(paragraph, { start: 0, length: 11 }, 'internal', 'Definitions');
+const links = session.listHyperlinks(); // ids feed updateHyperlink/removeHyperlink
+const bookmarks = session.listBookmarks(); // exact endpoint range + per-paragraph segments
+```
+
+External links own their relationship in the actual body/header/footer/footnote/endnote part;
+internal links are relationship-free bookmark targets. Bookmark rename retargets inbound links
+atomically, and unsafe removal or cross-part ranges return typed `EditResult` errors.
+
+Native images are occurrence-addressed too, with bytes kept explicit at the API boundary:
+
+```ts
+const capabilities = session.getImageCapabilities();
+const inserted = session.insertImage(paragraph, 0, pngBytes, {
+  widthPoints: 144,
+  altText: 'Revenue by quarter',
+});
+const image = session.listImages().find(value => value.id === inserted.imageId)!;
+session.setImageDimensions(image.id, { widthPoints: 108 });
+```
+
+PNG/JPEG/GIF/BMP/TIFF are writable. Existing WebP, external links, legacy VML, and unsupported
+DrawingML remain enumerable with `canMutate: false`. Dimensions use points; floating offsets use
+exact EMUs, and omitted insert dimensions use 96 DPI. The browser API accepts `Uint8Array` and
+does not fetch image URLs or read paths.
+
 ---
 
 ## Everything else
@@ -179,6 +275,48 @@ function DocumentComparer() {
 
 ## API Reference
 
+### Package verification
+
+`generatePackageManifest(document)` inspects supplied bytes without opening an editable package;
+`session.getPackageManifest()` describes the current logical session checkpoint, including unsaved
+edits, without advancing its version. Both return the same schema-v1 `PackageManifest` with exact
+package, ordered OPC-content, and normalized-semantic SHA-256 identities plus entries,
+relationships, facts, and structured findings. Worker users can call
+`worker.generatePackageManifest(document)` or `await workerSession.getPackageManifest()`. See
+[`package_manifests.md`](../docs/architecture/package_manifests.md) for the normalization boundary.
+
+### Stateful inspection and editing
+
+`openDocxSession(bytes)` exposes the live document rather than a one-shot conversion. Inspect the
+source before writing it: `listStyles()` returns the document's actual paragraph/character/table
+styles, `getFormatting(anchorId)` keeps `directParagraph` separate from `effectiveParagraph`, and
+`listInlineSpans(anchorId)` returns `anchorId` + `span` pairs accepted unchanged by `applyFormat`.
+
+```typescript
+const session = openDocxSession(bytes);
+try {
+  const anchorId = Object.keys(session.project().anchorIndex)[0];
+  const style = session.listStyles().find(s => s.name === "Strong Custom");
+  const run = session.listInlineSpans(anchorId).find(s => s.text === "Defined Term");
+  if (style && run) {
+    session.applyFormat(run.anchorId, run.span, { runStyle: style.id });
+  }
+} finally {
+  session.close();
+}
+```
+
+An omitted property in a `direct` record means "not written at this layer"; it must not be treated
+as false or zero. The matching `effective` record resolves document defaults and the full style
+chain. `getListMembership` and `getSectionInfo` likewise return their query `anchorId` so callers
+do not have to translate between inspection and mutation coordinate systems.
+
+`effective` is deliberately a shorter cascade than the renderer's: it excludes the numbering
+level's own paragraph properties and the table style's conditional formatting, so a list item
+indented only by its numbering definition reports `leftIndentTwips: 0` and a run bolded by a
+`firstRow` table style reports `bold: false`. Use `getListMembership` for the real numbering
+indentation. See `docs/architecture/docx_mutation_api.md` for the exact layer list.
+
 ### Core Functions
 
 #### `initialize(basePath?: string): Promise<void>`
@@ -440,7 +578,7 @@ so a page can embed a full viewer or editor without hosting anything itself.
 <div id="app" style="height: 100dvh"></div>
 <script type="module">
   import { createViewer, createEditor, createRibbonEditor }
-    from 'https://cdn.jsdelivr.net/npm/docxodus@9.2.0/dist/embed.bundle.js';
+    from 'https://cdn.jsdelivr.net/npm/docxodus@10.0.0/dist/embed.bundle.js';
 
   // Choose a factory, or render several into separate containers as shown.
   // Source may be a URL, Uint8Array, ArrayBuffer, Blob, or File.
@@ -470,7 +608,7 @@ For pages that can't use modules, `dist/embed.iife.js` exposes the same surface
 
 ```html
 <div id="doc"></div>
-<script src="https://cdn.jsdelivr.net/npm/docxodus@9.2.0/dist/embed.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/docxodus@10.0.0/dist/embed.iife.js"></script>
 <script>
   Docxodus.createRibbonEditor('#doc').then((ribbon) => { /* ... */ });
 </script>
@@ -486,7 +624,7 @@ first `<bundle dir>/wasm/`, then `<bundle dir>/` as a fallback. On a CDN that re
 
 ### CDN caveats
 
-- **Pin an exact version in production** (`docxodus@9.2.0`, not `@latest`) — CDN responses are
+- **Pin an exact version in production** (`docxodus@10.0.0`, not `@latest`) — CDN responses are
   cached as immutable, and the wire shapes between the JS wrappers and the WASM assemblies must
   come from the same release.
 - The build patches the .NET loader to fetch with `credentials: "omit"` — required because the
@@ -500,6 +638,46 @@ first `<bundle dir>/wasm/`, then `<bundle dir>/` as a fallback. On a CDN that re
 - First load fetches ~18 MB uncompressed across about 49 requests; subsequent loads hit the
   browser cache.
 
+## Standalone paginated HTML
+
+`docxodus/export-browser` turns a DOCX into a complete offline HTML document whose body contains
+the finalized fixed page boxes—not the hidden measurement tree. It returns the HTML together with
+the exact PageMap, renderer fingerprint, warnings, and a schema-v2 render report from that same
+sanitized tree.
+
+```ts
+import { convertDocxToPaginatedHtml } from 'docxodus/export-browser';
+
+const source = new Uint8Array(await file.arrayBuffer());
+const result = await convertDocxToPaginatedHtml(source, {
+  reviewProfile: 'final',
+  commentProfile: 'endnotes',
+  documentVersion: 12,
+  expectedSourceDigest: verifiedSha256,
+});
+
+download(new Blob([result.html], { type: 'text/html' }));
+console.log(result.pageCount, result.pageMap, result.renderReport);
+```
+
+The exporter copies caller bytes before its first asynchronous boundary, verifies them with the
+package manifest API, performs layout in an attached script-disabled frame, embeds or removes every
+automatic resource, and reopens the serialized result to verify page count and physical geometry.
+External HTTPS/mail/tel links remain user-activated links and are inventoried in the report; the
+exporter never follows them. `unsupportedContent: 'strict'` rejects visible placeholders or omitted
+resources instead of returning a nominally complete artifact.
+
+All three revision profiles (`final`, `original`, `markup`) are supported; `final` and `original`
+derive their projection out-of-place and never mutate the caller's bytes. `strictFonts: true`
+turns unresolved or unverified font families into failures; supplying a `fontResolver` (in Node,
+`fontDirectories` on `@docxodus/export`) is what makes families verifiable. A font the browser
+supplied on its own is labelled `browserObserved`; it is not presented as a verified host-font
+environment.
+
+By default the worker loads from `dist/wasm/` beside the package entry point. A deployment that
+hosts those files elsewhere may pass `wasmBasePath`. `docxodus/export-assets.json` is the closed,
+SHA-256-addressed runtime asset graph, and `docxodus/render-report.schema.json` is the report schema.
+
 ## Hosting WASM Files
 
 The WASM files need to be served from your web server. After building:

package/dist/canonical.d.ts

@@ -0,0 +1,7 @@
+/** Shared canonical-JSON serialization, used by both the export orchestrator and the browser
+ * font runtime wherever a value needs a stable digest or a deterministic wire form. */
+export declare function isWellFormedUnicode(value: string): boolean;
+export declare function assertWellFormedUnicode(value: string): void;
+/** Serialize report/schema values with recursively sorted object keys and no insignificant space. */
+export declare function canonicalJson(value: unknown): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA;uFACuF;AAEvF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAW1D;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAI3D;AA6BD,qGAAqG;AACrG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD"}

package/dist/canonical.js

@@ -0,0 +1,56 @@
+/** Shared canonical-JSON serialization, used by both the export orchestrator and the browser
+ * font runtime wherever a value needs a stable digest or a deterministic wire form. */
+export function isWellFormedUnicode(value) {
+    for (let index = 0; index < value.length; index++) {
+        const unit = value.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = value.charCodeAt(++index);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff) {
+            return false;
+        }
+    }
+    return true;
+}
+export function assertWellFormedUnicode(value) {
+    if (!isWellFormedUnicode(value)) {
+        throw new TypeError("Canonical JSON does not support unpaired UTF-16 surrogates");
+    }
+}
+function canonicalValue(value) {
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        assertWellFormedUnicode(value);
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("Canonical JSON does not support non-finite numbers");
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonicalValue);
+    if (typeof value === "object") {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("Canonical JSON supports only plain objects");
+        }
+        const result = {};
+        for (const key of Object.keys(value).sort()) {
+            assertWellFormedUnicode(key);
+            const member = value[key];
+            if (member !== undefined)
+                result[key] = canonicalValue(member);
+        }
+        return result;
+    }
+    throw new TypeError(`Canonical JSON does not support ${typeof value}`);
+}
+/** Serialize report/schema values with recursively sorted object keys and no insignificant space. */
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalValue(value));
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA;uFACuF;AAEvF,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;YACrC,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,CAAC;YACvC,IAAI,CAAC,CAAC,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC;gBAAE,OAAO,KAAK,CAAC;QACxD,CAAC;aAAM,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;YAC5C,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACnD,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,4DAA4D,CAAC,CAAC;IACpF,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,uBAAuB,CAAC,KAAK,CAAC,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,oDAAoD,CAAC,CAAC;QACvG,OAAO,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC1C,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC3D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACzD,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;QACpE,CAAC;QACD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACvE,uBAAuB,CAAC,GAAG,CAAC,CAAC;YAC7B,MAAM,MAAM,GAAI,KAAiC,CAAC,GAAG,CAAC,CAAC;YACvD,IAAI,MAAM,KAAK,SAAS;gBAAE,MAAM,CAAC,GAAG,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QACjE,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,IAAI,SAAS,CAAC,mCAAmC,OAAO,KAAK,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/dist/docxodus.worker.d.ts

@@ -5,7 +5,8 @@
  * thread free for UI updates and user interactions.
  *
  * Communication is via postMessage with structured request/response types.
- * Document bytes are transferred (not copied) for efficiency.
+ * Caller-owned Uint8Array inputs are first cloned to preserve their exact view and avoid
+ * detachment; that private clone is then transferred to the worker.
  */
 export {};
 //# sourceMappingURL=docxodus.worker.d.ts.map

package/dist/docxodus.worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docxodus.worker.d.ts","sourceRoot":"","sources":["../src/docxodus.worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}
+{"version":3,"file":"docxodus.worker.d.ts","sourceRoot":"","sources":["../src/docxodus.worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}