API reference

export type ToHTMLOptions = {
  /** Separator between top-level blocks. Defaults to `"\n"`. */
  separator?: string;
  /**
   * How embeds are written; every form reads back to the same block.
   * - `"auto"` (default): embeds that came from a site's embed code (tweets, posts, …) are written back as that
   *   code, its `<blockquote>` text readable without the script; widget embeds (Gist) always are; others as iframes.
   * - `"iframe"`: our own sandboxed iframes (widget embeds still as their snippet).
   * - `"link"`: link cards with the fallback text, for email and RSS.
   */
  embeds?: "auto" | "iframe" | "link";
  /**
   * Append each provider's official `<script>` once after its first snippet-form embed, so the code renders
   * as on the site when the HTML is published elsewhere. Off by default: the export runs no third-party code.
   */
  embedScripts?: boolean;
  /** Custom providers, so their embeds are rebuilt on export. Without them, those embeds are written as sandboxed generic iframes. */
  embedProviders?: readonly EmbedProvider[];
  /** Brand swatches (`tools.colors.swatches`), so colours stored by swatch name export as their hex. */
  swatches?: readonly ColorSwatch[];
};

export type HtmlBlock = {
  type: string;
  props?: Record<string, string | number | boolean>;
  content?: HtmlInline[] | HtmlTableContent;
  children?: HtmlBlock[];
  /** Kept source attributes and other metadata (§16). Left out when empty. */
  meta?: GenesisMeta;
};

export type DropReason = "content" | "noise" | "hidden" | "tracking" | "unsupported" | "embed" | "unsafe";

export type WrapperFrame = { tag: string; attrs?: Record<string, string>; group?: string };

export type ParseAsyncOptions = ParseOptions &
  Pick<UploadConfig, "uploadRemote" | "uploadFromUrl" | "uploadHeaders" | "mapUploadResponse" | "uploadConcurrency" | "trustedHosts"> & {
    /** Which image URLs to copy. Defaults to every `http(s)` image not already re-hosted. */
    rehostImages?: "auto" | "off" | ((url: string) => boolean);
    /** Stops pending uploads; the images they were for keep their original URLs. */
    signal?: AbortSignal;
  };

export type EditorTheme = "light" | "dark" | "system";

export type PersistOptions = {
  /** localStorage key. Defaults to `"genesis-editor:document"`. Use a distinct key per document. */
  key?: string;
  /** Delay after the last edit before saving, in milliseconds. Defaults to 400. */
  debounceMs?: number;
};

export type PersistStatus =
  | { status: "idle" }
  | { status: "saving" }
  | { status: "saved"; savedAt: number }
  | { status: "error"; error: unknown };

export type UploadErrorEvent =
  | {
      /** A file the user picked, pasted or dropped. */
      kind: "file";
      error: Error;
      file: File;
      /** The image block the file was meant for. */
      blockId: string;
      /** Uploads the same file to the same block again. */
      retry: () => Promise<void>;
    }
  | {
      /** A pasted or loaded image that couldn't be copied to your storage. It keeps its original URL. */
      kind: "rehost";
      error: Error;
      /** The image's original URL. */
      url: string;
      blockId: string;
      /** Tries the re-upload again. */
      retry: () => Promise<void>;
    };

export type UploadResponseMapper = (
  body: unknown,
  response: Response,
) => string | Promise<string>;

export type UploadCallContext = {
  /** Aborted when the block is deleted, the editor is destroyed, or the 30 s timeout passes. */
  signal: AbortSignal;
  /** Reports progress as a fraction from 0 to 1. */
  onProgress: (fraction: number) => void;
  blockId?: string;
  /** `"upload"` for files the user picked, pasted or dropped. */
  source: RehostSource | "upload";
  /** The kind of asset being transferred. Defaults to the file's MIME type when available. */
  kind?: AssetKind;
};

export type UploadHeaders = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);

export type RehostSource = "paste" | "value";

export type HtmlChangeInfo = {
  /** The document the HTML was serialized from. */
  blocks: GenesisBlock[];
  /** The report from the most recent HTML or Markdown import (initial value, `setHTML`/`setMarkdown`, or paste), if any. */
  report: FidelityReport | null;
  editor: BlockNoteEditor;
};

