docxodus 5.5.4 → 6.0.0

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/session.js

@@ -0,0 +1,224 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+import { PlaceholderKinds } from "./types.js";
+/**
+ * Stateful in-memory DOCX editing session keyed by markdown-projection anchor ids.
+ * Mirror of the .NET `DocxSession` surface. See
+ * `docs/architecture/docx_mutation_api.md` for the surface contract,
+ * anchor lifecycle, error catalog, and supported markdown subset.
+ *
+ * Sessions are not eligible for JS-side garbage collection — call {@link close}
+ * (or use a `using` block under TypeScript 5.2+) when done.
+ */
+export class DocxSession {
+    /** @internal */
+    constructor(handle, wasm) {
+        // ─── Raw escape hatch ────────────────────────────────────────────────
+        this.raw = {
+            getXml: (anchorId) => this.wasm.RawGetXml(this.handle, anchorId),
+            insertXml: (anchorId, position, xml) => JSON.parse(this.wasm.RawInsertXml(this.handle, anchorId, position, xml)),
+            replaceXml: (anchorId, xml) => JSON.parse(this.wasm.RawReplaceXml(this.handle, anchorId, xml)),
+        };
+        this.handle = handle;
+        this.wasm = wasm;
+    }
+    // ─── View ────────────────────────────────────────────────────────────
+    project() {
+        return JSON.parse(this.wasm.Project(this.handle));
+    }
+    // ─── Tier A: text CRUD ───────────────────────────────────────────────
+    replaceText(anchorId, markdown) {
+        return JSON.parse(this.wasm.ReplaceText(this.handle, anchorId, markdown));
+    }
+    deleteBlock(anchorId) {
+        return JSON.parse(this.wasm.DeleteBlock(this.handle, anchorId));
+    }
+    // ─── Tier B: structural ──────────────────────────────────────────────
+    insertParagraph(anchorId, position, markdown) {
+        return JSON.parse(this.wasm.InsertParagraph(this.handle, anchorId, position, markdown));
+    }
+    splitParagraph(anchorId, characterOffset) {
+        return JSON.parse(this.wasm.SplitParagraph(this.handle, anchorId, characterOffset));
+    }
+    mergeParagraphs(firstAnchorId, secondAnchorId) {
+        return JSON.parse(this.wasm.MergeParagraphs(this.handle, firstAnchorId, secondAnchorId));
+    }
+    // ─── Tier C: formatting ──────────────────────────────────────────────
+    applyFormat(anchorId, span, op) {
+        const spanJson = span ? JSON.stringify(span) : "";
+        return JSON.parse(this.wasm.ApplyFormat(this.handle, anchorId, spanJson, JSON.stringify(op)));
+    }
+    /**
+     * Convenience: find `substring` in the anchor's flat text and apply `op` to the
+     * first occurrence. Eliminates the offset-arithmetic trap from #138 — caller passes
+     * the visible text they want formatted, the WASM-side resolves it to a CharSpan.
+     */
+    applyFormatBySubstring(anchorId, substring, op) {
+        return JSON.parse(this.wasm.ApplyFormatBySubstring(this.handle, anchorId, substring, JSON.stringify(op)));
+    }
+    /**
+     * Convenience: apply `op` to the exact span of a {@link TextMatch} (typically from
+     * {@link grep}). The match's `enclosingAnchor.id` + `span` address one specific
+     * occurrence even when several identical needles share the same block.
+     */
+    applyFormatToMatch(match, op) {
+        const span = { start: match.span.start, length: match.span.length };
+        return this.applyFormat(match.enclosingAnchor.id, span, op);
+    }
+    setParagraphStyle(anchorId, styleId) {
+        return JSON.parse(this.wasm.SetParagraphStyle(this.handle, anchorId, styleId));
+    }
+    setListLevel(anchorId, levelDelta) {
+        return JSON.parse(this.wasm.SetListLevel(this.handle, anchorId, levelDelta));
+    }
+    removeListMembership(anchorId) {
+        return JSON.parse(this.wasm.RemoveListMembership(this.handle, anchorId));
+    }
+    // ─── Tier D: cell content ────────────────────────────────────────────
+    replaceCellContent(cellAnchorId, markdown) {
+        return JSON.parse(this.wasm.ReplaceCellContent(this.handle, cellAnchorId, markdown));
+    }
+    // ─── Search ──────────────────────────────────────────────────────────
+    /**
+     * Searches the flat text of every paragraph/heading/list-item in scope for
+     * matches of `pattern`, returning them in document order with the run
+     * fragments each match spans. Lets callers rewrite a match in place while
+     * preserving each fragment's formatting (bold/italic/hyperlink/etc.).
+     *
+     * `pattern` is a regular expression — use plain string equivalents wrapped
+     * in `^` / `$` or pass literal text escaped via a helper.
+     *
+     * @see docs/architecture/docx_mutation_api.md#grep
+     */
+    grep(pattern, options) {
+        return JSON.parse(this.wasm.Grep(this.handle, pattern, options ? JSON.stringify(options) : ""));
+    }
+    /**
+     * Like {@link grep}, but lets a single match span adjacent block-level
+     * siblings (paragraphs/headings/list items) under the same parent. Block
+     * boundaries appear in the matched text as `\n`, so `^`/`$` with the
+     * Multiline flag anchor at boundaries and `.` won't cross unless Singleline
+     * is set.
+     *
+     * Matches never cross OOXML package parts, container boundaries (body →
+     * table cell), or non-paragraph siblings (a table between two paragraphs
+     * breaks the run). Returned superset of {@link grep}: single-block matches
+     * still appear with one slice. Filter `slices.length > 1` for cross-block only.
+     *
+     * @see docs/architecture/docx_mutation_api.md#grepcrossblock
+     */
+    grepCrossBlock(pattern, options) {
+        return JSON.parse(this.wasm.GrepCrossBlock(this.handle, pattern, options ? JSON.stringify(options) : ""));
+    }
+    /**
+     * Finds every literal occurrence of `find` in the anchor's flat text and
+     * replaces it with `replace`, preserving the surrounding run formatting that
+     * the match didn't touch. Returns one `EditResult` per attempted match.
+     *
+     * Run-formatting contract: the replacement text inherits the formatting of
+     * the FIRST run the match spanned. Middle/trailing runs keep their `w:rPr`
+     * but lose the slice of text the match consumed.
+     *
+     * @see docs/architecture/docx_mutation_api.md#replacetextrange
+     */
+    replaceTextRange(anchorId, find, replace, options) {
+        return JSON.parse(this.wasm.ReplaceTextRange(this.handle, anchorId, find, replace, options ? JSON.stringify(options) : ""));
+    }
+    /**
+     * Replaces a specific Grep match in place — addresses the exact span by
+     * `enclosingAnchor.id` + `span.{start,length}`, so identical needles in the
+     * same paragraph (the template-fill case where five `[___]` placeholders
+     * each get a different value) don't collide.
+     */
+    replaceMatch(match, replace) {
+        return JSON.parse(this.wasm.ReplaceTextAtSpan(this.handle, match.enclosingAnchor.id, match.span.start, match.span.length, replace));
+    }
+    /**
+     * Enumerate template placeholders in the document. Thin classifier over
+     * {@link grep}: distinguishes `[___]` value blanks (`blank_fill`),
+     * `[bracketed alternative clauses]` (`alternative_clause`), and
+     * `[insert X]` / `[*italic hint*]` instructions (`instruction`).
+     *
+     * Combine kinds with bitwise OR: `PlaceholderKinds.BlankFill | PlaceholderKinds.Instruction`.
+     * Default is `PlaceholderKinds.All`; default scope is body only (1).
+     *
+     * @see docs/architecture/docx_mutation_api.md#findplaceholders
+     */
+    findPlaceholders(kinds = PlaceholderKinds.All, scope = 1) {
+        return JSON.parse(this.wasm.FindPlaceholders(this.handle, kinds, scope));
+    }
+    // ─── Annotation-based anchor discovery (#132) ────────────────────────
+    /**
+     * Resolves an annotation's range to the block-level markdown anchors covering
+     * it, in document order. The bridge between Docxodus' read-side annotation API
+     * and the write-side session: an agent that wants to edit "the indemnification
+     * clause" looks the annotation up by id and gets the anchors it can hand to
+     * {@link replaceText} / {@link deleteBlock} / {@link raw}. Returns an empty
+     * list when the id is unknown or its bookmark is missing.
+     *
+     * v1 returns the enclosing block anchors — every paragraph/heading/list-item/
+     * cell/row/table whose subtree overlaps the bookmark range. Filter by
+     * `kind === "p" | "h" | "li"` when you want only text-bearing blocks.
+     *
+     * @see docs/architecture/docx_mutation_api.md#findbyannotation
+     */
+    findByAnnotation(annotationId) {
+        return JSON.parse(this.wasm.FindByAnnotation(this.handle, annotationId));
+    }
+    /**
+     * Finds every annotation whose `labelId` matches and resolves each of their
+     * ranges. The result is keyed by annotation id so callers can disambiguate
+     * when the same label is applied to multiple regions (three "WARRANTY"
+     * annotations on different paragraphs become three entries). Annotations
+     * whose bookmark resolves to no anchors are omitted from the result.
+     */
+    findByLabel(labelId) {
+        return JSON.parse(this.wasm.FindByLabel(this.handle, labelId));
+    }
+    /**
+     * Resolves any bookmark in the main document part (Docxodus-managed or
+     * user-authored) to the block-level anchors covering its range, in document
+     * order. Empty when the bookmark name is unknown. Use this for raw bookmark
+     * names that didn't come from the annotation system.
+     */
+    findByBookmark(bookmarkName) {
+        return JSON.parse(this.wasm.FindByBookmark(this.handle, bookmarkName));
+    }
+    /**
+     * Enumerates every annotation persisted in the document. Lets an agent prime
+     * itself with "here are the labeled regions you can target" before committing
+     * to a specific id.
+     */
+    listAnnotations() {
+        return JSON.parse(this.wasm.ListAnnotations(this.handle));
+    }
+    // ─── Lifecycle ───────────────────────────────────────────────────────
+    undo() {
+        return this.wasm.Undo(this.handle);
+    }
+    redo() {
+        return this.wasm.Redo(this.handle);
+    }
+    save() {
+        return this.wasm.Save(this.handle);
+    }
+    close() {
+        this.wasm.CloseSession(this.handle);
+    }
+    // TypeScript 5.2+ disposable protocol
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+/**
+ * Opens a new {@link DocxSession} over the supplied DOCX bytes.
+ * The returned session holds its document in WASM memory until you call
+ * {@link DocxSession.close} (or it is disposed).
+ */
+export function openDocxSession(bytes, wasmExports, settings) {
+    const bridge = wasmExports.DocxSessionBridge;
+    const handle = bridge.OpenSession(bytes, settings ? JSON.stringify(settings) : "");
+    return new DocxSession(handle, bridge);
+}
+export { PlaceholderKinds } from "./types.js";
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,3 +1,96 @@
+/**
+ * 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
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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 +444,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 +470,264 @@ 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;
+        ReplaceText: (handle: number, anchor: string, md: string) => string;
+        DeleteBlock: (handle: number, anchor: 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;
+        FindPlaceholders: (handle: number, kinds: number, scope: number) => string;
+        FindByAnnotation: (handle: number, annotationId: string) => string;
+        FindByLabel: (handle: number, labelId: string) => string;
+        FindByBookmark: (handle: number, bookmarkName: string) => string;
+        ListAnnotations: (handle: number) => 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;
+}
+export interface DocxSessionProjection {
+    markdown: string;
+    anchorIndex: Record<string, {
+        partUri: string;
+        unid: string;
+        kind: string;
+        scope: 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;
+};
+export interface TemplatePlaceholder {
+    kind: PlaceholderKind;
+    /** For `instruction` placeholders: the inner text with surrounding brackets/asterisks stripped. */
+    hint?: string;
+    match: TextMatch;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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. Stale page caches and arbitrary
+ * metadata are omitted to keep the JSON payload compact — callers that need them
+ * can use the .NET API directly.
+ *
+ * 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;
 }
 /**
  * Severity level for comparison log entries.