docxodus 12.6.4 → 13.0.0

package/dist/types.d.ts

@@ -191,6 +191,19 @@ export declare enum PaginationMode {
      */
     Paginated = 1
 }
+/**
+ * How rendered tracked changes look (issue #851). Only used when `renderTrackedChanges` is on.
+ */
+export declare enum RevisionPresentation {
+    /** Docxodus's own review style (default): green/red text with light fills, purple moves, pilcrows. */
+    Docxodus = 0,
+    /**
+     * Close to Word's All Markup print: one colour per author for both insertions (underlined) and
+     * deletions (struck through), no fills or pilcrows, green double-lined moves, Word's default cell
+     * shading, and one left-margin change bar per changed paragraph. Full renders only.
+     */
+    Word = 1
+}
 /**
  * Annotation label display mode
  */
@@ -264,6 +277,8 @@ export interface ConversionOptions {
     showDeletedContent?: boolean;
     /** Whether to distinguish move operations from regular insert/delete (only when renderTrackedChanges=true, default: true) */
     renderMoveOperations?: boolean;
+    /** How tracked changes look (only when renderTrackedChanges=true, default: RevisionPresentation.Docxodus) */
+    revisionPresentation?: RevisionPresentation;
     /**
      * Whether to render placeholders for unsupported content (default: false)
      * When enabled, unsupported content (WMF/EMF images, math equations, form fields, etc.)
@@ -284,12 +299,20 @@ export interface ConversionOptions {
      * `renderBlockHtml`. Default: false.
      */
     stampAnchors?: boolean;
+    /**
+     * Emit Word lists as `<ol>`/`<ul>`/`<li>` instead of paragraphs (issue #895). Adjacent list
+     * paragraphs of one list share a list, and a deeper level nests inside the preceding item. CSS
+     * draws the marker (`list-style-type`, with `start`/`value` for restarts) only where it
+     * reproduces Word's marker exactly; other lists keep the generated marker spans under
+     * `list-style-type: none`. Ignored by paginated output. Default: false.
+     */
+    semanticLists?: boolean;
 }
 /**
  * Options for document comparison
  */
 export interface CompareOptions {
-    /** Author name for tracked changes (default: "Docxodus") */
+    /** Author name for tracked changes (default: the engine's, "Docxodus") */
     authorName?: string;
     /** Whether comparison is case-insensitive (default: false) */
     caseInsensitive?: boolean;
@@ -356,7 +379,7 @@ export declare enum DocxDiffFormatComparison {
  * every field is optional and an omitted field uses the engine default.
  */
 export interface DocxDiffSettings {
-    /** Author stamped on revisions and markup (default "Open-Xml-PowerTools"). */
+    /** Author stamped on revisions and markup (default "Docxodus"). */
     authorForRevisions?: string;
     /** Pin revision dates to a fixed epoch for byte-identical output (default true). */
     deterministic?: boolean;
@@ -365,10 +388,13 @@ export interface DocxDiffSettings {
     /**
      * Accept every pre-existing revision on both inputs before comparing (default false).
      * This flattens prior authorship; `preserveInputRevisions` takes precedence when both are set.
+     * The consolidate functions (`docxDiffConsolidate` and its siblings) always pre-accept the base
+     * and every reviewer, whatever this says: they compare the accepted view, as Word's Compare does.
      */
     preAcceptInputRevisions?: boolean;
     /**
-     * Preserve the inputs' existing tracked revisions Word-style (default false).
+     * Preserve the inputs' existing tracked revisions, as Word's Combine does (default false).
+     * Word's Compare pre-accepts them instead (see `preAcceptInputRevisions`).
      * This takes precedence over `preAcceptInputRevisions` when both are set.
      */
     preserveInputRevisions?: boolean;
@@ -412,6 +438,19 @@ export interface DocxDiffSettings {
      * the revision list and edit-script JSON are unaffected. Default false.
      */
     crossParagraphTokenDiff?: boolean;
+    /**
+     * Record a list item's previous label in `w:numberingChange` when an insertion, deletion or move
+     * elsewhere in its list renumbered it. Word's own compare never writes this; set false for output
+     * limited to the constructs Word writes. Default true. Consolidate honors it too.
+     */
+    trackNumberingChanges?: boolean;
+    /**
+     * Track a cell added to or removed from a paired table row with `w:cellIns`/`w:cellDel`. Word's own
+     * compare never writes cell-level revisions; set false and such a table is tracked as a whole (the
+     * original deleted, the revised inserted), in the markup and the revision list alike. Default true.
+     * Consolidate keeps cell-level revisions regardless.
+     */
+    trackCellInsertionsAndDeletions?: boolean;
 }
 /**
  * One revision from `docxDiffGetRevisions`. Mirrors the consumer shape of
@@ -666,6 +705,9 @@ export interface VersionInfo {
 export interface ErrorResponse {
     error: string;
     type?: string;
+    /**
+     * @deprecated Never populated: the engine stopped putting stack traces on the wire (issue #961).
+     */
     stackTrace?: string;
 }
 /**
@@ -1188,7 +1230,7 @@ export interface DocxodusWasmExports {
         ConvertDocxToHtmlWithOptions: (bytes: Uint8Array, pageTitle: string, cssPrefix: string, fabricateClasses: boolean, additionalCss: string, commentRenderMode: number, commentCssClassPrefix: string) => string;
         ConvertDocxToHtmlWithPagination: (bytes: Uint8Array, pageTitle: string, cssPrefix: string, fabricateClasses: boolean, additionalCss: string, commentRenderMode: number, commentCssClassPrefix: string, paginationMode: number, paginationScale: number, paginationCssClassPrefix: string) => string;
         ConvertDocxToHtmlFull: (bytes: Uint8Array, pageTitle: string, cssPrefix: string, fabricateClasses: boolean, additionalCss: string, commentRenderMode: number, commentCssClassPrefix: string, paginationMode: number, paginationScale: number, paginationCssClassPrefix: string, renderAnnotations: boolean, annotationLabelMode: number, annotationCssClassPrefix: string) => string;
-        ConvertDocxToHtmlComplete: (bytes: Uint8Array, pageTitle: string, cssPrefix: string, fabricateClasses: boolean, additionalCss: string, commentRenderMode: number, commentCssClassPrefix: string, paginationMode: number, paginationScale: number, paginationCssClassPrefix: string, renderAnnotations: boolean, annotationLabelMode: number, annotationCssClassPrefix: string, renderFootnotesAndEndnotes: boolean, renderHeadersAndFooters: boolean, renderTrackedChanges: boolean, showDeletedContent: boolean, renderMoveOperations: boolean, renderUnsupportedContentPlaceholders: boolean, documentLanguage: string | null, stampAnchors: boolean) => string;
+        ConvertDocxToHtmlComplete: (bytes: Uint8Array, pageTitle: string, cssPrefix: string, fabricateClasses: boolean, additionalCss: string, commentRenderMode: number, commentCssClassPrefix: string, paginationMode: number, paginationScale: number, paginationCssClassPrefix: string, renderAnnotations: boolean, annotationLabelMode: number, annotationCssClassPrefix: string, renderFootnotesAndEndnotes: boolean, renderHeadersAndFooters: boolean, renderTrackedChanges: boolean, showDeletedContent: boolean, renderMoveOperations: boolean, renderUnsupportedContentPlaceholders: boolean, documentLanguage: string | null, stampAnchors: boolean, revisionPresentation: number, semanticLists?: boolean) => string;
         GetAnnotations: (bytes: Uint8Array) => string;
         AddAnnotation: (bytes: Uint8Array, requestJson: string) => string;
         AddAnnotationWithTarget: (bytes: Uint8Array, requestJson: string) => string;
@@ -1219,11 +1261,11 @@ export interface DocxodusWasmExports {
          * Idempotent — assemblies load only once.
          */
         Warmup: () => string;
-        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) => string;
-        CompareDocumentsToHtmlFull: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, caseInsensitive: boolean, renderTrackedChanges: boolean) => string;
-        CompareDocumentsWithOptions: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, caseInsensitive: boolean) => Uint8Array;
+        CompareDocuments: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string | null) => Uint8Array;
+        CompareDocumentsToHtml: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string | null) => string;
+        CompareDocumentsToHtmlWithOptions: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string | null, renderTrackedChanges: boolean) => string;
+        CompareDocumentsToHtmlFull: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string | null, caseInsensitive: boolean, renderTrackedChanges: boolean) => string;
+        CompareDocumentsWithOptions: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string | null, caseInsensitive: boolean) => Uint8Array;
         GetRevisionsJson: (comparedDocBytes: Uint8Array) => string;
         GetCommentsJson: (docBytes: Uint8Array) => string;
     };
