docxodus 10.0.0 → 11.0.0

package/dist/types.d.ts

@@ -149,7 +149,10 @@ export interface MarkdownProjection {
     anchorIndex: Record<string, MarkdownAnchorTarget>;
 }
 /**
- * Revision type enum matching the .NET WmlComparerRevisionType
+ * Revision type enum matching the .NET `DocxDiffRevisionType`, as returned by the `docxDiff*`
+ * comparison APIs. NOT the shape {@link getRevisions} returns — that reads a document's own markup
+ * and reports the markup-level kind on `RevisionListEntry.type` (`ins`/`del`/`moveFrom`), with the
+ * grouped classification on `family`.
  */
 export declare enum RevisionType {
     /** Text or content that was added/inserted */
@@ -161,24 +164,6 @@ export declare enum RevisionType {
     /** Text content unchanged but formatting (bold, italic, etc.) changed */
     FormatChanged = "FormatChanged"
 }
-/**
- * Which comparison engine {@link compareDocuments} / {@link compareDocumentsToHtml}
- * use to redline two documents.
- *
- * The numeric values are the contract shared with the .NET `ComparisonEngine` enum
- * and the WASM boundary (marshalled as an int); `0` remains
- * {@link ComparisonEngine.WmlComparer} for wire compatibility. Omitted selectors use
- * {@link ComparisonEngine.DocxDiff}.
- *
- * `DocxDiff` is the default comparison engine. `WmlComparer` remains available for
- * callers that explicitly require its historical behavior.
- */
-export declare enum ComparisonEngine {
-    /** The legacy WmlComparer engine (retained at wire value 0). */
-    WmlComparer = 0,
-    /** The default DocxDiff IR diff engine. */
-    DocxDiff = 1
-}
 /**
  * Comment render mode
  * Use -1 (Disabled) to not render comments, or a positive value to enable with that mode
@@ -306,8 +291,6 @@ export interface ConversionOptions {
 export interface CompareOptions {
     /** Author name for tracked changes (default: "Docxodus") */
     authorName?: string;
-    /** Detail threshold 0.0-1.0 (default: 0.15, lower = more detailed) */
-    detailThreshold?: number;
     /** Whether comparison is case-insensitive (default: false) */
     caseInsensitive?: boolean;
     /**
@@ -316,68 +299,6 @@ export interface CompareOptions {
      * If false: changes are accepted, output shows final "clean" document
      */
     renderTrackedChanges?: boolean;
-    /**
-     * Which comparison engine to use (default: {@link ComparisonEngine.DocxDiff}).
-     * Pass {@link ComparisonEngine.WmlComparer} only when its historical behavior is required.
-     */
-    engine?: ComparisonEngine;
-}
-/**
- * Information about a document revision extracted from a compared document.
- *
- * @example
- * ```typescript
- * const revisions = await getRevisions(comparedDoc);
- * for (const rev of revisions) {
- *   if (rev.revisionType === RevisionType.Inserted) {
- *     console.log(`${rev.author} added: "${rev.text}"`);
- *   } else if (rev.revisionType === RevisionType.Deleted) {
- *     console.log(`${rev.author} removed: "${rev.text}"`);
- *   }
- * }
- * ```
- */
-export interface Revision {
-    /**
-     * Author who made the revision.
-     * This comes from the Word document's tracked changes author attribute.
-     * May be empty string if the document doesn't specify an author.
-     */
-    author: string;
-    /**
-     * ISO 8601 date string when the revision was made.
-     * Format: "YYYY-MM-DDTHH:mm:ssZ" (e.g., "2024-01-15T10:30:00Z")
-     * May be empty string if the document doesn't specify a date.
-     */
-    date: string;
-    /**
-     * Type of revision - "Inserted", "Deleted", or "Moved".
-     * Use the RevisionType enum for type-safe comparisons.
-     */
-    revisionType: RevisionType | string;
-    /**
-     * Text content of the revision.
-     * For paragraph breaks, this will be a newline character.
-     * May be empty string for non-text elements (e.g., images, math equations).
-     */
-    text: string;
-    /**
-     * For Moved revisions, this ID links the source and destination.
-     * Both the "from" and "to" revisions share the same moveGroupId.
-     * Undefined for non-move revisions.
-     */
-    moveGroupId?: number;
-    /**
-     * For Moved revisions: true = source (content moved FROM here),
-     * false = destination (content moved TO here).
-     * Undefined for non-move revisions.
-     */
-    isMoveSource?: boolean;
-    /**
-     * For FormatChanged revisions: details about what formatting changed.
-     * Undefined for non-format-change revisions.
-     */
-    formatChange?: FormatChangeDetails;
 }
 /**
  * Which property container a FormatChanged revision describes.
@@ -417,7 +338,7 @@ export interface FormatChangeDetails {
 export declare enum DocxDiffRevisionGranularity {
     /** The engine's native one-revision-per-token-span grain (the default). */
     Fine = 0,
