autumnnote 1.0.8 → 1.1.0

package/README.md

@@ -1,8 +1,8 @@
-# AutumnNote
+# Autumn Note
 
 <p align="center"><img src="image/banner.png" width="120" alt="AutumnNote Banner"/></p>
 
-[![Version](https://img.shields.io/badge/version-1.0.8-blue)](#)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](#)
 [![CI](https://github.com/cmm-cmm/Autumn-Note/actions/workflows/pages.yml/badge.svg)](https://github.com/cmm-cmm/Autumn-Note/actions/workflows/pages.yml)
 [![JavaScript](https://img.shields.io/badge/JavaScript-ES2022-F7DF1E?logo=javascript&logoColor=black)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
 [![Build](https://img.shields.io/badge/Build-Vite-646CFF?logo=vite&logoColor=white)](https://vitejs.dev/)
@@ -11,37 +11,60 @@
 [![jQuery](https://img.shields.io/badge/jQuery-free-lightgrey)](#)
 [![FontAwesome](https://img.shields.io/badge/FontAwesome-6.5.2-528DD7?logo=fontawesome&logoColor=white)](https://fontawesome.com/)
 
-A modern, lightweight WYSIWYG rich-text editor with vanilla JavaScript (ES2022+), no jQuery dependency.
+A modern, lightweight WYSIWYG rich-text editor built with vanilla JavaScript (ES2022+) — no jQuery, no heavy dependencies.
 
-> ✍️ *Write rich text. No dependencies. No drama.*
+> Write rich text. No dependencies. No drama.
 
-🔗 **[Live Demo](https://cmm-cmm.github.io/Autumn-Note/)**
+[Live Demo](https://cmm-cmm.github.io/Autumn-Note/)
 
 <p align="center"><img src="demo/Screenshot.png" alt="AutumnNote Screenshot"/></p>
 
 ---
 
+## Table of Contents
+
+1. [Features](#features)
+2. [Installation](#installation)
+3. [Quick Start](#quick-start)
+4. [API](#api)
+5. [Options](#options)
+6. [Toolbar Customisation](#toolbar-customisation)
+7. [Keyboard Shortcuts](#keyboard-shortcuts)
+8. [Mentions](#mentions)
+9. [Project Structure](#project-structure)
+10. [Comparison](#comparison)
+11. [License](#license)
+
+---
+
 ## Features
 
 ### Editing
 - **Text formatting** — bold, italic, underline, strikethrough, superscript, subscript
 - **Paragraph styles** — Normal, H1–H6, Blockquote, Code block
 - **Font family** — customisable dropdown (10 families by default)
+- **Font size** — configurable default via `defaultFontSize`; applied to new content
 - **Line height** — dropdown from 1.0 to 3.0
-- **Text & highlight colour** — native colour picker with last-used colour memory
+- **Text and highlight colour** — native colour picker with last-used colour memory; custom brand swatches via `colorSwatches`
 - **Alignment** — left, center, right, justify
 - **Lists** — unordered and ordered, with indent / outdent; Tab/Shift+Tab in list context
-- **Undo / redo** — built-in history stack (100 levels, `Ctrl+Z` / `Ctrl+Y`)
+- **Checklist** — interactive checkbox list; toggle items by clicking; converts to/from plain paragraphs on outdent
+- **Undo / redo** — built-in history stack (configurable depth via `historyLimit`, `Ctrl+Z` / `Ctrl+Y`)
 - **Tab key** — configurable spaces-per-tab; smart list indentation inside `<li>`
+- **RTL support** — set `direction: 'rtl'` to flip the editor layout and text direction
 
 ### Insert
 - **Horizontal rule** — inserts an `<hr>` at the current caret position
 - **Link dialog** — URL, display text (auto-filled from selection), "Open in new tab" checkbox; edits existing links when caret is inside an `<a>`
-- **Image dialog** — insert by URL with alt text, or file upload (base64 embed); enforces `maxImageSize`; supports custom `onImageUpload` handler for server-side upload
+- **Image dialog** — insert by URL with alt text, or file upload (base64 embed); enforces `maxImageSize`; file input restricted to browser-renderable MIME types; supports custom `onImageUpload` handler for server-side upload
+- **Image crop overlay** — inline interactive crop tool triggered from the image tooltip; corner and edge drag handles; canvas-based crop export; CORS fallback warning
 - **Video dialog** — paste a YouTube watch/short URL, Vimeo URL, or direct `.mp4 / .webm / .ogg` URL; configurable width; renders as responsive `<iframe>` or `<video>`
-- **Table** — interactive grid picker (up to 10×10); floating tooltip on table click for full row/column/cell management (see [Table tooltip](#table-tooltip))
-- **Emoji picker** — ~380 Unicode emoji across 7 categories (Smileys, People, Animals, Food, Travel, Objects, Symbols); keyword search; click to insert instantly as a plain text character (UTF-8 / utf8mb4 safe)
-- **FA Icon picker** — FontAwesome 6 Free Solid icons across 8 categories (Popular, Interface, Navigation, Media, Communication, Files, People, Objects); keyword search; configurable style (Solid / Regular / Light), size, and colour; inserts as `<i>` element; auto-injects FA CDN if not detected on the page
+- **Table** — interactive grid picker (up to 10x10); optional header row (`tableHeaderRow`); floating tooltip for full row/column/cell management
+- **Emoji picker** — approximately 380 Unicode emoji across 7 categories (Smileys, People, Animals, Food, Travel, Objects, Symbols); keyword search; click to insert as plain UTF-8 character
+- **FA Icon picker** — FontAwesome 6 Free Solid icons across 8 categories; keyword search; configurable style, size, and colour; inserts as `<i>` element; auto-injects FA CDN if not on the page
+
+### Search
+- **Find and Replace** — `Ctrl+F` to find, `Ctrl+H` for find-and-replace; TreeWalker text matching; `<mark>` highlighting; case-sensitive toggle; Prev/Next navigation; single and replace-all modes
 
 ### Inline tooltips
 Floating toolbars appear automatically when the user clicks on an editable element:
@@ -49,34 +72,53 @@ Floating toolbars appear automatically when the user clicks on an editable eleme
 | Element | Actions |
 |---|---|
 | **Link** | Open in new tab, Edit (reopens dialog), Unlink |
-| **Image** | Edit alt/URL (reopens dialog), Delete |
+| **Image** | Edit alt/URL (reopens dialog), Crop, Delete |
 | **Video** | Edit (reopens dialog), Delete |
 | **Table cell** | Row above/below, Delete row, Column left/right, Delete column, Merge cells, Unmerge cells, Cell selection mode, Column width, Row height, Border width, Delete table |
-| **Code block** (`<pre>`) | Copy code, Delete block |
+| **Code block** | Copy code, Delete block |
 
 ### Context menu
-Right-click inside the editor opens a context menu with: **Undo**, **Redo**, **Cut**, **Copy**, **Paste**, **Bold**, **Italic**, **Underline**, **Copy Format**, **Paste Format**, **Remove Format**.
+Right-click inside the editor opens a context menu with: **Undo**, **Redo**, **Cut**, **Copy**, **Paste**, **Bold**, **Italic**, **Underline**, **Copy Format**, **Paste Format**, **Remove Format**, and a **colour palette** for quick text/highlight colour changes.
+
+### Internationalisation
+- **Built-in locales** — English (`en`), Vietnamese (`vi`), Japanese (`ja`), Simplified Chinese (`zh`), French (`fr`), German (`de`), Spanish (`es`), Korean (`ko`)
+- **Custom locale** — pass any partial locale object to override individual strings
+- **Per-instance language** — set a different `lang` per editor instance on the same page
+- **Auto-fallback** — unknown codes or missing keys fall back to English
 
 ### UI
-- **Toolbar** — fully configurable button groups; renders with FontAwesome icons when detected, falls back to inline SVG icons
+- **Toolbar** — fully configurable button groups; overflow strategy: `wrap` (default) or `scroll`; FontAwesome icons with built-in SVG fallback
+- **Sticky toolbar** — `stickyToolbar: true` pins the toolbar to the viewport top; configurable offset for fixed nav bars
+- **Dark / light theme** — `theme: 'dark'` or `theme: 'light'` (default); full SCSS variable coverage
 - **Image resizer** — drag handle on selected image to resize proportionally
 - **Video resizer** — drag handle on selected video embed to resize
-- **Statusbar** — live word and character count; drag handle to resize editor height
+- **Statusbar** — live word and character count; drag handle to resize editor height; limit warnings when `maxChars` or `maxWords` is reached
 - **Code view** — toggle raw HTML; sanitised before applying back to the editor
 - **Fullscreen** — expands the editor to fill the viewport
 - **Placeholder** — CSS `::before` pseudo-element, zero DOM node cost
+- **Read-only mode** — `readOnly: true` renders a non-editable preview with toolbar hidden; toggle at runtime via `editor.setDisabled()`
+- **Auto-save** — `autoSave: true` persists content to `localStorage` on every change; key configurable via `autoSaveKey`
+- **Auto-save restore** — when `autoSave` and `autoSaveRestore` are both `true`, a dismissible banner prompts the user to restore or discard a previously saved draft on load; configurable age window via `autoSaveRestoreTimeout`
+- **Bubble toolbar** — `bubbleToolbar: true` shows a compact floating toolbar above selected text with quick-access buttons (bold, italic, underline, strikethrough, link, text colour, remove format, inline code); button set configurable via `bubbleToolbarItems`
+- **Markdown shortcuts** — `markdownShortcuts: true` (default) converts Markdown syntax typed in the editor into HTML in real time: `# ` → H1–H3, `> ` → blockquote, `- ` / `* ` → unordered list, `1. ` → ordered list, `[ ] ` → checklist, `---` → HR, ` ``` ` → code block; inline: `**bold**`, `*italic*`, `~~strikethrough~~`, `` `code` ``
+- **Custom focus ring** — `focusColor` accepts any CSS colour string to override the default blue focus ring
+- **Spellcheck** — browser spellcheck enabled by default (`spellcheck: true`)
 
 ### Integration
 - **No jQuery** — pure vanilla ES2022, zero runtime dependencies
-- **Bootstrap friendly** — optional Bootstrap 4/5 styling for toolbar buttons (`useBootstrap: true`)
+- **Bootstrap friendly** — optional Bootstrap 4/5 styling (`useBootstrap: true`)
 - **FontAwesome ready** — auto-detects FA on the page; falls back to built-in SVG icons
 - **Plugin-ready** — register custom modules via `AutumnNote.defaults`
-- **Tree-shakeable** — ES module build; all core utilities are individually exported
+- **Tree-shakeable** — ES module build; all core utilities individually exported
+- **TypeScript definitions** — bundled `types/index.d.ts` with full JSDoc coverage
+- **@mention autocomplete** — type `@` (or any custom trigger) to open a floating dropdown backed by a user-supplied `onSearch` function; inserts a non-editable mention chip; customisable chip HTML via `onInsert`
 
 ### Security
-- All HTML (pasted content, `setHTML()`, or code-view output) is passed through a DOM-based sanitiser that strips `<script>`, `<object>`, `<embed>`, and all `on*` event handler attributes; `<iframe>` elements are permitted in `setHTML()` to support embedded content
+- All HTML (pasted content, `setHTML()`, or code-view output) passes through a DOM-based sanitiser that strips `<script>`, `<object>`, `<embed>`, and all `on*` event handler attributes
+- `<iframe>` elements are permitted in `setHTML()` with src restricted to trusted CDN hosts; `srcdoc` is stripped
 - `javascript:` and `data:` URLs are rejected in links and images
 - Clipboard paste sanitises rich content to remove XSS vectors before inserting
+- `pasteStripAttributes` option strips `class`, `style`, and `data-*` from pasted HTML
 
 ---
 
@@ -85,14 +127,32 @@ Right-click inside the editor opens a context menu with: **Undo**, **Redo**, **C
 ### npm / pnpm / yarn
 
 ```bash
-npm install AutumnNote
+npm install autumnnote
+```
+
+```js
+import AutumnNote from 'autumnnote';
+import 'autumnnote/dist/autumnnote.css';
 ```
 
 ### CDN
 
+**jsDelivr** (Recommended):
+
 ```html
-<link rel="stylesheet" href="dist/AutumnNote.css" />
-<script src="dist/AutumnNote.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/autumnnote"></script>
+```
+
+**unpkg:**
+
+```html
+<script src="https://unpkg.com/autumnnote"></script>
+```
+
+
+```html
+<link rel="stylesheet" href="dist/autumnnote.css" />
+<script src="dist/autumnnote.umd.js"></script>
 ```
 
 > **FontAwesome icons** — the editor auto-detects FontAwesome on the page and falls back to built-in SVG icons when absent. To enable FA icons, include the FA stylesheet:
@@ -101,8 +161,6 @@ npm install AutumnNote
 > <!-- FontAwesome 6 Free (recommended) -->
 > <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css">
 > ```
->
-> If FA is not on the page but the **FA Icon picker** is used, the editor will automatically inject the FontAwesome CDN stylesheet on first open.
 
 ---
 
@@ -111,7 +169,7 @@ npm install AutumnNote
 ### ES Module
 
 ```js
-import AutumnNote from 'AutumnNote';
+import AutumnNote from 'autumnnote';
 
 const editor = AutumnNote.create('#my-editor', {
   placeholder: 'Start typing…',
@@ -126,7 +184,7 @@ const editor = AutumnNote.create('#my-editor', {
 
 ```html
 <div id="my-editor"><p>Hello!</p></div>
-<script src="dist/AutumnNote.umd.js"></script>
+<script src="dist/autumnnote.umd.js"></script>
 <script>
   const editor = AutumnNote.create('#my-editor');
 </script>
@@ -142,527 +200,69 @@ const editor = AutumnNote.create('#my-editor', {
 });
 ```
 
-### With FontAwesome 6
-
-```js
-const editor = AutumnNote.create('#my-editor', {
-  useFontAwesome: true,
-  fontAwesomeClass: 'fa-solid',  // FA 6 prefix
-});
-```
-
----
-
-## Usage
-
-### Read content on demand
-
-The most common pattern — attach a button that reads back the current HTML:
-
-```html
-<link rel="stylesheet" href="dist/autumnnote.css" />
-
-<div id="editor"><p>Hello, <strong>AutumnNote</strong>!</p></div>
-
-<button onclick="getHTML()">Get HTML</button>
-<pre id="output"></pre>
-
-<script src="dist/autumnnote.umd.js"></script>
-<script>
-  const editor = AutumnNote.create('#editor', { height: 300 });
-
-  function getHTML() {
-    document.getElementById('output').innerText = editor.getHTML();
-  }
-</script>
-```
-
-### React to every change
-
-Use `onChange` (or `editor.on('change', fn)`) to update a live preview automatically:
-
-```html
-<div id="editor"><p>Start typing…</p></div>
-<pre id="preview"></pre>
-
-<script src="dist/autumnnote.umd.js"></script>
-<script>
-  const editor = AutumnNote.create('#editor', {
-    height: 300,
-    onChange(html) {
-      document.getElementById('preview').innerText = html;
-    },
-  });
-</script>
-```
-
-### Set and clear content programmatically
-
-```js
-editor.setHTML('<p>New <em>content</em></p>'); // set
-editor.clear();                                 // clear to empty <p>
-console.log(editor.getText());                  // plain text, no markup
-```
-
----
-
-## API
-
-### Factory
-
-| Method | Description |
-|---|---|
-| `AutumnNote.create(selector, options?)` | Creates editor instance(s). `selector` can be a CSS string, `Element`, `NodeList`, or `Element[]`. Returns a `Context` for a single match, or `Context[]` for multiple. |
-| `AutumnNote.destroy(selector)` | Destroys editor(s) matching the selector and restores the original element. |
-| `AutumnNote.getInstance(selector)` | Returns the `Context` for a given element, or `null` if not initialised. |
-| `AutumnNote.defaults` | Global default options object. Mutate before calling `create()` to apply project-wide settings. |
-
-### Context (editor instance)
-
-| Method | Description |
-|---|---|
-| `editor.getHTML()` | Returns the current HTML content. Zero-width spaces inserted by the icon picker are stripped automatically. |
-| `editor.setHTML(html)` | Sets HTML content. Input is sanitised before rendering. |
-| `editor.getText()` | Returns plain text with no markup. |
-| `editor.clear()` | Clears all content, resets to an empty `<p>`. |
-| `editor.setDisabled(bool)` | Disables (`true`) or re-enables (`false`) the editor and toolbar. |
-| `editor.destroy()` | Removes the editor, disposes all modules, and restores the original element. |
-| `editor.on(event, fn)` | Subscribes to an editor event. Returns an unsubscribe function — call it to remove the listener. |
-| `editor.invoke('module.method', ...args)` | Calls any registered module method by dot-separated name. Returns the method's return value. |
-
-### Events
-
-| Name | Payload | Description |
-|---|---|---|
-| `change` | `html: string` | Fired after every content mutation. Debounced internally. |
-| `focus` | — | Editor's editable area gained focus. |
-| `blur` | — | Editor's editable area lost focus. |
-
-#### Subscribing to events
-
-```js
-const editor = AutumnNote.create('#editor');
-
-// Subscribe
-const unsub = editor.on('change', (html) => {
-  document.getElementById('output').innerHTML = html;
-});
-
-// Unsubscribe later
-unsub();
-```
-
-### `invoke()` examples
+### Dark mode
 
 ```js
-// Programmatically open a dialog
-editor.invoke('linkDialog.show');
-editor.invoke('imageDialog.show');
-editor.invoke('emojiDialog.show');
-editor.invoke('iconDialog.show');
-
-// Undo / redo
-editor.invoke('editor.undo');
-editor.invoke('editor.redo');
-
-// Toggle views
-editor.invoke('codeview.toggle');
-editor.invoke('fullscreen.toggle');
-
-// Query state
-const isCodeview  = editor.invoke('codeview.isActive');    // boolean
-const isFullscreen = editor.invoke('fullscreen.isActive'); // boolean
+const editor = AutumnNote.create('#my-editor', { theme: 'dark' });
 ```
 
----
-
-## Options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `placeholder` | `string` | `''` | Placeholder text shown when the editor is empty. |
-| `height` | `number` | `200` | Initial / minimum editor height in px. |
-| `minHeight` | `number` | `100` | Hard minimum height in px (enforced during resize). |
-| `maxHeight` | `number` | `0` | Maximum height in px. `0` = unlimited. |
-| `focus` | `boolean` | `false` | Auto-focus the editor on initialisation. |
-| `resizeable` | `boolean` | `true` | Show the drag-to-resize handle in the statusbar. |
-| `toolbar` | `Array` | default | Array of button group arrays. See [Toolbar customisation](#toolbar-customisation). |
-| `useBootstrap` | `boolean` | `false` | Apply Bootstrap button classes to toolbar buttons. |
-| `bootstrapVersion` | `number` | `5` | Bootstrap major version to target (`4` or `5`). |
-| `toolbarButtonClass` | `string` | `'btn btn-sm btn-light'` | CSS classes applied to toolbar buttons when `useBootstrap` is `true`. |
-| `useFontAwesome` | `boolean` | `true` | Render toolbar icons via FontAwesome when FA is detected on the page. |
-| `fontAwesomeClass` | `string` | `'fas'` | FontAwesome prefix class. Use `'fas'` for FA 5, `'fa-solid'` for FA 6. |
-| `pasteAsPlainText` | `boolean` | `false` | Force all pasted content to plain text, stripping all formatting. |
-| `pasteCleanHTML` | `boolean` | `true` | Sanitise HTML on paste — strips scripts and dangerous attributes. |
-| `allowImageUpload` | `boolean` | `true` | Show the file upload input in the image dialog. |
-| `maxImageSize` | `number` | `5` | Maximum image upload file size in MB. Files exceeding this are rejected with an alert. |
-| `onImageUpload` | `Function` | `null` | `(files: FileList) => void` — custom upload handler. When provided, overrides the default base64 embed behaviour. Insert the resulting URL yourself via `editor.invoke('editor.insertImage', url, alt)`. |
-| `tabSize` | `number` | `0` | Number of spaces inserted per Tab key press outside of lists. `0` = browser default Tab behaviour. |
-| `defaultFontFamily` | `string` | `'Arial'` | Font family applied as the default style for the editable area. |
-| `fontFamilies` | `string[]` | (10 fonts) | Font families listed in the Font Family dropdown. Default: Arial, Arial Black, Comic Sans MS, Courier New, Georgia, Impact, Tahoma, Times New Roman, Trebuchet MS, Verdana. |
-| `onChange` | `Function` | `null` | `(html: string) => void` — shorthand for `editor.on('change', fn)`. |
-| `onFocus` | `Function` | `null` | `(context: Context) => void` — shorthand for `editor.on('focus', fn)`. |
-| `onBlur` | `Function` | `null` | `(context: Context) => void` — shorthand for `editor.on('blur', fn)`. |
-| `stickyToolbar` | `boolean` | `false` | Stick the toolbar to the viewport top when the page is scrolled. |
-| `stickyToolbarOffset` | `number` | `0` | Top offset in px for the sticky toolbar (e.g. height of a fixed navigation bar). |
-| `theme` | `string` | `'light'` | Colour theme: `'light'` or `'dark'`. |
-| `codeHighlight` | `boolean` | `false` | Auto-load Prism.js for syntax highlighting inside `<pre><code>` blocks. |
-| `codeHighlightCDN` | `string` | cdnjs Prism 1.29.0 | Base CDN URL used when auto-loading Prism assets. |
-| `markdownPaste` | `boolean` | `true` | Convert pasted Markdown text to HTML when no HTML is present in the clipboard. |
-| `readOnly` | `boolean` | `false` | Start the editor in read-only (non-editable) mode. The toolbar is hidden and the content area is non-interactive. Toggle programmatically with `editor.setDisabled(bool)`. |
-| `focusColor` | `string` | `null` | Custom CSS colour for the editor focus ring, e.g. `'#f97316'`. Overrides the default blue when set. |
-
----
-
-## Dialogs
-
-### Link dialog
-Fields: **URL** (type=url, required), **Display text** (auto-populated from the current selection), **Open in new tab** checkbox.
-When the caret is inside an existing `<a>` element, the dialog pre-fills with the current link's values and updates in-place on confirm.
-
-### Image dialog
-Fields: **Image URL** (type=url), **Alt text**, and — when `allowImageUpload` is `true` — a **file picker** (accepts `image/*`). Selecting a file embeds it as a base64 data URI unless `onImageUpload` is provided.
-
-### Video dialog
-Fields: **Video URL** (YouTube / Vimeo / direct file), **Width** (px, default 560). Supported URL formats:
-- `https://www.youtube.com/watch?v=…` → `<iframe>` embed
-- `https://youtu.be/…` → `<iframe>` embed
-- `https://vimeo.com/…` → `<iframe>` embed
-- Direct `.mp4`, `.webm`, `.ogg` URL → `<video controls>` element
-
-### Emoji picker
-Displays ~380 Unicode emoji in a scrollable grid grouped into 7 categories. Filter by category tab or keyword search. Clicking an emoji inserts it immediately as a plain Unicode character — no extra "Insert" step. All characters are UTF-8 / utf8mb4 compatible.
-
-### FA Icon picker
-Displays FontAwesome 6 Free Solid icons grouped into 8 categories: **Popular**, **Interface**, **Navigation**, **Media**, **Communication**, **Files**, **People**, **Objects**. Filter by category or keyword search. Before inserting, configure:
-- **Style** — Solid, Regular, or Light (Pro)
-- **Size** — Inherit, 0.75em, 1em, 1.25em, 1.5em, 2em, 3em
-- **Colour** — colour picker + "Use colour" toggle
-
-The icon is inserted as `<i class="fa-solid fa-{name}" style="…">`. If FontAwesome is not loaded on the page, the dialog automatically injects the FA 6 CDN stylesheet on first open.
-
----
-
-## Table tooltip
-
-Clicking inside any table opens a floating tooltip with the following actions:
-
-| Group | Actions |
-|---|---|
-| Rows | Add Row Above, Add Row Below, Delete Row |
-| Columns | Add Column Left, Add Column Right, Delete Column |
-| Cells | Merge Cells |
-| Resize | Column Width (px / %), Row Height (px) |
-| Danger | Delete Table |
-
----
-
-## Toolbar Customisation
-
-The `toolbar` option accepts an array of button groups. Each group is a sub-array of button definition objects:
+### Read-only preview
 
 ```js
-import AutumnNote from 'AutumnNote';
-import {
-  boldBtn, italicBtn, underlineBtn, strikeBtn,
-  foreColorBtn, backColorBtn,
-  linkBtn, imageBtn, videoBtn, tableBtn,
-  emojiBtn, iconBtn,
-  codeviewBtn, fullscreenBtn,
-} from 'AutumnNote/src/js/module/Buttons.js';
-
-AutumnNote.create('#editor', {
-  toolbar: [
-    [boldBtn, italicBtn, underlineBtn, strikeBtn],
-    [foreColorBtn, backColorBtn],
-    [linkBtn, imageBtn, videoBtn, tableBtn],
-    [emojiBtn, iconBtn],
-    [codeviewBtn, fullscreenBtn],
-  ],
-});
+const preview = AutumnNote.create('#preview', { readOnly: true });
+preview.setHTML(savedHtml);
 ```
 
-**Available buttons**
-
-| Export | Type | Tooltip |
-|---|---|---|
-| `paragraphStyleBtn` | dropdown | Paragraph Style |
-| `fontFamilyBtn` | dropdown | Font Family |
-| `lineHeightBtn` | dropdown | Line Height |
-| `undoBtn` / `redoBtn` | button | Undo / Redo |
-| `boldBtn` / `italicBtn` / `underlineBtn` / `strikeBtn` | button | Text style |
-| `superscriptBtn` / `subscriptBtn` | button | Super / Subscript |
-| `foreColorBtn` / `backColorBtn` | color picker | Text colour / Highlight colour |
-| `alignLeftBtn` / `alignCenterBtn` / `alignRightBtn` / `alignJustifyBtn` | button | Alignment |
-| `ulBtn` / `olBtn` / `indentBtn` / `outdentBtn` | button | Lists & indentation |
-| `hrBtn` | button | Horizontal Rule |
-| `linkBtn` | button | Insert Link |
-| `imageBtn` | button | Insert Image |
-| `videoBtn` | button | Insert Video |
-| `tableBtn` | grid picker | Insert Table |
-| `emojiBtn` | button | Insert Emoji |
-| `iconBtn` | button | Insert FA Icon |
-| `codeviewBtn` | button | HTML Code View |
-| `fullscreenBtn` | button | Fullscreen |
-
-### Setting global defaults
+### Auto-save draft
 
 ```js
-import AutumnNote from 'AutumnNote';
-
-// Apply once before any create() calls
-Object.assign(AutumnNote.defaults, {
-  height: 400,
-  placeholder: 'Write something…',
-  fontAwesomeClass: 'fa-solid',
-  fontFamilies: ['Inter', 'Roboto', 'Georgia', 'Courier New'],
+const editor = AutumnNote.create('#my-editor', {
+  autoSave: true,
+  autoSaveKey: 'my-draft',
 });
 ```
 
----
-
-## Custom Image Upload
+### Custom image upload
 
 ```js
-AutumnNote.create('#editor', {
-  allowImageUpload: true,
+const editor = AutumnNote.create('#my-editor', {
   onImageUpload(files) {
-    const formData = new FormData();
-    formData.append('file', files[0]);
-
-    fetch('/api/upload', { method: 'POST', body: formData })
+    const fd = new FormData();
+    fd.append('file', files[0]);
+    fetch('/api/upload', { method: 'POST', body: fd })
       .then(r => r.json())
-      .then(({ url }) => {
-        // Insert the returned URL into the editor
-        this.invoke('editor.insertImage', url, files[0].name);
-      });
+      .then(({ url }) => editor.insertImage(url, files[0].name));
   },
 });
 ```
 
----
-
-## Multiple Instances
+### Bubble toolbar
 
 ```js
-const editors = AutumnNote.create('.rich-editor', { height: 250 });
-// editors is Context[] when selector matches multiple elements
-
-// Iterate all instances
-document.querySelectorAll('.rich-editor').forEach((el) => {
-  const editor = AutumnNote.getInstance(el);
-  console.log(editor.getHTML());
-});
-```
-
----
-
-## Project Structure
-
-```
-src/
-├── js/
-│   ├── core/
-│   │   ├── dom.js            DOM utilities (createElement, on, closest, …)
-│   │   ├── range.js          Selection / Range API helpers (withSavedRange, …)
-│   │   ├── func.js           General helpers (mergeDeep, debounce, …)
-│   │   ├── key.js            Keyboard key constants
-│   │   ├── lists.js          Array helpers
-│   │   ├── env.js            Browser / platform detection
-│   │   ├── markdown.js       Lightweight Markdown → HTML converter (paste handling)
-│   │   └── sanitise.js       DOM-based HTML and URL sanitiser (shared by all modules)
-│   ├── editing/
-│   │   ├── History.js        Undo / redo stack (100 levels)
-│   │   ├── Style.js          execCommand style wrappers
-│   │   ├── Table.js          Table creation and cell manipulation
-│   │   └── Typing.js         Tab / Enter key behaviour
-│   ├── module/
-│   │   ├── Editor.js         Core editing commands + getHTML / setHTML + sanitiser
-│   │   ├── Toolbar.js        Toolbar UI, button rendering (SVG + FA), dropdowns, colour picker
-│   │   ├── Buttons.js        Button / dropdown / colorpicker definitions and defaultToolbar
-│   │   ├── Statusbar.js      Word & character count + drag-to-resize
-│   │   ├── Clipboard.js      Paste sanitisation (HTML clean + plain-text mode)
-│   │   ├── ContextMenu.js    Right-click context menu (cut, copy, paste, format tools)
-│   │   ├── Placeholder.js    CSS-based placeholder
-│   │   ├── Codeview.js       HTML source view toggle
-│   │   ├── Fullscreen.js     Fullscreen mode
-│   │   ├── LinkDialog.js     Link insert / edit dialog
-│   │   ├── LinkTooltip.js    Floating toolbar for links (open / edit / unlink)
-│   │   ├── ImageDialog.js    Image insert dialog (URL + optional file upload)
-│   │   ├── ImageTooltip.js   Floating toolbar for images (edit / delete)
-│   │   ├── ImageResizer.js   Drag handle to resize images
-│   │   ├── VideoDialog.js    Video embed dialog (YouTube, Vimeo, direct file)
-│   │   ├── VideoTooltip.js   Floating toolbar for video embeds (edit / delete)
-│   │   ├── VideoResizer.js   Drag handle to resize video embeds
-│   │   ├── TableTooltip.js   Floating toolbar for tables (row/col/cell management)
-│   │   ├── CodeTooltip.js    Floating toolbar for code blocks (copy / delete)
-│   │   ├── EmojiDialog.js    Unicode emoji picker (~380 emoji, 7 categories)
-│   │   ├── IconDialog.js     FontAwesome icon picker (FA 6 Free Solid, 8 categories)
-│   │   └── ShortcutsDialog.js Keyboard shortcuts reference dialog (Shift+?)
-│   ├── Context.js            Editor instance hub — module registry and event bus
-│   ├── settings.js           Default options (AsnOptions)
-│   ├── renderer.js           DOM layout builder
-│   └── index.js              Public entry point + AutumnNote factory
-└── styles/
-    ├── _variables.scss       SCSS design tokens (colours, spacing, radii, transitions)
-    └── AutumnNote.scss  Main stylesheet
-```
-
----
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Start dev server with HMR (Vite)
-npm run dev
-
-# Build library (ES module + UMD + CSS)
-npm run build
-
-# Run unit tests (Vitest)
-npm test
-```
-
-Build output in `dist/`:
-- `AutumnNote.es.js` — ES module (tree-shakeable)
-- `AutumnNote.umd.js` — UMD bundle (script tag / CommonJS)
-- `AutumnNote.css` — compiled stylesheet
-
----
-
-## Comparison with Summernote
-
-| Feature | Summernote | AutumnNote |
-|---|---|---|
-| jQuery required | Yes | No |
-| Bootstrap required | Optional | No |
-| Build system | Grunt | Vite |
-| Module format | IIFE | ES module + UMD |
-| Written in | ES5 / ES6 mix | ES2022 |
-| HTML sanitisation | Basic | DOM-based (strips scripts, XSS vectors) |
-| Emoji picker | No | Yes (~380 Unicode emoji, 7 categories) |
-| FA icon picker | No | Yes (FA 6 Free Solid, 8 categories, searchable) |
-| Video embeds | No | Yes (YouTube, Vimeo, direct file) |
-| Image / video resize | No | Yes (drag handles) |
-| Inline tooltips | No | Yes (link, image, video, table, code) |
-| Context menu | No | Yes (with format copy/paste) |
-| Right-click context menu | No | Yes |
-
----
-
-## License
-
-MIT
-
----
-
-## Features
-
-### Editing
-- **Text formatting** — bold, italic, underline, strikethrough, superscript, subscript
-- **Paragraph styles** — Normal, H1–H6, Blockquote, Code block
-- **Font family** — customisable dropdown (10 families by default)
-- **Line height** — dropdown from 1.0 to 3.0
-- **Text & highlight colour** — native colour picker with last-used colour
-- **Alignment** — left, center, right, justify
-- **Lists** — unordered and ordered, with indent / outdent
-- **Undo / redo** — built-in history stack (100 levels, `Ctrl+Z` / `Ctrl+Y`)
-- **Tab key** — configurable spaces-per-tab, smart list indentation
-
-### Insert
-- **Horizontal rule**
-- **Link dialog** — insert / edit hyperlinks with text and target options
-- **Image dialog** — insert by URL or file upload (base64 embed); configurable max size
-- **Video dialog** — insert YouTube / Vimeo / direct video URLs as responsive embeds
-- **Table** — interactive grid picker (up to 10×10), context-menu actions (add/delete row/col, merge, split)
-- **Emoji picker** — ~380 Unicode emoji across 7 categories (Smileys, People, Animals, Food, Travel, Objects, Symbols) with keyword search; click to insert instantly
-- **FA Icon picker** — browse FontAwesome 6 Free Solid icons by category with keyword search; configurable style, size, and colour
-
-### UI
-- **Toolbar** — fully configurable button groups; auto-renders with SVG fallback or FontAwesome icons
-- **Inline tooltips** — link, image, video, table, and code-block context tooltips with edit/delete actions
-- **Image resizer** — drag handle to resize inserted images
-- **Video resizer** — drag handle to resize inserted video embeds
-- **Statusbar** — word and character count + drag-to-resize editor height
-- **Code view** — toggle raw HTML source editor with sanitisation on apply
-- **Fullscreen** — expand to fill the viewport
-- **Placeholder** — CSS-based, zero DOM pollution
-- **Context menu** — right-click menu for common actions
-
-### Integration
-- **No jQuery** — pure vanilla ES2022, zero runtime dependencies
-- **Bootstrap friendly** — optional Bootstrap 4/5 styling for toolbar buttons (`useBootstrap: true`)
-- **FontAwesome ready** — auto-detects FA on the page; falls back to inline SVG icons
-- **Plugin-ready** — register custom modules via `AutumnNote.defaults`
-- **Tree-shakeable** — ES module build; all core utilities are individually exported
-
-### Security
-- All HTML (pasted, loaded via `setHTML`, or applied from code view) is sanitised through a DOM-based parser — strips `<script>`, `<iframe>`, `<object>`, all `on*` attributes
-- `javascript:` URLs are rejected in links and images
-- Clipboard paste sanitises and removes XSS vectors before inserting
-
----
-
-## Installation
-
-### npm / pnpm / yarn
-
-```bash
-npm install AutumnNote
-```
-
-### CDN
-
-```html
-<link rel="stylesheet" href="dist/AutumnNote.css" />
-<script src="dist/AutumnNote.umd.js"></script>
-```
-
-> To use FontAwesome toolbar icons, include the FA stylesheet on your page. The editor auto-detects it and falls back to built-in SVG icons when FA is absent.
->
-> ```html
-> <!-- FontAwesome 6 Free -->
-> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css">
-> ```
-
----
-
-## Quick Start
-
-### ES Module
-
-```js
-import AutumnNote from 'AutumnNote';
-
 const editor = AutumnNote.create('#my-editor', {
-  placeholder: 'Start typing…',
-  height: 300,
-  onChange(html) {
-    console.log(html);
-  },
+  bubbleToolbar: true,
+  bubbleToolbarItems: ['bold', 'italic', 'underline', 'strikethrough', 'link', 'removeFormat'],
 });
 ```
 
-### Script tag (UMD)
-
-```html
-<div id="my-editor"><p>Hello!</p></div>
-<script src="dist/AutumnNote.umd.js"></script>
-<script>
-  const editor = AutumnNote.create('#my-editor');
-</script>
-```
-
-### With Bootstrap 5
+### @mention autocomplete
 
 ```js
 const editor = AutumnNote.create('#my-editor', {
-  useBootstrap: true,
-  bootstrapVersion: 5,
-  toolbarButtonClass: 'btn btn-sm btn-light',
+  mention: {
+    onSearch(query, callback) {
+      const users = [
+        { id: 1, label: 'Alice' },
+        { id: 2, label: 'Bob' },
+        { id: 3, label: 'Charlie' },
+      ];
+      callback(users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())));
+    },
+    onInsert(item) {
+      // optional: return custom HTML for the mention chip
+      return `<span class="mention" data-id="${item.id}">@${item.label}</span>`;
+    },
+  },
 });
 ```
 
@@ -674,31 +274,40 @@ const editor = AutumnNote.create('#my-editor', {
 
 | Method | Description |
 |---|---|
-| `AutumnNote.create(selector, options?)` | Creates editor instance(s). Returns a `Context` (or array of `Context`). |
+| `AutumnNote.create(selector, options?)` | Creates editor instance(s). `selector` can be a CSS string, `Element`, `NodeList`, or `Element[]`. Returns a `Context` or `Context[]`. |
 | `AutumnNote.destroy(selector)` | Destroys editor(s) and restores the original element. |
 | `AutumnNote.getInstance(selector)` | Returns the `Context` for a given element, or `null`. |
-| `AutumnNote.defaults` | Global default options — mutate before calling `create()` to set project-wide defaults. |
+| `AutumnNote.defaults` | Global default options object — mutate before calling `create()` to apply project-wide settings. |
 
-### Context (editor instance)
+### Context (instance methods)
 
 | Method | Description |
 |---|---|
-| `editor.getHTML()` | Returns the current HTML content (sanitised). |
-| `editor.setHTML(html)` | Sets HTML content (sanitised). |
-| `editor.getText()` | Returns plain text (no markup). |
-| `editor.clear()` | Clears all content. |
-| `editor.setDisabled(bool)` | Enables or disables the editor. |
-| `editor.destroy()` | Removes the editor and restores the original element. |
+| `editor.getHTML()` | Returns the current HTML. Zero-width spaces from the icon picker are stripped automatically. |
+| `editor.setHTML(html)` | Sets HTML content (sanitised). `<iframe>` elements are preserved. |
+| `editor.getText()` | Returns plain text with no markup. |
+| `editor.clear()` | Clears all content, resets to an empty `<p>`. |
+| `editor.setDisabled(bool)` | Disables (`true`) or re-enables (`false`) the editor and toolbar. |
+| `editor.destroy()` | Removes the editor, disposes all modules, and restores the original element. |
 | `editor.on(event, fn)` | Subscribes to an editor event. Returns an unsubscribe function. |
-| `editor.invoke('module.method', ...args)` | Calls any registered module method by name. |
+| `editor.off(event, fn)` | Removes a previously registered listener. |
+| `editor.invoke('module.method', ...args)` | Calls any registered module method by dot-separated name. |
 
 ### Events
 
 | Name | Payload | Description |
 |---|---|---|
-| `change` | `html: string` | Fired after every content mutation. |
-| `focus` | — | Editor gained focus. |
-| `blur` | — | Editor lost focus. |
+| `change` | `html: string` | Fired after every content mutation. Debounced internally. |
+| `focus` | `context` | Editor gained focus. |
+| `blur` | `context` | Editor lost focus. |
+| `init` | `context` | Fired once after the editor has fully initialised. |
+| `imageUpload` | `files: FileList` | Fired when images are dropped or pasted (when `onImageUpload` is provided). |
+| `imageError` | `{ file, message }` | Fired when an image is rejected (e.g. over `maxImageSize`). |
+| `paste` | `{ text, html }` | Fired after every paste event. |
+| `selectionChange` | `context` | Fired when the cursor or selection changes. |
+| `destroy` | `context` | Fired just before the editor is destroyed. |
+| `charLimitReached` | `context` | Fired when `maxChars` is hit. |
+| `wordLimitReached` | `context` | Fired when `maxWords` is hit. |
 
 ---
 
@@ -707,59 +316,125 @@ const editor = AutumnNote.create('#my-editor', {
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `placeholder` | `string` | `''` | Placeholder text shown when the editor is empty. |
-| `height` | `number` | `200` | Initial / minimum editor height in px. |
-| `minHeight` | `number` | `100` | Hard minimum height in px. |
-| `maxHeight` | `number` | `0` | Maximum height in px. `0` = unlimited. |
-| `focus` | `boolean` | `false` | Auto-focus the editor on initialisation. |
-| `resizeable` | `boolean` | `true` | Show the drag-to-resize handle in the statusbar. |
-| `toolbar` | `Array` | default | Array of button group arrays. See [Toolbar customisation](#toolbar-customisation). |
-| `useBootstrap` | `boolean` | `false` | Apply Bootstrap classes to toolbar buttons. |
+| `height` | `number` | `200` | Initial editor height in pixels. |
+| `minHeight` | `number` | `100` | Minimum resizable height in pixels. |
+| `maxHeight` | `number` | `0` | Maximum resizable height in pixels. `0` = unlimited. |
+| `focus` | `boolean` | `false` | Automatically focus the editor on creation. |
+| `resizable` | `boolean` | `true` | Show the resize handle at the bottom of the editor. |
+| `toolbar` | `Array[]` | all buttons | Toolbar layout. See [Toolbar Customisation](#toolbar-customisation). |
+| `toolbarOverflow` | `string` | `'wrap'` | Toolbar overflow strategy: `'wrap'` or `'scroll'`. |
+| `useBootstrap` | `boolean` | `false` | Apply Bootstrap CSS classes to toolbar buttons. |
 | `bootstrapVersion` | `number` | `5` | Bootstrap major version (`4` or `5`). |
 | `toolbarButtonClass` | `string` | `'btn btn-sm btn-light'` | CSS classes for toolbar buttons when `useBootstrap` is `true`. |
 | `useFontAwesome` | `boolean` | `true` | Use FA icons when FontAwesome is detected on the page. |
-| `fontAwesomeClass` | `string` | `'fas'` | FA prefix — `'fas'` for FA 5, `'fa-solid'` for FA 6. |
-| `pasteAsPlainText` | `boolean` | `false` | Strip all formatting on paste. |
+| `fontAwesomeClass` | `string` | `'fas'` | FA prefix: `'fas'` for FA 5, `'fa-solid'` for FA 6. |
+| `pasteAsPlainText` | `boolean` | `false` | Strip all formatting when pasting. |
 | `pasteCleanHTML` | `boolean` | `true` | Sanitise HTML on paste. |
-| `allowImageUpload` | `boolean` | `true` | Allow file upload in the image dialog. |
-| `maxImageSize` | `number` | `5` | Maximum image upload size in MB. |
-| `onImageUpload` | `Function` | `null` | Custom upload handler `(files: FileList) => void`. Overrides base64 embed. |
-| `tabSize` | `number` | `0` | Spaces inserted per Tab key press. `0` = browser default. |
-| `defaultFontFamily` | `string` | `'Arial'` | Font applied to the editable area. |
-| `fontFamilies` | `string[]` | (10 fonts) | Font families listed in the font-family dropdown. |
-| `onChange` | `Function` | `null` | `(html: string) => void` — called on every change. |
-| `onFocus` | `Function` | `null` | `(context: Context) => void` |
-| `onBlur` | `Function` | `null` | `(context: Context) => void` |
-| `stickyToolbar` | `boolean` | `false` | Stick the toolbar to the viewport top when the page is scrolled. |
-| `stickyToolbarOffset` | `number` | `0` | Top offset in px for the sticky toolbar (e.g. height of a fixed navigation bar). |
+| `pasteStripAttributes` | `boolean` | `false` | Strip `class`, `style`, and `data-*` attributes from pasted HTML. |
+| `markdownPaste` | `boolean` | `true` | Convert pasted Markdown shortcuts to HTML as you type. |
+| `allowImageUpload` | `boolean` | `true` | Allow drag/paste/file upload in the image dialog. |
+| `maxImageSize` | `number` | `5` | Maximum image file size in megabytes. |
+| `tabSize` | `number` | `4` | Number of spaces inserted when Tab is pressed. |
+| `historyLimit` | `number` | `100` | Maximum undo steps to retain. |
+| `defaultFontFamily` | `string` | `'Arial'` | Font shown by default in the font-family dropdown. |
+| `defaultFontSize` | `string` | `'14px'` | Default font size applied to new content. |
+| `fontFamilies` | `string[]` | 10 fonts | Font families available in the font-family dropdown. |
+| `stickyToolbar` | `boolean` | `false` | Pin the toolbar to the viewport top when the page is scrolled. |
+| `stickyToolbarOffset` | `number` | `0` | Top offset in pixels for the sticky toolbar (e.g. height of a fixed nav bar). |
 | `theme` | `string` | `'light'` | Colour theme: `'light'` or `'dark'`. |
-| `codeHighlight` | `boolean` | `false` | Auto-load Prism.js for syntax highlighting inside `<pre><code>` blocks. |
-| `codeHighlightCDN` | `string` | cdnjs Prism 1.29.0 | Base CDN URL used when auto-loading Prism assets. |
-| `markdownPaste` | `boolean` | `true` | Convert pasted Markdown text to HTML when no HTML is present in the clipboard. |
+| `readOnly` | `boolean` | `false` | Start the editor in non-editable (read-only) mode with toolbar hidden. |
+| `spellcheck` | `boolean` | `true` | Enable browser spellcheck in the editable area. |
+| `direction` | `string` | `'ltr'` | Text direction: `'ltr'` or `'rtl'`. |
+| `autoSave` | `boolean` | `false` | Persist content to `localStorage` on every change. |
+| `autoSaveKey` | `string` | `'autumnnote-autosave'` | `localStorage` key used when `autoSave` is enabled. |
+| `maxChars` | `number` | `0` | Maximum character count. `0` = unlimited. Shows warning in statusbar. |
+| `maxWords` | `number` | `0` | Maximum word count. `0` = unlimited. Shows warning in statusbar. |
+| `tableHeaderRow` | `boolean` | `false` | Insert a `<thead>` header row when creating new tables. |
+| `codeHighlight` | `boolean` | `true` | Auto-load Prism.js for syntax highlighting inside `<pre><code>` blocks. |
+| `codeHighlightCDN` | `string` | cdnjs Prism 1.29.0 | Base CDN URL for Prism assets. |
+| `colorSwatches` | `string[]` | `[]` | Custom brand colour swatches prepended to the colour picker palette. |
+| `focusColor` | `string` | `null` | Custom focus ring colour (any valid CSS colour). Overrides the default blue. |
+| `lang` | `string \| object` | `'en'` | UI display language. Built-in codes: `'en'`, `'vi'`, `'ja'`, `'zh'`, `'fr'`, `'de'`, `'es'`, `'ko'`. Pass a partial locale object for custom overrides. |
+| `markdownShortcuts` | `boolean` | `true` | Convert Markdown-style syntax typed in the editor to HTML in real time (block and inline rules). |
+| `bubbleToolbar` | `boolean` | `false` | Show a mini floating toolbar above the text selection for quick formatting. |
+| `bubbleToolbarItems` | `string[]` | `['bold','italic','underline','link','foreColor','removeFormat']` | Buttons shown in the bubble toolbar. Available names: `'bold'`, `'italic'`, `'underline'`, `'strikethrough'`, `'link'`, `'foreColor'`, `'removeFormat'`, `'inlineCode'`. |
+| `autoSaveRestore` | `boolean` | `false` | When `autoSave` is also `true`, show a restore banner on load if a draft exists. |
+| `autoSaveRestoreTimeout` | `number` | `7` | Max draft age in days before it is auto-discarded. `0` = no expiry. |
+| `onAutoSaveRestore` | `Function` | `null` | `(html, context) => void` — called after the user restores a draft. |
+| `mention` | `object` | `null` | @mention configuration object. Set `mention.onSearch` to activate. See [Mentions](#mentions). |
+| `onChange` | `Function` | `null` | `(html: string) => void` — called on every content change. |
+| `onFocus` | `Function` | `null` | `(context) => void` — called when the editor gains focus. |
+| `onBlur` | `Function` | `null` | `(context) => void` — called when the editor loses focus. |
+| `onInit` | `Function` | `null` | `(context) => void` — called once after the editor is initialised. |
+| `onImageUpload` | `Function` | `null` | `(files: FileList) => void` — custom upload handler. Overrides base64 embed. |
+| `onImageError` | `Function` | `null` | `({ file, message }) => void` — called when an image is rejected. |
+| `onPaste` | `Function` | `null` | `({ text, html }) => void` — called after every paste event. |
+| `onSelectionChange` | `Function` | `null` | `(context) => void` — called when cursor or selection changes. |
+| `onDestroy` | `Function` | `null` | `(context) => void` — called just before the editor is destroyed. |
+| `onCharLimitReached` | `Function` | `null` | `(context) => void` — called when `maxChars` is hit. |
+| `onWordLimitReached` | `Function` | `null` | `(context) => void` — called when `maxWords` is hit. |
 
 ---
 
 ## Toolbar Customisation
 
-The `toolbar` option accepts an array of button groups. Each group is an array of button definition objects imported from `Buttons.js`:
+The `toolbar` option accepts an array of **groups**. Each group is an array of button definition objects exported from the package:
 
 ```js
-import AutumnNote from 'AutumnNote';
-import {
-  boldBtn, italicBtn, underlineBtn,
-  linkBtn, imageBtn, emojiBtn, iconBtn,
-  codeviewBtn, fullscreenBtn,
-} from 'AutumnNote/src/js/module/Buttons.js';
+import AutumnNote, {
+  boldBtn, italicBtn, underlineBtn, strikeBtn,
+  superscriptBtn, subscriptBtn,
+  alignLeftBtn, alignCenterBtn, alignRightBtn, alignJustifyBtn,
+  ulBtn, olBtn, checklistBtn, indentBtn, outdentBtn,
+  undoBtn, redoBtn,
+  hrBtn, linkBtn, imageBtn, videoBtn,
+  emojiBtn, iconBtn, tableBtn,
+  fontFamilyBtn, paragraphStyleBtn, lineHeightBtn,
+  foreColorBtn, backColorBtn,
+  findBtn, findReplaceBtn,
+  codeviewBtn, fullscreenBtn, shortcutsBtn,
+} from 'autumnnote';
+```
+
+### Default toolbar layout
+
+```js
+[
+  [paragraphStyleBtn, fontFamilyBtn, lineHeightBtn],
+  [undoBtn, redoBtn],
+  [boldBtn, italicBtn, underlineBtn, strikeBtn],
+  [superscriptBtn, subscriptBtn],
+  [foreColorBtn, backColorBtn],
+  [alignLeftBtn, alignCenterBtn, alignRightBtn, alignJustifyBtn],
+  [ulBtn, olBtn, checklistBtn, indentBtn, outdentBtn],
+  [hrBtn, linkBtn, imageBtn, videoBtn, tableBtn, emojiBtn, iconBtn],
+  [codeviewBtn, fullscreenBtn, shortcutsBtn],
+]
+```
+
+### Custom toolbar example
 
+```js
 AutumnNote.create('#editor', {
   toolbar: [
+    [undoBtn, redoBtn],
     [boldBtn, italicBtn, underlineBtn],
-    [linkBtn, imageBtn, emojiBtn, iconBtn],
-    [codeviewBtn, fullscreenBtn],
+    [ulBtn, olBtn, checklistBtn],
+    [linkBtn, imageBtn],
+    [findBtn, findReplaceBtn],
   ],
 });
 ```
 
-**Available buttons**
+### Hiding the toolbar
+
+Pass an empty array for a toolbar-less editor (keyboard shortcuts still work):
+
+```js
+AutumnNote.create('#editor', { toolbar: [] });
+```
+
+### All available buttons
 
 | Export | Tooltip |
 |---|---|
@@ -771,16 +446,84 @@ AutumnNote.create('#editor', {
 | `superscriptBtn` / `subscriptBtn` | Super / Subscript |
 | `foreColorBtn` / `backColorBtn` | Text colour / Highlight colour |
 | `alignLeftBtn` / `alignCenterBtn` / `alignRightBtn` / `alignJustifyBtn` | Alignment |
-| `ulBtn` / `olBtn` / `indentBtn` / `outdentBtn` | Lists & indentation |
+| `ulBtn` / `olBtn` / `checklistBtn` | Lists |
+| `indentBtn` / `outdentBtn` | Indentation |
 | `hrBtn` | Horizontal Rule |
-| `linkBtn` | Insert Link |
+| `linkBtn` | Insert / Edit Link |
 | `imageBtn` | Insert Image |
 | `videoBtn` | Insert Video |
 | `tableBtn` | Insert Table (grid picker) |
 | `emojiBtn` | Insert Emoji |
 | `iconBtn` | Insert FA Icon |
+| `findBtn` | Find (Ctrl+F) |
+| `findReplaceBtn` | Find & Replace (Ctrl+H) |
 | `codeviewBtn` | HTML Code View |
 | `fullscreenBtn` | Fullscreen |
+| `shortcutsBtn` | Keyboard Shortcuts dialog |
+
+### Setting global defaults
+
+```js
+Object.assign(AutumnNote.defaults, {
+  height: 400,
+  theme: 'dark',
+  fontFamilies: ['Inter', 'Roboto', 'Georgia', 'Courier New'],
+  colorSwatches: ['#e74c3c', '#f39c12', '#2ecc71', '#3498db'],
+});
+```
+
+---
+
+## Keyboard Shortcuts
+
+| Keys | Action |
+|---|---|
+| `Ctrl + Z` | Undo |
+| `Ctrl + Shift + Z` / `Ctrl + Y` | Redo |
+| `Ctrl + B` | Bold |
+| `Ctrl + I` | Italic |
+| `Ctrl + U` | Underline |
+| `Ctrl + F` | Open Find dialog |
+| `Ctrl + H` | Open Find & Replace dialog |
+| `Shift + Enter` | Insert line break |
+| `Tab` | Insert spaces / indent list item |
+| `Shift + Tab` | Outdent list item |
+| `Shift + ?` | Open Keyboard Shortcuts dialog |
+
+> The number of spaces inserted by `Tab` is controlled by the `tabSize` option.
+
+---
+
+## Mentions
+
+The `mention` option object activates `@mention` autocomplete. Only `onSearch` is required; all other fields are optional.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `onSearch` | `Function` | — | `(query, callback) => void` — called when the user types after the trigger character. Pass an array of `{ id, label, avatar? }` to the callback. |
+| `onInsert` | `Function` | `null` | `(item) => string \| null` — return custom HTML for the inserted mention chip. Return `null` to use the built-in chip. |
+| `trigger` | `string` | `'@'` | Character that opens the dropdown. |
+| `minChars` | `number` | `0` | Minimum characters after the trigger before `onSearch` is called. `0` = open immediately. |
+| `maxResults` | `number` | `8` | Maximum items shown in the dropdown. |
+| `debounce` | `number` | `200` | Debounce delay in milliseconds for `onSearch` calls. |
+| `mentionClass` | `string` | `'an-mention'` | CSS class applied to the inserted mention chip. |
+| `allowSpaces` | `boolean` | `false` | Allow spaces in the query string before the dropdown closes. |
+
+### Example
+
+```js
+AutumnNote.create('#editor', {
+  mention: {
+    trigger: '@',
+    minChars: 1,
+    onSearch(query, callback) {
+      fetch(`/api/users?q=${encodeURIComponent(query)}`)
+        .then(r => r.json())
+        .then(users => callback(users)); // [{ id, label, avatar? }]
+    },
+  },
+});
+```
 
 ---
 
@@ -790,89 +533,119 @@ AutumnNote.create('#editor', {
 src/
 ├── js/
 │   ├── core/
-│   │   ├── dom.js            DOM utilities
-│   │   ├── range.js          Selection / Range API helpers
-│   │   ├── func.js           General utility helpers
+│   │   ├── dom.js            DOM utilities (createElement, on, closest, ...)
+│   │   ├── range.js          Selection and Range API helpers
+│   │   ├── func.js           General helpers (mergeDeep, debounce, ...)
 │   │   ├── key.js            Keyboard key constants
 │   │   ├── lists.js          Array helpers
-│   │   ├── env.js            Browser / platform detection
-│   │   ├── markdown.js       Markdown → HTML converter
+│   │   ├── env.js            Browser/platform detection
+│   │   ├── markdown.js       Lightweight Markdown to HTML converter
 │   │   └── sanitise.js       DOM-based HTML and URL sanitiser
 │   ├── editing/
-│   │   ├── History.js        Undo / redo stack
+│   │   ├── History.js        Undo/redo stack (configurable depth)
 │   │   ├── Style.js          execCommand style wrappers
-│   │   ├── Table.js          Table creation and manipulation
-│   │   └── Typing.js         Tab / Enter key behaviour
+│   │   ├── Table.js          Table creation and cell manipulation
+│   │   └── Typing.js         Tab/Enter/ArrowKey behaviour and FA icon caret handling
 │   ├── module/
-│   │   ├── Editor.js         Core editing commands + getHTML / setHTML
-│   │   ├── Toolbar.js        Toolbar UI and button rendering
-│   │   ├── Buttons.js        Button and dropdown definitions
-│   │   ├── Statusbar.js      Status bar + drag-to-resize
-│   │   ├── Clipboard.js      Paste sanitisation
-│   │   ├── ContextMenu.js    Right-click context menu
-│   │   ├── Placeholder.js    Placeholder text
-│   │   ├── Codeview.js       HTML source view
+│   │   ├── Editor.js         Core editing commands, getHTML/setHTML, sanitiser
+│   │   ├── Toolbar.js        Toolbar UI, button rendering (SVG + FA), dropdowns, colour picker
+│   │   ├── Buttons.js        Button/dropdown/colorpicker definitions and defaultToolbar
+│   │   ├── Statusbar.js      Word and character count, drag-to-resize, limit warnings
+│   │   ├── Clipboard.js      Paste sanitisation (HTML clean, plain-text, Markdown modes)
+│   │   ├── ContextMenu.js    Right-click context menu with colour palette
+│   │   ├── Placeholder.js    CSS-based placeholder
+│   │   ├── Codeview.js       HTML source view toggle
 │   │   ├── Fullscreen.js     Fullscreen mode
-│   │   ├── LinkDialog.js     Link insert / edit dialog
-│   │   ├── LinkTooltip.js    Inline link tooltip
-│   │   ├── ImageDialog.js    Image insert dialog (URL + upload)
-│   │   ├── ImageTooltip.js   Inline image tooltip
-│   │   ├── ImageResizer.js   Drag-to-resize for images
-│   │   ├── VideoDialog.js    Video embed dialog
-│   │   ├── VideoTooltip.js   Inline video tooltip
-│   │   ├── VideoResizer.js   Drag-to-resize for video embeds
-│   │   ├── TableTooltip.js   Table context tooltip
-│   │   ├── CodeTooltip.js    Code block context tooltip
-│   │   ├── EmojiDialog.js    Unicode emoji picker
-│   │   ├── IconDialog.js     FontAwesome icon picker
-│   │   └── ShortcutsDialog.js Keyboard shortcuts dialog
-│   ├── Context.js            Editor instance hub
-│   ├── settings.js           Default options
+│   │   ├── FindReplace.js    Find and Replace dialog (Ctrl+F / Ctrl+H)
+│   │   ├── LinkDialog.js     Link insert/edit dialog
+│   │   ├── LinkTooltip.js    Floating toolbar for links (open/edit/unlink)
+│   │   ├── ImageDialog.js    Image insert dialog (URL + file upload with MIME filtering)
+│   │   ├── ImageTooltip.js   Floating toolbar for images (edit/crop/delete)
+│   │   ├── ImageResizer.js   rAF-based drag handle to resize images
+│   │   ├── ImageCropOverlay.js  Inline crop tool (corner/edge handles, canvas export)
+│   │   ├── VideoDialog.js    Video embed dialog (YouTube, Vimeo, direct file)
+│   │   ├── VideoTooltip.js   Floating toolbar for video embeds (edit/delete)
+│   │   ├── VideoResizer.js   rAF-based drag handle to resize video embeds
+│   │   ├── TableTooltip.js   Floating toolbar for tables (row/col/merge/unmerge/select mode)
+│   │   ├── CodeTooltip.js    Floating toolbar for code blocks (copy/delete)
+│   │   ├── EmojiDialog.js    Unicode emoji picker (~380 emoji, 7 categories)
+│   │   ├── IconDialog.js     FontAwesome icon picker (FA 6 Free Solid, 8 categories)
+│   │   ├── ShortcutsDialog.js  Keyboard shortcuts reference dialog (Shift+?)
+│   │   ├── BubbleToolbar.js  Mini floating toolbar above text selection
+│   │   ├── MarkdownShortcuts.js  Inline Markdown-to-HTML input rules
+│   │   ├── AutoSaveRestore.js   Draft restore banner for localStorage drafts
+│   │   └── Mention.js        @mention autocomplete with floating dropdown
+│   ├── Context.js            Editor instance hub: module registry and event bus
+│   ├── settings.js           Default options (AsnOptions)
 │   ├── renderer.js           DOM layout builder
-│   └── index.js              Public entry point
+│   └── index.js              Public entry point + AutumnNote factory
 └── styles/
-    ├── _variables.scss       SCSS design tokens
-    └── AutumnNote.scss  Main stylesheet
+    ├── _variables.scss       SCSS design tokens (colours, spacing, radii, transitions)
+    └── autumnnote.scss       Main stylesheet
 ```
 
----
-
-## Development
+### Development commands
 
 ```bash
-# Install dependencies
-npm install
-
-# Start dev server (Vite)
-npm run dev
+npm install          # install dependencies
+npm run dev          # start Vite dev server with HMR
+npm run build        # build ES + UMD + CSS to dist/
+npm test             # run Vitest test suite once
+npm run test:watch   # run tests in watch mode
+npm run lint         # ESLint
+npm run typecheck    # TypeScript type check (tsconfig.json)
+```
 
-# Build library
-npm run build
+Build output in `dist/`:
 
-# Run tests
-npm test
-```
+| File | Format | Use |
+|---|---|---|
+| `autumnnote.es.js` | ES Module | `import` in bundlers (tree-shakeable) |
+| `autumnnote.umd.js` | UMD | `<script>` tag / CommonJS |
+| `autumnnote.css` | CSS | Styles for both builds |
 
 ---
 
-## Comparison with Summernote
-
-| Feature | Summernote | AutumnNote |
-|---|---|---|
-| jQuery required | Yes | No |
-| Bootstrap required | Optional | No |
-| Build system | Grunt | Vite |
-| Module format | IIFE | ES module + UMD |
-| Written in | ES5 / ES6 mix | ES2022 |
-| HTML sanitisation | Basic | DOM-based (strips scripts, XSS vectors) |
-| Emoji picker | No | Yes (~380 Unicode emoji) |
-| FA icon picker | No | Yes (FA 6 Free Solid, searchable) |
-| Video embeds | No | Yes (YouTube, Vimeo, direct) |
-| Image / video resize | No | Yes (drag handles) |
-| Inline tooltips | No | Yes (link, image, video, table, code) |
+## Comparison
+
+The table below compares AutumnNote against editors commonly used in this category. Specific library names are omitted to avoid bias.
+
+| Feature | Editor A | Editor B | Editor C | **AutumnNote** |
+|---|---|---|---|---|
+| jQuery dependency | Required | Required | Optional | **None** |
+| Runtime dependencies | Several | Several | 1–2 | **Zero** |
+| JavaScript standard | ES5 / legacy | ES6 mix | ES6 | **ES2022** |
+| Module format | IIFE / AMD | IIFE | CommonJS + IIFE | **ES Module + UMD** |
+| Build tool | Grunt | Gulp | Rollup | **Vite** |
+| TypeScript definitions | External / partial | Partial | Yes | **Yes (bundled)** |
+| HTML sanitisation | Basic | Whitelist-only | Moderate | **DOM-based (XSS-safe)** |
+| Iframe support in setHTML | No | No | Restricted | **Yes (host-trusted)** |
+| Dark theme | No | No | Yes | **Yes (built-in)** |
+| RTL text direction | No | Partial | No | **Yes** |
+| Built-in i18n locales | No | No | Partial | **Yes (8 languages)** |
+| Custom locale object | No | No | No | **Yes** |
+| Checklist (todo list) | No | No | No | **Yes** |
+| Find and Replace | No | No | No | **Yes (Ctrl+F / Ctrl+H)** |
+| Emoji picker | No | No | No | **Yes (~380 emoji)** |
+| FA icon picker | No | No | No | **Yes (FA 6, searchable)** |
+| Video embeds | No | No | No | **Yes (YouTube, Vimeo, direct)** |
+| Image crop tool | No | No | No | **Yes (inline)** |
+| Image / video resize | No | No | No | **Yes (drag handles)** |
+| Inline tooltips | No | No | Partial | **Yes (link, image, video, table, code)** |
+| Table cell merge/unmerge | No | No | Yes | **Yes** |
+| Table cell selection mode | No | No | No | **Yes** |
+| Context menu | No | No | No | **Yes (with colour palette)** |
+| Sticky toolbar | No | No | No | **Yes** |
+| Auto-save to localStorage | No | No | No | **Yes** |
+| Character / word limits | No | No | No | **Yes** |
+| Custom focus ring colour | No | No | No | **Yes** |
+| Read-only mode | No | Partial | Yes | **Yes** |
+| Custom colour swatches | No | No | No | **Yes** |
+| Code view (HTML source) | No | Yes | Yes | **Yes (sanitised)** |
+| Syntax highlighting | No | No | Partial | **Yes (Prism.js via CDN)** |
 
 ---
 
 ## License
 
-MIT
+[MIT](LICENSE)