// Type definitions for richtexteditor 2.x
// Project: https://richtexteditor.com
//
// These declarations cover the public surface documented at
// https://richtexteditor.com/docs and exercised by the React / Vue
// wrappers in this package. The editor itself is shipped as a single
// bundle (`richtexteditor/rte.js`) that attaches `RichTextEditor` to
// the global scope; the typings below describe both the constructor
// and the per-instance methods.

// =====================
// Structured content (JSON / Markdown)
// =====================

export type RichTextEditorValueFormat = "html" | "json";

export interface RichTextEditorStructuredMark {
  type: string;
  attrs?: Record<string, unknown>;
}

export interface RichTextEditorPageMargins {
  top?: string;
  right?: string;
  bottom?: string;
  left?: string;
}

export interface RichTextEditorPageSetup {
  format?: string;
  orientation?: "portrait" | "landscape";
  width?: string;
  height?: string;
  margins?: RichTextEditorPageMargins;
  headerHtml?: string;
  footerHtml?: string;
}

export interface RichTextEditorStructuredDocumentAttributes {
  pageSetup?: RichTextEditorPageSetup;
  [key: string]: unknown;
}

export interface RichTextEditorStructuredDocument {
  type: "doc";
  version: number;
  format: string;
  attrs?: RichTextEditorStructuredDocumentAttributes;
  html?: string;
  text?: string;
  content?: RichTextEditorStructuredNode[];
}

export interface RichTextEditorStructuredNode {
  type: string;
  attrs?: Record<string, unknown>;
  content?: RichTextEditorStructuredNode[];
  html?: string;
  marks?: RichTextEditorStructuredMark[];
  text?: string;
  [key: string]: unknown;
}

export interface RichTextEditorStructuredContentLike {
  html?: string;
  content?: RichTextEditorStructuredNode | RichTextEditorStructuredNode[];
  [key: string]: unknown;
}

export interface RichTextEditorValidationIssue {
  message: string;
  path: string;
}

export interface RichTextEditorValidationResult {
  document: RichTextEditorStructuredDocument;
  issues: RichTextEditorValidationIssue[];
  valid: boolean;
}

export type RichTextEditorAccessibilitySeverity = "error" | "warning";

export interface RichTextEditorAccessibilityIssue {
  code: string;
  message: string;
  path: string;
  severity: RichTextEditorAccessibilitySeverity;
}

export interface RichTextEditorAccessibilityRepairOptions {
  altText?: string;
  headingText?: string;
  targetLevel?: number;
}

export interface RichTextEditorAccessibilityResult {
  document: RichTextEditorStructuredDocument;
  issues: RichTextEditorAccessibilityIssue[];
  valid: boolean;
}

export type RichTextEditorLinkAuditSeverity = "error" | "warning";

export interface RichTextEditorLinkAuditIssue {
  code: string;
  href?: string;
  message: string;
  path: string;
  severity: RichTextEditorLinkAuditSeverity;
}

export interface RichTextEditorLinkAuditOptions {
  allowedDomains?: string[];
  allowedProtocols?: string[];
  flagNewWindowWithoutRel?: boolean;
  requireHttps?: boolean;
}

export interface RichTextEditorLinkAuditResult {
  document: RichTextEditorStructuredDocument;
  issues: RichTextEditorLinkAuditIssue[];
  valid: boolean;
}

export interface RichTextEditorTextStatistics {
  characters: number;
  charactersNoSpaces: number;
  words: number;
  selectedCharacters: number;
  selectedCharactersNoSpaces: number;
  selectedWords: number;
}

export interface RichTextEditorDocumentMetrics extends RichTextEditorTextStatistics {
  paragraphs: number;
  sentences: number;
  headings: number;
  images: number;
  tables: number;
  links: number;
  estimatedReadingMinutes: number;
}

export interface RichTextEditorDocumentOutlineItem {
  id: string;
  level: number;
  path: string;
  text: string;
}

export interface RichTextEditorTableOfContentsItem extends RichTextEditorDocumentOutlineItem {
  itemIndex?: number;
  indexLabel?: string;
  children: RichTextEditorTableOfContentsItem[];
}

export interface RichTextEditorFootnoteItem {
  id: string;
  number: number;
  path: string;
  refId: string;
  text: string;
}

export interface RichTextEditorTableOfContentsOptions {
  minLevel?: number;
  maxLevel?: number;
  indexMode?: "none" | "linear" | "hierarchical";
  title?: string;
  includeTitle?: boolean;
  ordered?: boolean;
  orderedListType?: "1" | "A" | "a" | "I" | "i";
}

export type RichTextEditorStructuredInput =
  | string
  | RichTextEditorStructuredDocument
  | RichTextEditorStructuredContentLike;

// =====================
// Commands
// =====================

/**
 * Built-in command identifiers accepted by execCommand / isCommandEnabled /
 * isCommandActive. The list is intentionally non-exhaustive — custom commands
 * registered via createToolbarButton are also valid execCommand inputs, hence
 * the `string` fallback.
 */
export type RichTextEditorCommand =
  | "bold" | "italic" | "underline" | "strikethrough" | "subscript" | "superscript"
  | "fontname" | "fontsize" | "forecolor" | "backcolor" | "removeformat"
  | "justifyleft" | "justifycenter" | "justifyright" | "justifyfull"
  | "indent" | "outdent" | "insertorderedlist" | "insertunorderedlist"
  | "insertimage" | "insertlink" | "unlink" | "inserthorizontalrule" | "insertpagebreak"
  | "inserttable" | "insertrowbefore" | "insertrowafter"
  | "insertcolumnbefore" | "insertcolumnafter" | "deleterow" | "deletecolumn" | "deletetable"
  | "undo" | "redo" | "selectall" | "copy" | "cut" | "paste"
  | "ucase" | "lcase" | "titlecase"
  | "source" | "fullscreen" | "preview" | "print"
  | "pastetext" | "pastefromword"
  | "paragraph" | "heading"
  | "documentoutline"
  | "contentminimap"
  | "accessibilitychecker"
  | "ai-ask" | "ai-chat" | "ai-review" | "ai-export-docx" | "ai-import-docx"
  | "dictation-toggle"
  // Modern block types (2.3.0) — backed by the blocktypes plugin.
  | "insertcallout" | "insertcolumns" | "inserttoggle"
  // Interactive to-do / task list (2.3.0) — backed by the todolist plugin.
  | "inserttodolist"
  // Equation editor (2.3.0) — backed by the mathdialog plugin.
  | "insertmath"
  // Mermaid diagram (2.3.0) — backed by the mermaiddiagram plugin.
  | "insertdiagram"
  // Bookmark preview card (2.3.0) — backed by the bookmarkcard plugin.
  | "insertbookmark"
  // Spell check (2.3.0) — backed by the spellcheck plugin.
  | "spellcheck"
  // Smart chips (2.3.0) — backed by the smartchips plugin.
  | "insertdatechip" | "insertchip"
  // Email toolkit (2.3.0) — backed by the emailtoolkit plugin.
  | "emailexport"
  // Read-aloud / text-to-speech (2.3.0) — backed by the readaloud plugin.
  | "readaloud"
  | string;

// =====================
// Selection
// =====================

