autumnnote 2.7.0 → 3.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "autumnnote",
-  "version": "2.7.0",
-  "description": "WYSIWYG rich-text editor built with vanilla JavaScript \u2014 zero dependencies, no jQuery. Dark mode, @mention, markdown shortcuts, bubble toolbar. React and Vue\u00a03 wrappers included.",
+  "version": "3.0.0",
+  "description": "WYSIWYG rich-text editor built with vanilla JavaScript — zero dependencies, no jQuery. Dark mode, @mention, markdown shortcuts, bubble toolbar. React and Vue 3 wrappers included.",
   "type": "module",
   "main": "dist/autumnnote.cjs",
   "module": "dist/autumnnote.es.js",
@@ -119,18 +119,18 @@
     "@vitest/browser-playwright": "^4.1.10",
     "@vitest/coverage-v8": "^4.1.8",
     "cross-env": "^10.1.0",
-    "eslint": "^10.7.0",
-    "jsdom": "^25.0.1",
-    "playwright": "^1.61.1",
-    "rollup-plugin-visualizer": "^7.0.1",
-    "sass": "^1.101.0",
-    "typescript": "^6.0.2",
-    "vite": "^8.1.5",
+    "eslint": "^10.8.1",
+    "jsdom": "^30.0.1",
+    "playwright": "^1.62.1",
+    "rollup-plugin-visualizer": "^7.1.1",
+    "sass": "^1.102.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.1",
     "vitest": "^4.1.8"
   },
   "packageManager": "pnpm@11.1.3",
   "engines": {
-    "node": ">=20.19.0"
+    "node": "^22.22.2 || >=24.15.0"
   },
   "browserslist": [
     "last 2 versions",

package/src/js/core/func.js

@@ -108,9 +108,14 @@ export function isFunction(val) {
  * mutations to the merged result do not bleed back into the source object
  * (e.g. mutating `instance.options.fontFamilies` should not affect
  * `AutumnNote.defaults.fontFamilies`).
- * @param {object} target
- * @param {object} source
- * @returns {object}
+ *
+ * The result starts as a copy of `target`, so it carries `target`'s shape —
+ * `source` only overwrites values. Typing the return as `T` rather than
+ * `object` is what lets callers read properties off the merged result.
+ * @template {object} T
+ * @param {T} target
+ * @param {object} [source]
+ * @returns {T}
  */
 export function mergeDeep(target, source) {
   // Start with a shallow copy of target; clone any arrays to avoid shared refs
@@ -133,16 +138,43 @@ export function mergeDeep(target, source) {
       }
     }
   }
-  return output;
+  // `output` is built key by key from `target`, which no inference can follow.
+  return /** @type {T} */ (output);
+}
+
+/**
+ * Structural equality for option values: plain objects and arrays compare by
+ * content, everything else (functions, DOM nodes, class instances) by identity.
+ * @param {*} a
+ * @param {*} b
+ * @returns {boolean}
+ */
+export function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length
+      && keys.every((key) => Object.hasOwn(b, key) && deepEqual(a[key], b[key]));
+  }
+  return false;
 }
 
 /**
- * Checks if value is a plain object.
+ * Checks if value is a plain object (an object literal or Object.create(null)).
+ *
+ * DOM nodes and class instances are not: mergeDeep() used to recurse into
+ * them, which turned a `popupContainer` element into a detached copy and
+ * stripped the prototype methods off class-based adapters.
  * @param {*} val
  * @returns {boolean}
  */
 export function isPlainObject(val) {
-  return val !== null && typeof val === 'object' && !Array.isArray(val);
+  if (val === null || typeof val !== 'object') return false;
+  const proto = Object.getPrototypeOf(val);
+  return proto === Object.prototype || proto === null;
 }
 
 /**

package/src/js/i18n/de.js

@@ -159,6 +159,8 @@ export const de = {
     replaceBtn:         'Ersetzen',
     noResults:          'Keine Ergebnisse',
     useRegex:           'Regulären Ausdruck verwenden',
+    prevMatch:          'Zurück (Umschalt+Eingabe)',
+    nextMatch:          'Weiter (Eingabe)',
     replaceAllBtn:      'Alle ersetzen',
     close:              '×',
   },
@@ -167,6 +169,7 @@ export const de = {
     title:     'Tastenkürzel',
     ariaLabel: 'Tastenkürzel',
     close:     'Schließen',
+    customCategory: 'Benutzerdefiniert',
     shortcuts: [
       {
         category: 'Textformatierung',
@@ -244,6 +247,13 @@ export const de = {
     charsLimit:   (n, max) => `Zeichen: ${n}/${max}`,
   },
 
+  a11y: {
+    editor:     'Rich-Text-Editor',
+    toolbar:    'Editor-Werkzeugleiste',
+    statistics: 'Editor-Statistik',
+    tableSize:  'Tabellengröße wählen',
+  },
+
   tooltips: {
     link: {
       ariaLabel:  'Link-Aktionen',

package/src/js/i18n/en.js

@@ -162,6 +162,8 @@ export const en = {
     replaceAllBtn:      'Replace All',
     noResults:          'No results',
     useRegex:           'Use Regular Expression',
+    prevMatch:          'Previous (Shift+Enter)',
+    nextMatch:          'Next (Enter)',
     close:              '\u00d7',
   },
 
@@ -176,6 +178,7 @@ export const en = {
     title:     'Keyboard Shortcuts',
     ariaLabel: 'Keyboard Shortcuts',
     close:     'Close',
+    customCategory: 'Custom',
     shortcuts: [
       {
         category: 'Text Formatting',
@@ -257,6 +260,13 @@ export const en = {
     charsLimit: (n, max) => `Chars: ${n}/${max}`,
   },
 
+  a11y: {
+    editor:     'Rich text editor',
+    toolbar:    'Editor toolbar',
+    statistics: 'Editor statistics',
+    tableSize:  'Select table size',
+  },
+
   tooltips: {
     link: {
       ariaLabel:  'Link actions',

package/src/js/i18n/es.js

@@ -159,6 +159,8 @@ export const es = {
     replaceBtn:         'Reemplazar',
     noResults:          'Sin resultados',
     useRegex:           'Usar expresión regular',
+    prevMatch:          'Anterior (Mayús+Intro)',
+    nextMatch:          'Siguiente (Intro)',
     replaceAllBtn:      'Reemplazar todo',
     close:              '×',
   },
@@ -167,6 +169,7 @@ export const es = {
     title:     'Atajos de teclado',
     ariaLabel: 'Atajos de teclado',
     close:     'Cerrar',
+    customCategory: 'Personalizados',
     shortcuts: [
       {
         category: 'Formato de texto',
@@ -244,6 +247,13 @@ export const es = {
     charsLimit:   (n, max) => `Caracteres: ${n}/${max}`,
   },
 
+  a11y: {
+    editor:     'Editor de texto enriquecido',
+    toolbar:    'Barra de herramientas del editor',
+    statistics: 'Estadísticas del editor',
+    tableSize:  'Seleccionar tamaño de tabla',
+  },
+
   tooltips: {
     link: {
       ariaLabel:  'Acciones de enlace',

package/src/js/i18n/fr.js

@@ -160,6 +160,8 @@ export const fr = {
     replaceBtn:         'Remplacer',
     noResults:          'Aucun résultat',
     useRegex:           'Utiliser une expression régulière',
+    prevMatch:          'Précédent (Maj+Entrée)',
+    nextMatch:          'Suivant (Entrée)',
     replaceAllBtn:      'Tout remplacer',
     close:              '\u00d7',
   },
@@ -168,6 +170,7 @@ export const fr = {
     title:     'Raccourcis clavier',
     ariaLabel: 'Raccourcis clavier',
     close:     'Fermer',
+    customCategory: 'Personnalisés',
     shortcuts: [
       {
         category: 'Mise en forme du texte',
@@ -245,6 +248,13 @@ export const fr = {
     charsLimit: (n, max) => `Caractères\u00a0: ${n}/${max}`,
   },
 
+  a11y: {
+    editor:     'Éditeur de texte enrichi',
+    toolbar:    'Barre d\'outils de l\'éditeur',
+    statistics: 'Statistiques de l\'éditeur',
+    tableSize:  'Choisir la taille du tableau',
+  },
+
   tooltips: {
     link: {
       ariaLabel:  'Actions du lien',

package/src/js/i18n/ja.js

@@ -160,6 +160,8 @@ export const ja = {
     replaceBtn:         '置換',
     noResults:          '結果なし',
     useRegex:           '正規表現を使用',
+    prevMatch:          '前へ (Shift+Enter)',
+    nextMatch:          '次へ (Enter)',
     replaceAllBtn:      'すべて置換',
     close:              '\u00d7',
   },
@@ -168,6 +170,7 @@ export const ja = {
     title:     'キーボードショートカット',
     ariaLabel: 'キーボードショートカット',
     close:     '閉じる',
+    customCategory: 'カスタム',
     shortcuts: [
       {
         category: 'テキスト書式',
@@ -245,6 +248,13 @@ export const ja = {
     charsLimit: (n, max) => `文字数: ${n}/${max}`,
   },
 
+  a11y: {
+    editor:     'リッチテキストエディター',
+    toolbar:    'エディターツールバー',
+    statistics: 'エディターの統計',
+    tableSize:  '表のサイズを選択',
+  },
+
   tooltips: {
     link: {
       ariaLabel:  'リンク操作',

package/src/js/i18n/ko.js

@@ -159,6 +159,8 @@ export const ko = {
     replaceBtn:         '바꾸기',
     noResults:          '결과 없음',
     useRegex:           '정규식 사용',
+    prevMatch:          '이전 (Shift+Enter)',
+    nextMatch:          '다음 (Enter)',
     replaceAllBtn:      '모두 바꾸기',
     close:              '×',
   },
@@ -167,6 +169,7 @@ export const ko = {
     title:     '키보드 단축키',
     ariaLabel: '키보드 단축키',
     close:     '닫기',
+    customCategory: '사용자 지정',
     shortcuts: [
       {
         category: '텍스트 서식',
@@ -244,6 +247,13 @@ export const ko = {
     charsLimit:   (n, max) => `글자: ${n}/${max}`,
   },
 
+  a11y: {
+    editor:     '서식 있는 텍스트 편집기',
+    toolbar:    '편집기 도구 모음',
+    statistics: '편집기 통계',
+    tableSize:  '표 크기 선택',
+  },
+
   tooltips: {
     link: {
       ariaLabel:  '링크 작업',

package/src/js/i18n/vi.js

@@ -161,6 +161,8 @@ export const vi = {
     replaceAllBtn:      'Thay thế tất cả',
     noResults:          'Không có kết quả',
     useRegex:           'Dùng biểu thức chính quy',
+    prevMatch:          'Trước (Shift+Enter)',
+    nextMatch:          'Tiếp (Enter)',
     close:              '\u00d7',
   },
 
@@ -168,6 +170,7 @@ export const vi = {
     title:     'Phím tắt bàn phím',
     ariaLabel: 'Phím tắt bàn phím',
     close:     'Đóng',
+    customCategory: 'Tùy chỉnh',
     shortcuts: [
       {
         category: 'Định dạng văn bản',
@@ -245,6 +248,13 @@ export const vi = {
     charsLimit: (n, max) => `Ký tự: ${n}/${max}`,
   },
 
+  a11y: {
+    editor:     'Trình soạn thảo văn bản',
+    toolbar:    'Thanh công cụ soạn thảo',
+    statistics: 'Thống kê văn bản',
+    tableSize:  'Chọn kích thước bảng',
+  },
+
   tooltips: {
     link: {
       ariaLabel:  'Hành động liên kết',

package/src/js/i18n/zh.js

@@ -160,6 +160,8 @@ export const zh = {
     replaceBtn:         '替换',
     noResults:          '没有结果',
     useRegex:           '使用正则表达式',
+    prevMatch:          '上一个 (Shift+Enter)',
+    nextMatch:          '下一个 (Enter)',
     replaceAllBtn:      '全部替换',
     close:              '\u00d7',
   },
@@ -168,6 +170,7 @@ export const zh = {
     title:     '键盘快捷键',
     ariaLabel: '键盘快捷键',
     close:     '关闭',
+    customCategory: '自定义',
     shortcuts: [
       {
         category: '文字格式',
@@ -245,6 +248,13 @@ export const zh = {
     charsLimit: (n, max) => `字符数: ${n}/${max}`,
   },
 
+  a11y: {
+    editor:     '富文本编辑器',
+    toolbar:    '编辑器工具栏',
+    statistics: '编辑器统计',
+    tableSize:  '选择表格大小',
+  },
+
   tooltips: {
     link: {
       ariaLabel:  '链接操作',

package/types/index.d.ts

@@ -29,6 +29,40 @@ export interface AutoSaveAdapter {
   remove?(payload: { key: string; context: Context }): void | Promise<void>;
 }
 
+/**
+ * One entry in the right-click menu. Most entries are a labelled row with an
+ * `action`; the remaining fields each select a different kind of row, and an
+ * entry that sets one of them ignores `action`.
+ */
+export interface ContextMenuItem {
+  /** Unique identifier. Omitted on separators and other non-interactive rows. */
+  name?: string;
+  label?: string;
+  /** Icon markup (SVG or HTML). */
+  icon?: string;
+  /** Key into `locale.contextMenu`; preferred over `label` when it resolves. */
+  localeKey?: string;
+  action?: (context: Context) => void;
+  /** Greys the row out and blocks the click. A function is evaluated per open. */
+  disabled?: boolean | ((context: Context) => boolean);
+  /** Opens a submenu instead of firing `action`. */
+  navigate?: ContextMenuItem[] | ((context: Context) => ContextMenuItem[]);
+  /** A horizontal rule. `sep` is an accepted alias. */
+  separator?: boolean;
+  /** @see separator */
+  sep?: boolean;
+  /** Renders as the submenu's "back" row rather than a command. */
+  back?: boolean;
+  /** Renders a row of quick colour swatches for `colorType`. */
+  colorStrip?: 'foreColor' | 'hiliteColor';
+  /** Renders the full palette plus a native colour input, for `colorType`. */
+  colorPalette?: boolean;
+  /** Which command `colorStrip` / `colorPalette` applies. */
+  colorType?: 'foreColor' | 'hiliteColor';
+  /** Renders the drag-to-size table picker. */
+  tableGrid?: boolean;
+}
+
 export interface SlashCommand {
   id: string;
   label?: string;
@@ -45,6 +79,38 @@ export interface CollaborationAdapter {
   onLocalChange?(html: string, context: Context): void | Promise<void>;
 }
 
+/** Built-in design tokens accepted by `themeVars` (any `--an-*` key also passes through). */
+export interface AsnThemeVars {
+  primary?: string;
+  'primary-hover'?: string;
+  border?: string;
+  bg?: string;
+  'bg-toolbar'?: string;
+  'bg-btn-hover'?: string;
+  'bg-btn-active'?: string;
+  text?: string;
+  muted?: string;
+  'statusbar-bg'?: string;
+  radius?: string;
+  'radius-sm'?: string;
+  'font-family'?: string;
+  'font-size'?: string;
+  'line-height'?: string;
+  [customProperty: `--an-${string}`]: string | number | undefined;
+}
+
+/**
+ * A keyMap value. Built-in commands: undo, redo, bold, italic, underline,
+ * inlineCode, link, find, findReplace, shortcuts, pastePlainText — or any
+ * toolbar button name. A handler returning `false` lets the key through.
+ */
+export type AsnKeyBinding =
+  | false
+  | null
+  | string
+  | ((context: Context, event: KeyboardEvent) => void | false)
+  | { run: (context: Context, event: KeyboardEvent) => void | false; description?: string };
+
 export interface AsnOptions {
   /** Placeholder text when the editor is empty. */
   placeholder?: string;
@@ -58,6 +124,12 @@ export interface AsnOptions {
   focus?: boolean;
   /** Show the resize handle in the statusbar. */
   resizable?: boolean;
+  /**
+   * Show the statusbar (word/char count and resize handle). Default `true`.
+   * When `false` the bar is hidden, but `getWordCount()`/`getCharCount()`
+   * keep working. Can be toggled at runtime with `updateOptions()`.
+   */
+  statusbar?: boolean;
   /** Toolbar button group configuration. */
   toolbar?: Array<Array<ToolbarItemDef | string>>;
   /** Use Bootstrap button classes on toolbar buttons. */
@@ -98,6 +170,16 @@ export interface AsnOptions {
   onInit?: (context: Context) => void;
   /** Callback fired just before the editor instance is destroyed. */
   onDestroy?: (context: Context) => void;
+  /**
+   * Fired before a command runs from the toolbar, a keyboard shortcut, the
+   * context menu or the bubble toolbar. Return `false` to cancel it.
+   */
+  onBeforeCommand?: (data: {
+    name: string;
+    value?: unknown;
+    source: 'toolbar' | 'shortcut' | 'contextMenu' | 'bubbleToolbar';
+    event?: KeyboardEvent;
+  }) => void | false;
   /** Callback fired whenever the selection changes inside the editor. */
   onSelectionChange?: (context: Context) => void;
   /** Callback fired when the character limit is reached. */
@@ -140,8 +222,29 @@ export interface AsnOptions {
   stickyToolbar?: boolean;
   /** Top offset in px for sticky toolbar (e.g. height of a fixed nav bar). */
   stickyToolbarOffset?: number;
-  /** Colour theme: 'light' (default) | 'dark'. */
+  /**
+   * Colour theme: 'light' (default), 'dark', or 'auto' (follows the OS
+   * `prefers-color-scheme`). Can be changed at runtime with `updateOptions()`.
+   */
   theme?: 'light' | 'dark' | 'auto';
+  /**
+   * Design-token overrides applied to this editor and its floating UI, e.g.
+   * `{ primary: '#f97316', radius: '10px' }`. Keys are token names (`primary`)
+   * or full custom properties (`--an-primary`). See README "Theming".
+   */
+  themeVars?: AsnThemeVars | null;
+  /**
+   * Added to the z-index of every floating layer (tooltips, popovers, dialogs,
+   * fullscreen). Use it to lift the editor's UI above a host modal. Default 0.
+   */
+  zIndexOffset?: number;
+  /**
+   * Where the editor mounts its floating UI: a selector, an element or a
+   * ShadowRoot. Default `document.body`. Use it inside a modal that traps
+   * focus, or a shadow root. The element must not have `transform`, `filter`
+   * or `contain` set, because floating UI is positioned against the viewport.
+   */
+  popupContainer?: string | Element | ShadowRoot | null;
   /** Auto-load Prism.js for syntax highlighting inside code blocks. */
   codeHighlight?: boolean;
   /** CDN base URL for Prism assets. */
@@ -165,6 +268,56 @@ export interface AsnOptions {
   defaultFontSize?: string;
   /** Font families shown in the font-family toolbar dropdown. */
   fontFamilies?: string[];
+  /** Sizes offered by the font-size dropdown (CSS lengths). Default 8px–72px. */
+  fontSizes?: string[];
+  /** Values offered by the line-height dropdown. Default '1.0'–'3.0'. */
+  lineHeights?: string[];
+  /** Block formats offered by the paragraph-style dropdown; `value` is a block tag name. */
+  paragraphStyles?: Array<{ value: string; label: string }>;
+  /** Replaces the built-in colour swatches (toolbar, bubble toolbar, context menu). `colorSwatches` are still prepended. */
+  colorPalette?: string[] | null;
+  /**
+   * Per-editor icon overrides keyed by button name (`bold`) or icon id
+   * (`list-ul`). A value starting with `<` is markup (e.g. an SVG); anything
+   * else is a CSS class list rendered as `<i class="...">`.
+   */
+  icons?: Record<string, string> | null;
+  /**
+   * Per-editor button definitions, usable by name in `toolbar` without the
+   * global registry: `{ save: { icon: 'save', tooltip: 'Save', action } }`.
+   */
+  buttons?: Record<string, Omit<ButtonDef, 'name'> | Omit<DropdownDef, 'name'>> | ToolbarItemDef[] | null;
+  /**
+   * Keyboard shortcuts merged over the defaults. Keys are combos (`Mod+B`,
+   * `Ctrl+Alt+1`; `Mod` = Ctrl or Cmd). Values: `false` to disable, a
+   * built-in command or toolbar button name, a handler, or `{ run, description }`.
+   */
+  keyMap?: Record<string, AsnKeyBinding> | null;
+  /** Link dialog defaults. */
+  linkDefaults?: {
+    /** Pre-tick "open in new tab" for new links. Default false. */
+    openInNewTab?: boolean;
+    /** `rel` for new-tab links; `noopener` is always added. Default 'noopener noreferrer'. */
+    rel?: string;
+    /** Prefix for bare domains ('example.com'); '' disables. Relative links are never prefixed. Default 'https://'. */
+    defaultProtocol?: string;
+  } | null;
+  /**
+   * Extra video providers for the video dialog, tried before the built-in
+   * YouTube/Vimeo rules. The embed URL's host must be built in or listed in
+   * `iframeHosts`, otherwise the provider is ignored.
+   */
+  videoProviders?: Array<{
+    name: string;
+    match: RegExp;
+    embed: (match: RegExpExecArray, url: string) => string;
+  }> | null;
+  /**
+   * Extra hostnames whose iframes survive sanitisation (exact hostnames,
+   * HTTPS only), e.g. `['player.twitch.tv']`. Every listed host can render
+   * arbitrary content inside the document — list only hosts you trust.
+   */
+  iframeHosts?: string[] | null;
   /** Start the editor in read-only (non-editable) mode. */
   readOnly?: boolean;
   /** Enable browser spellcheck in the editable area (default: true). */
@@ -188,7 +341,11 @@ export interface AsnOptions {
   /** Insert a header row (<thead>) when creating new tables. */
   tableHeaderRow?: boolean;
   /** Callback fired after every paste event. */
-  onPaste?: (data: { text: string; html: string | null }) => void;
+  /**
+   * Fired on every paste before anything is inserted. Return `false` to cancel
+   * the paste, or an HTML string to insert instead (it is sanitised).
+   */
+  onPaste?: (data: { text: string; html: string | null }) => void | false | string;
   /** Callback fired when pasted or dropped content cannot be processed. */
   onPasteError?: (error: PasteErrorData) => void;
   /** Additional color swatches shown at the top of the color picker. */
@@ -215,7 +372,7 @@ export interface AsnOptions {
   autoSaveRestoreTimeout?: number;
   /** Callback fired after the user chooses to restore a draft. */
   onAutoSaveRestore?: (html: string, context: Context) => void;
-  /** Maximum paste size in MB before paste is silently dropped (0 = unlimited). Default: 5. */
+  /** Maximum paste size in bytes; larger pastes are dropped and `pasteError` fires (0 = unlimited). Default: 5242880 (5 MB). */
   maxPasteSize?: number;
   /** Minimum image dimension in px during resize (width and height). Default: 20. */
   minImageSize?: number;
@@ -237,6 +394,14 @@ export interface AsnOptions {
   /** @mention autocomplete configuration. Activated when mention.onSearch is provided. */
   mention?: MentionOptions | null;
 
+  // ---- Right-click menu ------------------------------------------------------
+
+  /**
+   * Replaces the built-in right-click menu. Omit it, or omit `items`, to keep
+   * the default list.
+   */
+  contextMenu?: { items?: ContextMenuItem[] } | null;
+
   // ---- Slash command menu ----------------------------------------------------
 
   /** Show a "/" command palette for quick block insertion (headings, lists, table, image, ...). Default: true. */
@@ -247,6 +412,7 @@ export interface AsnOptions {
   documentAdapters?: Record<string, DocumentAdapter>;
   /** Optional external image processor, such as a Web Worker bridge. */
   imageProcessor?: (file: File, helpers: { context: Context }) => string | Promise<string>;
+  /** Bridge notified with local HTML changes. */
   collaborationAdapter?: CollaborationAdapter | null;
   /** Adds stable IDs to top-level blocks for external collaboration adapters. */
   blockIds?: boolean;
@@ -404,6 +570,8 @@ export interface AsnLocale {
     title: string;
     ariaLabel: string;
     close: string;
+    /** Heading of the section listing `keyMap` shortcuts. */
+    customCategory: string;
     shortcuts: Array<{ category: string; items: Array<{ keys: string; action: string }> }>;
   };
   contextMenu: Record<string, string>;
@@ -414,6 +582,13 @@ export interface AsnLocale {
     chars: (n: number) => string;
     charsLimit: (n: number, max: number) => string;
   };
+  /** Accessible names for landmarks that have no visible label. */
+  a11y: {
+    editor: string;
+    toolbar: string;
+    statistics: string;
+    tableSize: string;
+  };
   tooltips: {
     link: Record<string, string>;
     image: Record<string, string>;
@@ -507,13 +682,14 @@ export declare class Context {
   invoke(path: string, ...args: unknown[]): unknown;
 
   /** Subscribes to an editor event. Returns an unsubscribe function. */
-  on(eventName: string, handler: (...args: unknown[]) => void): () => void;
+  on(eventName: string, handler: (...args: any[]) => unknown): () => void;
 
   /** Unsubscribes from an editor event. */
   off(eventName: string, handler: (...args: unknown[]) => void): void;
 
   /** Triggers an editor event. */
-  triggerEvent(eventName: string, ...args: unknown[]): void;
+  /** Fires an event; returns the last value a handler returned (other than undefined). */
+  triggerEvent(eventName: string, ...args: unknown[]): unknown;
 
   /** Applies runtime-safe option changes without recreating the editor. */
   updateOptions(overrides: Partial<AsnOptions>): this;
@@ -776,6 +952,13 @@ export interface AutumnNoteStatic {
    * referenced by string name in toolbar configuration.
    */
   registerButton(btnDef: ToolbarItemDef): this;
+
+  /**
+   * Registers an icon for every editor, keyed by button name or icon id.
+   * `icon` is SVG/HTML markup, or a CSS class list such as `'bi bi-type-bold'`.
+   * The per-editor `icons` option takes precedence.
+   */
+  registerIcon(name: string, icon: string): this;
   registerSlashCommand(command: SlashCommand): this;
 
   /**