declare module "@univerjs/docs/facade" {
  import type { DocumentDataModel, IDocumentBody, IDocumentData, IParagraphStyle, ITextStyle } from "@univerjs/core";

  // @ts-ignore: optional external type dependency may be absent in generated workspaces.
  import type { DocumentBlockRangeType, ICustomBlock, ICustomTable, IDocumentBlockRange, IParagraph } from "@univerjs/core";

  /**
   * The top-level document body element types supported by the doc facade.
   */
  type FDocElementType = 'paragraph' | 'table' | 'blockRange' | 'customBlock';

  /**
   * Error thrown when a facade element key can no longer be resolved uniquely.
   *
   * A stale paragraph usually means the paragraph was deleted, or the document no
   * longer contains exactly one paragraph with the requested `paragraphId`.
   *
   * @example
   * ```ts
   * const doc = univerAPI.getActiveDocument();
   * if (!doc) throw new Error('No active document');
   *
   * const paragraph = doc.getBody().getChild(0).asParagraph();
   * paragraph.removeFromParent();
   *
   * try {
   *     paragraph.getText();
   * } catch (error) {
   *     if (error instanceof DocElementStaleError) {
   *         console.log('The paragraph handle is stale.');
   *     }
   * }
   * ```
   */
  class DocElementStaleError {
  }

  /**
   * A facade wrapper for document block ranges, such as callout, quote, and code blocks.
   *
   * Block range identity is backed by the persisted `IDocumentBlockRange.blockId`,
   * so wrappers can be re-resolved after text is inserted before the block range.
   *
   * @hideconstructor
   */
  class FDocBlockRange {
      /**
       * Get the document element type.
       * @returns {'blockRange'} The literal block range element type.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const blockRange = doc.getBody().getChild(0).asBlockRange();
       * console.log(blockRange.getType());
       * ```
       */
      getType(): 'blockRange';
      /**
       * Get the block range key.
       * @returns {string} The persisted `blockId` for this block range.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const blockRange = doc.getBody().getChild(0).asBlockRange();
       * console.log(blockRange.getKey());
       * ```
       */
      getKey(): string;
      /**
       * Get the parent body facade that owns this block range.
       * @returns {FDocBody} The document body facade.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const blockRange = doc.getBody().getChild(0).asBlockRange();
       * console.log(blockRange.getParent().getChildIndex(blockRange));
       * ```
       */
      getParent(): FDocBody;
      /**
       * Remove this block range and its content from the parent body.
       * @returns {boolean} `true` if the block range content was removed.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const blockRange = doc.getBody().getChild(0).asBlockRange();
       * blockRange.removeFromParent();
       * ```
       */
      removeFromParent(): boolean;
      /**
       * Get the block range type.
       * @returns {DocumentBlockRangeType} The block type, such as callout, quote, or code.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const blockRange = doc.getBody().getChild(0).asBlockRange();
       * console.log(blockRange.getBlockType());
       * ```
       */
      getBlockType(): DocumentBlockRangeType;
      /**
       * Get the plain text inside this block range.
       * @returns {string} The block range text.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const blockRange = doc.getBody().getChild(0).asBlockRange();
       * console.log(blockRange.getText());
       * ```
       */
      getText(): string;
      /**
       * Replace the plain text inside this block range.
       * @param {string} text The replacement text.
       * @returns {boolean} `true` if the block range text was replaced.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const blockRange = doc.getBody().getChild(0).asBlockRange();
       * blockRange.setText('Updated block text');
       * ```
       */
      setText(text: string): boolean;
      /**
       * Remove this block range wrapper from the body.
       *
       * This currently removes the block range and its content, matching
       * `removeFromParent()`.
       *
       * @returns {boolean} `true` if the block range content was removed.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const blockRange = doc.getBody().getChild(0).asBlockRange();
       * blockRange.unwrap();
       * ```
       */
      unwrap(): boolean;
  }

  /**
   * A text range in a document segment. Offsets are zero-based positions in the segment data stream.
   */
  interface IFDocTextRange {
      /** The inclusive start offset of the range. */
      startOffset: number;
      /** The exclusive end offset of the range. */
      endOffset: number;
      /** The header/footer segment id. Omit or use an empty string for the main body. */
      segmentId?: string;
  }