export interface RichTextEditorSelection {
  /** The native Range, when one is available. */
  range?: Range;
  /** The selected control element (image / table / hr) or null for caret/text selections. */
  control?: Element | null;
  /** Whether the selection is collapsed (no range / caret only). */
  isCollapsed: boolean;
  /** Whether the selection covers the entire document. */
  isAll?: boolean;
  [key: string]: unknown;
}

// =====================
// AI Toolkit (v2.0)
// =====================

export type RichTextEditorAiOperationType =
  | "preview-suggestion"
  | "replace-document"
  | "insert-below"
  | "add-comment"
  | string;

export interface RichTextEditorAiOperation {
  type: RichTextEditorAiOperationType;
  text: string;
  reason?: string;
  [key: string]: unknown;
}

export interface RichTextEditorAiResponse {
  sourceLabel?: string;
  reason?: string;
  message?: string;
  result?: string;
  operations?: RichTextEditorAiOperation[];
  [key: string]: unknown;
}

export interface RichTextEditorAiRequest {
  mode: string;
  prompt?: string;
  source?: string;
  selectionText?: string;
  documentText?: string;
  hasSelection?: boolean;
  language?: string;
  [key: string]: unknown;
}

export interface RichTextEditorAiStreamHandle {
  abort(): void;
  promise?: Promise<RichTextEditorAiResponse | undefined>;
}

export interface RichTextEditorAiStreamRequestOptions {
  url: string;
  body: Record<string, unknown>;
  headers?: Record<string, string>;
  onDelta?(delta: string, accumulated: string): void;
  onResponse?(response: RichTextEditorAiResponse): void;
  onDone?(text: string): void;
  onError?(error: Error): void;
}

export interface RichTextEditorAiExportDocxOptions {
  filename?: string;
  fileName?: string;
  title?: string;
  url?: string;
  download?: boolean;
}

export interface RichTextEditorAiImportDocxOptions {
  file?: Blob | File | null;
  filename?: string;
  fileName?: string;
  url?: string;
  apply?: boolean;
  mode?: "replace" | "insert";
  onError?(error: Error): void;
}

export interface RichTextEditorAiToolkit {
  setResolver(
    resolver: (request: RichTextEditorAiRequest) => Promise<RichTextEditorAiResponse> | RichTextEditorAiResponse,
  ): void;
  openDialog(options?: { presetMode?: string; prompt?: string }): void;
  openChatPanel(options?: { focusComposer?: boolean }): void;
  openReviewPanel(): void;
  runQuickAction(mode: string, options?: Record<string, unknown>): Promise<RichTextEditorAiResponse | undefined>;
  streamRequest(options: RichTextEditorAiStreamRequestOptions): RichTextEditorAiStreamHandle;
  exportDocx(options?: RichTextEditorAiExportDocxOptions): Promise<Blob | undefined>;
  importDocx(options?: RichTextEditorAiImportDocxOptions): Promise<string | undefined>;
  refreshRemoteReviewState?(force?: boolean): Promise<void>;
  acceptInline?(text: string): void;
  rejectInline?(): void;
}

// =====================
// Dictation
// =====================

export interface RichTextEditorDictation {
  isSupported(): boolean;
  isListening(): boolean;
  start(options?: { language?: string; continuous?: boolean }): void;
  stop(): void;
  toggle(options?: { language?: string }): void;
}

// =====================
// Revision history
// =====================

export interface RichTextEditorRevisionEntry {
  id: string;
  name?: string;
  createdAt: number;
  html: string;
  authorId?: string;
  authorName?: string;
}

export interface RichTextEditorRevisionDiff {
  oldHtml: string;
  newHtml: string;
  unifiedDiff?: string;
}

export interface RichTextEditorRevisionHistory {
  snapshot(name?: string): RichTextEditorRevisionEntry;
  promptAndSnapshot(): Promise<RichTextEditorRevisionEntry | undefined>;
  rename(id: string, name: string): void;
  list(): RichTextEditorRevisionEntry[];
  listNamed(): RichTextEditorRevisionEntry[];
  diff(idA: string, idB: string): RichTextEditorRevisionDiff;
  restore(id: string): void;
  remove(id: string): void;
}

// =====================
// Yjs collab
// =====================

export interface RichTextEditorCollabAttachOptions {
  doc: unknown;
  provider: unknown;
  textSync?: boolean;
  awareness?: unknown;
  fragmentName?: string;
  /**
   * The Yjs module (the `* as Y` namespace). REQUIRED to be the SAME Yjs
   * instance that created `doc` and backs `provider` whenever the editor can't
   * find it on `window.Y`. The CRDT engine builds document nodes with this
   * module; mixing two Yjs copies throws "Unexpected content type in insert
   * operation" and silently breaks text sync (yjs issue #438).
   */
  Y?: unknown;
  /**
   * When attaching to an EMPTY shared document, seed it from the editor's
   * current content (first-writer) instead of clearing the editor. Default
   * `true`. Set `false` to always let the shared document win (the editor is
   * cleared if the shared doc is empty). Reconciliation waits for the
   * provider's initial sync so it never clobbers not-yet-synced remote state.
   */
  seedFromHost?: boolean;
}

export interface RichTextEditorCollab {
  attach(options: RichTextEditorCollabAttachOptions): void;
  detach(): void;
}

// =====================
// Slash commands / mentions / comments / review ledger
// =====================

export interface RichTextEditorSlashCommand {
  id: string;
  label: string;
  description?: string;
  icon?: string;
  group?: string;
  run(editor: RichTextEditorInstance, context?: unknown): void;
}

export interface RichTextEditorSlashCommands {
  register(command: RichTextEditorSlashCommand): void;
  remove(id: string): void;
  list(): RichTextEditorSlashCommand[];
}

export interface RichTextEditorMentionItem {
  id: string;
  name: string;
  meta?: unknown;
}

export interface RichTextEditorMentionProvider {
  trigger: string;
  search(query: string):
    | Promise<RichTextEditorMentionItem[]>
    | RichTextEditorMentionItem[];
  render?(item: RichTextEditorMentionItem): string;
}

export interface RichTextEditorMentions {
  register(provider: RichTextEditorMentionProvider): void;
  remove(trigger: string): void;
}

export interface RichTextEditorCommentEntry {
  id: string;
  authorId?: string;
  authorName?: string;
  text: string;
  createdAt: number;
  resolved?: boolean;
  parentId?: string;
}

export interface RichTextEditorComments {
  add(text: string, options?: { authorName?: string }): RichTextEditorCommentEntry;
  reply(parentId: string, text: string, options?: { authorName?: string }): RichTextEditorCommentEntry;
  resolve(id: string): void;
  delete(id: string): void;
  list(): RichTextEditorCommentEntry[];
}

export interface RichTextEditorRestrictedEditingMarkOptions {
  /** Optional aria-label to apply to the new wrapper span. */
  label?: string;
}

