@nutrient-sdk/document-authoring 1.10.0-preview.202512171254.414ae9476ccdf6c895ab5cf4a5c42a6d1dc61dd9 → 1.10.0-preview.202512190816.90cd35dd5494eda6e0aba78c724b366b267c7ec8

package/lib/index.d.cts

@@ -652,7 +652,32 @@ export declare type DocAuthDocument = {
      */
     exportDOCX(options?: ExportDOCXOptions): Promise<ArrayBuffer>;
     /**
-     * @alpha
+     * Executes a transaction to programmatically read or modify the document.
+     *
+     * @remarks
+     * Provides programmatic access to the document structure through a draft document that can be
+     * read and modified. Changes are atomic and isolated until the transaction commits.
+     *
+     * The callback executes after all pending transactions and input have been processed. While
+     * the callback runs, document access is blocked, preventing any UI interactions until the
+     * transaction completes.
+     *
+     * @param callback - A {@linkcode TransactionCallback} function that receives a draft document
+     * @returns A Promise that resolves to the result value from the callback
+     *
+     * @example
+     * ```typescript
+     * await doc.transaction(async ({ draft }) => {
+     *   const section = draft.body().sections()[0];
+     *   const para = section.content().addParagraph();
+     *   para.asTextView().setText('Hello, World!');
+     *   return { commit: true };
+     * });
+     * ```
+     *
+     * @see {@linkcode TransactionCallback} for the callback function signature
+     * @see {@linkcode TransactionResult} for return value options
+     * @see {@linkcode Programmatic} for the full programmatic API namespace
      */
     transaction<T = void>(callback: TransactionCallback<T>): Promise<T>;
     /**
@@ -1389,42 +1414,282 @@ export declare type ImportDOCXOptions = {
 export declare type Locale = 'en' | 'fr' | 'de';
 
 /**
- * @alpha
+ * @public
  * @sidebarGroup programmatic api
  */
 export declare namespace Programmatic {
     /**
+     * Opaque type representing a contiguous region within the content.
+     *
+     * @remarks
+     * Ranges can be obtained from various API methods and then passed to other operations.
+     *
+     * **Examples:**
+     * - {@linkcode TextView.searchText} - Returns a range for a text match
+     * - {@linkcode TextView.setText} - Can be used to replace a given range
+     * - {@linkcode TextView.getPlainText} - Can be used to extract text at a specific range
+     * - {@linkcode TextView.setFormatting} - Can be used to apply formatting to a specific range
+     *
      * @sidebarGroup programmatic api
      */
     export type Range = {
+        /**
+         * @internal
+         */
         begin: number;
+        /**
+         * @internal
+         */
         end?: number;
     };
     /**
+     * Defines text formatting properties that can be applied to document content.
+     *
+     * @remarks
+     * The `Formatting` type specifies visual styling properties for text. All properties
+     * use `null` to represent "inherited from style".
+     *
+     * When applying formatting via e.g. {@linkcode TextView.setFormatting}, you typically use
+     * `Partial<Formatting>` to specify only the properties you want to change.
+     *
+     * @example
+     * Apply bold and color to text:
+     * ```typescript
+     * textView.setFormatting({
+     *   bold: true,
+     *   color: "#ff0000"
+     * });
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type Formatting = {
+        /**
+         * Font family name (e.g., "Arial", "Times New Roman").
+         *
+         * @remarks
+         * Specifies the typeface for the text.
+         * `null` means no explicit font is set (inherits from style).
+         */
         font: string | null;
+        /**
+         * Font size in points (e.g., 12, 14, 18).
+         *
+         * @remarks
+         * Specifies the size of the text in typographic points (1 point = 1/72 inch).
+         * Common sizes are 10-12 for body text, 14-18 for headings. `null` means no
+         * explicit size is set (inherits from style).
+         */
         fontSize: number | null;
+        /**
+         * Bold text weight.
+         *
+         * @remarks
+         * When `true`, text is rendered in bold weight. `false` or `null` means normal weight.
+         */
         bold: boolean | null;
+        /**
+         * Italic text style.
+         *
+         * @remarks
+         * When `true`, text is rendered in italic style. `false` or `null` means normal (upright) style.
+         */
         italic: boolean | null;
+        /**
+         * Text foreground color.
+         *
+         * @remarks
+         * Specifies the color of the text characters. Accepts hex color codes (e.g., "#ff0000" for red,
+         * "#0000ff" for blue). `null` means no explicit color is set (inherits from style).
+         */
         color: string | null;
+        /**
+         * Text background highlight color.
+         *
+         * @remarks
+         * Specifies the background color behind the text (like a highlighter pen). Accepts hex color
+         * codes (e.g., "#ffff00" for yellow, "#00ff00" for green). `null` means no highlight.
+         */
         highlight: string | null;
+        /**
+         * Strikethrough text decoration.
+         *
+         * @remarks
+         * When `true`, text is rendered with a horizontal line through the middle.
+         */
         strikeout: boolean | null;
+        /**
+         * Underline text decoration.
+         *
+         * @remarks
+         * When `true`, text is rendered with a line underneath.
+         */
         underline: boolean | null;
     };
     /**
+     * Pattern type for searching content in documents.
+     *
+     * @remarks
+     * `SearchFor` accepts either a string literal for exact matching or a regular expression
+     * for pattern-based matching. Used by search and replace operations throughout the API.
+     *
+     * **String literals:**
+     * - Performs case-sensitive exact substring matching
+     * - Finds the first occurrence of the exact string
+     *
+     * **Regular expressions:**
+     * - Supports full JavaScript RegExp syntax
+     * - Use flags for case-insensitive (`i`)
+     * - Word boundaries (`\b`), character classes, quantifiers, etc. are all supported
+     *
+     * @example
+     * String literal search (exact, case-sensitive):
+     * ```typescript
+     * // Find exact string "hello"
+     * const result = textView.searchText("hello");
+     * ```
+     *
+     * @example
+     * Case-insensitive word search:
+     * ```typescript
+     * // Find "hello" regardless of case, as a whole word
+     * const result = textView.searchText(/\bhello\b/i);
+     * ```
+     *
+     * @example
+     * Pattern matching with RegExp:
+     * ```typescript
+     * // Find all numbers
+     * draft.replaceText(/\d+/g, (match) => {
+     *   return `[${match}]`;
+     * });
+     *
+     * // Find words starting with capital letter
+     * const capitalWord = textView.searchText(/\b[A-Z][a-z]+\b/);
+     * ```
+     *
+     * @example
+     * Search and replace with different patterns:
+     * ```typescript
+     * // Replace exact string
+     * paragraph.replaceText("TODO", "DONE");
+     *
+     * // Replace using pattern
+     * paragraph.replaceText(/\bTODO\b/gi, "DONE");
+     *
+     * // Find dates in MM/DD/YYYY format
+     * const datePattern = /\b\d{2}\/\d{2}\/\d{4}\b/;
+     * paragraph.replaceText(datePattern, (match) => ({
+     *   text: match,
+     *   formatting: { bold: true, color: "#0000ff" }
+     * }));
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type SearchFor = string | RegExp;
     /**
+     * Specifies replacement content for text operations, including both text and formatting.
+     *
+     * @remarks
+     * `Replacement` is used with replace operations to specify what should replace the matched content.
+     *
+     * When used in {@linkcode ReplaceTextSignature} operations, if `text` is omitted, the original
+     * matched text is preserved and only formatting is modified.
+     *
+     * @example
+     * Replace formatting only (preserve text):
+     * ```typescript
+     * // Highlight all occurrences of "important" without changing text
+     * paragraph.replaceText(/important/gi, {
+     *   formatting: { highlight: "#ffff00", bold: true }
+     * });
+     * ```
+     *
+     * @example
+     * Dynamic replacement based on match (using with {@linkcode ReplaceFn}):
+     * ```typescript
+     * // Convert numbers to currency format with styling
+     * paragraph.replaceText(/\$?(\d+(\.\d{2})?)/g, (match) => {
+     *   const amount = parseFloat(match.replace('$', ''));
+     *   return {
+     *     text: `$${amount.toFixed(2)}`,
+     *     formatting: {
+     *       color: amount > 100 ? "#ff0000" : "#00ff00",
+     *       bold: amount > 100
+     *     }
+     *   };
+     * });
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type Replacement = {
+        /**
+         * The replacement text content.
+         *
+         * @remarks
+         * When specified, replaces the matched text with this string. When omitted,
+         * the original matched text is preserved (useful for formatting-only changes).
+         */
         text?: string;
+        /**
+         * Formatting to apply to the replacement text.
+         *
+         * @remarks
+         * Specifies formatting properties to apply.
+         */
         formatting?: Partial<Formatting>;
     };
     /**
+     * Callback function that dynamically generates replacement content based on matched text.
+     *
+     * @remarks
+     * `ReplaceFn` allows you to compute replacement content dynamically for each match found
+     * during a replace operation. The function receives the matched text as input and returns
+     * the replacment.
+     *
+     * This is particularly useful for:
+     * - Transforming matched text based on its content (e.g., converting to uppercase, parsing numbers)
+     * - Applying conditional formatting based on matched values
+     * - Implementing complex replacement logic that depends on the match
+     *
+     * @param value - The matched text string from the search pattern
+     * @returns Either a {@linkcode Replacement} object (for text and/or formatting changes) or a string (for simple text replacement)
+     *
+     * @example
+     * Transform matched text to uppercase:
+     * ```typescript
+     * // Convert all words in parentheses to uppercase
+     * paragraph.replaceText(/\((\w+)\)/g, (match) => {
+     *   return match.toUpperCase();
+     * });
+     * ```
+     *
+     * @example
+     * Apply conditional formatting based on content:
+     * ```typescript
+     * // Highlight TODO items in yellow, URGENT items in red
+     * draft.replaceText(/\b(TODO|URGENT)\b/g, (match) => {
+     *   return {
+     *     text: match,
+     *     formatting: {
+     *       highlight: match === "URGENT" ? "#ff0000" : "#ffff00",
+     *       bold: match === "URGENT"
+     *     }
+     *   };
+     * });
+     * ```
+     *
+     * @example
+     * Parse and transform numeric values:
+     * ```typescript
+     * // Double all numbers in the text
+     * paragraph.replaceText(/\d+/g, (match) => {
+     *   const num = parseInt(match);
+     *   return (num * 2).toString();
+     * });
+     * ```
      * @sidebarGroup programmatic api
      */
     export type ReplaceFn = (value: string) => Replacement | string;