  /**
   * Resolved paragraph metadata in the current document body.
   */
  interface IFDocResolvedParagraph {
      /** The underlying paragraph snapshot object. */
      paragraph: IParagraph;
      /** The current paragraph index in the body paragraph list. */
      paragraphIndex: number;
      /** The inclusive start offset of the paragraph text. */
      startOffset: number;
      /** The exclusive end offset of the paragraph text, before the paragraph break. */
      endOffset: number;
  }

  /**
   * A stable facade element handle that can be resolved by type and key.
   */
  interface IFDocElementHandle {
      /**
       * Get the element type.
       * @returns {FDocElementType} The element type used by the facade resolver.
       */
      getType(): FDocElementType;
      /**
       * Get the persisted key used by the facade to resolve the element.
       * @returns {string} The facade key.
       */
      getKey(): string;
  }

  /**
   * A rich-text-like object, such as `RichTextValue` or `RichTextBuilder`, that can provide document body data.
   */
  interface IFDocRichTextLike {
      /**
       * Get rich text data that contains document body data.
       * @returns {{ body?: IDocumentBody }} The rich text data object.
       */
      getData(): {
          body?: IDocumentBody;
      };
  }

  interface IFDocChildInfo {
      type: FDocElementType;
      key: string;
      position: number;
      priority: number;
  }