-    /** Coalesced to counts/texts comparable to the shipped WmlComparer's. */
+    /** Coalesced to the coarser contiguous-region grain the legacy comparer reported. */
     WmlComparerCompatible = 1
 }
 /**
@@ -549,6 +470,22 @@ export interface DocxDiffProducts {
     /** The stable semantic-change schema (what `docxDiffGetSemanticChanges` returns). */
     semanticChanges?: SemanticChangeSet;
 }
+/** One candidate of a {@link docxDiffCompareBatch} run: the products of comparing the shared
+ *  baseline against it, or the error that comparing it produced. */
+export interface DocxDiffBatchResult extends DocxDiffProducts {
+    /** The candidate's name, echoed from the request (its index when none was given). */
+    name: string;
+    /** Set when this candidate failed; its products are then absent. The rest of the batch is
+     *  unaffected — one malformed counterparty markup must not cost the other ninety-nine. */
+    error?: string;
+}
+/** A candidate document for {@link docxDiffCompareBatch}. */
+export interface DocxDiffBatchCandidate {
+    /** Echoed back on the matching result. Defaults to the candidate's index. */
+    name?: string;
+    /** The candidate document. */
+    document: File | Uint8Array;
+}
 /** Stable v1 operation names emitted by the semantic-change schema. */
 export type SemanticChangeOperation = "insert" | "delete" | "move" | "modify";
 /** Stable v1 semantic families. New schema versions may append families. */
@@ -675,7 +612,7 @@ export interface DocxDiffConsolidatedRevision extends DocxDiffRevision {
  * const insertions = revisions.filter(isInsertion);
  * ```
  */
-export declare function isInsertion(revision: Revision): boolean;
+export declare function isInsertion(revision: RevisionListEntry): boolean;
 /**
  * Type guard to check if a revision is a deletion.
  * @param revision - The revision to check
@@ -687,7 +624,7 @@ export declare function isInsertion(revision: Revision): boolean;
  * const deletions = revisions.filter(isDeletion);
  * ```
  */
-export declare function isDeletion(revision: Revision): boolean;
+export declare function isDeletion(revision: RevisionListEntry): boolean;
 /**
  * Type guard to check if a revision is a move operation.
  * @param revision - The revision to check
@@ -699,7 +636,7 @@ export declare function isDeletion(revision: Revision): boolean;
  * const moves = revisions.filter(isMove);
  * ```
  */
-export declare function isMove(revision: Revision): boolean;
+export declare function isMove(revision: RevisionListEntry): boolean;
 /**
  * Type guard to check if a revision is a format change.
  * @param revision - The revision to check
@@ -714,47 +651,7 @@ export declare function isMove(revision: Revision): boolean;
  * }
  * ```
  */
-export declare function isFormatChange(revision: Revision): boolean;
-/**
- * Type guard to check if a revision is a move source (content moved FROM here).
- * @param revision - The revision to check
- * @returns true if the revision is the source of a move
- *
- * @example
- * ```typescript
- * const revisions = await getRevisions(doc);
- * const moveSources = revisions.filter(isMoveSource);
- * ```
- */
-export declare function isMoveSource(revision: Revision): boolean;
-/**
- * Type guard to check if a revision is a move destination (content moved TO here).
- * @param revision - The revision to check
- * @returns true if the revision is the destination of a move
- *
- * @example
- * ```typescript
- * const revisions = await getRevisions(doc);
- * const moveDestinations = revisions.filter(isMoveDestination);
- * ```
- */
-export declare function isMoveDestination(revision: Revision): boolean;
-/**
- * Find the matching pair for a move revision.
- * @param revision - A move revision
- * @param allRevisions - All revisions from the document
- * @returns The matching move revision, or undefined if not found
- *
- * @example
- * ```typescript
- * const revisions = await getRevisions(doc);
- * for (const rev of revisions.filter(isMoveSource)) {
- *   const destination = findMovePair(rev, revisions);
- *   console.log(`"${rev.text}" moved to become "${destination?.text}"`);
- * }
- * ```
- */
-export declare function findMovePair(revision: Revision, allRevisions: Revision[]): Revision | undefined;
+export declare function isFormatChange(revision: RevisionListEntry): boolean;
 /**
  * Version information for the library
  */
@@ -778,7 +675,7 @@ export interface CompareResult {
     /** The redlined document as a Uint8Array */
     document: Uint8Array;
     /** List of revisions found */
-    revisions: Revision[];
+    revisions: RevisionListEntry[];
 }
 /** Algorithm-labelled digest in a verification artifact. */
 export interface VerificationDigest {
@@ -1195,15 +1092,12 @@ export interface DocxodusWasmExports {
          * Idempotent — assemblies load only once.
          */
         Warmup: () => string;
-        CompareDocuments: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, engine: number) => Uint8Array;
+        CompareDocuments: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string) => Uint8Array;
         CompareDocumentsToHtml: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string) => string;