@@ -1433,49 +1698,825 @@ export declare namespace Programmatic {
      */
     export type ReplacementOrReplaceFn = Replacement | ReplaceFn | string;
     /**
+     * Function signature for replacing text content within a document element.
+     *
+     * @remarks
+     * The `replaceText` method searches for all occurrences of a specified pattern and replaces them
+     * with new content. It can operate on various document elements including paragraphs, tables,
+     * sections, and the entire document body. The method processes all matches sequentially and
+     * returns the total number of replacements made.
+     *
+     * @param searchFor - The pattern to search for. Can be:
+     * - A string literal (case-sensitive, will match exact occurrences)
+     * - A RegExp for pattern matching (e.g., `/\bword\b/i` for case-insensitive word boundaries)
+     *
+     * @param replace - The replacement content. Can be:
+     * - A string: Simple text replacement
+     * - A {@linkcode Replacement} object: Replace text and/or apply formatting
+     * - A {@linkcode ReplaceFn} callback: Dynamic replacement based on matched text
+     *
+     * @returns The total number of replacements made
+     *
+     * @example Simple string replacement
+     * ```typescript
+     * // Replace all occurrences of "hello" with "goodbye"
+     * const count = paragraph.replaceText("hello", "goodbye");
+     * console.log(`Replaced ${count} occurrences`);
+     * ```
+     *
+     * @example Regular expression with formatting
+     * ```typescript
+     * // Find all "hi" and highlight them
+     * draft.replaceText(/\\bhi\\b/i, {
+     *   text: "REPLACED",
+     *   formatting: {
+     *     highlight: "#ff0000",
+     *     bold: true
+     *   }
+     * });
+     * ```
+     *
+     * @example Dynamic replacement with callback
+     * ```typescript
+     * // Convert all numbers to their doubled value
+     * draft.replaceText(/\d+/g, (match) => {
+     *   const num = parseInt(match);
+     *   return {
+     *     text: (num * 2).toString(),
+     *     formatting: { color: "#0000ff" }
+     *   };
+     * });
+     * ```
+     *
+     * @example Formatting-only changes (preserving original text)
+     * ```typescript
+     * // Highlight all occurrences of "important" without changing the text
+     * draft.replaceText(/important/i, (match) => ({
+     *   text: match, // Keep original text (preserves case)
+     *   formatting: { highlight: "#ffff00", bold: true }
+     * }));
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type ReplaceTextSignature = (searchFor: SearchFor, replace: ReplacementOrReplaceFn) => number;
     /**
+     * Represents a single match found by a search operation.
+     *
+     * @remarks
+     * `SearchResult` is returned by {@linkcode TextView.searchText} when a match is found. It contains
+     * both the matched text and a range, allowing you to inspect the match
+     * and perform further operations on it.
+     *
+     * The `range` property can be passed to other methods like {@linkcode TextView.setFormatting},
+     * {@linkcode TextView.setText}, or back to {@linkcode TextView.searchText} to continue searching
+     * after this match.
+     *
+     * When no match is found, `searchText` returns `undefined` instead of a `SearchResult`.
+     *
+     * @example
+     * Find and highlight the first occurrence:
+     * ```typescript
+     * const result = textView.searchText("important");
+     * if (result) {
+     *   console.log(`Found "${result.text}"`);
+     *   textView.setFormatting({ highlight: "#ffff00" }, result.range);
+     * }
+     * ```
+     *
+     * @example
+     * Double all numbers:
+     * ```typescript
+     * const searchFor = /\d+/i
+     * let result = textView.search(searchFor)
+     *
+     * while(result) {
+     *   const newRange = textView.replace(`${parseFloat(result.text)*2}`,result.range)
+     *   result = textView.search(searchFor,newRange)
+     * }
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type SearchResult = {
+        /**
+         * The location of the matched text within the document.
+         *
+         * @remarks
+         * An opaque {@linkcode Range} object identifying where the match was found. This range
+         * can be used with other TextView methods to manipulate the matched text, or passed
+         * back to {@linkcode TextView.searchText} to continue searching after this match.
+         */
         range: Range;
+        /**
+         * The matched text content.
+         *
+         * @remarks
+         * The actual text string that was matched by the search pattern. For string searches,
+         * this is identical to the search string. For RegExp searches, this is the text that
+         * matched the pattern.
+         */
         text: string;
     };
     /**
+     * Provides methods for reading and manipulating text content within a paragraph.
+     *
+     * @remarks
+     * `TextView` is the primary interface for working with text content in paragraphs. It provides
+     * comprehensive text manipulation capabilities including:
+     * - Reading plain text ({@linkcode getPlainText})
+     * - Searching for patterns ({@linkcode searchText})
+     * - Replacing text with formatting ({@linkcode replaceText})
+     * - Setting or replacing text content ({@linkcode setText})
+     * - Applying formatting to existing text ({@linkcode setFormatting})
+     * - Accessing inline elements like text runs, images, line breaks ({@linkcode inlines})
+     * - Adding new inline elements
+     *
+     * You obtain a `TextView` by calling {@linkcode Paragraph.asTextView} on a paragraph object.
+     *
+     * @example
+     * Basic text operations:
+     * ```typescript
+     * const textView = paragraph.asTextView();
+     *
+     * // Read text
+     * const text = textView.getPlainText();
+     * console.log('Paragraph text:', text);
+     *
+     * // Replace text
+     * textView.setText('New paragraph content');
+     *
+     * // Apply formatting
+     * textView.setFormatting({ bold: true, fontSize: 14 });
+     * ```
+     *
+     * @example
+     * Search and replace operations:
+     * ```typescript
+     * const textView = paragraph.asTextView();
+     *
+     * // Find first occurrence
+     * const result = textView.searchText(/important/i);
+     * if (result) {
+     *   console.log(`Found "${result.text}" at range`);
+     *   textView.setFormatting({ highlight: '#ffff00' }, result.range);
+     * }
+     *
+     * // Replace all occurrences
+     * const count = textView.replaceText(/TODO/g, {
+     *   text: 'DONE',
+     *   formatting: { color: '#00ff00' }
+     * });
+     * console.log(`Replaced ${count} occurrences`);
+     * ```
+     *
+     * @example
+     * Working with inline elements:
+     * ```typescript
+     * const textView = paragraph.asTextView();
+     *
+     * // Get all inline elements
+     * const inlines = textView.inlines();
+     *
+     * // Find text and images
+     * for (const rangeInline of inlines) {
+     *   if (rangeInline.inline.type === 'text') {
+     *     console.log('Text:', rangeInline.inline.plainText());
+     *   } else if (rangeInline.inline.type === 'image') {
+     *     const extent = rangeInline.inline.extent();
+     *     console.log(`Image: ${extent.width}x${extent.height}`);
+     *   }
+     * }
+     *
+     * // Add new content
+     * textView.addInlineText(' (added text)');
+     * textView.addLineBreak();
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type TextView = {
+        /**
+         * Extracts the plain text content without formatting.
+         *
+         * @param range - Optional range to extract text from. If omitted, returns all text.
+         * @returns The plain text string
+         *
+         * @remarks
+         * Returns the text content as a plain string, stripping out all formatting, images, and
+         * other inline elements. Line breaks within the paragraph are preserved as newline characters.
+         *
+         * When a range is provided, only the text within that range is returned. Ranges are typically
+         * obtained from search operations ({@linkcode searchText}) or other API methods.
+         *
+         * @example
+         * Get all text from a paragraph:
+         * ```typescript
+         * const textView = paragraph.asTextView();
+         * const text = textView.getPlainText();
+         * console.log('Full text:', text);
+         * ```
+         *
+         * @example
+         * Get text from a specific range:
+         * ```typescript
+         * const result = textView.searchText('important');
+         * if (result) {
+         *   const matchedText = textView.getPlainText(result.range);
+         *   console.log('Matched text:', matchedText); // "important"
+         * }
+         * ```
+         */
         getPlainText(range?: Range): string;
+        /**
+         * Searches for the first occurrence of a pattern.
+         *
+         * @param searchFor - The pattern to search for (string or RegExp)
+         * @param after - Optional range to start searching after. If omitted, searches from the beginning.
+         * @returns A {@linkcode SearchResult} if found, or `undefined` if no match exists
+         *
+         * @remarks
+         * Searches for the first occurrence of the specified pattern within the text view. Returns
+         * a {@linkcode SearchResult} containing both the matched text and its location as a {@linkcode Range}.
+         *
+         * The `after` parameter allows you to search iteratively by passing the range from a previous
+         * match, enabling you to find subsequent occurrences. This is useful for implementing custom
+         * find-next functionality.
+         *
+         * Unlike {@linkcode replaceText}, this method only finds the first occurrence (or the first
+         * occurrence after the specified range). Use this when you need to:
+         * - Check if a pattern exists
+         * - Get the location of a match for further processing
+         * - Iterate through matches manually with custom logic
+         *
+         * @example
+         * Find first occurrence:
+         * ```typescript
+         * const result = textView.searchText('hello');
+         * if (result) {
+         *   console.log(`Found "${result.text}"`);
+         *   // Apply formatting to the match
+         *   textView.setFormatting({ bold: true }, result.range);
+         * } else {
+         *   console.log('Pattern not found');
+         * }
+         * ```
+         *
+         * @example
+         * Iterate through all matches:
+         * ```typescript
+         * const pattern = /TODO/gi;
+         * let result = textView.searchText(pattern);
+         * let count = 0;
+         *
+         * while (result) {
+         *   count++;
+         *   console.log(`Match ${count}: "${result.text}"`);
+         *   // Highlight each match
+         *   textView.setFormatting({ highlight: '#ffff00' }, result.range);
+         *   // Search for next occurrence after this one
+         *   result = textView.searchText(pattern, result.range);
+         * }
+         * console.log(`Found ${count} matches`);
+         * ```
+         *
+         * @example
+         * Case-insensitive search:
+         * ```typescript
+         * const result = textView.searchText(/error/i);
+         * if (result) {
+         *   // Matches "error", "Error", "ERROR", etc.
+         *   textView.setFormatting({ color: '#ff0000' }, result.range);
+         * }
+         * ```
+         */
         searchText(searchFor: SearchFor, after?: Range): SearchResult | undefined;
+        /**
+         * Replaces all occurrences of a pattern with new content.
+         *
+         * @remarks
+         * Searches for all matches of the pattern within this text view and replaces them with
+         * the specified content. The replacement can be a simple string, a {@linkcode Replacement}
+         * object with text and formatting, or a {@linkcode ReplaceFn} callback for dynamic replacements.
+         *
+         * Returns the total number of replacements made, which is useful for confirming the
+         * operation succeeded and for logging/reporting purposes.
+         *
+         * See {@linkcode ReplaceTextSignature} for complete documentation, parameters, and examples.
+         *
+         * @example
+         * Simple text replacement:
+         * ```typescript
+         * const count = textView.replaceText('old', 'new');
+         * console.log(`Replaced ${count} occurrences`);
+         * ```
+         *
+         * @example
+         * Replace with formatting:
+         * ```typescript
+         * textView.replaceText(/ERROR/gi, {
+         *   text: 'ERROR',
+         *   formatting: { color: '#ff0000', bold: true }
+         * });
+         * ```
+         *
+         * @example
+         * Dynamic replacement with callback:
+         * ```typescript
+         * textView.replaceText(/\d+/g, (match) => {
+         *   const num = parseInt(match);
+         *   return (num * 2).toString();
+         * });
+         * ```
+         */
         replaceText: ReplaceTextSignature;
+        /**
+         * Sets or replaces text content within the text view.
+         *
+         * @param value - The new text content to insert
+         * @param range - Optional range to replace. If omitted, replaces all content.
+         * @returns A {@linkcode Range} representing the location of the newly inserted text
+         *
+         * @remarks
+         * Inserts or replaces text content. When no range is specified, this replaces all
+         * existing content in the text view with the new value. When a range is provided,
+         * only the content within that range is replaced.
+         *
+         * The returned range represents the location of the newly inserted text, which can
+         * be used for subsequent operations like applying formatting or further modifications.
+         *
+         * **Important:** This method replaces text but does not apply formatting. To apply
+         * formatting, use {@linkcode setFormatting} with the returned range, or use
+         * {@linkcode replaceText} to replace with both text and formatting in one operation.
+         *
+         * @example
+         * Replace all content:
+         * ```typescript
+         * const textView = paragraph.asTextView();
+         * const newRange = textView.setText('This is new content');
+         *
+         * // Apply formatting to the new text
+         * textView.setFormatting({ bold: true, fontSize: 14 }, newRange);
+         * ```
+         *
+         * @example
+         * Replace text at a specific range:
+         * ```typescript
+         * const result = textView.searchText('hello');
+         * if (result) {
+         *   // Replace "hello" with "goodbye"
+         *   const newRange = textView.setText('goodbye', result.range);
+         *   textView.setFormatting({ italic: true }, newRange);
+         * }
+         * ```
+         *
+         * @example
+         * Build up content with multiple insertions:
+         * ```typescript
+         * const textView = paragraph.asTextView();
+         *
+         * // Start with empty content
+         * textView.setText('');
+         *
+         * // Add content at the beginning
+         * const range1 = textView.setText('First sentence. ');
+         * textView.setFormatting({ bold: true }, range1);
+         *
+         * // Add more content
+         * const range2 = textView.setText('Second sentence. ');
+         * textView.setFormatting({ italic: true }, range2);
+         * ```
+         */
         setText(value: string, range?: Range): Range;