export interface RichTextEditorRestrictedEditing {
  isEnabled(): boolean;
  enable(): boolean;
  disable(): boolean;
  toggle(): boolean;
  /** Wrap the current selection in a `<span data-rte-editable="true">` so it remains editable when restricted mode is on. */
  markSelection(options?: RichTextEditorRestrictedEditingMarkOptions): Element | null;
  /** Remove the editable wrapper around the given node (or the current selection's wrapper). */
  unmark(node?: Element): boolean;
  list(): Element[];
  /** Move caret to the next editable region (wraps around). */
  goToNext(): Element | null;
  /** Move caret to the previous editable region. */
  goToPrev(): Element | null;
}

export interface RichTextEditorDocumentOutlinePanelItem {
  id: string;
  level: number;
  text: string;
  element: Element;
}

export interface RichTextEditorDocumentOutlinePanel {
  close(): void;
  list(): RichTextEditorDocumentOutlinePanelItem[];
  open(): void;
  refresh(): void;
  toggle(): void;
}

export interface RichTextEditorContentMinimap {
  close(): void;
  isOpen(): boolean;
  open(): void;
  refresh(): void;
  toggle(): void;
}

export interface RichTextEditorAccessibilityChecker {
  close(): void;
  getIssues(): RichTextEditorAccessibilityIssue[];
  open(): void;
  refresh(): RichTextEditorAccessibilityResult;
  repair(issueIndex: number, options?: RichTextEditorAccessibilityRepairOptions): RichTextEditorAccessibilityResult;
  run(): RichTextEditorAccessibilityResult;
  toggle(): void;
}

export interface RichTextEditorRestrictedEditingRegion {
  id: string;
  label?: string;
  element: Element;
}

export interface RichTextEditorRestrictedEditingMarkOptions {
  block?: boolean;
  id?: string;
  label?: string;
  placeholder?: string;
}

export interface RichTextEditorRestrictedEditing {
  clearSelectionRegion(): boolean;
  disable(): void;
  enable(): void;
  goToNext(): Element | null;
  goToPrevious(): Element | null;
  isEnabled(): boolean;
  list(): RichTextEditorRestrictedEditingRegion[];
  markSelection(options?: RichTextEditorRestrictedEditingMarkOptions): Element | null;
  refresh(): void;
  toggle(): boolean;
}

export type RichTextEditorReviewState = "pending" | "accepted" | "rejected" | string;

export interface RichTextEditorReviewLedgerEntry {
  id: string;
  state: RichTextEditorReviewState;
  text: string;
  reason?: string;
  createdAt: number;
  metadata?: Record<string, unknown>;
}

export interface RichTextEditorReviewLedger {
  add(entry: Omit<RichTextEditorReviewLedgerEntry, "id" | "createdAt"> & { id?: string }): RichTextEditorReviewLedgerEntry;
  update(id: string, patch: Partial<RichTextEditorReviewLedgerEntry>): RichTextEditorReviewLedgerEntry | undefined;
  remove(id: string): void;
  list(state?: RichTextEditorReviewState): RichTextEditorReviewLedgerEntry[];
  get(id: string): RichTextEditorReviewLedgerEntry | undefined;
}

// =====================
// Toolbar / dialog factories
// =====================

export interface RichTextEditorToolbarButtonOptions {
  text?: string;
  hint?: string;
  iconUrl?: string;
  shortcut?: string;
  click?(editor: RichTextEditorInstance): void;
  command?: string;
}

export interface RichTextEditorToolbarDropDownItem {
  text: string;
  value?: string | number;
  hint?: string;
  className?: string;
}

export interface RichTextEditorToolbarDropDownOptions {
  width?: string | number;
  items: RichTextEditorToolbarDropDownItem[];
  onSelect?(value: string | number, item: RichTextEditorToolbarDropDownItem): void;
}

export interface RichTextEditorDialogOptions {
  title?: string;
  width?: string | number;
  height?: string | number;
  /** Inner HTML for the dialog body (alternative to `html`). */
  body?: string;
  html?: string;
  /** Buttons rendered in the dialog footer. Defaults to OK / Cancel when omitted. */
  buttons?: Array<{
    text: string;
    isDefault?: boolean;
    isCancel?: boolean;
    click?(): void;
  }>;
  onClose?(): void;
}

// =====================
// Events
// =====================

/**
 * Built-in editor events. Custom events fired by plugins are also valid
 * (matched by the `string` fallback).
 *
 * - `change` — fired after editable content changes (content edits, paste,
 *   undo/redo, AI replacement). Handler signature: `() => void`.
 * - `selectionchange` — fired after the selection moves (caret move, range
 *   change, control selection). Handler signature: `() => void`.
 * - `exec_command` — fired when a toolbar / shortcut command runs. Handler
 *   signature: `(commandName: string, value?: unknown) => void`.
 * - `change_html_view` — fired when the editor toggles between Design and
 *   HTML/source modes. Handler signature: `(isHtmlView: boolean) => void`.
 * - `keydown` / `keyup` / `keypress` — pass-through of editable keyboard
 *   events. Handler signature: `(event: KeyboardEvent) => void`.
 * - `focus` / `blur` — editable focus / blur. Handler signature:
 *   `(event: FocusEvent) => void`.
 */
export type RichTextEditorEventName =
  | "change"
  | "selectionchange"
  | "exec_command"
  | "change_html_view"
  | "keydown" | "keyup" | "keypress"
  | "focus" | "blur"
  // Reserved for the AI toolkit — not yet emitted by the current build.
  | "ai_request" | "ai_response" | "ai_review_added" | "ai_review_resolved"
  | "comment_added" | "comment_resolved"
  | "revision_snapshot"
  | "charlimit" | "commentsonlychanged" | "contentchange" | "resize" | "customdialog"
  | string;

export type RichTextEditorEventHandler = (...args: any[]) => void;

// =====================
// Editor instance
// =====================

export interface RichTextEditorReadabilityStats {
  words: number;
  sentences: number;
  syllables: number;
  characters: number;
  avgWordsPerSentence: number;
  avgSyllablesPerWord: number;
  /** Flesch Reading Ease (higher = easier; ~0–100 typical). */
  fleschReadingEase: number;
  /** Flesch–Kincaid US grade level (clamped at 0). */
  fleschKincaidGrade: number;
  readingTimeMinutes: number;
  /** Human-readable reading time, e.g. "3 min" or "20 sec". */
  readingTimeText: string;
  /** Plain-language interpretation of the reading-ease score. */
  easeLabel: string;
}

export interface RichTextEditorImportOptions {
  /** `replace` (default) swaps the whole document; `insert` adds at the caret. */
  mode?: "replace" | "insert";
  /** `accept` attribute for the file picker (default `.md,.markdown,.html,.htm,.txt,.doc,.docx`). */
  accept?: string;
}

export interface RichTextEditorWordExportOptions {
  /** Document title (defaults to the first heading). */
  title?: string;
  /** Body font-family (default `"Calibri, 'Segoe UI', Arial, sans-serif"`). */
  fontFamily?: string;
  /** Body font-size (default `"11pt"`). */
  fontSize?: string;
  /** `@page` size (default `"8.5in 11in"`). */
  pageSize?: string;
  /** `@page` margin (default `"1in"`). */
  margin?: string;
  /** Landscape orientation (default `false`). */
  landscape?: boolean;
}

export interface RichTextEditorInstance {
  // ---- Lifecycle / events ----