  /**
   * A Facade API object bounded to a document body or header/footer segment.
   * It provides Google Docs-like element access and range editing methods.
   *
   * Paragraph elements use their persisted `paragraphId`. Tables, block ranges, and
   * custom blocks use their persisted ids.
   *
   * @hideconstructor
   */
  class FDocBody {
      /**
       * Get the number of top-level child elements in the body.
       * @returns {number} The number of child elements.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * console.log(body.getNumChildren());
       * ```
       */
      getNumChildren(): number;
      /**
       * Get a top-level child element by child index.
       * @param {number} index The zero-based child index.
       * @returns {FDocElement} The child element wrapper.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * const firstChild = body.getChild(0);
       * console.log(firstChild.getType());
       * ```
       */
      getChild(index: number): FDocElement;
      /**
       * Get the current child index of an element handle.
       * The index is resolved from the element key, so a paragraph handle keeps pointing
       * to the same paragraph after facade edits insert content before it.
       * @param {IFDocElementHandle} element The element handle to locate.
       * @returns {number} The current zero-based child index.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * const paragraph = body.getChild(1).asParagraph();
       * body.insertParagraph(0, 'Intro');
       * console.log(body.getChildIndex(paragraph));
       * ```
       */
      getChildIndex(element: IFDocElementHandle): number;
      /**
       * Insert plain text at a document body offset.
       * @param {number} index The zero-based insertion offset.
       * @param {string} text The plain text to insert.
       * @returns {boolean} `true` if the edit was applied.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * body.insertText(0, 'Hello ');
       * ```
       */
      insertText(index: number, text: string): boolean;
      /**
       * Insert a plain-text paragraph before the paragraph at the given paragraph index.
       * @param {number} index The zero-based paragraph insertion index.
       * @param {string} text The paragraph text. Defaults to an empty paragraph.
       * @returns {FDocParagraph} The inserted paragraph wrapper.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * const paragraph = body.insertParagraph(0, 'Document title');
       * paragraph.appendText(' suffix');
       * ```
       */
      insertParagraph(index: number, text?: string): FDocParagraph;
      /**
       * Append a plain-text paragraph at the end of the body.
       * @param {string} text The paragraph text. Defaults to an empty paragraph.
       * @returns {FDocParagraph} The appended paragraph wrapper.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * const paragraph = body.appendParagraph('Summary');
       * console.log(paragraph.getText());
       * ```
       */
      appendParagraph(text?: string): FDocParagraph;
      /**
       * Delete a range from the body.
       * @param {IFDocTextRange} range The text range to delete.
       * @returns {boolean} `true` if the range was deleted.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * body.deleteRange({ startOffset: 0, endOffset: 5 });
       * ```
       */
      deleteRange(range: IFDocTextRange): boolean;
      /**
       * Replace a range with plain text or rich text body data.
       * @param {IFDocTextRange} range The text range to replace.
       * @param {string | IFDocRichTextLike | { body?: IDocumentBody }} value The replacement text or rich-text-like value.
       * @returns {boolean} `true` if the replacement was applied.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * body.replaceRange({ startOffset: 0, endOffset: 5 }, 'Hello');
       * ```
       */
      replaceRange(range: IFDocTextRange, value: string | IFDocRichTextLike | {
          body?: IDocumentBody;
      }): boolean;
      /**
       * Apply text style to a body range.
       * @param {IFDocTextRange} range The range to style.
       * @param {ITextStyle} style The Univer text style patch.
       * @returns {boolean} `true` if the style was applied.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * body.setTextStyle({ startOffset: 0, endOffset: 5 }, { bl: 1 });
       * ```
       */
      setTextStyle(range: IFDocTextRange, style: ITextStyle): boolean;
      /**
       * Apply paragraph style to a paragraph handle or text range.
       * @param {FDocElement | FDocParagraph | IFDocTextRange} paragraph The paragraph handle or a range inside the paragraph.
       * @param {IParagraphStyle} style The Univer paragraph style patch.
       * @returns {boolean} `true` if the style was applied.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * const paragraph = body.getChild(0).asParagraph();
       * body.setParagraphStyle(paragraph, { horizontalAlign: 2 });
       * ```
       */
      setParagraphStyle(paragraph: FDocElement | FDocParagraph | IFDocTextRange, style: IParagraphStyle): boolean;
      /**
       * Get the text content of a paragraph by paragraph id.
       * @param {string} key The paragraph id.
       * @returns {string} The paragraph text without the trailing paragraph break.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * console.log(doc.getBody().getParagraphText(paragraph.getKey()));
       * ```
       */
      getParagraphText(key: string): string;
      /**
       * Replace the text content of a paragraph by paragraph id.
       * @param {string} key The paragraph id.
       * @param {string} text The replacement paragraph text.
       * @returns {boolean} `true` if the paragraph text was replaced.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * doc.getBody().setParagraphText(paragraph.getKey(), 'Updated text');
       * ```
       */
      setParagraphText(key: string, text: string): boolean;
      /**
       * Append text to a paragraph by paragraph id.
       * @param {string} key The paragraph id.
       * @param {string} text The text to append before the paragraph break.
       * @returns {boolean} `true` if the text was appended.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * doc.getBody().appendParagraphText(paragraph.getKey(), ' suffix');
       * ```
       */
      appendParagraphText(key: string, text: string): boolean;
      /**
       * Remove a paragraph by paragraph id.
       * @param {string} key The paragraph id.
       * @returns {boolean} `true` if the paragraph was removed.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * doc.getBody().removeParagraph(paragraph.getKey());
       * ```
       */
      removeParagraph(key: string): boolean;
      /**
       * Get a paragraph text range by paragraph id.
       * @param {string} key The paragraph id.
       * @returns {IFDocTextRange} The paragraph range excluding the trailing paragraph break.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * const range = doc.getBody().getParagraphRange(paragraph.getKey());
       * console.log(range.startOffset, range.endOffset);
       * ```
       */
      getParagraphRange(key: string): IFDocTextRange;
      /**
       * Check whether a paragraph has list metadata.
       * @param {string} key The paragraph id.
       * @returns {boolean} `true` if the paragraph is a list item.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * console.log(doc.getBody().isListParagraph(paragraph.getKey()));
       * ```
       */
      isListParagraph(key: string): boolean;
      /**
       * Check whether a paragraph is a task/checklist item.
       * @param {string} key The paragraph id.
       * @returns {boolean} `true` if the paragraph is an unchecked or checked task item.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * console.log(doc.getBody().isTaskParagraph(paragraph.getKey()));
       * ```
       */
      isTaskParagraph(key: string): boolean;
      /**
       * Set the checked state of a task/checklist paragraph.
       * @param {string} key The paragraph id.
       * @param {boolean} checked Whether the task should be checked.
       * @returns {boolean} `true` if the task state was updated, or `false` if the paragraph is not a task item.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * doc.getBody().setTaskChecked(paragraph.getKey(), true);
       * ```
       */
      setTaskChecked(key: string, checked: boolean): boolean;
      /**
       * Resolve a paragraph id to its current paragraph metadata.
       * @param {string} key The paragraph id.
       * @returns {IFDocResolvedParagraph} The current paragraph metadata.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * const resolved = doc.getBody().resolveParagraph(paragraph.getKey());
       * console.log(resolved.paragraphIndex);
       * ```
       */
      resolveParagraph(key: string): IFDocResolvedParagraph;
      /**
       * Resolve an element key to its current child metadata.
       * @param {FDocElementType} type The element type.
       * @param {string} key The persisted element key.
       * @returns {object} The current child metadata used by the facade.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const element = doc.getBody().getChild(0);
       * const resolved = doc.getBody().resolveElement(element.getType(), element.getKey());
       * console.log(resolved.position);
       * ```
       */
      resolveElement(type: FDocElementType, key: string): IFDocChildInfo;
      /**
       * Get a callout, quote, or code block range by block id.
       * @param {string} key The persisted block range id.
       * @returns {IDocumentBlockRange} The matching block range snapshot.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const block = doc.getBody().getChild(0).asBlockRange();
       * console.log(doc.getBody().getBlockRange(block.getKey()).blockType);
       * ```
       */
      getBlockRange(key: string): IDocumentBlockRange;
      /**
       * Get the text inside a callout, quote, or code block range.
       * @param {string} key The persisted block range id.
       * @returns {string} The block range text.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const block = doc.getBody().getChild(0).asBlockRange();
       * console.log(doc.getBody().getBlockRangeText(block.getKey()));
       * ```
       */
      getBlockRangeText(key: string): string;
      /**
       * Replace the text inside a callout, quote, or code block range.
       * @param {string} key The persisted block range id.
       * @param {string} text The replacement text.
       * @returns {boolean} `true` if the text was replaced.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const block = doc.getBody().getChild(0).asBlockRange();
       * doc.getBody().setBlockRangeText(block.getKey(), 'Updated block');
       * ```
       */
      setBlockRangeText(key: string, text: string): boolean;
      /**
       * Remove a callout, quote, or code block range and its content.
       * @param {string} key The persisted block range id.
       * @returns {boolean} `true` if the block range content was removed.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const block = doc.getBody().getChild(0).asBlockRange();
       * doc.getBody().removeBlockRange(block.getKey());
       * ```
       */
      removeBlockRange(key: string): boolean;
      /**
       * Get a table marker by table id.
       * @param {string} key The persisted table id.
       * @returns {ICustomTable} The matching table marker.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const table = doc.getBody().getChild(0).asTable();
       * console.log(doc.getBody().getTable(table.getTableId()));
       * ```
       */
      getTable(key: string): ICustomTable;
      /**
       * Remove a table marker and its content range.
       * @param {string} key The persisted table id.
       * @returns {boolean} `true` if the table range was removed.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const table = doc.getBody().getChild(0).asTable();
       * doc.getBody().removeTable(table.getTableId());
       * ```
       */
      removeTable(key: string): boolean;
      /**
       * Get a custom block marker by block id.
       * @param {string} key The persisted custom block id.
       * @returns {ICustomBlock} The matching custom block marker.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const customBlock = doc.getBody().getChild(0).asCustomBlock();
       * console.log(doc.getBody().getCustomBlock(customBlock.getBlockId()));
       * ```
       */
      getCustomBlock(key: string): ICustomBlock;
      /**
       * Remove a custom block marker and its placeholder character.
       * @param {string} key The persisted custom block id.
       * @returns {boolean} `true` if the custom block placeholder was removed.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const customBlock = doc.getBody().getChild(0).asCustomBlock();
       * doc.getBody().removeCustomBlock(customBlock.getBlockId());
       * ```
       */
      removeCustomBlock(key: string): boolean;
      /**
       * Create a sibling element wrapper relative to the current element key.
       * @param {FDocElementType} type The current element type.
       * @param {string} key The current element key.
       * @param {-1 | 1} direction `-1` for previous sibling, `1` for next sibling.
       * @returns {FDocElement | null} The sibling wrapper, or `null` if none exists.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const element = doc.getBody().getChild(0);
       * const next = doc.getBody().createSibling(element.getType(), element.getKey(), 1);
       * console.log(next?.getType());
       * ```
       */
      createSibling(type: FDocElementType, key: string, direction: -1 | 1): FDocElement | null;
  }