export type FidelityReport = {
  mode: ParseMode;
  /** 0–1: the share of mapped source elements, counting downgrades as half and lost visual styles as a tenth. */
  score: number;
  /** Top-level blocks produced. */
  blocks: number;
  /** Elements removed, with their content, and a short text preview of the first one. */
  dropped: { tag: string; reason: DropReason; count: number; preview?: string }[];
  /** Wrapper elements removed while keeping their content. */
  unwrapped: { tag: string; count: number }[];
  /** CSS properties that have no equivalent in the editor. `visual` ones lower the score. */
  unsupportedStyles: { prop: string; count: number; visual: boolean }[];
  /** Content converted to a simpler form, e.g. because its tool is off. */
  downgrades: { from: string; to: string; count: number }[];
  colors: { palette: number; hex: number };
  headings: { promoted: number; dropped: number };
  /** Text that kept a font size (`sized`), and sizes outside 6–72 px moved to the nearest end (`clamped`). */
  fontSizes: { sized: number; clamped: number };
  images: {
    total: number;
    /** Relative URLs made absolute with `baseUrl` or `<base href>`. */
    resolved: number;
    /** Relative URLs left as they are because there was no base URL. */
    unresolved: number;
    /** Images dropped because no usable URL was found, or inline images over `maxDataImageBytes`. */
    failed: number;
    /** Images copied to the app's storage afterwards (editor re-hosting, `parseHTMLAsync`). */
    rehosted: number;
    /** Images whose re-upload failed; they keep their original URL. */
    rehostFailed: number;
  };
  /** Embeds created: from a provider, generic (sandboxed) iframes, and iframes the policy turned into links. */
  embeds: { provider: number; generic: number; blocked: number };
  /** What noise removal took out. Undo it by parsing again with `clean: { noise: false }`. */
  cleanup: CleanupSummary;
  warnings: string[];
};

export type ParseMode = "clean" | "strict";

export type CleanOptions = {
  /** Set to `false` to skip page-furniture removal (main-content scoping, landmarks, scoring). Defaults to `true`. */
  noise?: boolean;
  /** Elements matching, inside, or containing these selectors are never removed as noise. */
  keepSelectors?: string[];
  /** Elements matching these selectors are always removed, even in small pastes. */
  dropSelectors?: string[];
  /**
   * `"collapse"` trims empty paragraphs at the start and end and turns runs of them into one;
   * `"keep"` keeps them all, so the editor's own HTML loads back unchanged. Defaults to `"collapse"`.
   */
  emptyParagraphs?: "collapse" | "keep";
  /** Extra phrases that mark page furniture when they make up most of an element's text. */
  phrases?: string[];
};

export type CleanupSummary = {
  /** Page-furniture sections removed (share bars, related links, navigation…). */
  sections: number;
  /** Why, e.g. `"share"`, `"related"`, `"navigation"`, in the order first seen. */
  labels: string[];
  /** Set when noise removal didn't run: `"small"` for pastes under 3 blocks or 500 characters, `"off"` when disabled. */
  skipped?: "small" | "off";
};

export type GenesisBlock = Block & { meta?: GenesisMeta };

export type GenesisMeta = {
  v: typeof META_VERSION;
  /** HTML attributes kept from the source: `id`, `lang`, `dir`. */
  attrs?: Record<string, string>;
  wrappers?: WrapperFrame[];
  styles?: Record<string, string>;
  /** The source element when it isn't implied by the block type, e.g. `"cite"` for a quote attribution. */
  source?: { tag: string };
  /** Set on imported blocks when `meta.trackProvenance` is on. */
  import?: { at: string; engine: string; origin?: string };
  /** Integrator and plugin data, namespaced by plugin name. */
  ext?: Record<string, unknown>;
};

export type MetaOptions = {
  /**
   * `"keep"` (default) keeps `meta` everywhere. `"strip-on-export"` keeps it in the document and in
   * localStorage, but leaves it out of `onChange`, `getBlocks`, `getHTML` and the clipboard. `"off"`
   * never stores it.
   */
  policy?: MetaPolicy;
  /** Stamp imported blocks with `meta.import` (`at`, `engine`, `origin`). Defaults to `false`. */
  trackProvenance?: boolean;
};

export type StoredDocument = {
  v: typeof STORAGE_VERSION;
  /** Public block JSON: `meta` is a top-level object on each block. */
  blocks: PartialBlock[];
  savedAt: number;
};

export type ToolSelection =
  | readonly (BuiltInToolName | (string & {}))[]
  | (BuiltInToolEntry & { [name: string]: boolean | object | undefined });

export type ToolOptions = {
  heading: {
    /** Heading levels to offer. Defaults to all six; the menus show the first three. */
    levels?: HeadingLevel[];
  };
  colors: ColorToolOptions;
};

export type ToolbarConfig =
  | readonly ToolbarItemName[]
  | {
      /** Items in order. Defaults to the built-in order followed by plugin items. */
      items?: readonly ToolbarItemName[];
      /** `"floating"` shows the toolbar over selected text; `"fixed"` pins it above the editor. Defaults to `"floating"`. */
      placement?: "floating" | "fixed";
    };