  /** Subscribe to an editor event. See {@link RichTextEditorEventName}. */
  attachEvent(name: RichTextEditorEventName, handler: RichTextEditorEventHandler): void;
  /** Unsubscribe from an editor event. */
  detachEvent(name: RichTextEditorEventName, handler: RichTextEditorEventHandler): void;

  /** Move keyboard focus into the editable area. */
  focus(): void;

  // ---- Content I/O ----

  /** Returns the current HTML string. */
  getHTMLCode(): string;
  /** Replaces editable content with the provided HTML and resets undo stack. */
  setHTMLCode(html: string): unknown;
  /** Returns the document as plain text (no markup). */
  getPlainText(): string;
  // The structured-content instance methods below are installed by the
  // structured-content bridge. The React/Vue/Angular wrappers install it
  // automatically; in any other setup call
  // `require("@richscripts/richtexteditor/integrations/shared").installStructuredContentBridge()`
  // once before relying on them. They are typed optional because a plain
  // `<script src="rte.js">` editor does not have them.
  /** Returns word/character statistics for the current document and selection. Requires the structured-content bridge. */
  getTextStatistics?(): RichTextEditorTextStatistics;
  /** Returns word/character statistics for the current selection only. Requires the structured-content bridge. */
  getSelectionStatistics?(): RichTextEditorTextStatistics;
  /** Returns richer document metrics including structure counts and estimated reading time. Requires the structured-content bridge. */
  getDocumentMetrics?(): RichTextEditorDocumentMetrics;
  /** Returns document footnotes in numeric/source order for review/sidebar workflows. Requires the structured-content bridge. */
  getFootnotes?(): RichTextEditorFootnoteItem[];
  /** Returns document-level page setup metadata used by JSON/HTML export workflows. Requires the structured-content bridge. */
  getDocumentPageSetup?(): RichTextEditorPageSetup | null;
  /** Returns the document as a structured-content JSON document. Requires the structured-content bridge. */
  getJSON?(): RichTextEditorStructuredDocument;
  /** Updates document-level page setup metadata and reapplies the document JSON. Requires the structured-content bridge. */
  setDocumentPageSetup?(pageSetup: RichTextEditorPageSetup | null): this;
  /** Replaces editable content from a structured-content JSON document or HTML string. Requires the structured-content bridge. */
  setJSON?(value: RichTextEditorStructuredInput): this;

  // ---- Read-only mode ----

  /** Returns the current read-only state. */
  getReadOnly(): boolean;
  /** Toggles the read-only state. When read-only, the editor blocks edits but keeps selection / scroll behaviour. */
  setReadOnly(readOnly: boolean): void;
  /** Returns whether the editor is in comments-only mode (content locked, comment workflows enabled). */
  getCommentsOnly(): boolean;
  /** Toggles comments-only mode without enabling full content editing. */
  setCommentsOnly(commentsOnly: boolean): void;

  // ---- Commands ----

  /**
   * Execute a toolbar / shortcut command. Most browser-native commands are
   * supported (`bold`, `italic`, `insertimage`, …) along with a number of
   * editor-specific commands (`source`, `fullscreen`, `ai-ask`, …).
   */
  execCommand(command: RichTextEditorCommand, value?: unknown): unknown;
  /** Returns true when the command is enabled in the current selection context. */
  isCommandEnabled(command: RichTextEditorCommand): boolean;
  /** Returns true when the command's effect is currently active (e.g. selection is bold). */
  isCommandActive(command: RichTextEditorCommand): boolean;

  // ---- Math (inline equations) ----
  /**
   * Wrap `$...$` runs in `<span class="rte-math-inline" data-tex="...">` so a
   * host-loaded math renderer can target them. Returns the number of runs wrapped.
   * No-op when `config.inlineMath === false`.
   */
  applyMathMarkup(): number;
  /**
   * Run `applyMathMarkup()` then render every `.rte-math-inline` span via a
   * math renderer detected on the host page (KaTeX, then MathJax v3+). Leaves
   * the markup intact when no renderer is present. Returns the span count.
   */
  renderMath(): number;

  // ---- Mermaid diagrams ----
  /**
   * Render every `.rte-mermaid` diagram block in the editor. Uses
   * `config.diagramResolver` (server-side render) if provided, else a
   * `window.mermaid` instance loaded by the host page; falls back to showing the
   * Mermaid source when neither is present. The source always round-trips in
   * `data-diagram`, so blocks stay editable. Returns the block count.
   */
  renderDiagrams(): number;

  // ---- Email export ----
  /**
   * Return email-client-safe HTML: a curated set of computed styles is inlined
   * onto each element as `style=""`, class/id removed, and (by default) the
   * content wrapped in a centered max-width table. Email clients strip `<style>`
   * and classes, so this produces HTML that renders correctly in Outlook/Gmail.
   */
  getEmailHTML(options?: { wrap?: boolean; width?: number }): string;

  // ---- Read aloud (text-to-speech) ----
  /**
   * Read the current selection (or the whole document if nothing is selected)
   * aloud via the browser's Web Speech API, sentence by sentence, highlighting
   * each sentence as it is spoken. No content is modified. Options: `rate`
   * (0.5–2), `voice` (a `SpeechSynthesisVoice.name`).
   */
  readAloud(options?: { rate?: number; voice?: string }): void;
  /** Stop any in-progress read-aloud and restore the caret/selection. */
  stopReadAloud(): void;

  // ---- Auto-embed ----
  /**
   * Programmatically convert a media URL (YouTube / Vimeo by default) into a
   * responsive embed at the caret. Returns `true` if the URL resolved to a
   * supported provider. The iframe src is rebuilt from a sanitized video id, never
   * the raw input. The same conversion happens automatically when a bare media URL
   * is pasted on its own line (see `config.autoEmbedEnabled`).
   */
  embedUrl(url: string): boolean;

  // ---- Foldable headings ----
  /** Collapse/expand the section beneath a heading element (everything up to the next heading of the same or higher level). */
  toggleHeadingFold(heading: Element): void;
  /** Fold the section enclosing the caret (its heading, or the nearest preceding heading). Returns `true` if a heading was found. */
  foldAtCaret(): boolean;
  /** Expand every collapsed heading section. */
  unfoldAll(): void;

  // ---- Typewriter / focus writing modes ----
  /** Turn typewriter scrolling (caret line pinned to a fixed vertical anchor) on or off. Returns the new state. */
  setTypewriterMode(on: boolean): boolean;
  /** Toggle typewriter scrolling. Returns the new state. */
  toggleTypewriterMode(): boolean;
  /** `true` if typewriter scrolling is active. */
  isTypewriterMode(): boolean;
  /** Turn focus mode (dim every block except the one with the caret) on or off. Returns the new state. */
  setFocusMode(on: boolean): boolean;
  /** Toggle focus mode. Returns the new state. */
  toggleFocusMode(): boolean;
  /** `true` if focus mode is active. */
  isFocusMode(): boolean;

  // ---- Accessibility ----
  /** Re-apply the assistive-technology metadata (iframe title, editing-region role/aria-label, document lang). Called automatically on init and remount. */
  applyAccessibilityMetadata(): void;
  /** Re-apply dialog accessibility (role="dialog" + aria-label on dialog popups, aria-labels on their fields). Called automatically when dialogs open. */
  applyDialogAccessibility(): void;