  /**
   * A facade wrapper for a document custom block, such as an embedded drawing or widget.
   *
   * Custom block identity is backed by the persisted `ICustomBlock.blockId`, so the
   * wrapper can be re-resolved after text is inserted before the custom block.
   *
   * @hideconstructor
   */
  class FDocCustomBlock {
      /**
       * Get the document element type.
       * @returns {'customBlock'} The literal custom block element type.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const customBlock = doc.getBody().getChild(0).asCustomBlock();
       * console.log(customBlock.getType());
       * ```
       */
      getType(): 'customBlock';
      /**
       * Get the custom block key.
       * @returns {string} The persisted `blockId` for this custom block.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const customBlock = doc.getBody().getChild(0).asCustomBlock();
       * console.log(customBlock.getKey());
       * ```
       */
      getKey(): string;
      /**
       * Get the parent body facade that owns this custom block.
       * @returns {FDocBody} The document body facade.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const customBlock = doc.getBody().getChild(0).asCustomBlock();
       * console.log(customBlock.getParent().getChildIndex(customBlock));
       * ```
       */
      getParent(): FDocBody;
      /**
       * Remove this custom block from the parent body.
       * @returns {boolean} `true` if the custom block placeholder was removed.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const customBlock = doc.getBody().getChild(0).asCustomBlock();
       * customBlock.removeFromParent();
       * ```
       */
      removeFromParent(): boolean;
      /**
       * Get the persisted custom block id.
       * @returns {string} The `ICustomBlock.blockId` value.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const customBlock = doc.getBody().getChild(0).asCustomBlock();
       * console.log(customBlock.getBlockId());
       * ```
       */
      getBlockId(): string;
  }