+        /**
+         * Applies formatting to text content.
+         *
+         * @param formatting - Partial formatting properties to apply
+         * @param range - Optional range to apply formatting to. If omitted, formats all content.
+         *
+         * @remarks
+         * Applies the specified formatting properties to text within the text view. Only the
+         * properties included in the `formatting` parameter are modified; other formatting
+         * properties remain unchanged.
+         *
+         * When no range is specified, formatting is applied to all content in the text view.
+         * When a range is provided, only the content within that range is formatted. Ranges
+         * are typically obtained from {@linkcode searchText} or {@linkcode setText}.
+         *
+         * **Note:** This method modifies formatting but does not change the text content itself.
+         * To change both text and formatting simultaneously, use {@linkcode replaceText}.
+         *
+         * @example
+         * Format entire paragraph:
+         * ```typescript
+         * const textView = paragraph.asTextView();
+         * textView.setFormatting({
+         *   font: 'Arial',
+         *   fontSize: 12,
+         *   bold: true
+         * });
+         * ```
+         *
+         * @example
+         * Format specific text found by search:
+         * ```typescript
+         * const result = textView.searchText(/important/i);
+         * if (result) {
+         *   textView.setFormatting({
+         *     highlight: '#ffff00',
+         *     bold: true
+         *   }, result.range);
+         * }
+         * ```
+         *
+         * @example
+         * Format newly inserted text:
+         * ```typescript
+         * const newRange = textView.setText('New heading');
+         * textView.setFormatting({
+         *   fontSize: 18,
+         *   bold: true,
+         *   color: '#0000ff'
+         * }, newRange);
+         * ```
+         *
+         * @example
+         * Apply partial formatting (only change color):
+         * ```typescript
+         * // Only change color, preserve all other formatting
+         * textView.setFormatting({ color: '#ff0000' });
+         * ```
+         */
         setFormatting(formatting: Partial<Formatting>, range?: Range): void;
+        /**
+         * Gets all inline elements within the text view.
+         *
+         * @returns An array of {@linkcode RangeInline} objects, each containing an inline element and its range
+         *
+         * @remarks
+         * Returns all inline elements (text runs, images, line breaks, footnotes, etc.) within
+         * the text view. Each element is paired with its location ({@linkcode Range}) in a
+         * {@linkcode RangeInline} object.
+         *
+         * The returned array preserves document order. Text content is split into multiple
+         * {@linkcode InlineText} elements whenever formatting changes. Other inline types include:
+         * - `'text'` - Text with consistent formatting ({@linkcode InlineText})
+         * - `'image'` - Embedded images ({@linkcode Image})
+         * - `'line-break'` - Soft line breaks ({@linkcode LineBreak})
+         * - `'page-break'` - Page breaks ({@linkcode PageBreak})
+         * - `'footnote'` - Footnote markers ({@linkcode Footnote})
+         * - `'endnote'` - Endnote markers ({@linkcode Endnote})
+         * - `'tab'` - Tab characters ({@linkcode Tab})
+         * - And more (see {@linkcode Inline})
+         *
+         * Use the `type` property on each inline element to discriminate and access type-specific
+         * methods and properties.
+         *
+         * @example
+         * List all inline elements:
+         * ```typescript
+         * const inlines = textView.inlines();
+         *
+         * for (const rangeInline of inlines) {
+         *   const { inline, range } = rangeInline;
+         *
+         *   if (inline.type === 'text') {
+         *     const text = inline.plainText();
+         *     const fmt = inline.formatting();
+         *     console.log(`Text: "${text}", Bold: ${fmt.bold}`);
+         *   } else if (inline.type === 'image') {
+         *     const extent = inline.extent();
+         *     console.log(`Image: ${extent.width}x${extent.height}`);
+         *   } else if (inline.type === 'line-break') {
+         *     console.log('Line break');
+         *   }
+         * }
+         * ```
+         *
+         * @example
+         * Find and resize all images:
+         * ```typescript
+         * const inlines = textView.inlines();
+         *
+         * for (const rangeInline of inlines) {
+         *   if (rangeInline.inline.type === 'image') {
+         *     const image = rangeInline.inline;
+         *     const current = image.extent();
+         *
+         *     // Scale to 50%
+         *     image.setExtent({
+         *       width: current.width * 0.5,
+         *       height: current.height * 0.5
+         *     });
+         *   }
+         * }
+         * ```
+         *
+         * @example
+         * Extract and format all text runs:
+         * ```typescript
+         * const inlines = textView.inlines();
+         *
+         * for (const rangeInline of inlines) {
+         *   if (rangeInline.inline.type === 'text') {
+         *     const text = rangeInline.inline.plainText();
+         *     if (text.includes('TODO')) {
+         *       // Highlight TODOs
+         *       textView.setFormatting({ highlight: '#ffff00' }, rangeInline.range);
+         *     }
+         *   }
+         * }
+         * ```
+         *
+         * @example
+         * Access footnote content:
+         * ```typescript
+         * const inlines = textView.inlines();
+         *
+         * for (const rangeInline of inlines) {
+         *   if (rangeInline.inline.type === 'footnote') {
+         *     const footnote = rangeInline.inline;
+         *     const content = footnote.content();
+         *     const paragraphs = content.blocklevels();
+         *     console.log(`Footnote has ${paragraphs.length} paragraphs`);
+         *   }
+         * }
+         * ```
+         */
         inlines(): RangeInline[];