export type SlashMenuItem = {
  /** Unique within the plugin. */
  key: string;
  title: string;
  subtext?: string;
  /** Extra search terms. */
  aliases?: string[];
  /** Menu section. Items without a group go under "Other". */
  group?: string;
  icon?: ReactNode;
  /** Shortcut hint shown on the right, e.g. `"⌘⌥C"`. */
  badge?: string;
} & (
  | {
      /** Block to insert, or to turn the current empty block into. */
      block: AnyPartialBlock;
      onItemClick?: never;
    }
  | {
      onItemClick: (editor: AnyEditor) => void;
      block?: never;
    }
);

export type MarkdownShortcut = {
  /** Matched against the text before the cursor. Anchor with `^` and end with `\s$` to trigger on space. */
  find: RegExp;
  /** The block to convert to, or a function of the match. Return `undefined` to skip. */
  block: AnyPartialBlock | ((match: RegExpMatchArray) => AnyPartialBlock | undefined);
};

export type ToolbarButtonProps = {
  /** Accessible name and tooltip. */
  label: string;
  icon: ReactNode;
  onClick: (editor: AnyEditor) => void;
  /** Shows the button as pressed, e.g. while the selection already has the style. */
  isSelected?: (editor: AnyEditor) => boolean;
  /** Hides the button for selections it doesn't apply to. */
  isVisible?: (editor: AnyEditor) => boolean;
};

export type EmbedOptions = {
  /** `"open"` (the default) allows providers and sandboxed generic iframes; `"allowlist"` allows providers only. */
  policy?: "open" | "allowlist";
  /** Provider names to allow. Defaults to all. */
  providers?: string[];
  /** Generic iframes under the `"open"` policy. Defaults to `true`. */
  generic?: boolean;
  /**
   * Wait for a click before loading the iframe (privacy). Defaults to `false` (load immediately).
   * The parser ignores this; it only affects drawing.
   */
  clickToLoad?: boolean;
};

export type EmbedProvider = {
  /** Stored in the block's `provider` prop. */
  name: string;
  /** Shown in the caption bar, e.g. `"YouTube"`. */
  label: string;
  /** Page URLs this provider embeds, anchored at `^https?://`. Capture groups go to `toEmbed`. */
  match: RegExp[];
  /**
   * Origins its frames load from: the CSP `frame-src` entries, and the only origins `toEmbed` may return.
   * For `render: "widget"` providers, the origins their script loads from.
   */
  frameOrigins: string[];
  /** Maps a pasted iframe `src` back to the page URL. Without it, the `src` itself is tried against `match`. */
  fromIframe?: (src: URL) => string | null | undefined;
  /** The site's own embed code (blockquote, div, link or script), read on paste and load and written back on export. */
  snippet?: EmbedSnippet;
  /** @deprecated Use `snippet`. Reads the page URL from the site's embed markup. */
  fromHTML?: (el: Element) => string | null | undefined;
  /**
   * `"iframe"` (the default): `toEmbed` returns the frame URL. `"widget"`, for sites that offer no frame
   * URL: `toEmbed` returns the script URL, and the snippet plus that script run in a sandboxed frame with
   * an opaque origin, so the script can't reach the app.
   */
  render?: "iframe" | "widget";
  /** Keep a pasted iframe's `width`/`height` as the aspect ratio (GIFs, photos), instead of the provider's size. */
  pastedSize?: boolean;
  toEmbed: (url: string, match: RegExpMatchArray) => EmbedFrame;
};

export type EmbedFrame = {
  src: string;
  /** CSS aspect ratio, e.g. `"16/9"`. Ignored when `height` is set. */
  aspectRatio?: string;
  /** Fixed height in pixels. */
  height?: number;
  /** Widest the frame gets, in pixels. */
  maxWidth?: number;
  /** Permissions policy. Defaults to `PROVIDER_ALLOW` for providers; generic embeds get none. */
  allow?: string;
  /** Defaults to `PROVIDER_SANDBOX` for providers and `GENERIC_SANDBOX` for generic embeds. */
  sandbox?: string;
};

export type ColorToolOptions = {
  /** Offer the nine palette colours. Default `true`. */
  palette?: boolean;
  /** Offer document colours and Custom… (any hex). With `false`, pasted hex snaps to a named colour. Default `true`. */
  custom?: boolean;
  /** Brand colours: lowercase names (`a-z`, `0-9`, `-`) that aren't palette names, and `#rrggbb` values. */
  swatches?: readonly ColorSwatch[];
};

export type ColorSwatch = { name: string; hex: string };

export type GoogleDriveImport = {
  /** Opens a picker and returns a file. No OAuth is built in; the host supplies the file. */
  pickFile: () => Promise<File | null>;
};