  /**
   * A generic top-level document body element.
   *
   * Use this wrapper when you need to inspect an element type first, navigate to
   * neighboring elements, or cast the element to a more specific facade wrapper.
   *
   * Paragraph keys are persisted `paragraphId` values. Tables, block ranges, and
   * custom blocks use their persisted ids.
   *
   * @hideconstructor
   */
  class FDocElement {
      /**
       * Get the document element type.
       * @returns {FDocElementType} The element type, such as `paragraph`, `table`, `blockRange`, or `customBlock`.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const element = doc.getBody().getChild(0);
       * console.log(element.getType());
       * ```
       */
      getType(): FDocElementType;
      /**
       * Get the facade key used to resolve this element.
       * @returns {string} The paragraph `paragraphId` or persisted table/block/custom block id.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * const element = body.getChild(0);
       * console.log(element.getKey());
       * ```
       */
      getKey(): string;
      /**
       * Get the parent body facade that owns this element.
       * @returns {FDocBody} The document body facade.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const element = doc.getBody().getChild(0);
       * console.log(element.getParent().getNumChildren());
       * ```
       */
      getParent(): FDocBody;
      /**
       * Get the next sibling element in the current body order.
       * @returns {FDocElement | null} The next sibling wrapper, or `null` when this is the last child.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const first = doc.getBody().getChild(0);
       * const next = first.getNextSibling();
       * console.log(next?.getType());
       * ```
       */
      getNextSibling(): FDocElement | null;
      /**
       * Get the previous sibling element in the current body order.
       * @returns {FDocElement | null} The previous sibling wrapper, or `null` when this is the first child.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const second = doc.getBody().getChild(1);
       * const previous = second.getPreviousSibling();
       * console.log(previous?.getType());
       * ```
       */
      getPreviousSibling(): FDocElement | null;
      /**
       * Remove this element from its parent body.
       * @returns {boolean} `true` if the element content was removed.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * const element = body.getChild(0);
       * element.removeFromParent();
       * ```
       */
      removeFromParent(): boolean;
      /**
       * Cast this generic element to a paragraph facade.
       * @returns {FDocParagraph} The paragraph facade wrapper.
       * @throws {TypeError} If the element is not a paragraph.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * console.log(paragraph.getText());
       * ```
       */
      asParagraph(): FDocParagraph;
      /**
       * Cast this generic element to a table facade.
       * @returns {FDocTable} The table facade wrapper.
       * @throws {TypeError} If the element is not a table.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const table = doc.getBody().getChild(0).asTable();
       * console.log(table.getTableId());
       * ```
       */
      asTable(): FDocTable;
      /**
       * Cast this generic element to a callout, quote, or code block range facade.
       * @returns {FDocBlockRange} The block range facade wrapper.
       * @throws {TypeError} If the element is not a block range.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const blockRange = doc.getBody().getChild(0).asBlockRange();
       * console.log(blockRange.getBlockType());
       * ```
       */
      asBlockRange(): FDocBlockRange;
      /**
       * Cast this generic element to a custom block facade.
       * @returns {FDocCustomBlock} The custom block facade wrapper.
       * @throws {TypeError} If the element is not a custom block.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const customBlock = doc.getBody().getChild(0).asCustomBlock();
       * console.log(customBlock.getBlockId());
       * ```
       */
      asCustomBlock(): FDocCustomBlock;
  }