-        CompareDocumentsToHtmlWithOptions: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, renderTrackedChanges: boolean, engine: number) => string;
-        CompareDocumentsToHtmlFull: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, detailThreshold: number, caseInsensitive: boolean, renderTrackedChanges: boolean, engine: number) => string;
-        CompareDocumentsWithOptions: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, detailThreshold: number, caseInsensitive: boolean, engine: number) => Uint8Array;
+        CompareDocumentsToHtmlWithOptions: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, renderTrackedChanges: boolean) => string;
+        CompareDocumentsToHtmlFull: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, caseInsensitive: boolean, renderTrackedChanges: boolean) => string;
+        CompareDocumentsWithOptions: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, caseInsensitive: boolean) => Uint8Array;
         GetRevisionsJson: (comparedDocBytes: Uint8Array) => string;
-        GetRevisionsJsonWithOptions: (comparedDocBytes: Uint8Array, detectMoves: boolean, moveSimilarityThreshold: number, moveMinimumWordCount: number, caseInsensitive: boolean) => string;
-        CompareDocumentsWithLog: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, detailThreshold: number, caseInsensitive: boolean) => string;
-        CompareDocumentsToHtmlWithLog: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, detailThreshold: number, caseInsensitive: boolean, renderTrackedChanges: boolean) => string;
     };
     DocxDiffBridge: {
         /** Redlined DOCX bytes (native markup), or empty array on error. */
@@ -1217,6 +1111,9 @@ export interface DocxodusWasmExports {
         /** One memoized pass, every requested product: `{"redlineB64":…, "revisions":[…],
          *  "editScript":…, "semanticChanges":…}` JSON (issue #594), or a JSON error object. */
         CompareProductsJson: (leftBytes: Uint8Array, rightBytes: Uint8Array, settingsJson: string, productsJson: string) => string;
+        /** One baseline read once, compared against many candidates:
+         *  `{"results":[{"name":…, …products…}]}` JSON (issue #617), or a JSON error object. */
+        CompareBatchJson: (baselineBytes: Uint8Array, candidatesJson: string, settingsJson: string, productsJson: string) => string;
         /** Accept all tracked revisions in a redlined DOCX → "right"-side bytes, or empty array on error. */
         AcceptRevisions: (bytes: Uint8Array) => Uint8Array;
         /** Reject all tracked revisions in a redlined DOCX → "left"-side bytes, or empty array on error. */
@@ -1307,6 +1204,9 @@ export interface DocxodusWasmExports {
         SetFooterText: (handle: number, anchor: string, kind: string, markdown: string) => string;
         InsertPageNumberField: (handle: number, anchor: string, field: string, format: string) => string;
         SetPageNumbering: (handle: number, anchor: string, opJson: string) => string;
+        InsertTableOfContents: (handle: number, anchor: string, pos: string, optionsJson: string) => string;
+        InsertTableOfFigures: (handle: number, anchor: string, pos: string, optionsJson: string) => string;
+        InsertTableOfAuthorities: (handle: number, anchor: string, pos: string, optionsJson: string) => string;
         ClearPageNumbering: (handle: number, anchor: string) => string;
         EnsureHeaderFooterVisible: (handle: number, anchor: string, kind: string) => string;
         InsertFootnote: (handle: number, anchor: string, characterOffset: number, markdown: string) => string;
@@ -1414,7 +1314,7 @@ export interface DocxodusWasmExports {
         SaveWithAnchorIds: (handle: number) => Uint8Array;
     };
 }
-export type EditErrorCode = "anchor_not_found" | "anchor_wrong_kind" | "anchors_not_adjacent" | "session_disposed" | "malformed_markdown" | "unsupported_markdown_syntax" | "table_insert_not_supported" | "footnote_ref_not_supported" | "comment_marker_not_supported" | "image_insert_not_supported" | "anchor_token_in_payload" | "offset_out_of_range" | "invalid_position" | "text_not_found" | "unknown_style" | "invalid_list_level" | "invalid_list_start_value" | "invalid_page_numbering" | "invalid_paragraph_format" | "invalid_table_styling" | "invalid_table_merge" | "table_anchor_migration_required" | "malformed_xml" | "disallowed_namespace" | "incompatible_element_type" | "validation_failed" | "nothing_to_undo" | "nothing_to_redo" | "duplicate_annotation_id" | "annotation_not_found" | "empty_annotation_span" | "empty_comment_span" | "revision_not_found" | "precondition_failed" | "invalid_batch_step" | "invalid_transaction" | "transaction_conflict" | "transaction_result_evicted" | "transaction_incomplete" | "hyperlink_not_found" | "bookmark_not_found" | "duplicate_bookmark_name" | "invalid_bookmark_name" | "invalid_hyperlink_target" | "missing_bookmark_target" | "bookmark_in_use" | "managed_bookmark" | "empty_hyperlink_span" | "unsupported_inline_boundary" | "revision_unsupported" | "revision_malformed" | "revision_ambiguous" | "tracked_operation_unsupported" | "unresolved_structural_revision" | "content_control_not_found" | "content_control_malformed" | "content_control_unsupported" | "content_control_locked" | "content_control_bound" | "content_control_wrong_type" | "invalid_content_control_value" | "content_control_placement_unsupported" | "content_control_nested_fill_unsupported" | "repeating_section_constraint" | "image_not_found" | "invalid_image_data" | "unsupported_image_format" | "image_too_large" | "invalid_image_dimensions" | "unsupported_image_markup" | "linked_image_read_only" | "invalid_image_layout" | "internal_error";
+export type EditErrorCode = "anchor_not_found" | "anchor_wrong_kind" | "anchors_not_adjacent" | "session_disposed" | "malformed_markdown" | "unsupported_markdown_syntax" | "table_insert_not_supported" | "footnote_ref_not_supported" | "comment_marker_not_supported" | "image_insert_not_supported" | "anchor_token_in_payload" | "offset_out_of_range" | "invalid_position" | "text_not_found" | "unknown_style" | "invalid_list_level" | "invalid_list_start_value" | "invalid_page_numbering" | "invalid_reference_field" | "invalid_paragraph_format" | "invalid_table_styling" | "invalid_table_merge" | "table_anchor_migration_required" | "malformed_xml" | "disallowed_namespace" | "incompatible_element_type" | "validation_failed" | "nothing_to_undo" | "nothing_to_redo" | "duplicate_annotation_id" | "annotation_not_found" | "empty_annotation_span" | "empty_comment_span" | "revision_not_found" | "precondition_failed" | "invalid_batch_step" | "invalid_transaction" | "transaction_conflict" | "transaction_result_evicted" | "transaction_incomplete" | "hyperlink_not_found" | "bookmark_not_found" | "duplicate_bookmark_name" | "invalid_bookmark_name" | "invalid_hyperlink_target" | "missing_bookmark_target" | "bookmark_in_use" | "managed_bookmark" | "empty_hyperlink_span" | "unsupported_inline_boundary" | "revision_unsupported" | "revision_malformed" | "revision_ambiguous" | "tracked_operation_unsupported" | "unresolved_structural_revision" | "content_control_not_found" | "content_control_malformed" | "content_control_unsupported" | "content_control_locked" | "content_control_bound" | "content_control_wrong_type" | "invalid_content_control_value" | "content_control_placement_unsupported" | "content_control_nested_fill_unsupported" | "repeating_section_constraint" | "image_not_found" | "invalid_image_data" | "unsupported_image_format" | "image_too_large" | "invalid_image_dimensions" | "unsupported_image_markup" | "linked_image_read_only" | "invalid_image_layout" | "internal_error";
 export interface AnchorRef {
     id: string;
     kind: string;
@@ -1868,6 +1768,49 @@ export interface ParagraphFormatOp {
  * `"even"` (even pages; sets `w:evenAndOddHeaders`).
  */
 export type HeaderFooterKind = "default" | "first" | "even";
+/**
+ * Options for {@link DocxSession.insertTableOfContents} (issue #607). Every field is a typed switch
+ * on the underlying `TOC` field, so a caller never writes `\o "1-3"` by hand — a malformed switch
+ * string renders as nothing in Word, silently, which is the failure these exist to prevent.
+ */
+export interface TableOfContentsOptions {
+    /** Heading levels to list (`\o`): a level or a range within 1-9, e.g. `"1-3"`. Default `"1-3"`. */
+    levels?: string;
+    /** Make each entry a hyperlink to its heading (`\h`). Default true. */
+    hyperlinks?: boolean;
+    /** Hide the leader tab and page numbers in Word's web view (`\z`). Default true. */
+    hideTabAndPageNumbersInWeb?: boolean;
+    /** Include paragraphs with an outline level but no heading style (`\u`). Default true. */
+    useOutlineLevels?: boolean;
+    /** Heading above the table, in Word's `TOCHeading` style. `null` or `""` inserts no heading.
+     *  Default `"Contents"`. */
+    title?: string | null;
+    /** Right-aligned dot-leader tab stop in twips. Default 9350 (US Letter, one-inch margins). */
+    rightTabPos?: number;
+}
+/** Options for {@link DocxSession.insertTableOfFigures}. A table of figures is a `TOC` field
+ *  selecting by caption label rather than outline level — Word's own encoding. */
+export interface TableOfFiguresOptions {
+    /** The caption label whose captions to list (`\c`) — `"Figure"`, `"Table"`, `"Exhibit"`. */
+    captionLabel?: string;
+    /** Make each entry a hyperlink to its caption (`\h`). Default true. */
+    hyperlinks?: boolean;
+    /** Right-aligned dot-leader tab stop in twips. Default 9350. */
+    rightTabPos?: number;
+}
+/** Word's fixed table-of-authorities categories. */
+export type AuthorityCategory = "cases" | "statutes" | "other_authorities" | "rules" | "treatises" | "regulations" | "constitutional_provisions";
+/** Options for {@link DocxSession.insertTableOfAuthorities}. */
+export interface TableOfAuthoritiesOptions {
+    /** Which category of authority to list (`\c`). Default `"cases"`. */
+    category?: AuthorityCategory;
+    /** Make each entry a hyperlink to its citation (`\h`). Default true. */
+    hyperlinks?: boolean;
+    /** Separator between an entry and its page numbers (`\e`), e.g. a tab. Default: Word's own. */
+    entryPageSeparator?: string;
+    /** Right-aligned dot-leader tab stop in twips. Default 9350. */
+    rightTabPos?: number;
+}
 /** Which page-number field `DocxSession.insertPageNumberField` emits: `"currentPage"` → PAGE,
  * `"totalPages"` → NUMPAGES. */
 export type PageNumberField = "currentPage" | "totalPages";
@@ -2691,61 +2634,6 @@ export declare enum ComparisonLogLevel {
     /** Error that may affect comparison results but didn't stop processing */
     Error = "Error"
 }
-/**
- * A single log entry from the comparison process.
- */
-export interface ComparisonLogEntry {
-    /** Severity level: "Info", "Warning", or "Error" */
-    level: ComparisonLogLevel | string;
-    /**
-     * Machine-readable code identifying the type of issue.
-     * Examples: "ORPHANED_FOOTNOTE_REFERENCE", "MISSING_STYLE"
-     */
-    code: string;
-    /** Human-readable description of the issue */
-    message: string;
-    /** Additional context or technical details (optional) */
-    details?: string;
-    /**
-     * Location in the document where the issue occurred (optional).
-     * Format: "part/xpath" e.g., "document.xml/w:footnoteReference[@w:id='3']"
-     */
-    location?: string;
-}
-/**
- * Result from comparison operations that includes a log of warnings/errors.
- */
-export interface CompareResultWithLog {
-    /** Whether the comparison succeeded */
-    success: boolean;
-    /** The redlined document as a Uint8Array (only if success is true) */
-    document?: Uint8Array;
-    /** Error message if success is false */
-    error?: string;
-    /** Log entries from the comparison process */
-    log: ComparisonLogEntry[];
-    /** Whether the log contains any warnings */
-    hasWarnings: boolean;
-    /** Whether the log contains any errors */
-    hasErrors: boolean;
-}
-/**
- * Result from HTML comparison operations that includes a log of warnings/errors.
- */
-export interface CompareToHtmlResultWithLog {
-    /** Whether the comparison succeeded */
-    success: boolean;
-    /** The HTML output (only if success is true) */
-    html?: string;
-    /** Error message if success is false */
-    error?: string;
-    /** Log entries from the comparison process */
-    log: ComparisonLogEntry[];
-    /** Whether the log contains any warnings */
-    hasWarnings: boolean;
-    /** Whether the log contains any errors */
-    hasErrors: boolean;
-}
 /**
  * Well-known log entry codes used by the comparison engine.
  */
@@ -2767,34 +2655,6 @@ export declare const ComparisonLogCodes: {
     /** A bookmark reference has no corresponding bookmark start/end */
     readonly OrphanedBookmark: "ORPHANED_BOOKMARK";
 };
-/**
- * Options for revision extraction with move detection configuration.
- */
-export interface GetRevisionsOptions {
-    /**
-     * Whether to detect and mark moved content.
-     * When enabled, deletions and insertions with similar text are linked as move pairs.
-     * @default true
-     */
-    detectMoves?: boolean;
-    /**
-     * Jaccard similarity threshold for move detection (0.0 to 1.0).
-     * Higher values require more exact word overlap between deletion and insertion.
-     * @default 0.8
-     */
-    moveSimilarityThreshold?: number;
-    /**
-     * Minimum word count for content to be considered for move detection.
-     * Short phrases below this threshold are excluded to avoid false positives.
-     * @default 3
-     */
-    moveMinimumWordCount?: number;
-    /**
-     * Whether similarity matching ignores case differences.
-     * @default false
-     */
-    caseInsensitive?: boolean;
-}
 /**
  * A custom annotation on a document range.
  */
@@ -3341,8 +3201,6 @@ export interface WorkerGetRevisionsRequest extends WorkerRequestBase {
     type: "getRevisions";
     /** Document bytes */
     documentBytes: Uint8Array;
-    /** Revision extraction options */
-    options?: GetRevisionsOptions;
 }
 /**
  * Get document metadata for lazy loading request.
@@ -3518,7 +3376,7 @@ export interface WorkerGetSemanticChangesResponse extends WorkerResponseBase {
 export interface WorkerGetRevisionsResponse extends WorkerResponseBase {
     type: "getRevisions";
     /** Array of revisions */
-    revisions?: Revision[];
+    revisions?: RevisionListEntry[];
 }
 /**
  * Response from getDocumentMetadata request.