  // ---- Markdown export ----
  /** Serialize the document to Markdown (friendly alias for the core `toMarkdown()` engine). */
  getMarkdown(): string;
  /** Copy the document to the clipboard as Markdown. Returns a promise that resolves `true` on success. Call from a user gesture. */
  copyAsMarkdown(): Promise<boolean>;
  /** Download the document as a `.md` file. `filename` is optional (derived from the first heading when omitted). Returns `true` if the download was triggered. */
  downloadMarkdown(filename?: string): boolean;

  // ---- Word export ----
  /** Build a Word-compatible HTML document string (MSO namespaces + page setup) from the current content. */
  getWordDocument(options?: RichTextEditorWordExportOptions): string;
  /** Download the document as a `.doc` Word file (opens natively in Word / LibreOffice). `filename` optional (derived from the first heading). Returns `true` if the download was triggered. */
  exportToWord(filename?: string, options?: RichTextEditorWordExportOptions): boolean;
  /** Alias of `exportToWord`. */
  downloadWord(filename?: string, options?: RichTextEditorWordExportOptions): boolean;

  // ---- Document import ----
  /** Open a file picker and import the chosen file (Markdown/HTML/text/Word `.doc`) into the editor. */
  openImportDialog(options?: RichTextEditorImportOptions): boolean;
  /** Import a `File` object. Resolves `true` if content was loaded. `.docx` needs `documentImportResolver`. */
  importFile(file: File, options?: RichTextEditorImportOptions): Promise<boolean>;
  /** Convert text to HTML for a given kind (`md` | `html` | `txt` | `doc`) without applying it. */
  htmlFromImportText(text: string, kind: "md" | "html" | "txt" | "doc"): string;

  // ---- Readability statistics ----
  /** Compute instant, local readability metrics for the current content (or `text`). */
  getReadabilityStats(text?: string): RichTextEditorReadabilityStats;
  /** Heuristic English syllable count for a single word. */
  countSyllables(word: string): number;

  // ---- Find & replace ----
  /** Open the built-in Find &amp; Replace dialog (live match highlighting + replace-all). Also reachable via the `/find` slash command. */
  openFindDialog(): void;
  /** Highlight every occurrence of `query` in the document and return the match count. */
  findHighlight(query: string): { matches: number };
  /** Open the keyboard-shortcut cheat sheet modal (also bound to Ctrl/Cmd+/ and the `/shortcuts` slash command). */
  showShortcuts(): void;

  // ---- Character / word limit ----
  /** Current character count (plain text, no markup). */
  getCharCount(): number;
  /** Current word count. */
  getWordCount(): number;
  /** Remaining characters before `maxLength`, or `null` when no `maxLength` is set. */
  getRemainingChars(): number | null;
  /** Whether the content exceeds the configured `maxLength`/`maxWords`. */
  isOverLimit(): boolean;

  // ---- Local draft autosave / recovery ----
  /** Persist the current document to localStorage immediately. Returns `true` on success. */
  saveLocalDraft(): boolean;
  /** `true` if a stored (non-expired) local draft exists for this editor. */
  hasLocalDraft(): boolean;
  /** The stored draft `{ html, t }` (t = epoch ms), or `null`. */
  getLocalDraft(): { html: string; t: number } | null;
  /** Apply the stored local draft to the editor. Returns `true` if one was restored. */
  restoreLocalDraft(): boolean;
  /** Delete the stored local draft (call after a successful server save). */
  clearLocalDraft(): boolean;

  // ---- AI ghost-text autocomplete ----
  /** Set (or clear with `null`) the resolver that produces inline completions. */
  setGhostTextResolver(fn: ((context: { before: string; after: string; full: string }) => string | Promise<string>) | null): void;
  /** Manually request an inline ghost-text suggestion at the caret. */
  requestGhostText(): void;
  /** Accept the currently-shown ghost suggestion (inserts it). Returns `true` if one was accepted. */
  acceptGhostText(): boolean;
  /** Dismiss the currently-shown ghost suggestion without inserting it. */
  dismissGhostText(): void;
  /** `true` while a ghost suggestion is being shown. */
  hasGhostText(): boolean;

  // ---- Theming ----

  /** Replaces the editable area's content stylesheet with raw CSS. */
  setContentCssText(css: string): void;
  /** Replaces the preview pane stylesheet with raw CSS. */
  setPreviewCssText(css: string): void;

  // ---- Insertion / selection helpers ----

  /** Inserts a new root paragraph at the current selection. */
  insertRootParagraph(): void;
  /** Wraps the current selection in a new element with the given tag name. */
  insertByTagName(tagName: string): Element | null;
  /** Surrounds the selection with the given tag name (e.g. `"strong"`, `"mark"`). */
  surroundByTagName(tagName: string): Element | null;
  /** Inserts the supplied element at the current selection. */
  insertElement(element: Element): Element;
  /** Surrounds the selection with the supplied element. */
  surroundElement(element: Element): Element;
  /** Inserts plain text (non-HTML) at the caret. */
  insertText(text: string): void;
  /** Inserts a raw HTML fragment at the caret. */
  insertHTML(html: string): void;

  /** Selects the supplied control (image / table / hr). */
  selectControl(element: Element): void;
  /** Selects the entire document. */
  selectDoc(): void;
  /** Collapses the current selection. */
  collapse(toEnd?: boolean): void;
  /** Deletes the current selection. */
  delete(): void;

  /** Persists the current caret position so it can be restored after a popup closes. */
  commitBookmark(): void;
  /** Resets the undo / redo stack. */
  clearHistory(): void;
  /** Re-evaluates toolbar enabled / active states. Useful after programmatic mutations. */
  notifySelectionChange(): void;

  // ---- DOM accessors ----

  /** Returns the editable Document (iframe document or main document for non-iframe mode). */
  getDocument(): Document;
  /** Returns the editable element (iframe body, or contenteditable host). */
  getEditable(): HTMLElement;
  /** Returns a serialized snapshot of the current selection. */
  getSelection(): RichTextEditorSelection;
  /** Returns the currently selected control element (image / table / hr) or null. */
  getSelectedControl(): Element | null;
  /** Returns the closest element ancestor of the current selection. */
  getSelectionElement(): Element | null;
  /** Returns the selected text as a plain string. */
  getSelectedText(): string;

  // ---- HTML helpers ----

  /** HTML-encodes a string (escapes `&`, `<`, `>`, `"`). */
  htmlEncode(value: string): string;
  /** Reverses {@link htmlEncode}. */
  htmlDecode(value: string): string;

  // ---- UI factories ----

  /** Creates a custom toolbar button. */
  createToolbarButton(id: string, options: RichTextEditorToolbarButtonOptions): unknown;
  /** Creates a custom toolbar drop-down. */
  createToolbarDropDown(id: string, options: RichTextEditorToolbarDropDownOptions): unknown;
  /** Opens a custom dialog. */
  createDialog(options: RichTextEditorDialogOptions): unknown;
  /** Closes the currently active popup dialog (if any). */
  closeCurrentPopup(): void;