  /**
   * A paragraph facade wrapper.
   *
   * Paragraph identity is backed by the persisted `paragraphId`. The id is
   * re-resolved before each method call, so insertions before this paragraph do
   * not break the wrapper.
   *
   * @hideconstructor
   */
  class FDocParagraph {
      /**
       * Get the document element type.
       * @returns {'paragraph'} The literal paragraph element type.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * console.log(paragraph.getType());
       * ```
       */
      getType(): 'paragraph';
      /**
       * Get the persisted paragraph id.
       * @returns {string} The paragraph id.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * console.log(paragraph.getKey());
       * ```
       */
      getKey(): string;
      /**
       * Get the persisted paragraph id.
       * @returns {string} The paragraph id.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * console.log(paragraph.getId());
       * ```
       */
      getId(): string;
      /**
       * Get the parent body facade that owns this paragraph.
       * @returns {FDocBody} The document body facade.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * console.log(paragraph.getParent().getChildIndex(paragraph));
       * ```
       */
      getParent(): FDocBody;
      /**
       * Remove this paragraph from its parent body.
       * @returns {boolean} `true` if the paragraph was removed.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * paragraph.removeFromParent();
       * ```
       */
      removeFromParent(): boolean;
      /**
       * Get this paragraph's plain text.
       * @returns {string} The paragraph text without the trailing paragraph break.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * console.log(paragraph.getText());
       * ```
       */
      getText(): string;
      /**
       * Replace this paragraph's plain text.
       * @param {string} text The replacement text. Do not include the paragraph break.
       * @returns {boolean} `true` if the paragraph text was replaced.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * paragraph.setText('Updated title');
       * ```
       */
      setText(text: string): boolean;
      /**
       * Append plain text before this paragraph's trailing paragraph break.
       * @param {string} text The plain text to append.
       * @returns {boolean} `true` if the text was appended.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * paragraph.appendText(' suffix');
       * ```
       */
      appendText(text: string): boolean;
      /**
       * Get the current text range occupied by this paragraph.
       * @returns {IFDocTextRange} The paragraph text range, excluding the trailing paragraph break.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * const range = paragraph.getRange();
       * doc.getBody().setTextStyle(range, { bl: 1 });
       * ```
       */
      getRange(): IFDocTextRange;
      /**
       * Check whether this paragraph is a bullet, ordered, or checklist item.
       * @returns {boolean} `true` if the paragraph has list metadata.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * console.log(paragraph.isListItem());
       * ```
       */
      isListItem(): boolean;
      /**
       * Check whether this paragraph is a task/checklist item.
       * @returns {boolean} `true` if this paragraph is an unchecked or checked task item.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * if (paragraph.isTask()) {
       *     paragraph.setTaskChecked(true);
       * }
       * ```
       */
      isTask(): boolean;
      /**
       * Set the checked state of this task/checklist paragraph.
       * @param {boolean} checked Whether the task item should be checked.
       * @returns {boolean} `true` if the task state was updated, or `false` if this paragraph is not a task item.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const paragraph = doc.getBody().getChild(0).asParagraph();
       * if (paragraph.isTask()) {
       *     paragraph.setTaskChecked(false);
       * }
       * ```
       */
      setTaskChecked(checked: boolean): boolean;
  }

