@zuilib/text-editor 0.11.1 → 0.12.0

package/README.md

@@ -7,15 +7,16 @@ document outline, and collapsible sections.
 
 **Features**
 
-- **Three modes**: rich WYSIWYG (`edit-md`), raw markdown (`edit-raw`),
+- **Three modes**: rich WYSIWYG (`edit-rich`), raw markdown (`edit-raw`),
   read-only render (`view`) — all driven by one controlled `value` string
 - **Markdown shortcuts** while typing: headings, lists, checklists,
-  blockquotes, links, fenced code (with syntax highlighting), tables
+  blockquotes, links, fenced code (highlighted by the package's own lexer,
+  16 grammars), tables
 - **Tables**: GFM pipe tables, edited in place (tab between cells, ranges,
   add / remove rows and columns from hover rails or the keyboard,
   inline formatting), styled like Claude artifacts
 - **Text measure and block width**: an opt-in readable text column
-  (`measure="48rem"`); each table and diagram picks *full* / *text* /
+  (`maxTextWidth="48rem"`); each table and diagram picks *full* / *text* /
   *content* width, Slab-style; row density per table
 - **Diagrams**: a drawing canvas embedded in the document. Eight box
   shapes (rectangle, ellipse, diamond, note, database, cloud, queue, actor)
@@ -26,7 +27,11 @@ document outline, and collapsible sections.
 - **Outline**: optional table-of-contents sidebar with click-to-scroll and
   current-section highlight
 - **Section folding**: collapse everything under a heading, view-layer only
-- **Toolbar**: inline formatting plus insert-table / insert-drawing
+- **Toolbar**: inline formatting and links, block types (headings, lists,
+  quote), insert-table / insert-drawing
+- **Extension platform**: register your own Lexical nodes, markdown
+  transformers and plugins through props; `./markdown` entry without the
+  drawing canvas; every chrome string translatable through `labels`
 - YAML **frontmatter** block support (`---` at the top)
 
 Everything round-trips through the markdown string: tables as GFM,
@@ -36,13 +41,26 @@ frontmatter as `---` blocks. Feature history: [CHANGELOG](./CHANGELOG.md).
 ## Installation
 
 ```bash
-pnpm add @zuilib/text-editor @zuilib/tokens \
+pnpm add @zuilib/text-editor @zuilib/tokens tailwindcss \
   lexical @lexical/react @lexical/markdown @lexical/rich-text \
   @lexical/code @lexical/list @lexical/link @lexical/table @lexical/utils
 ```
 
 All `lexical`/`@lexical/*` packages are peer dependencies at `^0.35.0`;