  /** Replaces the icon shown for a command. */
  setImageForCommand(command: string, iconUrl: string): void;

  // ---- Optional v2.0 surfaces (presence depends on config / plugin loading) ----

  /** AI Toolkit (proofread / rewrite / chat / review). Present when `enable-ai-toolkit` / `config.enableAiToolkit` is true. */
  aiToolkit?: RichTextEditorAiToolkit;

  /** Web Speech API dictation helper. */
  dictation?: RichTextEditorDictation;

  /** Local + named revision history. */
  revisionHistory?: RichTextEditorRevisionHistory;

  /** Yjs-based real-time collaboration. */
  collab?: RichTextEditorCollab;

  /** Slash-command menu (/<command> at start of line). */
  slashCommands?: RichTextEditorSlashCommands;

  /** @-mention / #-tag pickers. */
  mentions?: RichTextEditorMentions;

  /** Inline comments + threaded replies. */
  comments?: RichTextEditorComments;

  /** Word-style "protect document with editable regions" — lock the
   * document except for spans tagged `data-rte-editable="true"`. */
  restrictedEditing?: RichTextEditorRestrictedEditing;

  /** Live heading sidebar for in-editor document navigation. */
  documentOutline?: RichTextEditorDocumentOutlinePanel;

  /** Scroll-aware miniature document preview for long-form navigation. */
  contentMinimap?: RichTextEditorContentMinimap;

  /** In-editor accessibility audit and repair workflow. */
  accessibilityChecker?: RichTextEditorAccessibilityChecker;

  /** Persistent review ledger (pending / accepted / rejected). */
  reviewLedger?: RichTextEditorReviewLedger;

  /** Escape hatch for plugin-attached APIs not covered by these declarations. */
  [key: string]: unknown;
}

// =====================
// Constructor
// =====================

export interface RichTextEditorConfig {
  toolbar?: string | string[];
  height?: string | number;
  width?: string | number;
  iframe?: boolean;
  showSource?: boolean;
  contentCssUrl?: string;
  contentCssText?: string;
  enableAiToolkit?: boolean;
  enableStructuredContent?: boolean;
  enableRevisionHistory?: boolean;
  enableComments?: boolean;
  enableMentions?: boolean;
  enableSlashCommands?: boolean;
  enableTrackChanges?: boolean;
  enableYjsCollab?: boolean;
  enableDictation?: boolean;
  showStatistics?: boolean;
  statisticsDisplayMode?: "characters" | "words" | "both";
  statisticsShowSelection?: boolean;
  placeholder?: string;
  placeholderShowOnlyWhenEditable?: boolean;
  placeholderColor?: string;
  commentsOnly?: boolean;
  documentOutlineEnabled?: boolean;
  documentOutlineAutoOpen?: boolean;
  documentOutlineTitle?: string;
  documentOutlineHint?: string;
  documentOutlineEmptyText?: string;
  documentOutlineMinLevel?: number;
  documentOutlineMaxLevel?: number;
  contentMinimapEnabled?: boolean;
  contentMinimapAutoOpen?: boolean;
  contentMinimapTitle?: string;
  contentMinimapHint?: string;
  contentMinimapEmptyText?: string;
  contentMinimapWidth?: number;
  contentMinimapScale?: number;
  accessibilityCheckerEnabled?: boolean;
  accessibilityCheckerAutoOpen?: boolean;
  accessibilityCheckerTitle?: string;
  accessibilityCheckerHint?: string;
  accessibilityCheckerEmptyText?: string;
  restrictedEditingEnabled?: boolean;
  restrictedEditingMode?: boolean;
  restrictedEditingEditableAttr?: string;
  restrictedEditingEditableClassName?: string;
  restrictedEditingNavigable?: boolean;
  showTagList?: boolean;
  showFloatTextToolBar?: boolean;
  showFloatParagraph?: boolean;
  editorResizeMode?: "both" | "horizontal" | "vertical" | "none";
  /**
   * Notion-style block drag handles (2.3.0): hovering a top-level block shows a
   * ⋮⋮ handle to drag-reorder blocks. Default: `true`. Set `false` to disable.
   */
  blockDragHandles?: boolean;

  // ---- Auto-formatting on type ----
  /** Type a URL / email followed by space → auto-wraps it in an `<a>`. Default: `true`. */
  autoLinkOnType?: boolean;
  /** Auto-assign stable slug IDs to `<h1>`–`<h6>` so deep links / TOC navigation work. Default: `true`. */
  autoHeadingAnchors?: boolean;
  /** Show a 🔗 "copy link" icon on hover over `<h1>`–`<h6>`. Default: `true`. */
  copyHeadingLink?: boolean;
  /** Master toggle for smart typography (curly quotes, em-dash, ellipsis, trademarks). Default: `true`. */
  smartTypography?: boolean;
  /** `--` → em-dash on type. Default: `true`. */
  smartTypographyDashes?: boolean;
  /** `...` → `…` on type. Default: `true`. */
  smartTypographyEllipsis?: boolean;
  /** `(c)` → ©, `(r)` → ®, `(tm)` → ™. Default: `true`. */
  smartTypographyTrademarks?: boolean;
  /** Straight quotes → curly quotes (apostrophe-aware). Default: `true`. */
  smartTypographyQuotes?: boolean;
  /** Markdown-style **block** shortcuts: `# `/`## `/`### ` → headings, `> ` → blockquote, `- `/`* ` → bullet list, `1. ` → numbered list, `---`/`***`/`___` + Enter → `<hr>`. Default: `true`. */
  markdownShortcutsEnabled?: boolean;
  /** Markdown-style **inline** autoformat, applied when the closing delimiter is typed: `**bold**`/`__bold__` → `<strong>`, `*italic*`/`_italic_` → `<em>`, `` `code` `` → `<code>`, `~~strike~~` → `<s>`. Opening delimiter must sit at a word boundary (math, globs and snake_case are left alone). Default: `true`. */
  markdownInlineEnabled?: boolean;
  /** Right-click on selected text shows AI menu (Ask AI / Rewrite / Summarize / Translate). Default: `true`. */
  aiContextMenu?: boolean;

  // ---- Paste pipeline knobs ----
  /**
   * Show a brief "Cleaned from Word / Google Docs / LibreOffice / Notion / Excel / Confluence"
   * toast after the paste cleanup pipeline strips Office-source artefacts. Default: `true`.
   */
  smartPasteToast?: boolean;
  /**
   * When pasting a URL / email while text is selected, wrap the selection in `<a href>`
   * instead of replacing it. Matches Google Docs / Notion / TipTap / ProseMirror
   * behavior. Default: `true`.
   */
  smartLinkPaste?: boolean;
  /**
   * Paste mode override. `"text"` / `"pastetext"` forces plain-text paste; `"word"` /
   * `"pasteword"` runs the Word-paste cleanup pipeline even on non-Word HTML; `"disable"`
   * / `"disabled"` blocks paste entirely.
   */
  pasteMode?: "text" | "pastetext" | "word" | "pasteword" | "disable" | "disabled";