  /**
   * A facade wrapper for a document table marker.
   *
   * Table identity is backed by the persisted `ICustomTable.tableId`, so the
   * wrapper can be re-resolved after text is inserted before the table.
   *
   * @hideconstructor
   */
  class FDocTable {
      /**
       * Get the document element type.
       * @returns {'table'} The literal table element type.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const table = doc.getBody().getChild(0).asTable();
       * console.log(table.getType());
       * ```
       */
      getType(): 'table';
      /**
       * Get the table key.
       * @returns {string} The persisted `tableId` for this table.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const table = doc.getBody().getChild(0).asTable();
       * console.log(table.getKey());
       * ```
       */
      getKey(): string;
      /**
       * Get the parent body facade that owns this table.
       * @returns {FDocBody} The document body facade.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const table = doc.getBody().getChild(0).asTable();
       * console.log(table.getParent().getChildIndex(table));
       * ```
       */
      getParent(): FDocBody;
      /**
       * Remove this table from the parent body.
       * @returns {boolean} `true` if the table range was removed.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const table = doc.getBody().getChild(0).asTable();
       * table.removeFromParent();
       * ```
       */
      removeFromParent(): boolean;
      /**
       * Get the persisted table id.
       * @returns {string} The `ICustomTable.tableId` value.
       * @example
       * ```ts
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const table = doc.getBody().getChild(0).asTable();
       * console.log(table.getTableId());
       * ```
       */
      getTableId(): string;
  }

  interface IDocumentInsertTextFacadeOptions {
      startOffset?: number;
      endOffset?: number;
      segmentId?: string;
      cursorOffset?: number;
  }

  /**
   * Facade API object bounded to a document. It provides a set of methods to interact with the document.
   * @hideconstructor
   */
  class FDocument {
      readonly id: string;
      /**
       * Get the document data model of the document.
       * @returns {DocumentDataModel} The document data model.
       * @example
       * ```typescript
       * const fDocument = univerAPI.getActiveDocument();
       * const documentDataModel = fDocument.getDocumentDataModel();
       * console.log(documentDataModel);
       * ```
       */
      getDocumentDataModel(): DocumentDataModel;
      /**
       * Get the document body facade.
       *
       * The returned body facade provides synchronous Google Docs-like element APIs
       * for reading and editing top-level document body elements. Paragraph elements
       * use their persisted `paragraphId` values. Persisted elements, such as tables
       * and custom blocks, use their existing ids.
       *
       * @returns {FDocBody} The document body API instance.
       * @example
       * ```typescript
       * const doc = univerAPI.getActiveDocument();
       * if (!doc) throw new Error('No active document');
       *
       * const body = doc.getBody();
       * const paragraph = body.getChild(0).asParagraph();
       * paragraph.appendText(' updated');
       * ```
       */
      getBody(): FDocBody;
      dispose(): void;
      /**
       * Get the document id.
       * @returns {string} The document id.
       * @example
       * ```typescript
       * const fDocument = univerAPI.getActiveDocument();
       * const unitId = fDocument.getId();
       * console.log(unitId);
       * ```
       */
      getId(): string;
      /**
       * Get the document name.
       * @returns {string} The document name.
       * @example
       * ```typescript
       * const fDocument = univerAPI.getActiveDocument();
       * const name = fDocument.getName();
       * console.log(name);
       * ```
       */
      getName(): string;
      /**
       * Save the document snapshot data, including the document content and resource data, etc.
       * @returns {IDocumentData} The document snapshot data.
       * @example
       * ```typescript
       * const fDocument = univerAPI.getActiveDocument();
       * const snapshot = fDocument.save();
       * console.log(snapshot);
       * ```
       */
      save(): IDocumentData;
      /**
       * Undo the last operation in the document.
       * @returns {boolean} `true` if the undo operation was successful, or `false` if it failed.
       * @example
       * ```typescript
       * const fDocument = univerAPI.getActiveDocument();
       * const success = fDocument.undo();
       * console.log(success);
       * ```
       */
      undo(): boolean;
      /**
       * Redo the last undone operation in the document.
       * @returns {boolean} `true` if the redo operation was successful, or `false` if it failed.
       * @example
       * ```typescript
       * const fDocument = univerAPI.getActiveDocument();
       * const success = fDocument.redo();
       * console.log(success);
       * ```
       */
      redo(): boolean;
      /**
       * Adds the specified text to the end of this text region.
       * @param {string} text - The text to be added to the end of this text region.
       * @return {boolean} `true` if the text was successfully appended, or `false` if it failed.
       * @example
       * ```typescript
       * const fDocument = univerAPI.getActiveDocument();
       * const success = fDocument.appendText('Hello, world!');
       * console.log(success);
       * ```
       */
      appendText(text: string): boolean;
      /**
       * Inserts text at the provided document range. Defaults to appending before the final section break.
       * @param {string} text - The text to insert.
       * @param {IDocumentInsertTextFacadeOptions} options - Optional target range, segment id, and cursor offset.
       * @returns {boolean} `true` if the text was successfully inserted, or `false` if it failed.
       * @example
       *
       * // Insert text at a specific range in the document body
       * ```typescript
       * const fDocument = univerAPI.getActiveDocument();
       * const success = fDocument.insertText('Hello, world!', {
       *   startOffset: 5,
       *   endOffset: 5,
       *   segmentId: '',
       *   cursorOffset: 13,
       * });
       * console.log(success);
       * ```
       *
       * // Insert text at the beginning of a header or footer segment
       * ```typescript
       * const fDocument = univerAPI.getActiveDocument();
       * const snapshot = fDocument.save();
       * const { headers, footers } = snapshot;
       *
       * if (headers) {
       *   for (const headerId in headers) {
       *     if (headerId === 'target-header-id') {
       *       fDocument.insertText('Hello, header!', {
       *         startOffset: 0,
       *         endOffset: 0,
       *         segmentId: headerId,
       *       });
       *     }
       *   }
       * }
       *
       * if (footers) {
       *   for (const footerId in footers) {
       *     if (footerId === 'target-footer-id') {
       *       fDocument.insertText('Hello, footer!', {
       *         startOffset: 0,
       *         endOffset: 0,
       *         segmentId: footerId,
       *       });
       *     }
       *   }
       * }
       * ```
       */
      insertText(text: string, options?: IDocumentInsertTextFacadeOptions): boolean;
      /**
       * Inserts one or more plain-text paragraphs at the provided document range.
       * @param {string} text - The paragraph text to insert. Newlines are normalized to document paragraph separators.
       * @param {IDocumentInsertTextFacadeOptions} options - Optional target range, segment id, and cursor offset.
       * @returns {boolean} `true` if the paragraphs were successfully inserted, or `false` if it failed.
       * @example
       * ```typescript
       * const fDocument = univerAPI.getActiveDocument();
       * const success = fDocument.insertParagraph('Hello, world! This is a new paragraph.', {
       *   startOffset: 5,
       *   endOffset: 5,
       * });
       * console.log(success);
       * ```
       */
      insertParagraph(text?: string, options?: IDocumentInsertTextFacadeOptions): boolean;
  }

