docxodus 12.3.0 → 12.4.1

package/dist/index.js

@@ -1,50 +1,5 @@
-import { openDocxSession as openDocxSessionImpl } from "./session.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";
+/** Full browser API. Use docxodus/core for the engine without editor dependencies. */
+export * from "./core.js";
 export { DocxEditor } from "./editor.js";
 // The comment gutter and header/footer region are the editor's own; exported for hosts that
 // build their own chrome and want to drive them directly.
@@ -53,2050 +8,4 @@ export { CommentGutter } from "./editor-comments.js";
 // loading overlay wired onto DocxEditor's command surface. `createRibbonEditor`
 // (docxodus/embed) is the one-call version that also boots WASM.
 export { mountRibbon } from "./ribbon.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.2.0/dist/index.js"
-        // or "file:///path/to/node_modules/docxodus/dist/index.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) {
-    const exports = ensureInitialized();
-    const bytes = await toBytes(document);
-    const baselineBytes = baseline === undefined ? undefined : await toBytes(baseline);
-    await yieldToMain();
-    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}`);
-    }
-    const parsed = JSON.parse(result);
-    // Convert from PascalCase to camelCase
-    const convertPawlsPage = (p) => ({
-        page: {
-            width: p.Page?.Width ?? p.page?.width,
-            height: p.Page?.Height ?? p.page?.height,
-            index: p.Page?.Index ?? p.page?.index,
-        },
-        tokens: (p.Tokens || p.tokens || []).map((t) => ({
-            x: t.X ?? t.x,
-            y: t.Y ?? t.y,
-            width: t.Width ?? t.width,
-            height: t.Height ?? t.height,
-            text: t.Text ?? t.text,
-        })),
-    });
-    const convertAnnotation = (a) => ({
-        id: a.Id ?? a.id,
-        annotationLabel: a.AnnotationLabel ?? a.annotationLabel,
-        rawText: a.RawText ?? a.rawText,
-        page: a.Page ?? a.page,
-        annotationJson: convertAnnotationJson(a.AnnotationJson ?? a.annotationJson),
-        parentId: a.ParentId ?? a.parentId,
-        annotationType: a.AnnotationType ?? a.annotationType,
-        structural: a.Structural ?? a.structural,
-    });
-    const convertAnnotationJson = (json) => {
-        if (!json)
-            return undefined;
-        // Check if it's a TextSpan
-        if (json.Start !== undefined || json.start !== undefined) {
-            return {
-                id: json.Id ?? json.id,
-                start: json.Start ?? json.start,
-                end: json.End ?? json.end,
-                text: json.Text ?? json.text,
-            };
-        }
-        // Otherwise it's a dictionary of single-page annotations
-        const result = {};
-        for (const [key, value] of Object.entries(json)) {
-            const v = value;
-            result[key] = {
-                bounds: {
-                    top: v.Bounds?.Top ?? v.bounds?.top,
-                    bottom: v.Bounds?.Bottom ?? v.bounds?.bottom,
-                    left: v.Bounds?.Left ?? v.bounds?.left,
-                    right: v.Bounds?.Right ?? v.bounds?.right,
-                },
-                tokensJsons: (v.TokensJsons || v.tokensJsons || []).map((t) => ({
-                    pageIndex: t.PageIndex ?? t.pageIndex,
-                    tokenIndex: t.TokenIndex ?? t.tokenIndex,
-                })),
-                rawText: v.RawText ?? v.rawText,
-            };
-        }
-        return result;
-    };
-    const convertRelationship = (r) => ({
-        id: r.Id ?? r.id,
-        relationshipLabel: r.RelationshipLabel ?? r.relationshipLabel,
-        sourceAnnotationIds: r.SourceAnnotationIds ?? r.sourceAnnotationIds ?? [],
-        targetAnnotationIds: r.TargetAnnotationIds ?? r.targetAnnotationIds ?? [],
-        structural: r.Structural ?? r.structural,
-    });
-    return {
-        title: parsed.Title ?? parsed.title,
-        content: parsed.Content ?? parsed.content,
-        description: parsed.Description ?? parsed.description,
-        pageCount: parsed.PageCount ?? parsed.pageCount,
-        pawlsFileContent: (parsed.PawlsFileContent || parsed.pawlsFileContent || []).map(convertPawlsPage),
-        docLabels: parsed.DocLabels ?? parsed.docLabels ?? [],
-        labelledText: (parsed.LabelledText || parsed.labelledText || []).map(convertAnnotation),
-        relationships: (parsed.Relationships || parsed.relationships)?.map(convertRelationship),
-    };
-}
-/**
- * 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}`);
-    }
-    const parsed = JSON.parse(result);
-    // Convert from PascalCase to camelCase
-    return convertExternalAnnotationSet(parsed);
-}
-/**
- * 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}`);
-    }
-    const parsed = JSON.parse(result);
-    return {
-        isValid: parsed.IsValid ?? parsed.isValid,
-        hashMismatch: parsed.HashMismatch ?? parsed.hashMismatch,
-        issues: (parsed.Issues || parsed.issues || []).map((i) => ({
-            annotationId: i.AnnotationId ?? i.annotationId,
-            issueType: i.IssueType ?? i.issueType,
-            description: i.Description ?? i.description,
-            expectedText: i.ExpectedText ?? i.expectedText,
-            actualText: i.ActualText ?? i.actualText,
-        })),
-    };
-}
-/**
- * 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}`);
-    }
-    const parsed = JSON.parse(result);
-    return parsed.Html ?? parsed.html;
-}
-/**
- * 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
-function convertExternalAnnotationSet(parsed) {
-    const convertLabel = (l) => ({
-        id: l.Id ?? l.id,
-        color: l.Color ?? l.color,
-        description: l.Description ?? l.description ?? "",
-        icon: l.Icon ?? l.icon ?? "",
-        text: l.Text ?? l.text,
-        labelType: l.LabelType ?? l.labelType ?? "text",
-    });
-    const convertPawlsPage = (p) => ({
-        page: {
-            width: p.Page?.Width ?? p.page?.width,
-            height: p.Page?.Height ?? p.page?.height,
-            index: p.Page?.Index ?? p.page?.index,
-        },
-        tokens: (p.Tokens || p.tokens || []).map((t) => ({
-            x: t.X ?? t.x,
-            y: t.Y ?? t.y,
-            width: t.Width ?? t.width,
-            height: t.Height ?? t.height,
-            text: t.Text ?? t.text,
-        })),
-    });
-    const convertAnnotation = (a) => ({
-        id: a.Id ?? a.id,
-        annotationLabel: a.AnnotationLabel ?? a.annotationLabel,
-        rawText: a.RawText ?? a.rawText,
-        page: a.Page ?? a.page,
-        annotationJson: convertAnnotationJson(a.AnnotationJson ?? a.annotationJson),
-        parentId: a.ParentId ?? a.parentId,
-        annotationType: a.AnnotationType ?? a.annotationType,
-        structural: a.Structural ?? a.structural,
-    });
-    const convertAnnotationJson = (json) => {
-        if (!json)
-            return undefined;
-        // Check if it's a TextSpan
-        if (json.Start !== undefined || json.start !== undefined) {
-            return {
-                id: json.Id ?? json.id,
-                start: json.Start ?? json.start,
-                end: json.End ?? json.end,
-                text: json.Text ?? json.text,
-            };
-        }
-        // Otherwise it's a dictionary of single-page annotations
-        const result = {};
-        for (const [key, value] of Object.entries(json)) {
-            const v = value;
-            result[key] = {
-                bounds: {
-                    top: v.Bounds?.Top ?? v.bounds?.top,
-                    bottom: v.Bounds?.Bottom ?? v.bounds?.bottom,
-                    left: v.Bounds?.Left ?? v.bounds?.left,
-                    right: v.Bounds?.Right ?? v.bounds?.right,
-                },
-                tokensJsons: (v.TokensJsons || v.tokensJsons || []).map((t) => ({
-                    pageIndex: t.PageIndex ?? t.pageIndex,
-                    tokenIndex: t.TokenIndex ?? t.tokenIndex,
-                })),
-                rawText: v.RawText ?? v.rawText,
-            };
-        }
-        return result;
-    };
-    const convertRelationship = (r) => ({
-        id: r.Id ?? r.id,
-        relationshipLabel: r.RelationshipLabel ?? r.relationshipLabel,
-        sourceAnnotationIds: r.SourceAnnotationIds ?? r.sourceAnnotationIds ?? [],
-        targetAnnotationIds: r.TargetAnnotationIds ?? r.targetAnnotationIds ?? [],
-        structural: r.Structural ?? r.structural,
-    });
-    // Convert label dictionaries
-    const textLabels = {};
-    const rawTextLabels = parsed.TextLabels || parsed.textLabels || {};
-    for (const [key, value] of Object.entries(rawTextLabels)) {
-        textLabels[key] = convertLabel(value);
-    }
-    const docLabelDefinitions = {};
-    const rawDocLabelDefs = parsed.DocLabelDefinitions || parsed.docLabelDefinitions || {};
-    for (const [key, value] of Object.entries(rawDocLabelDefs)) {
-        docLabelDefinitions[key] = convertLabel(value);
-    }
-    return {
-        documentId: parsed.DocumentId ?? parsed.documentId,
-        documentHash: parsed.DocumentHash ?? parsed.documentHash,
-        createdAt: parsed.CreatedAt ?? parsed.createdAt,
-        updatedAt: parsed.UpdatedAt ?? parsed.updatedAt,
-        version: parsed.Version ?? parsed.version,
-        title: parsed.Title ?? parsed.title,
-        content: parsed.Content ?? parsed.content,
-        description: parsed.Description ?? parsed.description,
-        pageCount: parsed.PageCount ?? parsed.pageCount,
-        pawlsFileContent: (parsed.PawlsFileContent || parsed.pawlsFileContent || []).map(convertPawlsPage),
-        docLabels: parsed.DocLabels ?? parsed.docLabels ?? [],
-        labelledText: (parsed.LabelledText || parsed.labelledText || []).map(convertAnnotation),
-        relationships: (parsed.Relationships || parsed.relationships)?.map(convertRelationship),
-        textLabels,
-        docLabelDefinitions,
-    };
-}
-// ============================================================================
-// 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}`);
-    }
-    const parsed = JSON.parse(result);
-    return parsed.Html ?? parsed.html;
-}
-/**
- * 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}`);
-    }
-    const parsed = JSON.parse(result);
-    return parsed.Html ?? parsed.html;
-}
-/**
- * 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}`);
-    }
-    const parsed = JSON.parse(result);
-    return parsed.Html ?? parsed.html;
-}
-/**
- * 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=index.js.map