-        addLineBreak(insertionPoint?: {
+        /**
+         * Adds new inline text at a specific position.
+         *
+         * @param text - The text content to add
+         * @param insertionPoint - Optional position to insert. If omitted, appends to the end.
+         * @returns A {@linkcode Range} representing the location of the newly inserted text
+         *
+         * @remarks
+         * Inserts new text content at the specified position without replacing existing content.
+         * When no insertion point is provided, the text is appended to the end.
+         *
+         * The `insertionPoint` parameter specifies both a reference range and a placement
+         * relative to that range:
+         * - `placement: 'before'` - Insert before the reference range
+         * - `placement: 'after'` - Insert after the reference range
+         *
+         * The returned range represents the location of the newly inserted text, which can
+         * be used for subsequent operations like applying formatting.
+         *
+         * **Note:** The newly inserted text inherits formatting from its context. To apply
+         * specific formatting, use {@linkcode setFormatting} with the returned range.
+         *
+         * @example
+         * Append text to the end:
+         * ```typescript
+         * const newRange = textView.addInlineText(' (additional text)');
+         * textView.setFormatting({ italic: true }, newRange);
+         * ```
+         *
+         * @example
+         * Insert before specific text:
+         * ```typescript
+         * const result = textView.searchText('important');
+         * if (result) {
+         *   const newRange = textView.addInlineText('VERY ', {
+         *     placement: 'before',
+         *     range: result.range
+         *   });
+         *   textView.setFormatting({ bold: true }, newRange);
+         * }
+         * // Result: "VERY important"
+         * ```
+         *
+         * @example
+         * Insert after specific text:
+         * ```typescript
+         * const result = textView.searchText(/chapter \d+/i);
+         * if (result) {
+         *   const newRange = textView.addInlineText(' (revised)', {
+         *     placement: 'after',
+         *     range: result.range
+         *   });
+         *   textView.setFormatting({ fontSize: 10 }, newRange);
+         * }
+         * // Result: "Chapter 5 (revised)"
+         * ```
+         *
+         * @example
+         * Build content with multiple insertions:
+         * ```typescript
+         * const textView = paragraph.asTextView();
+         * textView.setText('');
+         *
+         * let lastRange = textView.addInlineText('First');
+         * textView.setFormatting({ bold: true }, lastRange);
+         *
+         * lastRange = textView.addInlineText(', Second', {
+         *   placement: 'after',
+         *   range: lastRange
+         * });
+         * textView.setFormatting({ italic: true }, lastRange);
+         *
+         * // Result: "First, Second" (First is bold, Second is italic)
+         * ```
+         */
+        addInlineText(text: string, insertionPoint?: {
             placement: 'before' | 'after';
             range: Range;
-        }): LineBreak;
-        addInlineText(text: string, insertionPoint?: {
+        }): Range;
+        /**
+         * Adds a line break (soft return) at a specific position.
+         *
+         * @param insertionPoint - Optional position to insert. If omitted, appends to the end.
+         * @returns A {@linkcode Range} representing the location of the newly inserted line break
+         *
+         * @remarks
+         * Inserts a line break (also called a soft return) at the specified position. Line breaks
+         * create a new line within the same paragraph without starting a new paragraph. This is
+         * equivalent to pressing Shift+Enter in most word processors.
+         *
+         * When no insertion point is provided, the line break is appended to the end of the
+         * text view content.
+         *
+         * The `insertionPoint` parameter specifies both a reference range and a placement
+         * relative to that range:
+         * - `placement: 'before'` - Insert before the reference range
+         * - `placement: 'after'` - Insert after the reference range
+         *
+         * The returned range represents the location of the line break, which can be used
+         * for further operations if needed.
+         *
+         * **Use cases:**
+         * - Multi-line addresses within a single paragraph
+         * - Poetry or verse formatting
+         * - Breaking text within list items or table cells
+         * - Any scenario where visual line separation is needed without semantic paragraph breaks
+         *
+         * @example
+         * Add line break at the end:
+         * ```typescript
+         * const textView = paragraph.asTextView();
+         * textView.setText('First line');
+         * textView.addLineBreak();
+         * textView.addInlineText('Second line');
+         * // Result:
+         * // First line
+         * // Second line
+         * // (in same paragraph)
+         * ```
+         *
+         * @example
+         * Insert line break at specific position:
+         * ```typescript
+         * const result = textView.searchText(/\d{5}/); // Find ZIP code
+         * if (result) {
+         *   textView.addLineBreak({
+         *     placement: 'before',
+         *     range: result.range
+         *   });
+         * }
+         * // Result:
+         * // 123 Main St
+         * // 12345
+         * ```
+         *
+         * @example
+         * Format a multi-line address:
+         * ```typescript
+         * const textView = paragraph.asTextView();
+         * textView.setText('John Smith');
+         * textView.addLineBreak();
+         * textView.addInlineText('123 Main Street');
+         * textView.addLineBreak();
+         * textView.addInlineText('Springfield, IL 62701');
+         *
+         * // All in one paragraph:
+         * // John Smith
+         * // 123 Main Street
+         * // Springfield, IL 62701
+         * ```
+         *
+         * @example
+         * Poetry formatting:
+         * ```typescript
+         * const textView = paragraph.asTextView();
+         * textView.setText('Roses are red,');
+         * textView.addLineBreak();
+         * textView.addInlineText('Violets are blue,');
+         * textView.addLineBreak();
+         * textView.addInlineText('Programming is great,');
+         * textView.addLineBreak();
+         * textView.addInlineText('And so are you!');
+         * ```
+         */
+        addLineBreak(insertionPoint?: {
             placement: 'before' | 'after';
             range: Range;
-        }): InlineText;
-        removeInline(index?: number): Inline | undefined;
+        }): Range;
     };
     /**
-     * @sidebarGroup programmatic api
-     */
-    export type Extent = {
-        width: number;
-        height: number;
+     * Represents the dimensions (width and height) of a document element.
+     *
+     * @remarks
+     * `Extent` specifies the size of elements like images in the document. Dimensions are
+     * measured in points (1 point = 1/72 inch).
+     *
+     * @example
+     * Get image dimensions:
+     * ```typescript
+     * const inlines = textView.inlines();
+     * for (const rangeInline of inlines) {
+     *   if (rangeInline.inline.type === 'image') {
+     *     const extent = rangeInline.inline.extent();
+     *     console.log(`Image size: ${extent.width} x ${extent.height}`);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * Scale image proportionally:
+     * ```typescript
+     * const inlines = textView.inlines();
+     * for (const rangeInline of inlines) {
+     *   if (rangeInline.inline.type === 'image') {
+     *     const current = rangeInline.inline.extent();
+     *     const scale = 0.5; // Scale to 50%
+     *
+     *     rangeInline.inline.setExtent({
+     *       width: current.width * scale,
+     *       height: current.height * scale
+     *     });
+     *   }
+     * }
+     * ```
+     *
+     * @sidebarGroup programmatic api
+     */
+    export type Extent = {
+        /**
+         * The width of the element.
+         *
+         * @remarks
+         * Width dimension. Measured in points (1 point = 1/72 inch).
+         */
+        width: number;
+        /**
+         * The height of the element.
+         *
+         * @remarks
+         * Height dimension. Measured in points (1 point = 1/72 inch).
+         */
+        height: number;
     };
     /**
+     * Represents an image element within a document.
+     *
+     * @remarks
+     * `Image` is one of the inline element types that can appear within text content. Images
+     * are embedded within paragraphs alongside text and other inline elements. You obtain
+     * `Image` objects by iterating through inline elements and checking their type discriminator.
+     *
      * @sidebarGroup programmatic api
      */
     export type Image = {
+        /**
+         * Type discriminator for inline elements.
+         *
+         * @remarks
+         * Always has the value `'image'`. Use this property to narrow the inline element
+         * type and access image-specific methods.
+         */
         type: 'image';
+        /**
+         * Gets the current display dimensions of the image.
+         *
+         * @returns An {@linkcode Extent} object containing the image's width and height
+         *
+         * @remarks
+         * Returns the current display size of the image in the document. Dimensions are
+         * in points (1 point = 1/72 inch).
+         *
+         * @example
+         * ```typescript
+         * if (inline.type === 'image') {
+         *   const extent = inline.extent();
+         *   console.log(`Image: ${extent.width} x ${extent.height}`);
+         * }
+         * ```
+         */
         extent(): Extent;
+        /**
+         * Sets the display dimensions of the image. Dimensions are
+         * in points (1 point = 1/72 inch).
+         *
+         * @param extent - Partial extent object with width and/or height to set
+         *
+         * @remarks
+         * Modifies how the image is displayed in the document. You can specify both width
+         * and height, or just one dimension. When specifying only one dimension, the other
+         * remains unchanged (it does NOT maintain aspect ratio automatically).
+         *
+         * This modifies only the display size, not the underlying image data.
+         */
         setExtent(extent: Partial<Extent>): void;
     };
     /**
@@ -1485,39 +2526,236 @@ export declare namespace Programmatic {
         type: 'field';
     };
     /**
+     * Represents a footnote element within document content.
+     *
+     * @remarks
+     * `Footnote` is an inline element that contains a footnote reference mark in the main text
+     * and associated content that appears at the bottom of the page.
+     * The footnote itself contains block-level content (paragraphs, tables) accessed via the
+     * `content()` method.
+     *
+     * Footnotes are discovered by iterating through inline elements and checking their type
+     * discriminator. Once you have a `Footnote` object, you can access and modify its content
+     * using the {@linkcode BlockLevelContainer} interface.
+     *
+     * @example
+     * Find and list all footnotes:
+     * ```typescript
+     * const inlines = textView.inlines();
+     * for (const rangeInline of inlines) {
+     *   if (rangeInline.inline.type === 'footnote') {
+     *     const footnoteContent = rangeInline.inline.content();
+     *     const text = footnoteContent.blocklevels()
+     *       .map(bl => bl.type === 'paragraph' ? bl.asTextView().getPlainText() : '')
+     *       .join(' ');
+     *     console.log('Footnote text:', text);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * Search and replace within footnote content:
+     * ```typescript
+     * for (const rangeInline of textView.inlines()) {
+     *   if (rangeInline.inline.type === 'footnote') {
+     *     const footnoteContent = rangeInline.inline.content();
+     *     // Replace text in all footnote content
+     *     const count = footnoteContent.replaceText(/TODO/g, 'DONE');
+     *     console.log(`Replaced ${count} occurrences in footnote`);
+     *   }
+     * }
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type Footnote = {
+        /**
+         * Type discriminator for inline elements.
+         *
+         * @remarks
+         * Always has the value `'footnote'`. Use this property to narrow the inline element
+         * type and access footnote-specific methods.
+         */
         type: 'footnote';
+        /**
+         * Gets the block-level content container for this footnote.
+         *
+         * @returns A {@linkcode BlockLevelContainer} containing the footnote's paragraphs and tables
+         *
+         * @remarks
+         * Returns a container that holds the actual content of the footnote (what appears at
+         * the bottom of the page). You can use this to read, modify, add, or remove content
+         * within the footnote using the standard {@linkcode BlockLevelContainer} methods.
+         *
+         * @example
+         * ```typescript
+         * if (inline.type === 'footnote') {
+         *   const content = inline.content();
+         *   const paragraphs = content.blocklevels();
+         *   console.log(`Footnote has ${paragraphs.length} paragraphs`);
+         * }
+         * ```
+         */
+        content(): BlockLevelContainer;
     };
     /**
+     * Represents a reference to a footnote within footnote content.
+     *
+     * @remarks
+     * `FootnoteRef` is an inline element that appears within the content of a footnote itself,
+     * representing a reference back to where the footnote is cited in the main text. This is
+     * typically rendered as a superscript number or symbol at the beginning of the footnote text.
+     *
+     * Unlike {@linkcode Footnote} (which is the footnote marker in the main text with its associated
+     * content), `FootnoteRef` appears inside the footnote content area and links back to the
+     * main text.
+     *
+     * This is a marker element with no additional methods or properties beyond the type discriminator.
+     *
      * @sidebarGroup programmatic api
      */
     export type FootnoteRef = {
+        /**
+         * Type discriminator for inline elements.
+         *
+         * @remarks
+         * Always has the value `'footnote/ref'`. Use this property to identify footnote
+         * reference markers within footnote content.
+         */
         type: 'footnote/ref';
     };
     /**
+     * Represents an endnote element within document content.
+     *
+     * @remarks
+     * `Endnote` is an inline element that contains an endnote reference mark in the main text
+     * and associated content that appears at the end of the document or section. Endnotes are
+     * similar to footnotes but collected at the end rather than at the bottom of each page.
+     *
+     * The endnote contains block-level content (paragraphs, tables) accessed via the `content()`
+     * method. Endnotes are discovered by iterating through inline elements and checking their
+     * type discriminator.
+
+     * @example
+     * Find and list all endnotes:
+     * ```typescript
+     * const inlines = textView.inlines();
+     * for (const rangeInline of inlines) {
+     *   if (rangeInline.inline.type === 'endnote') {
+     *     const endnoteContent = rangeInline.inline.content();
+     *     const text = endnoteContent.blocklevels()
+     *       .map(bl => bl.type === 'paragraph' ? bl.asTextView().getPlainText() : '')
+     *       .join(' ');
+     *     console.log('Endnote text:', text);
+     *   }
+     * }
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type Endnote = {
+        /**
+         * Type discriminator for inline elements.
+         *
+         * @remarks
+         * Always has the value `'endnote'`. Use this property to narrow the inline element
+         * type and access endnote-specific methods.
+         */
         type: 'endnote';
+        /**
+         * Gets the block-level content container for this endnote.
+         *
+         * @returns A {@linkcode BlockLevelContainer} containing the endnote's paragraphs and tables
+         *
+         * @remarks
+         * Returns a container that holds the actual content of the endnote (what appears at
+         * the end of the document or section). You can use this to read, modify, add, or remove
+         * content within the endnote using the standard {@linkcode BlockLevelContainer} methods.
+         *
+         * @example
+         * ```typescript
+         * if (inline.type === 'endnote') {
+         *   const content = inline.content();
+         *   const paragraphs = content.blocklevels();
+         *   console.log(`Endnote has ${paragraphs.length} paragraphs`);
+         * }
+         * ```
+         */
+        content(): BlockLevelContainer;
     };
     /**
+     * Represents a reference to an endnote within endnote content.
+     *
+     * @remarks
+     * `EndnoteRef` is an inline element that appears within the content of an endnote itself,
+     * representing a reference back to where the endnote is cited in the main text. This is
+     * typically rendered as a superscript number or symbol at the beginning of the endnote text.
+     *
+     * Unlike {@linkcode Endnote} (which is the endnote marker in the main text with its associated
+     * content), `EndnoteRef` appears inside the endnote content area and links back to the
+     * main text.
+     *
+     * This is a marker element with no additional methods or properties beyond the type discriminator.
+     *
      * @sidebarGroup programmatic api
      */
     export type EndnoteRef = {
+        /**
+         * Type discriminator for inline elements.
+         *
+         * @remarks
+         * Always has the value `'endnote/ref'`. Use this property to identify endnote
+         * reference markers within endnote content.
+         */
         type: 'endnote/ref';
     };
     /**
+     * Represents a line break (soft return) within a paragraph.
+     *
+     * @remarks
+     * `LineBreak` is an inline element that creates a new line within the same paragraph without
+     * starting a new paragraph. This is also known as a "soft return" or "line wrap" and is
+     * typically inserted with Shift+Enter in word processors.
+     *
+     * Unlike starting a new paragraph, a line break:
+     * - Keeps the text in the same paragraph
+     * - Maintains paragraph-level formatting and numbering
+     * - Creates visual line separation without semantic paragraph separation
+     *
+     * Line breaks can be added programmatically using {@linkcode TextView.addLineBreak}.
+     *
+     * @example
+     * Find all line breaks in a paragraph:
+     * ```typescript
+     * const inlines = textView.inlines();
+     * const lineBreaks = inlines.filter(ri => ri.inline.type === 'line-break');
+     * console.log(`Found ${lineBreaks.length} line breaks`);
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type LineBreak = {
+        /**
+         * Type discriminator for inline elements.
+         *
+         * @remarks
+         * Always has the value `'line-break'`. Use this property to identify line break
+         * elements within text content.
+         */
         type: 'line-break';
     };
     /**
+     *
      * @sidebarGroup programmatic api
      */
     export type PageBreak = {
+        /**
+         * Type discriminator for inline elements.
+         *
+         * @remarks
+         * Always has the value `'page-break'`. Use this property to identify page break
+         * elements within text content.
+         */
         type: 'page-break';
     };
     /**
@@ -1533,11 +2771,84 @@ export declare namespace Programmatic {
         type: 'sep';
     };
     /**
+     * Represents a text segment with consistent formatting within a paragraph.
+     *
+     * @remarks
+     * `InlineText` is the most common inline element type, representing actual text content
+     * with uniform formatting properties. A paragraph's text is broken into multiple `InlineText`
+     * elements whenever formatting changes (e.g., switching from regular to bold text creates
+     * two separate `InlineText` elements).
+     *
+     * Each `InlineText` element has:
+     * - The actual text content (via {@linkcode plainText})
+     * - The formatting applied to that text (via {@linkcode formatting})
+     *
+     * `InlineText` elements are discovered by iterating through inline elements using
+     * {@linkcode TextView.inlines}.
+     *
+     * @example
+     * Extract all text content with formatting information:
+     * ```typescript
+     * const inlines = textView.inlines();
+     * for (const rangeInline of inlines) {
+     *   if (rangeInline.inline.type === 'text') {
+     *     const text = rangeInline.inline.plainText();
+     *     const fmt = rangeInline.inline.formatting();
+     *     console.log(`Text: "${text}", Bold: ${fmt.bold}, Color: ${fmt.color}`);
+     *   }
+     * }
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type InlineText = {
+        /**
+         * Type discriminator for inline elements.
+         *
+         * @remarks
+         * Always has the value `'text'`. Use this property to identify text content
+         * elements and distinguish them from other inline types (images, line breaks, etc.).
+         */
         type: 'text';
+        /**
+         * Gets the plain text content of this inline element.
+         *
+         * @returns The text string contained in this element
+         *
+         * @remarks
+         * Returns the actual text content without any formatting information. Each `InlineText`
+         * element represents a contiguous segment of text with uniform formatting.
+         *
+         * @example
+         * ```typescript
+         * if (inline.type === 'text') {
+         *   const text = inline.plainText();
+         *   console.log(`Text content: "${text}"`);
+         * }
+         * ```
+         */
         plainText(): string;
+        /**
+         * Gets the formatting properties applied to this text.
+         *
+         * @returns A {@linkcode Formatting} object describing all formatting properties
+         *
+         * @remarks
+         * Returns the complete formatting information for this text segment, including font,
+         * size, color, bold, italic, and other properties. Properties that are not explicitly
+         * set will have `null` values, indicating they inherit from the paragraph or document style.
+         *
+         * @example
+         * ```typescript
+         * if (inline.type === 'text') {
+         *   const fmt = inline.formatting();
+         *   console.log(`Font: ${fmt.font ?? 'default'}`);
+         *   console.log(`Size: ${fmt.fontSize ?? 'default'}`);
+         *   console.log(`Bold: ${fmt.bold ?? false}`);
+         *   console.log(`Color: ${fmt.color ?? 'default'}`);
+         * }
+         * ```
+         */
         formatting(): Formatting;
     };
     /**
@@ -1545,18 +2856,149 @@ export declare namespace Programmatic {
      */
     export type Inline = InlineText | Tab | Separator | LineBreak | PageBreak | Image | Field | Footnote | FootnoteRef | Endnote | EndnoteRef;
     /**
+     * Pairs an inline element with its location in the text view.
+     *
+     * @remarks
+     * `RangeInline` combines an inline element with the {@linkcode Range} indicating where it appears
+     * in the text view. This type is returned by {@linkcode TextView.inlines}, allowing you to both inspect
+     * inline elements and know their positions for further operations.
+     *
+     * The `range` property identifies the exact location of the inline element, which
+     * you can use with other TextView methods like {@linkcode TextView.setFormatting} or
+     * {@linkcode TextView.setText} to manipulate that specific range.
+     *
+     * This pairing is essential because:
+     * - You need the inline element to inspect its type and properties
+     * - You need the range to perform operations on that specific element
+     *
      * @sidebarGroup programmatic api
      */
     export type RangeInline = {
+        /**
+         * The location of the inline element within the text view.
+         *
+         * @remarks
+         * An opaque {@linkcode Range} object specifying where this inline element appears.
+         * This range can be passed to TextView methods to manipulate the element
+         * (e.g., {@linkcode TextView.setFormatting}).
+         */
         range: Range;
+        /**
+         * The inline element at this location.
+         *
+         * @remarks
+         * The actual inline element, which could be text, an image, a line break, or any
+         * other inline type. Use the `type` property to discriminate and access
+         * type-specific methods.
+         */
         inline: Inline;
     };
     /**
+     * Represents a paragraph block-level element within a document.
+     *
+     * @remarks
+     * `Paragraph` is one of the primary block-level elements in a document (along with {@linkcode Table}).
+     * It contains content like text, images, line breaks, and other elements.
+     *
+     * Paragraphs are obtained from:
+     * - {@linkcode BlockLevelContainer.blocklevels} - Get all block-level elements
+     * - {@linkcode BlockLevelContainer.addParagraph} - Create a new paragraph
+     *
+     * To work with paragraph content, use {@linkcode asTextView} to get a {@linkcode TextView} interface
+     * that provides methods for reading and manipulating the text and inline elements.
+     *
+     * @example
+     * Iterate through all paragraphs in a section:
+     * ```typescript
+     * const blockLevels = section.content().blocklevels();
+     * for (const bl of blockLevels) {
+     *   if (bl.type === 'paragraph') {
+     *     const textView = bl.asTextView();
+     *     const text = textView.getPlainText();
+     *     console.log('Paragraph text:', text);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * Add and populate a new paragraph:
+     * ```typescript
+     * const container = section.content();
+     * const newPara = container.addParagraph();
+     *
+     * // Set text content
+     * const textView = newPara.asTextView();
+     * textView.setText('This is a new paragraph.');
+     *
+     * // Apply formatting
+     * textView.setFormatting({ bold: true, fontSize: 14 });
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type Paragraph = {
+        /**
+         * Type discriminator for block-level elements.
+         *
+         * @remarks
+         * Always has the value `'paragraph'`. Use this property to narrow the block-level
+         * element type and access paragraph-specific methods.
+         */
         type: 'paragraph';
+        /**
+         * Gets a TextView interface for reading and manipulating the paragraph's content.
+         *
+         * @returns A {@linkcode TextView} that provides access to the paragraph's inline elements
+         *
+         * @remarks
+         * Returns a {@linkcode TextView} interface that exposes methods for working with the
+         * paragraph's text and inline elements. Use this to:
+         * - Read text content ({@linkcode TextView.getPlainText})
+         * - Search for text ({@linkcode TextView.searchText})
+         * - Modify text ({@linkcode TextView.setText})
+         * - Apply formatting ({@linkcode TextView.setFormatting})
+         * - Access inline elements ({@linkcode TextView.inlines})
+         *
+         * @example
+         * ```typescript
+         * if (blockLevel.type === 'paragraph') {
+         *   const textView = blockLevel.asTextView();
+         *   const text = textView.getPlainText();
+         *   console.log('Paragraph content:', text);
+         * }
+         * ```
+         */
         asTextView(): TextView;
+        /**
+         * Replaces all occurrences of a pattern with new content.
+         *
+         * @remarks
+         * Convenience method equivalent to calling {@linkcode TextView.replaceText} on the result
+         * of {@linkcode asTextView}. Searches for all matches of the pattern within this paragraph
+         * and replaces them with the specified content.
+         *
+         * See {@linkcode ReplaceTextSignature} for detailed parameter and usage information.
+         *
+         * @example
+         * ```typescript
+         * if (blockLevel.type === 'paragraph') {
+         *   // Replace all "TODO" with "DONE"
+         *   const count = blockLevel.replaceText(/TODO/g, 'DONE');
+         *   console.log(`Replaced ${count} occurrences`);
+         * }
+         * ```
+         *
+         * @example
+         * ```typescript
+         * if (blockLevel.type === 'paragraph') {
+         *   // Replace with formatting
+         *   blockLevel.replaceText(/ERROR/gi, {
+         *     text: 'ERROR',
+         *     formatting: { color: '#ff0000', bold: true }
+         *   });
+         * }
+         * ```
+         */
         replaceText: ReplaceTextSignature;
     };
     /**
@@ -1583,17 +3025,180 @@ export declare namespace Programmatic {
         replaceText: ReplaceTextSignature;
     };
     /**
+     * Union type representing the block-level elements that can appear in a document.
+     *
+     * @remarks
+     * `BlockLevel` is a discriminated union of {@linkcode Paragraph} and {@linkcode Table}, the two
+     * types of block-level elements that can exist within a document's content structure. Block-level
+     * elements are the primary building blocks of document content, appearing within:
+     * - Section content ({@linkcode Section.content})
+     * - Table cells ({@linkcode TableCell})
+     * - Footnote content ({@linkcode Footnote.content})
+     * - Endnote content ({@linkcode Endnote.content})
+     * - Headers and footers ({@linkcode HeaderFooter})
+     *
+     * Use the `type` discriminator property to determine which specific block-level element you're
+     * working with:
+     * - `type: 'paragraph'` - A {@linkcode Paragraph} element
+     * - `type: 'table'` - A {@linkcode Table} element
+     *
+     * Block-level elements are obtained from {@linkcode BlockLevelContainer.blocklevels}, which returns
+     * an array of `BlockLevel` elements that you can iterate through and process based on their type.
+     *
+     * @example
+     * Iterate through and process block-level elements:
+     * ```typescript
+     * const content = section.content();
+     * const blockLevels = content.blocklevels();
+     *
+     * for (const blockLevel of blockLevels) {
+     *   if (blockLevel.type === 'paragraph') {
+     *     // It's a paragraph
+     *     const textView = blockLevel.asTextView();
+     *     const text = textView.getPlainText();
+     *     console.log('Paragraph:', text);
+     *   } else if (blockLevel.type === 'table') {
+     *     // It's a table
+     *     const rows = blockLevel.rows();
+     *     console.log(`Table with ${rows.length} rows`);
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * Count paragraphs and tables in a section:
+     * ```typescript
+     * const blockLevels = section.content().blocklevels();
+     *
+     * let paragraphCount = 0;
+     * let tableCount = 0;
+     *
+     * for (const bl of blockLevels) {
+     *   if (bl.type === 'paragraph') {
+     *     paragraphCount++;
+     *   } else if (bl.type === 'table') {
+     *     tableCount++;
+     *   }
+     * }
+     *
+     * console.log(`Section has ${paragraphCount} paragraphs and ${tableCount} tables`);
+     * ```
+     *
+     * @example
+     * Process only paragraphs with specific text:
+     * ```typescript
+     * const blockLevels = section.content().blocklevels();
+     *
+     * for (const bl of blockLevels) {
+     *   if (bl.type === 'paragraph') {
+     *     const text = bl.asTextView().getPlainText();
+     *     if (text.includes('TODO')) {
+     *       // Highlight TODOs in red
+     *       bl.replaceText(/TODO/g, {
+     *         text: 'TODO',
+     *         formatting: { color: '#ff0000', bold: true }
+     *       });
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * Find the first table in a section:
+     * ```typescript
+     * const blockLevels = section.content().blocklevels();
+     * const firstTable = blockLevels.find(bl => bl.type === 'table');
+     *
+     * if (firstTable && firstTable.type === 'table') {
+     *   // TypeScript knows this is a Table due to type narrowing
+     *   const rows = firstTable.rows();
+     *   console.log(`First table has ${rows.length} rows`);
+     * } else {
+     *   console.log('No tables found');
+     * }
+     * ```
+     *
+     * @example
+     * Extract all text from both paragraphs and tables:
+     * ```typescript
+     * const blockLevels = section.content().blocklevels();
+     * const allText: string[] = [];
+     *
+     * for (const bl of blockLevels) {
+     *   if (bl.type === 'paragraph') {
+     *     const text = bl.asTextView().getPlainText();
+     *     allText.push(text);
+     *   } else if (bl.type === 'table') {
+     *     // Extract text from all cells in the table
+     *     for (const row of bl.rows()) {
+     *       for (const cell of row.cells()) {
+     *         const cellBlocks = cell.blocklevels();
+     *         for (const cellBl of cellBlocks) {
+     *           if (cellBl.type === 'paragraph') {
+     *             const text = cellBl.asTextView().getPlainText();
+     *             allText.push(text);
+     *           }
+     *         }
+     *       }
+     *     }
+     *   }
+     * }
+     *
+     * console.log('All text:', allText.join('\n'));
+     * ```
+     *
+     * @example
+     * Replace text across all block-level elements:
+     * ```typescript
+     * const blockLevels = section.content().blocklevels();
+     * let totalReplacements = 0;
+     *
+     * for (const bl of blockLevels) {
+     *   // Both Paragraph and Table have replaceText method
+     *   const count = bl.replaceText(/old/g, 'new');
+     *   totalReplacements += count;
+     * }
+     *
+     * console.log(`Replaced ${totalReplacements} occurrences`);
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type BlockLevel = Paragraph | Table;
     /**
+     * Container for block-level elements (paragraphs and tables).
+     *
+     * @remarks
+     * `BlockLevelContainer` is implemented by {@linkcode Body} and {@linkcode TableCell}, providing
+     * methods to manage block-level content within these containers.
+     *
+     * @example
+     * Adding paragraphs and tables:
+     * ```typescript
+     * const body = draft.body();
+     * const paragraph = body.addParagraph(); // Append paragraph at end
+     * const table = body.addTable(0);    // Insert table at start
+     * ```
+     *
+     * @example
+     * Accessing and removing elements:
+     * ```typescript
+     * const elements = body.blocklevels();
+     * const removed = body.removeElement(0);
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type BlockLevelContainer = {
+        /** Returns all block-level elements in this container. */
         blocklevels(): BlockLevel[];
