@richscripts/richtexteditor 2.9.0 → 2.11.0

package/index.d.ts

@@ -1,1412 +1,2075 @@
-// 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;
+// 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;
+}
+
+// =====================
+// Autocorrect, sanitiser, shadow DOM, imported styles
+// (autocorrect, sanitizer, shadowdom, importstyles). Shapes read from a live editor.
+// =====================
+
+/** Misspelling -> replacement, e.g. `{ teh: "the" }`. */
+export type RichTextEditorAutocorrectRules = Record<string, string>;
+
+export interface RichTextEditorSanitizerReport {
+  removedTags: Record<string, number> | string[];
+  removedAttributes: Record<string, number> | string[];
+  /** How many times the sanitiser has run. */
+  calls: number;
+  lastPasses: number;
+}
+
+// =====================
+// Tables, links, languages, pen, drag handle
+// (layouttable, tabletools, linkchecker, textpartlanguage, permanentpen, draghandle, rtlui).
+// Shapes read from a live editor.
+// =====================
+
+export interface RichTextEditorLinkIssue {
+  element: HTMLElement;
+  href: string;
+  text: string;
+  severity: string;
+  code: string;
+  message: string;
+}
+
+export interface RichTextEditorLanguageOption {
+  code: string;
+  label: string;
+  dir?: RichTextEditorTextDirection;
+}
+
+// =====================
+// Page layout, merge fields, cross-references, text direction
+// (pagination, mergefields, crossreference, textdirection). Shapes read from a live editor.
+// =====================
+
+export interface RichTextEditorPageGeometry {
+  format: string;
+  orientation: "portrait" | "landscape" | string;
+  pageWidth: number;
+  pageHeight: number;
+  contentWidth: number;
+  contentHeight: number;
+  marginTop: number;
+  marginRight: number;
+  marginBottom: number;
+  marginLeft: number;
+  headerHtml: string;
+  footerHtml: string;
+}
+
+export interface RichTextEditorMergeFieldDefinition {
+  id: string;
+  label: string;
+  /** Value shown while previewing, before real data is merged. */
+  sample?: unknown;
+}
+
+export interface RichTextEditorCrossReferenceTarget {
+  id: string;
+  label: string;
+  /** "heading", "table", "figure", "footnote", … */
+  type: string;
+  /** Current number, when the target is numbered. */
+  number?: string | number | null;
+}
+
+export type RichTextEditorTextDirection = "ltr" | "rtl";
+
+// =====================
+// Document tooling that shipped without typings
+// (watermark, footnotes, change case, format painter, table of contents,
+//  legal numbering, line numbers). Shapes read from a live editor.
+// =====================
+
+export interface RichTextEditorWatermarkOptions {
+  text?: string;
+  image?: string | null;
+  /** `tile` repeats across the page; other modes place a single mark. */
+  mode?: "tile" | string;
+  color?: string;
+  fontSize?: number;
+  opacity?: number;
+  angle?: number;
+  /** Include the watermark when printing (default false). */
+  print?: boolean;
+}
+
+export type RichTextEditorChangeCaseMode = "upper" | "lower" | "title" | "sentence" | "toggle";
+
+export interface RichTextEditorTocEntry {
+  id: string;
+  level: number;
+  text: string;
+  /** Page number when page view is on. */
+  page?: number;
+}
+
+export interface RichTextEditorLineNumberOptions {
+  start?: number;
+  interval?: number;
+  restartEachPage?: boolean;
+  [key: string]: unknown;
+}
+
+// =====================
+// Node types, state inspector, ruby, tracked changes
+// (plugins/nodetypes.js, stateinspector.js, rubyannotation.js, trackedchanges.js)
+// Shapes below were read from a live editor, not inferred from the sources.
+// =====================
+
+export interface RichTextEditorNodeTypeDefinition {
+  name: string;
+  /** CSS selector, or a predicate run against candidate elements. */
+  match: string | ((el: HTMLElement) => boolean);
+  /** Enforced as one uneditable unit (default true). */
+  atomic?: boolean;
+  inline?: boolean;
+  toJSON?(el: HTMLElement): unknown;
+  fromJSON?(data: unknown): HTMLElement;
+  toMarkdown?(el: HTMLElement): string;
+  /** Covers .docx and PDF at once; toDocx / toPdf / toWord override per format. */
+  toExportHTML?(el: HTMLElement): string;
+  toDocx?(el: HTMLElement): string;
+  toPdf?(el: HTMLElement): string;
+  toWord?(el: HTMLElement): string;
+  /** Fed to the sanitizer allowlist on registration. */
+  allowTags?: string[];
+  allowAttributes?: string[];
+}
+
+export interface RichTextEditorNodeTypeSummary {
+  name: string;
+  atomic: boolean;
+  inline: boolean;
+  hasToJSON: boolean;
+  hasFromJSON: boolean;
+  hasToMarkdown: boolean;
+  hasExportHTML: boolean;
+  instances: number;
+}
+
+export interface RichTextEditorNodeTypes {
+  register(definition: RichTextEditorNodeTypeDefinition): boolean;
+  unregister(name: string): boolean;
+  insert(name: string, data?: unknown): HTMLElement | null;
+  find(name?: string): HTMLElement[];
+  get(name: string): RichTextEditorNodeTypeDefinition | null;
+  list(): RichTextEditorNodeTypeSummary[];
+  /** Every instance in the document as `{ name, data }`. */
+  serialize(): { name: string; data: unknown }[];
+  typeOf(el: HTMLElement): string | null;
+}
+
+export interface RichTextEditorStateIssue {
+  id: string;
+  severity: "warn" | "error" | string;
+  message: string;
+  detail?: string;
+}
+
+export interface RichTextEditorStateSnapshot {
+  snapshotVersion: number;
+  generatedAt: string;
+  counters: { elements: number; textNodes: number; comments: number; characters: number; tags: Record<string, number> };
+  issues: RichTextEditorStateIssue[];
+  plugins: string[];
+  recentEvents: { at: string; event: string }[];
+  selection: {
+    available: boolean;
+    collapsed: boolean;
+    anchor?: unknown;
+    focus?: unknown;
+    insideEditable: boolean;
+    textLength: number;
+    text: string;
+    block?: string;
+  };
+  tree: { type: string; name?: string; attrs?: Record<string, string>; children?: unknown[] };
+}
+
+export interface RichTextEditorStateInspector {
+  open(): void;
+  close(): void;
+  toggle(): void;
+  isOpen(): boolean;
+  refresh(): void;
+  /** Derived document model as plain JSON — safe to attach to a support case. */
+  snapshot(): RichTextEditorStateSnapshot;
+  issues(): RichTextEditorStateIssue[];
+  /** Plugin initialisation order. */
+  plugins(): string[];
+  log(): { at: string; event: string }[];
+}
+
+export interface RichTextEditorRuby {
+  /** Wraps the selection in <ruby> with this reading. */
+  add(reading: string): boolean;
+  /** Reading of the ruby at the caret, or null. */
+  get(): string | null;
+  isRuby(): boolean;
+  remove(): boolean;
+  open(): void;
+}
+
+export interface RichTextEditorTrackedChangeEntry {
+  id: string;
+  changeType: "insert" | "delete" | string;
+  status: "pending" | "accepted" | "rejected" | string;
+  author?: string;
+  text?: string;
+  [key: string]: unknown;
+}
+
+export interface RichTextEditorTrackedChanges {
+  enable(user?: { name?: string; id?: string }): void;
+  disable(): void;
+  isEnabled(): boolean;
+  /** Pending entries by default; `{ all: true }` includes decided ones. */
+  list(options?: { all?: boolean }): RichTextEditorTrackedChangeEntry[];
+  accept(id: string): boolean;
+  reject(id: string): boolean;
+  acceptAll(filter?: unknown): number | boolean;
+  rejectAll(filter?: unknown): number | boolean;
+  canDecide(id: string, action?: "accept" | "reject"): boolean;
+}
+
+// =====================
+// Component blocks, commands, transforms (plugins/componentblocks.js,
+// plugins/commandbus.js, plugins/transforms.js)
+// =====================
+
+export interface RichTextEditorComponentContext {
+  editor: RichTextEditorInstance;
+  /** The host element in the document; its shadow root is where you render. */
+  el: HTMLElement;
+  name: string;
+  props: Record<string, unknown>;
+  setProps(props: Record<string, unknown>): boolean;
+}
+
+export interface RichTextEditorComponentDefinition {
+  name: string;
+  /** Render into the host's shadow root. Required. */
+  mount(root: ShadowRoot, ctx: RichTextEditorComponentContext): void;
+  /** Release timers, listeners and framework roots. Runs on delete and before a remount. */
+  unmount?(root: ShadowRoot, ctx: RichTextEditorComponentContext): void;
+  /** Re-render in place after setProps; without it the block is rebuilt. */
+  update?(root: ShadowRoot, ctx: RichTextEditorComponentContext): void;
+  /** `span` host instead of `div`. */
+  inline?: boolean;
+  /** Text used by exports and by clients that never run the component. */
+  placeholder?: string;
+  toMarkdown?(el: HTMLElement): string;
+  toExportHTML?(el: HTMLElement): string;
+}
+
+export interface RichTextEditorComponentSummary {
+  name: string;
+  inline: boolean;
+  mounted: number;
+}
+
+export interface RichTextEditorComponents {
+  register(definition: RichTextEditorComponentDefinition): boolean;
+  unregister(name: string): boolean;
+  insert(name: string, props?: Record<string, unknown>): HTMLElement | null;
+  props(el: HTMLElement): Record<string, unknown>;
+  setProps(el: HTMLElement, props: Record<string, unknown>): boolean;
+  find(name?: string): HTMLElement[];
+  get(name: string): RichTextEditorComponentDefinition | null;
+  list(): RichTextEditorComponentSummary[];
+}
+
+export type RichTextEditorCommandHandler = (
+  payload: unknown,
+  ctx: { editor: RichTextEditorInstance; command: string }
+) => boolean | void;
+
+export interface RichTextEditorCommandSummary {
+  command: string;
+  handlers: number;
+  priorities: number[];
+}
+
+export interface RichTextEditorCommands {
+  /** Higher priority runs first. Returns an unregister function. */
+  register(name: string, handler: RichTextEditorCommandHandler, priority?: number): () => void;
+  unregister(name: string, handler: RichTextEditorCommandHandler): boolean;
+  /** Runs handlers until one returns true. Returns whether it was handled. */
+  dispatch(name: string, payload?: unknown): boolean;
+  has(name: string): boolean;
+  list(): RichTextEditorCommandSummary[];
+}
+
+export type RichTextEditorTransform = (
+  editable: HTMLElement,
+  ctx: { editor: RichTextEditorInstance; name: string; pass: number; reason: string }
+) => boolean | void;
+
+export interface RichTextEditorTransforms {
+  /** Returns an unregister function. Return true from a transform to request another pass. */
+  register(transform: RichTextEditorTransform, options?: { name?: string; priority?: number }): () => void;
+  unregister(transform: RichTextEditorTransform): boolean;
+  run(): { passes: number; changed: boolean };
+  list(): { name: string; priority: number }[];
+}
+
+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;
+
+  // ---- Autocorrect and typography ----
+
+  setAutocorrectEnabled?(on: boolean): boolean;
+  isAutocorrectEnabled?(): boolean;
+  /** Adds one replacement rule. */
+  addAutocorrectRule?(from: string, to: string): boolean;
+  getAutocorrectRules?(): RichTextEditorAutocorrectRules;
+  /** Applies smart quotes, dashes and ellipses to a string and returns it. */
+  applyTypography?(text: string): string;
+
+  // ---- Sanitiser ----
+
+  /** Cleans an HTML string with the editor's allowlist. */
+  sanitizeHtml?(html: string): string;
+  /** Counters for what the sanitiser has removed so far. */
+  getSanitizerReport?(): RichTextEditorSanitizerReport;
+
+  // ---- Markdown ----
+
+  toMarkdown?(): string;
+  fromMarkdown?(markdown: string): unknown;
+  getMarkdown?(): string;
+  copyAsMarkdown?(): unknown;
+  downloadMarkdown?(filename?: string): unknown;
+
+  // ---- Export ----
+
+  getPdfBytes?(options?: Record<string, unknown>): Uint8Array | Promise<Uint8Array>;
+  exportToPdf?(filename?: string, options?: Record<string, unknown>): unknown;
+  downloadPdf?(filename?: string, options?: Record<string, unknown>): unknown;
+  exportPdf?(options?: Record<string, unknown>): unknown;
+  getDocxBlob?(options?: Record<string, unknown>): Blob | Promise<Blob>;
+  exportToDocx?(filename?: string, options?: Record<string, unknown>): unknown;
+  exportToWord?(options?: RichTextEditorWordExportOptions): unknown;
+  downloadWord?(filename?: string, options?: RichTextEditorWordExportOptions): unknown;
+  getWordDocument?(options?: RichTextEditorWordExportOptions): string;
+  getEmailHTML?(options?: Record<string, unknown>): string;
+
+  // ---- Formatting marks and inline code ----
+
+  setFormattingMarks?(on: boolean): boolean;
+  toggleFormattingMarks?(): unknown;
+  isFormattingMarks?(): boolean;
+  getFormattingMarksCss?(): string;
+  toggleInlineCode?(): unknown;
+  isInlineCode?(): boolean;
+
+  // ---- Gap cursor (blocks with no paragraph around them) ----
+
+  /** Places where a paragraph can be inserted between or beside atomic blocks. */
+  getGapPositions?(): unknown[];
+  insertParagraphBefore?(el: HTMLElement): unknown;
+  insertParagraphAfter?(el: HTMLElement): unknown;
+  insertParagraphAt?(index: number): unknown;
+
+  // ---- Shadow DOM hosting ----
+
+  isInShadowDom?(): boolean;
+  getShadowRoot?(): ShadowRoot | null;
+  /** Copies the editor's stylesheets into a shadow root; returns how many. */
+  adoptEditorStyles?(target?: ShadowRoot): number;
+  getAdoptedStyleCount?(): number;
+
+  // ---- Imported styles ----
+
+  importStyles?(options?: Record<string, unknown>): unknown;
+  getImportedStyles?(): unknown;
+  scanStylesheetClasses?(options?: Record<string, unknown>): unknown;
+
+  // ---- Accessibility helpers ----
+
+  /** Announces text to screen readers through the editor's live region. */
+  announce?(text: string, options?: { assertive?: boolean }): unknown;
+  /** Moves focus to the first toolbar button (the documented Escape hatch target). */
+  focusToolbar?(): unknown;
+  applyAccessibilityMetadata?(): unknown;
+  applyDialogAccessibility?(dialog?: HTMLElement): unknown;
+  ensureStyleSheetLive?(doc: Document, style: HTMLStyleElement, id: string, cssText: string): unknown;
+
+  // ---- Toolbar / dialog building blocks ----
+
+  createTabUI?(...args: unknown[]): unknown;
+  createToolbarItemDropDownPanel?(...args: unknown[]): unknown;
+  /** Fires an editor event by name. */
+  fireEvent?(name: string, ...args: unknown[]): unknown;
+  /** Subscribe to formatting state changes for a command. */
+  formatChanged?(...args: unknown[]): unknown;
+  getLangText?(key: string): string;
+
+  // ---- Other feature entry points ----
+
+  insertTableOfContents?(): unknown;
+  toggleWatermark?(): unknown;
+  readAloud?(): unknown;
+  stopReadAloud?(): unknown;
+  showShortcuts?(): unknown;
+  openFindDialog?(): unknown;
+  openImportDialog?(): unknown;
+  importFile?(file: File, options?: RichTextEditorImportOptions): unknown;
+  htmlFromImportText?(text: string, filename?: string): string;
+  embedUrl?(url: string): unknown;
+  renderMath?(): unknown;
+  applyMathMarkup?(): unknown;
+  renderDiagrams?(): unknown;
+  getReadabilityStats?(): Record<string, unknown>;
+  countSyllables?(word: string): number;
+  getFootnotes?(): unknown[];
+  getCharCount?(): number;
+  getWordCount?(): number;
+  getRemainingChars?(): number;
+  isOverLimit?(): boolean;
+  getCommentsOnly?(): boolean;
+  setCommentsOnly?(on: boolean): unknown;
+  setFocusMode?(on: boolean): unknown;
+  toggleFocusMode?(): unknown;
+  isFocusMode?(): boolean;
+  setTypewriterMode?(on: boolean): unknown;
+  toggleTypewriterMode?(): unknown;
+  isTypewriterMode?(): boolean;
+  saveLocalDraft?(): unknown;
+  restoreLocalDraft?(): unknown;
+  hasLocalDraft?(): boolean;
+  getLocalDraft?(): unknown;
+  clearLocalDraft?(): unknown;
+  requestGhostText?(): unknown;
+  acceptGhostText?(): unknown;
+  dismissGhostText?(): unknown;
+  hasGhostText?(): boolean;
+  setGhostTextResolver?(resolver: (context: unknown) => unknown): unknown;
+  foldAtCaret?(): unknown;
+  toggleHeadingFold?(el?: HTMLElement): unknown;
+  unfoldAll?(): unknown;
+  findHighlight?(text: string): unknown;
+  getSelectedControl?(): HTMLElement | null;
+  getSelectedText?(): string;
+  getDocument?(): Document;
+
+  // ---- Tables ----
+
+  insertLayoutTable?(rows: number, cols: number, options?: Record<string, unknown>): unknown;
+  /** "layout" or "data" for the table at the caret (or the one passed), null when there is none. */
+  getTableLayoutMode?(table?: HTMLTableElement): "layout" | "data" | null;
+  setTableLayoutMode?(mode: "layout" | "data"): unknown;
+  toggleTableLayoutMode?(): unknown;
+  isLayoutTable?(table?: HTMLTableElement): boolean;
+  listLayoutTables?(): HTMLTableElement[];
+  showLayoutTableOutlines?(on: boolean): boolean;
+  /** `{ ok }` is false with a `reason` when the table at the caret cannot be sorted. */
+  canSortTable?(): { ok: boolean; reason: string };
+  sortTableByColumn?(index: number, dir?: "asc" | "desc"): unknown;
+  sortTableAtCaret?(): unknown;
+  addTableRowNumbers?(options?: Record<string, unknown>): unknown;
+  removeTableRowNumbers?(): unknown;
+  hasTableRowNumbers?(): boolean;
+
+  // ---- Link checking ----
+
+  /** Runs the check; read the findings with getLinkIssues(). */
+  checkLinks?(): unknown;
+  getLinkIssues?(): RichTextEditorLinkIssue[];
+  highlightLinkIssues?(on?: boolean): unknown;
+  clearLinkHighlights?(): unknown;
+  getLinkCheckerCss?(): string;
+
+  // ---- Language of parts ----
+
+  /** Marks the selection with a BCP 47 language tag (WCAG 3.1.2). */
+  setTextLanguage?(code: string): unknown;
+  getTextLanguage?(): string | null;
+  removeTextLanguage?(): unknown;
+  getMarkedLanguages?(): unknown[];
+  listTextLanguages?(): RichTextEditorLanguageOption[];
+
+  // ---- Permanent pen ----
+
+  setPermanentPen?(on: boolean): unknown;
+  togglePermanentPen?(): unknown;
+  isPermanentPenActive?(): boolean;
+  /** CSS declarations applied while the pen is on, e.g. `{ color, "font-weight" }`. */
+  getPermanentPenStyle?(): Record<string, string>;
+  setPermanentPenStyle?(style: Record<string, string>): unknown;
+
+  // ---- Drag handle / block moves ----
+
+  setDragHandleEnabled?(on: boolean): boolean;
+  isDragHandleEnabled?(): boolean;
+  moveBlock?(block: HTMLElement, beforeEl?: HTMLElement | null): unknown;
+  moveBlockUp?(): unknown;
+  moveBlockDown?(): unknown;
+
+  // ---- Right-to-left user interface ----
+
+  setRtlUserInterface?(on: boolean): boolean;
+  toggleRtlUserInterface?(): boolean;
+  isRtlUserInterface?(): boolean;
+  getRtlUiCss?(): string;
+
+  // ---- Content (core, previously untyped) ----
+
+  /** Alias of getHTMLCode(). */
+  getHTML?(): string;
+  /** Alias of setHTMLCode(). */
+  setHTML?(html: string): unknown;
+  getText?(): string;
+  setText?(text: string): unknown;
+  setPlainText?(text: string): unknown;
+  /** HTML of the current selection, empty when nothing is selected. */
+  getSelectedHTML?(): string;
+  /** Word and character counts for the document. */
+  getStatistics?(): { words: number; characters: number };
+  showWordCount?(): void;
+  insertImageByUrl?(url: string): void;
+  /** Highlights every occurrence of the selected text; returns how many. */
+  markAllOccurrencesOfSelection?(): number;
+  clearFindHighlights?(): void;
+  printPreview?(): unknown;
+  /** Distraction-free reading mode; returns the new state. */
+  toggleReadingMode?(state?: boolean): boolean;
+  isReadingMode?(): boolean;
+  /** Adds a stylesheet to the editing document (or `doc`) under a stable id. */
+  injectStyleSheet?(doc: Document | null, id: string, cssText: string): unknown;
+  /** Releases listeners and observers before the host removes the editor. */
+  prepareDestroy?(): void;
+  destroy?(): void;
+
+  // ---- Page layout ----
+
+  setPageView?(on: boolean): boolean;
+  togglePageView?(): boolean;
+  isPageView?(): boolean;
+  getPageCount?(): number;
+  getPageGeometry?(): RichTextEditorPageGeometry;
+  setPageSetup?(setup: RichTextEditorPageSetup): void;
+
+  // ---- Merge fields ----
+
+  insertMergeField?(id: string): unknown;
+  listMergeFields?(): unknown[];
+  getMergeFieldDefinitions?(): RichTextEditorMergeFieldDefinition[];
+  /** Renders the document with one record's data. */
+  renderMergeFields?(data: Record<string, unknown>): unknown;
+  setMergeFieldPreview?(on: boolean): unknown;
+  toggleMergeFieldPreview?(): unknown;
+  isMergeFieldPreview?(): boolean;
+  getMergeFieldCss?(): string;
+
+  // ---- Cross-references ----
+
+  insertCrossReference?(targetId: string, format?: string): unknown;
+  listCrossReferenceTargets?(): RichTextEditorCrossReferenceTarget[];
+  getCrossReferences?(): unknown[];
+  /** Renumbers references after content moved. */
+  updateCrossReferences?(): unknown;
+  getPageOfElement?(el: HTMLElement): number | null;
+  getCrossReferenceCss?(): string;
+
+  // ---- Text direction (bidi) ----
+
+  setBaseDirection?(dir: RichTextEditorTextDirection): unknown;
+  getBaseDirection?(): RichTextEditorTextDirection;
+  setTextDirection?(dir: RichTextEditorTextDirection): unknown;
+  getTextDirection?(): RichTextEditorTextDirection;
+  toggleTextDirection?(): unknown;
+  /** Direction of the first strong character in `text`. */
+  detectTextDirection?(text: string): RichTextEditorTextDirection;
+  autoDetectTextDirection?(): unknown;
+  /** Wraps html in a bidi isolate so it cannot reorder surrounding text. */
+  isolateBidi?(html: string, dir?: RichTextEditorTextDirection): string;
+  insertIsolated?(html: string, dir?: RichTextEditorTextDirection): unknown;
+  getTextDirectionCss?(): string;
+
+  // ---- Watermark ----
+
+  /** Turns the watermark on or off; returns the new state. */
+  setWatermark?(on: boolean): boolean;
+  isWatermark?(): boolean;
+  getWatermarkOptions?(): RichTextEditorWatermarkOptions;
+  setWatermarkOptions?(options: RichTextEditorWatermarkOptions): void;
+
+  // ---- Footnotes ----
+
+  /** Inserts an auto-numbered footnote at the caret. */
+  insertFootnote?(text?: string): unknown;
+  /** Renumbers footnotes after content moved. */
+  syncFootnotes?(): unknown;
+  /** Footnote CSS, for rendering saved content outside the editor. */
+  getFootnotesCss?(): string;
+
+  // ---- Change case ----
+
+  changeCase?(mode: RichTextEditorChangeCaseMode): unknown;
+  getChangeCaseModes?(): RichTextEditorChangeCaseMode[];
+
+  // ---- Format painter ----
+
+  copyFormatting?(): unknown;
+  pasteFormatting?(): unknown;
+  /** `isSticky` keeps painting until cancelled. */
+  toggleFormatPainter?(isSticky?: boolean): unknown;
+  cancelFormatPainter?(): unknown;
+  isFormatPainterActive?(): boolean;
+  /** The captured character formatting, or null when nothing is captured. */
+  getCapturedFormatting?(): Record<string, unknown> | null;
+
+  // ---- Table of contents ----
+
+  getTableOfContents?(): RichTextEditorTocEntry[];
+  hasTableOfContents?(): boolean;
+  updateTableOfContents?(): unknown;
+  removeTableOfContents?(): unknown;
+  getTocCss?(): string;
+
+  // ---- Legal / multi-level numbering ----
+
+  setLegalNumbering?(on: boolean): unknown;
+  toggleLegalNumbering?(): unknown;
+  isLegalNumbering?(): boolean;
+  getLegalListCss?(): string;
+
+  // ---- Line numbers ----
+
+  setLineNumbers?(on: boolean): boolean;
+  toggleLineNumbers?(): unknown;
+  isLineNumbers?(): boolean;
+  getLineCount?(): number;
+  setLineNumberOptions?(options: RichTextEditorLineNumberOptions): void;
+  getLineNumbersCss?(): string;
+
+  /** Declare your own element as a node type. See docs/CUSTOM-NODE-TYPES.md. */
+  nodeTypes?: RichTextEditorNodeTypes;
+
+  /** Developer tool: derived document model and structural checks. */
+  stateInspector?: RichTextEditorStateInspector;
+
+  /** Ruby annotations (furigana, pinyin, bopomofo). */
+  ruby?: RichTextEditorRuby;
+
+  /** Track changes review queue. */
+  trackedChanges?: RichTextEditorTrackedChanges;
+
+  /** Framework components hosted as editable blocks. See docs/COMPONENT-BLOCKS.md. */
+  components?: RichTextEditorComponents;
+
+  /** Priority-ordered commands, and interception of built-in ones. See docs/COMMAND-BUS.md. */
+  commands?: RichTextEditorCommands;
+
+  /** Document normalization that runs after changes. See docs/TRANSFORMS.md. */
+  transforms?: RichTextEditorTransforms;
+
+  /** @-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;