docxodus 5.5.4 → 6.1.0

package/dist/types.d.ts

@@ -1,3 +1,153 @@
+/**
+ * Which parts of the OOXML package to include in the markdown projection.
+ * Bitflags mirroring the .NET `Docxodus.ProjectionScopes` enum.
+ */
+export declare enum ProjectionScopes {
+    Body = 1,
+    Headers = 2,
+    Footers = 4,
+    Footnotes = 8,
+    Endnotes = 16,
+    Comments = 32,
+    All = 63
+}
+/**
+ * How anchor markers are rendered in the markdown projection.
+ * Mirrors the .NET `Docxodus.AnchorRenderMode` enum.
+ */
+export declare enum AnchorRenderMode {
+    /** Anchor appears on its own line before each block element (default). */
+    Block = 0,
+    /** Block anchors plus inline `{#…}` markers for spans (comments, hyperlinks). */
+    BlockAndInline = 1,
+    /** No anchor markers in the output (projection only, no addressing). */
+    None = 2
+}
+/**
+ * Strategy for rendering `w:tbl` elements that don't fit GFM pipe-table constraints.
+ * Mirrors the .NET `Docxodus.TableRenderMode` enum.
+ */
+export declare enum TableRenderMode {
+    /** Emit GFM pipe tables when possible, opaque anchor blocks otherwise (default). */
+    GfmWithOpaqueFallback = 0,
+    /** Always emit GFM pipe tables, flattening complex structure with possible loss. */
+    AlwaysGfm = 1,
+    /** Always emit opaque anchor blocks. */
+    AlwaysOpaque = 2
+}
+/**
+ * How tracked changes are handled in the markdown projection.
+ * Mirrors the .NET `Docxodus.TrackedChangeMode` enum.
+ */
+export declare enum TrackedChangeMode {
+    /** Accept all revisions before conversion (default). */
+    Accept = 0,
+    /** Render insertions and deletions inline as `{+ins+}` / `{-del-}`. */
+    RenderInline = 1,
+    /** Accept insertions, drop deletions. */
+    StripDeletions = 2
+}
+/**
+ * How empty paragraphs are rendered. Mirrors the .NET `Docxodus.EmptyParagraphMode` enum.
+ */
+export declare enum EmptyParagraphMode {
+    /** Default: emit the anchor on its own line (`{#p:body:UNID}\n`). */
+    AnchorOnly = 0,
+    /** Tag the empty paragraph visibly so agents can pattern-match (`{#p:body:UNID} ∅`). */
+    MarkedEmpty = 1,
+    /** Skip empty paragraphs entirely — they don't appear in the markdown or the anchor index. */
+    Suppress = 2
+}
+/**
+ * How anchor ids are rendered inside `{#…}` tokens (and keyed in
+ * {@link MarkdownProjection.anchorIndex}). Mirrors the .NET
+ * `Docxodus.AnchorIdRendering` enum.
+ *
+ * `Anchor.token` (and any `AnchorRef` returned by `DocxSession` mutations)
+ * always carries the full Unid regardless of rendering — the choice only
+ * affects the markdown text. The returned `anchorIndex` is dual-keyed so
+ * lookups by either the rendered id or the full Unid work for the
+ * `Abbreviated`/`Sequential` modes.
+ */
+export declare enum AnchorIdRendering {
+    /** Full 32-char hex Unid (default; e.g. `{#h:body:a1b2c3d4e5f6789012345678901234ab}`). */
+    FullUnid = 0,
+    /** Shortest unique prefix per (kind, scope) bucket, 4-char floor (e.g. `{#h:body:a1b2}`).
+     *  Saves 5-10% of projection-token budget for LLM consumption. */
+    Abbreviated = 1,
+    /** Sequential numeric ids per (kind, scope) bucket in document order (e.g. `{#h:body:1}`).
+     *  Maximally token-efficient for one-shot LLM contexts. NOT stable across
+     *  `project()` calls and must NOT be persisted. */
+    Sequential = 2
+}
+/**
+ * How far below the target anchor to include in
+ * {@link DocxSession.projectAnchor}. Mirrors the .NET
+ * `Docxodus.ProjectionDepth` enum.
+ */
+export declare enum ProjectionDepth {
+    /** Just the target block itself (its anchor + its own text). For headings,
+     *  returns only the heading paragraph, not the section under it. */
+    SelfOnly = 0,
+    /** Self + descendants. Most useful for `tbl` anchors (returns the whole table);
+     *  for paragraphs it's the same as `SelfOnly`. */
+    Subtree = 1,
+    /** Self + descendants + following siblings up to (but not including) the next
+     *  sibling at the same or higher heading level. For non-heading anchors,
+     *  equivalent to `Subtree`. Dominant "give me this section" case; the default. */
+    SubtreeAndFollowingSiblings = 2
+}
+/**
+ * Settings controlling the markdown projection. Mirrors the .NET
+ * `WmlToMarkdownConverterSettings` class — see `docs/architecture/markdown_projection.md`.
+ */
+export interface MarkdownProjectionSettings {
+    scopes?: ProjectionScopes;
+    headingLevelOffset?: number;
+    anchorMode?: AnchorRenderMode;
+    tableMode?: TableRenderMode;
+    tableInlineCellMax?: number;
+    trackedChanges?: TrackedChangeMode;
+    resolveNumbering?: boolean;
+    emptyParagraphs?: EmptyParagraphMode;
+    /**
+     * How anchor ids are rendered in markdown output. Default `FullUnid`.
+     * Set to `Abbreviated` for terse LLM-friendly ids; `Sequential` for
+     * 1-based per-scope counters (best for replay logs / human review).
+     * `Anchor.token` (and any `AnchorRef`) always reflects the full Unid
+     * regardless; this only affects the markdown text. Use the returned
+     * {@link MarkdownProjection.anchorIndex} (dual-keyed for Abbreviated /
+     * Sequential) to translate rendered ids back to full Unids.
+     */
+    anchorIdRendering?: AnchorIdRendering;
+}
+/**
+ * Resolved location of an anchor in the underlying OOXML package — sufficient to walk
+ * back to the source element via the .NET API.
+ */
+export interface MarkdownAnchorTarget {
+    id: string;
+    kind: string;
+    scope: string;
+    unid: string;
+    partUri: string;
+    /** First ~80 characters of the element's flat text — for previewing/picking anchors. */
+    textPreview: string;
+    /** Resolved auto-numbering prefix (e.g. "1.", "First") for paragraphs/headings/list
+     *  items whose style or `w:numPr` produces numbering. Absent when the element has
+     *  no numbering. The prefix is NOT included in {@link textPreview} because
+     *  textPreview reflects only the run text; this field gives callers the value
+     *  Word actually renders before the element's text. */
+    autoNumberPrefix?: string;
+}
+/**
+ * Output of the markdown projection: rendered text plus the anchor index mapping
+ * each `{#…}` token back to a location in the OOXML package.
+ */
+export interface MarkdownProjection {
+    markdown: string;
+    anchorIndex: Record<string, MarkdownAnchorTarget>;
+}
 /**
  * Revision type enum matching the .NET WmlComparerRevisionType
  */