+        /** Adds a new paragraph. If `index` is provided, inserts at that position; otherwise appends to the end. */
         addParagraph(index?: number): Paragraph;
+        /** Adds a new table. If `index` is provided, inserts at that position; otherwise appends to the end. */
         addTable(index?: number): Table;
+        /** Removes the element at the specified index. Returns the removed element, or `undefined` if index is out of bounds. */
         removeElement(index: number): BlockLevel | undefined;
+        /** Searches and replaces text within this container. See {@linkcode ReplaceTextSignature}. */
         replaceText: ReplaceTextSignature;
     };
     /**
@@ -1604,21 +3209,158 @@ export declare namespace Programmatic {
         height: number;
     };
     /**
+     * Defines the margin dimensions for all four edges of a page.
+     *
+     * @remarks
+     * `PageMargins` specifies the whitespace between the page edges and the content area for
+     * a section. All margin values are measured in points (1 point = 1/72 inch).
+     *
+     * Page margins are configured through {@linkcode PageSetup.setPageMargins} and retrieved
+     * via {@linkcode PageSetup.pageMargins}. Each section can have its own margin settings,
+     * allowing different parts of a document to have different layouts.
+     *
+     * **Common margin values:**
+     * - **Normal margins** (US Letter): 72 points (1 inch) on all sides
+     * - **Narrow margins**: 36 points (0.5 inch) on all sides
+     * - **Wide margins**: 144 points (2 inches) on all sides
+     *
+     * @example
+     * Get current margins:
+     * ```typescript
+     * const pageSetup = section.pageSetup();
+     * const margins = pageSetup.pageMargins();
+     *
+     * console.log(`Top: ${margins.top}pt`);
+     * console.log(`Bottom: ${margins.bottom}pt`);
+     * console.log(`Left: ${margins.left}pt`);
+     * console.log(`Right: ${margins.right}pt`);
+     * ```
+     *
+     * @example
+     * Set standard 1-inch margins:
+     * ```typescript
+     * const pageSetup = section.pageSetup();
+     * pageSetup.setPageMargins({
+     *   top: 72,
+     *   bottom: 72,
+     *   left: 72,
+     *   right: 72
+     * });
+     * ```
+     *
+     * @example
+     * Set narrow margins (0.5 inch):
+     * ```typescript
+     * pageSetup.setPageMargins({
+     *   top: 36,
+     *   bottom: 36,
+     *   left: 36,
+     *   right: 36
+     * });
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type PageMargins = {
+        /**
+         * The left margin width in points.
+         *
+         * @remarks
+         * Distance from the left edge of the page to the start of the content area.
+         * Measured in points (1 point = 1/72 inch).
+         */
         left: number;
