docxodus 12.4.0 → 12.5.0

package/dist/core.js

@@ -0,0 +1,1915 @@
+import { openDocxSession as openDocxSessionImpl } from "./session.js";
+import { serializeVerificationRequest } from "./verification-request.js";
+import { readExternalAnnotationSet, readExternalAnnotationValidation, readOpenContractExport, readProjectedHtml, } from "./external-annotation-wire.js";
+import { DocxHistoryArchive, DocxHistoryClient, installHistoryStorageImports } from './history.js';
+export * from './history.js';
+export * from './history-checkpoints.js';
+export * from './history-indexeddb.js';
+export * from './history-controls.js';
+/** Open history over host-owned storage after initialize(). No network layer is installed. */
+export function openDocxHistory(storage) {
+    const bridge = ensureInitialized().HistoryBridge;
+    if (!bridge)
+        throw new Error('This WASM build does not include history bindings.');
+    return new DocxHistoryClient(bridge, storage);
+}
+/** Open a self-contained readonly .docxhistory file after initialize(); no storage adapter needed. */
+export function openDocxHistoryArchive(bytes) {
+    const bridge = ensureInitialized().HistoryBridge;
+    if (!bridge)
+        throw new Error('This WASM build does not include history bindings.');
+    return DocxHistoryArchive.open(bridge, bytes);
+}
+export { DocxSession } from "./session.js";
+export { PlaceholderKinds, ContextBoundary } from "./types.js";
+export { DiffFormat } from "./types.js";
+/**
+ * Open a {@link DocxSession} for surgical mutation of a DOCX. Requires
+ * {@link initialize} to have been called and awaited.
+ *
+ * The returned session keeps the document in WASM memory; call
+ * {@link DocxSession.close} when done.
+ */
+export function openDocxSession(bytes, settings) {
+    const wasm = ensureInitialized();
+    return openDocxSessionImpl(bytes, wasm, settings);
+}
+/**
+ * Mint a complete, blank single-paragraph DOCX (Normal style, US-Letter section) as bytes —
+ * a "New document" seed for editors that draft from scratch. Requires {@link initialize}.
+ */
+export function createBlankDocx() {
+    return ensureInitialized().DocxSessionBridge.CreateBlankDocx();
+}
+import { CommentRenderMode, PaginationMode, AnnotationLabelMode, RevisionType, DocxDiffRevisionGranularity, DocxDiffFormatComparison, ConflictResolution, ProjectionScopes, AnchorRenderMode, TableRenderMode, TrackedChangeMode, EmptyParagraphMode, AnchorIdRendering, ProjectionDepth, DocumentElementType, ComparisonLogLevel, ComparisonLogCodes, isInsertion, isDeletion, isMove, isFormatChange, findElementById, findElementsByType, getParagraphs, getTables, getTableColumns, targetElement, targetParagraph, targetParagraphRange, targetRun, targetTable, targetTableRow, targetTableCell, targetTableColumn, targetSearch, targetSearchInElement, } from "./types.js";
+export { PaginationEngine, clearPageCitationHighlight, createUnavailablePageMap, navigateToPageCitation, paginateHtml, } from "./pagination.js";
+// Page geometry is the document's own page setup (w:sectPr), read off the section wrappers
+// the converter stamps in every render mode, plus the fit-to-width zoom a view applies to it.
+export { DEFAULT_MARGIN, DEFAULT_PAGE_HEIGHT, DEFAULT_PAGE_WIDTH, fitScale, parseSectionDimensions, ptToPx, pxToPt, } from "./page-geometry.js";
+export { DocumentViewport } from "./viewport.js";
+export { CommentRenderMode, PaginationMode, AnnotationLabelMode, RevisionType, DocxDiffRevisionGranularity, DocxDiffFormatComparison, ConflictResolution, ProjectionScopes, AnchorRenderMode, TableRenderMode, TrackedChangeMode, EmptyParagraphMode, AnchorIdRendering, ProjectionDepth, DocumentElementType, ComparisonLogLevel, ComparisonLogCodes, isInsertion, isDeletion, isMove, isFormatChange, 
+// Document structure helpers
+findElementById, findElementsByType, getParagraphs, getTables, getTableColumns, 
+// Annotation target factory functions
+targetElement, targetParagraph, targetParagraphRange, targetRun, targetTable, targetTableRow, targetTableCell, targetTableColumn, targetSearch, targetSearchInElement, };
+let wasmExports = null;
+let initPromise = null;
+/**
+ * Yields to the browser's main thread, allowing pending UI updates to render.
+ *
+ * This is critical for WASM operations: since WASM runs synchronously on the
+ * main thread, React state updates (like loading spinners) won't paint unless
+ * we yield before the blocking work begins.
+ *
+ * Uses requestAnimationFrame which fires just before the next paint, ensuring
+ * any queued state updates are committed to the DOM.
+ *
+ * @internal
+ */
+async function yieldToMain() {
+    // In non-browser environments (SSR, tests), skip yielding
+    if (typeof requestAnimationFrame === "undefined") {
+        return;
+    }
+    // Double-rAF ensures the browser has fully painted before we continue
+    // First rAF: scheduled for next frame
+    // Second rAF: ensures first frame actually painted
+    await new Promise((resolve) => {
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => resolve());
+        });
+    });
+}
+/**
+ * Derive the WASM base path from this module's URL.
+ * Works whether loaded from node_modules, CDN, or bundled.
+ */
+function getDefaultWasmBasePath() {
+    try {
+        // import.meta.url gives us the URL of this module
+        // e.g., "https://cdn.jsdelivr.net/npm/docxodus@12.3.0/dist/core.js"
+        // or "file:///path/to/node_modules/docxodus/dist/core.js"
+        const moduleUrl = import.meta.url;
+        // Remove the filename to get the directory
+        const baseDir = moduleUrl.substring(0, moduleUrl.lastIndexOf('/') + 1);
+        // WASM files are in ./wasm/ relative to dist/
+        return baseDir + "wasm/";
+    }
+    catch {
+        // Fallback if import.meta.url is not available
+        return "";
+    }
+}
+/**
+ * Current base path for WASM files.
+ * Empty string means auto-detect from module URL.
+ */
+export let wasmBasePath = "";
+/**
+ * Set custom base path for WASM files.
+ * Pass empty string or don't call this to auto-detect from module location.
+ *
+ * @param path - Custom path to WASM files, or empty string for auto-detection
+ */
+export function setWasmBasePath(path) {
+    wasmBasePath = path && !path.endsWith("/") ? path + "/" : path;
+}
+/**
+ * Initialize the Docxodus WASM runtime.
+ * Must be called before using any conversion/comparison functions.
+ * Safe to call multiple times - will only initialize once.
+ *
+ * By default, WASM files are auto-detected from the module's location
+ * (works with CDN, npm, or local hosting).
+ * Pass a basePath to load from a custom location instead.
+ *
+ * @param basePath - Optional custom path to WASM files. Leave empty for auto-detection.
+ */
+export async function initialize(basePath) {
+    if (wasmExports)
+        return;
+    if (initPromise) {
+        return initPromise;
+    }
+    if (basePath !== undefined) {
+        setWasmBasePath(basePath);
+    }
+    // Clear the cached promise on failure so a caller can retry with a
+    // different base path (a rejected initialize() used to be permanent).
+    initPromise = loadWasm().catch((e) => {
+        initPromise = null;
+        throw e;
+    });
+    return initPromise;
+}
+/**
+ * Try to load WASM from a specific base path
+ */
+async function tryLoadFromPath(basePath) {
+    try {
+        const dotnetPath = basePath + "_framework/dotnet.js";
+        const { dotnet } = await import(/* webpackIgnore: true */ /* @vite-ignore */ dotnetPath);
+        const { getAssemblyExports, getConfig, setModuleImports } = await dotnet
+            .withDiagnosticTracing(false)
+            .create();
+        installHistoryStorageImports(setModuleImports);
+        const config = getConfig();
+        const exports = await getAssemblyExports(config.mainAssemblyName);
+        wasmExports = {
+            DocumentConverter: exports.DocxodusWasm.DocumentConverter,
+            DocumentComparer: exports.DocxodusWasm.DocumentComparer,
+            DocxDiffBridge: exports.DocxodusWasm.DocxDiffBridge,
+            DocxSessionBridge: exports.DocxodusWasm.DocxSessionBridge,
+            HistoryBridge: exports.DocxodusWasm.HistoryBridge,
+        };
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadWasm() {
+    // If a custom path is set, use it directly
+    if (wasmBasePath) {
+        const success = await tryLoadFromPath(wasmBasePath);
+        if (success)
+            return;
+        throw new Error(`Failed to load WASM from custom path: ${wasmBasePath}. ` +
+            `Ensure the WASM files are served at this location.`);
+    }
+    // Try to auto-detect from module URL (works for CDN and local imports)
+    const autoDetectedPath = getDefaultWasmBasePath();
+    if (autoDetectedPath) {
+        const success = await tryLoadFromPath(autoDetectedPath);
+        if (success) {
+            wasmBasePath = autoDetectedPath;
+            return;
+        }
+    }
+    // Auto-detection failed
+    throw new Error(`Failed to load WASM files. ` +
+        `Auto-detected path: ${autoDetectedPath || "(none)"}. ` +
+        `You can specify a custom path by calling initialize("/path/to/wasm/").`);
+}
+function ensureInitialized() {
+    if (!wasmExports) {
+        throw new Error("Docxodus not initialized. Call initialize() first and await it.");
+    }
+    return wasmExports;
+}
+function isErrorResponse(result) {
+    try {
+        const parsed = JSON.parse(result);
+        return typeof parsed === "object" && "Error" in parsed;
+    }
+    catch {
+        return false;
+    }
+}
+function parseError(result) {
+    const parsed = JSON.parse(result);
+    return {
+        error: parsed.Error || parsed.error,
+        type: parsed.Type || parsed.type,
+        stackTrace: parsed.StackTrace || parsed.stackTrace,
+    };
+}
+/**
+ * Convert a File or Uint8Array to Uint8Array
+ */
+async function toBytes(input) {
+    if (input instanceof Uint8Array) {
+        return input;
+    }
+    const buffer = await input.arrayBuffer();
+    return new Uint8Array(buffer);
+}
+/**
+ * Generate a deterministic, non-mutating verification manifest from DOCX bytes.
+ * Invalid, malformed, and encrypted packages are represented by structured findings.
+ */
+export async function generatePackageManifest(document) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    await yieldToMain();
+    return JSON.parse(exports.DocumentConverter.GeneratePackageManifest(bytes));
+}
+/**
+ * Run the default bounded deliverable-verification policy on exact DOCX bytes.
+ * Invalid, malformed, encrypted, and safety-limited packages are returned as
+ * structured report findings rather than editable-session errors. When supplied,
+ * the exact baseline bytes are used to classify pre-existing, new, and resolved findings.
+ */
+export async function verifyDeliverable(document, baseline, request) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    const baselineBytes = baseline === undefined ? undefined : await toBytes(baseline);
+    await yieldToMain();
+    if (request !== undefined) {
+        // The full request (issue #747): the same wire shape every transport parses.
+        const requestJson = serializeVerificationRequest(request);
+        const converter = exports.DocumentConverter;
+        if (!converter.VerifyDeliverableWithRequest || !converter.VerifyDeliverableWithBaselineAndRequest) {
+            throw new Error("This WASM bundle predates full verification requests; rebuild docxodus.");
+        }
+        return JSON.parse(baselineBytes === undefined
+            ? converter.VerifyDeliverableWithRequest(bytes, requestJson)
+            : converter.VerifyDeliverableWithBaselineAndRequest(baselineBytes, bytes, requestJson));
+    }
+    return JSON.parse(baselineBytes === undefined
+        ? exports.DocumentConverter.VerifyDeliverable(bytes)
+        : exports.DocumentConverter.VerifyDeliverableWithBaseline(baselineBytes, bytes));
+}
+/**
+ * Verify a portable JSON delivery change receipt against supplied artifact bytes.
+ *
+ * The receipt travels as its JSON envelope string; `artifacts` maps each artifact id
+ * the receipt records to the exact bytes to independently re-hash against it. Omitted
+ * artifacts report `"missing"`. Malformed input yields a structured invalid verdict
+ * whose findings carry the reason — never a thrown error.
+ */
+export async function verifyDeliveryReceipt(receiptJson, artifacts) {
+    const exports = ensureInitialized();
+    const artifactsJson = artifacts === undefined
+        ? ""
+        : JSON.stringify(Object.fromEntries(Object.entries(artifacts).map(([artifactId, bytes]) => [
+            artifactId,
+            bytesToBase64(bytes),
+        ])));
+    await yieldToMain();
+    return JSON.parse(exports.DocumentConverter.VerifyDeliveryReceipt(receiptJson, artifactsJson));
+}
+/**
+ * Prove that a redline's generated revisions accept to the intended final and reject to the
+ * selected baseline without consuming pre-existing review state.
+ *
+ * Three packages are inspected and two rebuilt, so on a UI thread prefer the worker proxy's
+ * `proveRedlineReversibility`. Malformed, encrypted, and safety-limited packages are reported as
+ * structured proof findings rather than thrown errors. The rebuilt packages are not returned:
+ * the proof carries their digests and the divergences between them and each expected document.
+ *
+ * @param baseline - The document the redline was generated against
+ * @param intendedFinal - The document accepting the generated revisions must reproduce
+ * @param redline - The generated redline under proof
+ */
+export async function proveRedlineReversibility(baseline, intendedFinal, redline) {
+    const exports = ensureInitialized();
+    const baselineBytes = await toBytes(baseline);
+    const intendedFinalBytes = await toBytes(intendedFinal);
+    const redlineBytes = await toBytes(redline);
+    await yieldToMain();
+    return JSON.parse(exports.DocumentConverter.ProveRedlineReversibility(baselineBytes, intendedFinalBytes, redlineBytes));
+}
+/**
+ * Convert a DOCX document to HTML.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @param options - Conversion options
+ * @returns HTML string
+ * @throws Error if conversion fails
+ *
+ * @example
+ * ```typescript
+ * // Basic conversion
+ * const html = await convertDocxToHtml(docxFile);
+ *
+ * // With pagination (PDF.js-style page view)
+ * const html = await convertDocxToHtml(docxFile, {
+ *   paginationMode: PaginationMode.Paginated,
+ *   paginationScale: 0.8
+ * });
+ *
+ * // With annotations rendered
+ * const html = await convertDocxToHtml(docxFile, {
+ *   renderAnnotations: true,
+ *   annotationLabelMode: AnnotationLabelMode.Above
+ * });
+ *
+ * // With footnotes and endnotes
+ * const html = await convertDocxToHtml(docxFile, {
+ *   renderFootnotesAndEndnotes: true
+ * });
+ *
+ * // With headers and footers
+ * const html = await convertDocxToHtml(docxFile, {
+ *   renderHeadersAndFooters: true
+ * });
+ *
+ * // With tracked changes (redlines visible)
+ * const html = await convertDocxToHtml(docxFile, {
+ *   renderTrackedChanges: true,
+ *   showDeletedContent: true,
+ *   renderMoveOperations: true
+ * });
+ * ```
+ */
+/**
+ * Render a single document block to faithful HTML, addressed by its anchor.
+ *
+ * The anchor is the `data-anchor` value stamped on a block during a full
+ * conversion (a bare 32-hex Unid), or a full `kind:scope:unid` anchor — either
+ * form works. Powers the editor's incremental per-block re-render: apply an edit
+ * to a DocxSession, then re-render only the changed block instead of the whole
+ * document. Returns the block's HTML element (no `<html>`/`<head>` wrapper).
+ */
+export async function renderBlockHtml(document, anchorId, options) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    await yieldToMain();
+    const result = exports.DocumentConverter.RenderBlockHtml(bytes, anchorId, options?.cssPrefix ?? "docx-", options?.fabricateClasses ?? false);
+    if (isErrorResponse(result)) {
+        throw new Error(`Block rendering failed: ${parseError(result).error}`);
+    }
+    return result;
+}
+export async function convertDocxToHtml(document, options) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    // Yield to browser before heavy WASM work - allows loading states to render
+    await yieldToMain();
+    let result;
+    // Check if any of the new complete options are specified
+    const needsCompleteMethod = options?.renderFootnotesAndEndnotes !== undefined ||
+        options?.renderHeadersAndFooters !== undefined ||
+        options?.renderTrackedChanges !== undefined ||
+        options?.showDeletedContent !== undefined ||
+        options?.renderMoveOperations !== undefined ||
+        options?.renderUnsupportedContentPlaceholders !== undefined ||
+        options?.documentLanguage !== undefined ||
+        options?.stampAnchors !== undefined;
+    // Use complete method when any new options are specified (most comprehensive)
+    if (needsCompleteMethod || options?.renderAnnotations) {
+        result = exports.DocumentConverter.ConvertDocxToHtmlComplete(bytes, options?.pageTitle ?? "Document", options?.cssPrefix ?? "docx-", options?.fabricateClasses ?? true, options?.additionalCss ?? "", options?.commentRenderMode ?? CommentRenderMode.Disabled, options?.commentCssClassPrefix ?? "comment-", options?.paginationMode ?? PaginationMode.None, options?.paginationScale ?? 1.0, options?.paginationCssClassPrefix ?? "page-", options?.renderAnnotations ?? false, options?.annotationLabelMode ?? AnnotationLabelMode.Above, options?.annotationCssClassPrefix ?? "annot-", options?.renderFootnotesAndEndnotes ?? false, options?.renderHeadersAndFooters ?? false, options?.renderTrackedChanges ?? false, options?.showDeletedContent ?? true, options?.renderMoveOperations ?? true, options?.renderUnsupportedContentPlaceholders ?? false, options?.documentLanguage ?? null, options?.stampAnchors ?? false);
+    }
+    // Use pagination-aware method when pagination is requested
+    else if (options?.paginationMode !== undefined && options.paginationMode !== PaginationMode.None) {
+        result = exports.DocumentConverter.ConvertDocxToHtmlWithPagination(bytes, options.pageTitle ?? "Document", options.cssPrefix ?? "docx-", options.fabricateClasses ?? true, options.additionalCss ?? "", options.commentRenderMode ?? CommentRenderMode.Disabled, options.commentCssClassPrefix ?? "comment-", options.paginationMode, options.paginationScale ?? 1.0, options.paginationCssClassPrefix ?? "page-");
+    }
+    else if (options) {
+        result = exports.DocumentConverter.ConvertDocxToHtmlWithOptions(bytes, options.pageTitle ?? "Document", options.cssPrefix ?? "docx-", options.fabricateClasses ?? true, options.additionalCss ?? "", options.commentRenderMode ?? CommentRenderMode.Disabled, options.commentCssClassPrefix ?? "comment-");
+    }
+    else {
+        result = exports.DocumentConverter.ConvertDocxToHtml(bytes);
+    }
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Conversion failed: ${error.error}`);
+    }
+    return result;
+}
+/**
+ * Compare two DOCX documents and return the redlined result as a DOCX.
+ *
+ * @param original - Original DOCX document
+ * @param modified - Modified DOCX document
+ * @param options - Comparison options
+ * @returns Redlined DOCX as Uint8Array
+ * @throws Error if comparison fails
+ */
+export async function compareDocuments(original, modified, options) {
+    const exports = ensureInitialized();
+    const originalBytes = await toBytes(original);
+    const modifiedBytes = await toBytes(modified);
+    // Yield to browser before heavy WASM work - allows loading states to render
+    await yieldToMain();
+    let result;
+    if (options?.caseInsensitive) {
+        result = exports.DocumentComparer.CompareDocumentsWithOptions(originalBytes, modifiedBytes, options?.authorName ?? "Docxodus", options.caseInsensitive);
+    }
+    else {
+        result = exports.DocumentComparer.CompareDocuments(originalBytes, modifiedBytes, options?.authorName ?? "Docxodus");
+    }
+    if (result.length === 0) {
+        throw new Error("Comparison failed - empty result");
+    }
+    return result;
+}
+/**
+ * Compare two DOCX documents and return the result as HTML.
+ *
+ * @param original - Original DOCX document
+ * @param modified - Modified DOCX document
+ * @param options - Comparison options
+ * @returns HTML string with redlined content
+ * @throws Error if comparison fails
+ */
+export async function compareDocumentsToHtml(original, modified, options) {
+    const exports = ensureInitialized();
+    const originalBytes = await toBytes(original);
+    const modifiedBytes = await toBytes(modified);
+    // Yield to browser before heavy WASM work - allows loading states to render
+    await yieldToMain();
+    const renderTrackedChanges = options?.renderTrackedChanges ?? true;
+    let result;
+    if (options?.caseInsensitive !== undefined) {
+        result = exports.DocumentComparer.CompareDocumentsToHtmlFull(originalBytes, modifiedBytes, options?.authorName ?? "Docxodus", options.caseInsensitive, renderTrackedChanges);
+    }
+    else {
+        result = exports.DocumentComparer.CompareDocumentsToHtmlWithOptions(originalBytes, modifiedBytes, options?.authorName ?? "Docxodus", renderTrackedChanges);
+    }
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Comparison failed: ${error.error}`);
+    }
+    return result;
+}
+/**
+ * Get revisions from a compared document.
+ *
+ * @param document - A document that has been through comparison (has tracked changes)
+ * @param options - Optional move detection configuration
+ * @returns Array of revisions
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * // Default settings (move detection enabled, 80% threshold)
+ * const revisions = await getRevisions(comparedDoc);
+ *
+ * // Custom move detection settings
+ * const revisions = await getRevisions(comparedDoc, {
+ *   detectMoves: true,
+ *   moveSimilarityThreshold: 0.9,  // Require 90% word overlap
+ *   moveMinimumWordCount: 5,       // Only consider phrases of 5+ words
+ *   caseInsensitive: true          // Ignore case when matching
+ * });
+ *
+ * // Disable move detection entirely
+ * const revisions = await getRevisions(comparedDoc, { detectMoves: false });
+ * ```
+ */
+export async function getRevisions(document) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    // Yield to browser before WASM work - allows loading states to render
+    await yieldToMain();
+    const result = exports.DocumentComparer.GetRevisionsJson(bytes);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to get revisions: ${error.error}`);
+    }
+    // The payload is the session's own revision wire shape, so it needs no remapping.
+    return JSON.parse(result);
+}
+// ─── DocxDiff (IR diff engine) ──────────────────────────────────────────────
+//
+// The structure-aware default comparison engine. Its specialized APIs add
+// anchor-addressed revisions and the diff-as-data edit script. Settings flow as
+// a JSON object; an empty `{}` (or omitted options) uses the engine defaults.
+/** Serialize DocxDiffSettings to the wire JSON the bridge parses (empty string when undefined). */
+function docxDiffSettingsJson(settings) {
+    return settings ? JSON.stringify(settings) : "";
+}
+/**
+ * Compare two DOCX documents with the IR diff engine and return the redlined
+ * result as a DOCX (native w:ins/w:del/w:moveFrom/w:moveTo/w:rPrChange markup).
+ *
+ * @param left - The earlier/original document.
+ * @param right - The later/revised document.
+ * @param settings - Optional {@link DocxDiffSettings}; omit for engine defaults.
+ * @returns Redlined DOCX as Uint8Array.
+ * @throws Error if comparison fails.
+ */
+export async function docxDiffCompare(left, right, settings) {
+    const exports = ensureInitialized();
+    const leftBytes = await toBytes(left);
+    const rightBytes = await toBytes(right);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.Compare(leftBytes, rightBytes, docxDiffSettingsJson(settings));
+    if (result.length === 0) {
+        throw new Error("DocxDiff comparison failed - empty result");
+    }
+    return result;
+}
+/**
+ * Compare two DOCX documents with the IR diff engine and return the
+ * anchor-addressed revision list.
+ *
+ * @param left - The earlier/original document.
+ * @param right - The later/revised document.
+ * @param settings - Optional {@link DocxDiffSettings}; omit for engine defaults.
+ * @returns Array of {@link DocxDiffRevision} (each carrying its left/right block anchors).
+ * @throws Error if the operation fails.
+ */
+export async function docxDiffGetRevisions(left, right, settings) {
+    const exports = ensureInitialized();
+    const leftBytes = await toBytes(left);
+    const rightBytes = await toBytes(right);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.GetRevisionsJson(leftBytes, rightBytes, docxDiffSettingsJson(settings));
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to get DocxDiff revisions: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return (parsed.revisions || parsed.Revisions || []).map(mapDocxDiffRevision);
+}
+/**
+ * Compare two DOCX documents ONCE and return every requested data product from
+ * that single memoized pass (issue #594). Where a review pipeline calling
+ * {@link docxDiffCompare}, {@link docxDiffGetRevisions}, and
+ * {@link docxDiffGetEditScript} separately pays for the alignment per call, this
+ * runs it once — each product identical to its standalone counterpart (the edit
+ * script is handed over parsed rather than as the serialized string).
+ *
+ * @param left - The earlier/original document.
+ * @param right - The later/revised document.
+ * @param settings - Optional {@link DocxDiffSettings}; omit for engine defaults.
+ * @param products - Products to compute; omit for all four.
+ * @throws Error if the operation fails.
+ */
+export async function docxDiffCompareProducts(left, right, settings, products) {
+    const exports = ensureInitialized();
+    const leftBytes = await toBytes(left);
+    const rightBytes = await toBytes(right);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.CompareProductsJson(leftBytes, rightBytes, docxDiffSettingsJson(settings), products ? JSON.stringify(products) : "");
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to compare products: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return {
+        redline: typeof parsed.redlineB64 === "string"
+            ? Uint8Array.from(atob(parsed.redlineB64), c => c.charCodeAt(0))
+            : undefined,
+        revisions: Array.isArray(parsed.revisions)
+            ? parsed.revisions.map(mapDocxDiffRevision)
+            : undefined,
+        editScript: parsed.editScript !== undefined
+            ? parsed.editScript
+            : undefined,
+        semanticChanges: parsed.semanticChanges !== undefined
+            ? parsed.semanticChanges
+            : undefined,
+    };
+}
+/**
+ * Compare ONE baseline against MANY candidates, reading the baseline once (issue #617).
+ *
+ * The read is the single largest stage of a comparison, and a fan-out — one negotiated
+ * draft against every counterparty's markup — otherwise re-reads the baseline for each
+ * one. This reads it once and compares every candidate against that snapshot; each
+ * result is identical to what {@link docxDiffCompareProducts} returns for the same pair.
+ *
+ * A candidate that fails carries an `error` instead of products; the rest of the batch
+ * still comes back, because one malformed markup should not cost the other ninety-nine.
+ *
+ * @param baseline - The shared left-hand document.
+ * @param candidates - The documents to compare against it, in order.
+ * @param settings - Optional {@link DocxDiffSettings}; omit for engine defaults.
+ * @param products - Products to compute; omit for all four.
+ * @throws Error if the batch itself fails (a bad baseline, malformed settings).
+ */
+export async function docxDiffCompareBatch(baseline, candidates, settings, products) {
+    const exports = ensureInitialized();
+    const baselineBytes = await toBytes(baseline);
+    const payload = [];
+    for (let i = 0; i < candidates.length; i++) {
+        const bytes = await toBytes(candidates[i].document);
+        payload.push({
+            name: candidates[i].name ?? String(i),
+            docB64: bytesToBase64(bytes),
+        });
+    }
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.CompareBatchJson(baselineBytes, JSON.stringify(payload), docxDiffSettingsJson(settings), products ? JSON.stringify(products) : "");
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to compare batch: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return (parsed.results ?? []).map((entry) => ({
+        name: String(entry.name ?? ""),
+        error: typeof entry.error === "string" ? entry.error : undefined,
+        redline: typeof entry.redlineB64 === "string"
+            ? Uint8Array.from(atob(entry.redlineB64), c => c.charCodeAt(0))
+            : undefined,
+        revisions: Array.isArray(entry.revisions)
+            ? entry.revisions.map(mapDocxDiffRevision)
+            : undefined,
+        editScript: entry.editScript !== undefined
+            ? entry.editScript
+            : undefined,
+        semanticChanges: entry.semanticChanges !== undefined
+            ? entry.semanticChanges
+            : undefined,
+    }));
+}
+/**
+ * Compare two DOCX documents with the IR diff engine and return the edit script
+ * as a JSON string — the diff-as-data differentiator. The script is the
+ * anchor-addressed list of block operations the markup and revision renderers
+ * both consume: stable and machine-readable for storage, transport, and audit.
+ *
+ * @param left - The earlier/original document.
+ * @param right - The later/revised document.
+ * @param settings - Optional {@link DocxDiffSettings}; omit for engine defaults.
+ * @returns The edit script serialized as indented JSON.
+ * @throws Error if the operation fails.
+ */
+export async function docxDiffGetEditScript(left, right, settings) {
+    const exports = ensureInitialized();
+    const leftBytes = await toBytes(left);
+    const rightBytes = await toBytes(right);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.GetEditScriptJson(leftBytes, rightBytes, docxDiffSettingsJson(settings));
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to get DocxDiff edit script: ${error.error}`);
+    }
+    return result;
+}
+/**
+ * Compare two DOCX documents and return the stable, versioned semantic-change
+ * schema. This is the audit/verification surface; it classifies document meaning
+ * beyond the renderer's internal edit script and preserves unknown package changes.
+ */
+export async function docxDiffGetSemanticChanges(left, right, settings) {
+    const exports = ensureInitialized();
+    const leftBytes = await toBytes(left);
+    const rightBytes = await toBytes(right);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.GetSemanticChangesJson(leftBytes, rightBytes, docxDiffSettingsJson(settings));
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to get semantic changes: ${error.error}`);
+    }
+    return JSON.parse(result);
+}
+/**
+ * Accept every tracked revision in a redlined DOCX and return the resulting bytes
+ * (materializes the "right"/revised side). The byte-in, byte-out counterpart of
+ * {@link docxDiffCompare}: `docxDiffAcceptRevisions(await docxDiffCompare(left, right))`
+ * equals `right` at the per-block text level — so callers can verify the round-trip
+ * contract of a redline, not just inspect its shape.
+ *
+ * @param redline - A DOCX carrying tracked-changes markup (e.g. {@link docxDiffCompare} output).
+ * @returns The DOCX bytes with all revisions accepted.
+ * @throws Error if the operation fails.
+ */
+export async function docxDiffAcceptRevisions(redline) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(redline);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.AcceptRevisions(bytes);
+    if (result.length === 0) {
+        throw new Error("DocxDiff accept-revisions failed - empty result");
+    }
+    return result;
+}
+/**
+ * Reject every tracked revision in a redlined DOCX and return the resulting bytes
+ * (materializes the "left"/original side): `docxDiffRejectRevisions(await
+ * docxDiffCompare(left, right))` equals `left` at the per-block text level.
+ *
+ * @param redline - A DOCX carrying tracked-changes markup (e.g. {@link docxDiffCompare} output).
+ * @returns The DOCX bytes with all revisions rejected.
+ * @throws Error if the operation fails.
+ */
+export async function docxDiffRejectRevisions(redline) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(redline);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.RejectRevisions(bytes);
+    if (result.length === 0) {
+        throw new Error("DocxDiff reject-revisions failed - empty result");
+    }
+    return result;
+}
+// ─── DocxDiff consolidate (composite N-way) ─────────────────────────────────
+//
+// Merge several reviewers' edits against one shared base DOCX. Each reviewer is
+// base64-encoded into the `[{author,docB64}]` wire shape the host base64-DECODES
+// (standard base64, not url-safe). Settings flow as the diff-settings JSON object
+// extended with an optional integer `conflictResolution`.
+/**
+ * Encode a Uint8Array to a standard (non-url-safe) base64 string. Uses a chunked
+ * binary string so large documents don't blow the call-stack limit of
+ * `String.fromCharCode(...bytes)`, and works in both browser (`btoa`) and Node
+ * (`Buffer`) hosts.
+ */
+function bytesToBase64(bytes) {
+    if (typeof btoa === "function") {
+        let binary = "";
+        const chunkSize = 0x8000; // 32 KB per chunk keeps the spread small
+        for (let i = 0; i < bytes.length; i += chunkSize) {
+            const chunk = bytes.subarray(i, i + chunkSize);
+            binary += String.fromCharCode.apply(null, chunk);
+        }
+        return btoa(binary);
+    }
+    // Node fallback (e.g. unit tests outside a browser).
+    return Buffer.from(bytes).toString("base64");
+}
+/** Serialize reviewers to the `[{author,docB64}]` wire JSON the host expects. */
+async function reviewersJson(reviewers) {
+    const arr = await Promise.all(reviewers.map(async (r) => ({
+        author: r.author,
+        docB64: bytesToBase64(await toBytes(r.document)),
+    })));
+    return JSON.stringify(arr);
+}
+/**
+ * Serialize DocxDiffConsolidateSettings to the wire JSON the bridge parses. Same
+ * shape as {@link docxDiffSettingsJson} plus the integer `conflictResolution`
+ * when present (empty string when undefined).
+ */
+function docxDiffConsolidateSettingsJson(settings) {
+    return settings ? JSON.stringify(settings) : "";
+}
+/** Map a single revision wire object (camelCase or PascalCase) to {@link DocxDiffRevision}. */
+function mapDocxDiffRevision(r) {
+    return {
+        revisionType: r.revisionType ?? r.RevisionType,
+        text: r.text ?? r.Text,
+        author: r.author ?? r.Author,
+        date: r.date ?? r.Date,
+        moveGroupId: r.moveGroupId ?? r.MoveGroupId ?? undefined,
+        isMoveSource: r.isMoveSource ?? r.IsMoveSource ?? undefined,
+        formatChange: (r.formatChange || r.FormatChange) ? {
+            oldProperties: r.formatChange?.oldProperties ?? r.FormatChange?.OldProperties,
+            newProperties: r.formatChange?.newProperties ?? r.FormatChange?.NewProperties,
+            changedPropertyNames: r.formatChange?.changedPropertyNames ?? r.FormatChange?.ChangedPropertyNames,
+        } : undefined,
+        leftAnchor: r.leftAnchor ?? r.LeftAnchor ?? undefined,
+        rightAnchor: r.rightAnchor ?? r.RightAnchor ?? undefined,
+    };
+}
+/**
+ * Consolidate several reviewers' edits against a shared base DOCX and return the
+ * merged redlined result as a DOCX (native multi-author tracked-changes markup).
+ *
+ * @param base - The shared base document all reviewers edited from.
+ * @param reviewers - The reviewers' edited copies + author names.
+ * @param settings - Optional {@link DocxDiffConsolidateSettings}; omit for engine defaults.
+ * @returns Consolidated redlined DOCX as Uint8Array.
+ * @throws Error if consolidation fails.
+ */
+export async function docxDiffConsolidate(base, reviewers, settings) {
+    const exports = ensureInitialized();
+    const baseBytes = await toBytes(base);
+    const reviewersJsonStr = await reviewersJson(reviewers);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.Consolidate(baseBytes, reviewersJsonStr, docxDiffConsolidateSettingsJson(settings));
+    if (result.length === 0) {
+        throw new Error("DocxDiff consolidation failed - empty result");
+    }
+    return result;
+}
+/**
+ * Consolidate several reviewers' edits against a shared base DOCX and return the
+ * per-token conflict report — every base span two or more reviewers edited
+ * incompatibly, with each reviewer's competing variant.
+ *
+ * @param base - The shared base document all reviewers edited from.
+ * @param reviewers - The reviewers' edited copies + author names.
+ * @param settings - Optional {@link DocxDiffConsolidateSettings}; omit for engine defaults.
+ * @returns Array of {@link DocxDiffConflict}.
+ * @throws Error if the operation fails.
+ */
+export async function docxDiffGetConflicts(base, reviewers, settings) {
+    const exports = ensureInitialized();
+    const baseBytes = await toBytes(base);
+    const reviewersJsonStr = await reviewersJson(reviewers);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.GetConflictsJson(baseBytes, reviewersJsonStr, docxDiffConsolidateSettingsJson(settings));
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to get DocxDiff conflicts: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return (parsed.conflicts || parsed.Conflicts || []).map((c) => ({
+        id: c.id ?? c.Id,
+        baseAnchor: c.baseAnchor ?? c.BaseAnchor,
+        tokenStart: c.tokenStart ?? c.TokenStart,
+        tokenEnd: c.tokenEnd ?? c.TokenEnd,
+        policy: c.policy ?? c.Policy,
+        competitors: (c.competitors || c.Competitors || []).map((comp) => ({
+            author: comp.author ?? comp.Author,
+            resultText: comp.resultText ?? comp.ResultText,
+        })),
+    }));
+}
+/**
+ * Consolidate several reviewers' edits against a shared base DOCX and return the
+ * merged revision list — each revision carrying its author, block anchors, and
+ * (when contested) the {@link DocxDiffConsolidatedRevision.conflictId} linking it
+ * to a {@link DocxDiffConflict}.
+ *
+ * @param base - The shared base document all reviewers edited from.
+ * @param reviewers - The reviewers' edited copies + author names.
+ * @param settings - Optional {@link DocxDiffConsolidateSettings}; omit for engine defaults.
+ * @returns Array of {@link DocxDiffConsolidatedRevision}.
+ * @throws Error if the operation fails.
+ */
+export async function docxDiffGetConsolidatedRevisions(base, reviewers, settings) {
+    const exports = ensureInitialized();
+    const baseBytes = await toBytes(base);
+    const reviewersJsonStr = await reviewersJson(reviewers);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.GetConsolidatedRevisionsJson(baseBytes, reviewersJsonStr, docxDiffConsolidateSettingsJson(settings));
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to get DocxDiff consolidated revisions: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return (parsed.revisions || parsed.Revisions || []).map((r) => ({
+        ...mapDocxDiffRevision(r),
+        conflictId: r.conflictId ?? r.ConflictId ?? undefined,
+    }));
+}
+/**
+ * Consolidate several reviewers' edits against a shared base DOCX and return the
+ * merged edit script as a JSON string — the diff-as-data view of the
+ * consolidation (the anchor-addressed list of composite block operations).
+ *
+ * @param base - The shared base document all reviewers edited from.
+ * @param reviewers - The reviewers' edited copies + author names.
+ * @param settings - Optional {@link DocxDiffConsolidateSettings}; omit for engine defaults.
+ * @returns The consolidated edit script serialized as indented JSON.
+ * @throws Error if the operation fails.
+ */
+export async function docxDiffGetConsolidatedEditScript(base, reviewers, settings) {
+    const exports = ensureInitialized();
+    const baseBytes = await toBytes(base);
+    const reviewersJsonStr = await reviewersJson(reviewers);
+    await yieldToMain();
+    const result = exports.DocxDiffBridge.GetConsolidatedEditScriptJson(baseBytes, reviewersJsonStr, docxDiffConsolidateSettingsJson(settings));
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to get DocxDiff consolidated edit script: ${error.error}`);
+    }
+    return result;
+}
+/**
+ * Get version information about the library.
+ */
+export function getVersion() {
+    const exports = ensureInitialized();
+    const result = exports.DocumentConverter.GetVersion();
+    const parsed = JSON.parse(result);
+    return {
+        library: parsed.Library || parsed.library,
+        dotnetVersion: parsed.DotnetVersion || parsed.dotnetVersion,
+        platform: parsed.Platform || parsed.platform,
+    };
+}
+/**
+ * Check if the WASM runtime is initialized.
+ */
+export function isInitialized() {
+    return wasmExports !== null;
+}
+/**
+ * The raw WASM bridge exports (DocumentConverter, DocxSessionBridge, ...).
+ *
+ * For consumers that drive a bridge class directly — most notably
+ * `DocxEditor.open(container, bytes, exports)`, which needs the exports object
+ * rather than the wrapped functions in this module. Requires `initialize()` to
+ * have completed; throws otherwise.
+ */
+export function getWasmExports() {
+    return ensureInitialized();
+}
+/**
+ * Get all annotations from a document.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @returns Array of annotations
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const annotations = await getAnnotations(docxFile);
+ * for (const annot of annotations) {
+ *   console.log(`${annot.label}: "${annot.annotatedText}"`);
+ * }
+ * ```
+ */
+export async function getAnnotations(document) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    const result = exports.DocumentConverter.GetAnnotations(bytes);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to get annotations: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return (parsed.Annotations || parsed.annotations || []).map((a) => ({
+        id: a.Id || a.id,
+        labelId: a.LabelId || a.labelId,
+        label: a.Label || a.label,
+        color: a.Color || a.color,
+        author: a.Author || a.author,
+        created: a.Created || a.created,
+        bookmarkName: a.BookmarkName || a.bookmarkName,
+        startPage: a.StartPage ?? a.startPage,
+        endPage: a.EndPage ?? a.endPage,
+        annotatedText: a.AnnotatedText || a.annotatedText,
+        metadata: a.Metadata || a.metadata,
+    }));
+}
+/**
+ * Add an annotation to a document.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @param request - Annotation details including search text or paragraph indices
+ * @returns Response with modified document bytes and annotation info
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * // Annotate by searching for text
+ * const result = await addAnnotation(docxFile, {
+ *   id: "annot-1",
+ *   labelId: "CLAUSE_A",
+ *   label: "Important Clause",
+ *   color: "#FFEB3B",
+ *   searchText: "shall not be liable",
+ *   occurrence: 1
+ * });
+ *
+ * // Annotate by paragraph range
+ * const result = await addAnnotation(docxFile, {
+ *   id: "annot-2",
+ *   labelId: "SECTION_1",
+ *   label: "Introduction",
+ *   color: "#4CAF50",
+ *   startParagraphIndex: 0,
+ *   endParagraphIndex: 2
+ * });
+ *
+ * // Get modified document
+ * const modifiedDocBytes = base64ToBytes(result.documentBytes);
+ * ```
+ */
+export async function addAnnotation(document, request) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    // Yield to browser before WASM work - allows loading states to render
+    await yieldToMain();
+    const requestJson = JSON.stringify({
+        Id: request.id,
+        LabelId: request.labelId,
+        Label: request.label,
+        Color: request.color ?? "#FFEB3B",
+        Author: request.author,
+        SearchText: request.searchText,
+        Occurrence: request.occurrence ?? 1,
+        StartParagraphIndex: request.startParagraphIndex,
+        EndParagraphIndex: request.endParagraphIndex,
+        Metadata: request.metadata,
+    });
+    const result = exports.DocumentConverter.AddAnnotation(bytes, requestJson);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to add annotation: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    const annotation = parsed.Annotation || parsed.annotation;
+    return {
+        success: parsed.Success ?? parsed.success ?? true,
+        documentBytes: parsed.DocumentBytes || parsed.documentBytes,
+        annotation: annotation ? {
+            id: annotation.Id || annotation.id,
+            labelId: annotation.LabelId || annotation.labelId,
+            label: annotation.Label || annotation.label,
+            color: annotation.Color || annotation.color,
+            author: annotation.Author || annotation.author,
+            created: annotation.Created || annotation.created,
+            bookmarkName: annotation.BookmarkName || annotation.bookmarkName,
+            annotatedText: annotation.AnnotatedText || annotation.annotatedText,
+        } : undefined,
+    };
+}
+/**
+ * Remove an annotation from a document.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @param annotationId - The ID of the annotation to remove
+ * @returns Response with modified document bytes
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const result = await removeAnnotation(docxFile, "annot-1");
+ * const modifiedDocBytes = base64ToBytes(result.documentBytes);
+ * ```
+ */
+export async function removeAnnotation(document, annotationId) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    const result = exports.DocumentConverter.RemoveAnnotation(bytes, annotationId);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to remove annotation: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return {
+        success: parsed.Success ?? parsed.success ?? true,
+        documentBytes: parsed.DocumentBytes || parsed.documentBytes,
+    };
+}
+/**
+ * Check if a document has any annotations.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @returns true if the document has annotations
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * if (await hasAnnotations(docxFile)) {
+ *   const annotations = await getAnnotations(docxFile);
+ *   console.log(`Document has ${annotations.length} annotations`);
+ * }
+ * ```
+ */
+export async function hasAnnotations(document) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    const result = exports.DocumentConverter.HasAnnotations(bytes);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to check annotations: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return parsed.HasAnnotations ?? parsed.hasAnnotations ?? false;
+}
+/**
+ * Get the document structure for element-based annotation targeting.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @returns Document structure with element tree
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const structure = await getDocumentStructure(docxFile);
+ *
+ * // Navigate the structure tree
+ * console.log(`Document has ${structure.root.children.length} top-level elements`);
+ *
+ * // Find all paragraphs
+ * const paragraphs = getParagraphs(structure);
+ * console.log(`Found ${paragraphs.length} paragraphs`);
+ *
+ * // Find all tables
+ * const tables = getTables(structure);
+ * for (const table of tables) {
+ *   const columns = getTableColumns(structure, table.id);
+ *   console.log(`Table ${table.id} has ${columns.length} columns`);
+ * }
+ *
+ * // Look up element by ID
+ * const element = findElementById(structure, "doc/p-0");
+ * if (element) {
+ *   console.log(`First paragraph: "${element.textPreview}"`);
+ * }
+ * ```
+ */
+export async function getDocumentStructure(document) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    // Yield to browser before WASM work - allows loading states to render
+    await yieldToMain();
+    const result = exports.DocumentConverter.GetDocumentStructure(bytes);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to get document structure: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    // Convert from PascalCase to camelCase
+    const convertElement = (el) => ({
+        id: el.Id || el.id,
+        anchorId: el.AnchorId || el.anchorId,
+        type: el.Type || el.type,
+        textPreview: el.TextPreview || el.textPreview,
+        index: el.Index ?? el.index,
+        rowIndex: el.RowIndex ?? el.rowIndex,
+        columnIndex: el.ColumnIndex ?? el.columnIndex,
+        rowSpan: el.RowSpan ?? el.rowSpan,
+        columnSpan: el.ColumnSpan ?? el.columnSpan,
+        children: (el.Children || el.children || []).map(convertElement),
+    });
+    const convertTableColumn = (col) => ({
+        tableId: col.TableId || col.tableId,
+        anchorId: col.AnchorId || col.anchorId,
+        tableAnchorId: col.TableAnchorId || col.tableAnchorId,
+        isVirtual: col.IsVirtual ?? col.isVirtual ?? false,
+        columnIndex: col.ColumnIndex ?? col.columnIndex,
+        cellIds: col.CellIds || col.cellIds || [],
+        cellAnchorIds: col.CellAnchorIds || col.cellAnchorIds || [],
+        rowCount: col.RowCount ?? col.rowCount,
+    });
+    const root = convertElement(parsed.Root || parsed.root);
+    // Convert elementsById dictionary
+    const elementsById = {};
+    const rawElementsById = parsed.ElementsById || parsed.elementsById || {};
+    for (const [key, el] of Object.entries(rawElementsById)) {
+        elementsById[key] = convertElement(el);
+    }
+    // Convert tableColumns dictionary
+    const tableColumns = {};
+    const rawTableColumns = parsed.TableColumns || parsed.tableColumns || {};
+    for (const [key, col] of Object.entries(rawTableColumns)) {
+        tableColumns[key] = convertTableColumn(col);
+    }
+    return {
+        root,
+        elementsById,
+        tableColumns,
+    };
+}
+/**
+ * Get document metadata for lazy loading pagination.
+ * This is a fast operation that extracts structure information without full HTML rendering.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @returns Document metadata including sections, dimensions, and content counts
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const metadata = await getDocumentMetadata(docxFile);
+ *
+ * // Check document overview
+ * console.log(`Document has ${metadata.totalParagraphs} paragraphs`);
+ * console.log(`Document has ${metadata.sections.length} sections`);
+ * console.log(`Estimated ${metadata.estimatedPageCount} pages`);
+ *
+ * // Check section properties
+ * for (const section of metadata.sections) {
+ *   console.log(`Section ${section.sectionIndex}: ${section.pageWidthPt}x${section.pageHeightPt}pt`);
+ *   console.log(`  Paragraphs: ${section.paragraphCount}, Tables: ${section.tableCount}`);
+ *   console.log(`  Has header: ${section.hasHeader}, Has footer: ${section.hasFooter}`);
+ * }
+ *
+ * // Check document features
+ * if (metadata.hasTrackedChanges) {
+ *   console.log("Document has tracked changes");
+ * }
+ * if (metadata.hasFootnotes) {
+ *   console.log("Document has footnotes");
+ * }
+ * ```
+ */
+export async function getDocumentMetadata(document) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    // Yield to browser before WASM work - allows loading states to render
+    await yieldToMain();
+    const result = exports.DocumentConverter.GetDocumentMetadata(bytes);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to get document metadata: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    // Convert from PascalCase to camelCase
+    const convertSection = (s) => ({
+        sectionIndex: s.SectionIndex ?? s.sectionIndex,
+        pageWidthPt: s.PageWidthPt ?? s.pageWidthPt,
+        pageHeightPt: s.PageHeightPt ?? s.pageHeightPt,
+        marginTopPt: s.MarginTopPt ?? s.marginTopPt,
+        marginRightPt: s.MarginRightPt ?? s.marginRightPt,
+        marginBottomPt: s.MarginBottomPt ?? s.marginBottomPt,
+        marginLeftPt: s.MarginLeftPt ?? s.marginLeftPt,
+        contentWidthPt: s.ContentWidthPt ?? s.contentWidthPt,
+        contentHeightPt: s.ContentHeightPt ?? s.contentHeightPt,
+        headerPt: s.HeaderPt ?? s.headerPt,
+        footerPt: s.FooterPt ?? s.footerPt,
+        paragraphCount: s.ParagraphCount ?? s.paragraphCount,
+        tableCount: s.TableCount ?? s.tableCount,
+        hasHeader: s.HasHeader ?? s.hasHeader,
+        hasFooter: s.HasFooter ?? s.hasFooter,
+        hasFirstPageHeader: s.HasFirstPageHeader ?? s.hasFirstPageHeader,
+        hasFirstPageFooter: s.HasFirstPageFooter ?? s.hasFirstPageFooter,
+        hasEvenPageHeader: s.HasEvenPageHeader ?? s.hasEvenPageHeader,
+        hasEvenPageFooter: s.HasEvenPageFooter ?? s.hasEvenPageFooter,
+        startParagraphIndex: s.StartParagraphIndex ?? s.startParagraphIndex,
+        endParagraphIndex: s.EndParagraphIndex ?? s.endParagraphIndex,
+        startTableIndex: s.StartTableIndex ?? s.startTableIndex,
+        endTableIndex: s.EndTableIndex ?? s.endTableIndex,
+    });
+    return {
+        sections: (parsed.Sections || parsed.sections || []).map(convertSection),
+        totalParagraphs: parsed.TotalParagraphs ?? parsed.totalParagraphs,
+        totalTables: parsed.TotalTables ?? parsed.totalTables,
+        hasFootnotes: parsed.HasFootnotes ?? parsed.hasFootnotes,
+        hasEndnotes: parsed.HasEndnotes ?? parsed.hasEndnotes,
+        hasTrackedChanges: parsed.HasTrackedChanges ?? parsed.hasTrackedChanges,
+        hasComments: parsed.HasComments ?? parsed.hasComments,
+        estimatedPageCount: parsed.EstimatedPageCount ?? parsed.estimatedPageCount,
+        estimatedPageCountSource: parsed.EstimatedPageCountSource ?? parsed.estimatedPageCountSource ?? "heuristic",
+    };
+}
+/**
+ * Export document to OpenContracts format.
+ *
+ * This provides complete document text, structure, and layout information
+ * compatible with the OpenContracts ecosystem for document analysis.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @returns OpenContractDocExport with complete document data
+ * @throws Error if export fails
+ *
+ * @example
+ * ```typescript
+ * const result = await exportToOpenContract(docxFile);
+ *
+ * // Access complete document text
+ * console.log(`Content length: ${result.content.length} characters`);
+ *
+ * // Get document structure
+ * console.log(`Pages: ${result.pageCount}`);
+ * console.log(`Structural annotations: ${result.labelledText.filter(a => a.structural).length}`);
+ *
+ * // Access PAWLS layout data
+ * for (const page of result.pawlsFileContent) {
+ *   console.log(`Page ${page.page.index}: ${page.tokens.length} tokens`);
+ * }
+ * ```
+ */
+export async function exportToOpenContract(document) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    // Yield to browser before WASM work - allows loading states to render
+    await yieldToMain();
+    const result = exports.DocumentConverter.ExportToOpenContract(bytes);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to export to OpenContract format: ${error.error}`);
+    }
+    return readOpenContractExport(JSON.parse(result));
+}
+/**
+ * Convert a DOCX file to an anchor-addressed Markdown projection.
+ *
+ * The projection is a deterministic, anchor-keyed Markdown rendering of the document,
+ * suitable for LLM editing pipelines, structured search indexers, and diff/review UIs.
+ * Every paragraph, heading, list item, table, table cell, footnote, endnote, and
+ * comment is addressable by an `{#kind:scope:unid}` anchor that survives reformatting.
+ *
+ * See `docs/architecture/markdown_projection.md` for the projection spec.
+ *
+ * @param document - DOCX file as `File` or `Uint8Array`
+ * @param settings - Optional projection settings (defaults: all scopes, anchor blocks, accept tracked changes)
+ * @throws Error if conversion fails
+ *
+ * @example
+ * ```typescript
+ * const result = await convertWmlToMarkdown(docxFile);
+ * console.log(result.markdown);
+ * for (const [id, target] of Object.entries(result.anchorIndex)) {
+ *   console.log(id, target.partUri);
+ * }
+ * ```
+ */
+export async function convertWmlToMarkdown(document, settings = {}) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    await yieldToMain();
+    const settingsJson = JSON.stringify({
+        Scopes: settings.scopes ?? ProjectionScopes.All,
+        HeadingLevelOffset: settings.headingLevelOffset ?? 0,
+        AnchorMode: settings.anchorMode ?? AnchorRenderMode.Block,
+        TableMode: settings.tableMode ?? TableRenderMode.GfmWithOpaqueFallback,
+        TableInlineCellMax: settings.tableInlineCellMax ?? 80,
+        TrackedChanges: settings.trackedChanges ?? TrackedChangeMode.Accept,
+        ResolveNumbering: settings.resolveNumbering ?? true,
+        EmptyParagraphs: settings.emptyParagraphs ?? EmptyParagraphMode.AnchorOnly,
+    });
+    const result = exports.DocumentConverter.ConvertWmlToMarkdown(bytes, settingsJson);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to convert document to markdown: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    const rawIndex = parsed.AnchorIndex ?? parsed.anchorIndex ?? {};
+    const anchorIndex = {};
+    for (const [key, value] of Object.entries(rawIndex)) {
+        const v = value;
+        anchorIndex[key] = {
+            id: v.Id ?? v.id,
+            kind: v.Kind ?? v.kind,
+            scope: v.Scope ?? v.scope,
+            unid: v.Unid ?? v.unid,
+            partUri: v.PartUri ?? v.partUri,
+            textPreview: v.TextPreview ?? v.textPreview ?? "",
+        };
+    }
+    return {
+        markdown: parsed.Markdown ?? parsed.markdown ?? "",
+        anchorIndex,
+    };
+}
+/**
+ * Add an annotation using flexible targeting (element ID, indices, or text search).
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @param request - Annotation details with target specification
+ * @returns Response with modified document bytes and annotation info
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * // First get the document structure to find target elements
+ * const structure = await getDocumentStructure(docxFile);
+ *
+ * // Annotate a specific paragraph by element ID
+ * const result1 = await addAnnotationWithTarget(docxFile, {
+ *   id: "annot-1",
+ *   labelId: "INTRO",
+ *   label: "Introduction",
+ *   color: "#4CAF50",
+ *   target: targetElement("doc/p-0")
+ * });
+ *
+ * // Annotate a table cell
+ * const result2 = await addAnnotationWithTarget(docxFile, {
+ *   id: "annot-2",
+ *   labelId: "CELL_HIGHLIGHT",
+ *   label: "Important Cell",
+ *   color: "#FFEB3B",
+ *   target: targetTableCell(0, 1, 2)  // Table 0, Row 1, Cell 2
+ * });
+ *
+ * // Annotate a table column
+ * const result3 = await addAnnotationWithTarget(docxFile, {
+ *   id: "annot-3",
+ *   labelId: "COLUMN_DATA",
+ *   label: "Values Column",
+ *   color: "#2196F3",
+ *   target: targetTableColumn(0, 1)  // Table 0, Column 1
+ * });
+ *
+ * // Search for text within a specific element
+ * const result4 = await addAnnotationWithTarget(docxFile, {
+ *   id: "annot-4",
+ *   labelId: "KEYWORD",
+ *   label: "Keyword",
+ *   color: "#FF5722",
+ *   target: targetSearchInElement("doc/p-2", "important", 1)
+ * });
+ * ```
+ */
+export async function addAnnotationWithTarget(document, request) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    // Yield to browser before WASM work - allows loading states to render
+    await yieldToMain();
+    const requestJson = JSON.stringify({
+        Id: request.id,
+        LabelId: request.labelId,
+        Label: request.label,
+        Color: request.color ?? "#FFEB3B",
+        Author: request.author,
+        Metadata: request.metadata,
+        ElementId: request.target.elementId,
+        ElementType: request.target.elementType,
+        ParagraphIndex: request.target.paragraphIndex,
+        RunIndex: request.target.runIndex,
+        TableIndex: request.target.tableIndex,
+        RowIndex: request.target.rowIndex,
+        CellIndex: request.target.cellIndex,
+        ColumnIndex: request.target.columnIndex,
+        SearchText: request.target.searchText,
+        Occurrence: request.target.occurrence ?? 1,
+        RangeEndParagraphIndex: request.target.rangeEndParagraphIndex,
+    });
+    const result = exports.DocumentConverter.AddAnnotationWithTarget(bytes, requestJson);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to add annotation: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    const annotation = parsed.Annotation || parsed.annotation;
+    return {
+        success: parsed.Success ?? parsed.success ?? true,
+        documentBytes: parsed.DocumentBytes || parsed.documentBytes,
+        annotation: annotation ? {
+            id: annotation.Id || annotation.id,
+            labelId: annotation.LabelId || annotation.labelId,
+            label: annotation.Label || annotation.label,
+            color: annotation.Color || annotation.color,
+            author: annotation.Author || annotation.author,
+            created: annotation.Created || annotation.created,
+            bookmarkName: annotation.BookmarkName || annotation.bookmarkName,
+            annotatedText: annotation.AnnotatedText || annotation.annotatedText,
+            metadata: annotation.Metadata || annotation.metadata,
+        } : undefined,
+    };
+}
+// ============================================================================
+// External Annotation Functions (Issue #57)
+// ============================================================================
+/**
+ * Compute the SHA256 hash of a document for integrity validation.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @returns SHA256 hash as lowercase hex string
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const hash = await computeDocumentHash(docxFile);
+ * console.log(`Document hash: ${hash}`);
+ *
+ * // Later, verify the document hasn't changed
+ * const currentHash = await computeDocumentHash(docxFile);
+ * if (currentHash !== storedHash) {
+ *   console.log("Document has been modified");
+ * }
+ * ```
+ */
+export async function computeDocumentHash(document) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    const result = exports.DocumentConverter.ComputeDocumentHash(bytes);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to compute document hash: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return parsed.Hash ?? parsed.hash;
+}
+/**
+ * Create an ExternalAnnotationSet from a document.
+ * This extracts the document structure and computes the hash for integrity validation.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @param documentId - Unique identifier for the document (filename, UUID, etc.)
+ * @returns ExternalAnnotationSet ready for adding annotations
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * // Create an annotation set
+ * const set = await createExternalAnnotationSet(docxFile, "contract-v1.0");
+ *
+ * // Access document text for searching
+ * console.log(`Document length: ${set.content.length} chars`);
+ *
+ * // Add label definitions
+ * set.textLabels["IMPORTANT"] = {
+ *   id: "IMPORTANT",
+ *   text: "Important",
+ *   color: "#FF0000",
+ *   description: "Important text",
+ *   icon: "",
+ *   labelType: "text"
+ * };
+ *
+ * // Create annotations using the content
+ * const annotation = createAnnotationFromSearch(
+ *   "ann-001", "IMPORTANT", set.content, "shall not be liable"
+ * );
+ * if (annotation) {
+ *   set.labelledText.push(annotation);
+ * }
+ *
+ * // Serialize for storage
+ * const json = JSON.stringify(set);
+ * ```
+ */
+export async function createExternalAnnotationSet(document, documentId) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    // Yield to browser before WASM work - allows loading states to render
+    await yieldToMain();
+    const result = exports.DocumentConverter.CreateExternalAnnotationSet(bytes, documentId);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to create external annotation set: ${error.error}`);
+    }
+    return readExternalAnnotationSet(JSON.parse(result));
+}
+/**
+ * Validate an external annotation set against a document.
+ * Checks hash match and verifies each annotation's text still matches.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @param annotationSet - The annotation set to validate
+ * @returns Validation result with any issues found
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const result = await validateExternalAnnotations(docxFile, annotationSet);
+ *
+ * if (!result.isValid) {
+ *   if (result.hashMismatch) {
+ *     console.log("Document has been modified since annotations were created");
+ *   }
+ *   for (const issue of result.issues) {
+ *     console.log(`${issue.issueType}: ${issue.description}`);
+ *   }
+ * }
+ * ```
+ */
+export async function validateExternalAnnotations(document, annotationSet) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    // Yield to browser before WASM work - allows loading states to render
+    await yieldToMain();
+    const annotationSetJson = JSON.stringify(annotationSet);
+    const result = exports.DocumentConverter.ValidateExternalAnnotations(bytes, annotationSetJson);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to validate external annotations: ${error.error}`);
+    }
+    return readExternalAnnotationValidation(JSON.parse(result));
+}
+/**
+ * Convert a DOCX document to HTML with external annotations projected.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @param annotationSet - The external annotation set to project
+ * @param conversionOptions - HTML conversion options
+ * @param projectionOptions - Annotation projection options
+ * @returns HTML string with annotations projected
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const html = await convertDocxToHtmlWithExternalAnnotations(
+ *   docxFile,
+ *   annotationSet
+ * );
+ *
+ * // With custom options
+ * const html = await convertDocxToHtmlWithExternalAnnotations(
+ *   docxFile,
+ *   annotationSet,
+ *   { pageTitle: "Annotated Document" },
+ *   { labelMode: AnnotationLabelMode.Inline, cssClassPrefix: "my-annot-" }
+ * );
+ * ```
+ */
+export async function convertDocxToHtmlWithExternalAnnotations(document, annotationSet, conversionOptions, projectionOptions) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    // Yield to browser before WASM work - allows loading states to render
+    await yieldToMain();
+    const annotationSetJson = JSON.stringify(annotationSet);
+    const result = exports.DocumentConverter.ConvertDocxToHtmlWithExternalAnnotations(bytes, annotationSetJson, conversionOptions?.pageTitle ?? "Document", conversionOptions?.cssPrefix ?? "docx-", conversionOptions?.fabricateClasses ?? true, conversionOptions?.additionalCss ?? "", projectionOptions?.cssClassPrefix ?? "ext-annot-", projectionOptions?.labelMode ?? AnnotationLabelMode.Above);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to convert with external annotations: ${error.error}`);
+    }
+    return readProjectedHtml(JSON.parse(result));
+}
+/**
+ * Search for text in a document and return character offsets.
+ * Useful for finding text locations to create annotations.
+ *
+ * @param document - DOCX file as File object or Uint8Array
+ * @param searchText - Text to search for
+ * @param maxResults - Maximum number of results (default: 100)
+ * @returns Array of TextSpan objects with offsets
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const occurrences = await searchTextOffsets(docxFile, "liability");
+ * console.log(`Found ${occurrences.length} occurrences`);
+ *
+ * for (const span of occurrences) {
+ *   console.log(`"${span.text}" at offset ${span.start}-${span.end}`);
+ * }
+ * ```
+ */
+export async function searchTextOffsets(document, searchText, maxResults = 100) {
+    const exports = ensureInitialized();
+    const bytes = await toBytes(document);
+    // Yield to browser before WASM work - allows loading states to render
+    await yieldToMain();
+    const result = exports.DocumentConverter.SearchTextOffsets(bytes, searchText, maxResults);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to search text: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return (parsed.Results || parsed.results || []).map((r) => ({
+        id: r.Id ?? r.id,
+        start: r.Start ?? r.start,
+        end: r.End ?? r.end,
+        text: r.Text ?? r.text,
+    }));
+}
+/**
+ * Create an annotation from character offsets.
+ * This is a client-side helper - no WASM call needed.
+ *
+ * @param id - Unique identifier for the annotation
+ * @param labelId - Label/category ID for the annotation
+ * @param documentText - Full document text (from annotationSet.content)
+ * @param startOffset - Start character offset (0-indexed, inclusive)
+ * @param endOffset - End character offset (exclusive)
+ * @returns OpenContractsAnnotation ready to add to an annotation set
+ * @throws Error if offsets are invalid
+ *
+ * @example
+ * ```typescript
+ * const set = await createExternalAnnotationSet(docxFile, "doc-1");
+ * const annotation = createAnnotation("ann-001", "IMPORTANT", set.content, 100, 150);
+ * set.labelledText.push(annotation);
+ * ```
+ */
+export function createAnnotation(id, labelId, documentText, startOffset, endOffset) {
+    if (startOffset < 0) {
+        throw new Error("Start offset must be non-negative");
+    }
+    if (endOffset < startOffset) {
+        throw new Error("End offset must be >= start offset");
+    }
+    if (endOffset > documentText.length) {
+        throw new Error("End offset exceeds document length");
+    }
+    const rawText = documentText.substring(startOffset, endOffset);
+    return {
+        id,
+        annotationLabel: labelId,
+        rawText,
+        page: 0,
+        annotationJson: {
+            id,
+            start: startOffset,
+            end: endOffset,
+            text: rawText,
+        },
+        annotationType: "text",
+        structural: false,
+    };
+}
+/**
+ * Create an annotation by searching for text in the document.
+ * This is a client-side helper - no WASM call needed.
+ *
+ * @param id - Unique identifier for the annotation
+ * @param labelId - Label/category ID for the annotation
+ * @param documentText - Full document text (from annotationSet.content)
+ * @param searchText - Text to search for
+ * @param occurrence - Which occurrence to use (1-based, default: 1)
+ * @returns OpenContractsAnnotation, or null if text not found
+ *
+ * @example
+ * ```typescript
+ * const set = await createExternalAnnotationSet(docxFile, "doc-1");
+ *
+ * // Find first occurrence
+ * const ann1 = createAnnotationFromSearch("ann-001", "LIABILITY", set.content, "shall not be liable");
+ * if (ann1) set.labelledText.push(ann1);
+ *
+ * // Find second occurrence
+ * const ann2 = createAnnotationFromSearch("ann-002", "LIABILITY", set.content, "shall not be liable", 2);
+ * if (ann2) set.labelledText.push(ann2);
+ * ```
+ */
+export function createAnnotationFromSearch(id, labelId, documentText, searchText, occurrence = 1) {
+    if (occurrence < 1) {
+        throw new Error("Occurrence must be >= 1");
+    }
+    const offsets = findTextOccurrences(documentText, searchText);
+    if (occurrence > offsets.length) {
+        return null;
+    }
+    const { start, end } = offsets[occurrence - 1];
+    return createAnnotation(id, labelId, documentText, start, end);
+}
+/**
+ * Find all occurrences of a text string in the document.
+ * This is a client-side helper - no WASM call needed.
+ *
+ * @param documentText - Full document text
+ * @param searchText - Text to search for
+ * @param maxResults - Maximum number of results (default: 100)
+ * @returns Array of { start, end } offsets
+ *
+ * @example
+ * ```typescript
+ * const occurrences = findTextOccurrences(set.content, "the");
+ * console.log(`Found ${occurrences.length} occurrences of "the"`);
+ * ```
+ */
+export function findTextOccurrences(documentText, searchText, maxResults = 100) {
+    if (!searchText)
+        return [];
+    const results = [];
+    let index = 0;
+    while (results.length < maxResults) {
+        index = documentText.indexOf(searchText, index);
+        if (index < 0)
+            break;
+        results.push({ start: index, end: index + searchText.length });
+        index += 1; // Move past start to find overlapping matches
+    }
+    return results;
+}
+// Helper function to convert PascalCase response to camelCase ExternalAnnotationSet
+// ============================================================================
+// Incremental Annotation Overlay API (Issue #106)
+// ============================================================================
+/**
+ * Project external annotations onto already-converted HTML.
+ * This avoids full DOCX re-conversion when only annotations change.
+ *
+ * Workflow:
+ * 1. Convert DOCX to HTML once using `convertDocxToHtml()`
+ * 2. Use this function to overlay annotations on the cached HTML
+ * 3. When annotations change, call this again with the same base HTML
+ *
+ * @param html - HTML string (previously converted via convertDocxToHtml)
+ * @param annotationSet - The external annotation set to project
+ * @param projectionOptions - Projection settings (CSS prefix, label mode, etc.)
+ * @returns HTML string with annotations projected
+ * @throws Error if projection fails
+ *
+ * @example
+ * ```typescript
+ * // Step 1: Convert once
+ * const baseHtml = await convertDocxToHtml(docxFile);
+ *
+ * // Step 2: Project annotations (fast, no DOCX re-conversion)
+ * const annotatedHtml = await projectAnnotationsOntoHtml(baseHtml, annotationSet);
+ *
+ * // Step 3: When annotations change, project again on the same base HTML
+ * annotationSet.labelledText.push(newAnnotation);
+ * const updatedHtml = await projectAnnotationsOntoHtml(baseHtml, annotationSet);
+ * ```
+ */
+export async function projectAnnotationsOntoHtml(html, annotationSet, projectionOptions) {
+    const exports = ensureInitialized();
+    await yieldToMain();
+    const annotationSetJson = JSON.stringify(annotationSet);
+    const result = exports.DocumentConverter.ProjectAnnotationsOntoHtml(html, annotationSetJson, projectionOptions?.cssClassPrefix ?? "ext-annot-", projectionOptions?.labelMode ?? AnnotationLabelMode.Above);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to project annotations: ${error.error}`);
+    }
+    return readProjectedHtml(JSON.parse(result));
+}
+/**
+ * Add a single annotation to existing HTML without re-converting the document.
+ * This is the fastest way to add one annotation to already-rendered HTML.
+ *
+ * @param html - HTML string (with or without existing annotations)
+ * @param annotation - The annotation to add
+ * @param label - Label definition for the annotation (optional, for color/text)
+ * @param projectionOptions - Projection settings
+ * @returns HTML string with the annotation added
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const annotation = createAnnotation("ann-new", "CLAUSE", set.content, 100, 150);
+ * const label = { id: "CLAUSE", text: "Clause", color: "#FF5722" };
+ * const updatedHtml = await addAnnotationToHtml(currentHtml, annotation, label);
+ * ```
+ */
+export async function addAnnotationToHtml(html, annotation, label, projectionOptions) {
+    const exports = ensureInitialized();
+    await yieldToMain();
+    const annotationJson = JSON.stringify(annotation);
+    const labelJson = label ? JSON.stringify(label) : "";
+    const result = exports.DocumentConverter.AddAnnotationToHtml(html, annotationJson, labelJson, projectionOptions?.cssClassPrefix ?? "ext-annot-", projectionOptions?.labelMode ?? AnnotationLabelMode.Above);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to add annotation to HTML: ${error.error}`);
+    }
+    return readProjectedHtml(JSON.parse(result));
+}
+/**
+ * Remove a single annotation from HTML by annotation ID.
+ * Unwraps annotation spans back to plain text.
+ *
+ * @param html - HTML string with annotations
+ * @param annotationId - ID of the annotation to remove
+ * @param cssClassPrefix - CSS class prefix used for annotations (default: "ext-annot-")
+ * @returns HTML string with the annotation removed
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const updatedHtml = await removeAnnotationFromHtml(currentHtml, "ann-001");
+ * ```
+ */
+export async function removeAnnotationFromHtml(html, annotationId, cssClassPrefix) {
+    const exports = ensureInitialized();
+    await yieldToMain();
+    const result = exports.DocumentConverter.RemoveAnnotationFromHtml(html, annotationId, cssClassPrefix ?? "ext-annot-");
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to remove annotation from HTML: ${error.error}`);
+    }
+    return readProjectedHtml(JSON.parse(result));
+}
+/**
+ * Generate CSS to hide annotations with specific label IDs.
+ * Enables CSS-based label filtering without re-rendering HTML.
+ *
+ * Apply the returned CSS to your document (e.g., via a `<style>` element)
+ * to hide/show annotations by label. This is much faster than re-projecting
+ * all annotations.
+ *
+ * @param hiddenLabelIds - Array of label IDs to hide
+ * @param cssClassPrefix - CSS class prefix (default: "ext-annot-")
+ * @returns CSS string that hides the specified labels
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * // Hide annotations with label "DRAFT" and "INTERNAL"
+ * const css = await generateAnnotationVisibilityCss(["DRAFT", "INTERNAL"]);
+ *
+ * // Apply to a <style> element in the DOM
+ * const styleEl = document.getElementById("visibility-overrides");
+ * styleEl.textContent = css;
+ *
+ * // To show all annotations again, clear the style:
+ * styleEl.textContent = "";
+ * ```
+ */
+export async function generateAnnotationVisibilityCss(hiddenLabelIds, cssClassPrefix) {
+    const exports = ensureInitialized();
+    await yieldToMain();
+    const result = exports.DocumentConverter.GenerateAnnotationVisibilityCss(JSON.stringify(hiddenLabelIds), cssClassPrefix ?? "ext-annot-");
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to generate visibility CSS: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return parsed.Css ?? parsed.css;
+}
+/**
+ * Generate annotation CSS for a set of labels.
+ * Useful when managing CSS separately from HTML content.
+ *
+ * @param labels - Label definitions (keyed by label ID)
+ * @param projectionOptions - Projection settings
+ * @returns CSS string for the annotation styles
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const labels = {
+ *   "CLAUSE": { id: "CLAUSE", text: "Clause", color: "#FF5722" },
+ *   "TERM": { id: "TERM", text: "Term", color: "#2196F3" },
+ * };
+ * const css = await generateAnnotationCss(labels);
+ * ```
+ */
+export async function generateAnnotationCss(labels, projectionOptions) {
+    const exports = ensureInitialized();
+    await yieldToMain();
+    const result = exports.DocumentConverter.GenerateAnnotationCss(JSON.stringify(labels), projectionOptions?.cssClassPrefix ?? "ext-annot-", projectionOptions?.labelMode ?? AnnotationLabelMode.Above);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to generate annotation CSS: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return parsed.Css ?? parsed.css;
+}
+//# sourceMappingURL=core.js.map