@@ -1283,8 +1325,8 @@ export interface DocxodusWasmExports {
         BeginTransaction: (handle: number) => number;
         CommitTransaction: (transactionHandle: number) => void;
         RollbackTransaction: (transactionHandle: number) => void;
-        ProjectAnchor: (handle: number, anchorId: string, depth: number) => string;
-        ProjectAnchorWithCitations: (handle: number, anchorId: string, depth: number, requestJson: string) => string;
+        ProjectAnchor: (handle: number, anchorId: string, depth: number | null) => string;
+        ProjectAnchorWithCitations: (handle: number, anchorId: string, depth: number | null, requestJson: string) => string;
         /** Ordered top-level render units per scope container (JSON {@link RenderPlan}) —
          *  what the editor's incremental reconciler diffs its DOM against. Optional:
          *  absent on older WASM bundles. */
@@ -1305,7 +1347,7 @@ export interface DocxodusWasmExports {
          *  true list-marker numbers. Optional: absent on older WASM bundles. */
         RenderBlocksHtml?: (handle: number, anchorIdsJson: string, cssPrefix: string, fabricateClasses: boolean) => string;
         RenderBlocksHtmlForReview?: (handle: number, anchorIdsJson: string, cssPrefix: string, fabricateClasses: boolean, renderTrackedChanges: boolean) => string;
-        RenderBlockHtml: (handle: number, anchorId: string, cssPrefix: string, fabricateClasses: boolean) => string;
+        RenderBlockHtml: (handle: number, anchorId: string, cssPrefix: string | null, fabricateClasses: boolean | null) => string;
         RenderBlockHtmlForReview?: (handle: number, anchorId: string, cssPrefix: string, fabricateClasses: boolean, renderTrackedChanges: boolean) => string;
         RenderHtml: (handle: number, cssPrefix: string, fabricateClasses: boolean, paginated: boolean, scale: number) => string;
         RenderHtmlForReview?: (handle: number, cssPrefix: string, fabricateClasses: boolean, paginated: boolean, scale: number, renderTrackedChanges: boolean) => string;
@@ -1350,7 +1392,7 @@ export interface DocxodusWasmExports {
         SetColumnWidths: (handle: number, cellAnchor: string, widthsJson: string) => string;
         SetTableBorders: (handle: number, cellAnchor: string, specJson: string) => string;
         SetCellShading: (handle: number, cellAnchor: string, fill: string, scope: string) => string;
-        SetRepeatHeaderRow: (handle: number, cellAnchor: string, repeat: boolean) => string;
+        SetRepeatHeaderRow: (handle: number, cellAnchor: string, repeat: boolean | null) => string;
         SetTableRowOptions: (handle: number, cellAnchor: string, repeatHeader: boolean | null, allowBreakAcrossPages: boolean | null, heightTwips: number | null, heightRule: string) => string;
         SetHeaderText: (handle: number, anchor: string, kind: string, markdown: string) => string;
         SetFooterText: (handle: number, anchor: string, kind: string, markdown: string) => string;
@@ -1407,6 +1449,7 @@ export interface DocxodusWasmExports {
         MoveBookmark: (handle: number, name: string, startAnchor: string, startOffset: number, endAnchor: string, endOffset: number) => string;
         RemoveBookmark: (handle: number, name: string) => string;
         ListRevisions: (handle: number) => string;
+        ListRevisionsFiltered?: (handle: number, filterJson: string) => string;
         ListRevisionRepairs?: (handle: number) => string;
         RepairRevisions?: (handle: number, repairsJson: string) => string;
         AcceptRevision: (handle: number, revisionId: string) => string;
@@ -1433,11 +1476,11 @@ export interface DocxodusWasmExports {
         ReplaceTextAtSpan: (handle: number, anchor: string, spanStart: number, spanLength: number, replace: string) => string;
         ReplaceTextAtSpanWithFormat?: (handle: number, anchor: string, spanStart: number, spanLength: number, replace: string, formatJson: string) => string;
         ReplaceInner: (handle: number, matchText: string, anchor: string, spanStart: number, spanLength: number, newInner: string) => string;
-        FindPlaceholders: (handle: number, kinds: number, scope: number, contextChars: number, boundary: number) => string;
-        FindPlaceholdersWithCitations: (handle: number, kinds: number, scope: number, contextChars: number, boundary: number, requestJson: string) => string;
+        FindPlaceholders: (handle: number, kinds: number | null, scope: number | null, contextChars: number | null, boundary: number | null) => string;
+        FindPlaceholdersWithCitations: (handle: number, kinds: number | null, scope: number | null, contextChars: number | null, boundary: number | null, requestJson: string) => string;
         GetEditSummary: (handle: number) => string;
-        RemainingPlaceholders: (handle: number, kinds: number) => string;
-        GetDiff: (handle: number, format: number) => string;
+        RemainingPlaceholders: (handle: number, kinds: number | null) => string;
+        GetDiff: (handle: number, format: number | null) => string;
         GetSemanticChanges: (handle: number) => string;
         VerifyDeliverable: (handle: number) => string;
         VerifyDeliverableWithRequest?: (handle: number, requestJson: string) => string;
@@ -1450,7 +1493,7 @@ export interface DocxodusWasmExports {
         Exists: (handle: number, anchorId: string) => boolean;
         FindByText: (handle: number, needle: string, optionsJson: string) => string;
         FindAllByText: (handle: number, needle: string, optionsJson: string) => string;
-        FindByRegex: (handle: number, pattern: string, regexOptions: number, optionsJson: string) => string;
+        FindByRegex: (handle: number, pattern: string, regexOptions: number | null, optionsJson: string) => string;
         FindByKind: (handle: number, kind: string, scope: string) => string;
         FindByKindWithCitations: (handle: number, kind: string, scope: string, requestJson: string) => string;
         GetAnchorInfo: (handle: number, anchorId: string) => string;
@@ -1479,7 +1522,10 @@ 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_page_setup" | "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" | "preview_not_found" | "preview_stale" | "revision_repair_rejected" | "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_page_setup" | "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" | "preview_not_found" | "preview_stale" | "revision_repair_rejected" | "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"
+/** A failed edit's rollback also failed, so the document may be half-changed. Every later
+ * mutation is refused with this code; close the session and reopen it from known-good bytes. */
+ | "session_corrupted";
 export interface AnchorRef {
     id: string;
     kind: string;
@@ -1643,9 +1689,40 @@ export interface MutationTransaction {
     /** A JSON object describing the batch (step kinds, targets, payloads). */
     request: Record<string, unknown>;
 }
+/** One changed top-level block in a {@link MarkdownPatch}. */
+export interface MarkdownPatchBlock {
+    /** The block's anchor id (`kind:scope:unid`). */
+    anchorId: string;
+    /** The block it now follows in its scope, or `null` when it is the scope's first block. */
+    afterAnchorId: string | null;
+    /** The block's own markdown, without the separators the full projection puts between blocks. */
+    markdown: string;
+}
+/**
+ * The projection change one mutation produced. Block-scoped: it carries the markdown of the
+ * top-level blocks (body paragraphs/tables, header and footer blocks, note definitions, comments)
+ * that changed or were added since the previous patch, and the ids of blocks that are gone.
+ * A client keeping one entry per block applies it by deleting `removedAnchorIds`, then, for each
+ * of `blocks` in order, deleting that id if present and re-inserting it after `afterAnchorId`.
+ *
+ * When a block-local patch cannot be exact, `fullDocument` is true and `markdown` is the whole
+ * projection: an edit that renumbered a list, changed a style, edited a header or footer, or added,
+ * removed or renumbered a story part or a note; the first patch after an op failed and rolled back
+ * or a preview was committed; any non-`FullUnid` anchor rendering. `undo()` and `redo()` return no
+ * patch: re-read the projection after them; the next patch covers only later changes. Call
+ * `project()` for the whole document at any time.
+ */
 export interface MarkdownPatch {
+    /** The anchor the op addressed. */
     scopeAnchorId: string;
+    /** The changed blocks' markdown in document order, or the whole projection when `fullDocument`. */
     markdown: string;
+    /** True when `markdown` is the whole projection; `blocks` and `removedAnchorIds` are then empty. */
+    fullDocument: boolean;
+    /** Blocks changed or added since the previous patch, in document order. */
+    blocks: MarkdownPatchBlock[];
+    /** Ids of blocks removed since the previous patch (or whose id changed). */
+    removedAnchorIds: string[];
 }
 export interface EditResult {
     success: boolean;
@@ -2753,6 +2830,20 @@ export interface GrepOptions {
     boundary?: number;
     /** Attach citations only if this exact registered layout is still valid. */
     citation?: PageCitationRequest;
+    /** Return at most this many matches, in document order. Omitted returns them all. */
+    maxResults?: number;
+}
+/**
+ * Narrows {@link DocxSession.listRevisions} to the entries matching every field set here.
+ * `author`, `changeType` (the entry's `type`), `family` and `resolutionStatus` ignore case;
+ * `partUri` is exact.
+ */
+export interface RevisionListFilter {
+    author?: string;
+    changeType?: string;
+    family?: string;
+    resolutionStatus?: string;
+    partUri?: string;
 }
 /**
  * Options that tune the `findBy*` helpers on {@link DocxSession}. Mirrors the
@@ -3783,8 +3874,18 @@ export interface WorkerResponseBase {
      */
     errorCode?: WorkerErrorCode;
 }
-/** Closed set of machine-readable worker failure causes. */
-export type WorkerErrorCode = "resource_limit";
+/**
+ * Closed set of machine-readable worker failure causes.
+ *
+ * - `resource_limit`: the operation exceeded a configured size or work limit.
+ * - `internal_error`: the worker threw an unexpected error while handling the request.
+ * - `timeout`: the request outlived its `timeoutMs` / `requestTimeoutMs` deadline.
+ * - `aborted`: the request's `AbortSignal` fired.
+ * - `message_error`: a worker response could not be deserialized (`messageerror`); every request
+ *   in flight is rejected with this code, because the lost response cannot be matched to its request.
+ * - `missing_result`: the worker reported success but sent no payload.
+ */
+export type WorkerErrorCode = "resource_limit" | "internal_error" | "timeout" | "aborted" | "message_error" | "missing_result";
 /**
  * Response from init request.
  */
@@ -3948,6 +4049,21 @@ export interface WorkerDocxodusOptions {
     wasmBasePath?: string;
     /** Abort the owned worker, including an initialization that has not completed. */
     signal?: AbortSignal;
+    /**
+     * Reject any request, including initialization, that has not answered within this many
+     * milliseconds, with a `timeout` {@link WorkerErrorCode}. Off by default: large documents can
+     * legitimately take a long time. A timed-out initialization stops the worker. Any other
+     * timed-out request is most likely still running on the worker's single thread, and later
+     * requests queue behind it; call `terminate()` to stop it.
+     */
+    requestTimeoutMs?: number;
+}
+/** Per-request options for a `WorkerDocxodus.withRequestOptions` view. */
+export interface WorkerRequestOptions {
+    /** Rejects each pending request of the view with an `aborted` {@link WorkerErrorCode} when it fires. */
+    signal?: AbortSignal;
+    /** A deadline in milliseconds that overrides the instance's `requestTimeoutMs`. */
+    timeoutMs?: number;
 }
 /**
  * OpenContracts document export format.