+        /**
+         * The right margin width in points.
+         *
+         * @remarks
+         * Distance from the right edge of the page to the end of the content area.
+         * Measured in points (1 point = 1/72 inch).
+         */
         right: number;
+        /**
+         * The top margin height in points.
+         *
+         * @remarks
+         * Distance from the top edge of the page to the start of the content area.
+         * Measured in points (1 point = 1/72 inch).
+         */
         top: number;
+        /**
+         * The bottom margin height in points.
+         *
+         * @remarks
+         * Distance from the bottom edge of the page to the end of the content area.
+         * Measured in points (1 point = 1/72 inch).
+         */
         bottom: number;
     };
     /**
+     * Controls physical page properties for a section.
+     *
+     * @remarks
+     * `PageSetup` provides methods to configure and query the physical page dimensions and
+     * margins for a section. Each section can have its own page setup, allowing different
+     * parts of a document to use different page sizes or orientations.
+     *
+     * Page setup is accessed via {@linkcode Section.pageSetup} and includes:
+     * - Page size (width and height)
+     * - Page margins (top, bottom, left, right)
+     *
+     * @example
+     * Change to landscape orientation:
+     * ```typescript
+     * const pageSetup = section.pageSetup();
+     * const currentSize = pageSetup.pageSize();
+     *
+     * // Swap width and height for landscape
+     * pageSetup.setPageSize({
+     *   width: currentSize.height,
+     *   height: currentSize.width
+     * });
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type PageSetup = {
+        /**
+         * Sets the page size for this section.
+         *
+         * @param size - Partial page size with width and/or height to set
+         *
+         * @remarks
+         * All dimensions are in points (1 point = 1/72 inch).
+         *
+         * To change orientation, swap the width and height values.
+         */
         setPageSize(size: Partial<PageSize>): void;
+        /**
+         * Sets the page margins for this section.
+         *
+         * @param margins - Partial page margins with top, bottom, left, and/or right to set
+         *
+         * @remarks
+         * All dimensions are in points (1 point = 1/72 inch).
+         */
         setPageMargins(margins: Partial<PageMargins>): void;
+        /**
+         * Gets the current page size for this section.
+         *
+         * @returns The current {@linkcode PageSize} with width and height
+         *
+         * @remarks
+         * All dimensions are in points (1 point = 1/72 inch).
+         *
+         */
         pageSize(): PageSize;
+        /**
+         * Gets the current page margins for this section.
+         *
+         * @returns The current {@linkcode PageMargins} with top, bottom, left, and right
+         *
+         * @remarks
+         * All dimensions are in points (1 point = 1/72 inch).
+         */
         pageMargins(): PageMargins;
     };
     /**
@@ -1626,44 +3368,837 @@ export declare namespace Programmatic {
      */
     export type HeaderFooter = BlockLevelContainer;
     /**
+     * Collection providing access to different header or footer variants.
+     *
+     * @remarks
+     * `HeadersFooters` represents a collection of header or footer variants for a section.
+     * The same type is used for both headers (via {@linkcode HeadersAndFooters.headers}) and
+     * footers (via {@linkcode HeadersAndFooters.footers}).
+     *
+     * Documents can have up to three variants for headers/footers:
+     * - **Default**: Used for most pages (typically odd pages in two-sided printing)
+     * - **First**: Used for the first page only (often different for title pages)
+     * - **Even**: Used for even pages in two-sided printing
+     *
+     * Each variant can be `null` if not configured in the document. Check for `null` before
+     * attempting to access or modify content.
+     *
+     * @example
+     * Access different header variants:
+     * ```typescript
+     * const headers = section.headersAndFooters().headers();
+     *
+     * // Default header (most pages)
+     * const defaultHeader = headers.default();
+     * if (defaultHeader) {
+     *   const para = defaultHeader.addParagraph();
+     *   para.asTextView().setText('Chapter Title');
+     * }
+     *
+     * // First page header (title page)
+     * const firstHeader = headers.first();
+     * if (firstHeader) {
+     *   const para = firstHeader.addParagraph();
+     *   para.asTextView().setText('Document Title');
+     * }
+     *
+     * // Even page header (for two-sided printing)
+     * const evenHeader = headers.even();
+     * if (evenHeader) {
+     *   const para = evenHeader.addParagraph();
+     *   para.asTextView().setText('Chapter Title - Even Page');
+     * }
+     * ```
+     *
+     * @example
+     * Set up page numbers in footer variants:
+     * ```typescript
+     * const footers = section.headersAndFooters().footers();
+     *
+     * // Default footer with page number
+     * const defaultFooter = footers.default();
+     * if (defaultFooter) {
+     *   const para = defaultFooter.addParagraph();
+     *   para.asTextView().setText('Page ');
+     *   // Note: Page number fields would be added separately
+     * }
+     *
+     * // First page footer (often empty or different)
+     * const firstFooter = footers.first();
+     * if (firstFooter) {
+     *   // Leave empty or add copyright notice
+     *   const para = firstFooter.addParagraph();
+     *   para.asTextView().setText('© 2024 Company Name');
+     * }
+     * ```
+     *
+     * @example
+     * Replace text across all variants:
+     * ```typescript
+     * const headers = section.headersAndFooters().headers();
+     *
+     * // Replace across all header variants that exist
+     * const count = headers.replaceText(/Draft/g, 'Final');
+     * console.log(`Updated ${count} occurrences across all header variants`);
+     * ```
+     *
+     * @example
+     * Check which variants exist:
+     * ```typescript
+     * const headers = section.headersAndFooters().headers();
+     *
+     * const hasDefault = headers.default() !== null;
+     * const hasFirst = headers.first() !== null;
+     * const hasEven = headers.even() !== null;
+     *
+     * console.log(`Header variants: default=${hasDefault}, first=${hasFirst}, even=${hasEven}`);
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type HeadersFooters = {
+        /**
+         * Gets the default header or footer.
+         *
+         * @returns The default {@linkcode HeaderFooter}, or `null` if not configured
+         *
+         * @remarks
+         * Returns the default (primary) header or footer used for most pages. In two-sided
+         * printing, this is typically used for odd pages when an even page variant is also
+         * configured. Returns `null` if the default variant is not configured in the document.
+         *
+         * @example
+         * ```typescript
+         * const headers = section.headersAndFooters().headers();
+         * const defaultHeader = headers.default();
+         *
+         * if (defaultHeader) {
+         *   const para = defaultHeader.addParagraph();
+         *   para.asTextView().setText('Document Header');
+         * } else {
+         *   console.log('No default header configured');
+         * }
+         * ```
+         */
         default(): HeaderFooter | null;
+        /**
+         * Gets the first page header or footer.
+         *
+         * @returns The first page {@linkcode HeaderFooter}, or `null` if not configured
+         *
+         * @remarks
+         * Returns the header or footer specifically for the first page of the section.
+         * This is commonly used for title pages that need different headers/footers from
+         * the rest of the document. Returns `null` if the first page variant is not
+         * configured in the document.
+         *
+         * @example
+         * ```typescript
+         * const headers = section.headersAndFooters().headers();
+         * const firstHeader = headers.first();
+         *
+         * if (firstHeader) {
+         *   const para = firstHeader.addParagraph();
+         *   para.asTextView().setText('Title Page Header');
+         * } else {
+         *   console.log('No first page header configured');
+         * }
+         * ```
+         */
         first(): HeaderFooter | null;
+        /**
+         * Gets the even page header or footer.
+         *
+         * @returns The even page {@linkcode HeaderFooter}, or `null` if not configured
+         *
+         * @remarks
+         * Returns the header or footer specifically for even-numbered pages, typically
+         * used in two-sided (duplex) printing where odd and even pages have different
+         * headers/footers (e.g., page numbers on different sides). Returns `null` if the
+         * even page variant is not configured in the document.
+         *
+         * @example
+         * ```typescript
+         * const headers = section.headersAndFooters().headers();
+         * const evenHeader = headers.even();
+         *
+         * if (evenHeader) {
+         *   const para = evenHeader.addParagraph();
+         *   para.asTextView().setText('Even Page Header');
+         * } else {
+         *   console.log('No even page header configured');
+         * }
+         * ```
+         */
         even(): HeaderFooter | null;