  // ---- Modern block types (2.3.0) ----
  /**
   * Callout/admonition variants offered by the callout block. Each entry is
   * `{ id, label, icon }`; `icon` is a string (emoji or text) shown in the
   * callout. Defaults to info / success / warning / danger / note.
   */
  calloutTypes?: Array<{ id: string; label: string; icon: string }>;
  /** Default callout variant id used when inserting without an explicit type. Default: `"info"`. */
  calloutDefaultType?: string;
  /** Default column count for the columns block (clamped 2–4). Default: `2`. */
  columnsDefaultCount?: number;

  // ---- Equation editor (2.3.0) ----
  /**
   * When true, `editor.applyMathMarkup()` wraps `$...$` runs in
   * `<span class="rte-math-inline" data-tex="...">` so a host-loaded math
   * renderer (KaTeX / MathJax) can target them, and the equation-editor dialog
   * (`insertmath`) is available. Default: `true`.
   */
  inlineMath?: boolean;
  /** Sample equations shown as quick-insert chips in the equation-editor dialog. */
  mathDialogSamples?: string[];

  // ---- Bookmark preview cards (2.3.0) ----
  /**
   * Optional resolver for rich bookmark previews. Given a URL, return a promise
   * of `{ title, description, image, favicon }` (any field optional). When omitted,
   * the `insertbookmark` command renders a basic card from the URL + favicon.
   */
  bookmarkResolver?: (url: string) => Promise<{ title?: string; description?: string; image?: string; favicon?: string }>;
  /**
   * Favicon service URL prefix (the page domain is appended + URL-encoded). Defaults
   * to the public Google s2 favicon endpoint. Set to `""` to disable favicon fetch.
   */
  bookmarkFaviconService?: string;

  // ---- Spell check (2.3.0) ----
  /**
   * When true (default), the editable carries `spellcheck="true"` so the browser's
   * native checker underlines misspellings.
   */
  spellCheckEnabled?: boolean;
  /**
   * Optional spell-check service (BYOK). Given the document text, return a promise
   * of issues `[{ word, offset?, length?, suggestions: string[] }]`. When set, the
   * `spellcheck` command opens a review panel with click-to-replace suggestions;
   * when omitted it falls back to the browser's native spell-check.
   */
  spellCheckResolver?: (text: string) => Promise<Array<{ word: string; offset?: number; length?: number; suggestions?: string[] }>>;

  // ---- Smart chips (2.3.0) ----
  /**
   * Optional resolver for Person / Link smart chips (BYOK). Given a query and chip
   * type, return a promise of `[{ label, value, icon?, href? }]`. Date chips need
   * no resolver. When omitted, Person/Link chips fall back to a plain text input.
   */
  chipResolver?: (query: string, type: "person" | "link") => Promise<Array<{ label?: string; value?: string; icon?: string; href?: string }>>;
  /** Optional date formatter for date chips: `(date: Date) => string`. Defaults to "Mon D, YYYY". */
  chipDateFormat?: (date: Date) => string;

  // ---- Email export (2.3.0) ----
  /**
   * Whitelist of CSS properties inlined onto each element by `getEmailHTML()`.
   * Kept small by default to avoid bloat. Provide your own array to widen or
   * narrow the set. Defaults to color/background/font/text/spacing/border props.
   */
  emailInlineProperties?: string[];
  /** Max content width (px) of the centered table `getEmailHTML()` wraps content in. Default 640. */
  emailWrapWidth?: number;

  // ---- Mermaid diagrams (2.3.0) ----
  /**
   * Optional server-side diagram renderer (BYOK). Given Mermaid source, return a
   * promise of `{ svg }` or `{ imageUrl }` (e.g. a Kroki endpoint). When omitted,
   * the plugin uses a `window.mermaid` instance loaded by the host page, and
   * falls back to showing the source when neither is available.
   */
  diagramResolver?: (source: string) => Promise<{ svg?: string; imageUrl?: string }>;
  /** Starter Mermaid snippets shown as chips in the diagram dialog. */
  diagramSamples?: string[];

  // ---- Auto-embed (2.3.0) ----
  /** Auto-convert a bare YouTube/Vimeo URL pasted on its own line into a responsive embed. Default `true`. */
  autoEmbedEnabled?: boolean;
  /**
   * Optional resolver to support providers beyond the built-in YouTube/Vimeo.
   * Given a pasted URL, return a trusted `https://` provider embed URL (used as
   * the iframe src) or `null` to decline.
   */
  autoEmbedResolver?: (url: string) => string | null;

  // ---- Foldable headings (2.3.0) ----
  /** Enable collapsible heading sections (gutter chevron + `toggleHeadingFold`/`foldAtCaret`/`unfoldAll`). Default `true`. */
  foldHeadingsEnabled?: boolean;

  // ---- Typewriter / focus writing modes (2.3.0) ----
  /** Start with typewriter scrolling active (caret line pinned to a fixed vertical anchor). Default `false`. Toggle at runtime via `toggleTypewriterMode`. */
  typewriterModeEnabled?: boolean;
  /** Start with focus mode active (dim every block except the current one). Default `false`. Toggle at runtime via `toggleFocusMode`. */
  focusModeEnabled?: boolean;
  /** Fraction (0.15–0.85) of the viewport height the caret line is held at in typewriter mode. `0.5` = vertical centre (default). */
  typewriterAnchor?: number;

  // ---- Markdown export (2.3.0) ----
  /** Enable the Copy/Download-as-Markdown commands and `getMarkdown`/`copyAsMarkdown`/`downloadMarkdown` API. Default `true`. */
  markdownExportEnabled?: boolean;

  // ---- Word export (2.3.2) ----
  /** Enable Export-to-Word (`exportToWord`/`getWordDocument` API, `exportword` command, `/export word` slash). Default `true`. */
  wordExport?: boolean;
  /** Default base file name for `exportToWord()` (derived from the first heading when unset). */
  wordExportFileName?: string;
  /** Body font-family for the exported Word document. Default `"Calibri, 'Segoe UI', Arial, sans-serif"`. */
  wordExportFontFamily?: string;
  /** Body font-size for the exported Word document. Default `"11pt"`. */
  wordExportFontSize?: string;
  /** `@page` size for the exported Word document. Default `"8.5in 11in"` (Letter); use `"21cm 29.7cm"` for A4. */
  wordExportPageSize?: string;
  /** `@page` margin for the exported Word document. Default `"1in"`. */
  wordExportMargin?: string;
  /** Export in landscape orientation. Default `false`. */
  wordExportLandscape?: boolean;

  // ---- Document import (2.3.2) ----
  /** Enable file import (`importFile`/`openImportDialog` API, `importdocument` command, `/import` slash). Default `true`. */
  documentImport?: boolean;
  /** Import behavior: `replace` (default) swaps the document; `insert` adds at the caret. */
  documentImportMode?: "replace" | "insert";
  /** `accept` attribute for the import file picker. */
  documentImportAccept?: string;
  /** Optional converter — `(file) => htmlString | Promise<htmlString>`. Lets a host handle `.docx` (or override any type) server-side. */
  documentImportResolver?: (file: File) => string | Promise<string>;

  // ---- Readability statistics (2.3.2) ----
  /** Enable readability stats (`getReadabilityStats`/`countSyllables` API, `readability` command, `/readability` slash). Default `true`. */
  readabilityStats?: boolean;
  /** Reading speed (words/minute) for the reading-time estimate. Default `200`. */
  readabilityWordsPerMinute?: number;