  interface IFUniverDocsMixin {
      /**
       * Create a new document and get the API handler of that document.
       * @param {Partial<IDocumentData>} data The snapshot of the document.
       * @returns {FDocument} The document API instance.
       * @example
       * ```typescript
       * const fDocument = univerAPI.createUniverDoc({ id: 'document-01', title: 'Document1'  });
       * console.log(fDocument);
       * ```
       */
      createDocument(data: Partial<IDocumentData>): FDocument;
      /**
       * Get the currently focused Univer document.
       * @returns {FDocument | null} The currently focused Univer document API instance, or null if there is no focused Univer document.
       * @example
       * ```typescript
       * const fDocument = univerAPI.getActiveDocument();
       * console.log(fDocument);
       * ```
       */
      getActiveDocument(): FDocument | null;
      /**
       * Get the document API handler by the document id.
       * @param {string} id The document id.
       * @returns {FDocument | null} The document API instance corresponding to the document id, or null if not found.
       * @example
       * ```typescript
       * const fDocument = univerAPI.getDocument('document-01');
       * console.log(fDocument);
       * ```
       */
      getDocument(id: string): FDocument | null;
  }

  class FUniverDocsMixin {
      createDocument(data: Partial<IDocumentData>): FDocument;
      getActiveDocument(): FDocument | null;
      getDocument(id: string): FDocument | null;
  }
}

declare module "@univerjs/core/facade" {
  import type { IFUniverDocsMixin } from "@univerjs/docs/facade";

  interface FUniver extends IFUniverDocsMixin {
  }
}