@@ -351,6 +501,7 @@ export interface DocxodusWasmExports {
         GetDocumentStructure: (bytes: Uint8Array) => string;
         GetDocumentMetadata: (bytes: Uint8Array) => string;
         ExportToOpenContract: (bytes: Uint8Array) => string;
+        ConvertWmlToMarkdown: (bytes: Uint8Array, settingsJson: string) => string;
         GetVersion: () => string;
         ConvertDocxToHtmlProfiled: (bytes: Uint8Array) => string;
         ProfileConversionDetailed: (bytes: Uint8Array) => string;
@@ -376,6 +527,503 @@ export interface DocxodusWasmExports {
         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;
     };
+    DocxSessionBridge: {
+        OpenSession: (bytes: Uint8Array, settingsJson: string) => number;
+        CloseSession: (handle: number) => void;
+        Project: (handle: number) => string;
+        ProjectAnchor: (handle: number, anchorId: string, depth: number) => string;
+        ReplaceText: (handle: number, anchor: string, md: string) => string;
+        DeleteBlock: (handle: number, anchor: string) => string;
+        DeleteRange: (handle: number, fromAnchorId: string, toAnchorIdExclusive: string) => string;
+        DeleteSection: (handle: number, headingAnchorId: string) => string;
+        InsertParagraph: (handle: number, anchor: string, pos: string, md: string) => string;
+        SplitParagraph: (handle: number, anchor: string, offset: number) => string;
+        MergeParagraphs: (handle: number, first: string, second: string) => string;
+        ApplyFormat: (handle: number, anchor: string, spanJson: string, opJson: string) => string;
+        ApplyFormatBySubstring: (handle: number, anchor: string, substring: string, opJson: string) => string;
+        SetParagraphStyle: (handle: number, anchor: string, styleId: string) => string;
+        SetListLevel: (handle: number, anchor: string, delta: number) => string;
+        RemoveListMembership: (handle: number, anchor: string) => string;
+        ReplaceCellContent: (handle: number, anchor: string, md: string) => string;
+        RawGetXml: (handle: number, anchor: string) => string;
+        RawInsertXml: (handle: number, anchor: string, pos: string, xml: string) => string;
+        RawReplaceXml: (handle: number, anchor: string, xml: string) => string;
+        Grep: (handle: number, pattern: string, optionsJson: string) => string;
+        GrepCrossBlock: (handle: number, pattern: string, optionsJson: string) => string;
+        ReplaceTextRange: (handle: number, anchor: string, find: string, replace: string, optionsJson: string) => string;
+        ReplaceTextAtSpan: (handle: number, anchor: string, spanStart: number, spanLength: number, replace: 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;
+        GetEditSummary: (handle: number) => string;
+        RemainingPlaceholders: (handle: number, kinds: number) => string;
+        GetDiff: (handle: number, format: number) => string;
+        FindByAnnotation: (handle: number, annotationId: string) => string;
+        FindByLabel: (handle: number, labelId: string) => string;
+        FindByBookmark: (handle: number, bookmarkName: string) => string;
+        GetAnchorInfo: (handle: number, anchorId: string) => string;
+        GetAnchorInfos: (handle: number, anchorIdsJson: string) => string;
+        GetBlockMetadata: (handle: number, anchorId: string) => string;
+        GetBlockMetadatas: (handle: number, anchorIdsJson: string) => string;
+        GetListMembership: (handle: number, anchorId: string) => string;
+        GetSectionInfo: (handle: number, anchorId: string) => string;
+        ListAnnotations: (handle: number) => string;
+        AddAnnotation: (handle: number, anchorId: string, spanJson: string, annotationJson: string) => string;
+        SessionRemoveAnnotation: (handle: number, annotationId: string) => string;
+        UpdateAnnotation: (handle: number, annotationId: string, updateJson: string) => string;
+        MoveAnnotation: (handle: number, annotationId: string, newAnchorId: string, newSpanJson: string) => string;
+        Undo: (handle: number) => boolean;
+        Redo: (handle: number) => boolean;
+        Save: (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" | "unknown_style" | "invalid_list_level" | "malformed_xml" | "disallowed_namespace" | "incompatible_element_type" | "validation_failed" | "nothing_to_undo" | "nothing_to_redo" | "internal_error";
+export interface AnchorRef {
+    id: string;
+    kind: string;
+    scope: string;
+    unid: string;
+}
+export interface EditError {
+    code: EditErrorCode;
+    message: string;
+    anchorId?: string;
+}
+export interface MarkdownPatch {
+    scopeAnchorId: string;
+    markdown: string;
+}
+export interface EditResult {
+    success: boolean;
+    error?: EditError;
+    created: AnchorRef[];
+    removed: AnchorRef[];
+    modified: AnchorRef[];
+    patch?: MarkdownPatch;
+}
+export interface CharSpan {
+    start: number;
+    length: number;
+}
+export interface FormatOp {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    code?: boolean;
+    color?: string;
+    runStyle?: string;
+}
+export interface DocxSessionSettings {
+    undoDepth?: number;
+    validateRawOps?: boolean;
+    trackedChanges?: "accept" | "render_inline" | "strip_deletions";
+    revisionAuthor?: string;
+    /**
+     * When false (default), `save()` strips the projector's internal `PtOpenXml:Unid`
+     * attributes before serializing — they aren't OOXML schema, and persisting them
+     * bloats large documents significantly (~700 KB on a 100-page DOCX). Set to true
+     * only when anchor ids must survive a save/reopen round trip.
+     */
+    persistAnchorIds?: boolean;
+    /**
+     * When true, ReplaceText / ReplaceTextRange / ReplaceMatch payloads have ASCII
+     * `"` and `'` converted to typographic curly quotes (`“ ” ‘ ’`) based on
+     * context — open at start / after whitespace / after open-bracket, close
+     * elsewhere. Avoids the cosmetic regression where a replacement lands as
+     * straight-quoted text adjacent to surrounding already-curly text. Default false.
+     */
+    smartQuotes?: boolean;
+    /**
+     * When `true` (default), the session projects the document at construction
+     * time so {@link DocxSession.getDiff} can compare initial vs. current.
+     * Set to `false` to skip the ~200ms upfront cost if you don't plan to diff.
+     */
+    captureInitialProjection?: boolean;
+}
+export interface DocxSessionProjection {
+    markdown: string;
+    anchorIndex: Record<string, {
+        partUri: string;
+        unid: string;
+        kind: string;
+        scope: string;
+        textPreview: string;
+    }>;
+}
+/**
+ * Per-fragment visible formatting reported by {@link DocxSession.grep}.
+ */
+export interface RunFormatting {
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    strike: boolean;
+    code: boolean;
+    color?: string;
+    hyperlinkUrl?: string;
+    runStyle?: string;
+}
+/**
+ * One piece of a {@link TextMatch} that came from a single `<w:r>` run.
+ */
+export interface RunFragment {
+    /** PtOpenXml:Unid of the `w:r` element this fragment came from. */
+    unid: string;
+    /** The text from this run that participates in the match. */
+    text: string;
+    /** Character offset + length of this fragment inside the run's flat text. */
+    spanInElement: CharSpan;
+    /** Visible formatting of the run this fragment came from. */
+    formatting: RunFormatting;
+}
+/**
+ * A single match returned by {@link DocxSession.grep}. The match always lives
+ * within one block-level element.
+ */
+export interface TextMatch {
+    text: string;
+    enclosingAnchor: AnchorRef;
+    span: CharSpan;
+    fragments: RunFragment[];
+    contextBefore: string;
+    contextAfter: string;
+    /** Regex capture groups; index 0 is always the whole match. */
+    groups: string[];
+}
+/**
+ * One block's contribution to a {@link CrossBlockMatch}. The slice's `fragments`
+ * list is empty when the match touches an empty paragraph — the slice is still
+ * recorded so callers can see the match crossed the empty block.
+ */
+export interface BlockSlice {
+    anchor: AnchorRef;
+    /** Character offset + length of the slice within the block's own flat text. */
+    spanInBlock: CharSpan;
+    /** Run fragments contributing to this slice, in document order. */
+    fragments: RunFragment[];
+}
+/**
+ * A single match returned by {@link DocxSession.grepCrossBlock}. The match may
+ * span multiple adjacent block-level elements (paragraphs/headings/list items)
+ * under the same parent container. `slices` is the per-block breakdown;
+ * `enclosingAnchors` lists every block the match touches, in document order.
+ *
+ * Block boundaries appear in `text` / `contextBefore` / `contextAfter` as
+ * single `\n` characters.
+ */
+export interface CrossBlockMatch {
+    text: string;
+    enclosingAnchors: AnchorRef[];
+    slices: BlockSlice[];
+    contextBefore: string;
+    contextAfter: string;
+    /** Regex capture groups; index 0 is always the whole match. */
+    groups: string[];
+}
+/**
+ * Options for {@link DocxSession.replaceTextRange}.
+ */
+export interface ReplaceOptions {
+    /** Case-insensitive matching for the literal `find` needle. */
+    ignoreCase?: boolean;
+    /** Cap the number of replacements; omitted = unlimited. */
+    maxReplacements?: number;
+}
+/**
+ * Categories of bracketed placeholders {@link DocxSession.findPlaceholders} recognizes.
+ *
+ * - `blank_fill` — `[___]` or `$[___]` value slots
+ * - `alternative_clause` — `[entire clause text]`
+ * - `instruction` — `[insert X]`, `[specify Y]`, `[*italicized hint*]`
+ */
+export type PlaceholderKind = "blank_fill" | "alternative_clause" | "instruction";
+/**
+ * Numeric flag layout matching the .NET `PlaceholderKinds` enum. Combine with bitwise OR.
+ */
+export declare const PlaceholderKinds: {
+    readonly BlankFill: 1;
+    readonly AlternativeClause: 2;
+    readonly Instruction: 4;
+    readonly All: 7;
+};
+/**
+ * Numeric flag layout matching the .NET `DiffFormat` enum. Use with
+ * {@link DocxSession.getDiff}.
+ *
+ * - `Json` (default) — anchor-keyed structured diff. Returns a `DiffEntry[]`.
+ * - `Unified` — `patch(1)`-compatible unified diff over the markdown projection.
+ *   Returns a single string (`""` when nothing changed).
+ * - `SideBySide` — two-column human-review diff (`diff -y` style) over the
+ *   markdown projection. Returns a single string.
+ */
+export declare const DiffFormat: {
+    readonly Json: 0;
+    readonly Unified: 1;
+    readonly SideBySide: 2;
+};
+/**
+ * A single anchor-keyed change in the diff between an initial and current projection.
+ */
+export interface DiffEntry {
+    op: "delete" | "insert" | "modify";
+    anchorId: string;
+    /** Pre-change text content for delete/modify; absent for insert. */
+    before?: string;
+    /** Post-change text content for insert/modify; absent for delete. */
+    after?: string;
+}
+/**
+ * Aggregate snapshot of edit-state introspection signals returned by
+ * {@link DocxSession.getEditSummary}.
+ */
+export interface EditSummary {
+    totalAnchors: number;
+    remainingPlaceholders: TemplatePlaceholder[];
+    bareUnderscoreRuns: TextMatch[];
+    footnoteCount: number;
+    inlineFootnoteRefCount: number;
+    commentCount: number;
+}
+/**
+ * Numeric flag layout matching the .NET `ContextBoundary` enum. Controls
+ * how `Grep` / `GrepCrossBlock` / `FindPlaceholders` decide where to stop
+ * walking outward when computing `TextMatch.contextBefore` / `contextAfter`.
+ *
+ * - `Char` (default) — truncate at `contextChars`. Matches legacy behavior.
+ * - `Bracket` — stop at `[` or `]`. Use for template fills: each placeholder's
+ *   context is unambiguously its own even when multiple placeholders crowd
+ *   into one sentence.
+ * - `Sentence` — stop at `.`, `!`, `?`, `:`, `;`.
+ * - `Comma` — stop at `,`. For matches inside enumerations.
+ */
+export declare const ContextBoundary: {
+    readonly Char: 0;
+    readonly Bracket: 1;
+    readonly Sentence: 2;
+    readonly Comma: 3;
+};
+export interface TemplatePlaceholder {
+    kind: PlaceholderKind;
+    /** For `instruction` placeholders: the inner text with surrounding brackets/asterisks stripped. */
+    hint?: string;
+    match: TextMatch;
+    /**
+     * Additional plausible classifications when the primary `kind` is borderline.
+     * Empty by default. The classic case is a long bracketed clause that happens
+     * to contain a `_______` blank: primary `kind` stays `"blank_fill"`
+     * (back-compat) and `alternativeKinds` contains `"alternative_clause"`.
+     */
+    alternativeKinds: PlaceholderKind[];
+}
+/**
+ * Options for {@link DocxSession.fillPlaceholders}.
+ */
+export interface FillOptions {
+    /** Which placeholder kinds to fill. Defaults to `PlaceholderKinds.All` so the
+     *  picker is invoked for every kind in the doc. Narrow with e.g.
+     *  `PlaceholderKinds.BlankFill | PlaceholderKinds.Instruction` to ignore
+     *  bracketed alternative clauses. */
+    kinds?: number;
+    /** Which package parts to scan. Defaults to body (1). */
+    scope?: number;
+    /** Max iteration passes for multi-pass nested-bracket scenarios. Default 8. */
+    maxPasses?: number;
+    /** When the match starts with `$` and the picker's return value doesn't,
+     *  preserve the `$` by prepending it. Default true. */
+    preserveDollarPrefix?: boolean;
+    /** Cap on `contextBefore` / `contextAfter` length on each side. Default 80. */
+    contextChars?: number;
+    /** Where to stop walking outward when computing context. Numeric layout
+     *  matching {@link ContextBoundary}. Default `Char` (0). */
+    boundary?: number;
+    /** When the picker returns an empty string (and after `$`-prefix preservation
+     *  has been applied), look at the chars immediately adjacent to the placeholder
+     *  span and absorb surrounding whitespace / leading-space-before-punctuation /
+     *  matched-brackets so the dropped placeholder doesn't leave cosmetic
+     *  artifacts. Default `false` (preserve the literal-delete behavior).
+     *
+     *  Rules: whitespace on both sides collapses to one space; whitespace before
+     *  and clause-terminating punctuation (`. , ; : ! ?`) after drops the leading
+     *  space; matched open/close brackets (`()` `[]` `{}`) on either side drop
+     *  both. NBSP / narrow NBSP / thin space are treated as whitespace.
+     *
+     *  Caveat: `$`-prefix preservation runs first, so a picker returning `""` for
+     *  `$[xxx]` with `preserveDollarPrefix: true` (default) ends up replacing with
+     *  `"$"` and coalescing is skipped. Set `preserveDollarPrefix: false` when you
+     *  want the `$` to drop along with the brackets. */
+    coalesceWhitespaceAroundEmptyFill?: boolean;
+}
+/**
+ * Aggregate result returned by {@link DocxSession.fillPlaceholders}.
+ *
+ * `skipped` counts placeholders the picker returned null for in the first pass
+ * that saw them — it stays > 0 even if later passes finished those same
+ * placeholders. Use `stillPresent` (post-loop document state) for the
+ * trustworthy "is the template done?" check; `skipped > 0 && stillPresent === 0`
+ * means "picker said no the first time but later passes resolved it."
+ */
+export interface BulkEditResult {
+    filled: number;
+    skipped: number;
+    /** Number of placeholders matching `options.kinds` in `options.scope` that
+     *  remain in the document after the final pass. `0` means the template is
+     *  fully filled for the requested kinds/scope. */
+    stillPresent: number;
+    passes: number;
+    unfilled: TemplatePlaceholder[];
+    errors: EditError[];
+}
+/**
+ * Options for {@link DocxSession.grep}.
+ *
+ * `regexOptions` and `scope` use the numeric flag layouts of the .NET
+ * `System.Text.RegularExpressions.RegexOptions` and `ProjectionScopes` enums.
+ * Common values:
+ *   - `RegexOptions.IgnoreCase = 1`
+ *   - `RegexOptions.Multiline = 2`
+ *   - `ProjectionScopes.Body = 1`, `Headers = 2`, `Footers = 4`,
+ *     `Footnotes = 8`, `Endnotes = 16`, `Comments = 32`, `All = 63`.
+ */
+export interface GrepOptions {
+    regexOptions?: number;
+    scope?: number;
+    contextChars?: number;
+    /**
+     * Whitespace handling. Numeric layout matching the .NET `WhitespaceMode` enum:
+     *   - 0 = Preserve (default; match against the document's original characters)
+     *   - 1 = Normalize (fold NBSP / narrow-NBSP / thin-space to ASCII space before matching)
+     */
+    whitespace?: number;
+    /**
+     * Where to stop walking outward when computing `TextMatch.contextBefore` /
+     * `contextAfter`. Numeric layout matching the .NET `ContextBoundary` enum;
+     * use the {@link ContextBoundary} const. Default `Char` (0) — truncate at
+     * `contextChars`.
+     */
+    boundary?: number;
+}
+/**
+ * Resolved location of an anchor — what {@link DocxSession.findByAnnotation} and
+ * the other discovery helpers return. The shape is {@link AnchorRef} plus the
+ * `partUri` of the package part the element lives in (useful for callers that
+ * walk the underlying OOXML directly).
+ */
+export interface AnchorTargetRef extends AnchorRef {
+    partUri: string;
+    /** First ~80 characters of the element's flat text — for previewing/picking anchors. */
+    textPreview: string;
+    /** Resolved auto-numbering prefix (e.g. "1.", "First") when the element carries
+     *  numbering. Absent otherwise. See {@link MarkdownAnchorTarget.autoNumberPrefix}. */
+    autoNumberPrefix?: string;
+}
+/**
+ * The shape returned by {@link DocxSession.getAnchorInfo}.
+ * Use {@link MarkdownAnchorTarget} when iterating a full projection — it
+ * includes the same fields plus `unid` and `partUri`.
+ */
+export interface AnchorInfo {
+    id: string;
+    kind: string;
+    scope: string;
+    textPreview: string;
+    /** Resolved auto-numbering prefix (e.g. "1.", "First") when the element carries
+     *  numbering. Absent for un-numbered paragraphs or non-paragraph kinds. */
+    autoNumberPrefix?: string;
+}
+/** Six list formats supported by the list write surface (decimal, upperLetter,
+ *  lowerLetter, upperRoman, lowerRoman, bullet). Surfaced on
+ *  {@link ListMembership.format} as a string union (mirrors the JSON wire format). */
+export type NumberFormat = "decimal" | "upperLetter" | "lowerLetter" | "upperRoman" | "lowerRoman" | "bullet";
+/** Numbering facts for a list-item paragraph. Returned by
+ *  {@link DocxSession.getListMembership} and surfaced as {@link BlockMetadata.list}. */
+export interface ListMembership {
+    /** The w:numId the paragraph belongs to (the w:num instance). */
+    numId: number;
+    /** The w:abstractNumId the paragraph's w:num points at. */
+    abstractNumId: number;
+    /** The paragraph's level (w:ilvl), 0-8. */
+    level: number;
+    /** Resolved format for this level. */
+    format: NumberFormat;
+    /** Always true for a paragraph carrying w:numPr (inline or via style). */
+    isAutoNumbered: boolean;
+    /** True when the w:numPr is inherited from the paragraph's style chain. */
+    fromStyle: boolean;
+    /** Start-override from w:lvlOverride/w:startOverride for this level, if any. */
+    startOverride?: number;
+    /** Resolved label (e.g. "1.", "(a)") — same value surfaced via AnchorInfo.autoNumberPrefix. */
+    generatedLabel?: string;
+}
+/** Block-level structural metadata. Returned by {@link DocxSession.getBlockMetadata}. */
+export interface BlockMetadata {
+    anchorId: string;
+    kind: string;
+    scope: string;
+    styleId?: string;
+    styleName?: string;
+    /** 0-based outline level (Word convention). */
+    outlineLevel?: number;
+    list?: ListMembership;
+    /** True when any descendant w:r carries a non-empty w:rPr. */
+    hasInlineFormatting: boolean;
+}
+/** Page-layout snapshot for the w:sectPr that governs an anchor.
+ *  Returned by {@link DocxSession.getSectionInfo}. */
+export interface SectionInfo {
+    sectionUnid: string;
+    pageWidthTwips: number;
+    pageHeightTwips: number;
+    landscape: boolean;
+    marginTopTwips: number;
+    marginBottomTwips: number;
+    marginLeftTwips: number;
+    marginRightTwips: number;
+    columns: number;
+    headerPartUris: string[];
+    footerPartUris: string[];
+}
+/**
+ * A custom annotation persisted in the document via Docxodus' annotation system.
+ * Returned by {@link DocxSession.listAnnotations}; mirrors the wire-relevant
+ * fields of the .NET `DocumentAnnotation` type. The page-info cache fields
+ * (`startPage`/`endPage`/`pageInfoStale`/`pageInfoComputedAt`) are omitted to
+ * keep the JSON payload compact — callers that need them can use the .NET API
+ * directly. The `metadata` bag is emitted only when non-empty.
+ *
+ * See `docs/architecture/custom_annotations.md` for the persistence design.
+ */
+export interface DocumentAnnotation {
+    /** Unique annotation identifier (caller-supplied at add time). */
+    id: string;
+    /** Label category/type (e.g. `"INDEMNIFICATION"`, `"CLAUSE_TYPE_A"`). */
+    labelId: string;
+    /** Human-readable label text displayed in the UI. */
+    label: string;
+    /** Highlight color in hex (e.g. `"#FFEB3B"`). */
+    color: string;
+    /** Internal bookmark name in the DOCX (`_Docxodus_Ann_{id}` for managed annotations). */
+    bookmarkName: string;
+    /** Author who created the annotation, if recorded. */
+    author?: string;
+    /** Creation timestamp in ISO-8601 (round-trip) format, if recorded. */
+    created?: string;
+    /** The text content covered by the annotation's bookmark, populated when reading. */
+    annotatedText?: string;
+    /** Arbitrary string→string metadata bag persisted with the annotation. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Partial-update payload for {@link DocxSession.updateAnnotation}.
+ * Null/missing fields leave the existing value unchanged. `metadataPatch`
+ * is a per-key merge: a non-null value sets the key, an explicit `null`
+ * removes it, a missing key leaves it unchanged.
+ */
+export interface AnnotationUpdate {
+    labelId?: string;
+    label?: string;
+    color?: string;
+    author?: string;
+    metadataPatch?: Record<string, string | null>;
 }
 /**
  * Severity level for comparison log entries.
@@ -923,7 +1571,7 @@ export interface DocumentMetadata {
 /**
  * Message types sent from main thread to worker.
  */
-export type WorkerRequestType = "init" | "convertDocxToHtml" | "compareDocuments" | "compareDocumentsToHtml" | "getRevisions" | "getDocumentMetadata" | "getVersion";
+export type WorkerRequestType = "init" | "convertDocxToHtml" | "compareDocuments" | "compareDocumentsToHtml" | "getRevisions" | "getDocumentMetadata" | "getVersion" | "sessionOpen" | "sessionClose" | "sessionAddAnnotation" | "sessionRemoveAnnotation" | "sessionUpdateAnnotation" | "sessionMoveAnnotation";
 /**
  * Base structure for worker requests.
  */
@@ -999,10 +1647,67 @@ export interface WorkerGetDocumentMetadataRequest extends WorkerRequestBase {
 export interface WorkerGetVersionRequest extends WorkerRequestBase {
     type: "getVersion";
 }
+/**
+ * Open a DocxSession in the worker.
+ */
+export interface WorkerSessionOpenRequest extends WorkerRequestBase {
+    type: "sessionOpen";
+    /** Document bytes transferred to the worker */
+    documentBytes: Uint8Array;
+    /** Session settings as JSON */
+    settingsJson?: string;
+}
+/**
+ * Close a worker DocxSession.
+ */
+export interface WorkerSessionCloseRequest extends WorkerRequestBase {
+    type: "sessionClose";
+    /** Session handle returned by sessionOpen */
+    handle: number;
+}
+/**
+ * Add an annotation via a worker DocxSession.
+ */
+export interface WorkerSessionAddAnnotationRequest extends WorkerRequestBase {
+    type: "sessionAddAnnotation";
+    handle: number;
+    anchorId: string;
+    /** CharSpan as JSON, or empty string for block-level */
+    spanJson: string;
+    annotationJson: string;
+}
+/**
+ * Remove an annotation via a worker DocxSession.
+ */
+export interface WorkerSessionRemoveAnnotationRequest extends WorkerRequestBase {
+    type: "sessionRemoveAnnotation";
+    handle: number;
+    annotationId: string;
+}
+/**
+ * Update an annotation via a worker DocxSession.
+ */
+export interface WorkerSessionUpdateAnnotationRequest extends WorkerRequestBase {
+    type: "sessionUpdateAnnotation";
+    handle: number;
+    annotationId: string;
+    updateJson: string;
+}
+/**
+ * Move an annotation via a worker DocxSession.
+ */
+export interface WorkerSessionMoveAnnotationRequest extends WorkerRequestBase {
+    type: "sessionMoveAnnotation";
+    handle: number;
+    annotationId: string;
+    newAnchorId: string;
+    /** CharSpan as JSON, or empty string for block-level */
+    newSpanJson: string;
+}
 /**
  * Union type of all possible worker requests.
  */
-export type WorkerRequest = WorkerInitRequest | WorkerConvertRequest | WorkerCompareRequest | WorkerCompareToHtmlRequest | WorkerGetRevisionsRequest | WorkerGetDocumentMetadataRequest | WorkerGetVersionRequest;
+export type WorkerRequest = WorkerInitRequest | WorkerConvertRequest | WorkerCompareRequest | WorkerCompareToHtmlRequest | WorkerGetRevisionsRequest | WorkerGetDocumentMetadataRequest | WorkerGetVersionRequest | WorkerSessionOpenRequest | WorkerSessionCloseRequest | WorkerSessionAddAnnotationRequest | WorkerSessionRemoveAnnotationRequest | WorkerSessionUpdateAnnotationRequest | WorkerSessionMoveAnnotationRequest;
 /**
  * Base structure for worker responses.
  */
@@ -1068,10 +1773,33 @@ export interface WorkerGetVersionResponse extends WorkerResponseBase {
     /** Version information */
     version?: VersionInfo;
 }
+/**
+ * Response from sessionOpen request.
+ */
+export interface WorkerSessionOpenResponse extends WorkerResponseBase {
+    type: "sessionOpen";
+    /** Integer handle identifying the session in the worker */
+    handle?: number;
+}
+/**
+ * Response from sessionClose request.
+ */
+export interface WorkerSessionCloseResponse extends WorkerResponseBase {
+    type: "sessionClose";
+}
+/**
+ * Response from session annotation write operations.
+ * The `result` field is the serialised EditResult from the WASM bridge.
+ */
+export interface WorkerSessionEditResponse extends WorkerResponseBase {
+    type: "sessionAddAnnotation" | "sessionRemoveAnnotation" | "sessionUpdateAnnotation" | "sessionMoveAnnotation";
+    /** EditResult returned by the session operation */
+    result?: EditResult;
+}
 /**
  * Union type of all possible worker responses.
  */
-export type WorkerResponse = WorkerInitResponse | WorkerConvertResponse | WorkerCompareResponse | WorkerCompareToHtmlResponse | WorkerGetRevisionsResponse | WorkerGetDocumentMetadataResponse | WorkerGetVersionResponse;
+export type WorkerResponse = WorkerInitResponse | WorkerConvertResponse | WorkerCompareResponse | WorkerCompareToHtmlResponse | WorkerGetRevisionsResponse | WorkerGetDocumentMetadataResponse | WorkerGetVersionResponse | WorkerSessionOpenResponse | WorkerSessionCloseResponse | WorkerSessionEditResponse;
 /**
  * Options for creating a worker-based Docxodus instance.
  */