+        /**
+         * Replaces all occurrences of a pattern across all configured variants.
+         *
+         * @remarks
+         * Convenience method that searches and replaces text across all variants (default,
+         * first, and even) that are configured. Only operates on non-null variants.
+         *
+         * See {@linkcode ReplaceTextSignature} for detailed parameter and usage information.
+         *
+         * @example
+         * ```typescript
+         * const headers = section.headersAndFooters().headers();
+         * const count = headers.replaceText('Company', 'Corporation');
+         * console.log(`Updated ${count} occurrences in headers`);
+         * ```
+         *
+         * @example
+         * ```typescript
+         * const footers = section.headersAndFooters().footers();
+         * footers.replaceText(/v\d+\.\d+/g, {
+         *   text: 'v2.0',
+         *   formatting: { fontSize: 9 }
+         * });
+         * ```
+         */
         replaceText: ReplaceTextSignature;
     };
     /**
+     * Provides access to both headers and footers for a section.
+     *
+     * @remarks
+     * `HeadersAndFooters` is a container that provides access to both the headers and footers
+     * for a section. It's obtained via {@linkcode Section.headersAndFooters} and acts as a gateway
+     * to the {@linkcode HeadersFooters} collections for headers and footers separately.
+     *
+     * Headers appear at the top of pages, footers at the bottom. Both can have different
+     * content for:
+     * - Default pages (typically odd pages)
+     * - First page (often different for title pages)
+     * - Even pages (for two-sided printing)
+     *
+     * @example
+     * Access headers and footers:
+     * ```typescript
+     * const hf = section.headersAndFooters();
+     * const headers = hf.headers();
+     * const footers = hf.footers();
+     *
+     * // Work with default header
+     * const defaultHeader = headers.default();
+     * if (defaultHeader) {
+     *   const para = defaultHeader.addParagraph();
+     *   para.asTextView().setText('Document Title');
+     * }
+     *
+     * // Work with default footer
+     * const defaultFooter = footers.default();
+     * if (defaultFooter) {
+     *   const para = defaultFooter.addParagraph();
+     *   para.asTextView().setText('Page ');
+     * }
+     * ```
+     *
+     * @example
+     * Replace text in all headers and footers:
+     * ```typescript
+     * const hf = section.headersAndFooters();
+     *
+     * // Replace across all headers and footers (default, first, even)
+     * const count = hf.replaceText(/Company Name/g, 'Acme Corporation');
+     * console.log(`Updated ${count} occurrences in headers/footers`);
+     * ```
+     *
+     * @example
+     * Add content to different header/footer types:
+     * ```typescript
+     * const hf = section.headersAndFooters();
+     *
+     * // Set up first page header (title page)
+     * const firstHeader = hf.headers().first();
+     * if (firstHeader) {
+     *   const para = firstHeader.addParagraph();
+     *   para.asTextView().setText('Title Page Header');
+     * }
+     *
+     * // Set up default header (for subsequent pages)
+     * const defaultHeader = hf.headers().default();
+     * if (defaultHeader) {
+     *   const para = defaultHeader.addParagraph();
+     *   para.asTextView().setText('Chapter 1');
+     * }
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type HeadersAndFooters = {
+        /**
+         * Gets the headers collection for this section.
+         *
+         * @returns A {@linkcode HeadersFooters} object providing access to header variants
+         *
+         * @remarks
+         * Returns the headers collection, which provides access to default, first page,
+         * and even page headers. Headers appear at the top of pages.
+         *
+         * @example
+         * ```typescript
+         * const headers = headersAndFooters.headers();
+         * const defaultHeader = headers.default();
+         * const firstPageHeader = headers.first();
+         * const evenPageHeader = headers.even();
+         * ```
+         */
         headers(): HeadersFooters;
+        /**
+         * Gets the footers collection for this section.
+         *
+         * @returns A {@linkcode HeadersFooters} object providing access to footer variants
+         *
+         * @remarks
+         * Returns the footers collection, which provides access to default, first page,
+         * and even page footers. Footers appear at the bottom of pages.
+         *
+         * @example
+         * ```typescript
+         * const footers = headersAndFooters.footers();
+         * const defaultFooter = footers.default();
+         * const firstPageFooter = footers.first();
+         * const evenPageFooter = footers.even();
+         * ```
+         */
         footers(): HeadersFooters;
+        /**
+         * Replaces all occurrences of a pattern in all headers and footers.
+         *
+         * @remarks
+         * Convenience method that searches and replaces text across all headers and footers
+         * for this section, including default, first page, and even page variants.
+         *
+         * See {@linkcode ReplaceTextSignature} for detailed parameter and usage information.
+         *
+         * @example
+         * ```typescript
+         * const count = headersAndFooters.replaceText('Draft', 'Final');
+         * console.log(`Updated ${count} occurrences`);
+         * ```
+         *
+         * @example
+         * ```typescript
+         * headersAndFooters.replaceText(/\(c\)/gi, {
+         *   text: '©',
+         *   formatting: { fontSize: 10 }
+         * });
+         * ```
+         */
         replaceText: ReplaceTextSignature;
     };
     /**
+     * Represents a section within a document body.
+     *
+     * @remarks
+     * `Section` is a major organizational unit within a document. Each section can have its own:
+     * - Page setup (size, margins, orientation) via {@linkcode pageSetup}
+     * - Headers and footers via {@linkcode headersAndFooters}
+     * - Content (paragraphs and tables) via {@linkcode content}
+     *
+     * Most documents have a single section with consistent page layout and headers/footers
+     * throughout. Multi-section documents are used when you need different page layouts
+     * (e.g., landscape vs portrait) or different headers/footers (e.g., different headers
+     * per chapter) in different parts of the document.
+     *
+     * Sections are obtained from {@linkcode Body.sections} and can be added with {@linkcode Body.addSection}.
+     *
+     * @example
+     * Access and work with section components:
+     * ```typescript
+     * const sections = document.body().sections();
+     * const section = sections[0];
+     *
+     * // Access page setup
+     * const pageSetup = section.pageSetup();
+     * const size = pageSetup.pageSize();
+     * console.log(`Page size: ${size.width} x ${size.height}`);
+     *
+     * // Access content
+     * const content = section.content();
+     * const blockLevels = content.blocklevels();
+     * console.log(`Section has ${blockLevels.length} elements`);
+     *
+     * // Access headers/footers
+     * const hf = section.headersAndFooters();
+     * const headers = hf.headers();
+     * ```
+     *
+     * @example
+     * Add content to a section:
+     * ```typescript
+     * const section = document.body().sections()[0];
+     * const content = section.content();
+     *
+     * // Add a paragraph
+     * const paragraph = content.addParagraph();
+     * paragraph.asTextView().setText('This is a new paragraph.');
+     *
+     * // Add a table
+     * const table = content.addTable();
+     * const row = table.addRow();
+     * const cell = row.addCell();
+     * ```
+     *
+     * @example
+     * Replace text within a section:
+     * ```typescript
+     * const section = document.body().sections()[0];
+     *
+     * // Replace text in this section only (content + headers/footers)
+     * const count = section.replaceText(/TODO/g, {
+     *   text: 'DONE',
+     *   formatting: { highlight: '#ffff00' }
+     * });
+     *
+     * console.log(`Replaced ${count} occurrences in this section`);
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type Section = {
+        /**
+         * Gets the page setup configuration for this section.
+         *
+         * @returns The {@linkcode PageSetup} for this section
+         *
+         * @remarks
+         * Returns the page setup object that controls the physical page properties for this
+         * section, including page size (width/height) and margins. Each section can have
+         * different page setup settings.
+         *
+         * @example
+         * ```typescript
+         * const pageSetup = section.pageSetup();
+         * const size = pageSetup.pageSize();
+         * const margins = pageSetup.pageMargins();
+         *
+         * console.log(`Page: ${size.width}x${size.height}`);
+         * console.log(`Margins: T:${margins.top} B:${margins.bottom}`);
+         * ```
+         */
         pageSetup(): PageSetup;
+        /**
+         * Gets the headers and footers configuration for this section.
+         *
+         * @returns The {@linkcode HeadersAndFooters} container for this section
+         *
+         * @remarks
+         * Returns an object that provides access to headers and footers for this section.
+         * Headers and footers can have different content for the first page, even pages,
+         * and default (odd) pages.
+         *
+         * @example
+         * ```typescript
+         * const hf = section.headersAndFooters();
+         * const headers = hf.headers();
+         * const footers = hf.footers();
+         *
+         * // Access default header
+         * const defaultHeader = headers.default();
+         * if (defaultHeader) {
+         *   const para = defaultHeader.addParagraph();
+         *   para.asTextView().setText('Document Title');
+         * }
+         * ```
+         */
         headersAndFooters(): HeadersAndFooters;
+        /**
+         * Gets the main content container for this section.
+         *
+         * @returns The {@linkcode BlockLevelContainer} containing the section's content
+         *
+         * @remarks
+         * Returns a container that holds all block-level elements (paragraphs and tables)
+         * for this section. This is where the main document content resides, separate from
+         * headers and footers.
+         *
+         * @example
+         * ```typescript
+         * const content = section.content();
+         * const blockLevels = content.blocklevels();
+         *
+         * // Iterate through paragraphs and tables
+         * for (const bl of blockLevels) {
+         *   if (bl.type === 'paragraph') {
+         *     const text = bl.asTextView().getPlainText();
+         *     console.log('Paragraph:', text);
+         *   } else if (bl.type === 'table') {
+         *     console.log('Table with', bl.rows().length, 'rows');
+         *   }
+         * }
+         * ```
+         */
         content(): BlockLevelContainer;
+        /**
+         * Replaces all occurrences of a pattern within this section.
+         *
+         * @remarks
+         * Convenience method that searches and replaces text across all content in this
+         * section, including the main content, headers, and footers. This is scoped to
+         * just this section, unlike {@linkcode Body.replaceText} or {@linkcode Document.replaceText}
+         * which operate across all sections.
+         *
+         * See {@linkcode ReplaceTextSignature} for detailed parameter and usage information.
+         *
+         * @example
+         * ```typescript
+         * // Replace only in this section
+         * const count = section.replaceText(/old/g, 'new');
+         * console.log(`Replaced ${count} occurrences in section`);
+         * ```
+         *
+         * @example
+         * ```typescript
+         * section.replaceText(/DRAFT/gi, {
+         *   text: 'FINAL',
+         *   formatting: { color: '#00aa00', bold: true }
+         * });
+         * ```
+         */
+        replaceText: ReplaceTextSignature;
     };
     /**
+     * Represents the document body containing all sections.
+     *
+     * @remarks
+     * `Body` is the container for all {@linkcode Section} elements in a document. Each section can
+     * have its own page setup (size, margins, orientation) and headers/footers. Most documents
+     * have a single section, but documents can be divided into multiple sections for different
+     * page layouts or header/footer configurations.
+     *
+     * The body is accessed via {@linkcode Document.body} and provides methods to:
+     * - Get all sections ({@linkcode sections})
+     * - Add new sections ({@linkcode addSection})
+     * - Remove sections ({@linkcode removeSection})
+     * - Replace text across all sections ({@linkcode replaceText})
+     *
+     * @example
+     * Access and iterate through sections:
+     * ```typescript
+     * const body = document.body();
+     * const sections = body.sections();
+     *
+     * console.log(`Document has ${sections.length} sections`);
+     *
+     * for (const section of sections) {
+     *   const content = section.content();
+     *   const paragraphs = content.blocklevels()
+     *     .filter(bl => bl.type === 'paragraph');
+     *   console.log(`Section has ${paragraphs.length} paragraphs`);
+     * }
+     * ```
+     *
+     * @example
+     * Add a new section to the document:
+     * ```typescript
+     * const body = document.body();
+     *
+     * // Add section at the end
+     * const newSection = body.addSection();
+     *
+     * // Configure page setup
+     * const pageSetup = newSection.pageSetup();
+     * pageSetup.setPageSize({ width: 12240000, height: 15840000 }); // Letter size
+     *
+     * // Add content
+     * const para = newSection.content().addParagraph();
+     * para.asTextView().setText('This is a new section');
+     * ```
+     *
+     * @example
+     * Replace text across all sections:
+     * ```typescript
+     * const body = document.body();
+     *
+     * // Replace across entire document body
+     * const count = body.replaceText(/TODO/g, {
+     *   text: 'DONE',
+     *   formatting: { highlight: '#00ff00' }
+     * });
+     *
+     * console.log(`Replaced ${count} occurrences across all sections`);
+     * ```
+     *
+     * @example
+     * Remove a section:
+     * ```typescript
+     * const body = document.body();
+     * const sections = body.sections();
+     *
+     * if (sections.length > 1) {
+     *   // Remove the last section
+     *   const removed = body.removeSection(sections.length - 1);
+     *   if (removed) {
+     *     console.log('Removed last section');
+     *   }
+     * }
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type Body = {
+        /**
+         * Gets all sections in the document body.
+         *
+         * @returns An array of {@linkcode Section} objects
+         *
+         * @remarks
+         * Returns all sections in the document in order. Most documents have a single section,
+         * but documents can contain multiple sections with different page setups or
+         * headers/footers.
+         *
+         * @example
+         * ```typescript
+         * const sections = body.sections();
+         * console.log(`Document has ${sections.length} sections`);
+         *
+         * sections.forEach((section, index) => {
+         *   console.log(`Section ${index + 1}`);
+         * });
+         * ```
+         */
         sections(): Section[];