  // ---- Character / word limit (2.3.2) ----
  /** Maximum characters (0 / unset = no limit). Enables the char-limit plugin. */
  maxLength?: number;
  /** Maximum words (0 / unset = no limit). */
  maxWords?: number;
  /** Block input past the limit. Default `true`. */
  charLimitEnforce?: boolean;
  /** Show the floating live counter. Default `true`. */
  charLimitShowCounter?: boolean;

  // ---- Accessibility metadata (2.3.0) ----
  /** Add assistive-technology metadata (iframe title, editing-region `role="textbox"`/`aria-label`, document `lang`). Default `true`. */
  a11yEnhance?: boolean;
  /** Accessible name announced for the editing region and iframe (WCAG 4.1.2). Default `"Rich text editor. Editing area."`. */
  contentAriaLabel?: string;
  /** BCP-47 language tag applied to the editing document (WCAG 3.1.1). Defaults to the host page `<html lang>` or `"en"`. */
  contentLang?: string;
  /** Add `role="dialog"` + accessible names to dialog popups and `aria-label`s to their fields (WCAG 4.1.2 / 1.3.1 / 3.3.2). Default `true`. */
  dialogA11y?: boolean;

  // ---- Local draft autosave / recovery (2.3.0) ----
  /**
   * Persist the document to localStorage as you type and offer to restore it on
   * the next load (crash / refresh recovery). `true` for defaults, or an options
   * object. Off by default. The `editor.saveLocalDraft`/`restoreLocalDraft`/etc.
   * API is always available regardless of this flag.
   */
  localDraft?: boolean | {
    /** Storage key suffix (default: editor id or page path). */
    key?: string;
    /** Debounce between autosaves in ms (default 2500). */
    intervalMs?: number;
    /** Drop drafts older than this many ms (default 14 days). */
    ttlMs?: number;
    /** Show the built-in restore bar on load (default true). */
    promptRestore?: boolean;
  };

  // ---- AI ghost-text autocomplete (2.3.0) ----
  /**
   * Enable Copilot/Notion-style inline AI completion: after a typing pause a
   * greyed suggestion appears after the caret (Tab accepts, Esc / typing
   * dismisses). `true` for defaults or an options object. Requires
   * `ghostTextResolver` to be set — inert otherwise. Off by default.
   */
  ghostText?: boolean | {
    /** Idle delay before requesting a suggestion, ms (default 600). */
    delayMs?: number;
    /** Minimum non-space chars of left context before requesting (default 3). */
    minChars?: number;
    /** Max chars of left context passed to the resolver (default 2000). */
    maxContext?: number;
  };
  /**
   * Bring-your-own completion source. Receives the text around the caret and
   * returns the continuation string (or a promise of one). No model ships by
   * default and no network call is made without this.
   */
  ghostTextResolver?: ((context: { before: string; after: string; full: string }) => string | Promise<string>) | null;

  // ---- Read aloud (2.3.0) ----
  /** Default speech rate for read-aloud (0.5–2). Default 1.0. */
  readAloudRate?: number;
  /** Highlight each sentence (via the native selection) as it is spoken. Default `true`. */
  readAloudHighlight?: boolean;

  // ---- Emoji :shortcode: autocomplete (2.3.0) ----
  /** Enable inline emoji autocomplete: complete `:shortcode:` → emoji, and a `:query` popup. Default `true`. */
  emojiAutocompleteEnabled?: boolean;
  /**
   * Map of `shortcode` → emoji used by the autocomplete (GitHub/Slack style, e.g.
   * `{ fire: "🔥", "+1": "👍" }`). Provide your own to extend or replace the
   * built-in curated set.
   */
  emojiShortcodes?: Record<string, string>;

  /** Any additional config flag understood by the editor. */
  [key: string]: unknown;
}

export interface RichTextEditorConstructor {
  /** Audit HTML or structured-content documents for common accessibility issues. */
  auditAccessibility(value: RichTextEditorStructuredInput): RichTextEditorAccessibilityResult;
  /** Audit link marks for empty, unsafe, malformed, or policy-disallowed destinations. */
  auditLinks(
    value: RichTextEditorStructuredInput,
    options?: RichTextEditorLinkAuditOptions
  ): RichTextEditorLinkAuditResult;
  /** Apply a supported accessibility repair and return the updated structured document. */
  repairAccessibilityIssue(
    value: RichTextEditorStructuredInput,
    issue: RichTextEditorAccessibilityIssue,
    options?: RichTextEditorAccessibilityRepairOptions
  ): RichTextEditorStructuredDocument;
  /** Read document-level page setup metadata from HTML or structured-content JSON. */
  getDocumentPageSetup(value: RichTextEditorStructuredInput): RichTextEditorPageSetup | null;
  /** Compute richer document metrics such as paragraphs, headings, links, and estimated reading time. */
  getDocumentMetrics(
    value: RichTextEditorStructuredInput,
    options?: {
      selectionText?: string | null | undefined;
      wordsPerMinute?: number | null | undefined;
    }
  ): RichTextEditorDocumentMetrics;
  /** Extract a flat heading outline suitable for document navigation sidebars. */
  getDocumentOutline(value: RichTextEditorStructuredInput): RichTextEditorDocumentOutlineItem[];
  /** Returns document footnotes in numeric/source order for review/sidebar workflows. */
  getFootnotes(value: RichTextEditorStructuredInput): RichTextEditorFootnoteItem[];
  /** Build a nested table-of-contents tree from the document headings. */
  getTableOfContents(
    value: RichTextEditorStructuredInput,
    options?: RichTextEditorTableOfContentsOptions
  ): RichTextEditorTableOfContentsItem[];
  new (container: string | Element, config?: RichTextEditorConfig): RichTextEditorInstance;
  /** Parse Markdown and return a structured-content document. */
  fromMarkdown(markdown: string): RichTextEditorStructuredDocument;
  prototype: RichTextEditorInstance;
  /** Server-safe HTML render of a structured-content document or HTML string. */
  renderHTML(value: RichTextEditorStructuredInput): string;
  /** Return a copy of the document with normalized page setup metadata applied. */
  setDocumentPageSetup(
    value: RichTextEditorStructuredInput,
    pageSetup: RichTextEditorPageSetup | null
  ): RichTextEditorStructuredDocument;
  /** Repopulate any `tableOfContents` nodes from the current heading structure. */
  syncTableOfContents(
    value: RichTextEditorStructuredInput,
    options?: RichTextEditorTableOfContentsOptions
  ): RichTextEditorStructuredDocument;
  /** Convert a structured-content document or HTML string to Markdown. */
  toMarkdown(value: RichTextEditorStructuredInput): string;
  /** Validate a structured-content document against the editor's schema. */
  validateStructuredContent(value: RichTextEditorStructuredInput): RichTextEditorValidationResult;
}

declare global {
  interface Window {
    RichTextEditor: RichTextEditorConstructor;
    RTE_DefaultConfig?: RichTextEditorConfig;
  }
}

declare const RichTextEditor: RichTextEditorConstructor;

export default RichTextEditor;