-`react`/`react-dom` at `^18 || ^19`.
+`react`/`react-dom` at `^18 || ^19`. Document typography (headings, lists,
+inline code) is Tailwind v4 utility classes, so the host needs `tailwindcss`
+and must scan this package from its CSS entry:
+
+```css
+@import "tailwindcss";
+@import "@zuilib/tokens/styles.css";
+@source "../node_modules/@zuilib/text-editor/dist";
+@import "@zuilib/text-editor/styles.css";
+```
+
+Without Tailwind, load `@zuilib/tokens/tokens.css` instead and style the
+document block classes yourself; the class list is on the
+[Theming](https://zuilib.com/docs/text-editor/theming#block-classes) page.
 
 ## Quick start
 
@@ -54,40 +72,58 @@ import { MarkdownEditor } from '@zuilib/text-editor'
 
 function Notes() {
   const [value, setValue] = useState('# Hello\n\n- [ ] Try checklists')
-  return <MarkdownEditor value={value} onChange={setValue} outline />
+  return <MarkdownEditor value={value} onValueChange={setValue} outline />
 }
 ```
 
-The component is controlled: pass `value` and persist what `onChange`
-emits. The emitted string is always plain markdown.
+The component is controlled: `value` is the document. `onValueChange` fires on
+every keystroke with the full markdown string; passing a different `value`
+back in (including `''`) replaces the document, and passing back the string
+just emitted is a no-op. Persisting on every call is usually too often, so
+debounce the write to your store; keep the React state update synchronous.
 
 ## Props (`MarkdownEditorProps`)
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `value` | `string` | `''` | Markdown source (controlled) |
-| `onChange` | `(value: string) => void` | — | Called on every edit |
-| `mode` | `'edit-md' \| 'edit-raw' \| 'view'` | `'edit-md'` | Editing surface |
-| `placeholder` | `string` | `'Start writing...'` | Empty-state hint |
+| `value` | `string` | — | Markdown source (controlled). Omit for an uncontrolled editor |
+| `defaultValue` | `string` | `''` | Initial markdown of an uncontrolled editor |
+| `onValueChange` | `(value: string) => void` | — | Called on every edit (see `debounceMs`) |
+| `debounceMs` | `number` | `0` | Milliseconds to wait after the last edit before `onValueChange` fires; the document itself is never delayed, and a pending call is flushed when the editor unmounts |
+| `mode` | `'edit-rich' \| 'edit-raw' \| 'view'` | `'edit-rich'` | Editing surface |
+| `placeholder` | `string` | `labels.placeholder` | Empty-state hint |
 | `readOnly` | `boolean` | `false` | Disables editing in Lexical modes |
 | `autoFocus` | `boolean` | `false` | Focus on mount |
 | `className` | `string` | — | Root wrapper class |
-| `toolbar` | `boolean \| (items) => ReactNode` | `true` | Formatting/insert toolbar (`edit-md`); function form customises it |
+| `toolbar` | `boolean \| (items) => ReactNode` | `true` | Formatting/insert toolbar (`edit-rich`); function form customises it |
 | `outline` | `boolean` | `false` | Table-of-contents sidebar |
-| `foldable` | `boolean` | `true` | Collapse sections under headings |
-| `measure` | `string` | — | Max width of the text column, a CSS length (`'48rem'` recommended). Sugar for `--zui-text-editor-measure` |
-| `defaultBlockWidth` | `{ table?, drawing? }` | — | `BlockWidth` written when the toolbar inserts a table / drawing |
+| `collapsible` | `boolean` | `true` | Collapse sections under headings |
+| `maxTextWidth` | `string` | — | Max width of the text column, a CSS length (`'48rem'` recommended). Sugar for `--zui-text-editor-measure` |
+| `newBlockWidth` | `{ table?, drawing? }` | — | `BlockWidth` written when the toolbar inserts a table / drawing |
+| `drawingStyle` | `'clean' \| 'ink'` | `'clean'` | Diagram rendering style; `ink` draws shapes as seeded pen strokes |
+| `onError` | `(error: Error) => void` | `console.error` | Called when Lexical throws inside an update |
+| `nodes` | `Klass<LexicalNode>[]` | — | Extra node classes, appended to the built-ins. Mount-time only |
+| `transformers` | `Transformer[] \| (defaults) => Transformer[]` | — | Extra markdown transformers ([Extending](#extending)). Mount-time only |
+| `nodeClassNames` | `EditorThemeClasses` | — | Class names for the rendered nodes, merged over the built-ins one level deep. Mount-time only |
+| `onEditorReady` | `(editor: LexicalEditor) => void` | — | Imperative access to the Lexical instance |
+| `labels` | `DeepPartial<EditorLabels>` | English | Every chrome string ([Localisation](#localisation)) |
+| `maxLength` | `number` | — | Plain-text limit; input past it is rejected at the caret. A controlled `value` is never trimmed |
+| `onCharacterCountChange` | `(length: number) => void` | — | Plain-text length after every change and once on mount |
+| `showCharacterCount` | `boolean` | `false` | Character counter under the document (`length / maxLength`) |
+| `id`, `name`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-invalid`, `aria-required` | | — | Forwarded to the editable surface ([Form integration](#form-integration)) |
+| `children` | `ReactNode` | — | Extra plugins or UI rendered under the root |
 
 ### Modes
 
 | `mode` | UI | Notes |
 |--------|-----|-------|
-| `'edit-md'` | Lexical rich editor | Shortcuts, toolbar, tables, canvas |
+| `'edit-rich'` | Lexical rich editor | Shortcuts, toolbar, tables, canvas |
 | `'edit-raw'` | Plain `<textarea>` | Direct markdown source editing |
 | `'view'` | Read-only render | Outline/folding still work |
 
-Switching `edit-raw` → `edit-md` re-mounts Lexical with the latest text
-(cursor-safe).
+Switching `edit-raw` → `edit-rich` re-imports the latest text into Lexical.
+In `edit-raw` the textarea keeps its own keystrokes whether or not `value`
+is given.
 
 ## Tables
 
@@ -169,7 +205,7 @@ frontmatter are capped at that width and centred in the pane, while each
 table and drawing chooses its own width.
 
 ```tsx
-<MarkdownEditor value={value} onChange={setValue} measure="48rem" />
+<MarkdownEditor value={value} onValueChange={setValue} maxTextWidth="48rem" />
 ```
 
 The prop is sugar for the CSS custom property `--zui-text-editor-measure`,
@@ -180,7 +216,7 @@ which is the actual contract — set it in a stylesheet on `.zui-text-editor`
 .zui-text-editor { --zui-text-editor-measure: 48rem; }
 ```
 
-**Adopting:** set `measure` (or the variable) and delete any external
+**Adopting:** set `maxTextWidth` (or the variable) and delete any external
 `max-width` / `margin-inline` overrides on `.zui-text-editor-content > *`;
 the library now owns that layout.
 
@@ -193,13 +229,13 @@ toolbar or the right end of the drawing toolbar:
 | `text` | The text column: edges align with the paragraphs. Identical to `full` until a measure is set | `<!-- width: text -->` / `"width":"text"` |
 | `content` | Shrinks to its columns / shapes, left-aligned with the text, never wider than the column | `<!-- width: content -->` / `"width":"content"` |
 
-Absence of a marker always means `full`, in every app. `defaultBlockWidth`
+Absence of a marker always means `full`, in every app. `newBlockWidth`
 only changes what the toolbar / `insertTable` / `insertDrawing` write into
 *new* blocks — and that value is written explicitly, even when it is
 `full`, so the document reads the same elsewhere:
 
 ```tsx
-<MarkdownEditor measure="48rem" defaultBlockWidth={{ table: 'text', drawing: 'text' }} … />
+<MarkdownEditor maxTextWidth="48rem" newBlockWidth={{ table: 'text', drawing: 'text' }} … />
 ```
 
 Headless: `useMarkdownEditor().blockWidth` / `setBlockWidth` act on the
@@ -222,9 +258,19 @@ keeps every table inside the column. Block classes: `.zui-paragraph`,
 
 ## Toolbar & custom toolbars
 
-In `edit-md` mode a toolbar offers inline formatting (bold, italic,
-strikethrough, inline code) plus **Insert table** and **Insert drawing**.
-Hide it with `toolbar={false}`.
+In `edit-rich` mode the toolbar has three groups: **format** (bold, italic,
+strikethrough, inline code, link), **block** (heading 1 to 3, bullet,
+numbered and check list, quote; pressing the active one returns to a
+paragraph) and **insert** (table, drawing). Hide it with `toolbar={false}`.
+
+The link button needs a non-empty selection (it is disabled for a bare
+caret) and opens a small bubble under it with a URL input, apply and
+remove; nothing is written to the document until a URL is applied, so
+Escape, moving the caret or leaving the bubble abandons the link without
+an `onValueChange`. The bubble also opens when the caret enters an existing
+link. URLs are validated: `javascript:`, `data:` and other script-capable
+schemes are refused (`isSafeUrl`, `SAFE_LINK_PROTOCOLS`), both here and
+for pasted links (an HTML paste keeps only the text of an unsafe `href`).
 
 ### Extending the toolbar
 
@@ -236,11 +282,13 @@ clicked.
 ```tsx
 <MarkdownEditor
   value={value}
-  onChange={setValue}
+  onValueChange={setValue}
   toolbar={(items) => (
     <MarkdownEditor.Toolbar>
       {items.format}
       <MarkdownEditor.ToolbarDivider />
+      {items.block}
+      <MarkdownEditor.ToolbarDivider />
       {items.insert}
       <MarkdownEditor.ToolbarDivider />
       {items.history}
@@ -253,6 +301,10 @@ clicked.
 ```
 
 `MarkdownEditor.Toolbar` hides itself in `view` / `edit-raw` / `readOnly`.
+`items` has `format`, `block`, `insert` and `history` (undo / redo, only
+in this function form). Buttons made with `ToolbarButton` take part in the
+toolbar's arrow-key navigation (`data-toolbar-item`); other elements you
+put in the toolbar keep their own focus handling.
 
 ### Placing your own toolbar (compound components)
 
@@ -262,7 +314,7 @@ panel header), compose the editor from its parts. Everything under
 anywhere in that subtree.
 
 ```tsx
-<MarkdownEditor.Root value={value} onChange={setValue}>
+<MarkdownEditor.Root value={value} onValueChange={setValue}>
   <header className="app-bar">
     <MarkdownEditor.Toolbar>
       <MarkdownEditor.FormatButtons />
@@ -279,12 +331,13 @@ anywhere in that subtree.
 
 | Part | Role |
 |------|------|
-| `Root` | Lexical composer + plugins. Takes `value`, `onChange`, `mode`, `readOnly`, `autoFocus`, `className` |
-| `Content` | The editable surface. Takes `placeholder`, `foldable`; children are docked sidebars |
+| `Root` | Lexical composer + plugins. Takes every prop of `MarkdownEditor` except `placeholder`, `toolbar`, `outline`, `collapsible`, `showCharacterCount` |
+| `Content` | The editable surface. Takes `placeholder`, `collapsible`, `showCharacterCount`; children are docked sidebars |
 | `Toolbar` | Container; renders the default groups when empty |
-| `FormatButtons`, `InsertButtons`, `HistoryButtons` | Built-in groups |
+| `FormatButtons`, `BlockButtons`, `InsertButtons`, `HistoryButtons` | Built-in groups (`InsertButtons drawing={false}` hides the drawing button) |
 | `ToolbarButton`, `ToolbarDivider` | Primitives for your own items |
 | `Outline` | Table-of-contents sidebar |
+| `CharacterCount` | Character counter, for placing it yourself |
 
 ### Headless: `useMarkdownEditor()`
 
@@ -303,7 +356,10 @@ function BoldButton() {
 ```
 
 It returns `editor` (the Lexical instance), `activeFormats`,
-`toggleFormat`, `insertTable`, `insertDrawing`, `blockWidth` /
+`toggleFormat`, `blockType` / `setBlockType` (`paragraph`, `h1`..`h6`,
+`quote`, `bullet`, `number`, `check`), `link` / `setLink(url | null)` /
+`hasSelection` (`setLink` with a URL is a no-op for a collapsed caret
+outside a link), `insertTable`, `insertDrawing`, `blockWidth` /
 `setBlockWidth` (width of the table or drawing containing the selection,
 `null` outside both), `tableDensity` / `setTableDensity` (`null` outside
 tables), `tableCell` / `insertTableRow` / `deleteTableRow` / `insertTableColumn` /
@@ -313,7 +369,7 @@ tables), `tableCell` / `insertTableRow` / `deleteTableRow` / `insertTableColumn`
 ## Diagrams (drawing canvas)
 
 The toolbar's insert-drawing button embeds a canvas; the drawing persists
-in the markdown as a ` ```drawing ` fenced JSON block (format version 2),
+in the markdown as a ` ```drawing ` fenced JSON block (format version 3),
 fully specified in **[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)**.
 
 - **Shapes**: rectangle, ellipse, diamond, note (sticky note), database
@@ -355,10 +411,10 @@ A stored drawing looks like this:
 
 ````md
 ```drawing
-{"version":2,"canvasHeight":260,"shapes":[
-  {"id":"web","type":"rect","x":40,"y":70,"w":170,"h":100,"stroke":"#1971c2","fill":"#a5d8ff","strokeWidth":2,"label":"CLIENT","text":"Web App"},
-  {"id":"api","type":"rect","x":330,"y":70,"w":170,"h":100,"stroke":"#2f9e44","fill":"#b2f2bb","strokeWidth":2,"label":"SERVICE","text":"API"},
-  {"id":"e1","type":"arrow","x":216,"y":120,"w":108,"h":0,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"startBinding":{"id":"web"},"endBinding":{"id":"api"},"text":"REST"}
+{"version":3,"canvasHeight":260,"shapes":[
+  {"id":"web","type":"rect","x":40,"y":70,"width":170,"height":100,"stroke":"#1971c2","fill":"#a5d8ff","strokeWidth":2,"label":"CLIENT","text":"Web App"},
+  {"id":"api","type":"rect","x":330,"y":70,"width":170,"height":100,"stroke":"#2f9e44","fill":"#b2f2bb","strokeWidth":2,"label":"SERVICE","text":"API"},
+  {"id":"e1","type":"arrow","x":216,"y":120,"width":108,"height":0,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"startBinding":{"id":"web"},"endBinding":{"id":"api"},"text":"REST"}
 ]}
 ```
 ````
@@ -386,7 +442,7 @@ expansion).
 
 The full skeleton spec (attach sides, explicit positions, free texts) is
 in [DRAWING_FORMAT.md](./DRAWING_FORMAT.md). Programmatic access:
-`parseDrawingSkeleton`, `expandSkeleton`, `DRAWING_SKELETON_JSON_SCHEMA`.
+`parseDrawingSkeleton`, `expandDrawingSkeleton`, `DRAWING_SKELETON_JSON_SCHEMA`.
 
 ### Theming the canvas
 
@@ -427,13 +483,279 @@ host theme in light and dark mode. Override any of them on
 
 `outline` docks a collapsible table-of-contents sidebar: live heading list
 indented by level, click to scroll, current section highlighted. Not part
-of the document — pure UI. Available in `edit-md` and `view`.
+of the document — pure UI. Available in `edit-rich` and `view`.
 
-`foldable` (default on) shows a chevron in the gutter of each heading on
+`collapsible` (default on) shows a chevron in the gutter of each heading on
 hover; clicking collapses the section (until the next heading of the same
 or higher level). Folding never changes the markdown; fold state resets on
 remount; a folded section auto-expands if the cursor enters it.
 
+## Extending
+
+The editor is a Lexical composer with a fixed set of nodes and markdown
+transformers. Three props open it up; a first-party plugin (mentions,
+comments, images) is built the same way a host would build one.
+
+```tsx
+import { MarkdownEditor, useMarkdownEditor, DRAWING_PRESET_TRANSFORMERS } from '@zuilib/text-editor'
+import { MentionNode, MENTION } from './mention'
+
+function MentionPlugin() {
+  const { editor } = useMarkdownEditor()
+  useEffect(() => editor.registerCommand(INSERT_MENTION_COMMAND, ...), [editor])
+  return null
+}
+
+<MarkdownEditor
+  value={value}
+  onValueChange={setValue}
+  nodes={[MentionNode]}
+  transformers={[MENTION]}
+  nodeClassNames={{ mention: 'zui-mention' }}
+  onEditorReady={(editor) => (editorRef.current = editor)}
+>
+  <MentionPlugin />
+</MarkdownEditor>
+```
+
+| Prop | What it does |
+|------|--------------|
+| `nodes` | Appended to the built-in node list (`DRAWING_PRESET_NODES`; `MARKDOWN_NODES` on `./markdown`). Lexical registers node classes when the composer is created, so the prop is read on mount only; change the `key` to remount with a different set |
+| `transformers` | An array goes **before** the built-ins, so it claims its syntax first on import and export; a function receives the built-in list and returns the whole list (`(defaults) => [MENTION, ...defaults.filter(t => t !== CODE_BLOCK)]`). Mount-time only. Everything that is not a `multiline-element` transformer (and not `CHECK_LIST`) is also offered as a typing shortcut |
+| `children` (plugins) | Anything under `MarkdownEditor` / `MarkdownEditor.Root` shares the editor: a component calling `useMarkdownEditor()` or `useLexicalComposerContext()` is a plugin |
+| `nodeClassNames` | Class names merged over `editorNodeClassNames` one level deep (`{ heading: { h1: 'x' } }` keeps `h2`); mount-time only |
+| `onEditorReady` | Called with the `LexicalEditor` once it exists |
+
+The built-in transformer order is exported as `DRAWING_PRESET_TRANSFORMERS` (default
+entry) and `MARKDOWN_TRANSFORMERS` (`./markdown`): `FRONTMATTER`, `DRAWING`,
+`DIAGRAM`, `LISTS`, `CHECK_LIST`, `TABLE`, `CODE_BLOCK`, then Lexical's
+`TRANSFORMERS` without `CODE`. Use the same list in a headless editor so
+import and export match the component byte for byte.
+
+### Entry points
+
+| Import | Contents |
+|--------|----------|
+| `@zuilib/text-editor` | Everything: the editor with the drawing canvas, all nodes, transformers and helpers |
+| `@zuilib/text-editor/markdown` | The editor without drawings: no `DrawingNode`, no ` ```drawing ` / ` ```diagram ` transformers, no insert-drawing button, no canvas code in the bundle. `MarkdownEditor`, `useMarkdownEditor`, the toolbar parts, tables, code highlighting, labels |
+| `@zuilib/text-editor/lexical` | The Lexical-facing escape hatch for plugin authors: presets (`MARKDOWN_PRESET`, `DRAWING_PRESET`), node classes, transformers, `$`-prefixed helpers, `createMarkdownEditor`, the tokenizer plumbing |
+| `@zuilib/text-editor/drawing` | The drawing canvas on its own: `DrawingNode`, `DRAWING`, `DIAGRAM`, `DrawingPlugin`, `DRAWING_PRESET`, the payload and skeleton helpers |
+| `@zuilib/text-editor/mentions`, `./comments`, `./images`, `./paste` | The first-party plugins ([Plugins](#plugins)); plugin components also on the default entry, node classes and `$`-helpers on the plugin entry and `./lexical` |
+
+`./markdown` plus `./drawing` reassembles the default entry:
+
+```tsx
+import { MarkdownEditor } from '@zuilib/text-editor/markdown'
+import { DrawingNode, DRAWING, DIAGRAM, DrawingPlugin } from '@zuilib/text-editor/drawing'
+
+<MarkdownEditor.Root value={value} onValueChange={setValue} nodes={[DrawingNode]} transformers={[DRAWING, DIAGRAM]}>
+  <MarkdownEditor.Content />
+  <DrawingPlugin />
+</MarkdownEditor.Root>
+```
+
+`createMarkdownEditor(preset)` (on `./lexical`) builds a `MarkdownEditor`
+(with its compound parts) around an `EditorPreset`
+(`{ nodes, transformers, plugins? }`) for packages that ship their own
+bundle of extensions.
+
+### Localisation
+
+`labels` takes a deep partial of `EditorLabels` (exported, English
+defaults in `DEFAULT_LABELS`): `placeholder`, `toolbar.*`, `outline.*`,
+`collapsibleHeadings.*`, `table.*`, `layout.*`, `drawing.*`, `count` and
+`limitExceeded` / `limitRestored` (the counter's limit announcements).
+Strings with a number are functions (`table.deleteRow(3)`,
+`drawing.deleteShapes(2)`).
+Document content is never translated.
+
+```tsx
+<MarkdownEditor
+  labels={{
+    placeholder: 'Commencez à écrire…',
+    toolbar: { bold: 'Gras', insertTable: 'Insérer un tableau' },
+    drawing: { deleteShapes: (n) => `Supprimer ${n} formes` },
+  }}
+/>
+```
+
+`useLabels()` returns the resolved labels inside the editor, for your own
+plugins.
+
+## Plugins
+
+Four first-party plugins ship in the package. Each is opt-in: import it
+from its own entry point (or from the default entry), pass its node and
+transformer to the root and mount the plugin as a child. `./markdown` does not
+include them. The one stylesheet covers all four. See the [plugins
+page](https://zuilib.com/docs/text-editor/plugins) for live examples.
+
+| Entry | Node / transformer | Plugin | Markdown |
+|-------|--------------------|--------|----------|
+| `@zuilib/text-editor/mentions` | `MentionNode`, `MENTION` | `MentionsPlugin` | `[@name](mention:id)` |
+| `@zuilib/text-editor/comments` | `MarkNode` (from `@lexical/mark`), `COMMENT` | `CommentsPlugin` | `<!-- zui:comment id -->text<!-- /zui:comment -->` |
+| `@zuilib/text-editor/images` | `ImageNode`, `IMAGE` | `ImagesPlugin`, `ImageButton` | `![alt](src)`, `![alt](src "title")` |
+| `@zuilib/text-editor/paste` | none | `PastePlugin` | unchanged |
+
+### Mentions
+
+```tsx
+import { MentionNode, MENTION, MentionsPlugin } from '@zuilib/text-editor/mentions'
+
+<MarkdownEditor value={value} onValueChange={setValue} nodes={[MentionNode]} transformers={[MENTION]}>
+  <MentionsPlugin search={(query) => api.people(query)} />
+</MarkdownEditor>
+```
+
+Typing the trigger at the start of a word opens a `role="listbox"` under
+the caret with the `search(query)` results (called on every keystroke;
+stale results are dropped). Arrow keys move, Enter or Tab inserts the
+highlighted item as a `MentionNode` followed by a space, Escape closes
+until the query changes. While the list is open the surface carries
+`aria-controls` and `aria-activedescendant`. Enter with no results is a
+normal Enter. The list never opens in `readOnly` mode, in inline code or
+inside another mention; the query stops at whitespace and 40 characters.
+
+| Prop | Description |
+|------|-------------|
+| `trigger` | One non-word character (default `'@'`) |
+| `search` | `(query) => Promise<MentionItem[]>`; an item is `{ id, name, hint? }` |
+| `render` | `(item, { active, query, trigger }) => ReactNode` for the option body; the option element, its role and selection state stay the plugin's |
+| `triggers` | `[{ trigger, search, render? }]` for several triggers (`@` people, `#` tags); replaces the three props above |
+| `maxItems` | Options listed at most (default 8) |
+| `labels` | `suggestions(trigger)` (listbox `aria-label`), `noResults`, `loading` |
+| `onSelect` | `(item, trigger)` after an insertion |
+
+The node is a token text node: the caret cannot enter it, Backspace
+removes it whole, its text is the trigger plus the name. Markdown writes
+`[@name](mention:id)`, a link other renderers show as text with a
+`mention:` href; a trigger must be a single non-word character for the
+transformer to claim it. `]` and `\` in the name are backslash-escaped
+and `%`, `)` and whitespace in the id percent-encoded, so any host values
+round-trip. `INSERT_MENTION_COMMAND` (`{ id, name, trigger? }`)
+inserts a mention at the selection without the menu. The theme key is
+`mention` (`zui-mention` by default), the element carries
+`data-mention="<id>"` and `data-slot="mention"`.
+
+### Comments
+
+```tsx
+import { MarkNode, COMMENT, CommentsPlugin } from '@zuilib/text-editor/comments'
+
+<MarkdownEditor value={value} onValueChange={setValue} nodes={[MarkNode]} transformers={[COMMENT]}>
+  <CommentsPlugin
+    comments={comments}
+    onAdd={(c) => setComments([...comments, c])}
+    onResolve={(id, resolved) => update(id, { resolved })}
+    onDelete={(id) => remove(id)}
+  />
+</MarkdownEditor>
+```
+
+The document owns the ranges, the host owns everything else. Selecting
+text shows a floating "Add comment" button above it; the button or
+`Mod+Shift+M` wraps the selection in a `MarkNode` with a fresh id and
+calls `onAdd({ id, quote, range, resolved: false })`, then puts the caret
+at the end of the range. With the caret inside a commented range (or right
+after it) a `role="group"` bubble under it lists the comments there with
+resolve / reopen and delete; `Mod+Shift+M` there moves focus into the
+bubble and Escape returns it to the surface. Delete removes the id from
+the document before `onDelete(id)`; resolve only calls
+`onResolve(id, resolved)`, the host decides.
+
+| Prop | Description |
+|------|-------------|
+| `comments` | `{ id, quote, range?, resolved? }[]`; a marker whose id is missing here is listed with `labels.unknown(id)` and only offers delete |
+| `onAdd`, `onResolve`, `onDelete` | See above |
+| `createId` | Id generator (default `crypto.randomUUID`) |
+| `labels` | `add`, `comments` (bubble `aria-label`), `resolve`, `reopen`, `remove`, `resolved`, `unknown(id)` |
+| `renderComment` | `(comment, { resolve, remove }) => ReactNode` replaces an entry's body |
+
+`range` is `{ start, end }` in `$getRoot().getTextContent()` at the time
+the comment was added; it is informational and not updated by later
+edits, the mark is the source of truth. Markdown writes
+`<!-- zui:comment id -->text<!-- /zui:comment -->`, which every other
+renderer hides, so the plain document stays readable. A range spanning
+several blocks is one marker pair per block with the same id;
+overlapping comments share a pair with the ids comma-separated
+(`zui:comment a,b`). Mark elements get `zui-comment`, `data-comment-ids`
+and `is-resolved` when every id on them is resolved; the colour reads
+`--zui-comment-color` (falls back to `--warning`). Helpers inside
+`editor.update` / `read`: `$getMarkNodes()`, `$getCommentIds()`,
+`$removeComment(id)`, `$plainTextOffset(node)`, plus
+`formatCommentMarker`, `parseCommentIds`, `ADD_COMMENT_COMMAND` and
+`COMMENTS_THEME`. Peer dependency: `@lexical/mark`.
+
+### Images
+
+```tsx
+import { ImageNode, IMAGE, ImagesPlugin, ImageButton } from '@zuilib/text-editor/images'
+
+<MarkdownEditor
+  value={value}
+  onValueChange={setValue}
+  nodes={[ImageNode]}
+  transformers={[IMAGE]}
+  toolbar={(items) => (
+    <MarkdownEditor.Toolbar>
+      {items.format}
+      {items.insert}
+      <ImageButton />
+    </MarkdownEditor.Toolbar>
+  )}
+>
+  <ImagesPlugin upload={(file) => api.upload(file)} maxSize={5 * 1024 * 1024} onError={toast} />
+</MarkdownEditor>
+```
+
+Files pasted or dropped on the surface (Lexical's `DRAG_DROP_PASTE`), or
+chosen through `ImageButton`, are checked against `accept` (default any
+`image/*`) and `maxSize` (bytes), then a progress placeholder
+(`role="progressbar"`) stands at the caret until `upload(file)` resolves
+with `{ src, alt? }`. The placeholder exports as nothing, so a value read
+mid-upload has no half image. A rejected promise removes the placeholder.
+`onError` receives `{ type: 'unsupported' | 'too-large' | 'upload' | 'unsafe-src', ... }`.
+Sources must pass `isSafeUrl` (`http:`, `https:`, relative paths; no
+`data:` or `blob:`), on import, on insertion and on upload results.
+Whitespace and parentheses in a source are percent-encoded on the node
+(markdown destinations end at them), and `]` in alt text and `"` in
+titles are backslash-escaped, so any uploaded file name round-trips.
+
+Clicking an image selects it (Backspace removes it) and shows an alt-text
+input under it; Enter or Escape commits and returns to the surface. The
+image is inline; a paragraph holding only an image renders it as a block.
+Markdown is `![alt](src)` or `![alt](src "title")`. Commands:
+`INSERT_IMAGE_COMMAND` (`{ src, alt?, title? }`) and
+`UPLOAD_IMAGES_COMMAND` (`File[]`). Labels: `altText`, `altPlaceholder`,
+`uploading`, `insertImage`. Theme key `image` (`zui-image`).
+
+### Paste normalisation
+
+```tsx
+import { PastePlugin } from '@zuilib/text-editor/paste'
+
+<MarkdownEditor value={value} onValueChange={setValue}>
+  <PastePlugin />
+</MarkdownEditor>
+```
+
+HTML from Word, Google Docs, Confluence and Outlook is cleaned before the
+built-in paste converts it: headings, paragraphs, lists (Word's
+`MsoListParagraph` runs become real `ul` / `ol`), tables, links, code,
+quotes, emphasis (`b`, `i` and styled spans become `strong`, `em`, `s`),
+images, `br` and `hr` stay; styles, classes, ids, spans, fonts, Office
+namespaces, conditional comments, scripts, styles, forms, iframes and SVG
+go. Plain-text pastes and pastes into an input are untouched.
+
+| Prop | Description |
+|------|-------------|
+| `when` | `'rich-sources'` (default) acts only on HTML with an Office / Docs / Confluence fingerprint (`isRichSourceHtml`); `'always'` cleans every HTML paste |
+| `tables`, `links`, `images` | `false` flattens cells to paragraphs, keeps link text only, drops images |
+| `transform` | `(html) => html` runs on the cleaned HTML before conversion |
+
+`normalizePastedHtml(html, options)` is the pure function behind it. Peer
+dependencies: `@lexical/html`, `@lexical/clipboard`.
+
 ## For AI agents / programmatic authoring
 
 Documents are plain markdown, so LLMs can generate them — including
@@ -448,8 +770,8 @@ diagrams:
 - `DRAWING_SKELETON_JSON_SCHEMA` and `DRAWING_DATA_JSON_SCHEMA` (exported)
   are the same contracts as JSON Schema: use them to validate generated
   payloads or as structured-output/tool schemas.
-- `parseDrawingSkeleton(json)` / `expandSkeleton(skeleton)` turn a skeleton
-  into `DrawingData`. `parseDrawingData(json)` is the editor's own lenient
+- `parseDrawingSkeleton(json)` / `expandDrawingSkeleton(skeleton)` turn a skeleton
+  into `DrawingData`. `deserializeDrawingData(json)` is the editor's own lenient
   parser (invalid shapes drop out; never throws); `serializeDrawingData` is
   its inverse. `drawingToMermaid(data)` exports a Mermaid `flowchart`.
 - A ready-made Claude Code skill lives in the monorepo at
@@ -458,36 +780,117 @@ diagrams:
 
 ## Exports
 
+The public surface is split by audience. The default entry and
+`./markdown` carry the host-facing API — no `$`-prefixed helper and no
+Lexical type. Plugin authors composing at the Lexical level import
+`@zuilib/text-editor/lexical`.
+
+### `@zuilib/text-editor` (and `./markdown`)
+
 | Export | Purpose |
 |--------|---------|
-| `MarkdownEditor`, `MarkdownEditorProps` | The component; compound parts as statics (`.Root`, `.Content`, `.Toolbar`, …) |
-| `useMarkdownEditor`, `MarkdownEditorApi` | Headless editor hook |
-| `Toolbar`, `ToolbarButton`, `ToolbarDivider`, `FormatButtons`, `InsertButtons`, `HistoryButtons` | Toolbar primitives |
-| `@zuilib/text-editor/styles.css` | Editor chrome + theme styles (required) |
-| `TABLE` | GFM table markdown transformer |
-| `BlockWidth`, `BLOCK_WIDTHS`, `isBlockWidth`, `BlockWidthDefaults` | Block width (`full` / `text` / `content`) type, values, guard, insertion defaults |
+| `MarkdownEditor`, `MarkdownEditorProps`, `ToolbarItems` | The component; compound parts as statics (`.Root`, `.Content`, `.Toolbar`, `.CharacterCount`, …); the groups (`format`, `block`, `insert`, `history`) handed to a `toolbar` render function |
+| `EditorRootProps`, `EditorContentProps`, `EditorMode`, `EditorFieldProps` | Types of the compound parts |
+| `useMarkdownEditor`, `MarkdownEditorApi`, `BlockType` | Headless editor hook |
+| `useEditorContext`, `useLabels` | Editor context (mode, labels, field attributes) for plugins |
+| `EditorLabels`, `EditorLabelsInput`, `DeepPartial`, `DEFAULT_LABELS`, `resolveLabels` | Localisation |
+| `CollapsibleHeadingsLabels`, `TableRowShortcutsLabels`, `TableColumnShortcutsLabels` | Label types of the individual plugins |
+| `Toolbar`, `ToolbarButton`, `ToolbarDivider`, `FormatButtons`, `BlockButtons`, `InsertButtons`, `HistoryButtons`, `CharacterCount` | Toolbar primitives and the counter |
+| `useToolbarKeyboard`, `TOOLBAR_ITEM_ATTRIBUTE` | APG toolbar keyboard pattern for your own toolbars |
+| `isSafeUrl`, `SAFE_LINK_PROTOCOLS` | Link validation used by the link plugin and bubble |
+| `EDIT_LINK_COMMAND` | Opens the link bubble for a non-empty selection (what the toolbar link button dispatches) |
+| `BlockWidth`, `BLOCK_WIDTHS`, `isBlockWidth`, `NewBlockWidths` | Block width (`full` / `text` / `content`) type, values, guard, insertion defaults |
 | `TableDensity`, `TableSettings`, `TableSettingsOptions`, `DEFAULT_TABLE_SETTINGS` | Table setting types |
-| `$getTableSettings`, `$setTableSettings`, `$isTableWidthExplicit`, `$getTableWidth`, `$setTableWidth`, `$getTableDensity`, `$setTableDensity`, `$getSelectedTable` | Table setting helpers (inside `editor.update`/`read`) |
-| `parseTableSettingsMarker`, `formatTableSettingsMarker` | Marker comment ⇄ `TableSettings` |
-| `DRAWING`, `DIAGRAM`, `DrawingNode`, `$createDrawingNode`, `$isDrawingNode` | Drawing node + markdown transformers (` ```drawing ` and ` ```diagram `) |
-| `FRONTMATTER`, `FrontmatterNode`, `$createFrontmatterNode`, `$isFrontmatterNode` | Frontmatter node + transformer |
-| `DrawingData`, `DrawingShape`, `DrawingShapeType` | Drawing payload types |
-| `parseDrawingData`, `serializeDrawingData` | Drawing payload (de)serialization |
+| `parseTableSettingsMarker`, `formatTableSettingsMarker` | Marker comment ⇄ `TableSettings` (`TABLE_WIDTH_MARKER` is deprecated) |
+| `TableCellPosition`, `insertableRowIndices`, `insertableColumnIndices`, `canDeleteRow`, `canDeleteColumn` | Pure table guards for custom toolbars |
+| `CodeGrammar`, `CodeRule`, `CodeToken`, `CodeTokenType` | Code highlighting types |
+| `registerCodeLanguage`, `hasCodeLanguage`, `resolveCodeLanguage`, `getCodeLanguages`, `tokenizeCode` | Code language registry and lexer |
+| `BUILTIN_CODE_LANGUAGES`, `CODE_TOKEN_TYPES`, `PLAIN_LANGUAGE` | Code highlighting constants |
+| `@zuilib/text-editor/styles.css` | Editor chrome + theme styles (required) |
+
+The default entry additionally re-exports the pure drawing-data API (below)
+and the plugin components (`MentionsPlugin`, `CommentsPlugin`,
+`ImagesPlugin`, `PastePlugin` with their commands, labels and types).
+
+### Drawing data (default entry and `./drawing`)
+
+| Export | Purpose |
+|--------|---------|
+| `DrawingData`, `DrawingShape`, `DrawingShapeType`, `NodeShapeType`, `ConnectorType`, `Binding`, `BindingSide`, `Point` | Drawing payload types |
+| `deserializeDrawingData`, `serializeDrawingData`, `normalizeDrawingData` | Drawing payload (de)serialization; version 2 payloads migrate on read |
 | `DRAWING_DATA_JSON_SCHEMA` | JSON Schema of the drawing payload |
-| `DrawingSkeleton`, `SkeletonBox`, `SkeletonConnector` | Skeleton types |
-| `parseDrawingSkeleton`, `expandSkeleton`, `DRAWING_SKELETON_JSON_SCHEMA` | Skeleton parsing, expansion to `DrawingData`, JSON Schema |
-| `drawingToMermaid` | Mermaid `flowchart` export |
+| `NODE_SHAPE_TYPES`, `CONNECTOR_TYPES`, `SHAPE_TYPES`, `SIDE_FIXED_POINTS`, `STROKE_COLORS`, `FILL_COLORS`, `EMPTY_DRAWING` | Drawing constants |
+| `isNodeShapeType`, `findNodeShapeAt`, `createBinding` | Node-shape guard, hit test, binding creation |
+| `NODE_SHAPE_DEFINITIONS`, `NodeShapeDefinition`, `TextField` | Data-driven shape geometry and text slots |
+| `DrawingSkeleton`, `SkeletonBox`, `SkeletonConnector`, `SkeletonEnd`, `SkeletonText`, `ColorName` | Skeleton types |
+| `parseDrawingSkeleton`, `isDrawingSkeleton`, `expandDrawingSkeleton`, `DRAWING_SKELETON_JSON_SCHEMA`, `COLOR_PRESETS` | Skeleton parsing, expansion to `DrawingData`, JSON Schema, palette |
+| `drawingToMermaid`, `MermaidOptions`, `MermaidDirection` | Mermaid `flowchart` export |
+| `DrawingPlugin`, `INSERT_DRAWING_COMMAND`, `DRAWING_FOCUS_COMMAND` | Handles insertion (`useMarkdownEditor().insertDrawing` dispatches the command); the canvas reports focus through the second |
+| `DrawingStyle` | The `drawingStyle` prop's type |
+
+Geometry internals (binding resolution, the elbow router, ink rendering,
+outline math) are implementation details and are no longer exported.
+
+### `@zuilib/text-editor/lexical`
+
+| Export | Purpose |
+|--------|---------|
+| `createMarkdownEditor`, `EditorPreset`, `MARKDOWN_PRESET`, `DRAWING_PRESET` | Build the component around a preset of nodes / transformers / plugins |
+| `MARKDOWN_NODES`, `MARKDOWN_TRANSFORMERS`, `DRAWING_PRESET_NODES`, `DRAWING_PRESET_TRANSFORMERS` | The production node and transformer lists (`./markdown` / default entry) |
+| `resolveTransformers`, `shortcutTransformers`, `TransformersInput` | How the `transformers` prop is merged, and which of the result double as typing shortcuts |
+| `editorNodeClassNames`, `mergeNodeClassNames` | The built-in node class names and the merge the `nodeClassNames` prop uses |
+| `$replaceMarkdown(markdown, transformers)`, `replaceMarkdown` | Replace the whole document from markdown (what the controlled `value` uses); keeps the caret position when it still exists |
+| `EXTERNAL_UPDATE_TAG` | Update tag on every external (host-driven) import, so a plugin's update listener can tell host imports from user edits |
+| `TABLE`, `LISTS`, `CODE_BLOCK` | GFM table transformer; nested lists (2-space nesting on export, 2 or 4 on import); fenced code (replaces Lexical's `CODE`; untagged blocks export as bare fences) |
+| `FRONTMATTER`, `FrontmatterNode`, `$createFrontmatterNode`, `$isFrontmatterNode`, `SerializedFrontmatterNode` | Frontmatter node + transformer |
+| `$getTableSettings`, `$setTableSettings`, `$isTableWidthExplicit`, `$getTableWidth`, `$setTableWidth`, `$getTableDensity`, `$setTableDensity`, `$getSelectedTable` | Table setting helpers (inside `editor.update`/`read`) |
+| `$getSelectedTableCell`, `$getTableCellPosition` | Where the selection is inside a table |
+| `$insertTableRowAt`, `$deleteTableRowAt`, `$insertTableRowNear`, `$deleteTableRowNear`, `$insertTableColumnAt`, `$deleteTableColumnAt`, `$insertTableColumnNear`, `$deleteTableColumnNear` | Row / column operations (`*At` by index, `*Near` relative to the selection; inside `editor.update`) |
+| `codeTokenizer`, `registerCodeBlockHighlighting` | Lexical tokenizer adapter and editor wiring |
+| `DRAWING`, `DIAGRAM`, `DrawingNode`, `$createDrawingNode`, `$isDrawingNode`, `SerializedDrawingNode` | Drawing node + markdown transformers (` ```drawing ` and ` ```diagram `) |
+| `MentionNode`, `$createMentionNode`, `$isMentionNode`, `MENTION`, `ImageNode`, `$createImageNode`, `$isImageNode`, `$getSelectedImage`, `IMAGE`, `COMMENT`, `$getMarkNodes`, `$getCommentIds`, `$removeComment`, `$plainTextOffset` | The first-party plugins' nodes, transformers and `$`-helpers (also on the plugin entries) |
 
 ## Form integration
 
+The editor is a controlled input with the attributes a form field needs.
+`id` and the `aria-*` props land on the editable surface (the
+contenteditable, or the textarea in `edit-raw`); `name` renders a hidden
+input carrying the markdown so a native form post includes it. The
+surface shows a focus ring on keyboard focus (`--ring`, falling back to
+`--primary`) and an inset outline in `--destructive` while
+`aria-invalid`.
+
 ```tsx
 <FormField control={form.control} name="body">
-  {({ field }) => (
-    <MarkdownEditor value={field.value} onChange={field.onChange} />
+  {({ field, fieldState }) => (
+    <FormItem>
+      <FormLabel htmlFor="body">Body</FormLabel>
+      <MarkdownEditor
+        id="body"
+        name={field.name}
+        value={field.value}
+        onValueChange={field.onChange}
+        aria-describedby="body-hint"
+        aria-invalid={fieldState.invalid}
+        aria-required
+        maxLength={2000}
+        showCharacterCount
+      />
+      <FormDescription id="body-hint">Markdown, 2000 characters max.</FormDescription>
+      <FormMessage />
+    </FormItem>
   )}
 </FormField>
 ```
 
+`maxLength` counts the document's plain text (not the markdown, except in
+`edit-raw` where the textarea's own `maxLength` applies); an edit that
+would pass it is rejected at the caret. `onCharacterCountChange` reports the
+length, `showCharacterCount` renders it (`MarkdownEditor.CharacterCount` places it
+elsewhere), and `labels.count` formats it. The visible count is not a
+live region; a hidden status announces `labels.limitExceeded(max)` /
+`labels.limitRestored(max)` only when the document crosses the limit.
+
 Load both CSS entry points (`@zuilib/tokens/styles.css`,
 `@zuilib/text-editor/styles.css`) in the app layout. Dark mode follows the
 ZUI convention: a `dark` class on `<html>`.
@@ -506,20 +909,35 @@ v4 host must scan this package for them to be generated:
 
 ## Architecture notes (for extenders)
 
-- Source: `src/EditorRoot.tsx` (composer + plugins), `src/EditorContent.tsx`,
-  `src/MarkdownEditor.tsx` (default composition), `src/useMarkdownEditor.ts`,
-  `src/components/Toolbar.tsx`; plugins in `src/plugins/`; drawing
+- Source: `src/editor-root.tsx` (composer + plugins), `src/editor-content.tsx`,
+  `src/markdown-editor.tsx` (default composition), `src/use-markdown-editor.ts`,
+  `src/components/toolbar.tsx`; plugins in `src/plugins/`; drawing
   canvas in `src/drawing/`; custom nodes in `src/nodes/`;
   transformers in `src/transformers/`
 - Markdown import/export via `@lexical/markdown` transformers; order
   matters: `FRONTMATTER`, `DRAWING` and `DIAGRAM` claim their blocks before
   `CODE`, `CHECK_LIST` before `UNORDERED_LIST`
-- `src/drawing/` keeps the format (`types.ts`, `schema.ts`), shape
+- `src/drawing/` keeps the format (`drawing-data.ts`, `schema.ts`), shape
   definitions (`shapes/`), pure geometry (`geometry.ts`), the Mermaid
   exporter (`mermaid.ts`) and the React canvas (`canvas/`) apart, so the
   router, bindings and skeleton expansion run without a DOM
-- Tests: `pnpm test` runs a headless-Lexical markdown round-trip suite
-  (`tests/roundtrip.mjs`)
+- Entry points: `src/index.ts` (default, `DRAWING_PRESET`), `src/markdown.ts`
+  (`MARKDOWN_PRESET`), `src/lexical.ts` (the Lexical escape hatch),
+  `src/drawing.ts`; `src/editor-api.ts` lists the host-facing exports the
+  first two have in common. tsup builds them with code splitting so the
+  entries share one copy of every module
+- `package.json` `sideEffects` lists the stylesheet and
+  `src/code/suppress-global-highlighter.ts` (the first import of every
+  entry: it flags Prism as manual before `@lexical/code` loads it, so a
+  host page's own highlighted blocks are never rewritten); nothing else
+  runs code at import time (the code-language registry loads its built-in
+  grammars on first lookup)
+- Tests: `pnpm test` runs every `tests/*.test.mjs` under `node --test`
+  (a11y, block width, code highlighting, drawing, extension API, ink, lists,
+  mermaid, round trip, skeleton, table grid, table transformer, value sync).
+  Mounted tests use jsdom (`tests/fixtures/dom.mjs`) and end with an
+  axe-core check. They import from `dist/`, so a `pretest` script runs the
+  build before them
 
 ## Related packages
 
@@ -531,6 +949,6 @@ v4 host must scan this package for them to be generated:
 
 ```bash
 pnpm --filter @zuilib/text-editor build   # tsup → dist/
-pnpm --filter @zuilib/text-editor test    # round-trip suite
+pnpm --filter @zuilib/text-editor test    # builds first (pretest), then the node --test suites
 pnpm --filter @zuilib/text-editor publish --access public
 ```