+        /**
+         * Adds a new section to the document body.
+         *
+         * @param index - Optional zero-based position to insert the section. If omitted, adds at the end.
+         * @returns The newly created {@linkcode Section}
+         *
+         * @remarks
+         * Creates and inserts a new section at the specified position. If no index is provided,
+         * the section is added at the end. The new section is initialized with default page
+         * setup and empty content.
+         *
+         * Use this when you need different page layouts, orientations, or headers/footers
+         * for different parts of your document.
+         *
+         * @example
+         * Add section at the end:
+         * ```typescript
+         * const newSection = body.addSection();
+         * const para = newSection.content().addParagraph();
+         * para.asTextView().setText('New section content');
+         * ```
+         *
+         * @example
+         * Insert section at specific position:
+         * ```typescript
+         * // Insert as the second section (index 1)
+         * const section = body.addSection(1);
+         * ```
+         */
         addSection(index?: number): Section;
+        /**
+         * Removes a section from the document body.
+         *
+         * @param index - Zero-based index of the section to remove
+         * @returns The removed {@linkcode Section}, or `undefined` if the index is invalid
+         *
+         * @remarks
+         * Removes the section at the specified index. If the index is out of bounds,
+         * returns `undefined`. Be cautious when removing sections as this removes all
+         * content within that section.
+         *
+         * @example
+         * ```typescript
+         * const sections = body.sections();
+         * if (sections.length > 1) {
+         *   // Remove the last section
+         *   const removed = body.removeSection(sections.length - 1);
+         *   if (removed) {
+         *     console.log('Successfully removed section');
+         *   }
+         * }
+         * ```
+         *
+         * @example
+         * Remove specific section with confirmation:
+         * ```typescript
+         * const indexToRemove = 2;
+         * const sections = body.sections();
+         *
+         * if (indexToRemove < sections.length) {
+         *   const removed = body.removeSection(indexToRemove);
+         *   console.log(`Removed section ${indexToRemove + 1}`);
+         * }
+         * ```
+         */
         removeSection(index: number): Section | undefined;
+        /**
+         * Replaces all occurrences of a pattern across all sections.
+         *
+         * @remarks
+         * Convenience method that searches and replaces text across all sections in the body,
+         * including all content, headers, and footers. This provides a simpler API than
+         * manually iterating through sections.
+         *
+         * See {@linkcode ReplaceTextSignature} for detailed parameter and usage information.
+         *
+         * @example
+         * ```typescript
+         * const count = body.replaceText(/old/g, 'new');
+         * console.log(`Replaced ${count} occurrences`);
+         * ```
+         *
+         * @example
+         * ```typescript
+         * body.replaceText(/ERROR/gi, {
+         *   text: 'ERROR',
+         *   formatting: { color: '#ff0000', bold: true }
+         * });
+         * ```
+         */
         replaceText: ReplaceTextSignature;
     };
     /**
+     * Represents the root of a document structure in the programmatic API.
+     *
+     * @remarks
+     * `Document` is the top-level entry point for programmatically accessing and modifying
+     * document content. It provides access to the document {@linkcode Body}, which contains all
+     * sections and their content.
+     *
+     * You typically obtain a `Document` instance from a transaction context when using the
+     * programmatic API to modify documents. The document is organized hierarchically:
+     *
+     * ```
+     * Document
+     *   └─ Body
+     *       └─ Section(s)
+     *           ├─ Content (BlockLevelContainer)
+     *           │   └─ Paragraph(s) / Table(s)
+     *           └─ Headers & Footers
+     * ```
+     *
+     * For document-wide operations, you can use the convenience {@linkcode replaceText} method
+     * to search and replace across all content without manually traversing the hierarchy.
+     *
+     * @example
+     * Access document structure and iterate through content:
+     * ```typescript
+     * const body = document.body();
+     * const sections = body.sections();
+     *
+     * console.log(`Document has ${sections.length} sections`);
+     *
+     * for (const section of sections) {
+     *   const content = section.content();
+     *   const blockLevels = content.blocklevels();
+     *   console.log(`Section has ${blockLevels.length} paragraphs/tables`);
+     * }
+     * ```
+     *
+     * @example
+     * Replace text across entire document:
+     * ```typescript
+     * // Replace all occurrences of "TODO" with "DONE" throughout the document
+     * const count = document.replaceText(/TODO/g, 'DONE');
+     * console.log(`Replaced ${count} occurrences across entire document`);
+     * ```
+     *
+     * @example
+     * Replace text with formatting across document:
+     * ```typescript
+     * // Highlight all instances of "IMPORTANT" in the entire document
+     * document.replaceText(/IMPORTANT/gi, {
+     *   text: 'IMPORTANT',
+     *   formatting: {
+     *     highlight: '#ffff00',
+     *     bold: true
+     *   }
+     * });
+     * ```
+     *
+     * @example
+     * Typical usage in a transaction:
+     * ```typescript
+     * await docAuthDoc.transaction(async (context) => {
+     *   const { draft } = context;
+     *
+     *   // 'draft' is a Programmatic.Document
+     *   const body = draft.body();
+     *   const sections = body.sections();
+     *
+     *   // Add a new section
+     *   const newSection = body.addSection();
+     *   const para = newSection.content().addParagraph();
+     *   para.asTextView().setText('New section content');
+     *
+     *   // Or use document-wide replace
+     *   draft.replaceText(/old/g, 'new');
+     *
+     *   return { commit: true };
+     * });
+     * ```
+     *
      * @sidebarGroup programmatic api
      */
     export type Document = {
+        /**
+         * Gets the document body containing all sections.
+         *
+         * @returns The {@linkcode Body} of the document
+         *
+         * @remarks
+         * Returns the document's body, which contains all sections. Each section has its
+         * own content (paragraphs and tables) and headers/footers. Use this as the entry
+         * point for navigating and modifying document structure.
+         *
+         * @example
+         * ```typescript
+         * const body = document.body();
+         * const sections = body.sections();
+         *
+         * // Work with sections
+         * for (const section of sections) {
+         *   const content = section.content();
+         *   // ... work with content
+         * }
+         * ```
+         */
         body(): Body;
+        /**
+         * Replaces all occurrences of a pattern throughout the entire document.
+         *
+         * @remarks
+         * Convenience method that searches and replaces text across all document content,
+         * including all sections, paragraphs, tables, headers, and footers. This is equivalent
+         * to manually calling {@linkcode Body.replaceText} on the document body, but provides a
+         * simpler API for document-wide operations.
+         *
+         * See {@linkcode ReplaceTextSignature} for detailed parameter and usage information.
+         *
+         * @example
+         * Simple document-wide replacement:
+         * ```typescript
+         * const count = document.replaceText('old text', 'new text');
+         * console.log(`Replaced ${count} occurrences`);
+         * ```
+         *
+         * @example
+         * Replace with formatting:
+         * ```typescript
+         * document.replaceText(/ERROR/g, {
+         *   text: 'ERROR',
+         *   formatting: { color: '#ff0000', bold: true }
+         * });
+         * ```
+         *
+         * @example
+         * Dynamic replacement with callback:
+         * ```typescript
+         * // Convert all numbers to currency format
+         * document.replaceText(/\$?(\d+(\.\d{2})?)/g, (match) => {
+         *   const amount = parseFloat(match.replace('$', ''));
+         *   return {
+         *     text: `$${amount.toFixed(2)}`,
+         *     formatting: { color: '#00aa00' }
+         *   };
+         * });
+         * ```
+         */
         replaceText: ReplaceTextSignature;
     };
         {};
@@ -1885,16 +4420,102 @@ export declare type ToolbarSeparatorItem = {
 };
 
 /**
- * @alpha
+ * Callback function for document transactions that provides access to a draft document for modification.
+ *
+ * @remarks
+ * `TransactionCallback` is the function signature used when working with document transactions via
+ * {@linkcode DocAuthDocument.transaction}. The callback receives a context object containing a
+ * `draft` document that can be modified, and returns a {@linkcode TransactionResult} to control
+ * whether changes are committed .
+ *
+ * **Key concepts:**
+ *
+ * **Context parameter:**
+ * - `context.draft` - A {@linkcode Programmatic.Document} instance representing the document in draft state
+ * - All modifications are made on this draft
+ * - Changes are isolated until the transaction commits
+ *
+ * **Return value:**
+ * - Must return a {@linkcode TransactionResult}
+ * - Return `true`, or `{ commit: true }` to commit changes
+ * - Optionally return a result value with `{ commit: boolean, result: T }`
+ *
+ * @example
+ * Explicit commit:
+ * ```typescript
+ * const r = await doc.transaction(async ({ draft }) => {
+ *   const replacementCount = draft.replaceText(/old/g, 'new');
+ *
+ *   return { commit: true, result: replacementCount };
+ * });
+ * ```
+ *
+ * @param context - Object containing the draft document to modify
+ * @returns A {@linkcode TransactionResult} controlling commit/rollback and optionally providing a result value
+ *
+ * @public
  * @sidebarGroup programmatic api
  * @see {@linkcode DocAuthDocument.transaction} for running transactions with this callback type.
+ * @see {@linkcode TransactionResult} for details on return value options.
+ */
+export declare type TransactionCallback<T = void> = (context: TransactionContext) => Promise<TransactionResult<T>>;
+
+/**
+ * Context object passed to transaction callbacks.
+ *
+ * @remarks
+ * Contains the draft document that can be read or modified within a transaction.
+ *
+ * @public
+ * @sidebarGroup programmatic api
+ * @see {@linkcode TransactionCallback} for how this context is used
  */
-export declare type TransactionCallback<T = void> = (context: {
+export declare type TransactionContext = {
+    /**
+     * The draft document for reading and modification.
+     *
+     * @remarks
+     * A {@linkcode Programmatic.Document} instance representing the document in draft state.
+     * All modifications are made to this draft and are isolated until the transaction commits.
+     */
     draft: Programmatic.Document;
-}) => Promise<TransactionResult<T>>;
+};
 
 /**
- * @alpha
+ * Return type for transaction callbacks that control whether changes are committed and optionally return a result.
+ *
+ * @remarks
+ * `TransactionResult` is returned from {@linkcode TransactionCallback} functions to control the outcome
+ * of a document transaction. It determines whether the changes made during the transaction should be
+ * committed to the document and optionally provides a result value to the transaction caller.
+ *
+ * **Commit behavior:**
+ * - `true` - **Commits** the transaction
+ * - `{ commit: true }` - **Commits** the transaction
+ * - `{ commit: true, result: T }` - **Commits** the transaction and returns a result value
+ * - `false` - Does **not** commit the transaction
+ * - `{ commit: false }` - Does **not** commit the transaction
+ * - `{ commit: false, result: T }` - Does **not** commit the transaction but still returns a result value
+ *
+ * **Async support:**
+ * All return values can be wrapped in a `Promise`, allowing async transaction callbacks.
+ *
+ * **Type parameter `T`:**
+ * - Defaults to `void` if no result is needed
+ * - Set to a specific type when you want to return a value from the transaction
+ * - The result can be returned regardless of whether the transaction commits or not
+ *
+ * @example
+ * Explicit commit:
+ * ```typescript
+ * const r = await doc.transaction(async ({ draft }) => {
+ *   const replacementCount = draft.replaceText(/old/g, 'new');
+ *
+ *   return { commit: true, result: replacementCount };
+ * });
+ * ```
+ *
+ * @public
  * @sidebarGroup programmatic api
  * @see {@linkcode TransactionCallback} for the callback signature that returns this result type.
  */