docxodus 12.3.0 → 12.4.1

package/dist/core.d.ts

@@ -0,0 +1,924 @@
+/** Engine API: safe to import in plain Node ESM without loading the browser editor. */
+import type { ConversionOptions, CompareOptions, RevisionListEntry, VersionInfo, ErrorResponse, CompareResult, PackageManifest, DeliverableVerificationResult, DeliveryReceiptVerificationResult, RedlineReversibilityProof, DocxodusWasmExports, FormatChangeDetails, DocxDiffSettings, DocxDiffRevision, DocxDiffBatchCandidate, DocxDiffBatchResult, DocxDiffProduct, DocxDiffProducts, SemanticChange, SemanticChangeFamily, SemanticChangeOperation, SemanticChangeSet, SemanticValue, DocxDiffReviewer, DocxDiffConsolidateSettings, DocxDiffConflict, DocxDiffConflictCompetitor, DocxDiffConsolidatedRevision, Annotation, AddAnnotationRequest, AddAnnotationResponse, RemoveAnnotationResponse, AnnotationOptions, DocumentStructure, DocumentElement, TableColumnInfo, AnnotationTarget, AddAnnotationWithTargetRequest, DocumentMetadata, SectionMetadata, OpenContractDocExport, PawlsPage, PawlsPageBoundary, PawlsToken, OpenContractsAnnotation, OpenContractsSinglePageAnnotation, BoundingBox, TokenId, TextSpan, OpenContractsRelationship, AnnotationLabel, ExternalAnnotationSet, ExternalAnnotationValidationResult, ExternalAnnotationValidationIssue, ExternalAnnotationProjectionSettings, MarkdownProjectionSettings, MarkdownAnchorTarget, MarkdownProjection, DocxSessionSettings } from "./types.js";
+import { DocxSession } from "./session.js";
+import { DocxHistoryArchive, DocxHistoryClient } from './history.js';
+import type { HistoryStorage } 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 declare function openDocxHistory(storage: HistoryStorage): DocxHistoryClient;
+/** Open a self-contained readonly .docxhistory file after initialize(); no storage adapter needed. */
+export declare function openDocxHistoryArchive(bytes: Uint8Array): Promise<DocxHistoryArchive>;
+export { DocxSession } from "./session.js";
+export type { AnchorInfo, AnchorRef, AnchorTargetRef, BlockMetadata, BookmarkInfo, BookmarkRangeSegment, CharSpan, CommentListEntry, ContentControlBindingInfo, ContentControlBindingPolicy, ContentControlFillOptions, ContentControlInfo, ContentControlPlacement, ContentControlType, DocumentAnnotation, DocumentRange, DocxSessionProjection, DocxSessionSettings, EditError, EditErrorCode, EditResult, FindOptions, EditorRenderOptions, FormatOp, HyperlinkInfo, HyperlinkKind, ImageBinaryFormat, ImageCapabilities, ImageDimensions, ImageFormatCapability, ImageHorizontalAlignment, ImageHorizontalReference, ImageInsertOptions, ImageMarkupKind, ImageOccurrence, ImagePlacement, ImageVerticalAlignment, ImageVerticalReference, ImageWrapMode, ImageWrapSide, FloatingImageLayout, LineSpacingRule, ListMembership, FormattingInspection, InlineSpan, ParagraphFormatting, RunFormattingInfo, StyleInfo, TableStyleFormatting, MarkdownPatch, NumberFormat, PageCitation, PageCitationFragment, PageCitationPage, PageCitationRequest, PageCitationUnavailableReason, PageMapRegistrationResult, PageMapStatus, PageNumberField, PageNumberingOp, PageSetupOp, ParagraphBorderEdge, ParagraphFormatOp, RevisionDiagnostic, RevisionFamily, RevisionResolutionStatus, SectionInfo, SessionRevisionType, TableOfAuthoritiesOptions, TableOfContentsOptions, TableOfFiguresOptions, TableBorderScope, TableBorderSpec, TableInsertOptions, TableMergeContent, TableShadingScope, PackageManifest, PackageManifestInspectionLimits, PackageManifestEntry, PackageManifestFacts, PackageRelationship, PackageContentTypeDeclaration, PackageRevisionCounts, PackageAnnotationCounts, DeliverableVerificationResult, DeliveryArtifactVerification, DeliveryArtifactVerificationStatus, DeliveryReceiptVerificationResult, DeliverableVerificationMode, DeliverableVerificationDecision, DeliverableFindingDisposition, DeliverableFindingCategory, DeliverableCheckStatus, DeliverablePackageChangeKind, DeliverableArtifactRole, DeliverableArtifactAvailability, DeliverableSemanticChangeFamily, DeliverablePackageIdentity, DeliverableCheckResult, DeliverableFinding, DeliverablePackageChange, DeliverableSemanticChange, DeliverableSemanticDelta, DeliverableArtifactMetadata, VerificationDigest, VerificationFinding, VerificationFindingSeverity, ChangeLocation, RedlineReversibilityProof, RedlineProofPathResult, RedlineProofPackageIdentity, RedlineProofFinding, RedlineProofDirection, RedlineRevisionClassification, RedlineRevisionDisposition, RedlineRevisionIdentity, RedlineRevisionFamily, RedlineRevisionResolutionStatus, RedlineRevisionDiagnostic, RedlineModeledSemanticComparison, RedlinePackageDivergence, RedlinePackageDivergenceKind, } from "./types.js";
+export type { FillOptions, BulkEditResult } from "./types.js";
+export { PlaceholderKinds, ContextBoundary } from "./types.js";
+export { DiffFormat } from "./types.js";
+export type { EditSummary, DiffEntry } 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 declare function openDocxSession(bytes: Uint8Array, settings?: DocxSessionSettings): DocxSession;
+/**
+ * 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 declare function createBlankDocx(): Uint8Array;
+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 type { PageDimensions, MeasuredBlock, PageInfo, PaginationResult, PaginationOptions, PageMap, PageMapPage, PageMapFragment, PageMapRect, PageMapMode, PageMapAvailability, PageMapStory, PageCitationNavigation, } from "./pagination.js";
+export { PaginationEngine, clearPageCitationHighlight, createUnavailablePageMap, navigateToPageCitation, paginateHtml, } from "./pagination.js";
+export type { CommentProfile, CompleteRenderReport, DocxodusExportErrorCode, ExportPhase, ExportResourceLimits, FailedRenderReport, FontConfigurationIdentity, FontResolution, FontResolver, PaginatedHtmlOptions, PaginatedHtmlResult, PaginatedRenderMetadata, ReadinessOutcome, RenderReport, RenderReportBase, RenderWarning, ResourceOutcome, ReviewProfile, UnsupportedContentOutcome, UnsupportedContentPolicy, } from "./export-browser.js";
+export { DEFAULT_MARGIN, DEFAULT_PAGE_HEIGHT, DEFAULT_PAGE_WIDTH, fitScale, parseSectionDimensions, ptToPx, pxToPt, } from "./page-geometry.js";
+export { DocumentViewport } from "./viewport.js";
+export type { ColumnWidth, DocumentViewportOptions } from "./viewport.js";
+export type { ConversionOptions, CompareOptions, RevisionListEntry, VersionInfo, ErrorResponse, CompareResult, FormatChangeDetails, Annotation, AddAnnotationRequest, AddAnnotationResponse, RemoveAnnotationResponse, AnnotationOptions, DocumentStructure, DocumentElement, TableColumnInfo, AnnotationTarget, AddAnnotationWithTargetRequest, DocumentMetadata, SectionMetadata, OpenContractDocExport, PawlsPage, PawlsPageBoundary, PawlsToken, OpenContractsAnnotation, OpenContractsSinglePageAnnotation, BoundingBox, TokenId, TextSpan, OpenContractsRelationship, AnnotationLabel, ExternalAnnotationSet, ExternalAnnotationValidationResult, ExternalAnnotationValidationIssue, ExternalAnnotationProjectionSettings, MarkdownProjectionSettings, MarkdownAnchorTarget, MarkdownProjection, DocxDiffSettings, DocxDiffRevision, DocxDiffBatchCandidate, DocxDiffBatchResult, DocxDiffProduct, DocxDiffProducts, SemanticChange, SemanticChangeFamily, SemanticChangeOperation, SemanticChangeSet, SemanticValue, DocxDiffReviewer, DocxDiffConsolidateSettings, DocxDiffConflict, DocxDiffConflictCompetitor, DocxDiffConsolidatedRevision, };
+export { 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, };
+/**
+ * Current base path for WASM files.
+ * Empty string means auto-detect from module URL.
+ */
+export declare let wasmBasePath: string;
+/**
+ * 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 declare function setWasmBasePath(path: string): void;
+/**
+ * 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 declare function initialize(basePath?: string): Promise<void>;
+/**
+ * Generate a deterministic, non-mutating verification manifest from DOCX bytes.
+ * Invalid, malformed, and encrypted packages are represented by structured findings.
+ */
+export declare function generatePackageManifest(document: File | Uint8Array): Promise<PackageManifest>;
+/**
+ * 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 declare function verifyDeliverable(document: File | Uint8Array, baseline?: File | Uint8Array): Promise<DeliverableVerificationResult>;
+/**
+ * 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 declare function verifyDeliveryReceipt(receiptJson: string, artifacts?: Record<string, Uint8Array>): Promise<DeliveryReceiptVerificationResult>;
+/**
+ * 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 declare function proveRedlineReversibility(baseline: File | Uint8Array, intendedFinal: File | Uint8Array, redline: File | Uint8Array): Promise<RedlineReversibilityProof>;
+/**
+ * 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 declare function renderBlockHtml(document: File | Uint8Array, anchorId: string, options?: {
+    cssPrefix?: string;
+    fabricateClasses?: boolean;
+}): Promise<string>;
+export declare function convertDocxToHtml(document: File | Uint8Array, options?: ConversionOptions): Promise<string>;
+/**
+ * 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 declare function compareDocuments(original: File | Uint8Array, modified: File | Uint8Array, options?: CompareOptions): Promise<Uint8Array>;
+/**
+ * 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 declare function compareDocumentsToHtml(original: File | Uint8Array, modified: File | Uint8Array, options?: CompareOptions): Promise<string>;
+/**
+ * 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 declare function getRevisions(document: File | Uint8Array): Promise<RevisionListEntry[]>;
+/**
+ * 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 declare function docxDiffCompare(left: File | Uint8Array, right: File | Uint8Array, settings?: DocxDiffSettings): Promise<Uint8Array>;
+/**
+ * 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 declare function docxDiffGetRevisions(left: File | Uint8Array, right: File | Uint8Array, settings?: DocxDiffSettings): Promise<DocxDiffRevision[]>;
+/**
+ * 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 declare function docxDiffCompareProducts(left: File | Uint8Array, right: File | Uint8Array, settings?: DocxDiffSettings, products?: DocxDiffProduct[]): Promise<DocxDiffProducts>;
+/**
+ * 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 declare function docxDiffCompareBatch(baseline: File | Uint8Array, candidates: readonly DocxDiffBatchCandidate[], settings?: DocxDiffSettings, products?: DocxDiffProduct[]): Promise<DocxDiffBatchResult[]>;
+/**
+ * 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 declare function docxDiffGetEditScript(left: File | Uint8Array, right: File | Uint8Array, settings?: DocxDiffSettings): Promise<string>;
+/**
+ * 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 declare function docxDiffGetSemanticChanges(left: File | Uint8Array, right: File | Uint8Array, settings?: DocxDiffSettings): Promise<SemanticChangeSet>;
+/**
+ * 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 declare function docxDiffAcceptRevisions(redline: File | Uint8Array): Promise<Uint8Array>;
+/**
+ * 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 declare function docxDiffRejectRevisions(redline: File | Uint8Array): Promise<Uint8Array>;
+/**
+ * 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 declare function docxDiffConsolidate(base: File | Uint8Array, reviewers: DocxDiffReviewer[], settings?: DocxDiffConsolidateSettings): Promise<Uint8Array>;
+/**
+ * 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 declare function docxDiffGetConflicts(base: File | Uint8Array, reviewers: DocxDiffReviewer[], settings?: DocxDiffConsolidateSettings): Promise<DocxDiffConflict[]>;
+/**
+ * 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 declare function docxDiffGetConsolidatedRevisions(base: File | Uint8Array, reviewers: DocxDiffReviewer[], settings?: DocxDiffConsolidateSettings): Promise<DocxDiffConsolidatedRevision[]>;
+/**
+ * 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 declare function docxDiffGetConsolidatedEditScript(base: File | Uint8Array, reviewers: DocxDiffReviewer[], settings?: DocxDiffConsolidateSettings): Promise<string>;
+/**
+ * Get version information about the library.
+ */
+export declare function getVersion(): VersionInfo;
+/**
+ * Check if the WASM runtime is initialized.
+ */
+export declare function isInitialized(): boolean;
+/**
+ * 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 declare function getWasmExports(): DocxodusWasmExports;
+/**
+ * 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 declare function getAnnotations(document: File | Uint8Array): Promise<Annotation[]>;
+/**
+ * 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 declare function addAnnotation(document: File | Uint8Array, request: AddAnnotationRequest): Promise<AddAnnotationResponse>;
+/**
+ * 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 declare function removeAnnotation(document: File | Uint8Array, annotationId: string): Promise<RemoveAnnotationResponse>;
+/**
+ * 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 declare function hasAnnotations(document: File | Uint8Array): Promise<boolean>;
+/**
+ * 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 declare function getDocumentStructure(document: File | Uint8Array): Promise<DocumentStructure>;
+/**
+ * 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 declare function getDocumentMetadata(document: File | Uint8Array): Promise<DocumentMetadata>;
+/**
+ * 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 declare function exportToOpenContract(document: File | Uint8Array): Promise<OpenContractDocExport>;
+/**
+ * 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 declare function convertWmlToMarkdown(document: File | Uint8Array, settings?: MarkdownProjectionSettings): Promise<MarkdownProjection>;
+/**
+ * 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 declare function addAnnotationWithTarget(document: File | Uint8Array, request: AddAnnotationWithTargetRequest): Promise<AddAnnotationResponse>;
+/**
+ * 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 declare function computeDocumentHash(document: File | Uint8Array): Promise<string>;
+/**
+ * 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 declare function createExternalAnnotationSet(document: File | Uint8Array, documentId: string): Promise<ExternalAnnotationSet>;
+/**
+ * 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 declare function validateExternalAnnotations(document: File | Uint8Array, annotationSet: ExternalAnnotationSet): Promise<ExternalAnnotationValidationResult>;
+/**
+ * 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 declare function convertDocxToHtmlWithExternalAnnotations(document: File | Uint8Array, annotationSet: ExternalAnnotationSet, conversionOptions?: ConversionOptions, projectionOptions?: ExternalAnnotationProjectionSettings): Promise<string>;
+/**
+ * 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 declare function searchTextOffsets(document: File | Uint8Array, searchText: string, maxResults?: number): Promise<TextSpan[]>;
+/**
+ * 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 declare function createAnnotation(id: string, labelId: string, documentText: string, startOffset: number, endOffset: number): OpenContractsAnnotation;
+/**
+ * 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 declare function createAnnotationFromSearch(id: string, labelId: string, documentText: string, searchText: string, occurrence?: number): OpenContractsAnnotation | null;
+/**
+ * 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 declare function findTextOccurrences(documentText: string, searchText: string, maxResults?: number): Array<{
+    start: number;
+    end: number;
+}>;
+/**
+ * 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 declare function projectAnnotationsOntoHtml(html: string, annotationSet: ExternalAnnotationSet, projectionOptions?: ExternalAnnotationProjectionSettings): Promise<string>;
+/**
+ * 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 declare function addAnnotationToHtml(html: string, annotation: OpenContractsAnnotation, label?: AnnotationLabel, projectionOptions?: ExternalAnnotationProjectionSettings): Promise<string>;
+/**
+ * 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 declare function removeAnnotationFromHtml(html: string, annotationId: string, cssClassPrefix?: string): Promise<string>;
+/**
+ * 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 declare function generateAnnotationVisibilityCss(hiddenLabelIds: string[], cssClassPrefix?: string): Promise<string>;
+/**
+ * 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 declare function generateAnnotationCss(labels: Record<string, AnnotationLabel>, projectionOptions?: ExternalAnnotationProjectionSettings): Promise<string>;
+//# sourceMappingURL=core.d.ts.map